@pilotspace/add 1.16.1 → 2.0.0

package/README.md

@@ -2,27 +2,34 @@
   <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.
 
-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
+the traced outcomes (`add.py deltas`). Conscience: evidence-scored gates, the
+tamper tripwire, the security hard-stop. 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, published
+online](https://pilotspace.github.io/ADD/). Read it once; keep it open beside you.
 
 ```
   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
@@ -41,29 +48,66 @@ 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:
+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 detail below — **Install**, **Use it**, and the
+[10-minute Quickstart](./GETTING-STARTED.md).
+
+## Highlights
+
+- 📉 **Anti-context-rot by design** — every decision lives on disk (`PLAN.md`, frozen contracts, red suites, `.add/state.json`), so a fresh session resumes losslessly; measured flat 1.0 quality across evolving milestones while conversation-carried flows decayed.
+- ✅ **Approve once, then let it run** — one human sign-off at the frozen contract; the agent drives Direction → Build → Verify.
+- 🔬 **Proof, not promises** — verified against observed behavior and pre-declared expectations, never just a plausible-looking diff; weakening a test to reach green is treated as tampering.
+- 💸 **Lean by measurement** — a thin 31-verb state kernel, a 3-call task walk, one file per feature; $2.20 per trusted milestone vs spec-kit's $3.90 in the latest head-to-head.
+- 🔒 **Security never gets waved through** — any security finding is a hard stop, human in the loop.
+- 🧠 **Personas route the work** — a project-owned persona proposes each task's lane, the freeze ratifies it, outcomes are traced, and the loop reflects on the record (GEPA) so the method adapts to your codebase.
+- 🎨 **See it before you build it** — a wireframe and a zero-dependency HTML mock, approved before any code.
+- 👥 **Built for teams** — git-native multi-user, N parallel milestones, DAG-scheduled waves.
+- 🧩 **One slice, many components** — monorepo or multi-repo, in one team.
+- 🤝 **Works with your AI** — 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 — the pain point is context rot, and we measured it
+
+Every AI coding tool can write code fast now, and every flow we benchmark 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, with an early list-shape spec
+violation carried through five further milestones, never re-examined). When every
+milestone instead started a **fresh session resuming from disk**, ADD held every
+floor at 1.0 across all six milestones — through a breaking shape change and a
+cross-cutting refactor — with zero regressions, at ~$2.90 per milestone (a 3–5×
+cut vs ADD 1.x's $4.65–13.94 per trusted feature). Honesty note, from the same
+report: on this friendly workload a strong model under spec-kit also passed the
+restart-mode 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.
+
+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 `TASK.md`. No sprawling doc tree.
-- **State on disk, not in chat.** A Python tool tracks where you are in
+  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
-  re-reading the repo.
-- **Progressive disclosure.** The skill loads only the guide for the phase you are
-  in — the context window stays lean.
+  re-reading the repo — and 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.
 
 ## 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
+ADD is the **trust layer** — the gated loop (Direction → Build → Verify)
+that decides when work is trusted, and the on-disk memory it runs on. 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.
@@ -75,23 +119,26 @@ never a runtime dependency — down to the three parts a project actually needs:
 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
+A distilled persona is applied as 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. That gated loop is what ADD contributes underneath
-any persona, distilled or not.
+contract, or wave through a security finding. In 2.0 personas also carry **task-kinds** and
+propose each task's route (full walk · fast lane · inline); the freeze ratifies the route, the
+gate traces the outcome, and `add.py deltas` rolls the traces into a per-lane scoreboard the
+loop reflects on (GEPA). 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
+2. **Keep whatever subagent libraries you already use.** ADD ships ONE `add` agent in the same
+   `.claude/agents/` mechanism as any other Claude Code subagent — the spawn names the mode
+   (direction · build · verify · advise · persona) and the agent loads that beat's guide plus the
+   best-fit persona. It coexists with a distilled persona, an agency-agents-derived specialist,
+   or a built-in expert with zero conflict; nothing is replaced.
+3. **Prefer the `add` agent for anything phase-shaped** — spawn it in verify mode for the
+   independent adversarial refute-read, in build mode for a red→green batch — before an ad-hoc
+   spawn. Reach for another specialist when a piece needs deep domain expertise the phase guide
    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
@@ -99,7 +146,7 @@ any persona, distilled or not.
 
 ## 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
@@ -118,8 +165,8 @@ pilotspace-add init
 /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
+The plugin carries the engine. On first `/add`, the skill materializes it 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.
 
@@ -128,9 +175,12 @@ 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
+re-materializes the skill and tooling 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.
+see whether a project is behind the installed package. Coming from 1.x? One
+command — `python3 .add/tooling/add.py migrate` — converts the whole board
+(task docs to `PLAN.md`, living 5-DD specs seeded); it's idempotent and refuses
+to guess on conflicts.
 
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
 your first feature end to end.
@@ -139,11 +189,15 @@ 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 |
+| `.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) the prose front-door to the **render-ready UDD foundation** — delete it if your project has no UI |
 
