ADD — AI-Driven Development

Your AI's first milestone is always great. ADD is for every milestone after that.

One skill file for work the AI plans, builds and verifies — while you own the two things it cannot do alone: decide what to make, and judge whether it is right. No engine, no CLI: the tools are files, git, and your project's own test command.

The agent is the hands. ADD is the memory, judgment, and conscience — the part of the team that survives when the context window doesn't. Memory: .add/PROJECT.md, one task file per change, five living specs — plain markdown in your repo. Judgment: every change is sized, and every guess the agent makes is written down. Conscience: checks sealed in git before the build, a verdict backed by real test output, and security findings that always stop.

The full reasoning — why every rule exists — is the ADD book.

  Foundation (context):  DDD  ·  SDD  ·  UDD
  The loop (this skill): TDD  ⇄  ADD
  Per task:  Direction (rules · assumptions · red checks → freeze commit)
             → Build (red → green)  → Verify (seal intact · fresh run · residue · verdict)  ↻

Quick Start

npx @pilotspace/add init                                # Node / npm

pip install pilotspace-add && pilotspace-add init       # Python / pip

Then, in your coding agent, say what you want to build:

/add — "Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."

The agent sizes the request, writes the task's rules, assumptions and failing checks, seals them with a freeze(<slug>) commit, builds to green, verifies on a fresh run, and hands you a report of what it decided and on what evidence. Full walkthrough: the Quickstart.

ADD in plain words

We gave Claude Code the same 300 real bugs from popular open-source projects twice: once on its own, and once with ADD installed. Same AI, same bugs, same settings.

In short: ADD fixes at least as many bugs, checks and tests almost every fix, and tells you what it assumed. It costs more, and the gain in bugs fixed is small enough that it is not yet proven. Run it with --effort medium. See the results animated, in plain words →

Highlights

• 📜 Every change leaves its reasoning in your repo — the rules, the guesses and the checks live in one task file next to the code, so the next session or teammate reads the intent instead of guessing it.
• 🛡️ Safer guesses where your spec is silent — ADD takes the least-privilege reading when nobody said who may act, and seals a check for it.
• 🔒 Trust rests on evidence, not a plausible diff — checks are sealed in a freeze commit before the build, and every task ends in a verdict you can re-run. Security findings always lead the report.
• ⚖️ An honest price — Measured on ADD 4.1.0 with Claude Sonnet 5.5 (n = 300 real bugs, both at --effort medium): ADD resolved 226 to vanilla Claude Code's 215, at 1.8× the dollars and 2.5× the seconds per bug. On small apps it costs 1.3–1.9× the dollars and 1.8–2.4× the minutes; correctness ties, and its tests catch more seeded bugs (0.81 vs 0.43) (results).
• 💸 Ceremony only where it buys trust — most changes take the Quick lane: one red→green test, one commit, no task file.

What ADD gives your project

Vanilla Claude Code already writes good code: on Sonnet 5.5 it passed every held-out edge case in our benchmark. What it does not leave behind is the why. ADD 4.0 is one skill file, with no engine and no CLI, that makes every change leave the reasoning in your repository, next to the code:

Vanilla Claude vs Claude + ADD — the same request, two flows

Two real round-6 runs on Sonnet 5.5, given the same spec: a booking service whose requirements contradict each other (a conflict gets 202 waitlisted and 409 rejected) and say nothing on six other decisions. ▶ Watch both play on one clock.

Same code quality, same headline decision. The difference is where that decision lives, and the guesses nobody asked about.

Measured on 4.0 — what you get, what you pay

The same Claude Code with and without the ADD skill, on claude-sonnet-5-5 (Sonnet 5.5): two small apps at n = 3 per arm, and all 300 SWE-bench Lite issues once per arm (results · both flows, animated · the earlier rounds, animated).

Effort matters. At --effort low ADD read its skill in only half its runs and resolved 201 of 300 to vanilla's 215. At medium it read the skill in 292 of 300 and resolved 226. In a blind six-issue review, one reviewer preferred vanilla's shorter output in 6 of 6, while 2 of the 5 vanilla patches they approved as is fail the benchmark's tests; timed review is not measured (fresh 300 at medium).

