@hegemonart/get-design-done 1.28.5 → 1.28.7

package/skills/darkmode/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 Standalone dark mode audit. Detects the project's dark mode architecture, runs architecture-specific checks across contrast, token completeness, anti-patterns, and meta properties, then writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`.
 
-For the full step-by-step methodology (architecture-detection greps, WCAG contrast formula, anti-pattern grep snippets, meta-property checks, screenshot capture, and `DARKMODE-AUDIT.md` template), see `../../reference/darkmode-audit-procedure.md`. For the perceptual-contrast layer (APCA / WCAG 3 draft) sitting on top of WCAG 2.1 ratios, see `../../reference/contrast-advanced.md`. For OKLCH-based dark token-pair generation, see `../../reference/color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe pattern, see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`.
+For the full step-by-step methodology (architecture-detection greps, WCAG contrast formula, anti-pattern grep snippets, meta-property checks, screenshot capture, and `DARKMODE-AUDIT.md` template), see `./darkmode-audit-procedure.md`. For the perceptual-contrast layer (APCA / WCAG 3 draft) sitting on top of WCAG 2.1 ratios, see `../../reference/contrast-advanced.md`. For OKLCH-based dark token-pair generation, see `../../reference/color-theory.md` §OKLCH. For the cross-skill output discipline + connection-probe pattern, see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`.
 
 ---
 
@@ -39,13 +39,13 @@ Probe `preview` connection per `../../reference/shared-preamble.md#connection-ha
 
 ## Workflow
 
-1. **Architecture Detection (DARK-02)** — run three greps (CSS custom props / Tailwind `dark:` / JS class toggle), classify primary architecture or `Hybrid` or `None`. If `None`, abort. Detail: `../../reference/darkmode-audit-procedure.md#step-1-architecture-detection-dark-02`.
-2. **Contrast Audit (DARK-03)** — extract dark-context token pairs for the detected architecture, compute WCAG 2.1 ratios, flag failures at 4.5:1 (body) / 3:1 (large text + UI boundaries). Cross-check with APCA from `../../reference/contrast-advanced.md` for thin / large / colored text. Detail: `../../reference/darkmode-audit-procedure.md#step-2-contrast-audit-dark-03`.
-3. **Token Override Completeness (DARK-04)** — every light-mode color token must have a dark-mode override. Flag missing overrides → P1. Detail: `../../reference/darkmode-audit-procedure.md#step-3-token-override-completeness-dark-04`.
-4. **Dark-Specific Anti-Patterns (DARK-05)** — Images/SVGs without dark variant (P2), pure-black backgrounds in dark context = BAN-05 (P1), missing `@media (forced-colors)` (P2). Detail: `../../reference/darkmode-audit-procedure.md#step-4-dark-specific-anti-patterns-dark-05`.
-5. **Meta Property Check (DARK-06)** — `color-scheme` property + `prefers-color-scheme` query. Each absent → P2. Detail: `../../reference/darkmode-audit-procedure.md#step-5-meta-property-check-dark-06`.
-6. **Visual Rendering (preview: available only)** — capture light/dark screenshot pair to `.design/screenshots/darkmode/{light,dark}.png`. Detail: `../../reference/darkmode-audit-procedure.md#step-5b-dark-mode-rendering-screenshots-when-preview-available`.
-7. **Write `.design/DARKMODE-AUDIT.md`** — group flagged issues by priority (P0 → P1 → P2 → P3). Full template at `../../reference/darkmode-audit-procedure.md#step-6-darkmode-auditmd-template`.
+1. **Architecture Detection (DARK-02)** — run three greps (CSS custom props / Tailwind `dark:` / JS class toggle), classify primary architecture or `Hybrid` or `None`. If `None`, abort. Detail: `./darkmode-audit-procedure.md#step-1-architecture-detection-dark-02`.
+2. **Contrast Audit (DARK-03)** — extract dark-context token pairs for the detected architecture, compute WCAG 2.1 ratios, flag failures at 4.5:1 (body) / 3:1 (large text + UI boundaries). Cross-check with APCA from `../../reference/contrast-advanced.md` for thin / large / colored text. Detail: `./darkmode-audit-procedure.md#step-2-contrast-audit-dark-03`.
+3. **Token Override Completeness (DARK-04)** — every light-mode color token must have a dark-mode override. Flag missing overrides → P1. Detail: `./darkmode-audit-procedure.md#step-3-token-override-completeness-dark-04`.
+4. **Dark-Specific Anti-Patterns (DARK-05)** — Images/SVGs without dark variant (P2), pure-black backgrounds in dark context = BAN-05 (P1), missing `@media (forced-colors)` (P2). Detail: `./darkmode-audit-procedure.md#step-4-dark-specific-anti-patterns-dark-05`.
+5. **Meta Property Check (DARK-06)** — `color-scheme` property + `prefers-color-scheme` query. Each absent → P2. Detail: `./darkmode-audit-procedure.md#step-5-meta-property-check-dark-06`.
+6. **Visual Rendering (preview: available only)** — capture light/dark screenshot pair to `.design/screenshots/darkmode/{light,dark}.png`. Detail: `./darkmode-audit-procedure.md#step-5b-dark-mode-rendering-screenshots-when-preview-available`.
+7. **Write `.design/DARKMODE-AUDIT.md`** — group flagged issues by priority (P0 → P1 → P2 → P3). Full template at `./darkmode-audit-procedure.md#step-6-darkmode-auditmd-template`.
 
 ---
 

package/skills/debug/SKILL.md

@@ -7,15 +7,15 @@ tools: Read, Write, Grep, Glob, AskUserQuestion, Task
 
 # /gdd:debug
 
-Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./../reference/debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
+Systematic, checkpoint-driven design debugger. Loads framing from `./../reference/debugger-philosophy.md` (five principles) and the feedback-loop construction catalog from `./debug-feedback-loops.md` (10 priority-ordered loop paths). Phase 1 builds the loop; Phase 2 generates hypotheses. Writes every step to `.design/DEBUG.md` so killed sessions can resume.
 
 ## Steps
 
-1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./../reference/debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
+1. **Load philosophy + feedback-loop catalog**: Read `reference/debugger-philosophy.md` (five principles) and `./debug-feedback-loops.md` (10 construction paths; iterate-on-loop discipline). Keep both in mind for the entire session.
 2. **Symptom**: If no symptom argument was passed, ask (AskUserQuestion): "What design symptom are you investigating? (observable only — 'cards look crowded', not 'padding is wrong')"
 3. **Resume check**: Read `.design/DEBUG.md` if it exists. If there is an open session with no `### Fix Proposal` block, ask: "Resume existing session '<symptom>' or start a new one?"
 4. **Ground truth load**: Read `.design/DESIGN-PLAN.md` (goals), `.design/STATE.md` `<decisions>` block (D-XX items), and any source files pointed at by the symptom.
