The Agent Engineering Kit

Make your AI coding agents ship clean, maintainable code.

Left alone, coding agents guess APIs, sprawl across files and call untested work “done”. This kit gives them the habits of a careful senior engineer: plan first, make small surgical changes, verify with evidence, simplify, and review. A safe installer puts it into your project in each tool’s own format.

npx agent-engineering-kit

Needs Node.js 18 or newer. It opens a guided installer in your browser, and nothing is written until you’ve reviewed every change as a diff. Or let your coding agent install it.

AI coding tools, each in its own format
18
tokens of always-on rules per session
600
runtime dependencies in the installer
0

An agent’s first draft, in review

The review marks four problems in the draft: a vague function name, a swallowed error, a TODO left in, and a weakened test. The reviewed version renames the function, throws on a failed response, removes the TODO, restores the exact assertion and adds a 404 test, and its checks pass.

Before reviewagent draft
src/invoices.ts
export async function doStuff(d) {

Name it for what it does.

try {
const res = await fetch(`/invoices/${d}`);
return res.json();
} catch (e) {}

Swallowed error.

// TODO: implement retries

Not done. Don’t call it done.

}
test/invoices.test.ts
Removed: expect(total).toBe(1250);
Added: expect(total).toBeTruthy();

Weakened test. Restore it.

After reviewready to merge
src/invoices.ts
export async function fetchInvoice(id) {
const res = await fetch(`/invoices/${id}`);
if (!res.ok) throw new HttpError(res.status);
return res.json();
}
test/invoices.test.ts
expect(total).toBe(1250);
test("throws on a 404", async () => { … });
  • Renamed to what it does: fetchInvoice(id)
  • Errors are thrown, not swallowed
  • No TODO left behind
  • Real assertion back, plus a 404 test
checks passed: lint, testVerified

§01 · The workflow

Every change goes through the same six steps.

The feature skill walks the agent through the whole lifecycle. Each step leaves evidence you can check, so “done” means the checks passed, not that the agent says so.

  1. Plan

    The agent maps the code, asks you what the code can’t tell it, and writes a plan to .agent-kit/plans/: must-haves, no-gos, and a “Done When” list of checks that pass or fail. Nothing is built until you approve it.

  2. Build test-first

    One small slice at a time: a failing test, the code that makes it pass, then a tidy-up. Every changed line traces to the request.

  3. Verify

    The verifier agent runs your project’s real format, lint, type-check, test and build commands, exercises the change, and reports pass or fail with the actual output.

  4. Simplify

    The code-simplifier goes over only the code changed in this task. Dead code, duplication, needless abstraction and narrating comments go, then the checks run again.

  5. Review

    test-analyzer checks the tests prove the change, silent-failure-hunter looks for swallowed errors, and security-reviewer and frontend-reviewer join when the change touches their area.

  6. Ship

    /ship groups the work into focused commits and writes the pull request description. It pushes or opens a PR only when you ask.

Example change

/feature add CSV export to the reports page

  1. Planplans/001-csv-export.md approved
  2. Buildexports rows as CSV
  3. Verifychecks passed: lint, test
  4. Simplifyfunction toCsvRow2(row) {…}
  5. ReviewReviewed
  6. ShipShipped

An illustration of the workflow, not output from a real project.

§02 · What’s inside

Six parts, each with one job.

Pick them in the installer with the Recommended, Minimal or Everything preset, or one by one. Each part has a plain-English “What is this?” before you choose it.

Engineering rules

A short block in AGENTS.md carries the always-on rules as pass/fail lines, about 600 tokens. The full rulebook is reference that skills and agents open one section at a time.

Sub-agents

8 helpers, each with one job and its own context: an explorer and an architect before coding, a verifier and a simplifier after, and reviewers for tests, silent failures, security and UI.

Skills

feature runs the whole pipeline from a plan file. quick-fix handles small changes, and verify-change, ship, learn and project-conventions cover the rest.

Guardrails

A format-on-edit hook that runs your project’s own formatter, a secret guard that keeps agents out of .env files, and optional pre-commit checks.

Every tool’s format

