--- name: add description: >- ADD (AI-Driven Development) — a lean, state-tracked workflow where the AI writes the code and the human owns direction and verification. Drives every change through one atomic task node: Direction (specify · plan · red tests) → Build → Verify, red/green TDD built in, trusted on a recorded receipt not a plausible diff. Research rides the same rails: "investigate this bug", "evaluate this library", "research X" route to the Explore lane. Use whenever a repo has a `.add/` bundle, or the user says "add", "/add", "start a task", "next phase", "specify this", "ADD method", "AI-driven development", or wants spec/tests-first discipline over vague-prompt coding. Resumes across sessions from the bundle alone — run `add status`, never re-read the repo. user-invocable: true category: workflows keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, receipt, gate, task, resume, explore, research] argument-hint: "status | " license: MIT metadata: { author: add, version: "3.4.0", format: ABF-1 } --- # ADD — direction · evidence · a durable bundle (the agent is the hands) You turn intent into the right-sized task, then drive it. ADD keeps the AI fast *and* safe by **fixing direction before the build** (rules, contract, red tests) and **trusting the result on passing evidence**, not on a diff that reads plausible. The bundle survives; the code is disposable. **Engine.** `add` below = `python3 .add/tooling/cli.py` (the ABF-1 CLI) — the vendored copy the installer drops into your project, which stamps `tooling_engine:`; `status --check` warns if it drifts. **First run in a fresh project** (no `.add/tooling/` yet): materialize it once with the package installer — `pilotspace-add init ""` (pip) or `add init ""` / `npx @pilotspace/add init ""` (npm), or `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init "" --no-skill` when installed as the Claude Code plugin — then drive from `.add/tooling/cli.py`. State lives in the `.add/` bundle — files are the database, `graph.json` is a rebuildable cache. The engine records; it never runs the method or spawns an agent. The full loop surface — including `fold · reopen · deltas · search · check · milestone-archive` — is wired. ## Always start here (orient — do not skip) Run **`add status`** first, every session — it is your resume point, read from the bundle, not the repo. Then branch: - **No `.add/` yet** → `add init --profile ""` — those two ship, and `init` refuses any other name rather than guess. Non-code domain? Take `doc`, then re-author its lenses (`domains.md`). Offer to seed starter personas (`seed.md`, opt-in), then size the request (Intake). - **A task is active** (`status` not `done`) → open `.add/tasks/.md`, read its `## CARD`, and work the beat `add status` names next. The beat is **derived from the node's stamps**, not the `status` field — which stays `direction` until close: unfrozen → author + freeze; frozen with no green receipt → build; a fresh green receipt → verify (loop below). - **No active task** → size the request first (Intake), then create scope. ## Intake — size before you create scope (`intake.md`) Read the request into a task shape, then pick the **lane** (you route; the human vetoes): - **Quick** — floor first (security · data · architecture, a consumed `gives:`, frozen scope → a Task); else ≤3 adjacent files, one-sitting diff, zero unknowns — small new behavior fits. Route and go, no node: inline card → red→green → `invariants:` → commit + exactly one `add learn` line. Medium → Task `--depth quick`; large → `standard|deep` or a Milestone. Ceremony falls with size; review never does. - **Task** — one atomic node in the active milestone's scope; `add deltas` first. The 3-beat loop below. - **Explore** — the answer IS the deliverable (research · investigate · high unknowns) — explore-first: questions + a hard budget freeze, and the gate reads the cited `## FINDINGS` brief directly — **no run receipt** for a findings-only explore (`phases/explore.md`). One contract-shaping unknown already argues this lane; freezing a contract on a guess ships the wrong thing with perfect receipts. - **Project / milestone** — a new theme or a slice too big for one task. `add deltas` first, then load the persona whose `flow:` includes **advisor** BEFORE drafting (skip silently if none is seeded), draft the milestone (goal · scope · exit criteria · breadth-first task list), confirm it, create it and its tasks, and record the lens: `add advise --persona