-5. **Phase 1 — Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./../reference/debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
+5. **Phase 1 — Build a feedback loop**: Before ANY hypothesizing, build a deterministic, fast, agent-runnable pass/fail signal that reproduces the symptom. See `./debug-feedback-loops.md` for the 10 construction paths in priority order (failing test > curl > CLI fixture > headless browser > trace replay > throwaway harness > fuzz > bisect > differential > HITL bash). Iterate on the loop itself (cache setup, narrow scope, pin time, seed RNG, isolate filesystem, freeze network) before iterating on the bug. For non-deterministic bugs: raise reproduction rate to at least 30%, not clean repro. **Do not proceed to Phase 2 (hypothesis generation) until you have a loop you believe in.**
 6. **Optional rendered-output check**: Use ToolSearch to see if Playwright/Preview MCP tools are available. If yes, capture rendered state. If no, fall back to code-only analysis.
 7. **Phase 2 — Investigation loop** (one hypothesis at a time) — for each step:
    - Form one hypothesis (one variable).

package/skills/design/SKILL.md

@@ -10,7 +10,7 @@ tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get
 
 **Stage 4 of 5** in the get-design-done pipeline. Thin orchestrator. All design execution intelligence lives in `agents/design-executor.md`.
 
-Full procedure detail: `../../reference/design-procedure.md`.
+Full procedure detail: `./design-procedure.md`.
 
 ---
 
@@ -20,7 +20,7 @@ Full procedure detail: `../../reference/design-procedure.md`.
 2. `mcp__gdd_state__get` -> snapshot `state`; read `state.position.wave` for execution plan.
 3. Abort only if `.design/DESIGN-PLAN.md` is missing: "No plan found. Run `/get-design-done:plan` first."
 
-Detail: `../../reference/design-procedure.md` §Stage entry.
+Detail: `./design-procedure.md` §Stage entry.
 
 ---
 
@@ -30,7 +30,7 @@ Detail: `../../reference/design-procedure.md` §Stage entry.
 - `--parallel` -> `parallel_mode=true` (use worktree isolation for `Parallel: true` tasks).
 - **Directionally-open check** (skipped if `auto_mode`): scan DESIGN-PLAN.md for tasks whose criteria read "explore N directions" / "pick a visual approach" and suggest `/gdd:sketch` first.
 - **Project-local conventions**: include any `./.claude/skills/design-*-conventions.md` and `~/.claude/gdd/global-skills/*.md` in every executor's `<required_reading>` — global conventions inform but do not override project-local D-XX decisions.
-- **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `../../reference/design-procedure.md` §.stories.tsx Stub.
+- **`.stories.tsx` stub**: after each new component file is created by the executor, emit a CSF stub alongside if `.storybook/` exists or `"storybook"` is in `package.json`, even with the dev server offline. Detail: `./design-procedure.md` §.stories.tsx Stub.
 
 ---
 
@@ -49,7 +49,7 @@ For each wave in order:
 3. **Parallel batch** (when `parallel_mode=true` AND any `Parallel: true` tasks in wave): announce the partition, spawn all `Parallel: true` tasks via concurrent `Task("design-executor", ..., isolation: "worktree")` calls in ONE response, wait for all `## EXECUTION COMPLETE` markers, merge worktrees (non-overlapping `Touches:` guarantees no conflicts; surface any conflict to the user before continuing), then `update_progress` + `checkpoint`.
 4. **Sequential tail** (`Parallel: false` or `parallel_mode=false`): spawn one `design-executor` at a time (no worktree isolation), waiting for each `## EXECUTION COMPLETE` and emitting `update_progress` per task; `checkpoint` after the final task of the wave.
 
-Full executor prompts (parallel + sequential variants) and the merge-worktrees protocol: `../../reference/design-procedure.md` §Step 2.
+Full executor prompts (parallel + sequential variants) and the merge-worktrees protocol: `./design-procedure.md` §Step 2.
 
 ---
 
@@ -70,12 +70,12 @@ Check task-NN.md files for `status: deviation`. If found: `mcp__gdd_state__get`
 
 ## After Completion
 
-Print the `=== Design stage complete ===` summary (tasks complete/total, deviations, commits since stage start, next step `/get-design-done:verify`). Template: `../../reference/design-procedure.md` §After Completion.
+Print the `=== Design stage complete ===` summary (tasks complete/total, deviations, commits since stage start, next step `/get-design-done:verify`). Template: `./design-procedure.md` §After Completion.
 
 ---
 
 ## Figma Write Dispatch
 
-After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `../../reference/design-procedure.md` §Figma Write Dispatch.
+After all tasks finish, if STATE.md `<connections>` has `figma: available`, offer the user the figma-write opt-in prompt (modes: annotate / tokenize / mappings, with optional `--dry-run`). Spawn `design-figma-writer` with the selected mode on "yes"; skip silently on "no". NEVER auto-run without confirmation. Full prompt + dispatch logic: `./design-procedure.md` §Figma Write Dispatch.
 
 ## DESIGN COMPLETE

package/skills/discover/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 **Stage 1.5 of 4.** Produces `.design/DESIGN-CONTEXT.md`.
 
-Full procedure detail: `../../reference/discover-procedure.md`.
+Full procedure detail: `./discover-procedure.md`.
 
 ---
 
@@ -19,26 +19,26 @@ Full procedure detail: `../../reference/discover-procedure.md`.
    - **Missing** -> create minimal skeleton from `reference/STATE-TEMPLATE.md` (stage=discover, status=in_progress, task_progress=0/1) and log warning "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
    - **Present + stage==discover + status==in_progress** -> RESUME (continue interview; do not reset).
    - **Otherwise** -> normal transition: set frontmatter stage=discover, `<position>` stage=discover, status=in_progress, task_progress=0/1.
-2. Probe connection availability. ToolSearch runs FIRST (MCP tools may be in the deferred tool set). Run three probes — A (Figma, variant-agnostic with prefix tiebreaker), B (Refero, ToolSearch-only), C (Pinterest, ToolSearch-only). After all probes, write `<connections>` to STATE.md so the builder doesn't re-probe. Full probe specs: `../../reference/discover-procedure.md` §Connection Probes.
+2. Probe connection availability. ToolSearch runs FIRST (MCP tools may be in the deferred tool set). Run three probes — A (Figma, variant-agnostic with prefix tiebreaker), B (Refero, ToolSearch-only), C (Pinterest, ToolSearch-only). After all probes, write `<connections>` to STATE.md so the builder doesn't re-probe. Full probe specs: `./discover-procedure.md` §Connection Probes.
 3. Update `last_checkpoint`. Write STATE.md.
 
 ---
 
 ## Auto Mode
 
