archgen-mcp 0.0.7 → 0.1.0

package/assets/references/orchestration.md

@@ -1,262 +1,149 @@
 # Orchestration playbook — survey, verify, dispatch
 
-Sub-agent briefs and the wave-execution mechanics. The orchestrator (SKILL.md)
-calls into these sections; workers never read this file.
+Sub-agent briefs and wave-execution rules for the orchestrator (`SKILL.md`). Workers never read this file.
 
 ## §survey — brownfield codebase analysis brief
 
-**The brief is a tool output:** `archgen_plan { action: 'brief', kind: 'survey' }`.
-Dispatch 1–2 sub-agents with it verbatim — do not hand-write the prompt.
-
-Accept the map only if every section is present and non-empty.
+Dispatch 1–2 survey sub-agents with `archgen_plan{action:'brief', kind:'survey'}` verbatim. Accept `.archgen/<slug>/codebase-map.md` only when all required sections (`Structure`, `Modules`, `Conventions`, `Affected`) are present and non-empty.
 
 ## §verifier — plan review brief
 
-Dispatch AFTER artifacts exist and `archgen_plan{action:'validate'}` passes.
+Dispatch AFTER artifacts exist and `archgen_plan{action:'validate'}` returns `data.valid:true`.
 
 ### Agent tier — EVERY verifier dispatch
+- **SMALL / MEDIUM plan:** 1 strong mid/high-tier reasoning agent.
+- **LARGE plan:** 1 top-tier reasoning agent.
+- **FORBIDDEN:** Never use explore, quick, fast, or cheap/low-tier models—weak verifiers miss defects and cause extra rounds.
 
-Verification is judgment-heavy: a weak verifier misses real defects AND raises
-false positives — costing MORE rounds, not fewer. Dispatch on the strongest
-reasoning agent the harness offers (best agent present), or a mid/high-tier
-sub-agent scaled to plan complexity:
-
-- SMALL/MEDIUM plan → one strong (mid/high-tier) agent.
-- LARGE plan → the stronger/highest tier available.
-- NEVER an explore / research / quick / small / cheap / fast sub-agent,
-  whatever the harness calls its low-end tiers.
+### ONE agent, the WHOLE plan, ONE pass
+- **Never split verification across concerns.** One holistic verifier detects cross-artifact contradictions that sliced agents miss. (If a plan exceeds context limits, split strictly by artifact volume—e.g., `plans/` vs `docs/`—never by verification dimension).
+- **Exhaustive single pass.** The verifier MUST return a complete `COVERAGE:` table (`PASS` / `FAIL` / `N/A` for every dimension) so all issues surface in Round 1.
 
 ### Verification pass — FULL-DEPTH, every run
 
-**The brief is a tool output:** `archgen_plan { action: 'brief', kind: 'verifier' }`.
-Dispatch it verbatim — do not hand-write the prompt.
-
-Each verifier run executes ALL four steps:
-
-1. Runs `archgen_plan{action:'verify', tasksYaml, planDir}` — deterministic
-   floor: cycles, dangling refs, same-wave ownership overlap, missing acceptance
-   criteria, plan↔task coverage. It returns a verdict of `APPROVE` or `ISSUES`.
-2. When markdown artifacts exist under `.archgen/<slug>/`, runs
-   `archgen_docs{action:'validate', slugDir}` — must be clean (`ok:true`, zero
-   broken references) alongside the verifier's APPROVE; broken references block
-   APPROVAL.
-3. Reads plans + tasks.yaml and judges what the tools cannot (the full
-   checklist is in the brief):
-   - Are wave boundaries sensible (no artificial serialization)?
-   - Do acceptance criteria objectively verify (command or observable)?
-   - Edge cases covered per SKILL.md right-sizing class?
-   - Code-standards compliance plausible for the planned structure?
-   - the CONTRACT-COMPLETENESS sweep (functional coverage, security, data
-     integrity, state/lifecycle/recovery, resource limits, operational
-     entrypoints, metric traceability, consistency) — the brief lists every
-     dimension and says when to apply it. These failure classes are the TOP
-     cause of multi-round loops: round 1 MUST sweep the applicable dimensions
-     exhaustively.
-4. Returns EXACTLY one line verdict: `APPROVE` or `ISSUES:` + numbered list.
+Pass the output of `archgen_plan{action:'brief', kind:'verifier'}` verbatim (includes pre-rendered evidence map, Mermaid dependency graph, and `archgen_docs` validation status). The verifier executes all four steps:
+1. Runs `archgen_plan{action:'verify', tasksYaml, planDir}` $\rightarrow$ requires `APPROVE` (checks cycles, dangling refs, wave ownership overlap, acceptance criteria, bidirectional plan$\leftrightarrow$task coverage).
+2. Runs `archgen_docs{action:'validate', slugDir}` (if markdown exists) $\rightarrow$ requires `valid:true` (zero broken links/anchors).
+3. Audits judgment dimensions across `plans/` and `tasks.yaml`:
+   - Wave boundary sanity (no artificial serialization).
+   - Objectively verifiable acceptance criteria (runnable command or observable output).
+   - Scope-appropriate edge-case coverage (`SKILL.md` Hard Rule 3).
+   - `references/code-standards.md` compliance.
+   - **Contract-completeness sweep** across all applicable dimensions: `functional coverage`, `security & data protection`, `data integrity`, `state, lifecycle & recovery`, `resource limits & abuse`, `operational entrypoints`, `metric traceability`, and `consistency`.
+4. Outputs the strict deliverable format:
+   ```
+   VERDICT: APPROVE | ISSUES
+   COVERAGE:
+   | dimension | status | reason |  <- every dimension marked PASS / FAIL / N/A
+   FINDINGS:                        <- present when VERDICT: ISSUES
+   1. file § section — defect — impact — concrete fix
+   ```
+   *Any report missing the `COVERAGE:` table is incomplete—treat as `ISSUES` and require examination of omitted dimensions.*
 
 ### Efficiency — fewer rounds + zero duplicate work, NEVER shallower checks
