archgen-skill 0.1.1 → 0.1.2

package/lib/node_modules/archgen-mcp/assets/references/artifact-templates.md

@@ -0,0 +1,120 @@
+# Artifact templates — copy, fill, never invent structure
+
+## Provenance header (SHOULD on every NEW tasks.yaml / architecture.yaml)
+
+Begin `tasks.yaml` and `architecture.yaml` with the three YAML comment lines returned by `archgen_plan{action:'scaffold'}`:
+
+```yaml
+# schema_version: 1
+# generator: archgen v1.2.3
+# generated_at: 2026-08-26T09:00:00.000Z
+```
+
+**Version token rules (NEVER guess or hand-type a version):**
+1. Paste the header generated by `scaffold` verbatim.
+2. When backfilling manually, resolve version strictly in this order:
+   a. Exact `MAJOR.MINOR.PATCH` from `.archgen-version` adjacent to `SKILL.md`.
+   b. Semver `"version"` field from adjacent `archgen.config.json`.
+   c. Omit version token: `# generator: archgen`.
+3. `npx archgen-skill migrate --apply` (`--check` dry-run default) snapshots existing files to `.archgen/.backup/<ts>/migrate/` and backfills missing headers idempotently.
+
+All files created in a single run share one ISO-8601 `generated_at` timestamp at line 1–3.
+
+## Self-containment rules (anti-hallucination)
+
+Artifacts are executed by sub-agents with zero conversation history. Enforce strictly:
+
+1. **Full repo-root-relative paths:** Every task step, `file_ownership` glob, artifact, and verification command MUST use complete paths (`src/features/catalog/api/routes.ts`), sourced exclusively from `architecture.yaml` (`structure:`/`owns[]`) or surveyed code. Never use bare filenames.
+2. **Traceable naming:** Every file, symbol, table, and env var must cite its governing `naming_conventions` key (e.g., `camelCase per naming_conventions.symbol_casing`). Add missing keys to `architecture.yaml` before citing them.
+3. **Zero chat dependency:** `.archgen/<slug>/` must be 100% self-contained. Unwritten facts do not exist.
+4. **Forbidden phrases:** Never write `"as discussed"`, `"the usual pattern"`, `"same as before"`, or `"see chat"`. Cite concrete artifact paths/keys instead.
+5. **Artifact-relative cross-references:** Point to contracts rather than restating them (e.g., `see ../architecture.yaml data_contracts.orders` or `../architecture.yaml api_contracts.payments.request_payload`).
+6. **GitHub-exact heading anchors:** Lowercase, strip punctuation (keep `-` and `_`), and convert every whitespace character to `-` without collapsing runs (`## TASK-02 — Auth API` $\rightarrow$ `#task-02--auth-api`). Broken anchors block verification.
+7. **Verifier-compatible IDs:** `archgen_plan{action:'verify'}` rejects unknown `UPPERCASE-NN` tokens in `plans/*.md`. Cite `FR-<MODULE>-nn` IDs in `tasks.yaml` acceptance criteria and `docs/prd.md`; inside `plans/*.md`, link via anchor (`../docs/prd.md#fr-catalog-01`). Every `tasks.yaml` ID must appear in `plans/*.md` (bidirectional coverage check).
+
+## Plan depth by scope class
+
+Select ONE scope class before authoring. Always fetch the required file set and skeletons from the tool:
+
+```
+archgen_plan { action: 'scaffold', scope: 'SMALL' | 'MEDIUM' | 'LARGE', slug: '<slug>' }
+```
+
+Adding or omitting files outside the scaffold output is a right-sizing defect. Authoring depth per class:
+
+- **SMALL** (localized change): Lean plan note only (no Context, PRD, or diagrams; full repo-root paths still mandatory):
+  ```markdown
+  # <feature> — plan note (SMALL)
+  Intent: <one paragraph>
+  Tasks: see tasks.yaml entries <ids>
+  Risks: <bullets or none>
+  ```
+- **MEDIUM**: Plan includes:
+  - **Context** (2–4 paragraphs max: why now, current state, delta).
+  - **Per-task sections** (`## <id> — <title>`): Approach (short bullets), **Edge cases** ($\ge 3$ bullets feeding the edge-case matrix), and **Out-of-scope**.
+  - **Verification steps**: Ordered, runnable, repo-root-relative commands. No PRD or diagrams unless structural changes require them.
+- **LARGE / greenfield-from-scratch**: Full stack—PRD (~1 page/module) + expanded `architecture.yaml` (`naming_conventions`, `data_contracts`, `api_contracts`, `environment_matrix`) + per-task edge-case matrices + per-module & integration Mermaid diagrams ($\le 15$ nodes each) + MEDIUM plan sections.
+
+## Structural correctness — verifier-enforced authoring rules
+
+- **Topological waves:** Wave / `parallel_group` labels MUST match the `depends_on` topological order (`archgen_plan{action:'graph', format:'mermaid'}`). Dependents never precede or share a wave with prerequisites.
+- **`artifacts` $\subseteq$ `file_ownership`:** Every path in `artifacts` must match the task's `file_ownership` globs.
+- **Runnable verification commands:** Repo-root-relative (no `../` or `--plan .`), specifying exact commands, flags, sample sizes, and thresholds.
+- **Restricted YAML subset:** Block mappings, block sequences, and single-line flow collections (`["a/**", "b.ts"]`, `{id: A}`) ONLY. **BANNED:** block scalars (`|` / `>`), duplicate keys, and multi-line flow collections.
+- **Targeted `tasks.yaml` edits:** Apply small, surgical edits or a clean full regeneration—never large multi-region patches.
+
+## Agent workspace & artifact location — the two-tier rule
+
+- **INSIDE `.archgen/<slug>/`** (self-contained planning & execution state):
+  - `tasks.yaml`, `plans/`, `architecture.yaml`, `answers.yaml`, `codebase-map.md`.
+  - `docs/prd.md` (planning artifact defining `FR-*` IDs validated by `archgen_docs`).
+  - `decisions/NNNN-title.md` (formal feature ADRs).
+  - `.agent/` (process state excluded from doc validation):
+    - `.agent/decisions/NNNN-<slug>.md` — runtime sub-agent implementation decisions.
+    - `.agent/learnings.md` — append-only discovered repo conventions.
+    - `.agent/notes/<task-id-or-topic>.md` — worker/survey/investigator working notes.
+    - `.agent/reports/<verifier|reviewer|investigate>-<round>.md` — gate & investigation reports.
+    - `.agent/resume.md` — $\le 10$-line compaction re-entry snapshot (slug, wave index, done/failed/blocked IDs, `archgen_tasks{action:'next'}`, remaining task plan sections), updated after every wave.
+- **OUTSIDE `.archgen/`** (product deliverables written to task `file_ownership` paths):
+  - Source code (`src/...`) and shipped user/operator documentation (`README.md`, API docs, runbooks).
+  - *Durable ADRs:* Promote repo-wide architectural decisions from `.archgen/<slug>/decisions/` to the project's canonical ADR directory (`docs/adr/`). Supersede rather than deleting/renumbering accepted ADRs.
+
+## architecture.yaml (LARGE scope)
+
+Generated via `archgen_plan{action:'scaffold', scope:'LARGE'}`. Authoring rules for the four anti-hallucination contract blocks:
+- Keep each module/domain contract block concise (~10–20 lines; split before exceeding 40 lines).
+- `modules[].depends_on_modules` MUST be a DAG (drives task `depends_on`).
+- `key_interfaces` lists ONLY exports consumable by other modules.
+- `environment_matrix` vars must fail fast if unparsed in `src/config/`.
+
+## Product requirements document (PRD) — LARGE/greenfield
+
+Generated via `scaffold` (`docs/prd.md`) and authored BEFORE `tasks.yaml` (~1 bullet-dense page per module):
+- `FR-<MODULE>-nn` IDs are **immutable** once referenced by `tasks.yaml`.
+- NFRs require concrete numbers (latency, RPS, compliance standard); adjectives fail verification.
+- Success metrics require `<baseline> -> <target> within <window>`.
+
+## tasks.yaml (canonical shape)
+
+Generated via `scaffold` (`schemas/tasks.schema.json`, `schema_version: 1`):
+- `depends_on` lists prerequisite task IDs (never dependents).
+- Same-wave `file_ownership` globs must be strictly disjoint.
+- `acceptance` criteria must be objectively checkable and cite edge-matrix rows (`E1`–`En`) and `FR-<MODULE>-nn` IDs (for LARGE).
+
+## Edge-case matrix (per task, MEDIUM+)
+
+Generated via `scaffold` and placed in each MEDIUM/LARGE task's plan section ($\le 10$ rows per table; split by concern if larger):
+- **Mandatory coverage classes:** empty/null, boundary values, authz denied, concurrent/conflicting write, failure/retry path, i18n/formatting edge.
+- **Infra tasks (migrations, deploys, queues) add:** partial-failure recovery, rollback path.
+- **Traceability:** Every row maps to `Covered by` (`<task-id>#<1-based acceptance index>`); zero orphan rows.
+
+## ADR template & Mermaid snippets
+
+Generated via `scaffold` (`decisions/NNNN-title.md` and `docs/mermaid-snippets.md`).
+
+## Per-module diagram (LARGE)
+
+Generated via `scaffold`. Authoring rules:
+- One flowchart per `modules:` entry showing internal components ($\le 6$ nodes) plus inbound `depends_on_modules` edges (consumer $\rightarrow$ provider).
+- One system integration diagram wiring modules as atomic nodes (no module internals).
+- **Hard limit:** $\le 15$ nodes per diagram (split if larger).