-When `--auto` is passed to the builder: if `tailwind.config.{js,cjs,mjs,ts}` exists -> Tailwind-only project (skip CSS file grep, parse tailwind.config for palette/spacing/font, use those as the baseline style signal). Else fall through to the existing CSS file grep logic. Detail: `../../reference/discover-procedure.md` §Auto Mode.
+When `--auto` is passed to the builder: if `tailwind.config.{js,cjs,mjs,ts}` exists -> Tailwind-only project (skip CSS file grep, parse tailwind.config for palette/spacing/font, use those as the baseline style signal). Else fall through to the existing CSS file grep logic. Detail: `./discover-procedure.md` §Auto Mode.
 
 ---
 
 ## Step 1 — Spawn design-context-builder
 
-Spawn `design-context-builder` -> `.design/DESIGN-CONTEXT.md`. The agent auto-detects via grep/glob first and interviews only for areas where auto-detect returned no confident answer. Baseline audit directory chain: `src/` -> `app/` -> `pages/` -> `lib/` -> flag "layout unknown". Common gray areas to probe (Area 7): font-change risk, token-layer introduction risk, component rebuild-vs-restyle. Wait for `## CONTEXT COMPLETE`, then update STATE.md `task_progress = 0.5`. Full prompt: `../../reference/discover-procedure.md` §Step 1.
+Spawn `design-context-builder` -> `.design/DESIGN-CONTEXT.md`. The agent auto-detects via grep/glob first and interviews only for areas where auto-detect returned no confident answer. Baseline audit directory chain: `src/` -> `app/` -> `pages/` -> `lib/` -> flag "layout unknown". Common gray areas to probe (Area 7): font-change risk, token-layer introduction risk, component rebuild-vs-restyle. Wait for `## CONTEXT COMPLETE`, then update STATE.md `task_progress = 0.5`. Full prompt: `./discover-procedure.md` §Step 1.
 
 ---
 
 ## Step 1.75 — Lazy gate: should design-context-checker run? (Plan 10.1-04, D-21)
 
-Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker. It applies the single-file heuristic (is `DESIGN-CONTEXT.md` in `git diff --name-only HEAD~1..HEAD`?) and emits JSON + `## GATE COMPLETE`. On `spawn: false`: append `lazy_skipped: true` telemetry row, skip Step 2, set STATE.md `<position>` as if checker passed. On `spawn: true`: proceed to Step 2. On first-run discover the gate always returns `spawn: true` (builder just wrote the file); the gate meaningfully short-circuits only on re-runs where the builder made no changes. Full prompt: `../../reference/discover-procedure.md` §Step 1.75.
+Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker. It applies the single-file heuristic (is `DESIGN-CONTEXT.md` in `git diff --name-only HEAD~1..HEAD`?) and emits JSON + `## GATE COMPLETE`. On `spawn: false`: append `lazy_skipped: true` telemetry row, skip Step 2, set STATE.md `<position>` as if checker passed. On `spawn: true`: proceed to Step 2. On first-run discover the gate always returns `spawn: true` (builder just wrote the file); the gate meaningfully short-circuits only on re-runs where the builder made no changes. Full prompt: `./discover-procedure.md` §Step 1.75.
 
 **Parallel synthesizer note:** discover does not spawn parallel researchers in v1, so `skills/synthesize/` is not wired here. If future variants spawn N parallel interviewers, wire synthesize between dispatch and collate as in `skills/map/` Step 3.5.
 
@@ -46,7 +46,7 @@ Spawn the cheap Haiku gate `design-context-checker-gate` before the full checker
 
 ## Step 2 — Spawn design-context-checker
 
-Spawn `design-context-checker` with `<required_reading>` on STATE.md + DESIGN-CONTEXT.md. The agent validates DESIGN-CONTEXT.md across 6 dimensions and returns APPROVED or BLOCKED with per-dimension verdicts. Wait for `## CONTEXT CHECK COMPLETE`. Full prompt: `../../reference/discover-procedure.md` §Step 2.
+Spawn `design-context-checker` with `<required_reading>` on STATE.md + DESIGN-CONTEXT.md. The agent validates DESIGN-CONTEXT.md across 6 dimensions and returns APPROVED or BLOCKED with per-dimension verdicts. Wait for `## CONTEXT CHECK COMPLETE`. Full prompt: `./discover-procedure.md` §Step 2.
 
 ---
 
@@ -67,6 +67,6 @@ Spawn `design-context-checker` with `<required_reading>` on STATE.md + DESIGN-CO
 
 ## After Writing
 
-Print the "=== Discovery complete ===" block with saved path, baseline score, top key issues, and next step (`/get-design-done:plan`). Do not proceed to planning automatically unless `--auto` was passed. Template: `../../reference/discover-procedure.md` §After Writing.
+Print the "=== Discovery complete ===" block with saved path, baseline score, top key issues, and next step (`/get-design-done:plan`). Do not proceed to planning automatically unless `--auto` was passed. Template: `./discover-procedure.md` §After Writing.
 
 ## DISCOVER COMPLETE

package/skills/explore/SKILL.md

@@ -11,7 +11,7 @@ tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get
 
 **Purpose:** Unified exploration merging the former `scan` (inventory grep) and `discover` (context interview) stages. Produces `.design/DESIGN.md`, `.design/DESIGN-DEBT.md`, and `.design/DESIGN-CONTEXT.md`.
 
-Full procedure detail: `../../reference/explore-procedure.md`.
+Full procedure detail: `./explore-procedure.md`.
 
 ---
 
@@ -35,11 +35,11 @@ Probe six connections, then batch-write results via ONE `mcp__gdd_state__probe_c
 - **E — paper.design**: ToolSearch `mcp__paper` + live `get_selection` call.
 - **F — pencil.dev**: `find . -name "*.pen"` file-presence.
 
-Full probe specs + commit-results JSON shape: `../../reference/explore-procedure.md` §Step 1.
+Full probe specs + commit-results JSON shape: `./explore-procedure.md` §Step 1.
 
 ## Step 1.5 — 21st.dev Prior-Art Check (when `21st-dev: available`)
 
-For each greenfield component in scope: `21st_magic_component_search(component_name, limit: 3)`. Fit >= 80% -> add `<prior-art>` block to DESIGN.md recommending adoption; fit < 80% -> note as reference, build custom. If `svgl_get_brand_logo` available and brand assets are in scope, call per logo and save SVGs to `.design/assets/`. Skip entirely if no greenfield components in scope. Detail: `../../reference/explore-procedure.md` §Step 1.5.
+For each greenfield component in scope: `21st_magic_component_search(component_name, limit: 3)`. Fit >= 80% -> add `<prior-art>` block to DESIGN.md recommending adoption; fit < 80% -> note as reference, build custom. If `svgl_get_brand_logo` available and brand assets are in scope, call per logo and save SVGs to `.design/assets/`. Skip entirely if no greenfield components in scope. Detail: `./explore-procedure.md` §Step 1.5.
 
 ---
 
@@ -49,9 +49,9 @@ For each greenfield component in scope: `21st_magic_component_search(component_n
 
 **Parallelism decision**: read `.design/config.json` + `reference/parallelism-rules.md`. Record verdict via `mcp__gdd_state__set_status` (`"explore_parallel"` / `"explore_serial"`). Parallel -> multiple `Task()` in one response; serial -> sequential.
 
-Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): component detection (Glob `**/*.{tsx,jsx,vue,svelte}`), color extraction (hex / rgb / hsl / Tailwind arbitrary), typography scan (font-family / Tailwind `font-*` / `text-*`), motion scan (`transition` / `animate-` / `@keyframes` / `framer-motion`), token detection (tailwind.config / CSS custom properties / token JSON), layout detection (ordered fallback `src/` -> `app/` -> `pages/` -> `lib/` -> unknown). Write `.design/DESIGN.md` + `.design/DESIGN-DEBT.md`. Then `mcp__gdd_state__update_progress` for scan progress. Detail: `../../reference/explore-procedure.md` §Step 2.
+Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): component detection (Glob `**/*.{tsx,jsx,vue,svelte}`), color extraction (hex / rgb / hsl / Tailwind arbitrary), typography scan (font-family / Tailwind `font-*` / `text-*`), motion scan (`transition` / `animate-` / `@keyframes` / `framer-motion`), token detection (tailwind.config / CSS custom properties / token JSON), layout detection (ordered fallback `src/` -> `app/` -> `pages/` -> `lib/` -> unknown). Write `.design/DESIGN.md` + `.design/DESIGN-DEBT.md`. Then `mcp__gdd_state__update_progress` for scan progress. Detail: `./explore-procedure.md` §Step 2.
 
