@pilotspace/add 1.0.0

package/skill/add/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: add
+description: >-
+  ADD (AI-Driven Development) — a minimal, state-tracked workflow for building
+  software where the AI writes the code and the human owns direction and
+  verification. Drives every feature through one lean TASK.md: Specify →
+  Scenarios → Contract → Tests → Build → Verify → Observe, with red/green TDD
+  built in. Use this skill whenever working in a repo that has a `.add/`
+  directory, when the user says "add", "start a task", "next phase", "specify
+  this feature", "ADD method", or "AI-driven development", or when scaffolding a
+  new feature and you want spec/tests-first discipline instead of vague-prompt
+  coding. Also use it to resume work across sessions (it reads `.add/state.json`
+  so you never re-read the whole repo).
+---
+
+# ADD — the orchestration engine
+
+You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
+(spec, scenarios, contract, failing tests) **before** the build, and trusting
+the result through passing evidence rather than a plausible-looking diff.
+
+**One file = one task.** Each feature lives in a single `.add/tasks/<slug>/TASK.md`
+with seven sections. You fill them top to bottom; the Python tool tracks where
+you are so context never rots across sessions.
+
+## Always start here (orient — do not skip)
+
+Run the tool to find the resume point instead of re-reading the repo:
+
+```bash
+python3 .add/tooling/add.py status
+```
+
+- **No `.add/` yet** → go to **phase 0 (setup)**: read `phases/0-setup.md`.
+- **A task is active** → open `.add/tasks/<active>/TASK.md`, look at its `phase:`
+  marker, and read the matching `phases/<n>-<phase>.md`. Work *only* that phase.
+- **No active task** → first SIZE the request (see Intake below), then create the
+  right scope: `python3 .add/tooling/add.py new-task <slug> --title "..."`.
+
+## Intake — size a request before creating scope
+
+When the user brings a raw request, classify it BEFORE making a milestone or task:
+read `intake.md` and place it in exactly one bucket — `new-major` · `sub-milestone`
+· `task` · `change-request` — then propose `{ bucket, rationale, command }` and let
+the human confirm. This is the intake altitude (request → versioned scope); see
+`intake.md` for the rubric, the tie-break order, and worked examples.
+
+Once a request is classified `new-major`/`sub-milestone`, drafting the actual
+`MILESTONE.md` (goal · scope · exit criteria · breadth-first tasks) is the second
+half of intake: read `scope.md` for how to fill it well, the per-outcome behavior,
+and the confirm-before-create rule. You propose the draft; the human confirms.
+
+## The flow and which file to load
+
+Load the phase guide **only for the phase you are in** (progressive disclosure):
+
+| Phase | Guide | Produces (TASK.md section) | Who leads |
+|-------|-------|----------------------------|-----------|
+| setup | `phases/0-setup.md` | `.add/` + survivor files | human |
+| specify | `phases/1-specify.md` | §1 rules + ranked least-sure flag | human + AI (co-specify) |
+| scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | human |
+| contract | `phases/3-contract.md` | §3 frozen shape | human + AI |
+| tests | `phases/4-tests.md` | §4 + red suite in `tests/` | human sets, AI writes |
+| build | `phases/5-build.md` | code in `src/`, tests green | **AI** |
+| verify | `phases/6-verify.md` | §6 checks + gate record | **human** |
+| observe | `phases/7-observe.md` | §7 spec delta | human + AI |
+
+In **observe**, also emit **competency deltas** — learnings tagged by which of the five
+(`DDD · SDD · UDD · TDD · ADD`) they improve — so the foundation self-improves across loops.
+You write them as `open`; the human folds them into `PROJECT.md`. Read `deltas.md` for the
+grammar and the status lifecycle. At milestone close (or on demand), run the fold ritual that
+gathers confirmed deltas into a versioned foundation — read `fold.md`.
+
+## The dynamic run (v6)
+
+Once **§3 CONTRACT is FROZEN**, the build→verify half MAY run as a dynamic, auto-gated run —
+fan-out + in-run convergence — instead of a manual build. Read `run.md` for the trigger, the
+touch-boundary, the evidence auto-gate, and the autonomy dial. The human-led front
+(specify·scenarios·contract) is unchanged; the run never edits a frozen contract and never
+auto-passes a security finding.
+
+## Non-negotiable rules (from the method)
+
+1. **Direction before speed.** Never start Build until §1–§4 exist and tests are red.
+2. **Trust evidence, not inspection.** A feature is trusted because its tests pass
+   and the blind-spots (concurrency, security, architecture) were checked — not
+   because the code reads plausibly.
+3. **Never weaken a test or edit a frozen contract to make the build pass.** That
+   inverts the method. A real change is a *change request* back to Specify.
+4. **No silent skips.** Every Verify ends in exactly one recorded outcome:
+   `PASS`, `RISK-ACCEPTED` (signed, non-security only), or `HARD-STOP`. A security
+   finding is always `HARD-STOP`.
+5. **Ask, don't guess.** If a requirement is unclear, stop and ask the user.
+
+## Advancing
+
+After a phase's exit gate is met, advance the state (this also syncs the marker
+inside TASK.md):
+
+```bash
+python3 .add/tooling/add.py advance            # next phase of the active task
+python3 .add/tooling/add.py gate PASS          # at verify: records PASS, marks done
+```
+
+## Depth by stage
+
+The steps never change; their depth does. Read the stage from `add.py status`:
+
+- **prototype** — run light; code is throwaway; design/experience is the point.
+- **poc** — run contract/tests/build deeply on the single riskiest slice only.
+- **mvp** — full flow, narrow scope, light observation.
+- **production** — every step at full rigor + the observe loop.
+
+## The trust layer
+
+The full method (the *why* behind every rule) is the AIDD book in `.add/docs/`.
+When a phase decision is genuinely unclear, read the linked chapter — each phase
+guide points to its chapter. Do not duplicate the book here; load it on demand.