-
-Every run stays FULL-DEPTH: both checks run to completion and the full
-judgment checklist applies each time. Efficiency comes ONLY from:
-
-- capping automatic rounds at 2 (gate protocol below);
-- batching fixes per file (fix discipline below);
-- never re-fixing an already-resolved finding.
-
-"Efficient" NEVER means skipping or lightening the verifier, the docs
-integrity check, or any judgment-checklist item.
+Never weaken or skip checks. Efficiency comes strictly from: (1) the exhaustive coverage table, (2) capping automatic rounds at 2, (3) batching fixes per file, and (4) never re-applying failed edits.
 
 ### Fix discipline — batch per file, dedupe repeats
-
-On `ISSUES:` the orchestrator fixes ALL findings before re-dispatching:
-
-- Group findings BY FILE; apply each file's fixes in ONE edit pass — open
-  each file once per round, not once per finding.
-- Round N reports the SAME finding as round N-1 (same file + same issue) →
-  the prior fix did not land: re-read the file and fix it properly — never
-  re-apply the identical edit.
+When `VERDICT: ISSUES` returns:
+- Group findings by file and apply all fixes to a file in a single edit pass.
+- If Round $N$ reports the identical finding as Round $N-1$, re-read the target file and apply a structural fix rather than repeating the prior edit.
+- If you disagree with a verifier finding, surface it verbatim to the user rather than ignoring or silently overriding it.
 
 ### Gate protocol — 2 automatic rounds, then ask the user
-
-The initial VERIFIER GATE flow (GENERATE step 5). Rounds 1–2 run
-automatically; fix ALL findings between rounds (fix discipline above):
-
-1. Round 1: dispatch verifier. `APPROVE` → gate passed → §plan-review.
-   `ISSUES:` → fix ALL findings → round 2.
-2. Round 2: dispatch verifier.
-   - Clean `APPROVE` → ask the user once more, recommending NO, proceed.
-   - `ISSUES:` → fix ALL findings → ask the user once more, recommending
-     YES, one more pass.
-   Ask recommendation-first per §interview/how-to-ask: "Run the verifier
-   once more to make sure everything passes?"
-3. On YES → run another round; if it returns `ISSUES:`, fix all and ask again
-   — every round beyond 2 is user-approved. On NO → proceed to §plan-review.
-4. On NO with findings still outstanding and no verifier `APPROVE` on record:
-   surface every outstanding finding verbatim and require an EXPLICIT user
-   waiver — never proceed silently. Hard rule 2 stands: the plan MUST NOT
-   reach the USER GATE without at least one verifier `APPROVE` (or that
-   explicit waiver on the record). An earlier `APPROVE` on record → proceed
-   to §plan-review, noting the latest unverified fixes.
+1. **Round 1:** Dispatch verifier. `APPROVE` $\rightarrow$ proceed to `§plan-review`. `ISSUES` $\rightarrow$ batch-fix all findings $\rightarrow$ Round 2.
+2. **Round 2:** Dispatch verifier.
+   - `APPROVE` $\rightarrow$ ask user recommendation-first: *"Run the verifier once more? 1. No, proceed (recommended) 2. Yes, run one more pass."*
+   - `ISSUES` $\rightarrow$ batch-fix all findings $\rightarrow$ ask user recommendation-first: *"Run the verifier once more to confirm fixes? 1. Yes, one more pass (recommended) 2. Waive remaining findings and proceed."*
+3. **Round 3+ (user-approved):** Each approval runs 1 pass.
+4. **Proceeding without `APPROVE`:** If the user declines another pass without a prior `APPROVE` on record, quote all unverified/outstanding findings verbatim and obtain an **explicit user waiver** before entering `§plan-review` (Hard Rule 2). Never cite token/cost numbers when reporting rounds.
 
 ## §plan-review — post-plan review stage
 