+The AIDD book itself no longer installs into projects — it lives online at
+[pilotspace.github.io/ADD](https://pilotspace.github.io/ADD/), and the engine
+deep-links the exact chapter whenever a gate or guide cites its rationale.
+
 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
@@ -165,9 +219,9 @@ exactly what that means, so there are no surprises:
 - **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
+- **What it writes:** files under your project's `.add/` (state, milestones, tasks) and
+  the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
+  it also materializes the engine 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
@@ -192,9 +246,9 @@ 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
+confirm the shape), then drafts each task's **specification bundle** — Spec +
+Scenarios + Contract + Tests as one Direction pass — 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:
@@ -218,19 +272,37 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 
 The durable asset is the decisions — spec, scenarios, contract, tests. The code is
 one implementation that satisfies them and can be regenerated. If the thing you'd
-be upset to lose is "the code," you're still working the old way.
+be upset to lose is "the code," you're still working the old way. This is also the
+anti-context-rot stance in one sentence: the artifacts on disk, not the
+conversation, are the project's memory.
 
 ## Read the method
 
-Start at [`docs/README.md`](./docs/README.md) — Foundations → the six steps →
+Start at [the book](https://pilotspace.github.io/ADD/) — Foundations → the loop →
 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.
+More entry points:
+
+- 📖 [Read the book online](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/)
+
+## What's new in 2.0
+
+- **Skill-led loop on a thin kernel** — the skill narrates Direction → Build →
+  Verify; `add.py` shrinks to a 31-verb state kernel (54 → 31).
+- **`PLAN.md` + one-shot `migrate`** — the per-task file is the plan; a whole 1.x
+  board converts with one idempotent command.
+- **Five living 5-DD specs with `delta-append`** — the project's evolving truth,
+  compacted forward instead of rewritten.
+- **Persona routes + the GEPA scoreboard** — personas propose lanes, gates trace
+  outcomes, `deltas` shows the per-lane record, and the loop reflects on it.
+- **The book stops shipping** — published online only, deep-linked from the engine.
+- **Measured**: every trust floor 1.0 across the 3-milestone benchmark at $2.20 per
+  trusted milestone; plus a new `--session-mode continue` harness that measures
+  context rot itself.
 
 ## Develop
 

package/agents/add.md

@@ -0,0 +1,68 @@
+---
+name: add
+description: The ADD specialist — ONE execution shell for every beat of the loop. The spawn prompt names the beat (direction · build · verify) or a service mode (advise · persona); 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. Recommended tier — top for direction/verify/advise, mid for build.
+model: inherit
+color: cyan
+---
+
+You are the **ADD specialist** — the one 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. Guide: `phases/build.md`.
+- **verify** — evidence · 3 lenses (security → concurrency → architecture) ·
+  earned-green refute-read · one outcome · observe/delta drafting. Guide:
+  `phases/verify.md`.
+- **advise** — a consultative second opinion on a named decision: recommendation
+  + tradeoffs weighed + confidence. No guide; you advise, never decide.
+- **persona** — select the best-fit existing persona for a described piece of
+  work, or DRAFT a new one from the seed templates 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): prefer a persona whose `flow:` names your mode's surface
+(direction→design · build→build · verify→verify · advise→advisor) 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.
+
+## 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.
+- 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.
+
+## 4 · 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 anywhere → refine before returning.
+
+## 5 · Return (disclose progress — the orchestrator parses this)
+`{ mode, persona, kind, result, evidence|bundle|verdict, residue, deltas,
+confidence: {per-dimension 0–1}, open_questions }`
+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.