`. **The floor is closed:** anything touching **security · data · architecture** always becomes a real task — never Quick, whatever its size. **Security is always a HARD-STOP.** When in doubt, size up. ## The 3-beat loop (this file IS the loop; refs load on demand) One task = one atomic node. Three beats, one human decision: 1. **DIRECTION** (`phases/direction.md`) — compose the whole bundle in ONE draft, then take the ONE approval. The draft, section by section: - `## RULES` — Must · Reject: what you were told. `## EDGES` — `E` boundary cases; a line you FILL is gate-bound like a Must, an untouched placeholder owes nothing. - `## ASSUMPTIONS` — sweep EVERY `gives:` surface on EVERY dimension (`who · which · when · absent · order · experience`): `A [] covers: · -> `, or retire a pair with `[] n/a · `. A cheaply-checkable guess is better discharged than priced: run the two-minute probe and record `found: ` + its evidence on the line. - `## PLAN` — contract shape (authored into `gives:`/`needs:` frontmatter) · strategy · `--kind explore`'s required `budget:`. `scope:` is FRONTMATTER (`--scope a,b`), never here. - `## CHECKS` — one check per Must and per Reject, each with a `covers:` key. The binding is enforced at **gate**, and it binds EVERY referent you name — Musts, Rejects, probed assumptions, edges. Run the checks **red for the right reason**. - `freeze` REFUSES a template slot, an unauthored `gives:`, an unswept `(dim, surface)` pair, or — at a human floor — an open decision no human answered (**`add interview `** puts each one to them for real, R:UNINTERVIEWED). It names them; `add todo` counts them down as you author. - The ONE approval stamps direction closed: **`add freeze --by "" --authority human`**. Get the composed prompt with `add brief ` — its refs resolve from the graph, so a spec edit re-scopes it with no edit here. 2. **BUILD** (`phases/build.md`) — code until every red check is green. Change **no** check and **no** frozen `gives:`; stay inside `scope:`. A discovered constraint or a strategy turn is *steering* — record it, seal untouched: `add replan --note ""`. Anything that would move a frozen surface is a change-request back to Direction, never a silent edit. 3. **VERIFY** (`phases/verify.md`) — gather evidence, check the 3 residue lenses (security · concurrency · architecture — **security HARD-STOP**), then `add run -- --junitxml="${TMPDIR:-/tmp}/add-run.xml"` for a fresh, bound receipt — `run` reads the report path your command names. Wrap the **narrowest command that reports every bound check**; the full suite rides CI. **No runner for your domain? Write one** — `run` parses JUnit XML and does not care what produced it, so a script comparing a measured value against a threshold your frozen RULES already state earns the same bound receipt (`domains.md`). And **`add gate PASS --by ""`** — a **PASS auto-closes** the task (and repairs its CARD). `add done` is only for closing after a signed `RISK-ACCEPTED`. Emit **lessons** as you learn them, tagged by which of the five specs they sharpen (`ddd · sdd · udd · tdd · add`) — they fold into `.add/specs/` at close (`loop.md`, `deltas.md`). Present every human decision — intake · freeze · gate · close — as a guided choice with the goal→done→plan arc (`gate.md`). Adopting a project-fit persona is opt-in (`personas.md`); a persona never lowers a gate. Delegate a beat to a best-fit persona subagent when it wants an expert (`streams.md`) — the delegate advises and returns a verdict; it never freezes, never gates, and security stays HARD-STOP. Read-only research fans out freely — facts merge; one write taints the stream back onto the serialized path. ## Non-negotiable rules (from the method) 1. **Direction before speed.** Never start Build until RULES · PLAN · CHECKS exist and checks are red. 2. **Trust evidence, not inspection.** A change is trusted because its checks pass and the residue (security · concurrency · architecture) was examined — not because the code reads fine. **A green gate proves the checks you declared ran, passed and are bound — never that they were enough.** A check that asserts nothing still binds and still passes. Writing the check that would have caught the bug is your job; the engine can only prove you ran the ones you wrote (`FORMAT.md` §10). 3. **Never weaken a check or edit a frozen `gives:` to make the build pass.** That inverts the method; a real change is a change-request back to Direction. 4. **No silent skips.** Every Verify ends in exactly one recorded outcome — `PASS`, `RISK-ACCEPTED` (signed, non-security), or `HARD-STOP`. A security finding is always `HARD-STOP`. 5. **A refusal is the method working.** Every engine refusal names its fix in the same breath (`next: `) — do that fix. Never route around the engine, never hand-edit state files or stamps to get past a refusal it just gave you. ## Command cookbook — copy a line ```bash add status # resume · --all full · --check conformance add init --profile code "" # create a .add/ bundle — code | doc ONLY (see domains.md) add upgrade # 2.x bundle? archive it whole, init 3.0, MIGRATION.md guides the rest add new Task --title "..." --depth quick|standard|deep [--sensitivity security|data|architecture] [--kind explore] [--milestone m] [--scope a,b] add brief # the composed XML prompt for the active beat add todo [--milestone m] # the open worklist by beat, each with its next verb add locate # which node's scope owns this file add search "" [--as-of ] # any concept — a delta answers with its own address add advise --persona

# record the lens that reviewed a sequential beat add doctor [--sync] # findings, never gates; --sync recompiles graph.json, re-vendors a stale engine add interview [--answer =confirm|correct|defer] # the open decisions, put to a human add freeze --by "" --authority human # the ONE approval → Build add replan --note "" # record a steering turn on a frozen task — seal untouched add run [--timeout ] -- --junitxml="${TMPDIR:-/tmp}/add-run.xml" # receipt · an explicit report path before the -- wins add gate PASS --by "" # verdict — a PASS auto-closes · RISK-ACCEPTED (signed) · HARD-STOP add done # close after a RISK-ACCEPTED (a PASS gate already did) add learn "" --evidence # file a lesson into a living spec add milestone-done # close a milestone — refuses while a goal box is unchecked ``` ## Depth dial — steps never change, ceremony does Depth tunes **ceremony**, not the authority floor. The floor is computed by the engine from `sensitivity:` (and `index.md`'s `sensitive_paths:`) — `security → human`, `data|architecture → plan`, else `process` — never from depth. - **quick** — CARD · CHECKS · EVIDENCE; at a green, `covers`-bound receipt the AI may record the PASS itself at `process` authority (an explicit pass you run, not an engine auto-verdict), unless the sensitivity floor is higher. - **standard** — the full node; evidence-gated, at whatever authority the floor computes. - **deep** — full node + milestone strategy, lowest-confidence-first; a human owns freeze whenever the floor (or your judgment) calls for it. A coined term you cannot decode is in `terms.md` — load it once, not every session. The method's **why** lives in `FORMAT.md` (the ABF-1 bundle format, in the ADD source repo) — **referenced, never inlined** (load the State; reference the Story). Read it only when a decision is genuinely unclear. The AIDD book is deeper background and is **external** (not shipped with the skill) — treat it as optional; never block waiting to open a file the skill does not ship.