/add

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 | <describe the change or goal>"
license: MIT
metadata: { author: add, version: "3.6.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 in, 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 "<name>"` (pip), `add init "<name>"` / `npx @pilotspace/add init "<name>"` (npm), or `node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init "<name>" --no-skill` as the Claude Code plugin — then drive `.add/tooling/cli.py`. State lives in `.add/` — files are the database, `graph.json` a rebuildable cache. The engine records; it never runs the method or spawns an agent. The full loop surface (`fold · reopen · drop · deltas · search · show · 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 <code|doc> "<name>"` — 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 it (Intake).

• **A task is active** (`status` not `done`) → `add show <slug>` — the node whole, its edges — 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 node in the active milestone; `add deltas` then `add show`. 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 theme, or a slice too big for one task. `add deltas` + `add search`, 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 <milestone> --persona <p>`.

**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<n>` 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<n> [<dim>] covers: <S ids> · <what the spec does NOT say — and the reading you took> -> <cost if wrong>`, or retire a pair with `[<dim>] n/a · <why>`. A cheaply-checkable guess is better discharged than priced: run the two-minute probe and record `found: <what>` + 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` — at least one check per referent you name (Musts, Rejects, probed assumptions,

edges), `covers:`-bound, built