Add

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 from .add/tooling/cli.py. State lives in the .add/ bundle — 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 — one per Must and per Reject, each with a covers: key binding EVERY referent you name: Musts, Rejects, probed assumptions, edges. Run them red for the right reason.
   • freeze REFUSES a template slot, an unauthored gives:, an unswept (dim, surface) pair, a FILLED edge or PROBED assumption no covers: names (R:UNCOVERED — bind it, never delete it), or — at a human floor, and on any Milestone stamped --authority human — a decision no human answered (add interview <slug>, R:UNINTERVIEWED). add todo counts them down as you author.
   • The ONE approval stamps direction closed: add freeze <slug> --by "<name>" --authority human. Get the composed prompt with add brief <slug> — 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 <slug> --note "<what changed>". 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 <slug> -- <test cmd> --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 (run it anyway before any receipt touching the engine). No runner for your domain? Write one — run parses JUnit XML and does not care what produced it (domains.md). Then add gate <slug> PASS --by "<name>" — a PASS auto-closes the task. add done is only for closing after a signed RISK-ACCEPTED.

Emit lessons as you learn them, tagged by the spec they sharpen (ddd · sdd · udd · tdd · add); the close DRAINS the ones it filed (loop.md, deltas.md). Present every human decision — intake · freeze · gate · close — as a guided choice with the goal→done→plan arc (gate.md). A project-fit persona loads by FIT at every beat — the ROSTER is what is opt-in (personas.md) — and never lowers a gate; delegate to one when a beat wants an expert (streams.md): it advises, never freezes or gates, security stays HARD-STOP. Read-only research fans out; one write serializes the stream.

Non-negotiable rules (from the method)

Command cookbook — copy a line

add status                                   # resume · --all full · --check conformance
add init --profile code "<name>"             # 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 <slug> --title "..." --depth quick|standard|deep [--sensitivity security|data|architecture] [--kind explore] [--milestone m] [--scope a,b]
add brief <slug>                             # the composed XML prompt for the active beat
add todo [--milestone m]                     # the open worklist by beat, each with its next verb
add locate <path>                            # which node's scope owns this file
add show <ref> [--expand N]                  # one node WHOLE + its relations, N levels (max 5)
add search ["<term>"] [--type/--status/--milestone V] [--as-of <d>]  # by text, or by field
add advise <slug> --persona <p>              # 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 <slug> [--answer <id>=confirm|correct|defer]  # the open decisions, put to a human
add freeze <slug> --by "<name>" --authority human    # the ONE approval → Build
add replan <slug> --note "<what changed>"    # record a steering turn on a frozen task — seal intact
add run <slug> [--timeout <s>] -- <test cmd> --junitxml="${TMPDIR:-/tmp}/add-run.xml"  # receipt · an explicit report path before the -- wins
add gate <slug> PASS --by "<name>"           # verdict — PASS auto-closes · RISK-ACCEPTED (signed) · HARD-STOP
add learn <ddd|sdd|udd|tdd|add> "<lesson>" --evidence <ref>   # file a lesson into a spec
add fold <lens> "<match>" [--reject | --bind "<decision>"]    # the human's verdict on one lesson
add drop <slug> --reason "<why>"             # withdraw a task from the plan — the reason stays on the node
add milestone-done <slug>                    # close — refuses an unchecked box, an open delta, or an unauthored task

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.