-**Step 2.x — i18n readiness probe (informational, per D-04)**: check `package.json` deps against `{react-intl, next-intl, i18next, vue-i18n, formatjs, lingui}` -> `framework-managed`; else grep `Intl.(DateTimeFormat|NumberFormat|...)` in `src/` -> `partial`; else `none`. Emit single line `Localization readiness: <state>` in the report. NO gate, NO blocking — surface signal only (D-07). Detail: `../../reference/explore-procedure.md` §Step 2.x.
+**Step 2.x — i18n readiness probe (informational, per D-04)**: check `package.json` deps against `{react-intl, next-intl, i18next, vue-i18n, formatjs, lingui}` -> `framework-managed`; else grep `Intl.(DateTimeFormat|NumberFormat|...)` in `src/` -> `partial`; else `none`. Emit single line `Localization readiness: <state>` in the report. NO gate, NO blocking — surface signal only (D-07). Detail: `./explore-procedure.md` §Step 2.x.
 
 ## Step 2.5 — Detect prior sketches and project-local conventions
 
@@ -71,7 +71,7 @@ Run the canonical scan grep/glob inventory (POSIX ERE, preserving PLAT-01/02): c
 - **3.d Record after each answer**: `mcp__gdd_state__add_decision` (atomic, auto-assigns D-NN); append a quality-classified JSON line to `.design/learnings/question-quality.jsonl`.
 - **3.e Produce DESIGN-CONTEXT.md**: summarize locked decisions, remaining gray areas, Figma tentatives. Frontmatter `status: complete`.
 
-Full interview protocol + JSON line schema: `../../reference/explore-procedure.md` §Step 3.
+Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
 
 ---
 

package/skills/health/SKILL.md

@@ -55,7 +55,7 @@ Health: 5 / 6 checks passing.
 
 ## Check MCP registration (gdd-mcp)
 
-After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./reference/health-mcp-detection.md`.
+After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.
 
 ## Update notice (safe-window surface)
 
@@ -74,7 +74,7 @@ After the health table, surface the Phase 28.5 skill-authoring contract drift si
 - `Skill-length: <total> total | <clean> clean | <warnings> warn (>=100) | <blockers> block (>=250)`
 - If blockers > 0: list each blocker as a row `- <name> (<lines> lines)`. Else: print `All skills within contract.`
 
-Thresholds: warn >=100, block >=250 (D-01). Strict description-format off by default (D-02). See `./reference/health-skill-length-report.md` for the JSON shape and threshold rationale.
+Thresholds: warn >=100, block >=250 (D-01). Strict description-format off by default (D-02). See `./health-skill-length-report.md` for the JSON shape and threshold rationale.
 
 ## Do Not
 

package/skills/new-cycle/SKILL.md

@@ -7,7 +7,7 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:new-cycle
 
-The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./reference/milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
 
 ## Steps
 

package/skills/peer-cli-add/SKILL.md

@@ -11,7 +11,7 @@ tools: Read, Edit, Write, Bash, Grep
 
 ## Role
 
-You add a brand-new peer-CLI to gdd's delegation layer. v1.27.0 ships 5 peers (codex, gemini, cursor, copilot, qwen). When the user wants a 6th — a peer that exists in the wild but isn't in our capability matrix — you walk them through the verification ladder and produce the 3-file footprint that integrates the peer cleanly. The procedural ladder, adapter scaffold shape, and verification gate live in `./reference/peer-cli-protocol.md`.
+You add a brand-new peer-CLI to gdd's delegation layer. v1.27.0 ships 5 peers (codex, gemini, cursor, copilot, qwen). When the user wants a 6th — a peer that exists in the wild but isn't in our capability matrix — you walk them through the verification ladder and produce the 3-file footprint that integrates the peer cleanly. The procedural ladder, adapter scaffold shape, and verification gate live in `./peer-cli-protocol.md`.
 
 ## Invocation Contract
 
@@ -22,7 +22,7 @@ You add a brand-new peer-CLI to gdd's delegation layer. v1.27.0 ships 5 peers (c
 
 ### Step 1 — Verification ladder (no edits yet)
 
-Walk the four-rung ladder in `./reference/peer-cli-protocol.md` §"Verification ladder":
+Walk the four-rung ladder in `./peer-cli-protocol.md` §"Verification ladder":
 
 1. Binary on PATH (`which` / `where`).
 2. Handshake test (`initialize` JSON-RPC over stdin; capture reply).
@@ -33,13 +33,13 @@ Stop at the first failing rung. Do not proceed to scaffold a broken adapter.
 
 ### Step 2 — Generate the adapter scaffold
 
-Copy one of `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` as the template (pick by protocol — ASP for `<protocol>=asp`, else ACP). Replace `ROLES_CLAIMED`, `ROLE_PREFIX`, `name`, `protocol` with the user's values from Step 1. The full adapter scaffold shape — `claims`, `dispatch`, exports — lives in `./reference/peer-cli-protocol.md` §"Adapter scaffold shape" so consumers (codex/gemini/cursor/copilot/qwen) stay byte-similar.
+Copy one of `scripts/lib/peer-cli/adapters/{codex,gemini,cursor,copilot,qwen}.cjs` as the template (pick by protocol — ASP for `<protocol>=asp`, else ACP). Replace `ROLES_CLAIMED`, `ROLE_PREFIX`, `name`, `protocol` with the user's values from Step 1. The full adapter scaffold shape — `claims`, `dispatch`, exports — lives in `./peer-cli-protocol.md` §"Adapter scaffold shape" so consumers (codex/gemini/cursor/copilot/qwen) stay byte-similar.
 
 Write the result to `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs`.
 
 ### Step 3 — Three-file footprint
 
-Per `./reference/peer-cli-protocol.md` §"Three-file footprint":
+Per `./peer-cli-protocol.md` §"Three-file footprint":
 
 1. New adapter at `scripts/lib/peer-cli/adapters/<new-peer-id>.cjs` (Step 2).
 2. Edit `scripts/lib/install/runtimes.cjs` — add `peerBinary` field (platform-aware: `<peer-binary>.cmd` on Windows, plain on POSIX).
@@ -48,7 +48,7 @@ Per `./reference/peer-cli-protocol.md` §"Three-file footprint":
 
 ### Step 4 — Verification gate
 
-Run the four-check gate in `./reference/peer-cli-protocol.md` §"Verification gate": `tsc --noEmit`, peer-cli tests, reference-registry round-trip, frontmatter validator. Any failure — surface error + offer revert.
+Run the four-check gate in `./peer-cli-protocol.md` §"Verification gate": `tsc --noEmit`, peer-cli tests, reference-registry round-trip, frontmatter validator. Any failure — surface error + offer revert.
 
 ### Step 5 — Surface the summary
 
@@ -77,7 +77,7 @@ Next steps:
 
 ## Edge cases
 
-See `./reference/peer-cli-protocol.md` §"Edge cases" for: peer speaks neither protocol, claims unknown role, claims all roles (generalist), peer-ID conflicts, and testing-only peers.
+See `./peer-cli-protocol.md` §"Edge cases" for: peer speaks neither protocol, claims unknown role, claims all roles (generalist), peer-ID conflicts, and testing-only peers.
 
 ## Record
 

package/skills/peer-cli-customize/SKILL.md

@@ -11,7 +11,7 @@ tools: Read, Edit, Bash, Grep
 
 ## Role
 
-You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) — there is no runtime config layer. Your job is to make this safe and validatable. The rewire discipline (per-edit validation, three frontmatter cases, validator gate) lives in `./reference/peer-cli-protocol.md` §"Rewire discipline" so the procedure stays canonical across consumers.
+You help the user rewire which peer-CLI delegate handles which agent's calls. The mechanism is direct file-edits to agent frontmatter (`delegate_to:` field added in Plan 27-06) — there is no runtime config layer. Your job is to make this safe and validatable. The rewire discipline (per-edit validation, three frontmatter cases, validator gate) lives in `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline" so the procedure stays canonical across consumers.
 
 ## Invocation Contract
 
