archgen-skill 0.0.3 → 0.0.5

package/vendor/skills/archgen/references/mcp-and-skills.md

@@ -4,43 +4,114 @@
 
 1. **Identify** the platform (SKILL.md Step 0), load its row from
    references/platforms.md section MCP: config file, top-level key, quirks.
-2. **Prefer the platform CLI** where the table lists one. It handles scope and
-   file selection correctly:
+2. **Discover** — when the correct installation method or config shape for
+   the detected harness is not confidently known, web-search the CURRENT
+   official installation docs/command FIRST. Never trust potentially-stale
+   memorized commands or invented config shapes; uncertainty triggers search,
+   not guessing.
+3. **Scope** — choose and state the install scope explicitly:
+   - **GLOBAL** — server types that are global entries (npx/npm-based MCP
+     servers usable across harnesses). Recommended for universally-useful
+     servers (codegraph is the canonical example) unless the user prefers
+     project-local.
+   - **HARNESS-SPECIFIC** — write into the detected platform's config only.
+     Recommended when the server only matters to that platform.
+   The user's approval covers the stated scope.
+4. **Prefer the platform CLI** where the table lists one, passing the scope
+   flag that matches the chosen scope:
    - `claude mcp add --scope project --transport http <name> <url>`
    - `codex mcp add <name> --url <url>` or `codex mcp add <n> -- cmd args`
    - `gemini mcp add -s project -t http <name> <url>`
-3. No CLI available: draft the exact config diff against the platform's real
+5. No CLI available: draft the exact config diff against the platform's real
    shape (see assets/mcp-template.json for annotated canonical forms) and SHOW
    it to the user. **USER APPROVAL GATE** — wait for an explicit yes before any
    write; approval is never inferred from earlier steps.
-4. Apply, then apply the restart semantics from the platforms table.
-5. Verify the tool is visible after reload; report failure modes honestly.
+6. Apply, then apply the restart semantics from the platforms table.
+7. Verify the tool is visible after reload; report failure modes honestly.
 
 Never write MCP configs silently. Never invent config shapes — the four known
 top-level keys are mcpServers / servers / mcp / context_servers; remote URL
-fields vary (url vs serverUrl vs httpUrl) per the platforms table.
+fields vary (url vs serverUrl vs httpUrl) per the platforms table. Uncertainty
+triggers web-search of current official docs, never invention.
 
 ## FETCH-SKILL procedure
 