package/lib/node_modules/archgen-mcp/assets/references/interview.md

@@ -0,0 +1,161 @@
+# Interview playbook — requirement elicitation
+
+Goal: achieve complete, conflict-free requirements in minimal round-trips. Batch 3–5 questions per turn, infer aggressively from context, ask only material decision-forks, and state derivative choices as veto-able defaults.
+
+## How to ask
+
+- **Tool-first, inline-fallback:** Use the harness's interactive question/choice tool if available; otherwise present numbered inline options.
+- **Recommendation-first:** Lead every question with your recommended option tagged `(recommended)` + brief rationale. Never present bare options.
+- **Ask forks, state decisions:** Ask ONLY questions that materially branch the architecture. For derivative choices, declare: *"I'll use X because Y — let me know if you prefer Z."*
+- **Scale volume to scope:** Round caps are ceilings, not targets. For simple/SMALL prompts, ask 1–2 core forks and infer the rest.
+
+*Example:*
+> Rollout strategy?
+> 1. Feature flag + staged rollout **(recommended)** — zero impact on active users
+> 2. Immediate cutover — simpler, higher risk
+> 3. Versioned API alongside — if legacy clients cannot upgrade
+> Reply 1–3, or "ok" to accept recommended.
+
+## Round 0 — calibration exchange (skippable)
+
+Infer from the prompt and repo first; ask only if genuinely ambiguous (skip entirely for SMALL/simple prompts or when already stated):
+1. **Target scale:** Prototype, MVP, or production-bound? (State inference + 1-line rationale for confirmation).
+2. **Team & tooling constraints:** Solo vs team, existing CI/lint/style conventions?
+3. **Timeline pressure:** None, moderate, or crunch?
+
+Record under `calibration:` in `answers.yaml`.
+
+## Step 1 — classify intent (decide during round 1)
+
+Classify into ONE `intent_class`, state it in one sentence, and record in `answers.yaml`:
+
+| `intent_class` | Signal | Elicitation Strategy | Max Rounds (incl. R0) | Default `scope_class` |
+|---|---|---|---|---|
+| `GREENFIELD-SYSTEM` | Net-new system; no host repo | Full PRD-grade discovery | $\le 6$ | `LARGE` |
+| `GREENFIELD-MODULE` | Net-new module in existing repo | Infer from host repo first; targeted forks | $\le 3$ | `MEDIUM` |
+| `BROWNFIELD-FEATURE` | Additive behavior in existing repo | Survey first; ask only unresolved gaps ($\le 5$ Qs) | $\le 3$ | `MEDIUM` / `SMALL` |
+| `BROWNFIELD-CHANGE` | Modify existing behavior in place | Survey first; diff current vs target behavior | $\le 3$ | `SMALL` |
+
+Infer `scope_class` (`SMALL`/`MEDIUM`/`LARGE`), state with 1-line reasoning, and let the user confirm or override. Never interrogate brownfield tasks with greenfield PRD questions.
+
+## GREENFIELD-SYSTEM — professional discovery (≤6 rounds)
+
+Tag recorded answers with `feeds:` targets for downstream traceability.
+
+### R1 — problem, users, success → PRD
+1. Core problem, target audience, and explicit non-goals? (`feeds: prd.problem|prd.non_goals`)
+2. 1–3 primary personas: role, job-to-be-done, operating environment? (`feeds: prd.personas`)
+3. Measurable success metrics (activation, latency, error rate—no adjectives)? (`feeds: prd.metrics`)
+
+### R2 — shape & module decomposition → architecture.yaml `modules`
+4. Confirm inferred tech stack + hosting target? (`feeds: prd.constraints`)
+5. External integrations (auth, payments, messaging, 3rd-party APIs)? (`feeds: prd.integrations`)
+6. **Strawman module map:** Propose candidate modules (`name — responsibility`) and ask user to add, merge, split, or rename until agreed. (`feeds: arch.modules`)
+
+### R3 — data & API sketches → `data_contracts`, `api_contracts`
+7. Core entities, key fields, and relationships (`belongs-to`/`has-many`)? (`feeds: arch.data_contracts`)
+8. Primary API operations (5–10 core `VERB + resource` endpoints/actions)? (`feeds: arch.api_contracts`)
+
+### R4 — NFRs with numbers → PRD
+9. Performance budgets: p95 latency, peak RPS/throughput? (`feeds: prd.nfrs`)
+10. Scale targets: active users, requests/day, annual data volume? (`feeds: prd.nfrs`)
+11. Security/compliance (GDPR/HIPAA/PCI), i18n locales, accessibility target (e.g., WCAG 2.2 AA)? (`feeds: prd.nfrs`)
+
+### R5 — environment & naming → `environment_matrix`, `naming_conventions`
+12. Environments (dev/staging/prod), secret management, deploy cadence? (`feeds: arch.environment_matrix`)
+13. Existing naming, domain glossary, or brand casing rules (`none` is valid)? (`feeds: arch.naming_conventions`)
+
+### R6 — close-out → PRD
+14. Explicit out-of-scope items excluded from this build? (`feeds: prd.out_of_scope`)
+15. Top 2 known technical or product risks? (`feeds: prd.risks`)
+
+Present the finalized module map + numeric NFRs for confirmation. `[wait for user]`
+
+### Traceability — `feeds:` tags
+
+Valid literal `feeds:` targets (join multiple with `|`, e.g., `feeds: prd.goals|arch.modules`):
+- **PRD:** `prd.problem`, `prd.goals`, `prd.non_goals`, `prd.personas`, `prd.metrics`, `prd.nfrs`, `prd.constraints`, `prd.integrations`, `prd.risks`, `prd.out_of_scope`
+- **Architecture:** `arch.modules`, `arch.data_contracts`, `arch.api_contracts`, `arch.environment_matrix`, `arch.naming_conventions`
+
+## GREENFIELD-MODULE — net-new inside an existing system (≤3 rounds)
+
+Infer from the host repo first, then confirm:
+1. Host touchpoints: which existing modules does it import from or expose interfaces to? (`feeds: arch.modules`)
+2. Data & API delta: new entities, events, or endpoints vs existing ones? (`feeds: arch.data_contracts|arch.api_contracts`)
+3. NFRs: inherit host perf/a11y/i18n baselines or define custom targets? (`feeds: prd.nfrs`)
+4. Confirm adherence to host `naming_conventions`? (`feeds: arch.naming_conventions`)
+
+## BROWNFIELD classes — survey BEFORE questioning (mandatory)
+
+Execute the codebase survey (`SKILL.md` BROWNFIELD steps 1–2) to produce `.archgen/<slug>/codebase-map.md` BEFORE asking questions. Never ask what the code already answers—cite the file path and confirm.
+
+### BROWNFIELD-FEATURE (additive; max ~5 questions, 1 batched message)
+1. Target acceptance behavior and critical edge cases not evident from code?
+2. Backward-compatibility requirements for existing data/clients?
+3. Rollout mechanism (feature flag, staged, immediate)?
+4. Protected paths outside `codebase-map.md` that must not be modified?
+5. Any corrections to `codebase-map.md`?
+
+### BROWNFIELD-CHANGE (behavior modification; ≤3 rounds)
+1. Exact behavioral diff: current vs desired behavior, plus invariants that must remain unchanged?
+2. Migration path: in-place update, parallel versioned endpoint, or breaking cutover?
+3. Verification criteria proving legacy behavior is removed and new behavior holds?
+
+## Conflict detection
+
+Immediately surface contradictions (scale vs budget, feature vs technical constraint, requirement vs `codebase-map.md`) one at a time:
+*"I see a tension between X and Y. Which takes precedence?"* `[wait for user]`
+
+## Token discipline
+
+- Batch 3–5 questions per turn; never ping-pong single questions.
+- Respect round ceilings (`GREENFIELD-SYSTEM` $\le 6$, all others $\le 3$ including R0).
+- Never re-ask facts provided in the prompt, calibration, or `codebase-map.md`.
+
+## Answers-file format (machine-readable, enables non-interactive runs)
+
+When `.archgen/<slug>/answers.yaml` is present and valid, treat it as authoritative input and skip conversational rounds. Generate its skeleton via `archgen_plan{action:'scaffold'}`:
+
+```yaml
+scope_class: MEDIUM              # SMALL | MEDIUM | LARGE (REQUIRED by SKILL.md)
+intent_class: GREENFIELD-SYSTEM  # optional: GREENFIELD-SYSTEM | GREENFIELD-MODULE | BROWNFIELD-FEATURE | BROWNFIELD-CHANGE
+calibration:                     # optional
+  scale: production              # prototype | mvp | production
+  teamConstraints: solo dev, repo lint rules apply
+  pressure: medium               # low | medium | high
+problem: one-line problem statement
+success_criteria:
+  - text: measurable outcome
+    feeds: prd.metrics
+constraints:
+  - must-not-change item # feeds: prd.constraints
+non_goals:                       # optional (GREENFIELD-SYSTEM)
+  - multi-tenant accounts
+personas:                        # optional (GREENFIELD-SYSTEM)
+  - role: shopper
+    goal: find and buy in under two minutes
+nfrs:                            # optional; numeric values required for GREENFIELD-SYSTEM
+  - "p95 API latency < 300ms at 50 rps"
+  - "locales: en, de"
+  - "accessibility: WCAG 2.2 AA"
+out_of_scope: []                 # optional
+stack:
+  language: typescript
+  runtime: node
+  hosting: vercel
+integrations: [auth0, stripe]
+compliance: []
+risks:
+  - known risk text
+```
+
+All fields added beyond `scope_class`, `problem`, `success_criteria`, `constraints`, `stack`, `integrations`, `compliance`, and `risks` are optional and backward-compatible. `feeds:` tags may appear as object keys or trailing `# feeds:` comments.
+
+## Completion test
+
+Elicitation is complete only when ALL hold:
+- All applicable intent-class questions are answered or explicitly waived.
+- Inferred decisions are confirmed or corrected by the user.
+- Zero unresolved conflicts remain.
+- `scope_class` (`SMALL`/`MEDIUM`/`LARGE`) and `intent_class` are agreed and recorded in `answers.yaml`.
+- For `GREENFIELD-SYSTEM`: strawman module map is agreed AND every NFR contains a concrete numeric target.