@@ -36,7 +36,7 @@ Valid `<new-delegate-target>` values:
 
 ### Step 3 — Validate the proposed rewire
 
-Cross-check against the capability matrix per `./reference/peer-cli-protocol.md` §"Rewire discipline":
+Cross-check against the capability matrix per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline":
 
 1. The peer must exist in the matrix.
 2. The role must be in the peer's `claims` list.
@@ -46,7 +46,7 @@ If validation fails, surface the error and stop. Do not edit the file.
 
 ### Step 4 — Apply the edit
 
-Use the `Edit` tool. Three cases (per `./reference/peer-cli-protocol.md` §"Rewire discipline"):
+Use the `Edit` tool. Three cases (per `./../peer-cli-add/peer-cli-protocol.md` §"Rewire discipline"):
 
 - **Field absent, user wants to add:** insert `delegate_to: <new-target>` into frontmatter (between `default-tier:` and the next field, or at the end of frontmatter).
 - **Field present, user wants to change:** replace the value; preserve indentation.
@@ -71,11 +71,11 @@ Verify: /gdd:peers (shows updated allowlist + capability matrix).
 
 ## Edge cases
 
-See `./reference/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmatrixed-peer (direct user to `peer-cli-add` first), rewire-to-unclaimed-role (refuse with helpful list), bulk-rewire (require explicit confirmation), validator-fails-post-edit (revert and surface).
+See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmatrixed-peer (direct user to `peer-cli-add` first), rewire-to-unclaimed-role (refuse with helpful list), bulk-rewire (require explicit confirmation), validator-fails-post-edit (revert and surface).
 
 ## Cross-references
 
-- `./reference/peer-cli-protocol.md` — rewire discipline, three frontmatter cases, edge cases.
+- `./../peer-cli-add/peer-cli-protocol.md` — rewire discipline, three frontmatter cases, edge cases.
 - `scripts/validate-frontmatter.ts` (Plan 27-06) — `delegate_to` validation.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) — capability matrix.
 - `skills/peer-cli-add/SKILL.md` — for adding a NEW peer (this skill rewires among existing peers).

package/skills/peers/SKILL.md

@@ -9,7 +9,7 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/telemetry/posterior.json` (canonical path declared by `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), then emit a single Markdown table summarizing peer-CLI status. Protocol-level handshake details live in `./reference/peer-cli-protocol.md`.
+You are a deterministic discovery skill. You do not spawn agents and do not delegate to peers. You read `scripts/lib/install/runtimes.cjs`, `scripts/lib/peer-cli/registry.cjs`, `.design/config.json`, and (optionally) `.design/telemetry/posterior.json` (canonical path declared by `bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), then emit a single Markdown table summarizing peer-CLI status. Protocol-level handshake details live in `./../peer-cli-add/peer-cli-protocol.md`.
 
 ## Invocation Contract
 
@@ -83,7 +83,7 @@ The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)
 
 ## Cross-references
 
-- `./reference/peer-cli-protocol.md` — ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
+- `./../peer-cli-add/peer-cli-protocol.md` — ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
 - `./reference/peer-cli-capabilities.md` (Plan 27-05) — full capability matrix doc.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`, `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10.
 

package/skills/plan/SKILL.md

@@ -10,7 +10,7 @@ tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_stat
 
 **Stage 3 of 5** in the get-design-done pipeline. Thin orchestrator. All planning intelligence lives in `agents/design-planner.md`.
 
-Full procedure detail: `../../reference/plan-procedure.md`.
+Full procedure detail: `./plan-procedure.md`.
 
 ---
 
@@ -30,39 +30,39 @@ Full procedure detail: `../../reference/plan-procedure.md`.
 
 ## Probe Chromatic connection
 
-Probe `chromatic` (CLI presence + `CHROMATIC_PROJECT_TOKEN` check; auto-`unavailable` if `storybook: not_configured`), then write status via `mcp__gdd_state__probe_connections` (single-entry array, never edit `<connections>` directly). Detail: `../../reference/plan-procedure.md` §Probe Chromatic connection.
+Probe `chromatic` (CLI presence + `CHROMATIC_PROJECT_TOKEN` check; auto-`unavailable` if `storybook: not_configured`), then write status via `mcp__gdd_state__probe_connections` (single-entry array, never edit `<connections>` directly). Detail: `./plan-procedure.md` §Probe Chromatic connection.
 
