archgen-skill 0.0.3 → 0.0.4

package/vendor/skills/archgen/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: archgen
-description: Enterprise architecture generation and autonomous task execution for coding agents. Interviews stakeholders (or surveys an existing codebase), generates architecture artifacts (architecture.yaml, docs with Mermaid diagrams, ADRs) plus a dependency-ordered tasks.yaml inside a single .archgen/ folder, then executes tasks in topological waves via sub-agents with a verifier gate before any work starts. Use when the user asks to design a system, generate architecture, plan a feature, add a feature to an existing codebase, or says things like "start work", "build the tasks", "generate architecture", "add feature X", "roll back changes", "install MCP server", or "fetch the design skill".
+description: Enterprise architecture generation and autonomous task execution for coding agents. Interviews stakeholders (or surveys an existing codebase), generates architecture artifacts (PRD, architecture.yaml, docs with Mermaid diagrams, ADRs) plus a dependency-ordered tasks.yaml inside a single .archgen/ folder, verifies and plan-reviews the plan, then executes tasks in topological waves via the platform's native sub-agents under verifier, plan-review, and user gates — loading required capability skills (ui-skills for any UI/design/frontend work) before planning and dispatch. Use when the user asks to design a system, generate architecture, plan a feature, add a feature to an existing codebase, investigate recurring post-implementation issues, or says things like "start work", "build the tasks", "generate architecture", "add feature X", "roll back changes", "install MCP server", or "fetch the design skill".
 license: MIT
 compatibility: Requires Node.js >= 18 (zero npm dependencies). Works on any agent harness that can read files and run shell commands.
 metadata:
-  version: 1.0.0
+  version: 0.0.4
   repo: https://github.com/akashmaurya99/archgen
 ---
 
 # archgen — architecture generation & wave execution
 
-You are the ORCHESTRATOR. You never implement features yourself. You gather
-requirements (or survey code), generate the plan and artifacts, get them
-verified, then dispatch work to sub-agents in dependency-safe waves.
+You are the ORCHESTRATOR. You gather requirements (or survey code), generate
+the plan and artifacts, get them verified and reviewed, then dispatch work in
+dependency-safe waves — through the platform's NATIVE sub-agent mechanism or,
+when no sub-agent functions, by executing tasks yourself
+(references/orchestration.md §dispatch).
 
 Deterministic logic lives in `scripts/` — invoke them and branch on their JSON
 output. Your job is orchestration, conversation, judgment, and dispatch.
@@ -25,6 +27,7 @@ Load when the user's prompt mentions any of:
 - "start work", "run tasks", "execute the plan", "next task"
 - "add feature", "implement feature", "new feature" (brownfield mode)
 - "roll back", "revert task", "undo change"
+- "investigate", "root cause", "keeps failing" (post-wave defect protocol)
 - "install mcp", "set up codegraph", "fetch skill", "design skill"
 
 Do NOT load for plain bug fixes or one-line edits that need no planning.
@@ -33,22 +36,57 @@ Do NOT load for plain bug fixes or one-line edits that need no planning.
 
 1. **Everything you generate goes inside `.archgen/<project-slug>/`** at the
    target repo root. NEVER write generated artifacts anywhere else. The only