package/lib/node_modules/archgen-mcp/assets/references/mcp-and-skills.md

@@ -0,0 +1,62 @@
+# MCP installation and skill fetching
+
+## archgen's own MCP server — already handled
+
+`npx archgen-skill init` (or `install`) automatically wires `archgen-mcp` and CodeGraph into every detected harness. Never configure them manually. If `archgen_*` tools are missing, run `npx archgen-skill init` at the repo root and ask the user to reload the harness (`§platforms/mcp-configuration`).
+
+The procedures below govern **external** MCP servers (e.g., `context7`) and capability skills.
+
+## INSTALL-MCP procedure (approval-gated)
+
+1. **Identify platform:** Call `archgen_setup{action:'harness_info'}` (or inspect `§platforms/mcp-configuration`) for the config path, top-level key (`mcpServers` / `servers` / `mcp` / `context_servers`), and URL field name (`url` / `serverUrl` / `httpUrl`).
+2. **Discover:** Web-search current official installation docs for the target MCP server and harness. Never guess commands or config schemas.
+3. **Declare scope:** State whether the install is **GLOBAL** (recommended for cross-project tools like CodeGraph) or **HARNESS-SPECIFIC** (project/platform-local).
+4. **Prefer native CLI** (matching chosen scope):
+   - Claude Code: `claude mcp add --scope project --transport http <name> <url>`
+   - Codex: `codex mcp add <name> --url <url>` or `codex mcp add <n> -- <cmd> <args>`
+   - Gemini CLI: `gemini mcp add -s project -t http <name> <url>`
+5. **Approval gate:** If editing config files directly, show the exact config diff (matching `packages/mcp/assets/mcp-template.json` conventions) and **WAIT FOR EXPLICIT USER APPROVAL** before writing.
+6. **Apply & verify:** Write config, apply platform restart/reload semantics, and verify tool visibility.
+
+## FETCH-SKILL procedure
+
+Capability-skill loading is **MANDATORY** whenever planned work matches a registry domain (especially `ui-skills` with `policy: "required"` for UI, frontend, design, animation, component, or landing-page tasks).
+
+0. **Execution points (runs TWICE per matched task):**
+   - **Pre-planning scan:** During GENERATE / BROWNFIELD / UPDATE, match every task before finalizing the plan.
+   - **Pre-dispatch verification:** Immediately before dispatching a worker, verify required skills are installed.
+1. **MATCH:** Call `archgen_skills{action:'match', title, summary, fileOwnership}`. Uses case-insensitive whole-word (`\b`) matching (e.g., `"ui"` matches `"redesign the ui"` or `"ui-skills"`, never `"build"` or `"guide"`). Any hit with `policy: "required"` makes steps 2–5 mandatory.
+2. **RESOLVE:** `archgen_skills` checks all project, harness, and global skill directories (`<project>/.agents/skills/<slug>/SKILL.md` and `~/.agents/skills/<slug>/`) and reports installation status and path.
+3. **INSTALL (if missing):** Skip if already installed (cache hit). Otherwise call:
+   ```
+   archgen_skills { action: 'install', skillId, harness, approve: true }
+   ```
+   This invokes `npx -y skills add <repo> --skill <slug> --agent <agent> --yes --json` to install the single matched skill non-interactively (never a full repo bundle) and verifies the resulting file path.
+4. **INTEGRATE (inline into worker contract):** Call `archgen_tasks{action:'contract', tasksYaml, taskId}`. It automatically extracts the normative rules (`MUST` / `SHOULD` / `NEVER`), file path, and section index from every matched required skill and embeds them directly into the worker prompt so workers cannot overlook them.
+   - To inspect a skill manually, call `archgen_skills{action:'load', skillId}` (full rules + index), `{action:'digest', skillId}` (index only), or `{action:'load', skillId, section}` (single section).
+5. **AUDIT:** Every worker completion report MUST include an explicit compliance line:
+   - `Skill compliance: followed <skill-slug> (<path/to/SKILL.md>)`
+   - `Skill compliance: NOT followed — <reason>`
+6. **MISSING CAPABILITY:** If a task clearly requires an specialized domain absent from the registry, web-search reputable skill repositories, propose the candidate to the user, and add to the registry ONLY after explicit user approval.
+
+## The registry
+
+Managed by `archgen_skills` at `packages/mcp/assets/skill-registry.json` (never edit directly):
+
+```json
+{
+  "id": "ui-motion",
+  "slug": "fixing-motion-performance",
+  "domain": "Motion",
+  "family": "ui-skills",
+  "repo": "ibelick/ui-skills",
+  "purpose": "Motion and animation performance — jank-free transitions.",
+  "matches": ["animation", "motion", "transition"],
+  "policy": "required"
+}
+```
+
+- `domain`: Human-readable label injected into the worker contract (`"Motion work: follow ..."`).
+- `matches[]`: Case-insensitive whole-word tokens matched against task `title`, `summary`, and `file_ownership`.
+- `policy`: `"required"` (mandatory pre-planning + pre-dispatch enforcement) or `"on-demand"` (loaded only when explicitly requested).
+- **Granular install:** Each domain maps to and installs ONE specific skill (`--skill <slug>`), never an entire skill family.