-When `chromatic: available`, run change-risk scoping before writing DESIGN-PLAN.md: identify token/component files in scope from DESIGN-CONTEXT.md, run `npx chromatic --trace-changed=expanded --dry-run`, count story files that depend on changed source files, and pass the story count to the design-planner spawn prompt. Detail: `../../reference/plan-procedure.md` §Chromatic Change-Risk Scoping.
+When `chromatic: available`, run change-risk scoping before writing DESIGN-PLAN.md: identify token/component files in scope from DESIGN-CONTEXT.md, run `npx chromatic --trace-changed=expanded --dry-run`, count story files that depend on changed source files, and pass the story count to the design-planner spawn prompt. Detail: `./plan-procedure.md` §Chromatic Change-Risk Scoping.
 
 ---
 
 ## Step 1 — Optional Research (skip if `auto_mode`)
 
-Complexity heuristic: DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn `design-phase-researcher` -> `.design/DESIGN-RESEARCH.md` (~100 lines, ~2 min). Wait for `## RESEARCH COMPLETE`, then `update_progress` `task_progress: "1/3"`. Full prompt: `../../reference/plan-procedure.md` §Step 1.
+Complexity heuristic: DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 -> spawn `design-phase-researcher` -> `.design/DESIGN-RESEARCH.md` (~100 lines, ~2 min). Wait for `## RESEARCH COMPLETE`, then `update_progress` `task_progress: "1/3"`. Full prompt: `./plan-procedure.md` §Step 1.
 
 ## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
 
-Spawn `design-pattern-mapper` -> `.design/DESIGN-PATTERNS.md` (classify by design concern, not by code architecture — no controllers/services/middleware vocabulary). Wait for `## MAPPING COMPLETE`. Full prompt: `../../reference/plan-procedure.md` §Step 1.5.
+Spawn `design-pattern-mapper` -> `.design/DESIGN-PATTERNS.md` (classify by design concern, not by code architecture — no controllers/services/middleware vocabulary). Wait for `## MAPPING COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.5.
 
 ## Step 1.6 — Assumptions Analysis (skip if `auto_mode`)
 
-If assumptions analysis is enabled: spawn `design-assumptions-analyzer` -> surfaces hidden design assumptions with confidence + evidence. Wait for `## ANALYSIS COMPLETE`. Full prompt: `../../reference/plan-procedure.md` §Step 1.6.
+If assumptions analysis is enabled: spawn `design-assumptions-analyzer` -> surfaces hidden design assumptions with confidence + evidence. Wait for `## ANALYSIS COMPLETE`. Full prompt: `./plan-procedure.md` §Step 1.6.
 
 ## Step 1.7 — Synthesize pre-plan inputs (Plan 10.1-04, D-13/D-15)
 
-If 2+ pre-plan agents ran (Step 1, 1.5, 1.6), invoke `Skill("synthesize", { outputs, directive, output_shape: "markdown" })` to merge their outputs into `.design/DESIGN-PREPLAN-BRIEF.md` (~150 lines, per-source headers preserved). Add the brief to the planner's `<required_reading>` in Step 2. If only one agent ran, skip. Full call signature + parallel-synthesizer note: `../../reference/plan-procedure.md` §Step 1.7.
+If 2+ pre-plan agents ran (Step 1, 1.5, 1.6), invoke `Skill("synthesize", { outputs, directive, output_shape: "markdown" })` to merge their outputs into `.design/DESIGN-PREPLAN-BRIEF.md` (~150 lines, per-source headers preserved). Add the brief to the planner's `<required_reading>` in Step 2. If only one agent ran, skip. Full call signature + parallel-synthesizer note: `./plan-procedure.md` §Step 1.7.
 
-**Research-synthesis persistence:** for each D-XX the synthesizer produces, `mcp__gdd_state__add_decision`; for each M-XX, `mcp__gdd_state__add_must_have`. Issue sequentially (lockfile-bound). Detail: `../../reference/plan-procedure.md` §Research-synthesis persistence.
+**Research-synthesis persistence:** for each D-XX the synthesizer produces, `mcp__gdd_state__add_decision`; for each M-XX, `mcp__gdd_state__add_must_have`. Issue sequentially (lockfile-bound). Detail: `./plan-procedure.md` §Research-synthesis persistence.
 
 ---
 
 ## Step 2 — Plan
 
-Spawn `design-planner` with `<required_reading>` covering STATE.md, DESIGN-CONTEXT.md, DESIGN-PATTERNS.md, plus (conditionally) DESIGN-RESEARCH.md, DESIGN-ASSUMPTIONS.md, DESIGN-PREPLAN-BRIEF.md (preferred when 1.7 ran), all `.design/sketches/*/WINNER.md`, all `.design/spikes/*/FINDINGS.md`, and all `./.claude/skills/design-*-conventions.md` + `~/.claude/gdd/global-skills/*.md` (project-local D-XX overrides globals). Wait for `## PLANNING COMPLETE`, then `update_progress` `task_progress: "2/3"`. Full prompt + conditional include syntax: `../../reference/plan-procedure.md` §Step 2.
+Spawn `design-planner` with `<required_reading>` covering STATE.md, DESIGN-CONTEXT.md, DESIGN-PATTERNS.md, plus (conditionally) DESIGN-RESEARCH.md, DESIGN-ASSUMPTIONS.md, DESIGN-PREPLAN-BRIEF.md (preferred when 1.7 ran), all `.design/sketches/*/WINNER.md`, all `.design/spikes/*/FINDINGS.md`, and all `./.claude/skills/design-*-conventions.md` + `~/.claude/gdd/global-skills/*.md` (project-local D-XX overrides globals). Wait for `## PLANNING COMPLETE`, then `update_progress` `task_progress: "2/3"`. Full prompt + conditional include syntax: `./plan-procedure.md` §Step 2.
 
 ## Step 3 — Check
 
-Spawn `design-plan-checker` to validate DESIGN-PLAN.md against DESIGN-CONTEXT.md across 5 dimensions: requirement coverage, task completeness, wave ordering, must-have derivation, auto-mode compliance. Wait for `## PLAN CHECK COMPLETE`, then `update_progress` `task_progress: "3/3"`. On `## PLAN CHECK RESULT: ISSUES FOUND` + BLOCKER: offer revise/accept/abort (`auto_mode`: auto-accept WARN, abort on BLOCKER). Full prompt + branching: `../../reference/plan-procedure.md` §Step 3.
+Spawn `design-plan-checker` to validate DESIGN-PLAN.md against DESIGN-CONTEXT.md across 5 dimensions: requirement coverage, task completeness, wave ordering, must-have derivation, auto-mode compliance. Wait for `## PLAN CHECK COMPLETE`, then `update_progress` `task_progress: "3/3"`. On `## PLAN CHECK RESULT: ISSUES FOUND` + BLOCKER: offer revise/accept/abort (`auto_mode`: auto-accept WARN, abort on BLOCKER). Full prompt + branching: `./plan-procedure.md` §Step 3.
 
 ---
 