-Run AFTER the verifier returns APPROVE and BEFORE the user gate. Dispatch
-REVIEWER sub-agents sized by the right-sizing class — always ONE holistic
-review of the WHOLE plan, never per-concern splits:
-
-- SMALL: main-agent self-review acceptable if no reviewer mechanism exists.
-- MEDIUM: 1 reviewer.
-- LARGE: 1 holistic reviewer on the strongest reasoning tier. A 2nd reviewer
-  ONLY if the plan is genuinely too large for one reviewer's context — split
-  by ARTIFACT/VOLUME then (e.g. plans vs docs), never by concern.
-
-One holistic reviewer analyzes ALL issues together: cross-issue reasoning
-catches contradictions a narrow per-concern slice misses, and one reviewer
-costs far fewer tokens than several. NEVER dispatch one sub-agent per
-individual issue/concern.
-
-**The brief is a tool output:** `archgen_plan { action: 'brief', kind: 'review' }`.
-Dispatch it verbatim — it already carries the mermaid graph + docs-validate
-context to attach.
-
-Reviewers are read-only and report-only — they never edit artifacts or code.
-The orchestrator fixes the artifacts itself, re-runs validate +
-re-dispatches the verifier gate after every change.
-
-### Review loop — bounded passes, then ask
-
-The fix→re-verify cycle stays, but reviewer passes are countable and bounded:
-
-1. Pass 1: holistic review. Zero findings → stage done.
-2. Findings → fix ALL (batched per file), re-run validate + the verifier
-   gate → pass 2.
-3. Pass 2 still yields findings → do NOT spawn more reviewers. Consolidate
-   the outstanding findings and ask the user once, recommendation-first per
-   §interview/how-to-ask: "Run one more targeted review pass on the N
-   open findings? 1. One more pass (recommended) 2. Waive these findings and
-   proceed."
-4. On YES → run EXACTLY ONE more pass, then consolidate and STOP. Zero
-   findings → stage done; findings remain → surface them and require an
-   explicit user waiver before the user gate. On NO → record the explicit
-   waiver, proceed.
-
-A "more review" approval authorizes EXACTLY ONE additional pass — never a
-fresh loop, never more reviewers. The stage ends ONLY at zero findings or an
-explicit user waiver on record.
-
-## §investigate — root-cause protocol
-
-Triggered when the USER reports repetitive/recurring issues AFTER implementation
-waves completed. Do NOT patch-fix under this protocol.
-
-**The brief is a tool output:** `archgen_plan { action: 'brief', kind: 'investigate' }`.
-Complexity-sized dispatch:
+Run AFTER Verifier `APPROVE` and BEFORE the User Gate. Dispatch read-only reviewer(s) using `archgen_plan{action:'brief', kind:'review'}` verbatim (pre-renders dependency graph, doc validation, and evidence map; reviewer makes zero `archgen_*` tool calls):
+- **SMALL:** Main-agent self-review permitted if sub-agents are unavailable.
+- **MEDIUM:** 1 holistic reviewer.
+- **LARGE:** 1 top-tier holistic reviewer (2nd allowed ONLY if context size requires splitting `plans/` vs `docs/`; never split by concern).
 
-- SMALL scope: main agent investigates directly.
-- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+Reviewers are strictly read-only. The orchestrator applies fixes, re-runs `validate` + Verifier Gate, and manages the bounded review loop:
+1. **Pass 1:** Zero findings $\rightarrow$ stage complete. Findings $\rightarrow$ batch-fix per file, re-run `validate` + Verifier Gate $\rightarrow$ Pass 2.
+2. **Pass 2:** Zero findings $\rightarrow$ stage complete. Findings remain $\rightarrow$ consolidate and ask user once (`§interview/how-to-ask`): *"Run one more targeted review pass on the N open findings? 1. One more pass (recommended) 2. Waive findings and proceed."*
+3. **Pass 3 (final):** On `1`, run **EXACTLY ONE** final pass, then stop. If findings remain, require an explicit user waiver before the User Gate.
 
