archgen-skill 0.0.5 → 0.0.7

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

@@ -1,275 +0,0 @@
-# Interview playbook — requirement elicitation
-
-Goal: complete, conflict-free requirements in the FEWEST round-trips.
-Batch 3–5 questions per message. Never ask what you can infer — ask only
-decision-forks, state everything else as a veto-able decision (§ How to ask).
-
-## How to ask
-
-- **Tool-first, options-fallback.** Use your harness's ask-question /
-  interactive multiple-choice tool when one exists; no such tool → ask inline
-  with labeled options. Same content either way.
-- **Recommendation-first.** Every option set leads with YOUR best judgment
-  tagged `(recommended)`, then alternatives. The user accepts the
-  recommendation by default and may override — never present bare options
-  without a recommendation.
-- **Ask forks, state decisions.** Ask ONLY the few decision-forks that
-  materially branch the plan. Everything derivative: DECIDE autonomously and
-  announce — "I'll use X because Y — say so if you'd rather Z" — so the user
-  can veto without being interrogated.
-- **Volume scales with scope.** Round caps (§ Step 1) are MAXIMA, not targets:
-  SMALL/simple prompt → at most 1–2 core questions, decide the rest; MEDIUM →
-  the targeted set; LARGE — or an experienced engineer signaling they want
-  control → the fuller discovery set.
-
-Worked example (recommendation-first, inline fallback form):
-
-> Rollout strategy?
-> 1. Feature flag + staged rollout **(recommended)** — existing users unaffected
-> 2. Immediate cutover — simpler, riskier
-> 3. Versioned API alongside — only if existing clients break
-> Reply 1–3, or just "ok" to accept the recommendation.
-
-## Round 0 — calibration exchange (skippable)
-
-Two or three rapid items, asked once at the very start — each INFERRED first
-(§ How to ask), asked only when genuinely ambiguous:
-
-1. Rough scale: prototype, MVP, or production-bound? INFER from the opening
-   message + repo context; state the inference + one line of reasoning and
-   let the user confirm or correct. Ask open-ended ONLY when genuinely
-   ambiguous.
-2. Team size + convention constraints? (solo? existing lint/CI/style guides?)
-3. Deadline pressure: none, moderate, crunch?
-
-Purpose is ONLY to pick question-set depth and right-size later verification
-rigor — never to collect requirements. SKIP the whole exchange when the user's
-opening message already answers these items (e.g. "quick prototype by
-Friday"); SMALL/simple prompts skip calibration entirely and go straight to
-their 1–2 core forks (§ How to ask). Record whatever was captured under
-`calibration:` in answers.yaml.
-
-## Step 1 — classify intent (decide during round 1)
-
-From the opening message + calibration, decide ONE intent class, state it to
-the user in one sentence, and record it as `intent_class` in answers.yaml:
-
-| intent_class | Signal | Question depth | Round cap |
-|---|---|---|---|
-| GREENFIELD-SYSTEM | net-new product/system from scratch; no host repo | full PRD-grade discovery | ≤6 |
-| GREENFIELD-MODULE | net-new capability inside an existing system/repo | targeted; infer from host repo first | ≤3 |
-| BROWNFIELD-FEATURE | existing repo, additive behavior | survey-first; ask only survey gaps (max ~5 questions) | ≤3 |
-| BROWNFIELD-CHANGE | modify existing behavior in place | survey-first; diff current vs desired | ≤3 |
-
-Never interrogate a BROWNFIELD-FEATURE with PRD-grade questions — token waste,
-user annoyance. Round caps INCLUDE round 0 when it runs.
-
-Default `scope_class` from the intent class (user's choice wins — scope_class
-is agreed in GENERATE step 1 and recorded in answers.yaml):
-GREENFIELD-SYSTEM→LARGE, GREENFIELD-MODULE→MEDIUM,
-BROWNFIELD-FEATURE→MEDIUM/SMALL, BROWNFIELD-CHANGE→SMALL.
-
-Scale is INFERRED, not asked: derive scope_class from the opening message +
-repo context + the class above, state it with one line of reasoning, and let
-the user confirm or correct. Ask about scale ONLY when genuinely
-ambiguous/confused. Small/simple prompts: skip heavy calibration, ask only
-the 1–2 core forks (§ How to ask), decide the rest.
-
-## GREENFIELD-SYSTEM — professional discovery (≤6 rounds)
-
-Creating a system from scratch demands PRD-grade inputs. Each round below
-lists its questions and where the answers land (`feeds:` tags — see
-Traceability).
-
-### R1 — problem, users, success → PRD
-
-1. What problem does this solve, for whom — and what is explicitly NOT a goal?
-2. Who uses it? Sketch 1–3 personas: role, key job-to-be-done, environment.
-3. What does success look like — measurable (activation, conversion,
-   time-saved, error rate)? Adjectives are not metrics.
-
-### R2 — shape & module decomposition → architecture.yaml `modules`
-
-Infer stack/hosting from stated preferences, then confirm:
-
-4. Stack + hosting target correct? (state your inference)
-5. Integration surfaces: auth, payments, email, existing APIs?
-
-Then PROPOSE a strawman module map from the domain talk — one line per
-candidate module as `name — responsibility` (mirroring `modules[]`:
-name/responsibility/owns) — and ask the user to react:
-
-6. React to this strawman module map: [list]. What is missing, misnamed, or
-   should be merged/split? Iterate until agreement — this seeds
-   architecture.yaml `modules`.
-
-### R3 — data & API sketches → `data_contracts`, `api_contracts`
-
-7. Core data entities and relationships — one line each: Entity — key fields —
-   belongs-to / has-many? (seeds `data_contracts`)
-8. Primary API surface: the 5–10 operations users/systems perform, verb +
-   resource? (seeds `api_contracts`)
-
-### R4 — NFRs with numbers → PRD
-
-Numbers or it didn't happen — reject "fast"/"scalable" without figures.
-
-9. Performance budgets: p95 latency, throughput at peak?
-10. Scale targets: users, reqs/day, data growth per year?
-11. Security/compliance checklist level (GDPR/HIPAA/PCI)? i18n locales?
-    Accessibility level (e.g. WCAG 2.2 AA)?
-
-### R5 — environment & naming → `environment_matrix`, `naming_conventions`
-
-12. Environment/deploy reality: which environments exist (dev/staging/prod),
-    hosting, config/secrets handling, deploy cadence? (seeds
-    `environment_matrix`)
-13. Naming/brand conventions that already exist: product-name casing, domain
-    terms to preserve, UI copy language(s)? (seeds `naming_conventions`;
-    "none" is a valid answer)
-
-### R6 — close-out → PRD
-
-14. Explicit out-of-scope list — adjacent things on record as NOT in this build?
-15. Top 2 risks you already know about?
-
-Close by presenting the agreed module map + captured NFR numbers for final
-confirmation ([wait for user]).
-
-### Traceability — `feeds:` tags
-
-Every recorded answer MAY carry a `feeds:` tag naming the artifact section it
-lands in. Keep the vocabulary literal — downstream templates consume these
-exact names:
-
-- PRD sections: `prd.problem`, `prd.goals`, `prd.non_goals`, `prd.personas`,
-  `prd.metrics`, `prd.nfrs`, `prd.constraints`, `prd.integrations`,
-  `prd.risks`, `prd.out_of_scope`
-- architecture.yaml keys: `arch.modules`, `arch.data_contracts`,
-  `arch.api_contracts`, `arch.environment_matrix`, `arch.naming_conventions`
-
-Multiple targets join with `|`, e.g. `feeds: prd.goals|arch.modules`.
-
-## GREENFIELD-MODULE — net-new inside an existing system (≤3 rounds)
-
-Infer first from the host repo (structure, conventions, neighboring modules),
-confirm second:
-
-1. Where does it plug in — which host modules does it read from / expose to?
-2. Contract with the host: data it consumes/produces, APIs or events it
-   exposes? (seeds `data_contracts` / `api_contracts` deltas)
-3. Inherited vs new NFRs: follow host perf/a11y/i18n baselines or set new ones?
-4. Naming follows host conventions — confirm? (seeds `naming_conventions`)
-
-## BROWNFIELD classes — survey BEFORE questioning (mandatory)
-
-Run the survey first (SKILL.md BROWNFIELD steps 1–2): prefer the codegraph MCP
-(`codegraph_explore`) when configured, else structured glob/grep; produce or
-update `.archgen/<slug>/codebase-map.md`. Then ask ONLY what the survey could
-not answer. NEVER ask what a file already answers — quote the file and ask for
-confirmation instead.
-
-### BROWNFIELD-FEATURE (additive; max ~5 questions, one batched message)
-
-Ask only unresolved gaps, typically:
-
-1. Acceptance criteria the code cannot reveal — exact expected behavior, edge
-   cases that matter.
-2. Back-compat expectations for existing records or clients.
-3. Rollout preference: feature flag, staged, immediate?
-4. Must-NOT-touch paths beyond what the map shows?
-5. Anything the codebase-map got wrong?
-
-### BROWNFIELD-CHANGE (behavior modification; ≤3 rounds)
-
-Survey focus: current behavior + blast radius (callers, tests, consumers).
-
-1. Current vs desired behavior — precise diff, including what must stay.
-2. Compatibility: migrate in place, version alongside, or breaking change?
-3. Acceptance for "changed": how do we prove old behavior is gone and the new
-   behavior holds?
-
-## Conflict detection
-
-While collecting, watch for and surface immediately:
-- Scale vs budget contradictions ("1M users" + "cheapest VPS")
-- Feature vs constraint collisions ("real-time" + "no websockets allowed")
-- Requirement vs existing-architecture conflicts (brownfield: check codebase-map)
-
-Format: "I see a tension between X and Y. Which wins?" — one per message,
-resolve before proceeding. [wait for user]
-
-## Token discipline
-
-- Batch 3–5 questions per message; never ping-pong one-per-message.
-- Hard round caps — MAXIMA, not targets (small prompts ask far fewer;
-  § How to ask): GREENFIELD-SYSTEM ≤6 rounds, every other class ≤3
-  (round 0 counts when it runs).
-- Skip any question already answered by the opening message, calibration, or
-  survey artifacts.
-
-## Answers-file format (machine-readable, enables non-interactive runs)
-
-For scripted E2E or re-runs, requirements may come from a file instead of
-conversation — `.archgen/<slug>/answers.yaml`:
-
-```yaml
-scope_class: MEDIUM        # SMALL | MEDIUM | LARGE — UNCHANGED; SKILL.md reads
-                           # this for right-sizing. Never remove or rename.
-intent_class: GREENFIELD-SYSTEM  # optional: GREENFIELD-SYSTEM |
-                           # GREENFIELD-MODULE | BROWNFIELD-FEATURE |
-                           # BROWNFIELD-CHANGE
-calibration:               # optional — from round 0
-  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          # structured entries MAY carry feeds:
-    feeds: prd.metrics
-constraints:
-  - must-not-change item              # plain scalars stay valid; tag via
-                                      # trailing comment:  # 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; NUMBERS 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: []             # checklist placeholders only
-risks:
-  - known risk text
-```
-
-Backward compatibility: ALL additions (`intent_class`, `calibration`,
-`non_goals`, `personas`, `nfrs`, `out_of_scope`, per-answer `feeds:` tags) are
-OPTIONAL. Existing fields keep their names and semantics; `scope_class` is
-retained verbatim because SKILL.md consumes it. Consumers that do not trace
-provenance ignore `feeds:` tags in both forms (sibling key on structured
-entries, trailing comment on plain scalars).
-
-The orchestrator treats answers.yaml as authoritative user input and skips
-the conversational rounds when it exists and parses cleanly.
-
-## Completion test
-
-Requirements are done when ALL hold:
-- Every applicable question in the chosen intent class's question set answered
-  (or explicitly waived by the user)
-- All drafted inferences confirmed or corrected
-- Zero unresolved conflicts
-- Scope class agreed (SMALL/MEDIUM/LARGE) — this gates artifact generation
-  (unchanged; SKILL.md consumes it)
-- Chosen `intent_class` recorded in answers.yaml
-- GREENFIELD-SYSTEM only: module-map agreement reached (user reacted to the
-  strawman and the revision is confirmed) AND NFR numbers captured — an NFR
-  without a number fails this gate

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

@@ -1,117 +0,0 @@
-# MCP installation and skill fetching
-
-## INSTALL-MCP procedure (approval-gated)
-
-1. **Identify** the platform (SKILL.md Step 0), load its row from
-   references/platforms.md section MCP: config file, top-level key, quirks.
-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>`
-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.
-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. Uncertainty
-triggers web-search of current official docs, never invention.
-
-## FETCH-SKILL procedure
-
-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",
-  "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

@@ -1,292 +0,0 @@
-# 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.
-
-## §survey — brownfield codebase analysis brief
-
-Dispatch 1–2 sub-agents with this prompt shape:
-
-```
-TASK: Survey this repository to prepare a feature plan for: <feature request>
-DELIVERABLE: write .archgen/<slug>/codebase-map.md containing EXACTLY these
-sections:
-  ## Structure      — top-2-levels folder tree w/ one-line purpose each
-  ## Modules        — table: module | responsibility | key entry points
-  ## Conventions    — naming, error-handling, test layout actually observed
-  ## Affected       — files/modules the feature will touch, with evidence paths
-SCOPE: read-only. Use codegraph MCP tools when available
-(codegraph_explore / codegraph_files); otherwise Glob+Grep systematically.
-VERIFY: every claim cites a real path; no guessed APIs.
-```
-
-Accept the map only if every section is present and non-empty.
-
-## §verifier — plan review brief
-
-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. 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?
-   - 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.
-
-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
-
-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.
-- 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.
-
-### When sub-agents are unavailable or fail
-
-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:
-
-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"
-# point the sub-agent's cwd at .worktrees/$id, then merge task-$id on success
-```
-
-### 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/`.
-
-Workers do NOT talk to each other; coordination happens only through
-tasks.yaml state.
-
-## 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.