-1. Read assets/skill-registry.json. Match the current task domain against
-   entry `matches` patterns (e.g. frontend/UI work matches ui-skills).
-2. Install into the CURRENT platform's skill dir (platforms.md paths):
-   - Generic: `npx skills add <owner>/<repo>` (writes correct path for 75+
-     harnesses; `-g` for global).
-   - Entry-specific command when present (e.g. `npx ui-skills get baseline-ui`).
-3. Confirm files landed where expected; then FOLLOW the fetched skill's own
-   instructions for the task domain.
-4. Missing capability: web-search reputable skill repos, propose to user,
-   on approval append an entry to the registry (PR or local edit).
+Capability-skill loading is **REQUIRED, not opportunistic**. Whenever planned
+work touches a registry `matches` domain, the matching skill MUST be loaded —
+during planning (GENERATE / BROWNFIELD / UPDATE) AND re-verified during
+execution (worker dispatch). UI/design/frontend/animation/component/
+landing-page work REQUIRES the design skills (`ui-skills`, `policy:
+"required"`) loaded first. Referenced from elsewhere as:
+*see references/mcp-and-skills.md § FETCH-SKILL procedure*.
+
+0. **WHEN** — mandatory, twice per matched task:
+   - **Pre-planning scan**: while planning, check every task's title, summary,
+     and `file_ownership` against the registry BEFORE the plan is finalized;
+     fetch any matched skill at that point.
+   - **Pre-dispatch verification**: immediately before dispatching each worker,
+     re-verify its match; if the skill is missing from the platform skill dir,
+     install it before dispatch proceeds.
+1. **MATCH** — read assets/skill-registry.json. Test every task's title,
+   summary, and file_ownership globs against each entry's `matches` patterns
+   using case-insensitive substring matching (e.g. a task titled "polish
+   landing page hero" matches ui-skills via `"landing page"`). One hit = this
+   procedure is mandatory for that task.
+2. **RESOLVE** — determine the CURRENT platform's skill dir from
+   references/platforms.md § Skill install paths. That table owns the paths;
+   never duplicate them here.
+3. **INSTALL once if absent** — cached check first: if the skill is already
+   present in the resolved platform skill dir, skip reinstall and go to step 4.
+   Otherwise run the entry's `install` command (generic fallback:
+   `npx skills add <owner>/<repo>`; `-g` for global; entry-specific commands
+   like `npx ui-skills get baseline-ui` when present). Then VERIFY presence:
+   confirm the skill directory/SKILL.md landed where platforms.md says it
+   should. Fetch happens ONCE per project; later runs are cache hits.
+4. **INTEGRATE** — inject the follow-instruction into (a) the planning context
+   so tasks reference the skill's standards, and (b) EVERY affected worker
+   prompt, using this sentence template:
+
+   > `<Domain> work: follow <skill-dir>/SKILL.md (installed via FETCH-SKILL) — apply its standards to every relevant decision.`
+
+   Concrete design instantiation for ui-skills:
+
+   > `Design work: follow <skill-dir>/SKILL.md (installed via FETCH-SKILL) — apply its component/motion/baseline standards to every visual decision.`
+
+5. **AUDIT** — workers MUST state in their completion report whether they
+   followed the injected skill, one auditable line, e.g.:
+   `Skill compliance: followed ui-skills (<skill-dir>/SKILL.md)` or
+   `Skill compliance: NOT followed — <reason>`.
+6. **MISSING CAPABILITY** — unmatched-but-obvious domain (user says "make it
+   pretty" with no registry entry): web-search reputable skill repos, propose
+   to user, on approval append an entry to the registry (PR or local edit).
+   Never add registry entries without explicit user approval.
 
 ## Registry entry shape
 
+Canonical keys, in order — there are no others. Notably there is NO
+`npxCommand` field anywhere in the registry; the executable command lives in
+`install` (with optional `direct_fetch`):
+
 ```json
 {
   "name": "short-name",
   "purpose": "when to reach for it",
   "repo": "owner/repo",
   "install": "npx skills add owner/repo",
-  "matches": ["frontend", "ui", "design"]
+  "direct_fetch": "optional per-skill fetch command",
+  "browse": "optional listing command",
+  "mcp_endpoint": "optional MCP URL",
+  "matches": ["frontend", "ui", "design"],
+  "policy": "required"
 }
 ```
+
+- `matches[]`: case-insensitive substrings tested against task titles,
+  summaries, and file_ownership during the FETCH-SKILL domain scan (step 1).
+- `policy` (`required` | `on-demand`) — how mandatory loading is:
+  - `"required"`: loading is MANDATORY whenever work touches any of the
+    entry's `matches` domains — pre-planning fetch plus pre-dispatch
+    verification (FETCH-SKILL steps 0–5 all apply). Currently only ui-skills
+    carries this; design/UI/frontend work must not proceed without it.
+  - `"on-demand"`: fetched only when a task explicitly names the installer or
+    another registry entry lacks a usable command (e.g.
+    vercel-skills-installer).

package/vendor/skills/archgen/references/orchestration.md

@@ -24,24 +24,196 @@ Accept the map only if every section is present and non-empty.
 
 ## §verifier — plan review brief
 
-Dispatch AFTER artifacts exist and validate.mjs passes. The verifier:
+Dispatch AFTER artifacts exist and validate.mjs passes.
+
+### Agent tier — EVERY verifier dispatch
+
+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.
+
+### Verification pass — FULL-DEPTH, every run
+
+Each verifier run executes ALL four steps:
 
 1. Runs `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
    — deterministic floor: cycles, dangling refs, same-wave ownership overlap,
    missing acceptance criteria, plan↔task coverage.
-2. Reads plans + tasks.yaml and judges what scripts cannot:
+2. When markdown artifacts exist under `.archgen/<slug>/`, runs
+   `node <skill>/scripts/doc-index.mjs .archgen/<slug> --validate` — must be
+   clean (zero broken references, exit 0) alongside verify-plan APPROVE;
+   broken references block APPROVAL.
+3. Reads plans + tasks.yaml and judges what scripts cannot:
    - 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?
-3. Returns EXACTLY one line verdict: `APPROVE` or `ISSUES:` + numbered list.
+   - CONTRACT-COMPLETENESS sweep — round 1 must confirm OR flag-as-missing
+     every APPLICABLE dimension (later discovery = the round-1 sweep failed,
+     not a gap). Apply a dimension only where the system actually has that
+     concern — skip what genuinely doesn't apply, but NEVER skip a dimension
+     the system touches:
+     - **Functional coverage**: every stated requirement/feature has tasks +
+       objectively verifiable acceptance.
+     - **Security & data protection** (if it authenticates, authorizes,
+       encrypts, or handles sensitive data): authn/authz flows, session &
+       credential lifecycle, replay/CSRF protection, encryption & privacy
+       boundaries, input validation — each fully specified, not named-and-
+       skipped.
+     - **Data integrity**: schemas, relationships, validation, and migration /
+       back-compat for any persisted state.
+     - **State, lifecycle & recovery** (if any operation is stateful,
+       long-running, or multi-step): checkpointing/resume, idempotency,
+       cleanup, expiry, compensation/rollback semantics.
+     - **Resource limits & abuse** (if it exposes shared or anonymous
+       resources): quotas, rate limits, retention/deletion, anonymous-abuse
+       controls.
+     - **Operational entrypoints**: every stack-required build/deploy/test/
+       bootstrap entrypoint is OWNED by some task (no orphan entrypoint).
+     - **Metric traceability**: every PRD success metric maps to a task
+       acceptance criterion with a reproducible command / sample size / data
+       source.
+     - **Consistency**: actively check cross-contract claims for internal
+       contradiction (a claim in one artifact that another artifact violates).
+     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.
+
+### Efficiency — fewer rounds + zero duplicate work, NEVER shallower checks
+
+Every run stays FULL-DEPTH: both scripts 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 verify-plan.mjs, doc-index.mjs,
+or any judgment-checklist item.
+
+### 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.
+
+### 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.md § 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.
+
+## §plan-review — post-plan review stage
+
+Run AFTER verify-plan 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.
+
+```
+TASK: Review the plan in .archgen/<slug>/ READ-ONLY.
+EXAMINE:
+  - edge cases per module
+  - task ordering / parallelization sanity (waves vs real dependencies)
+  - cross-module contract mismatches (interfaces, paths, naming)
+  - enhancement recommendations
+  - documentation completeness
+DELIVERABLE: numbered findings list; each finding = what + where + why.
+You NEVER edit files. Report only.
+```
+
+Reviewers are read-only and report-only — they never edit artifacts or code.
+The orchestrator fixes the artifacts itself, re-runs validate.mjs +
+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.mjs + 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.md § 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. Complexity-sized dispatch:
+
+- SMALL scope: main agent investigates directly.
+- MEDIUM/LARGE: 1–3 investigator sub-agents split by suspected subsystem.
+
+Investigators produce ALL four:
+
+1. Root cause statement — one sentence naming the actual defect.
+2. Evidence — files/lines/repro steps.
+3. Blast radius — which tasks/artifacts are affected.
+4. Remediation plan — routed through the normal gates: new fix tasks get fresh
+   ids inheriting the affected task's ownership globs.
 
-Orchestrator fixes issues (edits artifacts) and re-dispatches. Loop until
-APPROVE — never present to the user before verifier approval.
+Token discipline: investigators read narrowly around evidence, not whole-repo
+sweeps. Patch-fixes without a root-cause statement are forbidden under this
+protocol.
 
 ## §dispatch — wave execution
 
-### Tier 1: native sub-agents (preferred where strong)
+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.
+
+### Native sub-agents (preferred)
 
 - Claude Code: background Agent tool per task; add worktree isolation for
   tasks whose ownership might brush shared files.
@@ -51,55 +223,69 @@ APPROVE — never present to the user before verifier approval.
 - 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.
 
-### Tier 2: bash fallback workers (universal floor)
+### When sub-agents are unavailable or fail
 
-```bash
-#!/usr/bin/env bash
-set -uo pipefail
-SLUG="<slug>"; ROOT="$(pwd)"; SKILL="<abs-path-to-skills/archgen>"
-run_task() { # $1=id  $2=prompt-file
-  local id="$1" pf="$2" log=".archgen/$SLUG/results/$id.log"
-  mkdir -p "$(dirname "$log")"
-  local body; body="$(cat "$pf")
-
-You own exactly the file_ownership globs listed for this task in tasks.yaml. Follow archgen code-standards. On success run: node \"$SKILL/scripts/set-status.mjs\" .archgen/$SLUG/tasks.yaml \"$id\" done ; on failure set-status failed."
-  case "$ARCHGEN_HARNESS" in
-    claude)    claude -p "$body" --output-format json --permission-mode acceptEdits > "$log" 2>&1 ;;
-    opencode)  opencode run "$body" --auto --format json > "$log" 2>&1 ;;
-    codex)     codex exec --sandbox workspace-write --json -o "$log.final" "$body" > "$log" 2>&1 ;;
-    gemini)    gemini --output-format json "$body" > "$log" 2>&1 ;;
-    agy)       agy -p --output-format json --print-timeout 15m "$body" > "$log" 2>&1 ;;
-    *) echo "unknown harness: $ARCHGEN_HARNESS" >&2; return 9 ;;
-  esac
-
-You own exactly: $(node "$SKILL/scripts/impact.mjs" .archgen/$SLUG/tasks.yaml "$id" >/dev/null 2>&1 && echo 'see tasks.yaml file_ownership'). Follow archgen code-standards. On success run: node "$SKILL/scripts/set-status.mjs" .archgen/$SLUG/tasks.yaml "$id" done ; on failure set-status failed." \
-}
-# Wave N: launch all frontier tasks in parallel…
-for t in $(node "$SKILL/scripts/next-tasks.mjs" .archgen/$SLUG/tasks.yaml \
-           | node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>console.log(JSON.parse(d).waves[0].map(t=>t.id).join(" ")))'); do
-  run_task "$t" ".archgen/$SLUG/results/$t.prompt" & pids="$pids $!"
-done
-fail=0; for p in $pids; do wait "$p" || fail=1; done
-exit $fail   # orchestrator inspects statuses before next wave
-```
+Detect first — one of:
+
+- 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).
+
+Then, in order:
 
-Isolation upgrade for Tier 2 when ownership borders are tight:
+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.
+
+Never silently switch harnesses. Never ask permission to fall back for routine
+failures the main agent can simply do itself.
+
+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.
+
+Isolation for native sub-agents when ownership borders are tight:
 
 ```bash
 git worktree add ".worktrees/$id" -b "task-$id"