-Investigators produce ALL four:
+## §investigate — root-cause protocol
 
-1. Root cause statement — one sentence naming the actual defect.
-2. Evidence — files/lines/repro steps.
-3. Blast radius — which tasks/artifacts are affected
-   (`archgen_plan{action:'impact', tasksYaml, target}`).
-4. Remediation plan — routed through the normal gates: new fix tasks get fresh
-   ids inheriting the affected task's ownership globs.
+Triggered when the user reports recurring defects after wave execution. Pass `archgen_plan{action:'brief', kind:'investigate'}` verbatim:
+- **SMALL:** Main agent investigates directly.
+- **MEDIUM / LARGE:** 1–3 read-only investigator sub-agents split by disjoint suspected subsystem.
 
-Token discipline: investigators read narrowly around evidence, not whole-repo
-sweeps. Patch-fixes without a root-cause statement are forbidden under this
-protocol.
+Mandatory 4-part deliverable (no patch-fixing allowed):
+1. **Root cause statement:** One sentence identifying the underlying defect.
+2. **Evidence:** Exact file paths, line numbers, and reproduction steps.
+3. **Blast radius:** Affected tasks/artifacts via `archgen_plan{action:'impact', tasksYaml, target}`.
+4. **Remediation plan:** New fix tasks with fresh IDs inheriting affected `file_ownership` globs, routed through normal Verifier/Review/User gates.
 
 ## §dispatch — wave execution
 
-Dispatch policy: dispatch each task to the harness's NATIVE sub-agent mechanism
-when available AND functional. If sub-agents do not exist on this platform, or
-the sub-agent fails, or lacks required tool permissions (read/write/etc.), the
-MAIN AGENT executes the task ITSELF — sequentially, respecting waves and
-ownership globs. Cross-harness/platform delegation is allowed ONLY through an
-explicit user gate (below). There is NO automatic fallback to other harnesses,
-platforms, or CLIs — ever.
+Dispatch tasks via the platform's native sub-agent mechanism (`archgen_setup{action:'harness_info'}`). If sub-agents are missing, fail to spawn, or lack file permissions, the **main agent executes tasks sequentially itself**. Never switch harnesses or spawn external CLIs without explicit user approval.
 
-### Native sub-agents (preferred)
+### WHEN to dispatch a sub-agent — and when NOT to
 
-- Claude Code: background Agent tool per task; add worktree isolation for
-  tasks whose ownership might brush shared files.
-- Cursor: background subagents; request isolation when >2 parallel workers.
-- Antigravity: invoke_subagent async.
-- Codex: spawn_agent works but children can't nest — flatten the plan instead.
-- Gemini CLI: parallel @agents are hub-and-spoke only AND have no isolation →
-  use them ONLY for read-only/research waves unless wrapping in worktrees.
+**Sub-agents are for bounded implementation/analysis work, NEVER for state lookups:**
 
-### When sub-agents are unavailable or fail
+| Operation | Executor |
+|---|---|
+| Wave frontier, task list, task status (`archgen_tasks{next\|list}`) | **MAIN AGENT** (1 tool call; NEVER a sub-agent) |
+| Plan health, graph, coverage, impact (`archgen_plan`, `archgen_docs`) | **MAIN AGENT** (1 tool call; NEVER a sub-agent) |
+| Registry update, resume snapshot, CodeGraph status | **MAIN AGENT** (1 tool call; NEVER a sub-agent) |
+| Single task implementation | **Worker sub-agent** (prompt = `archgen_tasks{action:'contract'}`) |
+| Brownfield codebase survey | **Survey sub-agent** (`brief: 'survey'`, CodeGraph-first) |
+| Verifier / Plan-Review / Investigation | **Gate / Investigator sub-agent** (`brief: 'verifier'\|'review'\|'investigate'`) |
 
-Detect first — one of:
+### Reuse the agent's session — NEVER re-dispatch for the same context
 
-- mechanism missing on this platform;
-- spawn failure (sub-agent never started / crashed at launch);
-- tool-permission gaps (sub-agent runs but cannot read/write/edit files).
+Maintain a **dispatch ledger** (`dispatchKey -> agent session` using the `dispatchKey` from `archgen_tasks{action:'contract'}`). If a task requires a follow-up fix, clarification, or re-verification in files the agent already touched, **continue that agent's existing session** rather than spawning a fresh agent.
 
