fix: stop spawning thirteen agents that do not exist

CHANGELOG.md

@@ -100,6 +100,45 @@ hint", which reads as *leave it in place* — while its presence is exactly what
 It is a template-enforcement marker: **delete it once you have written the section it names.** That
 deletion is the completeness contract, and nothing had ever said so.
 
+### Thirteen agents that never existed (#29)
+
+Phases 7, 8 and 9 instructed Claude to spawn seven subagents by name. **Six did not exist.** The
+reference documents were worse: `references/agent-roster.md` — which calls itself "the
+authoritative reference for agent orchestration decisions" — and `docs/agents.md` between them
+presented **thirteen** non-existent agents as usable, six of those in the Build-loop table, the
+most-exercised part of the product. `SKILL.md`, the file Claude actually reads, carried the same
+list plus a worked `Agent(backend-architect, ...)` example.
+
+**A spawn that resolves to nothing does not raise and does not warn.** The phase carries on as
+though the work were done. A team ran Phase 7, the definition said the API documentation was being
+generated, and `api-docs.md` never appeared.
+
+The root cause was a single false claim: `docs/agents.md` listed these under **"Built-in Claude
+Code subagents — Claude Code runtime — 13+"**. They were never runtime built-ins. Believing they
+came free is why nobody built them. Only `Explore` and `Plan` come from the runtime; everything
+else ships in `agents/` (13) or `harness/agents/` (6).
+
+**The fix follows what already worked.** Phases 0–3 and the Build loop spawn nothing via
+`Agent(...)` and never did — they describe their work as steps. Phases 7–9 now do the same:
+
+| Was delegated to a non-existent agent | Now |
+|---|---|
+| README + API docs (`doc-updater`, `backend-architect`) | Written directly — `07-documentation.md` Steps 1–2 |
+| Staging/production deploy (`devops-automator`) | Executed directly from `RUNBOOK.md` — `08-deployment.md` Steps 2, 4 |
+| Smoke tests (`e2e-runner`) | Executed directly — `08-deployment.md` Step 3 |
+| Performance baseline (`performance-benchmarker`) | Measured directly, before any threshold is set — `09-monitoring.md` Step 1 |
+| Feedback synthesis (`feedback-synthesizer`) | Part of the retrospective — `09-monitoring.md` Step 5 |
+| Tests, API work, spikes (`test-writer-fixer`, `api-tester`, `rapid-prototyper`, `tdd-guide`) | The `test-writer` / `api-pattern` skills and `/sdlc-spike` |
+
+`build-error-resolver` spawns are kept — it genuinely ships. The distinction now stated in the docs
+is that a **skill** runs in the main context with the surrounding work in view, which is what
+authoring needs, while an **agent** starts cold, which is what reviewing needs. That, not a persona
+name, is what decides whether something should be delegated.
+
+`docs/phase-lifecycle.md` had said "No custom SDLC agents are spawned during Documentation /
+Deployment / Monitoring" the whole time. It was right, and nothing reconciled it against the phase
+files that disagreed.
+
 ### The rails that catch the next one
 
 `scripts/tests/test_registry_docs_consistency.py` asserts that:
@@ -112,6 +151,14 @@ deletion is the completeness contract, and nothing had ever said so.
 - all three docs that list Gate 2's placeholder markers match `check_gates.PLACEHOLDER_MARKERS`,
   with the specific `[bracket text]` false claim kept as a named regression
 
+`scripts/tests/test_agent_references.py` asserts that every agent named in an `Agent(...)` spawn or
+an agent-table column — across `phases/`, `SKILL.md`, all of `docs/` and all of `references/` —
+ships in `agents/` or `harness/agents/`, or appears on an explicit allowlist of Claude Code
+built-ins and sibling-plugin agents. It parses the tables rather than pattern-matching backticks,
+so phase slugs and spec statuses are not mistaken for agent names. Its file list is derived by glob:
+the first pass at this fix corrected two documents by hand and left the same claims standing in
+three others, which is exactly how the original drift happened.
+
 Every check was verified by reintroducing the original defect and confirming it fails — a guard
 that has never failed is a configuration, not a control.
 

SKILL.md