package/skills/quality-gate/SKILL.md

@@ -87,4 +87,4 @@ Emit one JSON object on stdout: `{status, iteration, commands_run, started_at, c
 - Do not invoke verify or design — Stage 4.5 sits strictly between.
 - Exit-code convention: `0` clean; non-zero classified as failure. Do not interpret stderr for pass/fail.
 
-For verify-side severity classification (when this gate's `status="fail"` reaches the verify entry gate), see `./reference/threat-modeling.md` — STRIDE dispositions are the audit-side framework that informs whether a failed quality gate blocks ship.
+For verify-side severity classification (when this gate's `status="fail"` reaches the verify entry gate), see `./threat-modeling.md` — STRIDE dispositions are the audit-side framework that informs whether a failed quality gate blocks ship.

package/skills/router/SKILL.md

@@ -53,15 +53,15 @@ Existing consumers reading any subset of the older fields keep working unchanged
 
 ## Path Selection Heuristic
 
-The router emits `path` (3-tier: `fast|quick|full`, legacy enum, stable for back-compat) AND `complexity_class` (4-tier: `S|M|L|XL`, Phase 25 / D-04 additive). Full mapping table, bucket-assignment signal list, `--dry-run` downgrade rule, and the S-class short-circuit semantics live in `./reference/router-rules.md#path-selection-heuristic`. The S-class short-circuit is load-bearing: when `complexity_class` would be `S`, the router does not run; the deterministic skip list lives in the `/gdd:*` SKILL.md entry, and the budget-enforcer hook treats "no payload + matching command name" as the S signal.
+The router emits `path` (3-tier: `fast|quick|full`, legacy enum, stable for back-compat) AND `complexity_class` (4-tier: `S|M|L|XL`, Phase 25 / D-04 additive). Full mapping table, bucket-assignment signal list, `--dry-run` downgrade rule, and the S-class short-circuit semantics live in `./router-rules.md#path-selection-heuristic`. The S-class short-circuit is load-bearing: when `complexity_class` would be `S`, the router does not run; the deterministic skip list lives in the `/gdd:*` SKILL.md entry, and the budget-enforcer hook treats "no payload + matching command name" as the S signal.
 
 ## Cost Estimation Algorithm
 
-Standard cost-estimation pseudocode (sum over planned spawn graph; per-agent `(in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate` using `./reference/model-prices.md`) lives in `./reference/router-rules.md#cost-estimation-algorithm`.
+Standard cost-estimation pseudocode (sum over planned spawn graph; per-agent `(in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate` using `./reference/model-prices.md`) lives in `./router-rules.md#cost-estimation-algorithm`.
 
 ## Runtime-aware model resolution
 
-Computation contract for `resolved_models`, implementation surfaces (`scripts/lib/runtime-detect.cjs` + `scripts/lib/tier-resolver.cjs`), per-agent emission rules (including the JSON-`null` contract), and the Claude-runtime back-compat assertion live in `./reference/router-rules.md#runtime-aware-model-resolution`. Top-line: `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat; `resolved_models` runs the per-runtime translation additively on top.
+Computation contract for `resolved_models`, implementation surfaces (`scripts/lib/runtime-detect.cjs` + `scripts/lib/tier-resolver.cjs`), per-agent emission rules (including the JSON-`null` contract), and the Claude-runtime back-compat assertion live in `./router-rules.md#runtime-aware-model-resolution`. Top-line: `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat; `resolved_models` runs the per-runtime translation additively on top.
 
 ## Cache-Hit Detection
 

package/skills/scan/SKILL.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 **Pre-pipeline initializer.** Run once in any new or existing repo before starting the Discover -> Plan -> Design -> Verify pipeline.
 
-Full procedure detail: `../../reference/scan-procedure.md`.
+Full procedure detail: `./scan-procedure.md`.
 
 Produces:
 - `DESIGN.md` — snapshot of the existing design system as it actually is
@@ -26,9 +26,9 @@ Default: full scan of tokens, patterns, and anti-patterns. Component inventory i
 
 At scan entry, before running any step:
 
-1. Read or create `.design/STATE.md` from `reference/STATE-TEMPLATE.md` (set `stage=scan`, `status=in_progress`, `task_progress=0/8`; preserve `started_at` on resume). See `../../reference/scan-procedure.md` §State Integration for the full read/create/resume decision tree.
-2. Probe Figma + Refero connections (variant-agnostic ToolSearch + tiebreaker resolution). Detail: `../../reference/scan-procedure.md` §Probe connection availability.
-3. Run the four Phase 8 probes (preview, storybook, chromatic, graphify) and batch-write results to STATE.md `<connections>`. Detail: `../../reference/scan-procedure.md` §Phase 8 Connection Probes.
+1. Read or create `.design/STATE.md` from `reference/STATE-TEMPLATE.md` (set `stage=scan`, `status=in_progress`, `task_progress=0/8`; preserve `started_at` on resume). See `./scan-procedure.md` §State Integration for the full read/create/resume decision tree.
+2. Probe Figma + Refero connections (variant-agnostic ToolSearch + tiebreaker resolution). Detail: `./scan-procedure.md` §Probe connection availability.
+3. Run the four Phase 8 probes (preview, storybook, chromatic, graphify) and batch-write results to STATE.md `<connections>`. Detail: `./scan-procedure.md` §Phase 8 Connection Probes.
 4. Emit the first-run connection nudge if every probe returned `not_configured` AND `.design/config.json > connections_onboarding` is absent.
 5. Update `last_checkpoint`; persist STATE.md before proceeding to Step 1.
 
@@ -36,35 +36,35 @@ At scan entry, before running any step:
 
 ## Workflow
 
-The scan executes eight steps in order. Each step's full grep commands, analysis prompts, and decision rules live in `../../reference/scan-procedure.md` — keep that file open while executing.
+The scan executes eight steps in order. Each step's full grep commands, analysis prompts, and decision rules live in `./scan-procedure.md` — keep that file open while executing.
 
 ### Step 1 — Orient
 
-Detect framework, CSS approach, component count, style file count, token system. Detect source root by ordered fallback (`src/` -> `app/` -> `pages/` -> `lib/`) and substitute into subsequent grep commands. Log the detected source root in DESIGN.md frontmatter. Detail: `../../reference/scan-procedure.md` §Step 1.
+Detect framework, CSS approach, component count, style file count, token system. Detect source root by ordered fallback (`src/` -> `app/` -> `pages/` -> `lib/`) and substitute into subsequent grep commands. Log the detected source root in DESIGN.md frontmatter. Detail: `./scan-procedure.md` §Step 1.
 
 ### Step 2 — Extract Color System
 