-Then, in order:
+### Parallel dispatch — no overlap, and never more than three at once
 
-1. DEFAULT — main agent executes the task itself, sequentially, respecting
-   waves and file_ownership globs. No user permission needed for this.
-2. USER GATE — cross-harness/platform delegation ONLY. When the sub-agent
-   problem looks platform-specific, STOP and tell the user the concrete issue,
-   propose using another platform/harness for that specific task (name the
-   harness + its command shape), and proceed ONLY after the user explicitly
-   allows it. Log the user's choice in the final report.
+**HARD CAP: MAX 3 LIVE PARALLEL SUB-AGENTS.** Execute larger waves in batches of $\le 3$. Before parallel dispatch, verify all six invariants:
+1. **Same wave only:** Dispatch only tasks returned in the current wave by `archgen_tasks{action:'next'}`.
+2. **Disjoint write globs:** Enforced by `next` (`OWNERSHIP_CONFLICT` blocks overlap).
+3. **No concurrent gate agents:** Never run Verifier or Reviewer agents while worker waves are executing.
+4. **Single writer per shared file:** Serialize tasks that touch shared configs, lockfiles, or entrypoints.
+5. **Ledger pre-registration:** Record `dispatchKey` in the dispatch ledger BEFORE spawning.
+6. **Live-agent counting:** Completed/paused sessions awaiting follow-up do not count against the 3-agent active cap.
 
-Never silently switch harnesses. Never ask permission to fall back for routine
-failures the main agent can simply do itself.
+### Native sub-agents (preferred)
+- **Claude Code:** Background `Agent` tool per task; use `git worktree` isolation when globs border shared files.
+- **Cursor:** Background subagents; enable isolation when running $>2$ parallel workers.
+- **Antigravity:** Async `invoke_subagent`.
+- **Codex:** `spawn_agent` (children cannot nest—flatten orchestration).
+- **Gemini CLI:** Parallel `@agents` lack write isolation—use only for read-only/survey waves unless wrapped in `git worktree`.
 
-A sub-agent MECHANISM failure (missing/spawn/permissions) is not a TASK
-failure — run the diagnose-and-ask flow above first. Mark a task failed only
-after execution was actually attempted (by sub-agent or main agent) and did
-not complete.
+### When sub-agents are unavailable or fail
 
-Isolation for native sub-agents when ownership borders are tight:
+If the sub-agent mechanism is missing, crashes at launch, or lacks read/write permissions (a **mechanism failure**, not a task failure):
+1. **Default:** Main agent executes the task sequentially itself, honoring wave order and `file_ownership`. No user prompt required.
+2. **Cross-harness fallback (USER GATE):** Only if the issue is platform-blocking, report the exact error, propose a specific alternative harness/CLI command, and wait for explicit user approval. Log the decision in the final report.
 
+Optional worktree isolation for tight ownership boundaries:
 ```bash
 git worktree add ".worktrees/$id" -b "task-$id"
-# point the sub-agent's cwd at .worktrees/$id, then merge task-$id on success
+# run sub-agent in .worktrees/$id, then merge task-$id on completion
 ```
-### Worker prompt contract
 
-**The contract is a tool output — never hand-assemble it:**
+### Worker prompt contract
 
+Always generate the worker prompt via:
 ```
 archgen_tasks { action: 'contract', tasksYaml: <tasks.yaml>, taskId: <id> }
 ```
+It bundles: task ID/title, verbatim acceptance criteria, `file_ownership` globs, dependency neighborhood, `references/code-standards.md` path, inline normative rules (`MUST`/`SHOULD`/`NEVER`) + paths/indexes for all matched required skills, pre-located plan sections, `.agent/` workspace paths, completion protocol (`set_status` + `Skill compliance:` line + commit scope), worker prohibitions, CodeGraph usage directive, and `dispatchKey`.
 
-It assembles, from the same sources everything else reads:
-
-- the task id + title;
-- the acceptance criteria **VERBATIM**;
-- the `file_ownership` globs ("edit NOTHING outside these");
-- the dependency neighbourhood (prerequisites + what depends on this task);
-- the code-standards reference path;
-- the capability-skill follow-instruction, when the task matched one;
-- the **pre-located doc sections** — the sections that mention the task id, never
-  the whole plan;
-- the working-state location;
-- the finish procedure (set_status + the `Skill compliance:` line + commit scope).
-
-**CODEGRAPH:** if `.codegraph/` is present, the worker must navigate with the
-CodeGraph MCP tools for anything needing understanding — never guess architecture
-from prose.
-
-**Workers do NOT talk to each other;** coordination happens only through
-tasks.yaml state.
-
-**Before dispatching**, check the contract's `warnings`: a task with no acceptance
-criteria or no file ownership is not dispatchable — fix the plan first.
+**Pre-dispatch check:** Inspect `contract.warnings`. Never dispatch a task with missing acceptance criteria, empty `file_ownership`, or an uninstalled required skill.
 
 ## Failure policy
 
