Imported from pilotspace/ADD (add-method/src/add_method/_bundled/skill/add/SKILL.md). Install upstream with npx skills add pilotspace/ADD --skill add. Copyright stays with the author (MIT).

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 "<name>" (pip) or add init "<name>" / npx @pilotspace/add init "<name>" (npm), or node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init "<name>" --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 · 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 the request (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 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 <slug> 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 <slug> --by "<name>" --authority human. Get the composed prompt with add brief <slug> — 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 <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. 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 <slug> PASS --by "<name>" — 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)

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 untouched
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 — a PASS auto-closes · RISK-ACCEPTED (signed) · HARD-STOP
add learn <ddd|sdd|udd|tdd|add> "<lesson>" --evidence <ref>   # file a lesson into a living spec
add milestone-done <slug>                    # 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.