@@ -237,81 +237,75 @@ An index page at `.sdlc/reports/index.html` MUST exist. It serves as the single
 
 All reports are written to `.sdlc/reports/`:
 - `index.html` -- project dashboard (single entry point)
-- `phase00-visual.html`, `phase01-visual.html`, ..., `build-visual.html`, ..., `close-visual.html` -- phase summary reports (numeric phases use `phaseNN-`; the Build loop and Close use their `build` / `close` slug)
-- `phase00-<artifact>.html`, `phase01-<artifact>.html`, ... -- artifact sub-pages
-- Additional named reports (e.g., `architecture-diagrams.html`, `phase03-section-review.html`) are encouraged alongside the numbered report
+- `00-discovery-visual.html`, `01-requirements-visual.html`, ..., `build-visual.html`, ..., `close-visual.html` -- phase summary reports. **Every phase uses its registry slug**, including the non-numeric `build` and `close`
+- `00-discovery-<artifact>.html`, `01-requirements-<artifact>.html`, ... -- artifact sub-pages
+- Additional named reports (e.g., `architecture-diagrams.html`, `03-foundation-section-review.html`) are encouraged alongside the phase report
 
 ## Agent Orchestration Protocol
 
-Claude MUST use the Agent tool to spawn specialized subagents rather than doing all work inline. The Agent tool produces better results for non-trivial tasks: subagents have focused context, specialized instructions, and independent execution. This is not optional.
+Claude uses the Agent tool where a subagent buys something real: a perspective that did not write
+the work, or a bounded search that would otherwise flood the main context. **Most phase work is not
+delegated** — it is performed directly, as the phase definitions describe.
 
-See `references/agent-roster.md` for the full phase-by-phase mapping with conditions, parallel groups, and background policy.
+**Only spawn an agent that exists.** A spawn that resolves to nothing does not raise and does not
+warn; the phase simply carries on as though the work were done. Every name below ships in
+`agents/` or `harness/agents/`, or is a Claude Code built-in. See `references/agent-roster.md` for
+the full mapping, and `scripts/tests/test_agent_references.py` for the check that keeps it honest.
 
 ### Mandatory Spawns (No Exceptions)
 
 | Trigger | Agent | Behavior |
 |---------|-------|----------|
 | Build or compilation fails | `build-error-resolver` | Spawn immediately. Do not attempt manual fixes first. |
 | Code touches auth, payments, secrets, or PII | `security-reviewer` | Foreground. STOP on CRITICAL/HIGH findings. |
-| Build loop + profile requires TDD | `tdd-guide` | Spawn BEFORE writing any code for the change. |
-| Per-change check in the Build loop | `code-reviewer` + `security-reviewer` | Spawn both in a single message (parallel, foreground). |
 | A change in the Build loop completes | `section-evaluator` | Foreground, blocking. FAIL verdict = fix before proceeding. |
-| Build loop with independent changes | Domain-specific agents | Spawn in parallel (single message) for non-dependent changes. |
-| Gate check fails unexpectedly | `Explore` | Investigate root cause before attempting fixes. |
+| Gate check fails unexpectedly | `Explore` or `debugger` | Investigate root cause before attempting fixes. |
 
 ### Phase-by-Phase Agent Roster (Summary)
 
 | Phase | Primary Agents | Conditional Agents |
 |-------|---------------|--------------------|