-- Sub-agent mechanism failure (missing/spawn/permissions) → §dispatch
-  diagnose-and-ask flow FIRST. It is not yet a task failure.
-- Task exit ≠ 0 OR status=failed → leave it failed. NEVER auto-retry.
-- Downstream tasks stay blocked by the resolver (blockedByFailure).
-- Report to user: failed id, log path, proposed fix-task description.
-  [wait for user] A fix task gets fresh id, depends_on=[], ownership of the
-  failed task's globs.
+- **Mechanism failure** (missing/spawn crash/permissions) $\rightarrow$ follow fallback flow above (do not mark task `failed`).
+- **Task execution failure** (non-zero exit or unmet acceptance) $\rightarrow$ mark `failed` via `set_status`. **NEVER auto-retry.**
+- Downstream dependents are automatically held in `blockedByFailure` by the resolver.
+- Report failed task ID, logs, and a proposed fix task (`new ID`, `depends_on: []`, inheriting failed `file_ownership` globs) to the user. `[wait for user]`

package/assets/references/platforms.md

@@ -1,142 +1,73 @@
 # Platform capability matrix (November 2026)
 
-Facts verified against official vendor docs (2026-11); cells marked UNVERIFIED could
-not be confirmed. The capability DATA is served by
-`archgen_setup{action:'harness_info'}` — this file keeps the narrative.
+Authoritative platform capability data is served dynamically by `archgen_setup{action:'harness_info'}` from `packages/mcp/assets/platform-capabilities.json`.
 
 ## Harness capabilities
 
-**The capability data is a tool output — never read a table for it:**
-
+Query platform capabilities directly via the tool rather than static tables:
 ```
-archgen_setup { action: 'harness_info' }              # detect + return the row
-archgen_setup { action: 'harness_info', harness: 'claude' }   # one harness
+archgen_setup { action: 'harness_info' }                   # auto-detect current harness
+archgen_setup { action: 'harness_info', harness: 'claude' } # query specific harness
 ```
-
-It returns, per harness: the skill install paths (project + global), the MCP
-config file + top-level key + entry shape, the MCP CLI, the restart semantics and
-the sub-agent dispatch capability (mechanism, parallelism, isolation). The
-canonical data is `packages/mcp/assets/platform-capabilities.json` — the tool
-serves it, so it can never drift from reality.
+Returns: project & global skill paths, MCP config path, top-level JSON/TOML key, server entry schema, CLI commands, restart semantics, and sub-agent dispatch mechanics (tool name, parallelism, isolation).
 
 ## Platform detection
 
-Probe in order (the same order the tool uses):
-
-`.claude/` (Claude Code) · `.cursor/` (Cursor) · `.windsurf/` (Windsurf) ·
-`.opencode|opencode.json` (OpenCode) · `.github/copilot-instructions.md`
-(Copilot) · `~/.codex` (Codex) · `.gemini/` (Gemini CLI/Antigravity) ·
-`.kiro/` (Kiro) · `.trae/` (Trae).
-
-First match wins. `archgen_setup{action:'harness_info'}` does the same detection
-and returns the row — prefer it over probing by hand.
+`archgen_setup{action:'harness_info'}` probes in this priority order (first match wins):
+`.claude/` (Claude Code) $\rightarrow$ `.cursor/` (Cursor) $\rightarrow$ `.windsurf/` (Windsurf) $\rightarrow$ `.opencode` / `opencode.json` (OpenCode) $\rightarrow$ `.github/copilot-instructions.md` (Copilot) $\rightarrow$ `~/.codex` (Codex) $\rightarrow$ `.gemini/` (Gemini CLI / Antigravity) $\rightarrow$ `.kiro/` (Kiro) $\rightarrow$ `.trae/` (Trae).
 
 ## archgen installed layout
 
-`install.sh` / `npx archgen-skill install` maintain ONE canonical store plus
-thin bridges — the skill is never copied twice:
+`npx archgen-skill install` maintains a single canonical store with lightweight bridges:
 
 | Path | Role |
 |---|---|