package/skill/add/deltas.md

@@ -0,0 +1,69 @@
+# Competency deltas — how each loop sharpens the foundation
+
+A **competency delta** is a single learning a task produces, tagged by which of ADD's five
+competencies it improves. You write deltas in a task's **OBSERVE** phase; later, the
+`foundation-update-loop` gathers the confirmed ones and folds them into a versioned `PROJECT.md`.
+This is how `DDD · SDD · UDD · TDD · ADD` stop being write-once and start converging.
+
+You (the AI) **emit** deltas as `open`. Only the **human** moves a delta to `folded` or `rejected`
+(folding into the foundation is judgment — see the verify/observe seam). You never self-fold.
+
+## The grammar (frozen)
+
+Each delta is ONE line, exactly:
+
+```
+- [<COMPETENCY> · <status>] <learning> (evidence: <pointer>)
+```
+
+- `<COMPETENCY>` — exactly one of the five (below).
+- `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
+- `<learning>` — the insight, in one phrase ("the domain model missed multi-tenancy").
+- `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review
+  note. No evidence → it is an opinion, not a delta.
+
+## The five competencies (pick exactly one per delta)
+
+| tag | competency | a delta here means you learned something about… |
+|-----|------------|--------------------------------------------------|
+| `DDD` | Domain | the domain model — an entity, rule, or boundary the spec assumed wrong |
+| `SDD` | Spec | what the feature must do / must reject — a missing or wrong requirement |
+| `UDD` | UI/UX | the user-facing shape — a flow, affordance, or wording that misled |
+| `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
+| `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
+
+If a learning seems to touch two, ask "which competency, once updated, would have PREVENTED this?"
+That is its home. Split genuinely separate learnings into separate deltas; never tag one twice.
+
+## Status lifecycle
+
+```
+emit (OBSERVE)        human review (foundation-update-loop)
+   open  ───────────▶  folded     (the learning is merged into PROJECT.md; version bumps)
+         └──────────▶  rejected   (considered and deliberately NOT folded — the trail is kept)
+```
+
+An `open` delta is a pending signal. `folded` and `rejected` are both human decisions; a `rejected`
+delta is left in place (not deleted) so "we saw this and chose not to act" stays auditable.
+
+## Reject codes (well-formedness — you are the first check, the human is the backstop)
+
+There is no engine validator yet, so before you record a delta, self-check it:
+
+- `unknown_competency` — the tag is missing or not one of `DDD · SDD · UDD · TDD · ADD`. Fix the tag.
+- `no_evidence` — the `(evidence: …)` pointer is missing or empty. Add the proof, or drop the line.
+- `unknown_status` — the status is not `open | folded | rejected`. A fresh delta is `open`.
+
+## Worked example
+
+A task that built a tenancy feature finished its OBSERVE phase with:
+
+```
+- [DDD · open] the account model conflated org and workspace (evidence: scenario_cross_tenant_read failed)
+- [TDD · open] no scenario covered a deleted tenant's dangling sessions (evidence: review note, PR thread)
+- [ADD · open] the scaffold's allow-list missed the tenancy lib, slowing build (evidence: build log retry)
+```
+
+Three learnings, three competencies, each with a pointer. At the next foundation update the human
+folded the DDD and TDD deltas into `PROJECT.md` (→ `folded`) and rejected the ADD one as a one-off
+(→ `rejected`). The foundation got sharper; nothing was silently lost.

