agent-equip

A quickstart CLI that seeds AI-development tooling into your projects — per stack.

agent-equip drops a consistent set of AI-assisted development tooling into a target project — cross-agent instructions (AGENTS.md), agent-agnostic on-demand skills, per-agent adapters for the agents you pick, a commit shell helper, a pre-commit hook, and Conductor workspace scaffolding — tailored to the project's stack. It merges safely into files that already exist and can recommend & install curated packages for the stack.

About

Setting up the same AI tooling by hand in every repo is tedious and drifts over time. agent-equip makes it one command: pick your stack, and it installs a consistent AI-assistant setup into your project (plus a small commit helper into your shell). Re-run it any time to stay current — it never clobbers your own edits.

Built with Bun + TypeScript.

Supported stacks

• Bun CLI — Bun + TypeScript command-line tools (--stack bun-cli)
• .NET — C# / .NET — dotnet test, CSharpier, Roslynator, analyzers (--stack dotnet)
• Laravel — PHP / Laravel — Pest, Pint, Boost (--stack laravel)
• React — React + TypeScript — Vitest, Testing Library (--stack react)

More stacks (e.g. Node/generic, Python) are on the roadmap.

Features

• Cross-agent instructions + agnostic skills — AGENTS.md (read by most coding agents) is the canonical, agent-neutral layer, and it now carries an on-demand Skills index any AGENTS.md-reading agent (e.g. Codex) can use. Skill bodies are authored once, agent-agnostic; init --agents lets you pick which agents also get a native adapter (Claude Code today → .claude/skills + slash commands). Other Claude-only pieces (the CLAUDE.md adapter, permissions, commit-message generation) remain Claude-specific; broader per-agent adapters are on the roadmap.
• Test-driven development, built in — a red → green → refactor loop shipped as skills every agent can read: test-driven-development (new behavior — one ~2–6 test slice per cycle, gates that demand real command output), tdd-feedback (routes review comments and bug reports into the right phase — a failing reproducer before any bug fix), and codifying-existing-behavior (pins current behavior before you change it). Claude Code additionally gets three isolated subagents, one per phase, so a test can't be retrofitted to the code that was already written. See Test-driven development.
• One-command project setup — run /agent-equip in your agent and it onboards the repo (writes a project-context doc into AGENTS.md: structure, key features, and the conventions that differ from your stack's norms) and tailors the pre-commit + Conductor files to the project.
• Stack-aware — tailors those instructions, rules, and recommendations to your project's stack (see Supported stacks).
• Smart commit command — runs your pre-commit checks, then writes the commit message for you from the staged diff (via Claude) and prefixes a branch ticket id.
• Package recommendations — spots stack-relevant tools you're missing (e.g. Laravel Boost) and installs the ones you pick.
• Conductor-ready — sets up Conductor so parallel agent workspaces work out of the box.
• Non-destructive & updatable — merges into your existing files instead of overwriting them; re-run any time to pull the latest tooling.

Requirements

• Node.js v20+ — bun is not required to run agent-equip; the published CLI is a plain Node bundle
• A target project that is a git repository
• Optional:
  • the claude CLI — for commit-message generation and smart merges of structured config
  • stack tooling for package installs (e.g. Composer for the Laravel packages)

Usage

Run it straight from npm — no clone, no bun. The CLI ships as a Node bundle, so any npx (or bunx) works:

npx agent-equip init /path/to/project --stack laravel
# bunx works the same:
bunx agent-equip init /path/to/project --stack laravel

Or run it from inside the target repo — the path defaults to .:

cd /path/to/project
npx agent-equip init --stack bun-cli

Pull template improvements into a project you've already set up — update reads the stack and agents recorded at install time, so it needs no flags:

cd /path/to/project
npx agent-equip update

It refreshes every pristine managed file to the current templates, reports a vX → vY line plus the per-file outcomes, and lists any files it left alone because you'd edited them ("kept your local edits"). Add --dry-run to preview.

List available stacks:

npx agent-equip list

Pin a version with [email protected]; omit it to always fetch the latest.

From source (development)

Building from source uses bun (the repo's toolchain), but the produced CLI still runs on Node:

git clone https://github.com/michaelhrivnak/agent-equip.git && cd agent-equip
bun install
bun run bin/agent-equip.ts init /path/to/project --stack laravel

init options

| Flag | Description | | --- | --- | | -s, --stack <name> | Stack template to install (skips the picker) | | --dry-run | Show what would change; write nothing | | -y, --yes | Don't prompt (requires --stack) | | --project-only | Seed project files only; skip the user-level commit helper | | --no-packages | Skip the curated package picker | | --no-agent-tools | Skip the agent-tools picker (plugins / MCP / hooks) | | --force | Allow installing into the agent-equip repo itself (dogfooding) |

update options

| Flag | Description | | --- | --- | | --dry-run | Show what would change; write nothing | | --project-only | Refresh project files only; skip the user-level commit helper | | -s, --stack <name> | Override the stack (only needed for a pre-versioned install with no recorded stack) |

What gets installed

Into the target project:

• AGENTS.md — shared, cross-agent instructions assembled from the stack's rules (a managed agent-equip block; your own content is preserved).
• CLAUDE.md — a thin adapter that imports AGENTS.md for Claude Code.
• .claude/ — Claude Code adapter: settings, slash commands, the TDD phase subagents (agents/tdd-*.md) and the feedback-router hook (hooks/) — all always shipped — plus native copies of the on-demand skills (only when Claude is a selected agent).
• .agent-equip/skills/ — agent-agnostic skill bodies, referenced by the AGENTS.md Skills index so any agent (e.g. Codex) can load them on demand.
• .gitignore — a managed agent-equip block for the files above.
• .conductor/ — settings.toml plus a setup.sh stub for Conductor workspace setup.
• .agent-equip/precommit — a lint/format hook the commit helper runs (kept out of the repo root to avoid clutter).
• .agent-equip/ prompts (setup.md, onboard.md) and matching /agent-equip + /onboard commands, plus the tune-precommit / tune-conductor skills — the guided setup (see "Finish setup" below).
• The TDD skills (test-driven-development, tdd-feedback, codifying-existing-behavior) and your stack's testing conventions (laravel-testing, react-testing) — see Test-driven development.
• CLAUDE.local.md.example — copy to CLAUDE.local.md for personal, gitignored overrides.
• Laravel only: tests/Unit/TestCommentStandardTest.php, a guard that enforces the strict Arrange–Act–Assert comment standard. This is the one file seeded into your application test suite — read the caveat in Test-driven development before your next test run.

Into your home directory (once, machine-level):

• ~/.config/agent-equip/commit.sh and a source line added to ~/.zshrc and/or ~/.bashrc (autodetected from your shell).

Ownership: what stays current vs. what you take over

agent-equip ships a library it keeps current and a scaffold it hands over:

| File | Owner | On re-run | | --- | --- | --- | | AGENTS.md rules block, CLAUDE.md, skills, /commands, .claude/agents, .claude/hooks, .agent-equip/*.md prompts | product | refreshed while pristine; your edit forks it and updates stop | | .agent-equip/precommit, .conductor/* | team | seeded as smart defaults, then yours the moment you edit them | | .claude/settings.json (permissions, hooks, tool picks) | mixed | deep-merged every run; your values always win | | .gitignore | shared | managed agent-equip block only; the rest is yours |

The contract: a file you haven't touched stays current on re-run; a file you've edited is yours — agent-equip never modifies it again (and won't nag with *.agent-equip-new for it). Two ways to customize:

• Extend prose alongside it — add project context above the AGENTS.md block, use CLAUDE.local.md, or add your own skills/commands. This keeps the product prose updatable.
• Edit the scaffold directly — .agent-equip/precommit, the Conductor files, permissions. That's what it's for; editing is how you take ownership.

agent-equip tracks the sha of each whole file it wrote in .agent-equip/manifest.json (committed) to tell pristine files from forked ones. Marked-block files (AGENTS.md, CLAUDE.md, .gitignore) instead refresh just their block, always preserving your surrounding content. A pre-existing file agent-equip didn't create is never overwritten — you get a *.agent-equip-new copy to reconcile once.

The commit helper

Once installed, commit (from any repo):

1. runs .agent-equip/precommit (lint/format) and aborts if it fails,
2. stages everything,
3. uses the claude CLI to write a one-line message from the staged diff — with retry / type- your-own / abort if generation fails — and prefixes a branch ticket id (e.g. ABC-123) when present.

Test-driven development

agent-equip seeds a full TDD workflow, not just an instruction to "write tests". The loop is red → green → refactor, run one behavior slice at a time — a cohesive set of ~2–6 tests covering one feature surface, not a single assertion and not the whole feature. Every test is Arrange–Act–Assert with exactly one Act, asserting what a caller observes through a public interface so it survives refactoring. The gates are the point: you don't advance a phase until its exit condition is shown as real command output, never a claim.

Three skills cover the lifecycle, and because their bodies live in .agent-equip/skills/ and are listed in the AGENTS.md skills index, any agent that reads AGENTS.md (Codex included) can load them on demand:

| Skill | Fires on | | --- | --- | | test-driven-development | new behavior — a new function, endpoint, component, command | | tdd-feedback | feedback on shipped work; classifies each item BUG / SLICE / REFACTOR-HAT / DIRECT, so a bug gets a failing reproducer before any fix | | codifying-existing-behavior | changing existing behavior — pins what it does today first |

Your stack also gets its testing conventions as a skill, so tests match the project instead of a generic template: laravel-testing (Pest, factories, RefreshDatabase, Inertia prop assertions, byte-exact external-HTTP fixtures) and react-testing (Vitest + Testing Library, query by role, userEvent).

Claude Code additionally gets phase isolation. Honest TDD is hard in one context window — the analysis that wrote the test bleeds into the implementation. So each phase runs in its own subagent, seeded only with what it needs and returning the real run output: .claude/agents/tdd-test-writer.md (🔴), tdd-implementer.md (🟢), tdd-refactorer.md (🔵). Other harnesses fall back to holding the same discipline in a single context — test to red before any production code. The subagents read your stack testing skill for the project's real commands.

A feedback-router hook (.claude/hooks/feedback-router-reminder.sh, registered as UserPromptSubmit in .claude/settings.json) nudges the agent to route feedback through tdd-feedback instead of jumping straight to editing. It is reminder-only: it never blocks, always exits 0, and prints nothing unless a prompt looks like feedback.

Two things worth knowing before you run it:

• The hook is deliberately broad. Its matcher is "", so the script runs on every prompt (it needs jq — without it the hook silently no-ops). The match regex includes bare \bchange\b, \brename\b, \bremove\b and \bbug\b, so an unrelated "change the port in the config" will trip it and inject a note telling the agent to consult tdd-feedback first. To turn it off, set "hooks": { "UserPromptSubmit": [] } in .claude/settings.json — don't just delete the key. The deep-merge re-adds keys your file is missing on the next run, but it never overwrites an array you've already set.
• The Laravel guard test runs against your suite. --stack laravel seeds tests/Unit/TestCommentStandardTest.php — the only file agent-equip writes into application code rather than an agent-config directory. It scans tests/**/*.php and resources/js/**/*.test.ts(x) and fails on any AAA label that breaks the strict form, so on a mature repo that never used the standard your suite can go red on the first run after install. Conform the labels or delete the file.

Curated packages

After seeding files, agent-equip checks the target for stack-relevant packages it doesn't yet have (declared in templates/<stack>/packages.json) and offers a checklist. It shows the exact install commands and only runs the ones you confirm.

Recommended agent tools

agent-equip also offers an interactive picker of agent tooling — Claude plugins, MCP servers, and hooks (declared in templates/<stack>/agent-tools.json) — applying the ones you select to .claude/settings.json and/or .mcp.json. Nothing third-party is written without your choice: under --yes or when the output isn't a terminal it only reports what's available. Skip it with --no-agent-tools.

The committed .claude/settings.json also registers the feedback-router UserPromptSubmit hook (see Test-driven development) and ships a permissions baseline — read-only commands auto-allowed; destructive ones (rm -rf, git reset/stash, force-push, branch deletion, sudo) denied; git commit/push always prompt. Loosen or tighten it per-developer in .claude/settings.local.json. Treat it as a guardrail against accidental damage or secret exposure, not a security boundary: prefix-based denies are bypassable, so real secrets belong outside any reachable .env file.

Finish setup in your agent

After init seeds the files, open the project in your agent and run /agent-equip (Claude Code) — or follow .agent-equip/setup.md in any agent. It does the whole setup in one pass, with minimal questions:

1. Onboard — explores the repo and writes your project context into AGENTS.md, above the managed block: structure, the most important features, and the conventions that differ from your stack's defaults (the highest-signal part for future agents).
2. Tailor the pre-commit — sets .agent-equip/precommit to the project's real format/lint/type-check/test commands (subsetting or skipping a slow suite).
3. Tailor Conductor — fills .conductor/setup.sh + settings.toml (deps, database, local services, run scripts, ports, parallel-safety).

The pieces are also available individually — /onboard (context only) and the tune-precommit / tune-conductor skills — and everything is re-runnable to refresh as the project evolves.

AGENTS.md ends up with two parts: your project context (above the managed block, yours to own) and the generic guardrail-rules agent-equip block (refreshed on re-install).

Roadmap

See ROADMAP.md — and the GitHub milestones — for what's planned.

Contributing

Contributions are welcome — new stacks especially. The merge/marker/manifest behavior is specified implementation-independently in SPEC.md — read it before changing how files are composed or merged (and any future reimplementation must satisfy it).

Development

bun install
bun test          # tests live under test/<area>/ (per stack, plus core)
bun run lint      # Biome (tabs, double quotes) — strict, warnings fail
bun run fix       # Biome format + safe lint fixes
bun run typecheck # tsc --noEmit
bun run build     # bundle the Node CLI → dist/agent-equip.js (what npm publishes)
bun run stacks    # refresh the README "Supported stacks" list from stack.json

The repo's toolchain is bun, but the published artifact is a plain Node bundle (bun build --target=node) — shipped code must not use Bun runtime APIs. CI enforces this with a node-smoke job that installs the packed tarball and runs the CLI on Node with bun absent from PATH. The implementation-independent behavior contract lives in SPEC.md.

CI runs lint + typecheck + tests on pushes to main and on every PR. The repo dogfoods its own installer via the bun-cli stack, so ./.agent-equip/precommit runs the same checks locally.

Adding a stack

1. Create templates/<name>/ with the files that differ from common (identical relative paths override the common layer). Rules in templates/<name>/rules/*.md are assembled into the project's AGENTS.md; skills in templates/<name>/skills/<skill>/skill.md are emitted as agnostic bodies plus per-agent copies (a stack skill overrides a common one of the same name); structured configs (*.json, MSBuild *.csproj/*.props/*.targets, *.toml) are merged; other files are copied.
2. Optionally add templates/<name>/stack.json (label, description) for the picker, and templates/<name>/packages.json to curate installable packages.
3. Add tests under test/<name>/.
4. Run bun run stacks to refresh the README "Supported stacks" list (drift-tested — CI fails if you skip it).

It then appears in agent-equip list and --stack <name> automatically.

License

Released under the MIT License.