-# run worker with cwd=.worktrees/$id, then merge task-$id on success
+# point the sub-agent's cwd at .worktrees/$id, then merge task-$id on success
 ```
 
-### Worker prompt contract (both tiers)
+### Worker prompt contract
+
+Every worker receives ALL of:
+
+- task id + title;
+- its acceptance criteria VERBATIM;
+- its file_ownership globs ("edit NOTHING outside these");
+- the code-standards reference (`references/code-standards.md`);
+- instruction to run set-status done/failed immediately upon finishing:
+  `node <skill>/scripts/set-status.mjs .archgen/<slug>/tasks.yaml <id> done|failed`;
+- commit guidance: commit completed work scoped to the owned files;
+- BEFORE writing code run
+  `node <skill>/scripts/plan-graph.mjs <slug-dir-or-tasks.yaml> --node <task-id>`
+  and honor every connected dependency shown;
+- all file paths come from tasks.yaml/architecture.yaml VERBATIM — never
+  reconstruct paths from memory.
+- working state goes under `.archgen/<slug>/.agent/` — execution decisions to
+  `.agent/decisions/`, notes to `.agent/notes/<id>.md` (see
+  references/artifact-templates.md § Agent workspace & artifact location).
+  NEVER create ad-hoc note/context/decision folders at the repo root or
+  anywhere outside `.archgen/`.
 
-Every worker receives: task id+title, its acceptance criteria verbatim, its
-file_ownership globs ("edit NOTHING outside these"), the code-standards
-reference, and the done/failed status-update command. Workers do NOT talk to
-each other; coordination happens only through tasks.yaml state.
+Workers do NOT talk to each other; coordination happens only through
+tasks.yaml state.
 
 ## Failure policy
 
-- Worker exit ≠ 0 OR status=failed → leave it failed. NEVER auto-retry.
+- 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

package/vendor/skills/archgen/references/platforms.md

@@ -69,24 +69,11 @@ Claude Code project-scope servers.
 |---|---|---|---|
 | Claude Code | `Agent` tool + subagent_type; `.claude/agents/*.md` | Yes (default since v2.1.198; cap ~20) | BEST: `isolation: worktree` frontmatter; `/batch` |
 | OpenCode | task/subagent tool + subagent_type | Yes (fg + background) | None in core → use file-ownership discipline or team-mode plugin worktrees |
-| Codex CLI | model-mediated `spawn_agent`; max_depth=1 | Yes but children can't nest | None → prefer top-level parallel `codex exec` + manual git worktrees |
+| Codex CLI | model-mediated `spawn_agent`; max_depth=1 | Yes but children can't nest | None built-in → flatten plans into top-level `spawn_agent` calls (children cannot nest); add manual git worktrees if edits collide |
 | Gemini CLI | subagents-as-tools; `@agent-name` | Yes BUT strictly hub-and-spoke (no nested calls) | None → restrict parallel workers to read-only roles unless given external worktrees |
 | Cursor | Subagents w/ `is_background` frontmatter; `/multitask` | Yes | Opt-in per-subagent worktree or cloud VM |
 | Antigravity | `invoke_subagent` (async by design); `/fork` | Yes | `/fork` workspace separation; per-subagent worktrees UNVERIFIED |
 
-## Headless invocation templates (fallback workers)
-
-```
-claude    claude -p "<prompt>" --output-format json --permission-mode acceptEdits
-opencode  opencode run "<prompt>" --auto --format json
-codex     codex exec --sandbox workspace-write --json -o <out-file> "<prompt>"
-gemini    gemini --output-format json "<prompt>"
-agy       agy -p --output-format json --print-timeout 15m "<prompt>"
-```
-
-Completion signal = process exit (Claude documents 0/non-zero contract).
-NEVER pass secrets as arguments. Feature-detect old binaries via `--version`.
-
 ## Unknown platform procedure
 
 1. WEB SEARCH: `<platform> official docs MCP configuration` and
@@ -94,3 +81,58 @@ NEVER pass secrets as arguments. Feature-detect old binaries via `--version`.
 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.
+
+## 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 (audited 8 codegraph-family tools Aug 2026; local
+binary v1.0.1 empirically confirms). 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 when configured (offered at Step 0).
+- YAML plan graphs → exclusively `scripts/plan-graph.mjs`.
+- Markdown artifact navigation → `scripts/doc-index.mjs`.
+
+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 `doc-index.mjs` inside `.archgen/` — it understands TASK/FR
+reference semantics. Brownfield surveys prefer codegraph once present.
+
+### Codegraph install & index (concrete — researched Aug 2026, v1.0.1)
+
+CodeGraph = `@colbymchenry/codegraph` (npm), CLI `codegraph`, MIT, 100% local.
+It persists a SQLite symbol graph in `.codegraph/` and serves it over MCP. It
+indexes SOURCE symbols only (scope above) — pair with `doc-index.mjs` /
+`plan-graph.mjs` for markdown/YAML. Requires Node 22 or 24 (native SQLite
+bindings; other versions fall back to a 5–10x-slower WASM backend).
+
+Install the CLI (one-time, global):
+- `npm i -g @colbymchenry/codegraph` (any OS with Node), or
+- `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), or
+- zero-install: `npx @colbymchenry/codegraph`.
+
+Wire the harness (writes MCP config + instructions — INSTALL-MCP approval gate):
+- `codegraph install --yes` (auto-detect agents, global)
+- `codegraph install --target=<agent> --yes` (explicit harness)
+- `codegraph install --target=auto --location=local --yes` (project-local)
+- `codegraph install --print-config <agent>` (preview snippet, no writes)
+- Manual config shape: assets/mcp-template.json (stdio `codegraph serve --mcp`
+  or npx `-y @colbymchenry/codegraph mcp`).
+
+Index the project (per project; creates `.codegraph/` + builds the graph):
+- `codegraph init` (add `--yes` to skip prompts); one-shot bootstrap:
+  `codegraph install --yes --init`. Auto-syncs on file change thereafter.
+- `codegraph status` to verify; `codegraph uninit` removes the index;
+  `codegraph uninstall` de-wires the agents; `codegraph upgrade` updates.
+
+`.codegraph/` is deterministic and small — committing it gives teammates the
+index on first checkout (team recommendation); git-ignore it for solo repos.
+Never point two OSes (Windows + WSL) at one `.codegraph/`.
+
+Agent flow: detect `.codegraph/` at repo root. Present → use `codegraph_explore`
+for source navigation. Absent → offer once (INSTALL-MCP approval pattern,
+recommendation-first), run the commands above on approval; on decline use
+Glob+Grep.