package/skill/add/fold.md

@@ -0,0 +1,66 @@
+# Folding deltas — how the foundation self-improves
+
+This **closes the loop**. `deltas.md` lets a task EMIT learnings (`open` competency deltas in its
+OBSERVE phase); folding gathers the confirmed ones and writes them into a **versioned foundation**,
+so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones instead of drifting.
+
+You (the AI) **gather and propose**; the **human confirms**; you then write the **append-only** fold.
+You never self-fold — folding is judgment (see the verify/observe seam).
+
+## When to fold
+
+At **milestone close** (the natural "version bump to the foundation"), or **on demand** when open
+deltas have piled up. This is a convention, not a command — there is no `add.py fold`; the ritual
+lives here so the engine stays judgment-free.
+
+## The ritual
+
+1. **Gather** — scan every task's OBSERVE `### Competency deltas` block for lines still `open`.
+2. **Group** — bucket them by competency (`DDD · SDD · UDD · TDD · ADD`).
+3. **Propose** — for each, draft the exact foundation edit (see routing) and show the human.
+4. **Confirm** — the human accepts or declines each delta. No write happens without this.
+5. **Write** — append the accepted edits, flip each delta's status, and bump the version.
+
+## Fold routing (every competency has a home)
+
+| competency | folds into | how |
+|------------|-----------|-----|
+| `DDD` | `PROJECT.md` §Domain (DDD) | refine/append a model bullet |
+| `SDD` | `PROJECT.md` §Spec / Living Document (SDD) | refine/append a settled-vs-open line |
+| `UDD` | `PROJECT.md` §Users (UDD) | refine/append a UX line |
+| `TDD` | `CONVENTIONS.md` | append a testing convention (no PROJECT.md section — it is the engine) |
+| `ADD` | `CONVENTIONS.md` | append a build/harness convention (likewise the engine) |
+
+**Every** fold — whatever the competency — ALSO appends one row to `PROJECT.md` **§Key Decisions**
+(date · decision · why · outcome): the universal, auditable trail of what the foundation learned.
+
+## Status transitions & version
+
+- on **confirm**: the delta moves `open` → `folded` (and its edit is appended to the routed target).
+- on **decline**: the delta moves `open` → `rejected` and is **left in place** — never deleted —
+  so "we considered this and chose not to act" stays auditable.
+- a fold is **append-only**: it adds bullets/rows; it never silently rewrites existing foundation text.
+- each fold session **bumps** the `foundation-version:` marker in `PROJECT.md` by one (monotonic int).
+
+## Reject codes (the AI is first check, the human the backstop)
+
+- `no_open_deltas` — nothing is `open` anywhere. The ritual is a no-op; do **not** bump the version.
+- `unconfirmed_fold` — a write was attempted without recorded human confirmation. The AI proposes;
+  it never self-folds. Stop and get confirmation.
+- `unroutable_delta` — a delta's competency is not one of the five, so it has no fold target. Fix the
+  delta (it is malformed per `deltas.md`) before folding.
+
+## Worked example (from this repo's own history)
+
+The `competency-deltas` task closed its OBSERVE with two deltas — the homeless ones, `TDD`/`ADD`,
+which have no PROJECT.md section:
+
+```
+- [ADD · open] dogfood .add/tooling template can silently diverge from canonical (evidence: md5 mismatch this build)
+- [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: scope-loop note + this build)
+```
+
+At the next fold the human confirms both. Routing sends each to `CONVENTIONS.md` (a "sync the dogfood
+tree + assert md5 parity" convention), appends a §Key Decisions row for each, flips them to `folded`,
+and bumps `foundation-version` 1 → 2. The two competencies the foundation never tracked before now
+have a home — which is exactly why v5 routes TDD/ADD to `CONVENTIONS.md`.

package/skill/add/intake.md

@@ -0,0 +1,49 @@
+# Intake — size a request into versioned scope
+
+Before a task exists, ADD turns a raw request into correctly-sized, versioned scope.
+This is the **intake altitude**: the per-task flow is phases 0–7; intake is the step
+*before* a task — request → milestone or task. You (the AI) **propose**; the human
+**confirms**. Never create scope without a confirmed proposal.
+
+## The four buckets
+
+Classify every request into exactly ONE bucket:
+
+| Bucket | Decision test | Implied command |
+|--------|---------------|-----------------|
+| `new-major` | a new product theme/pillar no active milestone's goal covers | `add.py new-milestone vN` |
+| `sub-milestone` | a slice of an EXISTING major theme, too big for one task | `add.py new-milestone vN-M` |
+| `task` | fits within the ACTIVE milestone's stated scope | `add.py new-task <slug>` |
+| `change-request` | modifies ALREADY-FROZEN scope (a frozen contract or a shipped promise) | `add.py phase specify\|contract <affected>` |
+
+**Tie-break order: the frozen-scope test runs FIRST, before the size test.**
+First ask "does this change already-frozen scope?" → if yes, it is a `change-request`
+(never re-size frozen work as new scope). Only if no, apply the size test: a new theme
+→ `new-major`; a slice of a live theme → `sub-milestone`; fits the active milestone
+→ `task`.
+
+## What you emit (the proposal)
+
+For every request, emit ONE of:
+
+- **a classification** — `{ bucket, rationale, command }` — where `rationale` names WHY
+  (the theme, the slice, the fit, or the frozen scope touched) and `command` is the exact
+  `add.py …` from the table. The human confirms or overrides before you run it.
+- **a rejection** — `{ reject, rationale }` — and you create nothing:
+  - `ask_human` — too ambiguous/underspecified to size. Ask the human; never guess a bucket.
+  - `frozen_scope` — it changes frozen scope; route it as a `change-request` back to
+    SPECIFY/CONTRACT of the affected task — never spawn a parallel milestone that forks the truth.
+  - `split_required` — it spans more than one bucket; propose the SMALLEST set of correctly-sized
+    items, each with its own rationale; never force it into one milestone.
+
+When confirmed, record the `rationale` in the artifact you create or affect — the new
+MILESTONE.md goal/body, the new TASK.md, or a note in the affected TASK.md — never in state.json.
+
+## Worked examples (from this project's own history)
+
+| request | bucket | rationale |
+|---------|--------|-----------|
+| give ADD a hosted web dashboard | new-major | a new product theme no active milestone's goal covers → a fresh major line (v5) |
+| add the build corridor + tests-red-before-build | sub-milestone | a slice of the live v4 "self-driving" theme, too big for one task → v4-2 |
+| expose owner/stop as --json | task | fits the active v4-1 (intake interface) scope → one task |
+| guide --json phase/gate should be nullable | change-request | changes the FROZEN machine-state-json contract → reopen its CONTRACT, do not make a new milestone |

package/skill/add/phases/0-setup.md

@@ -0,0 +1,35 @@
+# Phase 0 — Setup (once per project)
+
+Goal: make every later gate enforceable automatically. Do this once.
+
+## Do
+
+1. Initialise the runtime (creates `.add/` + survivor-layer files):
+   ```bash
+   python3 .add/tooling/add.py init --name "<project>" --stage prototype
+   ```
+   If the tool isn't there yet, the installer (`npx @pilotspace/add init`) placed it at
+   `.add/tooling/add.py`.
+2. Fill the survivor-layer files (they outlive all code):
+   - `.add/PROJECT.md` — **the foundation**: Domain (DDD) · Spec/Living-Document (SDD,
+     → active milestone) · UI/UX (UDD) · Key Decisions. Cross-milestone context the
+     engine reads first. Keep it to one screen. Book: `docs/14-foundation.md`.
+   - `.add/CONVENTIONS.md` — language, folders, naming, lint, error-code style, architecture.
+   - `.add/GLOSSARY.md` — one name per concept; used in specs, contracts, and code.
+   - `.add/MODEL_REGISTRY.md` — which AI model/version writes this project.
+   - `.add/dependencies.allowlist` — packages the AI may use; CI rejects others.
+3. Confirm CI runs green on the empty skeleton before the first feature.
+
+## Exit gate
+
+- [ ] `.add/state.json` exists (`add.py status` works).
+- [ ] `.add/PROJECT.md` foundation filled (domain · spec · UI/UX).
+- [ ] CONVENTIONS, GLOSSARY, MODEL_REGISTRY, allowlist filled.
+- [ ] Pipeline green on the skeleton.
+
+## Next
+
+```bash
+python3 .add/tooling/add.py new-task <slug> --title "<feature>"
+```
+Then read `phases/1-specify.md`. · Book: `docs/10-setup-and-stages.md`.

package/skill/add/phases/1-specify.md

@@ -0,0 +1,55 @@
+# Phase 1 — Specify (the rules)
+
+Goal: state what the feature MUST do and what it must REJECT, with zero ambiguity
+for the AI to resolve by guessing. Fill **§1 SPECIFY** in TASK.md.
+
+Specify is **co-specification**: brainstorm the shape WITH the user, draft it, then let
+the user validate with your advice. If you cannot write the spec, you do not yet
+understand the feature — that is information, not an obstacle. Stop and ask.
+
+## Co-specify in three moves
+
+1. **Diverge** — before drafting, surface the decision space: the 2–3 genuine framings of the
+   feature + the open questions you would otherwise guess. Invite the user to add, kill,
+   redirect. (Conversational — no new file. At prototype/poc this collapses to one sentence.)
+2. **Converge** — draft §1, then RANK what you are least sure about (below).
+3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
+
+## Produce (in TASK.md §1)
+
+- **Framings weighed** — a one-line trace of what you considered: `X (chosen) · Y · Z`.
+- **Must** — each required behavior.
+- **Reject** — each refused input/situation, paired with a **named error code**
+  (`amount <= 0 -> "amount_invalid"`, never "handle bad input").
+- **After** — the state that is true once it succeeds.
+- **Assumptions — least-sure first** — ranked most-likely-wrong → least. The top 1–2 carry a
+  `⚠` flag: `⚠ <assumption> — least sure because <why>; if wrong: <cost>`. The rest are the
+  low-stakes `[x]` tail. Never a flat wall of equal `[x]` ticks — that is what gets rubber-stamped.
+
+## The least-sure flag is bundle-wide
+
+The single human approval happens once, at the contract freeze, over the whole bundle. So your
+§1 ranking is the FIRST FEEDER into a bundle-level flag the user reads at the seam (`run.md`):
+*"of everything I'm asking you to freeze, these 1–2 are most likely wrong."* A flag may point at
+a §1 assumption, an uncovered scenario, or the contract shape.
+
+## AI prompt
+
+> Role: a domain analyst who brainstorms, then asks rather than assumes. Read CONVENTIONS,
+> GLOSSARY, and the user's raw input. First surface 2–3 framings + open questions and let me
+> react. Then produce §1: Framings weighed, every Must, every Reject with a named error code,
+> the After state, and the Assumptions RANKED least-sure first — flag the 1–2 you are least
+> sure about with why + cost. Never resolve an ambiguity by guessing.
+
+## Exit gate
+
+- [ ] Framings weighed noted; every required behavior stated.
+- [ ] Every rejection has a named error code; success state-change described.
+- [ ] Assumptions ordered least-sure first; the 1–2 `⚠` flags carry why + cost — or an honest
+      "none material" that still names the single biggest risk (never a blank "none").
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/2-scenarios.md`.
+Book: `docs/03-step-1-specify.md`. (UI feature? also sketch flows + every screen
+state: loading/empty/error/success.)

package/skill/add/phases/2-scenarios.md

@@ -0,0 +1,36 @@
+# Phase 2 — Scenarios (pass/fail cases)
+
+Goal: rewrite each rule as a concrete Given/When/Then that is readable by people
+and checkable by machines. This is the highest-leverage artifact — the tests are
+generated from it. Fill **§2 SCENARIOS** in TASK.md.
+
+## Produce (in TASK.md §2)
+
+```gherkin
+Scenario: <short name>
+  Given <starting situation>
+  When <action>
+  Then <observable result>
+  And <what must remain unchanged>   # REQUIRED for every rejection
+```
+
+The `And ... unchanged` clause catches corrupting partial failures (e.g. a balance
+deducted before a check fails). Never omit it on a rejection.
+
+## AI prompt
+
+> Role: a specification tester. Read §1 and GLOSSARY. Write one scenario per Must
+> and per Reject rule. For every rejection add an And-clause asserting what must NOT
+> change. Results must be specific and observable — never "then it works".
+
+## Exit gate
+
+- [ ] One scenario per Must rule.
+- [ ] One scenario per Reject rule.
+- [ ] Each result is a specific, observable fact.
+- [ ] Every rejection asserts what stays unchanged.
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/3-contract.md`.
+Book: `docs/04-step-2-scenarios.md`.

package/skill/add/phases/3-contract.md

@@ -0,0 +1,41 @@
+# Phase 3 — Contract (freeze the shape)
+
+Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE
+it. This is the seam that makes the AI-led build safe: below it code is
+disposable; above it nothing breaks because the shape does not move. Fill
+**§3 CONTRACT** in TASK.md.
+
+## Produce (in TASK.md §3)
+
+- Interfaces (endpoints/functions/messages) with inputs/outputs.
+- Request/response shapes + persistent schema (note transactional needs).
+- Names drawn from `GLOSSARY.md` (same concept = same name everywhere).
+- A response for **every** Reject error code from §1.
+
+Then mark `Status: FROZEN @ v1`. Generate a mock + contract tests so dependent
+work can start before the real code exists.
+
+**The freeze is the one approval.** This seam is where the single human approval lands, over the
+whole bundle (§1–§4). Before asking for it, present the bundle **least-sure first**: the 1–2 points
+most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
+eye before they freeze. See `run.md`.
+
+## AI prompt
+
+> Role: an interface architect; frozen contracts are immutable. Read §1, §2,
+> GLOSSARY. Produce §3: interfaces, shapes, schema named from the glossary; a
+> response for every Reject code; a mock returning the contracted shapes and
+> contract tests pinning them. Mark FROZEN. No business logic. Never change a
+> frozen contract — a change reopens Specify.
+
+## Exit gate
+
+- [ ] Versioned and marked `FROZEN`.
+- [ ] Contract tests pass against the mock.
+- [ ] Every name matches the glossary.
+- [ ] Every spec rejection has a contracted response.
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/4-tests.md`.
+Book: `docs/05-step-3-contract.md`.

package/skill/add/phases/4-tests.md

@@ -0,0 +1,37 @@
+# Phase 4 — Tests (red safety net)
+
+Goal: turn scenarios + contract into automated tests and confirm they FAIL before
+any code exists. This operationalizes red/green TDD: red now, green only after
+Build. Fill **§4 TESTS** and write the suite into `.add/tasks/<slug>/tests/`.
+
+## The must-fail principle
+
+Run the suite now, with no implementation — it must be **red for the right
+reason** (missing implementation, not a broken harness). A test that passes
+before code exists is testing nothing and will wave bad code through later.
+
+## Produce
+
+- One executable test per scenario (§2), asserting **behavior, not internals**.
+- Contract-conformance tests (shapes + error responses from §3).
+- Side-effect assertions on rejection paths (`assert balance unchanged`).
+- A recorded coverage target in §4.
+
+## AI prompt
+
+> Role: a test author who writes tests before code. Read §2 and §3. Turn each
+> scenario into an executable test; add contract-conformance and edge-case tests;
+> run the suite and confirm it fails for the right reason. Record a coverage
+> target. Do NOT implement the feature. Never assert on internals.
+
+## Exit gate
+
+- [ ] One test per scenario.
+- [ ] Suite runs and is **red for the right reason**.
+- [ ] Tests assert observable behavior.
+- [ ] Coverage target recorded.
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/5-build.md`.
+Book: `docs/06-step-4-tests.md`.

package/skill/add/phases/5-build.md

@@ -0,0 +1,38 @@
+# Phase 5 — Build (AI writes the code)
+
+Goal: implement the feature so EVERY failing test passes — without changing any
+test or the contract. This is the only phase the AI leads. It works because §1–§4
+removed all ambiguity. Write code into `.add/tasks/<slug>/src/`.
+
+## Work in small batches
+
+Pick ONE task-sized slice, restate the tests it must satisfy, implement, run
+tests, iterate to green. Keep each batch small enough to review in full — you
+cannot move faster than you can verify.
+
+## The cardinal rule
+
+**Never weaken or delete a test to make it pass, and never edit the frozen
+contract.** That makes the code judge itself. A genuine need to change either is a
+change request back to Specify. Honor the feature-specific safety rule named in §5
+(e.g. atomic balance update) — the one property tests alone may not force.
+
+## AI prompt
+
+> Read §1, §3, §4, and CONVENTIONS. Make EVERY failing test pass, one small batch
+> at a time. Constraints: do NOT change any test; do NOT change the contract; honor
+> the §5 safety rule; use only allow-listed packages; stop and ask if unclear.
+> Report which tests pass and exactly what changed.
+
+## Exit gate
+
+- [ ] All tests pass.
+- [ ] Coverage did not decrease.
+- [ ] No test and no contract modified by the AI.
+- [ ] No dependency outside the allow-list.
+- [ ] Change small enough to review in full.
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/6-verify.md`.
+Book: `docs/07-step-5-build.md`.

package/skill/add/phases/6-verify.md

@@ -0,0 +1,39 @@
+# Phase 6 — Verify (evidence + blind-spot checks)
+
+Goal: establish trust and record an outcome. Passing tests are necessary, not
+sufficient. This phase is **human-led** — there is no AI role. Fill **§6** in
+TASK.md including the GATE RECORD.
+
+## Part one — confirm the evidence
+
+- [ ] All tests pass.
+- [ ] Coverage did not decrease.
+- [ ] No test or contract was altered during build.
+
+If any is false, stop and return to Build — there is nothing to verify yet.
+
+## Part two — check what tests miss
+
+- **Concurrency/timing** — is it correct when two run at once? (Tests run serially
+  and miss races.) This is usually the single most important check.
+- **Security** — exposed secrets, injection openings, unexpected/invented
+  dependencies. A security finding is always `HARD-STOP`, never a waiver.
+- **Architecture** — does it respect layering/dependency rules in CONVENTIONS.md?
+
+## Record exactly one outcome (no silent pass)
+
+| Outcome | When |
+|---------|------|
+| `PASS` | all checks met |
+| `RISK-ACCEPTED` | a **non-security** gap, with signed owner + ticket + expiry |
+| `HARD-STOP` | any failing test or any security finding |
+
+## Exit gate / Next
+
+- [ ] Evidence confirmed, blind-spots checked, a person approved, outcome recorded.
+
+```bash
+python3 .add/tooling/add.py gate PASS          # marks the task done
+# or: add.py gate RISK-ACCEPTED   |   add.py gate HARD-STOP (return to Build)
+```
+Then read `phases/7-observe.md`. Book: `docs/08-step-6-verify.md`.

package/skill/add/phases/7-observe.md

@@ -0,0 +1,32 @@
+# Phase 7 — Observe (feed the next loop)
+
+Goal: release deliberately, watch reality, and turn what you learn into the next
+spec. Release is not the finish line — it is where the most reliable information
+about the feature finally appears. Fill **§7** in TASK.md.
+
+## Do
+
+1. **Release behind a blast-radius limit** — feature flag and/or gradual rollout.
+2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
+   define what you alert on: overall error rate, each rejection's rate (a spike in
+   one is a signal), latency of the risky operation under load.
+3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
+   concrete change that re-enters the flow at Specify (a new task).
+
+## AI prompt
+
+> Role: a reliability analyst feeding the next cycle. Read telemetry, objectives,
+> incidents. Report error-budget burn; cluster errors and surface the top
+> real-world failures; draft a SPEC delta with evidence links. Never auto-roll-back
+> — recommend; a human owns the production decision.
+
+## Exit gate
+
+- [ ] Released behind a flag/rollout.
+- [ ] Scenario-based monitors live.
+- [ ] A reviewed spec delta captured (becomes the next `new-task`).
+
+## Next
+
+Loop. The artifacts you built are living documents the next cycle refines.
+Book: `docs/09-the-loop.md`.