-   files you may touch outside `.archgen/` are source-code edits performed by
-   worker sub-agents for approved tasks and the `AGENTS.md` features registry,
-   maintained exclusively via `scripts/update-agents.mjs`.
-2. **Two gates before execution**: (a) the VERIFIER sub-agent must return
-   APPROVE on plan+tasks, then (b) the USER must approve. Never skip either.
-3. **Right-size every generation.** Classify scope BEFORE creating files:
-   - SMALL (one tweak/feature): tasks entries + one short plan note. No
-     architecture.yaml, no diagrams, no ADRs.
-   - MEDIUM: plan + tasks.yaml (+ architecture update ONLY if structure changes).
-   - LARGE / greenfield: full artifact set.
-   Never regenerate an existing artifact unless the change requires it.
-4. **Platform awareness.** Detect the harness before touching configs or
+   files you may touch outside `.archgen/` are source-code edits for approved
+   tasks — performed by worker sub-agents, or by you when self-executing per
+   references/orchestration.md §dispatch — and the `AGENTS.md` features
+   registry, maintained exclusively via `scripts/update-agents.mjs`.
+2. **Three stages before execution**: (a) the VERIFIER sub-agent must return
+   APPROVE on plan+tasks, then (b) the PLAN-REVIEW stage must reach zero
+   findings (or an explicit user waiver), then (c) the USER must approve.
+   Never skip any stage.
+3. **Right-size every generation — the depth ladder.** Classify scope BEFORE
+   creating files; depth scales with the intent class references/interview.md
+   assigns (GREENFIELD-SYSTEM vs BROWNFIELD-FEATURE vs …):
+   - SMALL (one tweak/feature): lean plan-note + tasks entries — paths still
+     verbatim. No Context section, no diagrams, no PRD.
+   - MEDIUM: plan with Context / per-task Approach + Edge cases (min 3 per
+     task) / Verification steps + tasks.yaml (+ architecture update ONLY if
+     structure changes).
+   - LARGE / greenfield-from-scratch: FULL professional stack — PRD
+     (`docs/prd.md`), `architecture.yaml` with naming_conventions /
+     data_contracts / api_contracts / environment_matrix, per-module Mermaid
+     diagrams, edge-case matrices mapped to acceptance criteria.
+   Token balance: bullet-dense over prose, diagrams ≤15 nodes, no boilerplate
+   inflation — quality floor without waste. Never regenerate an existing
+   artifact unless the change requires it.
+4. **Self-containment.** Artifacts must survive context summarization alone:
+   any session reading ONLY `.archgen/<slug>/` executes correctly with zero
+   chat history. Every task carries complete repo-root paths taken VERBATIM
+   from architecture.yaml/tasks.yaml; workers never reconstruct paths from
+   memory. Forbidden phrases: "as discussed", "see chat", "same as before"
+   (full rules: references/artifact-templates.md).
+5. **Completeness.** No partially implemented feature ships as done.
+   Acceptance criteria must be objectively verifiable AND cover full behavior
+   (edge-matrix rows included). Stubs, TODO placeholders, and mock-only paths
+   are FAILED tasks even when tests pass. The final report carries an
+   explicit completeness checklist per feature.
+6. **Status discipline — NON-NEGOTIABLE.** After EVERY individual task
+   completes, in the SAME turn and before anything else, ensure ALL THREE:
+   (1) tasks.yaml status written via
+   `node <skill>/scripts/set-status.mjs .archgen/<slug>/tasks.yaml <id> done|failed`
+   — the worker usually does this; you VERIFY it landed, never assume;
+   (2) the corresponding system/todo tracker item marked completed;
+   (3) the AGENTS.md features registry refreshed via
+   `node <skill>/scripts/update-agents.mjs <repo-root>` so the Updated column
+   carries the current date. Batch-updating statuses at session end is
+   FORBIDDEN. Dispatching the next wave while any completed task's status or
+   todos lag is FORBIDDEN. This survives compaction because it is per-turn,
+   not per-session.
+7. **Platform awareness.** Detect the harness before touching configs or
    spawning agents — see references/platforms.md. If the platform is unknown,
    use your WEB SEARCH tool to find its official docs for skill/MCP config
    locations, propose what you found, and get user approval before writing.
-5. **Code quality is contractual.** Workers follow references/code-standards.md:
+8. **Code quality is contractual.** Workers follow references/code-standards.md:
    no `any`, no unhandled `undefined`, files < 1000 LOC, professional folder
    trees and file names, why-comments. The verifier rejects violations.
 
@@ -61,10 +99,31 @@ Identify the running harness by probing, in order:
    `.github/copilot-instructions.md` (Copilot), `~/.codex` (Codex),
    `.gemini/` (Gemini CLI/Antigravity), `.kiro/` (Kiro), `.trae/` (Trae).
 2. First match wins → load that row of references/platforms.md for: skill
-   install paths, MCP config file + shape, sub-agent mechanism, headless CLI.
+   install paths, MCP config file + shape, sub-agent mechanism.
 3. No match → WEB SEARCH `<platform name> MCP configuration official docs`
    and `<platform> agent skills install`. Summarize findings to the user,
    get approval, then proceed using discovered facts.
