ADD — AI-Driven Development

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

A minimal, state-tracked skill for work the AI does and you own the two things it cannot do alone: decide what to make, and verify it is correct. Software is where it started; the loop holds anywhere the result can be checked.

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: the board, frozen contracts, and living specs on disk (cli.py status resumes any session losslessly). Judgment: personas propose each task's lane and the loop learns from traced outcomes (cli.py deltas). Conscience: evidence-scored gates, the tamper tripwire, the security hard-stop.

Native on Claude Code; every other CLI agent follows the same loop through the phase guides. The full reasoning — why every rule exists — is the AIDD book.

  Foundation (context):  DDD  ·  SDD  ·  UDD
  Engine (this skill):   TDD  ⇄  ADD
  Flow per task:  Direction (spec · scenarios · contract · red tests → ONE freeze)
                  → Build (red → green)  → Verify (evidence-scored gate)  ↻

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 it into a milestone (you confirm the shape), drafts the specification bundle — spec → scenarios → contract → red tests as one Direction pass (you approve once, at the frozen contract) — then builds and verifies to green. Full walkthrough: the 10-minute Quickstart.

Highlights

• 📉 Your agent stops re-breaking last month's work — every decision lives on disk (the task files under .add/tasks/, frozen contracts, red suites, .add/graph.json), so a fresh session resumes with the full picture. Measured: quality held flat where a long conversation decayed (six-milestone benchmark, n=1 per arm, ADD 2.0.0, pinned model — report).
• ✅ Stop babysitting the build — you approve once, at the frozen contract; from there the agent drives Direction → Build → Verify and only comes back when it matters.
• 🔬 Know it's correct without reading every line — trust comes from your pre-declared tests passing, never a diff that merely looks right; the contract you approved cannot be edited under a build without the change appearing in the record.
• 💸 Pay ceremony only where it buys something — most changes take the direct lane and never create a node at all; when one does, a thin 26-verb kernel and a 3-call walk carry it. What you get for the ceremony is concrete: a frozen contract the agent cannot edit, a run receipt bound to the checks it names, and a gate that refuses rather than waves through.
• 🔒 Never ship a security hole on autopilot — any security finding is a hard stop with you in the loop, in every mode.
• 🧠 The method adapts to your codebase — a project-owned persona proposes each task's approach, the freeze ratifies it, outcomes are recorded, and lessons land on the spec they belong to.
• 🙋 "Who has to live with this?" is a question it cannot skip — every surface is swept for who receives the output and what would make it hard for them, alongside the five correctness dimensions; freeze refuses until it is answered or explicitly retired.
• 👥 Grows with your team — git-native multi-user, N parallel milestones, DAG-scheduled waves; monorepo or multi-repo in one team.
• 🤝 Keep the agent you already use — Claude, Copilot, Cursor, Codex, Gemini; install via npm, pip, or the Claude Code plugin.

Direction before speed. Trust comes from passing tests — not from reading code and finding it plausible.

How much ceremony? — the ladder

Most changes never create a node. Size the work first; the floor is checked FIRST and always wins (security · data · architecture, a published surface something else consumes, or frozen scope → a node, however small). Under that floor:

Skipped ceremony is never skipped review: a direct change still writes its check and runs it red — it just does not persist a node to prove it did.

Why ADD — context rot, measured

Every AI tool writes code fast and aces a greenfield first milestone. The unsolved part is trust across change: when the spec evolves in milestone 2 and breaks compatibility in milestone 3, does the work you already trusted stay trusted?

Our benchmark runs the same six-milestone evolving project through each flow under a pinned model with deterministic probe scoring (report, revised edition). The causal finding: when ONE continued conversation carried the milestones, every flow decayed the same way (coverage .92 → .75, an early spec violation carried through five more milestones). When every milestone instead started a fresh session resuming from disk, ADD held every floor at 1.0 across all six — through a breaking shape change and a cross-cutting refactor — with zero regressions.

That's the design, in three moves:

• One file per feature. Rules, assumptions, contract, checks, and gate record all live inline in a single task file at .add/tasks/<slug>.md. No sprawling doc tree.
• State on disk, not in chat. Files are the database — a stdlib-Python kernel reads where you are back off the .add/ bundle itself (graph.json is a rebuildable cache, not the source of truth), so a fresh session resumes with one command instead of trusting a long conversation's memory.
• Progressive disclosure. The skill narrates the whole loop itself and loads a deeper phase reference only when the beat needs it — the context window stays lean.

