docs(voyage): add Mermaid architecture diagrams + primitives decision-matrix

Replace the ASCII pipeline figure in README with two Mermaid diagrams — the full pipeline (all 7 commands + 7 handover contracts) and agents per phase — and add a "Primitives per step" decision-matrix to docs/architecture.md, pointed to from README. Corrects prior prose: /trekexecute spawns no sub-agents; Phase 5 swarm is 6 fixed + 2 conditional; cross-cutting = 7 hook scripts incl. Stop->OTEL. Both diagrams validated with mermaid-cli 11.12.0 (render clean); node --test 756/0 fail (doc-consistency pins intact). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017AkavgP4v6QT1x8aZtRa9S
2026-06-24 11:26:44 +02:00 · 2026-06-24 11:26:44 +02:00 · 8112e4f45c
commit 8112e4f45c
parent ef569c084e
2 changed files with 74 additions and 15 deletions
--- a/README.md
+++ b/README.md
@ -604,24 +604,65 @@ Claude never pre-generates suggestions in this flow.

 ## The full pipeline

+Six commands, one pipeline — each step hands a structured artifact to the next (the seven [handover contracts](docs/HANDOVER-CONTRACTS.md)):
+
+```mermaid
+flowchart LR
+    B["/trekbrief"]
+    R["/trekresearch"]
+    P["/trekplan"]
+    X["/trekexecute"]
+    V["/trekreview"]
+    C["/trekcontinue"]
+    A["architect plugin<br/>(opt-in, not bundled)"]
+
+    B -->|"H1 · brief.md · PUBLIC"| R
+    R -->|"H2 · research/NN-*.md"| P
+    A -.->|"H3 · architecture/overview.md"| P
+    P -->|"H4 · plan.md"| X
+    X -.->|"H5 · progress.json (--resume)"| X
+    X -->|"H7 · .session-state.local.json"| C
+    C -->|"next session"| X
+    X -.->|"git diff"| V
+    V -->|"H6 · review.md (loop back)"| P
 ```