Small changes. A change with no new behavior (a typo, a rename, a comment, a config value) is made without a new test; every bug fix keeps its test, as measured. A looser rule (a test only when the AI judged it important) was tried and dropped: on 101 of the issues it resolved 78 against 83 for the measured skill, for a 6% saving.

Earlier rounds, older models and the full method are in the results history.

_{Fine print: both arms ran with the operator's own ~/.claude kept out of the session; earlier rounds loaded it, and its security-guidance plugin slowed every ADD commit. Run ADD at --effort medium: at --effort low it skipped its own skill in half the SWE runs and resolved 25 fewer issues. The small apps are n = 3: direction, not proof.}

When vanilla Claude is the right call

• Throwaway work (a script, a spike, a one-shot), or a fix you will not review: use vanilla. It runs about 2.5× faster at about half the price, and on SWE-bench Lite it resolved 215 of 300 to ADD's 226.
• A product you will still be changing next month (several milestones, teammates, or anything where who may do this? matters): use ADD. The decisions outlive the chat, the guesses get reviewed, and the checks cannot quietly weaken.
• In between, ADD sizes each request itself. Most changes take the Quick lane, which is one red→green test and one commit, with no task file.

ADD works with the agent you already use (Claude Code, Codex, Cursor, Copilot, Gemini) and installs via npm, pip, or the Claude Code plugin.

Direction before speed. Trust comes from evidence you can re-run, not from reading code and finding it plausible.

How much ceremony? — the lanes

Most changes never create a node. The agent sizes each request and routes it to the lightest safe lane. The floor is checked first: anything touching security · data · architecture, or a surface other code consumes, is at least a Task.

Skipped ceremony is never skipped review: a Quick change still writes its test and runs it red.

Install

Pick your ecosystem — all three install the same skill:

npx @pilotspace/add init                   # Node / npm

pip install pilotspace-add && pilotspace-add init      # Python / pip

# Claude Code plugin — no npm or pip needed
/plugin marketplace add pilotspace/ADD
/plugin install add@add-method

This installs:

The installer drops files only. The bundle itself — .add/PROJECT.md and the specs — is the agent's first move when you run /add.

Already installed? npx @pilotspace/add@latest update (or pipx run pilotspace-add update) refreshes the skill and leaves your project work untouched. Coming from 3.x? Your bundle reads as-is; the update removes the old engine files. See what changed in 4.0.

New here? Pick the walkthrough that matches what you are making:

• 🔍 Quickstart — your first feature, end to end
• 📒 Beyond code — a month-end close: same loop, where the artifact under check is a ledger rather than a repo

Boundaries — what this package writes and runs

• Runs only when you ask. Nothing executes on install beyond copying files.
• What it writes: the skill under .claude/skills/add/, persona files under .add/, and the managed ADD block in your agent's context file. Never above the project root.
• Network: none. npm/pipx fetch the package; after that ADD is entirely offline.
• No secrets, no credentials, no privileged access.

Use it

You talk to the agent; it drives the method. In Claude Code, /add starts or resumes work and /add status summarizes where things stand. Other agents read the managed ADD block the installer writes into AGENTS.md (and CLAUDE.md), which points them at the same skill file; if .gemini/ exists, the installer also adds AGENTS.md to Gemini CLI's context files.

You can always read the state yourself: it is .add/PROJECT.md, the task files, and git log.

The non-negotiables

1. Direction before build — no production code before rules, assumptions and checks exist and the checks have failed for the right reason.
2. Evidence, not inspection — a change is trusted because its checks pass fresh on the committed tree and its residue was read. A green proves the checks you wrote ran — never that they were enough.
3. Never weaken a sealed check or edit the contract to pass — changed intent is a visible refreeze with a reason.
4. No silent outcomes — every task ends PASS, RISK-ACCEPTED or HARD-STOP; every guess is an assumption the human can read. Security findings are always HARD-STOP.
5. invariants: bind every change, Quick included.

Read the method

• 📖 Read the book — the full method, chapter by chapter
• 🔍 Quickstart — one real feature, end to end
• 📒 Beyond code — one real month-end close, end to end
• 📊 Benchmark results — every trust and cost claim, measured
• ⚖️ ADD vs spec-kit — the honest comparison

Develop

python3 -m pytest -q      # from add-method/

License: MIT.