_{Honesty note: on this friendly single-app workload a strong model under spec-kit also passed the restart floors (and ran cheaper) — we published the retraction of our own earlier collapse claim when we found the meter defect behind it. What ADD uniquely adds is the guarantees: contracts that can't be silently edited, tests that can't be quietly weakened, security findings that can't scroll past.}

ADD vs skill libraries (e.g. agency-agents)

ADD is the trust layer — the gated loop (Direction → Build → Verify) that decides when work is trusted, plus the on-disk memory it runs on. It answers how you trust what gets built. Skill libraries and role-specific subagents (a backend expert, a security reviewer) answer who does the work. Different layers — they compose, they don't compete.

ADD's persona loop distills a lean, project-fit persona from a teacher corpus like agency-agents — vendored at personas-teacher/, read off-build while drafting, never a runtime dependency — down to the three parts a project needs: Identity, Critical Rules, Success Metrics. The project then owns that persona.

A distilled persona is an advisory overlay during direction, build, or verify: it shapes how a step gets done, never whether it happens. It can't skip a gate, edit a frozen contract, or wave through a security finding. Personas also propose each task's approach; the freeze ratifies it, the gate records the outcome, and cli.py deltas lists the lessons that came out of it, by lens.

Best setup: install ADD to drive the loop, keep whatever subagent libraries you already use. ADD ships two agents — add-worker (the execution shell) and add-advisor (the second mind it spawns to propose a plan, pressure-test a draft, or decide a delegable ambiguity) — in the same .claude/agents/ mechanism as any other subagent; they coexist with a distilled persona or a built-in expert with zero conflict, nothing is replaced. Prefer add-worker for anything phase-shaped (verify mode for the adversarial refute-read, build mode for a red→green batch) and let it consult add-advisor when confidence is thin; reach for another specialist when a piece needs deep domain expertise the phase guide doesn't carry. The gates hold no matter who did the work — a delegated subagent proposes; the orchestrating agent records.

Install

Pick your ecosystem — all three install the same skill and tooling:

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

The plugin carries the engine. On first /add, the skill materializes it into the project and scaffolds .add/ — a self-contained result identical to the npm/pip flow. No flags needed: the project name is inferred from your folder (pass --name "My App" to set it up front). Ceremony is per-task in 3.x — a task declares its own --depth and --sensitivity, so there is no project-wide stage.

Already installed? npx @pilotspace/add@latest update (or pipx run pilotspace-add update) re-materializes the skill and tooling while leaving your project work untouched; add --check to see whether a project is behind. Coming from 2.x? 3.0 is a clean break: it reads a different bundle format and never converts one. Run add upgrade — it renames .add/ to .add-2x-archive/ byte-for-byte, writes a MIGRATION.md beside it, and initialises a fresh 3.0 bundle. Nothing is deleted and nothing is rewritten; the 2.x record stays readable as the account of how the project was built.

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

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

This installs:

Project state is not created at install — the installer drops files only; initialisation is the agent's first move when you run /add. add init is what writes the bundle: index.md, PROJECT.md, graph.json, log.md, and the living specs/.

Boundaries — what this plugin writes and runs

ADD works inside your project — here is exactly what that means:

• Runs only when you ask. Nothing executes on install. It acts when you run /add. User-initiated, every time.
• What it runs: the bundled engine only — node bin/cli.js and python3 .add/tooling/cli.py. No downloaded or remote code.
• What it writes: files under your project's .add/ and the managed guideline block in CLAUDE.md / AGENTS.md. Never above the project root.
• Network: none. Nothing in the installer or the engine opens a socket — no update check, no telemetry, no analytics. npm/pipx fetch the package; after that ADD is entirely offline.
• No secrets, no credentials, no privileged access. Pure local file orchestration.

Use it

ADD is AI-first: you talk to the agent; it drives the method. The installer detects which coding agent you're in and drops the context file it reads — so ADD drives under Claude Code, Codex, OpenCode, Cursor, Windsurf, Trae, Gemini CLI, GitHub Copilot, Cline, and Aider (anything else falls back to a generic AGENTS.md). Only Claude Code runs /add natively; every other agent follows the same loop through cli.py status (the resume point) and cli.py brief <slug> (the composed prompt for the beat that node is on).

You can hand-drive the CLI too:

python3 .add/tooling/cli.py status      # where am I? (resume point)

The non-negotiables

1. Direction before speed — no Build until spec, scenarios, contract, and red tests exist.
2. Trust evidence, not inspection — a feature is trusted because its tests pass and the non-functional risks (concurrency, security, architecture) were checked.
3. Never weaken a test or edit a frozen contract to make the build pass.
4. No silent skips — every Verify records PASS, RISK-ACCEPTED, or HARD-STOP. Security findings are always HARD-STOP.
5. Ask, don't guess.

The decisions survive; the output is disposable

The durable asset is the decisions — rules, assumptions, contract, checks. What you produced is one thing that satisfies them and can be made again: a module, a report, a reconciliation. If the thing you'd be upset to lose is the output rather than the reasoning that justified it, you're still working the old way.

Read the method

• 📖 Read the book — the full AIDD method, chapter by chapter
• 🔍 Full hands-on walkthrough — 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 — where we tie, where they win, what only ADD guarantees
• 🗞️ ADD Across the Org: AI-Driven Development Beyond Code

Develop

npm test     # runs the Python tests for the tooling (red/green)

License: MIT.