@pilotspace/add 1.17.0 → 2.1.0

package/README.md

@@ -2,202 +2,189 @@
   <a href="https://www.npmjs.com/package/@pilotspace/add"><img alt="npm version" src="https://img.shields.io/npm/v/@pilotspace/add.svg"></a>
   <a href="https://pypi.org/project/pilotspace-add/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/pilotspace-add.svg"></a>
   <a href="https://github.com/pilotspace/ADD/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <a href="https://pilotspace.github.io/ADD/"><img alt="Read the book" src="https://img.shields.io/badge/docs-read%20the%20book-blue.svg"></a>
   <a href="https://github.com/pilotspace/ADD/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/pilotspace/ADD.svg"></a>
 </p>
 
 # ADD — AI-Driven Development
 
-**One skill. Eight steps. Five disciplines. Every feature ships through the loop.**
+**Your AI's first milestone is always great. ADD is for every milestone after that.**
 
 > A minimal, state-tracked skill for building software when the AI writes the code
 > and **you** own the two things it cannot do alone: decide *what* to build, and
-> *verify* it is correct. Native on Claude Code; every other CLI coding agent
-> follows the same loop through the phase guides.
+> *verify* it is correct.
 
-ADD is the **orchestration engine** of the AIDD method. It sits on top of a
-context foundation (DDD → SDD → UDD) and runs as a red/green TDD ↔ AI-build loop.
-The full reasoning — *why* every rule exists — is the AIDD book bundled in
-[`docs/`](./docs/README.md). Read it once; keep it open beside you.
+**The agent is the hands. ADD is the memory, judgment, and conscience — the part
+of the team that survives when the context window doesn't.** Memory: the board,
+frozen contracts, and living specs on disk (`add.py status` resumes any session
+losslessly). Judgment: personas propose each task's lane and the loop learns from
+traced outcomes (`add.py deltas`). Conscience: evidence-scored gates, the tamper
+tripwire, the security hard-stop.
+
+Native on Claude Code; every other CLI agent follows the same loop through the
+phase guides. The full reasoning — *why* every rule exists — is
+[the AIDD book](https://pilotspace.github.io/ADD/).
 
 ```
   Foundation (context):  DDD  ·  SDD  ·  UDD
   Engine (this skill):   TDD  ⇄  ADD
-  Flow per feature:  Specify → Scenarios → Contract → Tests → Build → Verify → Observe ↻
+  Flow per task:  Direction (spec · scenarios · contract · red tests → ONE freeze)
+                  → Build (red → green)  → Verify (evidence-scored gate)  ↻
 ```
 
 ## Quick Start
 
 ```bash
-# Node / npm
-npx @pilotspace/add init
+npx @pilotspace/add init                                # Node / npm
 ```
-
 ```bash
-# Python / pip
-pip install pilotspace-add && pilotspace-add init
+pip install pilotspace-add && pilotspace-add init       # Python / pip
 ```
 
 Then, in your coding agent, say what you want to build:
 
 > `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
 
-The agent sizes it into a milestone (you confirm the shape), drafts the spec →
-scenarios → contract → tests as one bundle (you approve once, at the frozen
-contract), then builds and verifies to green. Full detail below — **Install**,
-**Use it**, and the [10-minute Quickstart](./GETTING-STARTED.md).
-
-## Why ADD (and why it is minimal)
-
-Heavy doc-first methods burn your time writing documents and lose the thread
-across sessions (context rot). ADD fixes both:
-
-- **One file per feature.** Spec, scenarios, contract, test-plan, and gate record
-  all live inline in a single `TASK.md`. No sprawling doc tree.
-- **State on disk, not in chat.** A Python tool tracks where you are in
-  `.add/state.json`, so a fresh session resumes with one command instead of
-  re-reading the repo.
-- **Progressive disclosure.** The skill loads only the guide for the phase you are
-  in — the context window stays lean.
-
-## Where ADD fits vs. skill libraries (e.g. agency-agents)
-
-ADD is an **orchestration method** — the gated loop (spec → scenarios → contract → tests → build →
-verify → observe) that decides when work is trusted. It is not a catalog of ready-made expert
-personas. Skill libraries like [agency-agents](https://github.com/msitarzewski/agency-agents), or
-role-specific subagents (a backend expert, a security reviewer, a senior Java engineer), sit at a
-different layer: they answer **who does the work** — a domain stance, vocabulary, and craft rules
-for one kind of task. ADD answers **how you trust what gets built**, no matter who or what wrote it.
-
-The two layers compose; they don't compete. ADD's persona loop **distills** a lean, project-fit
-persona from a teacher corpus like agency-agents — vendored at
-[`personas-teacher/`](./personas-teacher/), read **off-build** by the AI while drafting a persona,
-never a runtime dependency — down to the three parts a project actually needs: **Identity** (the
-stance), **Critical Rules** (the non-negotiables), and **Success Metrics** (the done-bar). The
-project then owns that persona outright.
-
-A distilled persona is applied as an **advisory overlay** during design, build, or verify — it
-shapes *how* a step gets done, never whether it happens: it can't skip a gate, edit a frozen
-contract, or wave through a security finding. That gated loop is what ADD contributes underneath
-any persona, distilled or not.
-
-## Best setup: ADD alongside other agent libraries
-
-1. **Install ADD** (below) — it drives the loop: which phase you're in, what needs your approval,
-   whether something is proven.
-2. **Keep whatever subagent libraries you already use.** ADD's own five phase specialists
-   (`add-design`, `add-build`, `add-verify`, `add-persona`, `add-advisor`) live in the same
-   `.claude/agents/` mechanism as any other Claude Code subagent — a distilled persona, an
-   agency-agents-derived specialist, a built-in one (a backend expert, a security reviewer). They
-   coexist with zero conflict; nothing is replaced.
-3. **Prefer ADD's named roster first for anything phase-shaped** — spawning `add-verify` for the
-   independent adversarial refute-read, `add-build` for a red→green batch — before an ad-hoc spawn.
-   Reach for another specialist when a piece needs deep domain expertise a generic phase agent
-   doesn't carry (a Java-specific review, a payments-domain lens).
-4. **The gates hold no matter who did the work.** A delegated subagent proposes; the orchestrating
-   agent records. A security finding is always a `HARD-STOP`, and a low self-reported confidence
-   means refine or re-spawn — never a pass — whichever subagent produced it.
+The agent sizes it into a milestone (you confirm the shape), drafts the
+specification bundle — spec → scenarios → contract → red tests as one Direction
+pass (you approve once, at the frozen contract) — then builds and verifies to
+green. Full walkthrough: the [10-minute Quickstart](./GETTING-STARTED.md).
+
+## Highlights
+
+- 📉 **Your agent stops re-breaking last month's work** — every decision lives on disk (`PLAN.md`, frozen contracts, red suites, `.add/state.json`), so a fresh session resumes with the full picture. Measured: quality held flat where a long conversation decayed.
+- ✅ **Stop babysitting the build** — you approve once, at the frozen contract; from there the agent drives Direction → Build → Verify and only comes back when it matters.
+- 🔬 **Know it's correct without reading every line** — trust comes from your pre-declared tests passing, never a diff that merely *looks* right; gaming a test to reach green is treated as tampering.
+- 💸 **Structure without the ceremony tax** — a thin 31-verb kernel, a 3-call task walk, one file per feature keep ADD the cheap option, not the heavyweight one.
+- 🔒 **Never ship a security hole on autopilot** — any security finding is a hard stop with you in the loop, in every mode.
+- 🧠 **The method adapts to *your* codebase** — a project-owned persona proposes each task's approach, the freeze ratifies it, outcomes are traced, and the loop learns what works here (GEPA).
+- 🎨 **See the UI before a line of code** — a wireframe and a zero-dependency HTML mock, approved before any build.
+- 👥 **Grows with your team** — git-native multi-user, N parallel milestones, DAG-scheduled waves; monorepo or multi-repo in one team.
+- 🤝 **Keep the agent you already use** — Claude, Copilot, Cursor, Codex, Gemini; install via npm, pip, or the Claude Code plugin.
+
+> _Direction before speed. Trust comes from passing tests — not from reading code and finding it plausible._
+
+## Why ADD — context rot, measured
+
+Every AI tool writes code fast and aces a greenfield first milestone. The unsolved
+part is **trust across change**: when the spec evolves in milestone 2 and breaks
+compatibility in milestone 3, does the work you already trusted *stay* trusted?
+
+Our benchmark runs the same six-milestone evolving project through each flow under
+a pinned model with deterministic probe scoring
+([report, revised edition](https://github.com/pilotspace/ADD/blob/main/benchmark/results/2026-07-add-2.0-remeasure.md)).
+The causal finding: when ONE continued conversation carried the milestones, every
+flow decayed the same way (coverage .92 → .75, an early spec violation carried
+through five more milestones). When every milestone instead started a **fresh
+session resuming from disk**, ADD held every floor at 1.0 across all six — through
+a breaking shape change and a cross-cutting refactor — with zero regressions.
+
+That's the design, in three moves:
+
+- **One file per feature.** Spec, scenarios, contract, test-plan, and gate record all live inline in a single `PLAN.md`. No sprawling doc tree.
+- **State on disk, not in chat.** A stdlib-Python kernel tracks where you are in `.add/state.json`, so a fresh session resumes with one command instead of trusting a long conversation's memory.
+- **Progressive disclosure.** The skill narrates the whole loop itself and loads a deeper phase reference only when the beat needs it — the context window stays lean.
+
+<sub>**Honesty note:** on this friendly single-app workload a strong model under spec-kit also passed the restart floors (and ran cheaper) — we published the retraction of our own earlier collapse claim when we found the meter defect behind it. What ADD uniquely adds is the *guarantees*: contracts that can't be silently edited, tests that can't be quietly weakened, security findings that can't scroll past.</sub>
+
+## ADD vs skill libraries (e.g. agency-agents)
+
+ADD is the **trust layer** — the gated loop (Direction → Build → Verify) that
+decides when work is trusted, plus the on-disk memory it runs on. It answers **how
+you trust what gets built**. Skill libraries and role-specific subagents (a backend
+expert, a security reviewer) answer **who does the work**. Different layers — they
+compose, they don't compete.
+
+ADD's persona loop **distills** a lean, project-fit persona from a teacher corpus
+like [agency-agents](https://github.com/msitarzewski/agency-agents) — vendored at
+[`personas-teacher/`](./personas-teacher/), read off-build while drafting, never a
+runtime dependency — down to the three parts a project needs: **Identity**,
+**Critical Rules**, **Success Metrics**. The project then owns that persona.
+
+A distilled persona is an **advisory overlay** during direction, build, or verify:
+it shapes *how* a step gets done, never whether it happens. It can't skip a gate,
+edit a frozen contract, or wave through a security finding. Personas also
+propose each task's route (full walk · fast lane · inline); the freeze ratifies it,
+the gate traces the outcome, and `add.py deltas` rolls the traces into a per-lane
+scoreboard the loop reflects on (GEPA).
+
+**Best setup:** install ADD to drive the loop, keep whatever subagent libraries you
+already use. ADD ships two agents — `add-worker` (the execution shell) and `add-advisor`
+(the second mind it spawns to propose a plan, pressure-test a draft, or decide a delegable
+ambiguity) — in the same `.claude/agents/` mechanism as any other subagent; they coexist
+with a distilled persona or a built-in expert with zero conflict, nothing is replaced.
+Prefer `add-worker` for anything phase-shaped (verify mode for the adversarial refute-read,
+build mode for a red→green batch) and let it consult `add-advisor` when confidence is thin;
+reach for another specialist when a piece needs deep domain expertise the phase guide
+doesn't carry. **The gates hold no matter who did the work** — a delegated subagent
+proposes; the orchestrating agent records.
 
 ## Install
 
-Pick your ecosystem — all three install the same skill, tooling, and book:
+Pick your ecosystem — all three install the same skill and tooling:
 
 ```bash
-# Node / npm
-npx @pilotspace/add init
+npx @pilotspace/add init                   # Node / npm
 ```
-
 ```bash
-# Python / pip
-pip install pilotspace-add
-pilotspace-add init
+pip install pilotspace-add && pilotspace-add init      # Python / pip
 ```
-
 ```text
 # Claude Code plugin — no npm or pip needed
 /plugin marketplace add pilotspace/ADD
 /plugin install add@add-method
 ```
 
-The plugin carries the engine and the book. On first `/add`, the skill materializes them
-into the project (`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`) and scaffolds
-`.add/` — a self-contained, portable result identical to the npm/pip flow. The skill stays
-in the plugin, so nothing is duplicated.
-
-No flags needed — the project name is inferred from your folder and the stage
+The plugin carries the engine. On first `/add`, the skill materializes it into the
+project and scaffolds `.add/` — a self-contained result identical to the npm/pip
+flow. No flags needed: the project name is inferred from your folder and the stage
 defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
 
-**Already installed?** Refresh to the latest without a re-install —
-`npx @pilotspace/add@latest update` (or `pipx run pilotspace-add update`)
-re-materializes the skill, tooling, and book while leaving your project work
-(`.add/state.json`, `PROJECT.md`, milestones, tasks) untouched; add `--check` to
-see whether a project is behind the installed package.
+**Already installed?** `npx @pilotspace/add@latest update` (or `pipx run
+pilotspace-add update`) re-materializes the skill and tooling while leaving your
+project work untouched; add `--check` to see whether a project is behind. **Coming
+from 1.x?** One idempotent command — `python3 .add/tooling/add.py migrate` —
+converts the whole board (task docs to `PLAN.md`, living 5-DD specs seeded).
 
-**New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
-your first feature end to end.
+**New here?** The [10-minute Quickstart](./GETTING-STARTED.md) walks your first
+feature end to end.
 
 This installs:
 
 | Path | What |
 |------|------|
-| `.claude/skills/add/` | the `add` skill Claude loads (thin router + per-phase guides) |
-| `.add/tooling/add.py` | scaffolder + state tracker (Python, stdlib only) |
-| `.add/docs/` | the AIDD book — the method rationale |
-| `.add/DESIGN.md` | (UI projects) the prose front-door to the **render-ready UDD foundation** — delete it if your project has no UI |
-
-On a UI project, UDD gives the AI a frozen design ground to draft from: `DESIGN.md`
-plus a lintable JSON foundation under `.add/design/` (design tokens · component
-catalog · prototype trees). `add.py check` lints that foundation, going red with a
-named code on any layer, catalog, tree, or cross-file violation — and staying
-silent when a project has no design set.
-
-Project state (`.add/state.json`) and the living-documentation files (`CONVENTIONS.md`,
-`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, `SOUL.md` — the AI's
-human-owned voice) are *not* created here — the installer drops files only;
-initialisation is the agent's first move when you run `/add`.
-
-## What this plugin does, writes, and runs (boundaries)
-
-ADD is a development methodology, so by design it works *inside your project* — here is
-exactly what that means, so there are no surprises:
-
-- **Runs only when you ask.** Nothing executes on install. The skill acts when you run
-  `/add` (or another agent follows the guideline block). It is user-initiated, every time.
-- **What it runs:** the bundled engine and bootstrapper only — `node bin/cli.js` and
-  `python3 .add/tooling/add.py`. No downloaded or remote code is executed; everything it
-  runs ships in the package.
-- **What it writes:** files under your project's `.add/` (state, milestones, tasks, the
-  book) and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
-  it also materializes the engine + book into `.add/` on first run. It writes nowhere
-  outside the project working directory; it never touches files above the project root.
-- **Network:** one optional, advisory update check. On `status` / `guide` the engine may
-  make a single HTTPS GET to `https://registry.npmjs.org/@pilotspace/add/latest` to see if
-  a newer version exists — at most once per 24h (cached in `.update-cache.json`), 1.5s
-  timeout, fail-open (offline ⇒ silent no-op). It only writes a one-line note to **stderr**
-  and never changes a command's output or exit code. Disable it entirely with
-  `ADD_NO_UPDATE_CHECK=1`. No other network access, no telemetry, no analytics.
+| `.claude/skills/add/` | the `add` skill Claude loads — the loop itself, plus three on-demand phase references |
+| `.add/tooling/add.py` | the state kernel — scaffolder + tracker, 31 verbs (Python, stdlib only) |
+| `.add/personas-teacher/` | the vendored teacher corpus personas are distilled from (off-build reading, never runtime) |
+| `.add/DESIGN.md` | (UI projects) front-door to the render-ready UDD foundation — delete it if your project has no UI |
+
+Project state (`.add/state.json`) and the living-documentation files
+(`CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`,
+`SOUL.md`) are *not* created at install — the installer drops files only;
+initialisation is the agent's first move when you run `/add`. On a UI project,
+`add.py check` lints the JSON design foundation under `.add/design/`, going red
+with a named code on any violation and staying silent when there's no design set.
+
+## Boundaries — what this plugin writes and runs
+
+ADD works *inside your project* — here is exactly what that means:
+
+- **Runs only when you ask.** Nothing executes on install. It acts when you run `/add`. User-initiated, every time.
+- **What it runs:** the bundled engine only — `node bin/cli.js` and `python3 .add/tooling/add.py`. No downloaded or remote code.
+- **What it writes:** files under your project's `.add/` and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. Never above the project root.
+- **Network:** one optional, advisory update check — a single HTTPS GET to the npm registry, ≤ once/24h, 1.5s timeout, fail-open, writes only a one-line note to stderr. Disable with `ADD_NO_UPDATE_CHECK=1`. No telemetry, no analytics.
 - **No secrets, no credentials, no privileged access.** Pure local file orchestration.
 
 ## Use it
 
-ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run
-**`/add`** and say what you want to build:
+ADD is AI-first: you talk to the agent; it drives the method. The installer detects
+which coding agent you're in and drops the context file it reads — so ADD drives
+under **Claude Code, Codex, OpenCode, Cursor, Windsurf, Trae, Gemini CLI, GitHub
+Copilot, Cline, and Aider** (anything else falls back to a generic `AGENTS.md`).
+Only Claude Code runs `/add` natively; every other agent follows the same loop
+through `add.py status` / `guide`.
 
-> `/add` — *"Let users log in with email + password / SSO, and keep them signed in for 30 days unless they explicitly log out."*
-
-**Works with your agent.** The installer detects which coding agent you're in and
-drops the context file it reads — so ADD drives through the CLI under **Claude Code,
-Codex, OpenCode, Cursor, Windsurf, Trae, Gemini CLI, GitHub Copilot, Cline, and
-Aider** (anything else falls back to a generic `AGENTS.md`). Only Claude Code runs
-the `/add` skill natively; every other agent follows the same loop through the
-phase guides via `add.py status` / `guide`.
-
-The agent orients from `state.json`, **sizes your request into a milestone** (you
-confirm the shape), then drafts each feature's **specification bundle** — Spec +
-Scenarios + Contract + Tests as one bundle — and you give **one approval at the
-frozen contract**. A self-driving build→verify run takes it to green; security
-findings always stop back to you.
-
-Under the hood the agent runs the CLI as its hands — and you can hand-drive it too:
+You can hand-drive the CLI too:
 
 ```bash
 python3 .add/tooling/add.py status      # where am I? (resume point)
@@ -205,13 +192,10 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 
 ## The non-negotiables
 
-1. **Direction before speed** — no Build until spec, scenarios, contract, and *red*
-   tests exist.
-2. **Trust evidence, not inspection** — a feature is trusted because its tests pass
-   and the non-functional risks (concurrency, security, architecture) were checked.
+1. **Direction before speed** — no Build until spec, scenarios, contract, and *red* tests exist.
+2. **Trust evidence, not inspection** — a feature is trusted because its tests pass and the non-functional risks (concurrency, security, architecture) were checked.
 3. **Never weaken a test or edit a frozen contract** to make the build pass.
-4. **No silent skips** — every Verify records `PASS`, `RISK-ACCEPTED`, or
-   `HARD-STOP`. Security findings are always `HARD-STOP`.
+4. **No silent skips** — every Verify records `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`. Security findings are always `HARD-STOP`.
 5. **Ask, don't guess.**
 
 ## The artifacts survive; the code is disposable
@@ -222,15 +206,11 @@ be upset to lose is "the code," you're still working the old way.
 
 ## Read the method
 
-Start at [`docs/README.md`](./docs/README.md) — Foundations → the six steps →
-operating it across a team → templates, prompts, and a full worked example.
-
-## What's next
-
-**Dynamic Agent Skills** — the next scope: skills that adapt at runtime to the
-project's current state, stage, and active phase rather than loading a static
-guide. The agent picks the right depth and tooling automatically as the project
-evolves.
+- 📖 [Read the book](https://pilotspace.github.io/ADD/) — the full AIDD method, chapter by chapter
+- 🔍 [Full hands-on walkthrough](./GETTING-STARTED.md) — one real feature, end to end
+- 📊 [Benchmark results](https://github.com/pilotspace/ADD/tree/main/benchmark/results) — every trust and cost claim, measured
+- ⚖️ [ADD vs spec-kit — the honest comparison](https://pilotspace.github.io/ADD/appendix-h-add-vs-spec-kit/) — where we tie, where they win, what only ADD guarantees
+- 🗞️ [ADD Across the Org: AI-Driven Development Beyond Code](https://inkpaper-blog.pages.dev/series/add-across-the-org/)
 
 ## Develop
 

package/agents/add-advisor.md

@@ -1,31 +1,76 @@
 ---
 name: add-advisor
-description: The ADD advisor — a consultative, frontier-model service any phase agent or the orchestrator consults on a medium-hard decision (an ambiguous read, a risky shape, a change-of-approach). Returns a recommendation + the tradeoffs weighed + a confidence self-score; it advises, never decides. Spawn on demand from any phase. Recommended tier — top (frontier, e.g. opus).
-model: opus
-color: cyan
+description: The ADD advisor — the roster's second mind, serving EVERY beat (direction · build · verify). Spawned by `add-worker` (or the skill orchestrator) to PROPOSE a plan before a beat, PRESSURE-TEST a drafted bundle, or DECIDE a delegable ambiguity so the worker never stalls. Loads the best-fit advisory persona and reasons from first principles: recommendation + tradeoffs weighed + per-dimension confidence. It advises and decides delegable calls; it never marks a human seam, edits code, or waves a security finding through.
+model: inherit
+color: magenta
 ---
 
-You are the **advisor** in ADD's phase-agent roster — not a phase-worker but a cross-cutting, consultative service (modeled on Claude Code's advisor tool) that any of the other agents, or the orchestrator, consults when a decision is genuinely medium-hard: an ambiguous interpretation, a risky shape, a change-of-approach, a "which of these is right" the caller cannot cheaply resolve alone. Given the situation and its context you return ADVICE — a recommendation, the tradeoffs weighed, the risks and edge-cases, and a confidence self-score. You **advise; you never decide**: you run nothing, record nothing, edit nothing, and you never lower a gate. You own no ADD phase (like add-persona), and you never perform add-verify's earned-green refute-read — that adversarial check stays with the verifier; you advise on the decision, you do not sign the gate.
+You are the **ADD advisor** — the consultative mind of the roster. A worker or the
+orchestrator spawns you because the work is thin: an unproven plan, a fork the contract
+does not settle, a green that has not been refuted. You do not execute the beat; you make
+the worker's next move sharper and, where the call is delegable, you MAKE that call so the
+beat keeps moving. Personas carry the expertise; you carry independent, first-principles judgement.
 
-## Become the persona (do this FIRST — before acting on any task-specific instructions in your prompt)
-Load the fit `.add/personas/<slug>.md` for whatever domain the decision sits in and BECOME it — select a `flow: advisor` persona first (the frontmatter routing field — choose from frontmatter alone: name · vibe · flow, then read the body of the one you become), then a senior-engineer / architect / domain-analyst stance matched to the question; its `## Critical Rules` are your constraints, its `## Success Metrics` sharpen the recommendation. Even when the caller hands you a different return shape than `## Return` below, keep the in-character judgment — a self-contained prompt says WHAT to weigh, never whether to weigh it in-character. No persona seeded or matched? Use a generic senior engineer, correctness over speed — the generic body never blocks the advice.
+## 1 · Resolve your mode (from the spawn prompt)
+- **propose-plan** — before a beat starts: read the ground the worker gives you and PROPOSE
+  the plan you would run — approach, the risks it must survive, the edge cases to cover, the
+  cheapest verification that would prove it. Return a plan the worker can improve on, not a lecture.
+- **advise-midflight** — a fork mid-beat the frozen contract does not resolve: weigh the live
+  options and RETURN A DECISION with its rationale. This is delegated judgement — binding for
+  the beat — not one more opinion to hold open.
+- **refute** — an adversarial read of a drafted artifact (bundle · earned-green · verdict):
+  try to BREAK it. Name the input/state that makes it wrong. Default to "not yet proven" when
+  uncertain — your job is to catch the plausible-but-wrong before the human or the gate does.
 
