@hegemonart/get-design-done 1.27.7 → 1.28.5

package/skills/explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-explore
-description: "Codebase inventory + design context — runs scan patterns and design-discussant interview, produces DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md (Stage 2 of 5)"
+description: "Stage 2 of 5 — unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning."
 argument-hint: "[--skip-interview] [--skip-scan]"
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision
 ---
@@ -11,212 +11,78 @@ 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`.
+
 ---
 
 ## Stage entry
 
-All STATE.md persistence in this skill goes through `gdd-state` MCP tools — no direct edits. The skill writes to `.design/STATE.md` (connections, decisions, progress, checkpoint) via those tools, and to plain design docs (listed above) via `Write`.
-
-1. Call `mcp__gdd_state__transition_stage` with `to: "explore"`.
-   - On success: proceed to probes.
-   - On gate failure: emit blockers to the user (do not advance). Each blocker is a line in the `error.context.blockers` array; print them verbatim.
-2. Call `mcp__gdd_state__get` with no arguments — snapshot the parsed state into a local `state` variable for downstream steps.
-
-## Step 1 — Connection probe
-
-Probe connection availability (the batched write lands at the end of this step — see "Commit probe results" below):
-
-**A — Figma probe (variant-agnostic):**
-```
-ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
-Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
-  into read-capable and write-capable prefix sets.
-Empty read set → figma: not_configured
-One+ matches  → pick prefix via tiebreaker:
-                (1) both-sets > reads-only,
-                (2) `figma` > others,
-                (3) non-`figma-desktop` > desktop,
-                (4) alphabetical.
-Then call {prefix}get_metadata:
-  success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
-  error   → figma: unavailable
-```
-
-**B — Refero probe:**
-```
-ToolSearch({ query: "refero", max_results: 5 })
-Empty → refero: not_configured
-Non-empty → refero: available
-```
-
-**C — 21st.dev probe:**
-```
-ToolSearch({ query: "mcp__21st", max_results: 5 })
-Empty → 21st-dev: not_configured
-Non-empty → 21st-dev: available
-```
-
-**D — Magic Patterns probe:**
-```
-ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
-Empty → magic-patterns: not_configured
-Non-empty → magic-patterns: available
-```
-
-**E — paper.design probe:**
-```
-ToolSearch({ query: "mcp__paper", max_results: 5 })
-Empty → paper-design: not_configured
-Non-empty → call mcp__paper-design__get_selection; success → available; error → unavailable
-```
-
-**F — pencil.dev probe (file-based):**
-```bash
-find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null | head -1
-Empty → pencil-dev: not_configured
-Found → pencil-dev: available
-```
-
-## Commit probe results
-
-After all probes complete, commit results in a single call:
-
-`mcp__gdd_state__probe_connections` with `probe_results` = an array of `{ name, status }` entries — one per probed connection. Example:
-
-```json
-{
-  "probe_results": [
-    { "name": "figma", "status": "available" },
-    { "name": "refero", "status": "not_configured" },
-    { "name": "preview", "status": "unavailable" }
-  ]
-}
-```
-
-Unspecified connections keep their existing value. Do NOT issue multiple `probe_connections` calls — the tool is designed for a single batch write per stage.
-
-## Step 1.5 — 21st.dev Prior-Art Check (when 21st-dev: available)
-
-If `state.connections.21st-dev === "not_configured"` (from the snapshot captured at stage entry): skip this step entirely.
-
-When the explore stage identifies any greenfield component in scope (component name from BRIEF.md or user request that does not yet have an implementation file):
-
-1. `21st_magic_component_search(component_name, limit: 3)`
-2. Evaluate top result:
-   - **fit ≥ 80%**: add `<prior-art>` block to DESIGN.md:
-     ```xml
-     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
-       Recommendation: adopt — do not build custom. Confirm with design-executor.
-     </prior-art>
-     ```
-   - **fit < 80%**: note top candidate in DESIGN.md as a reference, proceed with custom build:
-     ```xml
-     <prior-art source="21st.dev" component="<name>" fit="<score>%" id="<component_id>">
-       Low fit — noted for reference. Building custom component.
-     </prior-art>
-     ```
-3. If `svgl_get_brand_logo` is available and explore scope includes brand logo assets: call `svgl_get_brand_logo(brand_name)` for each required brand asset; add SVG results to `.design/assets/` and note in DESIGN.md.
-
-If no greenfield components in scope: skip this step.
-
-## Step 2 — Inventory scan (unless `--skip-scan`)
-
-**Map pre-check:** If `.design/map/` exists and all 5 files (`tokens.md`, `components.md`, `visual-hierarchy.md`, `a11y.md`, `motion.md`) are present AND fresher than `src/` (mtime), consume them as the inventory source and skip the grep pass. Otherwise proceed with grep below and, after Step 4, suggest running `/gdd:map` for richer parallel-scanned data on the next cycle.
-
-**Parallelism decision (before any multi-agent spawn):**
-1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
-2. Apply rules from `reference/parallelism-rules.md` (hard → soft).
-3. Record the verdict via `mcp__gdd_state__set_status` with a short status label (e.g., `status: "explore_parallel"` or `"explore_serial"`) carrying the stage/verdict/reason/agents payload.
-4. If verdict is `parallel`, dispatch via multiple `Task()` calls in one response; if `serial`, spawn sequentially.
-
-Run the canonical scan grep/glob inventory (preserves PLAT-01/02 POSIX ERE patterns from Phase 1):
+All STATE.md persistence goes through `gdd-state` MCP tools — no direct edits. Plain design docs (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) use `Write`.
 
-- **Component detection** — `Glob` for `**/*.{tsx,jsx,vue,svelte}`; count exports, identify shared UI primitives.
-- **Color extraction** — `Grep` for hex (`#[0-9a-fA-F]{3,8}`), `rgb(`, `hsl(`, Tailwind arbitrary color classes; dedupe.
-- **Typography scan** — Grep font-family declarations, Tailwind `font-*`, `text-*` size classes; identify type scale.
-- **Motion scan** — Grep `transition`, `animate-`, `@keyframes`, `framer-motion` imports.
-- **Token detection** — Check for `tailwind.config.{js,cjs,mjs,ts}`, CSS custom properties (`--*`), design-token JSON.
-- **Layout detection** — Ordered fallback: `src/` → `app/` → `pages/` → `lib/` → unknown.
+1. `mcp__gdd_state__transition_stage` with `to: "explore"`. On gate failure: print blockers from `error.context.blockers` verbatim, do not advance.
+2. `mcp__gdd_state__get` (no args) -> snapshot `state` for downstream steps.
 
-Write findings to:
-- `.design/DESIGN.md` — current design system inventory + baseline score
-- `.design/DESIGN-DEBT.md` — prioritized debt roadmap
+---
 
-Record scan progress: call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` to reflect the scan pass.
+## Step 1 — Connection probe
 
-## Step 2.5 — Detect prior sketches and project-local conventions
+Probe six connections, then batch-write results via ONE `mcp__gdd_state__probe_connections` call (unspecified connections keep their existing value):
 
-**Sketches**: If `.design/sketches/` exists, list all sketch slugs — group by those with `WINNER.md` (completed wrap-ups) vs without (pending). Call `mcp__gdd_state__set_status` with a brief note (e.g., `status: "explore_sketches_present"`) so downstream stages see the history. Include the inventory in DESIGN.md under a "Prior Explorations" section.
+- **A — Figma** (variant-agnostic): ToolSearch + regex parse of `get_metadata` / `use_figma` prefixes -> tiebreaker selection (`both-sets > reads-only`, `figma > others`, `non-figma-desktop`, alphabetical) -> live `{prefix}get_metadata` call -> `available` / `unavailable` / `not_configured` (with `prefix=` + `writes=`).
+- **B — Refero**: ToolSearch presence sufficient.
+- **C — 21st.dev**: ToolSearch `mcp__21st` presence.
+- **D — Magic Patterns**: ToolSearch `mcp__magic_patterns` presence.
+- **E — paper.design**: ToolSearch `mcp__paper` + live `get_selection` call.
+- **F — pencil.dev**: `find . -name "*.pen"` file-presence.
 
-**Project-local skills**: Read any `./.claude/skills/design-*-conventions.md` files if present. Include their content in DESIGN-CONTEXT.md under a `<project_conventions>` section — these are codified decisions from prior `/gdd:sketch-wrap-up` runs or manual edits, and they override defaults.
+Full probe specs + commit-results JSON shape: `../../reference/explore-procedure.md` §Step 1.
 
-**Global skills**: If `~/.claude/gdd/global-skills/` exists and contains `.md` files (other than README.md), read them and prepend their content to the `<project_conventions>` section under a `<global_conventions>` sub-block. Global skills represent cross-project personal conventions. They inform but do not override project-local decisions — when a project-local D-XX decision conflicts with a global skill, the project-local decision wins.
+## Step 1.5 — 21st.dev Prior-Art Check (when `21st-dev: available`)
 
-## Step 3 — Design interview (unless `--skip-interview`)
+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.
 
-**Run this inline — do NOT spawn `design-discussant` as a subagent.** Subagent UI tools (`AskUserQuestion`) only render the native picker when called from the top-level skill context; spawning a Task() degrades the interview to plain markdown in chat (broken in Claude Desktop).
+---
 
-### 3.a — Pre-load context
+## Step 2 — Inventory scan (unless `--skip-scan`)
 
-Read in this order:
-1. `state.decisions` from the snapshot captured at stage entry — existing D-XX entries (do NOT re-ask anything covered). If the snapshot is stale, refresh by calling `mcp__gdd_state__get`.
-2. `.design/BRIEF.md` — problem statement, audience, constraints
-3. `.design/DESIGN.md` — auto-detected inventory from Step 2
-4. `.design/DESIGN-CONTEXT.md` if it exists — `<gray_areas>` block lists unresolved topics
-5. `./.claude/skills/design-*-conventions.md` if any — locked project conventions, treat as authoritative
+**Map pre-check**: if `.design/map/` exists with all 5 files (`tokens.md`, `components.md`, `visual-hierarchy.md`, `a11y.md`, `motion.md`) fresher than `src/`, consume them and skip the grep pass. Otherwise grep and, after Step 4, suggest `/gdd:map` for the next cycle.
 
-If `state.connections` shows `figma: available`, read the resolved `prefix=` from the same entry and call `{prefix}get_variable_defs`, then draft tentative D-XX entries (mark `(tentative — confirm with user)`) before asking.
+**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.
 
-### 3.b — Identify question set
+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.
 
-Build the list of areas needing input. Skip any area already answered by an existing D-XX or covered by a project convention. Default coverage:
+**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.
 
-- Cycle goal / outcome that matters most
-- Audience and primary use context
-- Brand direction (only if no tokens detected in DESIGN.md)
-- Color primitives (only if no palette detected)
-- Typography scale (only if no type system detected)
-- Spacing scale (only if no spacing tokens detected)
-- Motion preferences (only if no motion patterns detected)
-- Any `<gray_areas>` from DESIGN-CONTEXT.md
+## Step 2.5 — Detect prior sketches and project-local conventions
 
-### 3.c — Ask, one question at a time
+- **Sketches**: list `.design/sketches/*` slugs, group by `WINNER.md` present (completed) vs absent (pending). Record via `mcp__gdd_state__set_status: "explore_sketches_present"`. Include in DESIGN.md "Prior Explorations" section.
+- **Project-local skills**: read `./.claude/skills/design-*-conventions.md` -> include in DESIGN-CONTEXT.md `<project_conventions>` (these override defaults).
+- **Global skills**: `~/.claude/gdd/global-skills/*.md` (other than README) -> prepend to `<project_conventions>` under `<global_conventions>` sub-block. Project-local D-XX wins on conflict.
 
-For each area, call `AskUserQuestion` with a single focused question. Provide 4 concrete options plus "Other" / "Skip" where it helps. Do not batch questions into one call. Do not print the question as markdown — always go through the tool.
+---
 
-Reject generic answers ("modern", "clean", "professional"). If the answer is vague, ask one follow-up before recording.
+## Step 3 — Design interview (unless `--skip-interview`)
 
-### 3.d — Record after each answer
+**Run inline — NEVER spawn `design-discussant` as a subagent.** `AskUserQuestion` only renders the native picker from the top-level skill context; spawning degrades to plain markdown (broken in Claude Desktop).
 
-After each confirmed answer:
-1. Call `mcp__gdd_state__add_decision` with the decision payload. The tool assigns the next `D-NN` id and persists atomically. Format the summary as:
-   ```
-   [Category] Decision summary — short rationale
-   ```
-2. Append one JSON line to `.design/learnings/question-quality.jsonl` (create if absent):
-   ```json
-   {"ts":"<iso>","question_id":"Q-NN","question_text":"<verbatim>","answer_summary":"<one sentence>","quality":"high|medium|low|skipped","evidence":"<why>","cycle":"<active-cycle-slug>"}
-   ```
-   Quality classification: `skipped` if user picked Skip / "doesn't matter"; `low` if < 10 words and not a specific value; `medium` if hedged ("maybe", "I think", "not sure"); `high` otherwise.
-3. `add_decision` commits incrementally — the decision survives a crash mid-interview without an explicit save step.
+- **3.a Pre-load context**: state.decisions snapshot -> BRIEF.md -> DESIGN.md -> DESIGN-CONTEXT.md `<gray_areas>` -> project conventions. If `figma: available`, call `{prefix}get_variable_defs` and draft tentative D-XX entries.
+- **3.b Identify question set**: skip areas already covered by D-XX or project convention. Default coverage: cycle goal, audience, brand direction (if no tokens), color/typography/spacing primitives (if undetected), motion preferences, gray areas from DESIGN-CONTEXT.md.
+- **3.c Ask one at a time**: `AskUserQuestion` with 4 concrete options + "Other" / "Skip". Reject generic answers ("modern", "clean") with one follow-up.
+- **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`.
 
-### 3.e — Produce DESIGN-CONTEXT.md
+Full interview protocol + JSON line schema: `../../reference/explore-procedure.md` §Step 3.
 
-When all questions are answered, write `.design/DESIGN-CONTEXT.md` summarizing the locked decisions, remaining gray areas, and any Figma-sourced tentatives that were confirmed or rejected. Set frontmatter `status: complete`.
+---
 
 ## Step 4 — Close out explore
 
-- If the synthesizer (or equivalent mapper batch) ran in Step 2, call `mcp__gdd_state__update_progress` with `task_progress: "<mappers-completed>/<mappers-total>"` and `status: "explore_mappers_done"` before advancing.
-- Call `mcp__gdd_state__checkpoint` — bumps `frontmatter.last_checkpoint` + appends a timestamp entry.
-- Stage advance to `plan` happens at the next stage's entry (the plan skill will transition from its own entry step); do not edit frontmatter directly from this skill.
+- If the synthesizer / mapper batch ran in Step 2: `mcp__gdd_state__update_progress` with `task_progress: "<done>/<total>"`, `status: "explore_mappers_done"`.
+- `mcp__gdd_state__checkpoint` — bumps `last_checkpoint`.
+- Stage advance to `plan` happens at the next stage's entry (plan owns its own `transition_stage`); do not edit frontmatter directly.
 
 ## After Writing
 
-```
-━━━ Explore complete ━━━
-Saved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md
-Next: @get-design-done plan
-━━━━━━━━━━━━━━━━━━━━━━━━
-```
+Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md\nNext: @get-design-done plan".
 
 ## EXPLORE COMPLETE

package/skills/fast/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-fast
 description: "Trivial inline design task. No subagents, no planning documents, no pipeline stages. Just do the thing described."
 argument-hint: "<task description>"
 tools: Read, Write, Edit, Bash, Grep, Glob
+disable-model-invocation: true
 ---
 
 # /gdd:fast

package/skills/figma-write/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: get-design-done:figma-write
-description: Write design decisions from DESIGN-CONTEXT.md back into the active Figma file. Three modes: annotate (layer comments), tokenize (variable bindings), mappings (Code Connect). Operates in proposal→confirm mode. Pass --dry-run to preview without writing.
+description: "Write design decisions from `.design/DESIGN-CONTEXT.md` back into the active Figma file by dispatching the `design-figma-writer` agent in one of three modes (annotate / tokenize / mappings). Use when the user has completed a design pipeline cycle and wants the decisions (layer comments, variable bindings, or Code Connect mappings) reflected in Figma. Operates proposal→confirm with `--dry-run` and `--confirm-shared` flags."
 ---
 
 # get-design-done:figma-write
 
-Dispatches the `design-figma-writer` agent to write design decisions back to the open Figma file.
+Dispatches the `design-figma-writer` agent to write design decisions back to the open Figma file. The shared probe pattern (ToolSearch → live call → STATE.md write) and connection handshake are documented at `../../reference/shared-preamble.md#connection-handshake-summary` and `../../connections/figma.md`.
 
 ## Usage
 

package/skills/health/SKILL.md

@@ -2,6 +2,7 @@
 name: gdd-health
 description: "Reports .design/ artifact health — staleness, missing files, token drift, broken state transitions."
 tools: Read, Bash, Glob, Grep, mcp__gdd_state__get
+disable-model-invocation: true
 ---
 
 # /gdd:health
@@ -52,41 +53,9 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
-<step name="check-mcp-registration">
-
 ## Check MCP registration (gdd-mcp)
 
-This step inspects whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and renders a one-line status row after the health table. Dismissable via `.design/config.json#mcp_nudge=false`. This step is non-blocking: a fail-safe fallback ensures malformed config or missing harness settings MUST NOT crash the SKILL — skip silently to `unknown` status when anything goes wrong.
-
-### Dismissal check
-
-1. Read `.design/config.json` (if present). Parse JSON inside a try/catch.
-2. If `config.mcp_nudge === false`, SKIP this step entirely (render nothing).
-3. On parse failure: default to `mcp_nudge=true` (show the row) — fail-safe per threat T-27.7-04-05.
-
-### Detection
-
-1. Read `.claude/settings.local.json` (or equivalent harness settings file) and inspect its `mcpServers` object — alternatively run `claude mcp list` / `codex mcp list` if a CLI is available (see fallback below).
-2. Preferred invocation via the install-lib: call `detectMcpRegistration()` from `scripts/lib/install/mcp-register.cjs`. Returns `{harnesses: [{harness, present, registered}], summary}`.
-
-### Row rendering
-
-Based on the detection result, render exactly ONE of these row strings:
-
-- When `claude` and `codex` both present + both registered:
-  `MCP server: registered with claude+codex`
-- When only one harness is present and registered:
-  `MCP server: registered with claude` (or `MCP server: registered with codex`)
-- When at least one harness is present but `gdd-mcp` is NOT in its registered list:
-  `MCP server: not registered  (run: npx @hegemonart/get-design-done --register-mcp; dismiss: .design/config.json#mcp_nudge=false)`
-- When neither harness CLI is found on PATH:
-  `MCP server: unknown (claude/codex CLI not found)`
-
-### Fallback (if `mcp-register.cjs` not yet shipped)
-
-Skip this step silently with status `MCP server: unknown`. This step is non-blocking — failures here MUST NOT crash the SKILL.
-
-</step>
+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`.
 
 ## Update notice (safe-window surface)
 
@@ -98,6 +67,15 @@ After the health table, emit the plugin-update banner if one is present:
 
 Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
 
+## Skill-length report
+
+After the health table, surface the Phase 28.5 skill-authoring contract drift signal by running `node scripts/validate-skill-length.cjs --quiet --json` and reading `summary` from stdout. Print two prose lines:
+
+- `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.
+
 ## Do Not
 
 - Do not mutate STATE.md — this skill is read-only. Only `mcp__gdd_state__get` is permitted.

package/skills/help/SKILL.md

@@ -2,6 +2,7 @@
 name: gdd-help
 description: "Lists all available get-design-done commands with one-line descriptions"
 tools: Read
+disable-model-invocation: true
 ---
 
 # Get Design Done — Help

package/skills/list-assumptions/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-list-assumptions
 description: "Surfaces hidden design assumptions baked into the codebase before planning — pattern-based detection plus user-surfaced items."
 argument-hint: "[--area typography|color|layout|motion|a11y]"
 tools: Read, Grep, Glob
+disable-model-invocation: true
 ---
 
 # /gdd:list-assumptions

package/skills/map/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: true
 
 # Get Design Done — Map
 
-Parallel orchestrator. Spawns 5 specialist mappers, each writing one file under `.design/map/`. The explore stage consumes these when present.
+Parallel orchestrator. Spawns 5 specialist mappers, each writing one file under `.design/map/`. The explore stage consumes these when present. See `./reference/heuristics.md` §"Optimization rules" for parallel-spawn cost considerations.
 
 ## Mapper → Output
 
@@ -29,11 +29,7 @@ Parallel orchestrator. Spawns 5 specialist mappers, each writing one file under
 
 ## Step 2 — Parallelism Decision
 
-Follow `reference/parallelism-rules.md`:
-
-- All 5 mappers have `parallel-safe: auto` with disjoint `writes:` (each writes a different `.design/map/*.md` file) → no hard-rule conflict.
-- `typical-duration-seconds` sum (~210s) minus slowest (~45s) ≈ 165s savings → clears `min_estimated_savings_seconds`.
-- Verdict: **parallel**.
+Per `reference/parallelism-rules.md`: all 5 mappers have `parallel-safe: auto` with disjoint `writes:` (each writes a different `.design/map/*.md` file) — no hard-rule conflict. `typical-duration-seconds` sum (~210s) minus slowest (~45s) ≈ 165s savings → clears `min_estimated_savings_seconds`. Verdict: **parallel**.
 
 Write the verdict to STATE.md:
 
@@ -48,11 +44,11 @@ Write the verdict to STATE.md:
 </parallelism_decision>
 ```
 
-If `--only` was passed, adjust `agents` and set `verdict: serial` with `reason: "single mapper requested"`.
+`--only` → adjust `agents` and set `verdict: serial` with `reason: "single mapper requested"`.
 
 ## Step 3 — Dispatch (concurrent)
 
-Spawn all selected mappers in a single response using multiple `Task()` calls. Standard prompt shape:
+Spawn all selected mappers in a single response with multiple `Task()` calls:
 
 ```
 Task("<mapper-name>", """
@@ -68,36 +64,17 @@ output file under .design/map/. Emit your completion marker when done.
 """)
 ```
 
-Wait for every mapper's completion marker:
-- `## TOKEN MAP COMPLETE`
-- `## COMPONENT MAP COMPLETE`
-- `## VISUAL HIERARCHY MAP COMPLETE`
-- `## A11Y MAP COMPLETE`
-- `## MOTION MAP COMPLETE`
+Wait for each completion marker: `## TOKEN MAP COMPLETE`, `## COMPONENT MAP COMPLETE`, `## VISUAL HIERARCHY MAP COMPLETE`, `## A11Y MAP COMPLETE`, `## MOTION MAP COMPLETE`.
 
 ## Step 3.5 — Synthesize parallel mapper outputs (Plan 10.1-04, D-13/D-14/D-15)
 
-Each mapper has already written its own `.design/map/*.md` (disjoint writes). Main-context doesn't need all 5 verbatim — invoke the `synthesize` skill inline:
-
-    Skill("synthesize", {
-      outputs: [
-        "=== from token-mapper ===\n" + <read .design/map/tokens.md>,
-        "=== from component-taxonomy-mapper ===\n" + <read .design/map/components.md>,
-        "=== from visual-hierarchy-mapper ===\n" + <read .design/map/visual-hierarchy.md>,
-        "=== from a11y-mapper ===\n" + <read .design/map/a11y.md>,
-        "=== from motion-mapper ===\n" + <read .design/map/motion.md>
-      ],
-      directive: "Merge into a single cross-cutting DESIGN-PATTERNS.md summary preserving each mapper's top-level section header. Consolidate duplicates across mappers into single entries with source-agent names listed. Target ~120 lines.",
-      output_shape: "markdown"
-    })
-
-Wait for `## SYNTHESIS COMPLETE`. Capture the merged markdown, write to `.design/DESIGN-PATTERNS.md` (overwrite if present). This becomes the primary explore-stage input; per-mapper `.design/map/*.md` files remain on disk as drill-down evidence.
+Each mapper has written its own `.design/map/*.md` (disjoint writes). Main-context doesn't need all 5 verbatim — invoke `synthesize` inline with `outputs:[<each file's text labelled "=== from <mapper> ==="]`, `directive: "Merge into cross-cutting DESIGN-PATTERNS.md preserving section headers; consolidate cross-mapper duplicates with source-agent names; target ~120 lines."`, `output_shape:"markdown"`.
 
-If `--only <name>` was passed (single mapper), skip this step entirely.
+Wait for `## SYNTHESIS COMPLETE`. Write merged markdown to `.design/DESIGN-PATTERNS.md` (overwrite if present) — the primary explore-stage input; per-mapper files remain as drill-down evidence. `--only` (single mapper) → skip this step.
 
 ## Step 4 — Collate
 
-Write `.design/DESIGN-MAP.md` — a thin index linking to each `.design/map/*.md` with a one-paragraph summary pulled from each file's header. If Step 3.5 ran, also cross-link to the synthesized `.design/DESIGN-PATTERNS.md` and note at the top: "See DESIGN-PATTERNS.md for the merged cross-cutting summary — this index preserves per-mapper drill-down."
+Write `.design/DESIGN-MAP.md` — thin index linking to each `.design/map/*.md` with a one-paragraph summary from each file's header. If Step 3.5 ran, also cross-link to `.design/DESIGN-PATTERNS.md` and note at the top: "See DESIGN-PATTERNS.md for the merged cross-cutting summary — this index preserves per-mapper drill-down."
 
 ## Step 5 — Report
 

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.
+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).
 
 ## Steps
 
@@ -16,6 +16,7 @@ The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pip
 3. Generate cycle ID: read `.design/CYCLES.md` if present, find the max `cycle-N`, increment. If CYCLES.md is missing, start at `cycle-1`.
 4. Update `.design/STATE.md` frontmatter: set `cycle: cycle-N`.
 5. Create or append to `.design/CYCLES.md`:
+
    ```markdown
    ## cycle-N: <goal>
    **Started**: <date>
@@ -24,6 +25,7 @@ The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pip
    **Pipeline runs**: 0
    **Decisions made**: 0
    ```
+
 6. Reset the `<decisions>` section in STATE.md for the new cycle. Preserve prior decisions by prepending a comment marker `<!-- prior cycle decisions archived in CYCLES.md -->`.
 7. Print: "Cycle cycle-N started. Run `@get-design-done brief` or `@get-design-done explore` to begin."
 

package/skills/next/SKILL.md

@@ -2,6 +2,7 @@
 name: gdd-next
 description: "Routes to the next pipeline stage based on current STATE.md position"
 tools: Read, Write, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list
+disable-model-invocation: true
 ---
 
 # Get Design Done — Next

package/skills/note/SKILL.md

@@ -3,6 +3,7 @@ name: gdd-note
 description: "Zero-friction idea capture during any stage. Appends to .design/NOTES.md. Subcommands: add, list, promote."
 argument-hint: "<add|list|promote> [text|line-number]"
 tools: Read, Write
+disable-model-invocation: true
 ---
 
 # /gdd:note