fix: stop spawning thirteen agents that do not exist

[MCKRUZ]

Closes #29.

Stacked on #39 (→ #38 → #37). Merge in order; GitHub retargets automatically.

Bigger than filed

I filed this as six phantom agents in phases 7–9. The real count across the repo is thirteen:

api-tester, backend-architect, devops-automator, doc-updater, e2e-runner, feedback-synthesizer, frontend-developer, performance-benchmarker, rapid-prototyper, refactor-cleaner, tdd-guide, test-writer-fixer, and code-reviewer as a claimed built-in.

Six of them sit in the Build-loop table — the most-exercised part of the product. references/agent-roster.md calls itself "the authoritative reference for agent orchestration decisions" and two-thirds of what it listed was fiction. SKILL.md — the file Claude actually reads — carried the same list plus a worked Agent(backend-architect, ...) example.

Why it does real damage

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 runs Phase 7, the definition says the API documentation is being generated, and api-docs.md never appears.

The root cause

One false claim in docs/agents.md:

| Built-in Claude Code subagents | Claude Code runtime | 13+ | code-reviewer, security-reviewer, backend-architect, Explore |

They were never runtime built-ins. Only Explore and Plan come from the runtime; security-reviewer ships in harness/agents/. Believing the rest came free is almost certainly why nobody ever built them.

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, and they work. Phases 7–9 were the outlier.

Was delegated to a non-existent agent	Now
README + API docs	Written directly — 07-documentation.md Steps 1–2
Staging/production deploy	Executed from RUNBOOK.md — 08-deployment.md Steps 2, 4
Smoke tests	Executed directly — Step 3
Performance baseline	Measured directly, before any threshold is set — 09-monitoring.md Step 1
Feedback synthesis	Part of the retrospective — Step 5
Tests / API work / spikes	The test-writer and api-pattern skills, and /sdlc-spike

build-error-resolver spawns are kept — it genuinely ships.

The docs now state the principle that decides this: a skill runs in the main context with the surrounding work in view, which is what authoring needs; an agent starts cold, which is what reviewing needs. That, not a persona name, is the test for whether to delegate.

Corroboration: docs/phase-lifecycle.md said "No custom SDLC agents are spawned during Documentation / Deployment / Monitoring" the whole time. It was right. Nothing ever reconciled it against the phase files that disagreed.

Also here

Completes #36's sweep — SKILL.md still documented the phaseNN- report convention, which the earlier pass missed because its glob covered phases/, docs/ and commands/ but not SKILL.md or references/. Both guards are now glob-driven over the whole repo.

Test plan

• Full suite: 574 passed, 6 skipped
• Zero phantom references remain outside CHANGELOG.md (history) and harness/agents/README.md (a deliberate catalogue of external agents a team may optionally pull — left as-is)
• New guard mutation-tested twice: once with a phantom Agent() spawn, once with a phantom roster row, and again against SKILL.md after the parser was tightened
• Guard parses agent-table columns rather than matching backticks — the naive version produced 10 false positives on phase slugs (build, close) and spec statuses

Note for review

This rewrites prose in five documents including SKILL.md. The mechanical claims are all test-enforced now, but the wording deserves your eye — particularly the skill-versus-agent framing in SKILL.md and references/agent-roster.md, since that is new guidance rather than a correction.

🤖 Generated with Claude Code