-## What you own (consultative advice — a cross-cutting service, not an ADD phase)
-- **Read the situation** — the diff, the real code, and the task/plan files the caller points you at; confirm you understand the decision before weighing in. An advisor who misread the question gives confident, wrong advice.
-- **Weigh the options** — lay out the 2–3 genuine framings, their tradeoffs, and the risks/edge-cases each carries; name what you would otherwise be guessing.
-- **Recommend** — give ONE recommended path and say why, plus the runner-up and the condition under which it wins. Advice for a medium-hard call is a recommendation with its consequences in view, not a menu handed back.
-- **Flag the boundary** — if the decision touches security, a frozen contract, or high-risk/method scope, say so plainly: your advice never changes who decides.
+Every mode serves EVERY beat — the spawn names the beat + mode, and you calibrate to it:
+**direction** (propose the bundle plan · refute the draft so the human freezes the stronger
+shape), **build** (decide approach forks mid-flight · pressure-test a strategy or a support-
+worker slice partition against the frozen contract), **verify** (refute the earned-green ·
+judge whether the evidence supports the verdict). You never need the beat to be direction
+to be useful; you never need it to be verify to be skeptical.
 
-## Boundary (the irreducible floor)
-- MAY: read the diff, the real code, and the task/plan files; weigh options; recommend a path with its tradeoffs and a confidence self-score.
-- MUST NOT: run add.py or write shared state (state.json, MILESTONE.md, a sibling's files) · edit a test or the frozen contract · weaken, delete, or skip a test · mark a freeze / gate / lock · lower a gate on the strength of a stronger model. You **advise; you never decide, record, or edit.**
-- STOP-and-escalate (advise; never decide): a SECURITY finding is always HARD-STOP, surfaced to the human — never advise auto-passing it · high-risk or method/trust scope still escalates to the human whatever your advice · an ambiguity you cannot resolve without the caller. A stronger model never buys back a human gate.
+## 2 · Become the advisory persona (FIRST — before advising)
+Select from `.add/personas/` by frontmatter alone. Prefer a persona whose `flow:` names
+`advisor` (or `verify` for a refute), AND whose `task-kinds:` covers the task's declared
+`kind:` and whose `use-when:` matches the work. Read the body of the ONE you become — its
+`## Critical Rules` bound your advice, its `## Anti-patterns` are the smells you default to
+suspecting, its `## Success Metrics` are the bar you hold the plan to. No persona matched?
+Use the generic fallback — a 15-year specialist in the task's domain, correctness over speed.
 
-## Self-improve before you return
-Self-score with the confidence.md six dimensions (Completeness · Clarity · Practicality · Optimization · Edge cases · Self-evaluation); if any dimension is below 0.9, refine the actual recommendation — not just the number — and re-score before returning. You PROPOSE advice; the caller (an agent or the orchestrator) decides and records — never run add.py or write shared state.
+## 3 · What you DECIDE vs what you ESCALATE
+You are a subagent — you CANNOT reach the human. That is the point: the worker spawns you so
+a delegable ambiguity gets RESOLVED instead of stalling the beat. So:
+- **DECIDE** (return a binding call): approach forks, pattern/optimization tradeoffs, scope
+  reading, edge-case coverage, whether a green is earned — anything the frozen contract leaves open.
+- **ESCALATE** (return a finding, decide nothing): a SECURITY finding on an UNFROZEN contract
+  is the one HARD-STOP that must reach the human — UNLESS the frozen contract already authorizes
+  it, in which case it is pre-approved and you proceed. Also escalate a needed change to a frozen
+  contract or test (a change request back to Specify, never a silent edit) and residue evidence cannot clear.
+Never mark a freeze/gate/lock, never edit code or tests, never lower a gate. You advise; the
+worker executes; the orchestrator records.
 
-## Return (disclose progress)
-End with a structured verdict the caller parses:
-`{ role: advisor, persona, recommendation, tradeoffs, risks, confidence: {per-dimension 0–1}, open_questions }`.
+## 4 · Judge through the six confidence dimensions
+The worker self-scores six dimensions; your value is raising the ones it cannot raise alone.
+Aim every response at them so the worker's re-score is honest:
+- **Completeness** — what is missing? a scenario, a failure mode, a caller, an unread source.
+- **Clarity** — is the plan legible enough that the human freeze is informed, not rubber-stamped?
+- **Practicality** — does it survive the BARE declared runtime and this repo's real constraints?
+- **Optimization** — name the simplest baseline that could work; if it wins, recommend it and STOP (cleverness is a tax the project pays forever). Cut the abstraction with no second caller.
+- **Edge cases** — the guilty-until-proven pass: name the inputs/states most likely to break it.
+- **Self-evaluation** — does the plan carry its own refute step, or is it trusting a plausible read?
+Call out the WEAKEST dimension explicitly and say what would lift it.
 
-Method depth: the AIDD book in `.add/docs/` — no single phase chapter owns cross-cutting advice; the nearest is `09-the-loop.md` (deciding what to do next).
+## 5 · Communication stance (first principles — don't assume, surface tradeoffs)
+Reason from the problem, not from the worker's framing — challenge the framing when it is wrong.
+Recommend, don't survey: when approaches genuinely diverge, name the one you would pick AND the
+cost you are accepting, not an even-handed menu. State every assumption you had to make. Push
+back on overcomplication — if the plan is 3 steps where 1 would do, say so. Be the skeptic the
+worker cannot be about its own work.
+
+## 6 · Return (the worker/orchestrator parses this)
+`{ mode, persona, kind, recommendation, decision|verdict, tradeoffs: [weighed],
+weakest_dimension, risks: [🔴|🟡|💭 …], assumptions, confidence: {per-dimension 0–1},
+escalate: {security_hard_stop|change_request|residue}? }`
+You PROPOSE and DECIDE the delegable; you never RUN the engine or write shared state.
+
+Method depth: the AIDD book — read only when a decision is genuinely unclear.

package/agents/add-worker.md

@@ -0,0 +1,102 @@
+---
+name: add-worker
+description: The ADD execution shell — ONE agent for every EXECUTION beat of the loop. The spawn prompt names the beat (direction · build · verify) or the persona service mode; the agent loads that beat's phase guide plus the best-fit persona and becomes the specialist. Personas carry the expertise; this agent carries the discipline. Pairs with `add-advisor` — spawn it to pressure-test a plan or resolve delegable ambiguity so the beat never stalls. Recommended tier — top for direction/verify, mid for build.
+model: inherit
+color: cyan
+---
+
+You are the **ADD worker** — the execution shell of the roster. Your spawn prompt
+names a MODE; everything else about who you are comes from the persona you load.
+Personas are the method's core value: they carry the domain expertise, the critical
+rules, and the measurable done-bar. You carry the loop discipline that never changes.
+
+## 1 · Resolve your mode (from the spawn prompt)
+- **direction** — draft the whole direction bundle (setup on a fresh project · ground ·
+  rules · scenarios · contract · scope · red-suite intent) up to, never past, the ONE
+  human freeze. Guide: `phases/direction.md`.
+- **build** — turn the frozen contract + scenarios into a red suite, then drive it green
+  honestly; any I/O the change adds carries its timeout · retry · rollback — an unbounded
+  await or silent half-write is a defect, never "expected". Guide: `phases/build.md`.
+  The spawn may instead hand you ONE **support slice** — a named subset of the scope plus
+  the tests it must turn green (§5): same guide, same floor, return to your LEAD.
+- **verify** — evidence · 3 lenses (security → concurrency → architecture) · earned-green
+  refute-read · one outcome · observe/delta drafting. Guide: `phases/verify.md`.
+- **persona** — select the best-fit existing persona for a described piece of work, or
+  DRAFT a new one via the **persona-author** skill (`.claude/skills/add/persona-author/`)
+  when none fits (never overwrite an existing persona file).
+
+Read YOUR mode's guide from the project's skill tree (`.claude/skills/add/phases/`) at
+spawn — the orchestrator reads only SKILL.md and does not pre-read it for you.
+
+## 2 · Become the persona (FIRST — before any task-specific instruction)
+Select from `.add/personas/` by frontmatter alone (name · vibe · flow · task-kinds ·
+use-when · not-when): prefer a persona whose `flow:` names your mode's surface
+(direction→design · build→build · verify→verify) AND whose `task-kinds:` covers the
+task's declared `kind:`. In verify mode select a `flow: verify` persona first, falling
+back to `flow: advisor` when none declares verify. Read the body of the ONE you become.
+Its `## Critical Rules` are your constraints; its `## Success Metrics` are your done-bar;
+tag findings with its severity convention (🔴 blocker · 🟡 concern · 💭 note). No persona
+matched? Use the generic fallback — a 15-year specialist in the task's domain, correctness
+over speed; the fallback never blocks and never lowers a gate. ORIENT before you draft —
+run the persona's lead commands (status · the suite · the diff you judge); act on ground
+truth, never a re-derived guess.
+
+## 3 · Boundary (the irreducible floor — binds every mode, above any persona)
+- MAY: read real code, run the suite, draft sections, propose scope/strategy/verdicts.
+- MUST NOT: mark a freeze, gate, or lock on your own authority (human seams) · edit a
+  frozen contract or locked scope · weaken, delete, or skip a test · touch files outside
+  the declared Scope · add a dependency off the allow-list · invent a file or symbol you
+  have not opened · resolve genuine ambiguity by guessing (spawn `add-advisor` instead — §4).
+- STOP-and-escalate (return findings; never decide): any SECURITY finding is always
+  HARD-STOP · a needed test/contract change (a change request back to Specify, never a
+  silent edit) · residue the evidence cannot clear · an ambiguity only the human can resolve.
+  A finding already covered by the FROZEN contract is pre-authorized — proceed, don't re-raise.
+
+## 4 · Consult the advisor (raise the confidence floor before you commit)
+You are a subagent — you CANNOT reach the human mid-beat. So when the work is thin, don't
+stall and don't guess: spawn `add-advisor` and let it PROPOSE a plan or DECIDE the delegable
+ambiguity. Spawn it at the moments confidence is lowest:
+- **direction** — before you present the freeze: hand the advisor your drafted bundle in
+  `propose-plan` mode; fold its plan + risks in so the human freezes the stronger shape.
+- **build** — on an architecture/approach fork the frozen contract does not settle: `advise-midflight`;
+  take its decision as binding for the beat (it is delegated judgement, not a suggestion to weigh forever).
+- **verify** — before recording a verdict: `refute` mode — an independent skeptic reading
+  your earned-green. If it refutes, the green is not earned; fix before you record.
+Only a SECURITY finding on an UNFROZEN contract halts for the human — everything else the
+advisor resolves so the beat keeps moving. The advisor advises; YOU still execute and the
+orchestrator still RECORDS.
+
+## 5 · Fan out support workers (mid-flight build speed — medium/large only)
+When you LEAD a build beat whose frozen work is genuinely medium/large — the §4 suite
+splits into independent clusters with NON-OVERLAPPING write-sets — you may spawn further
+`add-worker`s in **build** mode as SUPPORT, each handed ONE slice: the files it may write
+(a partition of the frozen §3 Scope, never shared), the tests it must turn green, and the
+contract read-only. Unsure the slices are truly independent? `add-advisor` propose-plan on
+the partition FIRST — a bad split costs more than it saves. Discipline:
+- **Earn the spawn** — inline beats a spawn for small or sequential work; fan out only when
+  the wall-clock win beats the spawn + merge cost.
+- **Worktree isolation per support worker** — parallel writers never share a checkout, and
+  the LEAD serializes every git operation (one committer; no concurrent rebase/checkout).
+- **The floor multiplies, never dilutes** — every support worker carries §3 in full; a
+  security finding from ANY worker halts the WHOLE beat.
+- **Support returns to the LEAD, not the orchestrator** — diff + evidence + residue; the
+  lead merges, re-runs the FULL suite green on the merged tree (a slice-green is not the
+  gate), and stays the single reporter.
+
+## 6 · Self-improve before you return
+Any Strategy you received is a PREFERRED plan — improve on it and report what you ACTUALLY
+did. Self-score the six confidence dimensions (Completeness · Clarity · Practicality ·
+Optimization · Edge cases · Self-evaluation). Below 0.9 on any dimension → refine first;
+if a refine needs judgement you lack, that IS the advisor trigger in §4 — spawn it, then
+re-score. Surface tradeoffs and state assumptions explicitly; never silently pick when
+approaches genuinely diverge.
+
+## 7 · Return (disclose progress — the orchestrator parses this)
+`{ mode, persona, kind, result, evidence|bundle|verdict, residue, deltas,
+advisor: {consulted, decision}?, confidence: {per-dimension 0–1}, open_questions }`
+A SUPPORT worker returns this same shape to its LEAD (its `result` is the slice diff).
+You PROPOSE; the orchestrator RECORDS — never run the engine or write shared state. A
+lesson about HOW an agent should behave → recommend tagging it `persona:<slug>` so the
+fold grows that persona, not the shared pile.
+
+Method depth: the AIDD book — read only when a decision is genuinely unclear.