package/lib/node_modules/archgen-mcp/assets/references/orchestration.md

@@ -0,0 +1,149 @@
+# Orchestration playbook — survey, verify, dispatch
+
+Sub-agent briefs and wave-execution rules for the orchestrator (`SKILL.md`). Workers never read this file.
+
+## §survey — brownfield codebase analysis brief
+
+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'}` 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.
+
+### 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
+
+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
+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
+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
+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 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).
+
+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.
+
+## §investigate — root-cause protocol
+
+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.
+
+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 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.
+
+### WHEN to dispatch a sub-agent — and when NOT to
+
+**Sub-agents are for bounded implementation/analysis work, NEVER for state lookups:**
+
+| 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'`) |
+
+### Reuse the agent's session — NEVER re-dispatch for the same context
+
+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.
+
+### Parallel dispatch — no overlap, and never more than three at once
+
+**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.
+
+### 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`.
+
+### When sub-agents are unavailable or fail
+
+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"
+# run sub-agent in .worktrees/$id, then merge task-$id on completion
+```
+
+### 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`.
+
+**Pre-dispatch check:** Inspect `contract.warnings`. Never dispatch a task with missing acceptance criteria, empty `file_ownership`, or an uninstalled required skill.
+
+## Failure policy
+
+- **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/lib/node_modules/archgen-mcp/assets/references/platforms.md

