agent-config

Install agent tool bundles into a repo. agent-config packages reusable Claude Code agents, slash commands, hooks, and the scripts they drive — and drops them into any target repo with one command.

The first bundle, test-quality, is a testing toolbox: an audit script, a testing doctrine, four subagents, and the /test, /cover, /rewrite-test, /mutate, /audit-tests, /ship commands. The doctrine is stack-agnostic — repo-specific details come from a per-repo profile.

Layout

agent-config/
  bin/agent-config.mjs     the CLI entry
  src/install.mjs          install logic (resolves bundles off disk)
  bundles/
    test-quality/          the testing bundle (assets + manifest + schema + profiles)
  core/                    placeholder for a future multi-backend runtime (see note)

It's a single package — no workspace, no inter-package dependency.

Quick start

# Install the test-quality bundle into another repo:
npx agent-config add test-quality /path/to/repo

# Preview without writing anything:
npx agent-config add test-quality /path/to/repo --dry-run

# Also drop an editable profile template:
npx agent-config add test-quality /path/to/repo --with-config

# From a clone of this repo:
node bin/agent-config.mjs add test-quality /path/to/repo

# See what's installed and whether anything has drifted:
npx agent-config status /path/to/repo

add copies the bundle's Claude config into .claude/, the doctrine into docs/testing/, and the audit script into scripts/, then merges the required hooks into .claude/settings.json (idempotent — re-running is a no-op).

Configuring for a repo

Each consuming repo commits one profile, agent.config.json, describing how the universal doctrine binds to its stack (the datastore module, the test commands, the directory layout, the tenant key, the mutation tool, etc.). The profile is validated by bundles/test-quality/schema/profile.schema.json, and bundles/test-quality/profiles/trpc-prisma.json is a ready-made preset.

{
  "unitUnderTest": { "term": "handler", "sourceGlob": "src/server/**/*.ts" },
  "dataLayer": { "dbModule": "@/db" },
  "testRunner": { "name": "vitest", "projects": [{ "name": "server", "match": "__tests__/server/", "kind": "server" }] }
}

The audit script (scripts/audit-tests.mjs) reads agent.config.{mjs,json} from the target repo root, falling back to a built-in default preset.

Versioning & drift

Each bundle manifest carries a version. On every add/sync, the installer writes a lockfile, .agent-config/lock.json, into the target repo recording the bundle version and a content hash of every file it manages. Commit it — like package-lock.json, it's shared provenance for the team.

agent-config status reads that lockfile and reports, per bundle:

• whether the installed version is current (update available: 1.0.0 → 1.1.0),
• which managed files were modified locally (would conflict on update),
• which generated files (e.g. STACK.md) were hand-edited,
• which tracked files are missing.

.claude/settings.json is deep-merged rather than owned, so it is intentionally not tracked for drift. Hashes are taken against the canonical bundle content, so a pre-existing file that add skipped will correctly show as drifted. See docs/specs/01-versioning-lockfile.md for the full design.

CLAUDE.md variants & discovery

CLAUDE.md is a first-class, versioned asset. The package ships a catalog of named variants under variants/ (e.g. node-service, minimal), each a clean doctrine body that layers in per-repo bindings via @import.

# List catalog variants:
npx agent-config claude-md list

# Install one (writes a provenance marker + lockfile entry):
npx agent-config claude-md add node-service /path/to/repo
npx agent-config claude-md add node-service /path/to/repo --at=packages/api/CLAUDE.md

# Find & classify every CLAUDE.md in a repo:
npx agent-config discover /path/to/repo

discover walks the tree and reports, per file: provenance (locked › marked › foreign), state (clean/modified, hashed against the lockfile or in-file marker), currency (up to date/outdated (X → Y)), and its @import references (resolved → ok/missing). A foreign file is fingerprinted against the catalog, so a hand-copied CLAUDE.md is recognized as matches [email protected] (unmarked). Installed files carry an HTML-comment marker Claude Code ignores; the lockfile is authoritative when present. See docs/specs/02-claude-md-variants-discover.md.

Updating

The catalog is authoritative — agent-config owns the managed CLAUDE.md, so update overwrites it with the current canonical version (or switches variant). Real customization belongs in the @import-ed files (CLAUDE.local.md, the generated STACK.md), which update never touches — so there's no merge to do.

npx agent-config update /path/to/repo                       # all installs
npx agent-config update /path/to/repo --path=CLAUDE.md      # one file
npx agent-config update /path/to/repo --to=minimal          # switch variant
npx agent-config update /path/to/repo --force               # also reset local drift

An outdated file is overwritten to canonical. A file you've hand-edited ("drifted") is left alone until you pass --force — and any overwrite of a drifted file first saves the old contents to <file>.bak, so a hand-edit is never lost without a copy. No git, no 3-way merge. Full design in docs/specs/03-update-merge.md.

Output across status/discover/update is colorized via Node's built-in util.styleText (no dependency), and falls back to plain text when piped or under NO_COLOR.

Status / scope

This is a config distributor, deliberately. Almost everything a bundle does lives in Claude Code markdown; the portable code is the installer + the audit script. See core/README.md for the multi-backend runtime direction that's reserved but not built.