-Grep hex / `oklch()` / `hsl()` / `rgb()` colors, CSS custom properties, and Tailwind color config. Analyze palette size, token discipline, AI-slop colors (#6366f1, #8b5cf6, #06b6d4), semantic naming, dark-mode purity. Produce a color inventory table. Detail: `../../reference/scan-procedure.md` §Step 2.
+Grep hex / `oklch()` / `hsl()` / `rgb()` colors, CSS custom properties, and Tailwind color config. Analyze palette size, token discipline, AI-slop colors (#6366f1, #8b5cf6, #06b6d4), semantic naming, dark-mode purity. Produce a color inventory table. Detail: `./scan-procedure.md` §Step 2.
 
 ### Step 2A — Figma Token Augmentation
 
-If `figma: available` in STATE.md `<connections>`: call `{prefix}get_variable_defs`, translate variables by type/name pattern, merge with grep-derived tokens (never replace). Skip silently if `figma` is `not_configured` or `unavailable`. Detail: `../../reference/scan-procedure.md` §Step 2A.
+If `figma: available` in STATE.md `<connections>`: call `{prefix}get_variable_defs`, translate variables by type/name pattern, merge with grep-derived tokens (never replace). Skip silently if `figma` is `not_configured` or `unavailable`. Detail: `./scan-procedure.md` §Step 2A.
 
 ### Step 3 — Extract Typography System
 
-Grep font families, sizes, weights, line-heights. Analyze family count, scale compliance, weight hierarchy, line-height on body, reflex-font signals. Read `${CLAUDE_PLUGIN_ROOT}/reference/typography.md` for comparison criteria. Detail: `../../reference/scan-procedure.md` §Step 3.
+Grep font families, sizes, weights, line-heights. Analyze family count, scale compliance, weight hierarchy, line-height on body, reflex-font signals. Read `${CLAUDE_PLUGIN_ROOT}/reference/typography.md` for comparison criteria. Detail: `./scan-procedure.md` §Step 3.
 
 ### Step 4 — Extract Spacing System
 
-Grep CSS spacing values, Tailwind spacing overrides, space tokens. Score grid compliance against the 4/8/12/16/24/32/48/64 series. Detail: `../../reference/scan-procedure.md` §Step 4.
+Grep CSS spacing values, Tailwind spacing overrides, space tokens. Score grid compliance against the 4/8/12/16/24/32/48/64 series. Detail: `./scan-procedure.md` §Step 4.
 
 ### Step 5 — Anti-Pattern Audit
 
-Read `${CLAUDE_PLUGIN_ROOT}/reference/anti-patterns.md`. Run all BAN-XX and SLOP-XX grep commands, plus a11y checks (focus rings, reduced-motion, div onClick, small fonts). Detail: `../../reference/scan-procedure.md` §Step 5.
+Read `${CLAUDE_PLUGIN_ROOT}/reference/anti-patterns.md`. Run all BAN-XX and SLOP-XX grep commands, plus a11y checks (focus rings, reduced-motion, div onClick, small fonts). Detail: `./scan-procedure.md` §Step 5.
 
 ### Step 6 — Component Inventory
 
-If `--quick`, skip. Otherwise run the three-pass multi-signal filter (JSX-return + className + framework-import) to produce an authoritative component list, then enumerate primitives. In `--full` mode, emit one row per file. Detail: `../../reference/scan-procedure.md` §Step 6.
+If `--quick`, skip. Otherwise run the three-pass multi-signal filter (JSX-return + className + framework-import) to produce an authoritative component list, then enumerate primitives. In `--full` mode, emit one row per file. Detail: `./scan-procedure.md` §Step 6.
 
 ### Step 7 — Score All 7 Categories
 
@@ -72,21 +72,21 @@ Read `${CLAUDE_PLUGIN_ROOT}/reference/audit-scoring.md`. Score each category 0
 
 ### Step 8 — Generate Design Debt Roadmap
 
-Classify each finding P0/P1/P2/P3, estimate effort XS/S/M/L/XL, group by debt theme, compute `priority_score = (severity_weight * effort_weight) + (dependency_depth * 2)`. Mark P1+XS/S items as quick wins. Detail: `../../reference/scan-procedure.md` §Step 8.
+Classify each finding P0/P1/P2/P3, estimate effort XS/S/M/L/XL, group by debt theme, compute `priority_score = (severity_weight * effort_weight) + (dependency_depth * 2)`. Mark P1+XS/S items as quick wins. Detail: `./scan-procedure.md` §Step 8.
 
 ---
 
 ## Outputs
 
-Write both artifacts using the templates in `../../reference/scan-procedure.md`:
+Write both artifacts using the templates in `./scan-procedure.md`:
 
-- **`DESIGN.md`** (project root) — design-system snapshot with score table, color/typography/spacing/component inventories, anti-pattern status, motion summary. Frontmatter records `score`, `framework`, `css_approach`, `token_layer`, and (if Figma ran) `figma_variables_used` + `figma_source`. Template: `../../reference/scan-procedure.md` §Output 1.
-- **`.design/DESIGN-DEBT.md`** — prioritized debt roadmap grouped P0/P1/P2/P3, with priority_score ordering, recommended fix order, and pipeline recommendation. Template: `../../reference/scan-procedure.md` §Output 2.
+- **`DESIGN.md`** (project root) — design-system snapshot with score table, color/typography/spacing/component inventories, anti-pattern status, motion summary. Frontmatter records `score`, `framework`, `css_approach`, `token_layer`, and (if Figma ran) `figma_variables_used` + `figma_source`. Template: `./scan-procedure.md` §Output 1.
+- **`.design/DESIGN-DEBT.md`** — prioritized debt roadmap grouped P0/P1/P2/P3, with priority_score ordering, recommended fix order, and pipeline recommendation. Template: `./scan-procedure.md` §Output 2.
 
 ---
 
 ## After Writing
 
-Print the user-facing summary block from `../../reference/scan-procedure.md` §After Writing — project name, score, P0/P1 counts, quick-win count, artifact paths, and next-step options (start pipeline, fix quick wins first, or just reference the debt).
+Print the user-facing summary block from `./scan-procedure.md` §After Writing — project name, score, P0/P1 counts, quick-win count, artifact paths, and next-step options (start pipeline, fix quick wins first, or just reference the debt).
 
 ## SCAN COMPLETE

package/skills/start/SKILL.md

@@ -41,7 +41,7 @@ disable-model-invocation: true
 
 ## Workflow
 
-Six steps, all documented in `./reference/start-procedure.md`. Companion file `./reference/start-interview.md` holds the 5-question copy + defaults + validation.
+Six steps, all documented in `./start-procedure.md`. Companion file `./reference/start-interview.md` holds the 5-question copy + defaults + validation.
 
 | Step | What it does | Where to look |
 |------|--------------|---------------|