@hegemonart/get-design-done 1.41.0 → 1.42.0

package/dist/claude-code/.claude/skills/discuss/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gdd-discuss
+description: "Adaptive design interview command that spawns design-discussant in normal / --all / --spec mode to gather decisions via one-question-at-a-time AskUserQuestion, writing D-XX entries to STATE.md <decisions>. Use when locking design decisions outside the main pipeline or backfilling missing context."
+argument-hint: "[topic] [--all] [--spec] [--cycle <name>]"
+tools: Read, Write, Task
+---
+
+# /gdd:discuss
+
+**Role:** You are the `/gdd:discuss` command. You spawn the `design-discussant` agent with the right mode and context.
+
+## Step 1 — Read state
+
+Read `.design/STATE.md`. Note:
+- Current `cycle:` frontmatter value
+- Highest existing `D-XX` number under `<decisions>`
+
+If `.design/STATE.md` does not exist, tell the user to run `/gdd:brief` first and stop.
+
+## Step 2 — Parse arguments
+
+Inspect `$ARGUMENTS`:
+- Free-text before flags → `<topic>`
+- `--all` → batch gray-areas mode
+- `--spec` → Socratic ambiguity scoring mode
+- `--cycle <name>` → scope decisions to that cycle
+
+## Step 3 — Spawn design-discussant
+
+```
+Task("design-discussant", """
+<required_reading>
+@.design/STATE.md
+@.design/BRIEF.md
+@.design/DESIGN-CONTEXT.md
+@./.claude/skills
+</required_reading>
+
+<mode>{normal|--all|--spec}</mode>
+<topic>{topic or omit}</topic>
+<cycle>{cycle-name or omit}</cycle>
+
+Run an adaptive design interview. Append D-XX decisions to STATE.md <decisions> block.
+Emit `## DISCUSS COMPLETE` when done.
+""")
+```
+
+Use only the modes the user actually passed. Missing flags → `<mode>normal</mode>`.
+
+## Step 4 — Inline glossary maintenance (CONTEXT.md)
+
+When a fuzzy phrase is resolved into a sharper term, or a new domain concept is named
+during the interview: write to `./CONTEXT.md` IMMEDIATELY (do NOT batch). Use the schema
+in `./../../reference/context-md-format.md` — H2 heading per term, body paragraph,
+optional `**Aliases:**` line for term-merging. Multi-context repos use `CONTEXT-MAP.md`
+plus per-area `<area>/CONTEXT.md`. CONTEXT.md is lazy-created on the first term write.
+
+## Step 5 — Session wrap: ADR-offer scan
+
+For each decision recorded this session, check ALL three criteria from
+`./../../reference/adr-format.md`: (a) **hard-to-reverse**, (b) **surprising-without-context**,
+(c) **real-tradeoff**. If ALL three hold, offer to author `docs/adr/NNNN-<slug>.md`. If
+ANY criterion fails, the decision stays in STATE.md `<decisions>`. Routine choices are
+NEVER auto-promoted.
+
+## Step 6 — Report
+
+Wait for `## DISCUSS COMPLETE`. Re-read STATE.md. Count new D-XX entries since Step 1. Print:
+
+```
+━━━ Discuss complete ━━━
+New decisions: N (D-XX through D-YY)
+Mode: normal | --all | --spec
+Cycle: <name or "default">
+━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Constraints
+
+- Do not run the interview yourself — always spawn the agent.
+- Do not touch files outside `.design/`.
+
+## Rationalizations — Thought to Reality
+
+The shortcuts an agent takes during a discuss session, and what each one costs the decision record:
+
+| Thought | Reality |
+|---------|---------|
+| "I'll ask all eight questions at once to save time." | Batched questions overwhelm the user; one-at-a-time keeps each decision clean and prevents coupled answers. |
+| "I can run the interview inline instead of spawning the discussant." | The skill's contract is to always spawn the agent — running it yourself skips the discussant's mode handling and D-XX numbering. |
+| "This answer is good enough, I'll record it as a decision without follow-up." | A vague answer ("modern", "clean") recorded as a D-XX locks in an undecided premise; reject and re-ask once. |
+| "I'll batch all the new D-XX entries into STATE.md at the end." | Decisions written atomically per answer survive an interrupted session; batching loses everything if the session drops. |
+| "The glossary term can wait until I write the summary." | CONTEXT.md is written immediately per term — a deferred glossary entry is a naming inconsistency the next cycle inherits. |
+| "Every decision this session is worth an ADR." | ADRs require all three criteria (hard-to-reverse, surprising, real-tradeoff); auto-promoting routine choices buries the genuinely load-bearing ones. |
+
+## DISCUSS COMMAND COMPLETE

package/dist/claude-code/.claude/skills/do/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gdd-do
+description: "Natural-language design task router. Parses your intent, maps to the right gdd command(s), confirms before executing."
+argument-hint: "<natural language description>"
+tools: Read, Write, AskUserQuestion
+---
+
+# /gdd:do
+
+Takes a free-form description, maps it to a `/gdd:*` command, confirms with the user, then routes.
+
+## Intent parsing table
+
+| Intent signals | Maps to |
+|---|---|
+| "explore", "scan", "what design patterns", "what components" | `/gdd:explore` |
+| "discuss", "decide", "what should we use for", "help me decide" | `/gdd:discuss` |
+| "plan", "create tasks", "what tasks do we need" | `@get-design-done plan` |
+| "design", "implement", "build", "execute" | `@get-design-done design` |
+| "verify", "check", "audit", "review" | `/gdd:audit` |
+| "sketch", "explore directions", "try designs", "variant" | `/gdd:sketch` |
+| "spike", "experiment", "feasibility", "test if" | `/gdd:spike` |
+| "fix [specific thing]" | `/gdd:fast` |
+| "pause", "stop", "save my place" | `/gdd:pause` |
+| "resume", "pick back up", "continue where I left off" | `/gdd:resume` |
+| "ship", "PR", "submit", "merge" | `/gdd:ship` |
+| "undo", "revert", "roll back" | `/gdd:undo` |
+
+## Steps
+
+1. Parse the argument text. Match it against the intent signals table. Choose the best fit.
+2. If two intents tie, ask (AskUserQuestion): "Did you mean <option A> or <option B>?"
+3. Print the routing decision in this exact shape:
+   ```
+   I'll run `/gdd:<command>` — "<one-line rationale>". Confirm? (yes/no)
+   ```
+4. On confirmation: invoke the target skill with any parameters extracted from the input (e.g., topic for `discuss`, symptom for `debug`).
+5. On rejection: ask "What did you mean instead?" and retry once, then abort gracefully.
+
+## Do Not
+
+- Do not execute the target command without confirmation.
+- Do not invent new commands — if no intent matches, say so and list the closest options.
+
+## DO COMPLETE

package/dist/claude-code/.claude/skills/explore/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: gdd-explore
+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
+---
+
+# Get Design Done — Explore
+
+**Role:** You are the Explore stage. Stage 2 of 5 in the get-design-done pipeline.
+
+**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: `./explore-procedure.md`.
+
+---
+
+## Stage entry
+
+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`.
+
+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.
+
+---
+
+## Step 1 — Connection probe
+
+Probe six connections, then batch-write results via ONE `mcp__gdd_state__probe_connections` call (unspecified connections keep their existing value):
+
+- **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.
+
+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: `./explore-procedure.md` §Step 1.5.
+
+---
+
+## Step 2 — Inventory scan (unless `--skip-scan`)
+
+**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.
+
+**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: `./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: `./explore-procedure.md` §Step 2.x.
+
+## Step 2.5 — Detect prior sketches and project-local conventions
+
+- **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.
+
+---
+
+## Step 3 — Design interview (unless `--skip-interview`)
+
+**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).
+
+- **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`.
+
+Full interview protocol + JSON line schema: `./explore-procedure.md` §Step 3.
+
+---
+
+## Step 4 — Close out explore
+
+- 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
+
+Print: "=== Explore complete ===\nSaved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md\nNext: @get-design-done plan".
+
+<HARD-GATE>
+Do NOT transition to plan (or invoke `/gdd:plan`) until BOTH `.design/DESIGN.md` AND `.design/DESIGN-CONTEXT.md` are committed AND the user has approved them. If this project uses a custom `.design` location, read the artifact paths from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations — Thought to Reality
+
+The shortcut excuses an agent reaches for during explore, and the drift each one introduces:
+
+| Thought | Reality |
+|---------|---------|
+| "I already know this codebase, I can skip the inventory scan." | An unscanned codebase hides the tokens/components you'll duplicate — the grep pass exists to stop you reinventing what's there. |
+| "The six connection probes are noise, I'll assume Figma is off." | A skipped probe means a wrong connection assumption silently breaks the design stage's tool dispatch. |
+| "`--skip-interview` is fine, the brief covered it." | The interview locks the gray areas the brief left fuzzy; skipping it ships undecided D-XX into planning. |
+| "I'll batch all the interview questions to save round-trips." | Batched questions overwhelm the user and smuggle in coupled assumptions — one-at-a-time keeps each decision clean. |
+| "DESIGN-DEBT.md is optional, the scan was clean enough." | Unrecorded debt resurfaces as an unexplained constraint three stages later with no provenance. |
+| "Prior sketches and project conventions don't apply this cycle." | Ignored conventions get overridden by defaults, producing inconsistency the audit will flag against the rest of the system. |
+
+## EXPLORE COMPLETE

package/dist/claude-code/.claude/skills/explore/explore-procedure.md

@@ -0,0 +1,267 @@
+---
+name: explore-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [explore, procedure, extracted, pipeline-stage, connection-probe, design-interview, i18n]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/explore/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/explore/SKILL.md`; this file holds the
+detail the agent reaches for when executing a specific step (six connection probes, 21st.dev
+prior-art check, inventory scan grep, design interview protocol, i18n probe, decision
+recording).
+
+# Explore Procedure
+
+Detailed procedure for the get-design-done `explore` Stage 2 orchestrator. Companion to
+`../skills/explore/SKILL.md`. Read this file when executing a specific step; the SKILL.md
+keeps the load-bearing workflow + decision tree, this file holds the deep methodology.
+
+---
+
+## 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 (DESIGN.md / DESIGN-DEBT.md / DESIGN-CONTEXT.md) 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):
+
+- **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.
+
+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 2.x — i18n readiness probe (informational)
+
+Phase 28 D-04 probe — 3-state classification, **informational only**. NO gate, NO blocking, NO required-action. Output appears as a single line in the explore report.
+
+Classification logic (matches `./reference/i18n.md` §Explore Integration Spec):
+
+```txt
+1. Read package.json (dependencies + devDependencies).
+
+2. Check against library matrix:
+     react-intl, next-intl, i18next, vue-i18n, formatjs, lingui
+   >=1 library found in deps or devDeps -> state = "framework-managed"
+                                          -> STOP, emit line, exit probe.
+
+3. Else (no library):
+     grep -RE "Intl\.(DateTimeFormat|NumberFormat|PluralRules|RelativeTimeFormat|ListFormat|Collator|Segmenter)" src/
+   >=1 match -> state = "partial"
+              -> emit line, exit probe.
+
+4. Else: state = "none"
+         -> emit line, exit probe.
+```
+
+Output line in explore report (single informational line, per D-04):
+
+```txt
+Localization readiness: framework-managed | partial | none
+```
+
+(Exactly one of the three values, single line.) A consumer downstream (a planning agent, a roadmap reviewer, the user) can act on the signal if a gap is meaningful for the project, but the probe itself never forces a step — surface signal, do not bolt on a new pillar (D-07 orthogonal-lens discipline).
+
+## Step 2.5 — Detect prior sketches and project-local conventions
+
+**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.
+
+**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.
+
+**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 3 — Design interview (unless `--skip-interview`)
+
+**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
+
+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
+
+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.
+
+### 3.b — Identify question set
+
+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:
+
+- 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
+
+### 3.c — Ask, one question at a time
+
+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.
+
+### 3.d — Record after each answer
+
+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.e — Produce DESIGN-CONTEXT.md
+
+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.
+
+## After Writing
+
+```
+=== Explore complete ===
+Saved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md
+Next: @get-design-done plan
+=========================
+```

package/dist/claude-code/.claude/skills/export/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: gdd-export
+description: "Packages a completed design cycle (.design artifacts + decisions + screenshots) into a stakeholder-shareable artifact — self-contained HTML, print-styled PDF (Paged.js-compatible), or a Notion page. Redacts secrets; --pseudonymize masks identity for external sharing; --pr posts the HTML preview as a PR comment. Use to hand a design-review packet to PMs/execs/brand who aren't in the repo."
+argument-hint: "<cycle-id> --format html|pdf|notion [--pseudonymize] [--pr]"
+user-invocable: true
+tools: Read, Write, Bash, Glob, Grep, ToolSearch, Task
+---
+
+# /gdd:export
+
+Turns a completed cycle's in-repo design output into a shareable artifact. Closes the gap that `.design/*.md` lives only in the repo — stakeholders not in code can't consume it. The format contract + source set live in `../../reference/export-formats.md`; the Notion write-path in `../../connections/notion.md`.
+
+## Steps
+
+1. **Resolve the cycle.** `<cycle-id>` (or the current cycle from `.design/STATE.md`). Read the **source set**: `EXPERIENCE.md` (Phase 19.5), `.design/DESIGN.md`, `.design/DESIGN-VERIFICATION.md`, `.design/DESIGN-AUDIT.md` (if present), the decision log, and any Preview/Chromatic screenshots.
+2. **Redact (always) + pseudonymize (opt-in).** Pass every section through `scripts/lib/redact.cjs` (secrets). If `--pseudonymize`, additionally apply `scripts/lib/pseudonymize.cjs` (git identity / paths / hostname) for external sharing. Honor `GDD_DISABLE_NOTION` for the notion format.
+3. **Assemble per `--format`:**
+   - **`html`** (default) — `node -e "require('scripts/lib/export/build-html.cjs').buildHtml({...})"` → a **self-contained** HTML (inline CSS, base64-embedded screenshots, no external refs). Write to `.design/export/<cycle>.html`.
+   - **`pdf`** — the same `buildHtml({ ..., print: true })` (Paged.js-compatible `@page` print CSS). Write `.design/export/<cycle>.print.html`; instruct the user to render it via Paged.js / headless-Chrome (GDD ships **no** PDF runtime — D-02).
+   - **`notion`** — probe the Notion MCP (`ToolSearch({query:"notion"})`); if `available`, create a page from the same source (nested toggles + image upload) per `connections/notion.md`; if `not_configured`/disabled → degrade to the `html` format + a note.
+4. **`--pr`** — hand the generated HTML preview to `agents/pr-commenter.md` (via `Task`) to post as a PR comment (degrade-to-noop if no PR / pr-commenter unavailable).
+5. **Print the artifact path** (and the Notion URL / PR comment status when applicable).
+
+## Do Not
+
+- Do not add a PDF/markdown runtime dependency (`paged`/`puppeteer`/`pdfkit`/a markdown lib) — `build-html.cjs` is pure and the PDF is render-it-yourself print HTML (D-02).
+- Do not emit an un-redacted artifact — redact is mandatory; pseudonymize is the external-sharing opt-in.
+- Do not block on Notion/PR — both degrade to a noop / the html file.
+
+## EXPORT COMPLETE

package/dist/claude-code/.claude/skills/extract-learnings/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-extract-learnings
+description: "Extracts project-specific design patterns and decisions from .design/ artifacts and writes them to .design/learnings/. Optionally proposes updates to reference/ files for user review."
+tools: Bash, Read, Write, Glob, Grep
+---
+
+# /gdd:extract-learnings
+
+**Role:** Scan `.design/` artifacts for recurring patterns, successful decisions, and validated approaches. Write structured learnings to `.design/learnings/`. Optionally propose additions to tracked `reference/` files for the user to review and approve.
+
+## When to run
+
+- After `/gdd:complete-cycle` (auto-suggested by complete-cycle skill)
+- After a major verify/audit pass surfaces new patterns
+- Manually, to checkpoint what the project has learned
+
+## Protocol
+
+### Step 1 — Gather source artifacts
+
+Collect content from available `.design/` files:
+
+```bash
+ls .design/*.md 2>/dev/null
+```
+
+Read (if present): DESIGN-CONTEXT.md, DESIGN-VERIFICATION.md, DESIGN-DEBT.md, DESIGN-SUMMARY.md, CYCLES.md
+
+### Step 2 — Invoke gdd-learnings-extractor agent
+
+Delegate extraction to the `gdd-learnings-extractor` agent, passing it the list of available files. The agent extracts structured learning entries.
+
+### Step 3 — Write learnings artifact
+
+The agent writes or appends to `.design/learnings/LEARNINGS.md`.
+
+Layout of `.design/learnings/LEARNINGS.md`:
+
+```markdown
+# Project Learnings
+
+## <Category> — <Date>
+
+### L-<NN>: <Title>
+
+**Source:** <which .design/ file and section>
+**Pattern type:** decision | anti-pattern | validated-approach | token-convention | component-convention
+**Confidence:** high | medium | low
+**Summary:** <1-2 sentences>
+**Evidence:** <quote or paraphrase from source>
+**Proposed reference update:** <yes — see proposal below | no>
+
+---
+```
+
+### Step 4 — Reference file proposal (optional)
+
+After writing LEARNINGS.md, check each learning entry with `Proposed reference update: yes`.
+
+For each such entry: generate a proposed addition to the appropriate `reference/` file (e.g., `reference/heuristics.md`, `reference/anti-patterns.md`).
+
+Print the proposal to the terminal and ask the user to review:
+
+```
+━━━ Reference update proposal ━━━
+
+Learning L-03 suggests adding to reference/anti-patterns.md:
+
+  ### Anti-pattern: Overloaded primary button
+  Using the primary button style for more than one action per screen
+  reduces clarity and violates Nielsen's heuristic #4 (consistency).
+  Evidence: DESIGN-VERIFICATION.md, cycle 3.
+
+Accept this update? [y/n/edit]
+```
+
+If user types `y`: write the addition to the reference file.
+If user types `n`: mark the learning as "proposal declined" in LEARNINGS.md.
+If user types `edit`: open the proposed text for the user to modify, then write.
+
+### Step 5 — Summary
+
+```
+━━━ Learnings extracted ━━━
+Source files scanned:    <N>
+Learnings written:       <N>
+Reference proposals:     <N>  (<M> accepted)
+Output: .design/learnings/LEARNINGS.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Required reading (conditional)
+
+@.design/intel/decisions.json (if present)
+@.design/intel/patterns.json (if present)
+@.design/learnings/LEARNINGS.md (if present)
+
+## EXTRACT-LEARNINGS COMPLETE