-| `.agents/skills/archgen/` | Canonical store — `SKILL.md` + `references/code-standards.md` (guidance only; the MCP server owns every capability) |
-| `.claude/skills/archgen` | Optional symlink → canonical store, for Claude Code discovery |
-| `CLAUDE.md` | One-line `@AGENTS.md` bridge only — no content of its own |
-| `AGENTS.md` | The hub every harness reads; hosts the features registry between `<!-- archgen:features:start -->` and `<!-- archgen:features:end -->` |
+| `.agents/skills/archgen/` | Canonical store: `SKILL.md` + `references/code-standards.md` |
+| `.claude/skills/archgen` | Optional symlink $\rightarrow$ canonical store for Claude Code discovery |
+| `CLAUDE.md` | Single-line `@AGENTS.md` pointer |
+| `AGENTS.md` | Cross-harness hub hosting the feature registry between `<!-- archgen:features:start -->` and `<!-- archgen:features:end -->` |
 
-The registry table (`| Feature | Status | Updated |`, one row per
-`.archgen/<slug>/`) is machine-maintained by `archgen_registry{action:'update'}` after
-every generate/plan/wave run — never hand-edit it; edit `.archgen/` state and
-re-run the tool instead.
+Never hand-edit the `AGENTS.md` registry table (`| Feature | Status | Updated |`); update it exclusively via `archgen_registry{action:'update'}`.
 
 ## MCP configuration
 
-**The per-platform shapes are a tool output:** `archgen_setup{action:'harness_info'}`
-returns each harness's config file, top-level key and entry shape.
-
-Four different top-level keys exist — NEVER assume `mcpServers`:
-`mcpServers` (claude, cursor, windsurf, gemini, antigravity, kiro, trae) ·
-`servers` (vscode/copilot) · `mcp` (opencode) · `context_servers` (zed). Codex
-CLI uses TOML (`[mcp_servers.<id>]`).
-
-Remote URL fields vary per platform (`url` vs `serverUrl` vs `httpUrl`); the tool
-reports the exact field. Uncertainty triggers a web-search of the current
-official docs, never invention.
-
-**Wiring is a tool call:** `archgen_setup{action:'install_mcp', approve:true}`.
-Never hand-edit a harness config.
+Query `archgen_setup{action:'harness_info'}` for exact per-platform MCP schemas:
+- **Top-level keys vary:**
+  - `mcpServers`: Claude Code, Cursor, Windsurf, Gemini CLI, Antigravity, Kiro, Trae
+  - `servers`: VS Code / GitHub Copilot
+  - `mcp.servers.<id>`: OpenCode (nested under `mcp.servers`, never flat `mcp.<id>`)
+  - `context_servers`: Zed
+  - `[mcp_servers.<id>]`: Codex CLI (TOML)
+- **Remote URL keys vary:** `url` vs `serverUrl` vs `httpUrl` (check `harness_info`).
+- **Automated wiring:** Use `archgen_setup{action:'install_mcp', approve:true}` rather than hand-editing config files.
 
 ## Sub-agent dispatch capability
 
-**Also a tool output:** `archgen_setup{action:'harness_info'}` returns the
-dispatch mechanism, whether it parallelises, its limits and its isolation story.
-Use it before dispatching — the fallback (self-execute) and the isolation advice
-depend on it.
+Always inspect `archgen_setup{action:'harness_info'}` before wave execution to determine the native sub-agent tool, parallel execution limits, worktree isolation requirements, or whether to fall back to sequential main-agent execution.
 
 ## Unknown platform procedure
 
-1. WEB SEARCH: `<platform> official docs MCP configuration` and
-   `<platform> agent skills install path`.
-2. Prefer official vendor domains over blog posts; note the date of sources.
-3. Present findings + proposed config diff to the user. [approval gate]
-4. Apply, verify, and offer to append findings to this table upstream.
+1. **Web search:** `<platform> official docs MCP configuration` and `<platform> agent skills install path` (prioritize official vendor docs; note publication dates).
+2. **Propose:** Present discovered paths and exact config diff to the user. `[approval gate]`
+3. **Apply & verify:** Write approved config, verify tool availability, and offer to upstream the platform definition.
 
 ## Codegraph indexing scope
 
