A stack of nested loops
with explicit exit criteria.
The pipeline runs as the main Claude Code session. Each phase has a contract; each loop has an exit checklist; each gate is enforced by a hook that exit-2's until evidence is real. The README is the source of truth; this page is the visual map.
Trace a run, phase by phase
A live signal travels the spine of the pipeline. Hover any phase to inspect its owners, the artifact it emits, and the contract that must be true before the next phase fires.
100%-coverage hard gate. 12-condition exit checklist.
- 01openspec validate --all --strict must be valid — independently re-run by the Stop hook (v3.9.2) so a skipped or mis-reported verdict cannot pass.
- 02Every requirement has ≥ 1 measurable scenario; every both-layer requirement has an explicit front-to-back integration criterion.
- 03Reuse decisions cite real files/symbols in CODEBASE_MAP; no duplicate capabilities.
- 04Phase 2 cannot start until all 12 conditions hold.
10 phases at a glance
100%-coverage hard gate. 12-condition exit checklist.
- 01openspec validate --all --strict must be valid — independently re-run by the Stop hook (v3.9.2) so a skipped or mis-reported verdict cannot pass.
- 02Every requirement has ≥ 1 measurable scenario; every both-layer requirement has an explicit front-to-back integration criterion.
- 03Reuse decisions cite real files/symbols in CODEBASE_MAP; no duplicate capabilities.
- 04Phase 2 cannot start until all 12 conditions hold.
Every phase, full detail
Build CODEBASE_MAP, ROUTE_MAP, DESIGN_MAP, INTEGRATION_MAP.
- ›Cartographer + route-mapper produce per-codebase maps.
- ›3 codebase-map-reviewer agents argue in parallel until all return ok — no iteration cap (v3.8.0 unbounded solving).
- ›Integration mapping converges 3 explorers → master-synthesizer.
- ›Freshness short-circuit: skip when last_mapped ≥ git head.
- ›v3.33.0: a claude.ai/design/p/<id> link (or a `claude_design` MCP mention) is auto-detected here and the whole design project is fetched natively — no zip download.
Normalize OpenSpec / Superpowers / plain markdown briefs.
- ›Orchestrator inspects the requirements folder and converts to one internal contract.
- ›Initializes coverage-map.json.
- ›Phase 0.1 (v2.18.0): consults the per-codebase discipline registry and auto-applies safe disciplines; routes the rest as Solution Requirements.
- ›Phase 0c (v3.5.0): dispatches the data-engineering-exploration pipeline when data-plane work (dbt, Airflow, Snowflake, Kafka, feature-stores) is detected.
100%-coverage hard gate. 12-condition exit checklist.
- ›openspec validate --all --strict must be valid — independently re-run by the Stop hook (v3.9.2) so a skipped or mis-reported verdict cannot pass.
- ›Every requirement has ≥ 1 measurable scenario; every both-layer requirement has an explicit front-to-back integration criterion.
- ›Reuse decisions cite real files/symbols in CODEBASE_MAP; no duplicate capabilities.
- ›Phase 2 cannot start until all 12 conditions hold.
Long-lived named teammates with their own 1M-context windows.
- ›Claude Code Agent Teams primitive by default (Lead + N teammates, shared task list, SendMessage for direct messaging).
- ›Falls back to ephemeral subagents when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is missing or Claude Code < 2.1.32 — mode recorded in intake-state.json.
- ›v3.30.0: every spawn brief carries a mandatory `[CT6-TEAMMATE <name> RUN <id>]` first line so the sticky run-arm recognizes teammate sessions.
Hook-enforced. Evidence schema v7 — 17 fields + independent_review.
- ›PostToolUse(TaskUpdate) exit-2's until every field validates.
- ›5 VAO fields (oracle_match / baseline_clean / no_fake_data / adversarial / skill_invocation_audit) each block on fail.
- ›Independent reviewer ≠ teammate. 3 rejections → escalation handoff.
- ›23 Layer-3 verification tools — v3.47.0 `verify-check-can-fail` (a cited output must prove it could have failed: pytest `collected 0 items` or a tsc run over zero files is refused), v3.55.0 `verify-frontend-e2e` as a hard loop-exit gate, and v3.59.0 `verify-claim-instrument-binding` (agent-authored claims only; a mutation whose sha256 shows the file never changed is refused). v3.65.0 adds `verify-suite-manifest` with default-deny production safety.
- ›v3.62.0 review-evidence binding: evidence carries `task_subject`, so a manifest pointed at a reused integer id can no longer ride another lane's clean review — mismatched evidence is invisible, and the refusal quotes the foreign binding.
- ›v3.44.0 `frontend_impact_e2e_review`: when the diff carries frontend impact, a real-frontend end-to-end verdict is MANDATORY — a passing unit test can never open the gate.
- ›v3.47.0 unmanifested-task gate: during an active run a task cannot flip to `completed` when no teammate manifest registers it — the hole behind "approved and reported, built by nobody".
- ›v3.42.0 principles-injection: every agent carries the compiled 7-principle ETHOS block; reviewers reach for a tie-breaker that's written down once, not scattered across 55 skill bodies.
Shared boundaries; contract sync between teammates.
- ›No new feature code at this phase.
- ›Resolve cross-team shared types and API contracts.
- ›v3.48.0 contract-first parallelism: the architect settles the inbound surface contract first and the backend provisions the endpoint at its REAL path serving a contract-conforming payload immediately — the frontend builds against a live endpoint (real HTTP, real error paths) while the backend replaces the internals underneath. Neither side waits, and neither moves the approved contract unilaterally.
- ›cdlg_overlap flags shared hot callees (call-graph closure intersection), not just shared files.
Real backend. Playwright. Visual-fidelity. UI interaction.
- ›Full-stack tests run against the real running app.
- ›v3.65.0 whole-suite integration: Phase 5 and `dev-api-integration-testing` enumerate the committed `suite-manifest.json` and run the ENTIRE dev Playwright suite — not just the tests this run happened to add.
- ›v3.55.0 frontend-E2E loop-exit gate: click-driven, as-the-user, full Playwright E2E is a HARD run-level exit criterion; v3.57.0 makes it run-scoped so the pipeline stops asking the user to do its job.
- ›v3.65.0 intuition-map lifecycle: `INTERACTION_INTUITION_MAP.md` is guaranteed present (ensure), grown from user-specified flows as confirmed entries (grow), and updated from debugging discoveries with `regression_refs[]` (bug-path-upsert). A contradiction leaves a confirmed entry byte-identical and asks a targeted question quoting both readings.
- ›Editability + visual verification teams independently re-verify.
- ›Test-failure RCA: forward + backward + alt-hypotheses, 3-pass rigor floor mandatory — no bounded 3-cycle cap anywhere (v3.55.3 / v3.55.4 swept the last residue).
- ›MemPalace gains function-level lineage records keyed by func:// IDs; Session Review (v3.26.0) + Seeded MemPalace (v3.27.0) feed cross-run learning.
- ›v3.42.0 recall data-envelope: every MemPalace-rendered block is wrapped in a do-not-interpret data envelope at the render boundary — recalled context is data, never instructions.
Per-task-group dependency graph + unbounded worklist.
- ›Iterate task groups in dependency order.
- ›Solution Requirements (SRs) auto-spawn fix teams on every surfaced issue; test-failure origins route through diagnostic-research first.
- ›v3.8.0: no iteration ceiling — the loop runs until everything is green.
Coverage map fully green; re-spawn on gap.
- ›Master review verdict must be overall: pass.
- ›Any gap re-spawns the originating team.
- ›Verdict is written where the Stop hook can independently re-audit it (v3.9.2).
Per requirement → commit → auto-merge to main → push. Worktree pruned.
- ›Stop-hook completion audit is a non-halting worklist (v3.8.0) + deterministic openspec validate --all --strict re-run (v3.9.2) that blocks the commit on any invalid active change.
- ›v3.56.0 turn-boundary completion lock: a session cannot end its turn while registered work is still open — the condition is read from disk (`hooks/open_work.py`), never asserted by the agent. Unknown or missing status counts as OPEN; the asymmetry fails safe.
- ›v3.64.0 abandonment discrimination: an open task untouched longer than the abandonment window (`CT6_TASK_STALE_HOURS`, floored at 1h) is inherited debt — listed with its store dir named, never blocking. `open_work.py retire --session <sid>` closes a dead list with an audit trail and refuses live tasks without --force.
- ›v3.30.0 run-continuity marker at .architect-team/active-run.json must be cleared via --mark-complete (the only path out); --stand-down is the user-explicit abandonment verb.
- ›v3.7.0 default: clean architect-team/<slug> branch is merged --no-ff into main, pushed, deleted (local + remote); worktree removed.
- ›Conflicts or protected-branch rejects fall back to feature-branch + PR. --force is never added.
- ›v3.46.0 delivery manifest: every close-out emits a stakeholder-readable bill of sale — plain-speak problem statement, executable validation steps with expected results, and the location + functionality of every new element. Matches a user-provided example document's vocabulary and layout; embedded in the run_complete email.
- ›v3.44.0 opt-in dev → test-on-dev → prod: `.architect-team-deploy.json` is IMMUTABLE to agents — only a human changes a human's policy.
- ›Opt out per-run with --no-commit / --no-push / --no-auto-merge / --no-compact / --no-teams.
The server tier + the verification layer the gates read
Librarian · Session Review · Seeded MemPalace · Triage/Evaluator
Runs entirely on the local machine — not a deployed / production service. Every services/**/*.py is asserted import-clean stdlib + in-repo only at module load, so closed / paid pieces plug through adapter seams and each service lifts cleanly into its own repo.
- ›/architect-team:librarian-install — full lifecycle CLI + per-OS boot descriptor (launchd / systemd / schtasks), never auto-loaded.
- ›Session Review + Seeded MemPalace feed cross-run learning back into Phase 5.
- ›Real Anthropic adapter when ANTHROPIC_API_KEY resolves, else honest provisioned-but-disabled state.
23 verification tools + a unified virtue-framed / bypass detector
Every Phase 3 self-review carries 5 VAO verdicts (oracle_match / baseline_clean / no_fake_data / adversarial / skill_invocation_audit) — any fail blocks the gate.
- ›verify-check-can-fail (v3.47.0, the 21st tool) — a cited verification output must prove it could have failed. Zero-work signatures (pytest collected 0 items, no-tests-found runners, a tsc --noEmit over zero files) are refused; every diff-added test needs red-run-first proof.
- ›verify-frontend-e2e (v3.55.0) — click-driven, as-the-user Playwright E2E is a HARD run-level loop-exit gate, run-scoped since v3.57.0.
- ›verify-claim-instrument-binding (v3.59.0, the 23rd tool) — agent-authored claims only; a mutation whose sha256 shows the file never changed is refused. v3.65.0 adds verify-suite-manifest with default-deny production safety.
- ›pretool_unilateral_override_guard.py (v3.0.0) — the unified virtue-framed / element-of-bypass detector; catches drift at action time, not Stop time.
- ›pretool_skill_gate.py (v3.15.0) — skill-invocation hard gate; blocks build tools until the pipeline Skill is re-invoked after compact.
- ›Pipeline-bypass detection (v2.22.0), proxy-element substitution (v2.21.0), deploy-mandate contract (v2.20.0), in-flight clarification processing (v2.19.0).
v3.44.0 adds the conditionally-required frontend_impact_e2e_review: when the diff carries frontend impact, a real-frontend end-to-end verdict is mandatory — a passing unit test can never open the gate. OPTIONAL_VAO_FIELDS 3 → 4 at v3.47.0.
The data-plane analog of visual-to-api-design
When the brief touches dbt / Airflow / Snowflake / Databricks / Kafka / feature-store work, Phase 0 dispatches a 7-stage exploration pipeline that emits an OpenSpec brief Phase 1 validates like any other — with ≥ 1 blocker-severity validation rule per transformation and end-to-end lineage + aggregate + per-endpoint metrics.
Per-endpoint call traces the diagnostic team consumes
Deterministic core in hooks/lineage_graph.py; runtime-witness reconciliation reuses code-path-witness.json as ground truth. Rename-stable func:// / asset:// IDs join MemPalace records across renames.
Three modes. one confirm probe. a heal path for every drift.
Fable via Claude sign-in; no split, no api-key. Uniform-fable ship state.
Local LiteLLM gateway on api-key auth; uniform-fable model policy. Env block written to ~/.claude/settings.json.
Split policy secondary-split — dev-class agents route through the gateway to ct6-secondary (OpenAI Codex or Z.ai GLM 5.2), spawn-compat via claude-haiku-4-5 impersonation.
Honest disclosure: requests labeled claude-haiku-4-5 through this gateway are answered by the chosen secondary (e.g. GLM 5.2), not by Anthropic's Haiku. The mapping is recorded in gateway.json, printed by status, and test-pinned.
How flow is decided
Phase 3 review gate
Every TaskUpdate(completed) on a teammate-owned task is gated. The hook exits 2 (block) until the 12-field evidence schema + independent_review are valid. 3 consecutive rejections → escalation handoff.
Issue → fix routing
Every surfaced issue becomes a Solution Requirement. Test-failure origins route through diagnostic research first; editability + interaction gaps go straight to a fix team. The loop closes when the originating check passes.
Stop-hook completion audit
Non-halting worklist (v3.8.0) + deterministic openspec validate --all --strict re-run (v3.9.2) + v3.30.0 run-continuity guard. The Stop hook blocks Phase 8 while .architect-team/active-run.json is `active` even on a momentarily-clean worklist; after CT6_MAX_NO_PROGRESS_STOPS no-progress blocks it auto-writes escalation-pending.md so wedged runs surface instead of looping.
Seven scripts. eight wired events. evidence-driven gates.
Every gate in the pipeline is enforced by a hook. No agent can mark its own work done. The Stop hook re-runs openspec validate --all --strict (v3.9.2) and carries the v3.56.0 turn-boundary completion lock — open work is read from disk via hooks/open_work.py, never asserted, with v3.64.0 inherited-stale work listed rather than blocking; the PostToolUse(TaskUpdate) hook adds the v3.47.0 unmanifested-task gate — during an active run a task cannot flip to completed unless a teammate manifest registers it, and v3.62.0 selects the evidence file BOUND to that task; the SessionStart hook heals v3.41.1 activation drift and wraps every v3.42.0 MemPalace recall in a do-not-interpret data envelope — a wedged run auto-escalates instead of looping.
pretool_skill_gate.py — v3.15.0 skill-invocation hard gate + v3.30.0 sticky run-arm. A user session that hasn't re-invoked the Skill since its last compact boundary is blocked from build and dispatch tools until it does.
pretool_unilateral_override_guard.py (v3.0.0) — the unified virtue-framed/bypass detector: blocks ad-hoc edits during an active run when no Skill(architect-team-pipeline) has been invoked. v3.56.0 also makes it the completion-lock's ground truth: the ask-ledger and the harness task store are immutable to agent writes.
review-gate-task.py — evidence schema v7 (17 self-review fields + independent_review block). Exit 2 blocks completion until every field validates. v3.62.0 selects the evidence file BOUND to the completing task via `task_subject`, so a reused integer id can't ride a foreign review.
review-gate-task.py — the same evidence gate re-checked at task completion, so a flip to `completed` outside a TaskUpdate can't slip past the schema.
teammate-idle-check.py — re-checks review-gate evidence when a subagent stops; feeds the continuous Solution-Requirement intake loop.
teammate-idle-check.py — the Agent-Teams counterpart: a named teammate going idle with open work triggers the same evidence re-check rather than a silent stall.
pipeline-completion-audit.py — non-halting worklist (v3.8.0) + deterministic openspec validate --all --strict re-run (v3.9.2) + v3.30.0 run-continuity guard + the v3.56.0 turn-boundary completion lock (read from disk via hooks/open_work.py, four named kill-switches, teammate owner-scoping) + v3.64.0 abandonment discrimination — inherited-stale tasks surface with their store dir named and never block.
precompact-closeout.py — captures worklist + evidence pointers and the v3.18.0 doc-currency reminder before context compaction, so a resumed session can reconstruct state.
sessionstart-run-continuity.py — v3.30.0 injects the resume-via-Skill directive on start / resume / clear / compact; v3.41.1 activation self-heal re-applies a dropped ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN env block merge-preservingly from the persisted master key when the gateway port is live; v3.42.0 wraps every injected MemPalace recall in a do-not-interpret data envelope.
What's on disk when a phase passes
Every gate reads a JSON file. Below: the exact shape the Phase 3 hook requires, and the Solution Requirement the orchestrator picks up to spawn a fix team.
{
"task_id": "T-042-add-invoice-export",
"spec_review": "pass",
"quality_review": "pass",
"real_not_stubbed": true,
"tests": { "added": 4, "passing": 4 },
"demo_artifact": "demos/T-042-export.mp4",
"files_changed": [
"apps/web/routes/invoices.export.tsx",
"apps/api/handlers/invoices/export.ts",
"tests/e2e/invoices.export.spec.ts"
],
"reuse_compliance": "ok",
"visual_fidelity_review": "pass",
"test_completeness_review": "pass",
"integration_testing_review": "pass",
"ui_interaction_review": "pass",
"oracle_match_review": "pass",
"baseline_clean_review": "pass",
"no_fake_data_review": "pass",
"adversarial_review": "pass",
"skill_invocation_audit": "pass",
"independent_review": {
"reviewer": "task-reviewer",
"verdict": "pass",
"spec_review": "pass",
"quality_review": "pass",
"real_not_stubbed": true,
"reuse_compliance": "ok",
"reviewed_at": "2026-05-31T14:22:08Z"
}
}{
"id": "SR-2026-05-31-014",
"status": "open",
"origin": {
"kind": "playwright-failure",
"test": "tests/e2e/invoices.export.spec.ts",
"discovered_by": "interaction-reviewer",
"discovered_at": "2026-05-31T14:18:51Z"
},
"summary": "Export button fires request but never resolves; spinner hangs.",
"acceptance_criteria": [
"Clicking Export downloads a CSV within 3s for ≤1k rows.",
"Failure path surfaces a toast and re-enables the button.",
"Playwright covers both success and failure flows."
],
"routing": {
"diagnostic_research_required": true,
"fix_team": "frontend+backend"
}
}12 conditions. all must hold. no iteration cap.
Phase 2 cannot start until every condition is satisfied. The orchestrator runs the checklist each iteration; failures route to the proposal-refiner.
- 01openspec validate --all --strict returns valid: true.
- 02Every artifact (proposal, specs, design, tasks) has status: done.
- 03Every source requirement has ≥ 1 scenario.
- 04Every requirement's acceptance criteria are measurable.
- 05Every front-end requirement has an explicit Playwright user-flow spec.
- 06Every back-end requirement has explicit dev-API integration test criteria.
- 07Every both-layer requirement has a front-to-back integration criterion (or recorded mock_testing_authorized opt-out).
- 08Every new module / file / dep in design.md has a Reuse Decision citing CODEBASE_MAP.md.
- 09Every Reuse Decision cites a file/symbol that actually exists.
- 10No duplicate capabilities (cross-checked via CODEBASE_MAP / INTEGRATION_MAP).
- 11Every new third-party dep has a documented comparison against the existing stack.
- 12tasks.md creates a new file only where existing files cannot be extended.
$ openspec validate --all --strict --json
{ "valid": true, "errors": [] }
$ openspec status --json
{ "proposal": "done", "specs": "done", "design": "done", "tasks": "done" }
▣ Phase 1 exit checklist
[12/12] all conditions satisfied → unlocking Phase 2 (team-spawn)Three failure modes. one hook field.
Ships as: page.request.post('/api/...') — bypasses the UI entirely.
Caught by: interaction-completeness flags zero genuine page.click on a non-stub control.
Ships as: Route wired to <ComingSoon /> while the design specifies a real screen.
Caught by: Every route enumerated and classified live / placeholder / confirmed-stub.
Ships as: Mockup's 'Welcome back, Sarah' shipped to every user.
Caught by: dynamic-value-discovery classifies from context, not from the literal.
# ui_interaction_review takes "pass" | "n/a" | "fail"
#
# pass — every interactive element genuinely user-flow-tested,
# every page live, every value correctly static or
# dynamically bound, OR a confirmed-stub.
# n/a — slice has no UI surface. REQUIRES non-empty
# ui_interaction_review_note.
# fail — BLOCKED by the hook. An unwired-control / placeholder-page /
# hardcoded-dynamic-value gap must be escalated as an SR,
# not marked complete.