Written once and rendered per tool. AGENTS.md is the hub, shared folders are written once, and a tool gets its own files only where it can’t read a shared one.

A careful installer

A browser GUI, a terminal wizard and a scriptable CLI on one core. Preview first, backups, an install record, and a clean update and uninstall.

§03 · Works with

18 AI coding tools, plus any agent that reads AGENTS.md.

Tools whose files are already in your project are pre-selected. Each line lists what the installer writes natively for that tool; anything else gets a note with the exact steps. See the full table and the reasons.

  1. Claude Coderules, skills, agents, format on edit, secret guard
  2. OpenAI Codexrules, skills, agents
  3. Cursorrules, skills, agents, format on edit, secret guard
  4. GitHub Copilotrules, skills, agents
  5. Gemini CLIrules, skills, agents, secret guard
  6. Google Antigravityrules, skills, agents
  7. Grok Buildrules, skills
  8. Windsurf / Devin Desktoprules, skills, format on edit, secret guard
  9. Kirorules, skills, agents, secret guard
  10. opencoderules, skills, agents
  11. Kilo Coderules, skills, agents
  12. JetBrains Junierules, skills, agents, secret guard
  13. Augment Coderules, skills, agents, secret guard
  14. Clinerules, skills
  15. Zedrules, skills
  16. Amprules, skills
  17. Warprules, skills
  18. Aidersecret guard
  19. Any other agent (AGENTS.md)rules, skills

§04 · Safe by default

The installer never surprises your repository.

Your project is treated as untrusted input, and your own files stay yours. How the installer works.

No slop
  1. Preview first. Every change is shown as a diff, with the tools that read each file. Nothing is written until you confirm.
  2. Merged, never overwritten. AGENTS.md, CLAUDE.md and ignore files get a marked block; JSON settings get in-place edits that keep your formatting.
  3. Backed up. Every file that will change is copied to .agent-kit/backup/ first, and the backups are kept out of git.
  4. Recorded. .agent-kit/install.json lists every file and setting the kit added, so it can update and remove exactly those.
  5. Reversible. Uninstall removes only what the kit added. A file you’ve edited since keeps your changes.
  6. Repeatable. Running it twice with the same choices changes nothing, not even the install record.
  7. Contained. It writes only inside the folder you chose, never through a symlink, and runs no package-manager or plugin commands.

§05 · Install

Two ways in.

Either way, you see every change before anything is written. All the install options.

Let your agent install it

Paste this into your coding agent in your project. It works out your stack, commands and conventions from the code, shows you what it found and where, asks only what the code can’t tell it, and runs the installer with your approval.

Install the Agent Engineering Kit in this project. Read and follow https://raw.githubusercontent.com/vishalguptax/agent-engineering-kit/main/docs/install-with-an-agent.md. Ask me before anything that changes my files.

Run it yourself

With Node.js 18 or newer, this opens the installer in your browser. There’s nothing to clone or install first.

npx agent-engineering-kit

No browser? Add --terminal. Scripting or CI? --target ./my-app --tools claude-code,codex --preset recommended --yes

§06 · Questions

Questions people ask first.

Does the installer change my files without asking?

No. It shows every change as a diff first, and nothing is written until you confirm. Files that change are backed up to .agent-kit/backup/, and AGENTS.md, CLAUDE.md and settings files are merged, never overwritten.

Which AI coding tools does it work with?

18 named tools, including Claude Code, OpenAI Codex, Cursor, GitHub Copilot and Gemini CLI, plus any other agent that reads AGENTS.md. Each one gets the kit in its own format.

How much context does it use?

The always-on rules in AGENTS.md are about 600 tokens per session. The full rulebook is reference: skills and agents open only the section they need.

Does it need dependencies or make network calls?

npx downloads only the installer and the kit, about 100 kB with no dependencies. Once running, the installer makes no network calls.

How do I update or uninstall it?

Run the installer again. It offers Update, Add or remove components or tools, and Uninstall. Uninstall removes only what the kit added and keeps your own edits.

Does it work on Windows?

The installer and the format hook run on Node, so they work as is, though Windows hasn't been tested by hand yet. The optional pre-commit check is a POSIX sh script, which Git for Windows provides.