-Current mainstream codegraph indexers extract SOURCE symbols only
-(functions/classes/imports) — they do not index markdown headings, and YAML
-support ranges from absent to file-level config tracking; none can graph
-tasks.yaml dependencies. Generic code indexers verifiably do not extract
-markdown headings or YAML task semantics, so archgen ships its own
-deterministic graph tools:
-
-- Source navigation → codegraph MCP (built automatically by Step 0 / the
-  the `archgen_codegraph` bootstrap flow).
-- YAML plan graphs → exclusively `archgen_plan{action:'graph'}`.
-- Markdown artifact navigation → `archgen_docs`.
-
-If the harness exposes a markdown-heading indexer (e.g. a
-`codegraph_index_markdown`-style tool), prefer it for general repo docs but
-still use `archgen_docs` inside `.archgen/` — it understands TASK/FR
-reference semantics. Brownfield surveys prefer codegraph once present.
+Mainstream codegraph indexers parse **source-code symbols only** (functions, classes, imports)—never Markdown headings or YAML task dependencies. Use the dedicated tool for each artifact class:
+- **Source code navigation:** CodeGraph MCP tools (`.codegraph/`).
+- **YAML task dependency graphs:** `archgen_plan{action:'graph'}`.
+- **`.archgen/` Markdown navigation & FR/TASK link validation:** `archgen_docs`.
 
 ### Codegraph bootstrap (official CLI, no command list here)
 
-CodeGraph = `@colbymchenry/codegraph` (npm), CLI `codegraph`, MIT, local-first,
-self-contained runtime. It persists a SQLite symbol graph in `.codegraph/`,
-serves it over MCP, and indexes SOURCE symbols only (scope above) — pair with
-`archgen_docs` / `archgen_plan{action:'graph'}` for markdown/YAML.
-
-**No version is pinned:** the bootstrap always takes the latest published
-release and refreshes it in place. The MCP server exposes its own tool set to
-the agent, so the skill does not restate the CLI's command surface — read it
-from the installed CLI (`codegraph help`) or the MCP tools themselves.
-
-> **Entry point — the `archgen_codegraph` tool.** It installs the CLI **if it
-> is missing** (an installed CodeGraph is the user's to manage and is never
-> upgraded behind their back), wires every DETECTED harness with the correct
-> per-platform shape, and builds the project index — idempotently, with an
-> approval gate before any config write. It drives the official CLI; it never
-> reimplements it.
-> ```
-> archgen_codegraph { action: 'ensure' }   # install if missing + wire + index
-> archgen_codegraph { action: 'status' }   # what is installed/wired/indexed
-> ```
-
-**Rules that matter to the agent:**
-- The index is built ONCE per project; the MCP server's watcher keeps it live,
-  so **never re-index** — no manual index/sync steps after the bootstrap.
-- MCP configs are written only with `approve: true`; the tool returns its plan
-  otherwise. A config that is not valid JSON (e.g. JSONC) is reported, never
-  rewritten. Harnesses that are not installed are never touched.
-- Only DETECTED harnesses get an entry. The per-platform file path, top-level
-  key (`mcpServers` / `servers` / `mcp` / `context_servers`) and server entry
-  live in `packages/mcp/assets/harness-mcp.json` — one source of truth.
-- **Telemetry — disclose it, never claim "100% local":** it is enabled by
-  default on a fresh install and reports a machine ID (`~/.codegraph/`), and the
-  tool changes it only with an explicit `telemetry: 'off' | 'on'`.
-
-Agent flow (Step 0): detect `.codegraph/` at the repo root.
-- **Absent** → `archgen_codegraph{action:'ensure'}` once
-  per project (standing approval from the user's install-time consent; show the
-  printed plan). On decline → grep/Glob.
-- **Present** → use the CodeGraph MCP tools for navigation. Never re-index.
+CodeGraph (`@colbymchenry/codegraph`, MIT) maintains a local SQLite symbol graph in `.codegraph/` and serves it via MCP.
+- **Entry point:**
+  ```
+  archgen_codegraph { action: 'ensure' } # install CLI if missing + wire detected harnesses + index
+  archgen_codegraph { action: 'status' } # check install, wiring, and index state
+  ```
+- **Operational rules:**
+  - **Index once:** Built during bootstrap and kept live by the MCP file watcher—**never re-index manually**.
+  - **Safe config writes:** Non-bootstrap config edits require `approve: true`, touch only detected harnesses (`packages/mcp/assets/harness-mcp.json`), and never overwrite invalid JSON/JSONC or upgrade an existing user-installed CLI.
+  - **Telemetry disclosure:** CodeGraph enables anonymous machine-ID telemetry (`~/.codegraph/`) by default; disclose this accurately (never claim "100% offline/no telemetry") and pass `telemetry: 'off' | 'on'` only when requested.
+- **Step 0 flow:** If `.codegraph/` is present, use CodeGraph MCP tools. If absent, run `archgen_codegraph{action:'ensure'}` once per project (fallback to grep/glob if declined).