- /trekbrief   /trekresearch    /trekplan         /trekexecute
- ┌──────────────┐    ┌───────────────────┐   ┌─────────────────────┐  ┌─────────────────────┐
- │ Interview    │    │ 5 local agents    │   │ brief-reviewer      │  │ Parse plan          │
- │ ↓            │    │ 4 external agents │   │ ↓                   │  │ ↓                   │
- │ Intent/Goal  │    │ + Gemini bridge   │   │ 6-8 exploration     │  │ Detect sessions     │
- │ ↓            │    │ ↓                 │   │ agents (parallel)   │  │ ↓                   │
- │ Research     │    │ Triangulation     │   │ ↓                   │  │ Execute steps       │
- │ topics       │    │ ↓                 │   │ Opus planning       │  │ (verify + manifest  │
- │ ↓            │ → brief → → → → → → → → → → → ↓                   │→ │  + checkpoint)      │
- │ brief.md     │    │ research/*.md     │   │ plan-critic +       │  │ ↓                   │
- └──────────────┘    └───────────────────┘   │ scope-guardian      │  │ Phase 7.5 manifest  │
-                                             │ ↓                   │  │ audit + 7.6 recovery│
-                                             │ plan.md             │  │ ↓                   │
-                                             └─────────────────────┘  │ progress.json + done│
-                                                                      └─────────────────────┘
+
+Solid arrows are the forward pipeline; dashed are conditional/internal edges (`--resume`, the git-diff that feeds review, the opt-in architect input). **H1 (`brief.md`) is the only PUBLIC contract** — the single integration point for any upstream brief producer.
+
+### Agents per phase
+
+Every command orchestrates its agents inline from the main context (all sub-agents are `model: opus`-pinned). `/trekexecute` is the exception — it spawns **no** sub-agents.
+
+```mermaid
+flowchart TB
+    subgraph BR["/trekbrief"]
+        BRG["brief-reviewer (gate · ≤3 iter)"]
+    end
+    subgraph RES["/trekresearch · Phase 4 — parallel"]
+        RL["LOCAL: architecture-mapper · dependency-tracer<br/>task-finder · git-historian · convention-scanner*"]
+        RE["EXTERNAL: docs-researcher · community-researcher<br/>security-researcher* · contrarian-researcher* · gemini-bridge*"]
+    end
+    subgraph PL["/trekplan"]
+        PLG["Phase 4b · brief-reviewer (gate)"]
+        PLS["Phase 5 — parallel (6 + 2*): architecture-mapper · dependency-tracer<br/>risk-assessor · task-finder · test-strategist · git-historian<br/>convention-scanner* · research-scout*"]
+        PLC["Phase 9 — parallel · plan-critic · scope-guardian"]
+        PLG --> PLS --> PLC
+    end
+    subgraph EX["/trekexecute · no sub-agents"]
+        EXI["inline step-loop + claude -p worktrees<br/>+ Phase 7.5/7.6 manifest audit (deterministic)"]
+    end
+    subgraph RV["/trekreview"]
+        RVR["Phase 5 — parallel · code-correctness-reviewer · brief-conformance-reviewer*"]
+        RVJ["Phase 6 · review-coordinator (Judge)"]
+        RVR --> RVJ
+    end
+    BR --> RES --> PL --> EX --> RV
 ```

+`* = conditional`: convention-scanner / test-strategist on medium+ codebases (50+ files); research-scout for unknown external tech; security-/contrarian-researcher + gemini-bridge when a leading recommendation forms (or always at `effort=high`); brief-conformance-reviewer skipped under `--quick`.
+
+> **Which Claude Code primitive each phase uses — and the alternatives considered (Workflow substrate, delegated orchestrator, dormant synthesis-agent)** → see [docs/architecture.md §Primitives per step](docs/architecture.md#primitives-per-step-decision-matrix).
+
 All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.

 An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/trekplan` auto-discovers its `architecture/overview.md` output as priors when present.
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -80,6 +80,24 @@ The `.html` files (`brief.html`, `plan.html`, `review.html`) are produced by `sc

 No code-level dependency between plugins — the contract is filesystem-level only.

+### Primitives per step (decision matrix)
+
+Which native Claude Code primitive each pipeline step runs on today, and the alternatives that were considered and where they landed. Companion to *Delegate the engine, keep the policy* above; the full decision records live in `docs/voyage-vs-cc-balance-analysis.md`, `docs/T1-cc26-delegated-orchestration.md`, and `docs/T2-cc27-workflow-substrate.md`.
+
+| Step | Primitive today (production) | Alternatives considered (status) |
+|---|---|---|
+| **brief** | Inline interview loop → `brief.md` (framing gate) | `AskUserQuestion` as the Q&A engine (recommended, not yet wired); Skill/Workflow auto-orchestration (rejected — one-shot, can't span slash-command/handover boundaries) |
+| **research** | Inline spawns a foreground swarm; MCP per agent¹ | Delegated `synthesis-agent` (PoC measured Δ main-context ≈ 0 → ships **dormant**, wired to nothing) |
+| **plan** | Inline: parallel explorer swarm → synthesis → adversarial `plan-critic` | Delegated orchestrator via nested sub-agents (CC-26 → lean NO, not wired; `planning-orchestrator.md` is a reference doc, not a spawnable agent) |
+| **execute** | Inline step loop; multi-session via `git worktree` + `claude -p` waves; deterministic manifest audit | CC `TaskCreate`/`TodoWrite` for progress/resume (insufficient — carries no step status / attempts / SHA / drift → own typed `progress.json` contract) |
+| **review** | Inline parallel reviewers (no cross-feed) → `review-coordinator` Judge | **Workflow** substrate for Phase 5–6 (bake-off POSITIVE: +4.4 % tokens / +54 % wall-time → shipped **opt-in `--workflow`**, not default; wholesale substrate swap declined) |
+| **continue** | Inline reads `.session-state.local.json` → zero-confirm resume | CC `--resume` (transcript replay, not typed work-state → insufficient) |
+| **cross-cutting** | 7 hook scripts: `pre-bash` + `pre-write` guards, `post-bash` stats, `session-title`, `pre-`/`post-compact` flush, **`Stop`→OTEL** export | — |
+
+¹ MCP per research agent: `docs-researcher` → Microsoft Learn + Tavily · `community-`/`security-`/`contrarian-researcher` → Tavily (+ WebSearch/WebFetch) · `gemini-bridge` → Gemini Deep Research MCP. Graceful degradation when an MCP server is absent.
+
+**Legend:** *production* = wired and active · *dormant* = shipped but wired to nothing (`synthesis-agent`) · *opt-in* = behind a flag (`--workflow`) · *not wired* = considered, deferred (delegated orchestrator, the `AskUserQuestion` brief engine).
+
 ## State

 All artifacts in one project directory (default):