archgen-mcp 0.0.7 → 0.1.0

package/assets/references/interview.md

@@ -1,277 +1,161 @@
 # 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).
+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, 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):
+- **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)** — 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.
+> 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)
 
-Two or three rapid items, asked once at the very start — each INFERRED first
-(§ How to ask), asked only when genuinely ambiguous:
+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?
 
-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.
+Record 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.
+Classify into ONE `intent_class`, state it in one sentence, and record in `answers.yaml`:
 
-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.
+| `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` |
 
-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.
+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)
 
-Creating a system from scratch demands PRD-grade inputs. Each round below
-lists its questions and where the answers land (`feeds:` tags — see
-Traceability).
+Tag recorded answers with `feeds:` targets for downstream 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.
+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`
-
-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`.
+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 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`)
+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
-
-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)?
+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. 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)
+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`)
 
-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]).
+Present the finalized module map + numeric NFRs for 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`.
+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 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`)
+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)
 
-Run the survey first (SKILL.md BROWNFIELD steps 1–2): prefer the CodeGraph MCP
-tools (Step 0 builds the index when absent), 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:
+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.
 
-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-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)
-
-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?
+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
 
-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]
+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 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.
+- 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)
 
-For scripted E2E or re-runs, requirements may come from a file instead of
-conversation — `.archgen/<slug>/answers.yaml`.
-
-**The skeleton is a tool output:** `archgen_plan{action:'scaffold', scope:'LARGE'}`
-returns a ready-to-fill `answers.yaml` with every field below. The shape:
+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 — 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
+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
+  pressure: medium               # low | medium | high
 problem: one-line problem statement
 success_criteria:
-  - text: measurable outcome          # structured entries MAY carry feeds:
+  - text: measurable outcome
     feeds: prd.metrics
 constraints:
-  - must-not-change item              # plain scalars stay valid; tag via
-                                      # trailing comment:  # feeds: prd.constraints
-non_goals:                 # optional (GREENFIELD-SYSTEM)
+  - must-not-change item # feeds: prd.constraints
+non_goals:                       # optional (GREENFIELD-SYSTEM)
   - multi-tenant accounts
-personas:                  # optional (GREENFIELD-SYSTEM)
+personas:                        # optional (GREENFIELD-SYSTEM)
   - role: shopper
     goal: find and buy in under two minutes
-nfrs:                      # optional; NUMBERS required for GREENFIELD-SYSTEM
+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
+out_of_scope: []                 # optional
 stack:
   language: typescript
   runtime: node
   hosting: vercel
 integrations: [auth0, stripe]
-compliance: []             # checklist placeholders only
+compliance: []
 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.
+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
 
-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
+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/assets/references/mcp-and-skills.md

@@ -2,121 +2,52 @@
 
 ## archgen's own MCP server — already handled
 
-The `archgen-mcp` server and CodeGraph are wired by the installer
-(`npx archgen-skill init` / `install`), into every DETECTED harness, with the
-correct per-platform file and key. You never configure them by hand.
+`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`).
 
-If the `archgen_*` tools are missing from your tool list, run
-`npx archgen-skill init` in the project root and ask the user to reload the
-harness — that is the only setup step. The full per-platform shapes live in
-§platforms/mcp-configuration and in the installer's registry; the
-`archgen_setup` tool reports exactly what it would write (`action:'harnesses'`).
-
-Everything below is for OTHER MCP servers (context7, …).
+The procedures below govern **external** MCP servers (e.g., `context7`) and capability skills.
 
 ## INSTALL-MCP procedure (approval-gated)
 
-1. **Identify** the platform (SKILL.md Step 0), load its row from
-   §platforms/mcp-configuration: 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 `packages/mcp/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.
+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 **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 §mcp-and-skills/fetch-skill*.
-
-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** — call `archgen_skills { action: 'match', title, summary,
-   fileOwnership }`. The tool holds the registry and applies **case-insensitive
-   whole-WORD matching** (`\b` boundaries; a match requires the pattern to stand
-   alone as a token or hyphen/underscore-delimited unit). Bare `"ui"` matches
-   the task "redesign the ui" and "ui-skills audit", but does NOT match
-   "guide", "build", "sequence", or "building" — the 2026-08 substring semantics
-   mis-fired on every task and made the required gate meaningless. One
-   `required` hit = this procedure is mandatory for that task.
-2. **RESOLVE** — the tool reports, for every match, whether the skill is
-   already installed and at which path. It owns the per-platform resolution
-   (§platforms/harness-capabilities is the human-readable mirror);
-   never duplicate that logic here.
-3. **INSTALL once if absent** — cached check first: if the skill is already
-   present, skip the reinstall and go to step 4. Otherwise call
-   `archgen_skills { action: 'install', skillId, harness, approve: true }`.
-   The tool drives the `skills` CLI (`npx -y skills add <repo> --skill <slug>
-   --agent <agent> --yes --json`) — **one skill, never a bundle**, and
-   non-interactively (the CLI PROMPTS without `--yes`/`--agent`, so an
-   automated install would hang). Then VERIFY: the tool re-checks the
-   filesystem and reports the path. 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.`
+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.
 
-   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.
 ## The registry
 
-The registry lives with the MCP server — `packages/mcp/assets/skill-registry.json`
-— and is read by the `archgen_skills` tool. The agent never edits it and never
-reads it directly; the tool is the only interface.
-
-Canonical entry keys, in order:
+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.",
@@ -125,28 +56,7 @@ Canonical entry keys, in order:
 }
 ```
 
-- `matches[]`: case-insensitive WHOLE-WORD patterns tested against task titles,
-  summaries and file_ownership during the FETCH-SKILL domain scan (step 1).
-  Never raw substrings — see step 1 for why.
-- `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).
-  - `"on-demand"`: fetched only when a task explicitly names the capability.
-
-**Install model.** The `skills` CLI (npm package `skills`, from
-vercel-labs/skills) installs ONE named skill:
-
-```
-npx -y skills add <repo> --skill <slug> --agent <agent> --yes --json
-```
-
-`--yes` and `--agent` are MANDATORY for an automated install: without them the
-CLI is interactive and will hang. It lands the skill at
-`<project>/.agents/skills/<slug>/SKILL.md` (global: `~/.agents/skills/<slug>/`)
-— every harness reads `.agents/skills/`, so that one path is what a worker
-should be pointed at.
-
-**No clustering.** A task that mentions "animation" gets the motion skill — not
-the whole UI family. The registry maps a capability DOMAIN to ONE precise skill,
-and the tool installs exactly that.
+- `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.