@@ -0,0 +1,81 @@
+# Platform capability matrix (November 2026)
+
+Authoritative platform capability data is served dynamically by `archgen_setup{action:'harness_info'}` from `packages/mcp/assets/platform-capabilities.json`.
+
+## Harness capabilities
+
+Query platform capabilities directly via the tool rather than static tables:
+```
+archgen_setup { action: 'harness_info' }                   # auto-detect current harness
+archgen_setup { action: 'harness_info', harness: 'claude' } # query specific harness
+```
+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
+
+`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
+
+`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` |
+| `.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 -->` |
+
+Never hand-edit the `AGENTS.md` registry table (`| Feature | Status | Updated |`); update it exclusively via `archgen_registry{action:'update'}`.
+
+## MCP configuration
+
+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 (the `.vscode/mcp.json` workspace format)
+  - `mcp.servers.<id>`: OpenCode (nested under `mcp.servers`, never flat `mcp.<id>`)
+  - `context_servers`: Zed
+  - `[mcp_servers.<id>]`: Codex CLI (TOML)
+- **VS Code reads TWO formats.** The VS Code format is `servers` in
+  `.vscode/mcp.json`; the PORTABLE format is `mcpServers` in the Copilot
+  user's `mcp-config.json` — `$COPILOT_HOME/mcp-config.json`, or
+  `~/.copilot/mcp-config.json`. Copilot harness sessions read the portable
+  format directly, and `COPILOT_HOME` REPLACES the default (VS Code checks
+  only one of the two). The global wiring therefore goes to the Copilot home
+  in the portable format, so VS Code stable, VS Code Insiders, the Copilot
+  CLI and every workspace see the same server.
+- **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
+
+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` (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
+
+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`, 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).