-| 0 Discovery | — | `Explore` (existing codebase) |
-| 1 Requirements | — | `Explore`, `feedback-synthesizer` |
-| 2 Design | `architect` | `backend-architect`, `frontend-developer`, `security-reviewer` |
-| 3 Foundation | `deep-plan:section-writer` | `Plan`, `Explore` |
-| build Build Loop | Domain agents per change | `tdd-guide`, `section-evaluator`, `code-reviewer`, `security-reviewer`, `build-error-resolver`, `test-writer-fixer`, `e2e-runner`, `api-tester`, `performance-benchmarker`, `refactor-cleaner` (background) |
-| 7 Documentation | `doc-updater` | `backend-architect` (API docs) |
-| 8 Deployment | `devops-automator` | `e2e-runner` (smoke tests), `build-error-resolver` |
-| 9 Monitoring | — | `performance-benchmarker`, `feedback-synthesizer` |
-| close Close & Transfer | — | `doc-updater`, `feedback-synthesizer` |
+| 0 Discovery | — | `Explore`, `discovery-analyst` |
+| 1 Requirements | — | `Explore`, `requirements-analyst`, `feature-architect`, `bizreq-analyst` |
+| 2 Design | `architect` | `security-reviewer`, `compliance-checker`, `data-analyst`, `visual-designer`, `conversation-designer`, `multi-reviewer` |
+| 3 Foundation | `deep-plan:section-writer` | `Plan`, `planner`, `Explore` |
+| build Build Loop | `section-evaluator` | `grader`, `security-reviewer`, `multi-reviewer`, `build-error-resolver`, `debugger`, `gate-repair`, `deep-implement:code-reviewer` (background) |
+| 7 Documentation | — | `Explore` (ADR gap analysis) |
+| 8 Deployment | — | `build-error-resolver` |
+| 9 Monitoring | — | none |
+| close Close & Transfer | — | none |
+
+**Building is not delegated to a domain agent.** The Delegate beat is Claude building from an
+approved plan under the rails; the checking ladder is what makes that safe, not a specialist
+persona. Authoring work uses **skills** — `test-writer`, `api-pattern`, `spec-writer`, `pr-writer`,
+`eval-builder`, `diagnose` — because a skill runs in the main context with the surrounding work in
+view. Agents serve the Discern beat, where starting cold is the point.
 
 ### Parallel Execution Rules
 
 **Use a single message with multiple Agent tool calls when:**
-- Two or more Build loop changes have no dependency on each other (e.g., backend + frontend changes).
-- A per-change check fires in the Build loop — always launch `code-reviewer` and `security-reviewer` simultaneously.
-- Testing in the Build loop — launch `test-writer-fixer`, `e2e-runner`, and `api-tester` simultaneously when all apply.
+- A feature spans a web surface and a voice/chat surface — `visual-designer` and `conversation-designer` author different specs and do not conflict.
 - Phase 3 (Foundation) has multiple independent section plans to generate.
+- Several independent review lenses apply to the same change.
 
 **Use sequential Agent calls when:**
-- One agent's output is the input to the next (e.g., `tdd-guide` must complete before the implementation agent starts).
+- One agent's output is the input to the next.
 - A security CRITICAL/HIGH finding must be resolved before proceeding.
 - A build failure must be fixed before continuing.
 
-**Pattern for parallel change implementation:**
+**Pattern for parallel section planning:**
 ```
 # Single message — two Agent tool calls fire simultaneously:
-Agent(backend-architect, "Implement SECTION-002 per .sdlc/artifacts/03-foundation/section-plans/SECTION-002.md")
-Agent(frontend-developer, "Implement SECTION-003 per .sdlc/artifacts/03-foundation/section-plans/SECTION-003.md")
+Agent(deep-plan:section-writer, "Generate the section plan for SECTION-002 per .sdlc/artifacts/03-foundation/")
+Agent(deep-plan:section-writer, "Generate the section plan for SECTION-003 per .sdlc/artifacts/03-foundation/")
 ```
 
 ### Background Agents
 
 Run with `run_in_background: true` (non-blocking):
-- `doc-updater` — documentation updates during the Build loop
-- `refactor-cleaner` — dead code cleanup during the Build loop
-- `code-reviewer` — rolling per-change review in the Build loop
 - `deep-implement:code-reviewer` — diff review against section plans
 
-Never background: security reviews, build error resolution, or any work producing phase gate artifacts.
-
-### Domain Agent Selection (Build loop)
-
-| Change domain | Primary agent |
-|----------------|---------------|
-| Python / C# / server-side logic | `backend-architect` |
-| HTML / CSS / Angular / React | `frontend-developer` |
-| CI/CD / cloud infrastructure | `devops-automator` |
-| Spike / proof-of-concept | `rapid-prototyper` |
-| Any change with auth / payments / secrets | + `security-reviewer` (foreground) |
+Never background: security reviews, build error resolution, spec/section evaluation, or any work producing phase gate artifacts.
 
 ---