+4. **Codegraph offer (once per project).** Beginning ANY archgen work in a
+   repo with NO `.codegraph/` directory, on a harness that provides codegraph
+   tooling → propose installing + indexing once, reusing the INSTALL-MCP
+   approval pattern (show exactly what gets written and indexed; wait for
+   explicit approval). Discover the CURRENT install method via web search
+   when not known with confidence — never a memorized command — and state
+   the chosen scope (this harness's config vs a global npx/npm entry) before
+   proposing. Brownfield surveys prefer it once present. Scope note: 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 uses codegraph when
+   configured, YAML plan graphs come exclusively from
+   `scripts/plan-graph.mjs`, and markdown artifact navigation comes from
+   `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.
 
 ## Step 1 — Route the mode
 
@@ -77,8 +136,9 @@ Pick ONE mode from the user's intent and follow its section below:
 | "start work" / execute pending tasks | **START-WORK** |
 | Change requirements mid-flight | **UPDATE** |
 | Undo completed work | **ROLLBACK** |
+| Recurring issues after completed waves | **INVESTIGATE** |
 | Need an MCP server not yet configured | **INSTALL-MCP** |
-| Task needs a capability skill we reference | **FETCH-SKILL** |
+| Work touches a registry capability domain — loading is mandatory | **FETCH-SKILL** |
 
 ---
 
@@ -86,19 +146,31 @@ Pick ONE mode from the user's intent and follow its section below:
 
 1. **Acknowledge + confirm scope class.** One sentence stating what you'll do
    and whether this looks SMALL/MEDIUM/LARGE. Ask to proceed. [wait for user]
-2. **Interview.** Follow references/interview.md: role-aware questions
-   (business → technical → constraints), detect conflicts between answers,
-   iterate until the requirement set is complete. Keep it tight — batch
-   questions, never interrogate one-per-message. [wait for user per round]
-3. **Generate artifacts** into `.archgen/<slug>/` (slug = project short name):
-   - LARGE: `architecture.yaml` (per schemas/architecture-conventions.md),
-     `docs/*.md` with Mermaid C4-context/container diagrams, ADRs in
-     `decisions/`, `plans/<feature>.md`, `tasks.yaml`.
-   - MEDIUM: `plans/<feature>.md` + `tasks.yaml`.
-   - SMALL: append entries to existing `tasks.yaml` (create minimal file if none).
-   Use templates from references/artifact-templates.md. Every task needs:
+2. **Interview.** Follow references/interview.md: round-0 calibration, then
+   classify ONE intent class (GREENFIELD-SYSTEM / GREENFIELD-MODULE /
+   BROWNFIELD-FEATURE / BROWNFIELD-CHANGE) and record it as `intent_class` in
+   answers.yaml. Respect the round caps (GREENFIELD-SYSTEM ≤6 rounds, every
+   other class ≤3). Batch questions, never interrogate one-per-message.
+   [wait for user per round]
+3. **Generate artifacts** into `.archgen/<slug>/` (slug = project short name)
+   at the depth Hard rule 3 demands for the class:
+   - LARGE / greenfield-from-scratch: `docs/prd.md` (PRD) FIRST, then
+     `architecture.yaml` (naming_conventions, data_contracts, api_contracts,
+     environment_matrix; modules carry depends_on_modules + key_interfaces),
+     per-module Mermaid diagrams (≤15 nodes each), per-task edge-case
+     matrices mapped to acceptance rows, ADRs in `decisions/`,
+     `plans/<feature>.md`, `tasks.yaml`.
+   - MEDIUM: `plans/<feature>.md` (Context / per-task Approach + Edge cases /
+     Verification) + `tasks.yaml`.
+   - SMALL: lean plan-note + tasks entries (paths verbatim).
+   Use templates from references/artifact-templates.md; Hard rule 4
+   (self-containment) governs every path and phrase. Every task needs:
    id, title, depends_on (prerequisite ids), file_ownership (disjoint globs!),
    acceptance criteria, and status left unset (resolver derives readiness).
+   **FETCH-SKILL pre-planning scan**: BEFORE finalizing the plan, test every
+   task's title/summary/file_ownership against assets/skill-registry.json
+   `matches` patterns and fetch any matched skill now
+   (references/mcp-and-skills.md § FETCH-SKILL procedure).
    If `<slug>` already exists under `.archgen/`, pick `<slug>-2`, `<slug>-3`, …
    — NEVER overwrite or merge into an existing feature folder.
 4. **Self-check + registry:** run
@@ -109,24 +181,41 @@ Pick ONE mode from the user's intent and follow its section below:
 5. **VERIFIER GATE.** Dispatch a verifier sub-agent (brief in
    references/orchestration.md §verifier). It must also run
    `node <skill>/scripts/verify-plan.mjs .archgen/<slug>/tasks.yaml --plan .archgen/<slug>/plans`
-   and return APPROVE or an issues list. Fix issues and re-verify until APPROVE.
-6. **USER GATE.** Present: artifact list, wave summary
+   and return APPROVE or an issues list; when markdown artifacts exist under
+   `.archgen/<slug>/`, it additionally runs
+   `node <skill>/scripts/doc-index.mjs .archgen/<slug> --validate` — zero
+   broken references is required alongside verify-plan APPROVE. It may consult
+   `plan-graph.mjs --node <id>` neighborhoods when judging ordering sanity.
+   Fix issues and re-verify until APPROVE.
+6. **PLAN-REVIEW.** After verifier APPROVE, dispatch reviewer sub-agent(s)
+   sized by scope class (references/orchestration.md §plan-review: SMALL —
+   main-agent self-review acceptable; MEDIUM — 1 reviewer; LARGE — 2–3 split
+   by concern). Attach `plan-graph.mjs --mermaid --status` output plus
+   `doc-index.mjs .archgen/<slug> --validate` results to the reviewer package
+   (the mermaid doubles as your wave-progress render). Reviewers are
+   read-only; YOU fix the artifacts, then re-run validate + the verifier gate
+   after every change. Iterate until zero findings or an explicit user waiver.
+7. **USER GATE.** Present: artifact list, wave summary
    (`node scripts/next-tasks.mjs .archgen/<slug>/tasks.yaml`), and the
    ownership map. Ask: "Approve to start work?" [wait for user]
-7. On approval → continue into START-WORK.
+8. On approval → continue into START-WORK.
 
 ## BROWNFIELD (existing codebase)
 
 1. Acknowledge + state that you'll survey before planning. [wait for user]
 2. **SURVEY.** Dispatch survey sub-agent(s) (brief in
    references/orchestration.md §survey). They analyze the current code —
-   prefer the codegraph MCP (`codegraph_explore`) when configured, else
-   structured grep/glob — and write `.archgen/<slug>/codebase-map.md`:
-   structure, modules, conventions, affected surfaces for the requested feature.
+   prefer the codegraph MCP (`codegraph_explore`) when configured (offered at
+   Step 0 when absent), else structured grep/glob — and write
+   `.archgen/<slug>/codebase-map.md`: structure, modules, conventions,
+   affected surfaces for the requested feature.
 3. Plan against the map: same artifact rules as GENERATE steps 3–4, but every
    new task's file_ownership must be checked against the map so workers edit
    real paths. New tasks integrate with any existing unfinished tasks.yaml.
-4. Continue with GENERATE steps 4–7 (verifier gate → user gate → start).
+   Intent class is BROWNFIELD-FEATURE or BROWNFIELD-CHANGE
+   (references/interview.md): survey FIRST, ask only survey gaps.
+4. Continue with GENERATE steps 4–8 (verifier gate → plan-review → user gate
+   → start).
 
 ## START-WORK (wave execution loop)
 
@@ -137,24 +226,39 @@ Run from the target repo root where `.archgen/<slug>/` exists.
    - Exit 2 (cycle) or 3 (ownership clash): fix tasks.yaml, re-run.
    - `blockedByFailure` non-empty: report those tasks to the user; they stay
      excluded until re-planned.
-   - Empty waves + nothing blocked: report completion, go to step 6.
+   - Empty waves + nothing blocked: report completion, go to step 7.
 2. Mark the wave running: for each task in wave 1,
    `node scripts/set-status.mjs <tasks.yaml> <id> running`.
 3. **Dispatch** per references/orchestration.md §dispatch:
-   - Native sub-agents where the harness supports them well (Claude Code:
-     background Agent tool + worktree isolation; Cursor: background subagents).
-   - Otherwise bash fallback workers over headless CLIs (exact block in
-     references/orchestration.md).
-   - One worker per task. Worker prompt = task title + acceptance criteria +
-     owned files + "follow references/code-standards.md" + instruction to run
-     `set-status.mjs <id> done` on success (or `failed` on failure) and commit.
-4. After the wave settles: re-run next-tasks. Failed tasks are NOT retried
+   - Use THIS platform's NATIVE sub-agent mechanism (Claude Code: background
+     Agent tool + worktree isolation; Cursor: background subagents;
+     Antigravity: invoke_subagent — full table in references/platforms.md).
+   - Mechanism missing, spawn failed, or sub-agent lacks tool permissions →
+     the MAIN AGENT EXECUTES THE TASK ITSELF, sequentially, respecting waves
+     and ownership globs. No user permission needed to self-execute.
+   - Switching to another harness/platform happens ONLY after telling the
+     user the concrete problem and getting explicit approval. NEVER
+     auto-spawn other CLIs or harnesses.
+   - One worker per task. The worker prompt is the FULL contract in
+     references/orchestration.md §dispatch ("Worker prompt contract") —
+     including running `plan-graph.mjs --node <id>` before writing code,
+     taking every path VERBATIM from tasks.yaml/architecture.yaml, and MAY
+     query `doc-index.mjs .archgen/<slug> --refs-to <their-task-id>` to find
+     the docs constraining their work. For
+     FETCH-SKILL-matched tasks, embed the follow-instruction sentence and
+     require the one-line `Skill compliance:` audit in the completion report
+     (references/mcp-and-skills.md § FETCH-SKILL procedure).
+4. **Per-task closeout (Hard rule 6).** The moment EACH task finishes — same
+   turn: verify its `set-status done|failed` landed, mark its tracker/todo
+   item completed, refresh AGENTS.md via update-agents.mjs. Never let these
+   lag into the next dispatch.
+5. After the wave settles: re-run next-tasks. Failed tasks are NOT retried
    automatically — surface them, propose a fix task, [wait for user].
-   Refresh the registry so AGENTS.md tracks the new statuses:
-   `node <skill>/scripts/update-agents.mjs <repo-root>`.
-5. Repeat until no actionable tasks remain.
-6. Final report: tasks done/failed/blocked, commits produced, suggested
-   follow-ups. Update `.archgen/<slug>/plans/*.md` checkboxes if present.
+6. Repeat until no actionable tasks remain.
+7. Final report: tasks done/failed/blocked, commits produced, suggested
+   follow-ups, and the per-feature completeness checklist (Hard rule 5),
+   which must include a clean `doc-index.mjs .archgen/<slug> --validate` run.
+   Update `.archgen/<slug>/plans/*.md` checkboxes if present.
 
 ## UPDATE (requirements changed mid-flight)
 
@@ -162,8 +266,12 @@ Run from the target repo root where `.archgen/<slug>/` exists.
    `node scripts/impact.mjs <tasks.yaml> <taskId-or-path>`.
 2. Apply the right-sizing rule again: edit only affected artifacts. New
    requirements → new tasks appended with correct depends_on; obsolete pending
-   tasks → remove (never remove done tasks — history lives in git).
-3. Re-run validate + VERIFIER GATE on the changed set, then USER GATE.
+   tasks → remove (never remove done tasks — history lives in git). Run the
+   FETCH-SKILL domain scan over new/changed tasks
+   (references/mcp-and-skills.md § FETCH-SKILL procedure).
+3. Re-run validate + VERIFIER GATE on the changed set, then PLAN-REVIEW
+   (references/orchestration.md §plan-review, sized to the changed scope),
+   then USER GATE.
 
 ## ROLLBACK
 
@@ -173,6 +281,23 @@ Run from the target repo root where `.archgen/<slug>/` exists.
    dependency order, plus status rewinds via set-status --force.
 3. USER GATE (mandatory — destructive). Execute, mark statuses, verify build.
 
+## INVESTIGATE (recurring issues after waves)
+
+Trigger: the USER reports repetitive/recurring issues AFTER implementation
+waves completed. Do NOT patch-fix. Follow references/orchestration.md
+§investigate:
+
+1. Size by complexity: SMALL scope → the main agent investigates directly;
+   larger → 1–3 investigator sub-agents split by suspected subsystem.
+2. Investigators produce ALL FOUR: root-cause statement (one sentence),
+   evidence (files/lines/repro steps), blast radius (affected
+   tasks/artifacts), remediation plan. Token balance: read narrowly around
+   evidence — no whole-repo sweeps.
+3. Remediation routes through the NORMAL gates as fresh fix tasks (new ids
+   inheriting the affected task's ownership globs): verifier → plan-review →
+   user. Patch-fixes without a root-cause statement are forbidden under this
+   protocol.
+
 ## INSTALL-MCP
 
 When a needed MCP (e.g. codegraph, context7) is not configured:
@@ -180,34 +305,68 @@ When a needed MCP (e.g. codegraph, context7) is not configured:
 1. Look up the CURRENT platform's MCP config in references/platforms.md
    (config file, top-level key, field quirks — e.g. VS Code uses `servers`,
    OpenCode uses `mcp` with array commands, Antigravity requires `serverUrl`).
-2. Prefer the platform CLI if listed (claude/codex/gemini/copilot mcp add …).
+2. **Discover, don't recall.** If the correct CURRENT install command or
+   config shape for this harness is not known with confidence, WEB SEARCH the
+   official docs FIRST and act on what they say — memorized commands and
+   config shapes go stale (same discipline as the unknown-platform
+   procedure, Hard rule 7).
+3. **Scope the install deliberately:** apply the discovered method at the
+   right scope — write into THAT detected harness's config shape, or perform
+   a GLOBAL install when the server type makes it appropriate (npx/npm-based
+   servers are global entries usable across harnesses). State the chosen
+   scope explicitly to the user BEFORE writing anything.
+4. Prefer the platform CLI if listed (claude/codex/gemini/copilot mcp add …).
    Otherwise draft the exact config diff and SHOW IT. [wait for user approval]
-3. Write config only after approval. Note restart semantics from the table.
-4. Verify: check the tool appears in your available tools after reload; if
+5. Write config only after approval. Note restart semantics from the table.
+6. Verify: check the tool appears in your available tools after reload; if
    not, report the failure mode honestly.
 
-Unknown platform → web-search fallback (Step 0 rule 4).
-
-## FETCH-SKILL
-
-When a task domain matches an entry in `assets/skill-registry.json`
-(e.g. frontend/UI work → ui-skills):
-
-1. Read the registry entry {name, repo, npxCommand}.
-2. Install into the CURRENT platform's skill dir (paths in
-   references/platforms.md): usually `npx skills add <repo>` or the entry's
-   own command (e.g. `npx ui-skills get baseline-ui`).
-3. Confirm installation, then FOLLOW the fetched skill for that task domain.
-4. If the registry lacks a needed capability: web-search for a reputable
-   skill repo, propose it to the user, add to the registry on approval.
+Unknown platform → web-search procedure (Hard rule 7). The Step-0 codegraph
+proposal reuses this exact approval pattern.
+
+## FETCH-SKILL (mandatory capability loading)
+
+Capability-skill loading is REQUIRED, not opportunistic — full procedure in
+references/mcp-and-skills.md § FETCH-SKILL procedure. It runs TWICE per
+matched task:
+
+1. **Pre-planning scan.** While planning (GENERATE / BROWNFIELD / UPDATE),
+   test every task's title, summary, and file_ownership against the
+   `matches` patterns in assets/skill-registry.json (case-insensitive
+   substring). One hit = loading is mandatory for that task.
+   UI/design/frontend/animation/component/landing-page work REQUIRES
+   ui-skills (`policy: "required"`).
+2. **Install once per project.** Resolve the CURRENT platform's skill dir
+   from references/platforms.md § Skill install paths. Already present →
+   skip reinstall (cache hit). Absent → run the entry's `install` command
+   (e.g. `npx skills add ibelick/ui-skills`) and VERIFY presence. Registry
+   keys are exactly name/purpose/repo/install/direct_fetch/browse/
+   mcp_endpoint/matches/policy.
+3. **Pre-dispatch verification.** Immediately before dispatching each
+   matching worker: re-verify the match and that the skill is still present;
+   install first if missing. Dispatch does not proceed otherwise.
+4. **Integrate + audit.** Inject the follow-instruction sentence from
+   references/mcp-and-skills.md into every affected worker prompt and require
+   a one-line `Skill compliance:` statement in its completion report.
+5. **Missing capability.** Unmatched-but-obvious domain: web-search reputable
+   skill repos, propose to the user, add to the registry ONLY on explicit
+   approval.
 
 ## Things you must NOT do
 
 - Do NOT write artifacts outside `.archgen/<slug>/`.
 - Do NOT reuse or overwrite an existing `.archgen/<slug>/` folder — suffix
   `-2`, `-3`, … instead (multi-feature repos must stay isolated).
-- Do NOT skip the verifier gate or the user gate — ever, even for SMALL scopes.
-- Do NOT implement features yourself; dispatch workers.
+- Do NOT skip the verifier gate, the plan-review stage, or the user gate —
+  ever, even for SMALL scopes.
+- Do NOT batch status updates at session end or dispatch a wave while any
+  completed task's status/todos lag (Hard rule 6).
+- Do NOT auto-spawn another harness/CLI when sub-agents misbehave — execute
+  the task yourself, or ask the user first (references/orchestration.md
+  §dispatch).
+- Do NOT implement features yourself while a functioning sub-agent mechanism
+  exists — dispatch workers. Self-execution is the default ONLY when the
+  mechanism is missing/failing (§dispatch).
 - Do NOT put two same-wave tasks on overlapping file_ownership globs.
 - Do NOT retry failed tasks without user consent.
 - Do NOT modify MCP/skill configs silently — always show the diff first.
@@ -226,7 +385,8 @@ When a task domain matches an entry in `assets/skill-registry.json`
 | Worker finishes but acceptance unmet | Mark failed, do NOT cascade, propose fix task |
 | User interrupts mid-wave | Let running workers finish; stop before next wave |
 | No Node ≥18 available | State requirement; offer npx-based alternative if present |
-| Headless CLI missing for fallback workers | Use native sub-agents, else halt with clear message |
+| Sub-agent mechanism missing/fails/lacks permissions | Main agent executes the task itself; cross-harness switch only after telling the user the concrete problem and getting explicit approval (references/orchestration.md §dispatch) |
+| Recurring defects after waves completed | Switch to INVESTIGATE — root cause first, no patch-fixes |
 
 ## Scripts quick reference
 
@@ -238,4 +398,12 @@ scripts/update-agents.mjs <projectRoot> [--slug <s>] [--status <s>] [--prune]
                         # AGENTS.md features registry
 scripts/impact.mjs      <tasks.yaml> <id-or-artifactPath>  # ripple JSON
 scripts/verify-plan.mjs <tasks.yaml> --plan <dir>          # APPROVE|ISSUES
+scripts/plan-graph.mjs  <slug-dir-or-tasks.yaml> [--node <id>] [--mermaid [--status]] [--module <name>]
+                        # task-DAG queries: --node neighborhood, --mermaid graph,
+                        # --module filter — generic code indexers do not extract YAML task graphs.
+                        # Scope-hardened to .archgen/<slug>/ only; dedup-guaranteed output
+scripts/doc-index.mjs   <slug> [--validate|--refs-to <id>|--stale|--diagrams]
+                        # markdown artifact map: heading tree, backlinks,
+                        # broken-reference gate, staleness, diagram inventory.
+                        # Same .archgen/<slug>/ scope lock; unique-ref counting, dup-definition checks
 ```

package/vendor/skills/archgen/archgen.config.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.0.4",
+  "skillName": "archgen",
+  "markers": {
+    "start": "<!-- archgen:start (managed block - do not edit between markers) -->",
+    "end": "<!-- archgen:end -->",
+    "featuresStart": "<!-- archgen:features:start -->",
+    "featuresEnd": "<!-- archgen:features:end -->"
+  },
+  "files": {
+    "stamp": ".archgen-version",
+    "projectManifest": ".install-manifest.json",
+    "globalManifest": ".archgen-install-manifest.list",
+    "backupDir": ".backup"
+  }
+}

package/vendor/skills/archgen/assets/skill-registry.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "./registry-schema-note.md",
   "version": 1,
   "skills": [
     {
@@ -10,14 +9,16 @@
       "direct_fetch": "npx ui-skills get <skill-name>",
       "browse": "npx ui-skills list --category <category>",
       "mcp_endpoint": "https://www.ui-skills.com/mcp",
-      "matches": ["frontend", "ui", "ux", "design", "component", "animation", "motion", "landing page"]
+      "matches": ["frontend", "ui", "ux", "design", "component", "animation", "motion", "landing page"],
+      "policy": "required"
     },
     {
       "name": "vercel-skills-installer",
       "purpose": "Canonical cross-harness skill installer (75+ agents) - use when a registry entry lacks a direct command",
       "repo": "vercel-labs/skills",
       "install": "npx skills add <owner>/<repo> [-a <agent>] [-g] [--copy]",
-      "matches": ["*installer*"]
+      "matches": ["*installer*"],
+      "policy": "on-demand"
     }
   ]
 }