@hegemonart/get-design-done 1.0.7

package/skills/explore/SKILL.md

@@ -0,0 +1,109 @@
+---
+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)"
+argument-hint: "[--skip-interview] [--skip-scan]"
+tools: Read, Write, Bash, Grep, Glob, Task
+---
+
+# 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`.
+
+---
+
+## Step 1 — Connection probe
+
+Probe connection availability and update `.design/STATE.md` `<connections>`:
+
+**A — Figma probe:**
+```
+ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+Empty → figma: not_configured
+Non-empty → call mcp__figma-desktop__get_metadata; success → available; error → unavailable
+```
+
+**B — Refero probe:**
+```
+ToolSearch({ query: "refero", max_results: 5 })
+Empty → refero: not_configured
+Non-empty → refero: available
+```
+
+Write results to STATE.md `<connections>`.
+
+## 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. Write verdict to STATE.md `<parallelism_decision>` with stage/verdict/reason/agents.
+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
+
+Mark STATE.md `task_progress` for the scan pass.
+
+## 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). Note in STATE.md that sketches are present. Include the inventory in DESIGN.md under a "Prior Explorations" section so downstream stages see the history.
+
+**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`)
+
+Spawn the `design-discussant` agent:
+
+```
+Task("design-discussant", """
+<required_reading>
+@.design/STATE.md
+@.design/BRIEF.md
+@.design/DESIGN.md
+@./.claude/skills
+</required_reading>
+
+<mode>normal</mode>
+
+Run an adaptive interview for areas not already covered by D-XX decisions.
+Append D-XX decisions to STATE.md <decisions>. Produce/update .design/DESIGN-CONTEXT.md.
+
+Emit `## DISCUSS COMPLETE` when done.
+""")
+```
+
+Wait for `## DISCUSS COMPLETE`.
+
+## Step 4 — Update STATE.md
+
+- Set frontmatter `stage: plan`.
+- Set `<position>` `status: completed` for explore.
+- Set `<timestamps>` `explore_completed_at` = now.
+- Update `last_checkpoint`. Write STATE.md.
+
+## After Writing
+
+```
+━━━ Explore complete ━━━
+Saved: .design/DESIGN.md, .design/DESIGN-DEBT.md, .design/DESIGN-CONTEXT.md
+Next: @get-design-done plan
+━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## EXPLORE COMPLETE

package/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

package/skills/fast/SKILL.md

@@ -0,0 +1,44 @@
+---
+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
+---
+
+# /gdd:fast
+
+The leanest possible execution path. No subagents, no STATE.md update, no DESIGN-*.md artifacts. Read the target file, apply the change inline, commit.
+
+## When to use
+
+- "Change this button's border-radius to 8px"
+- "Add a hover state to the nav links"
+- "Fix the mobile breakpoint on the hero"
+- Single-file or single-component obvious changes
+
+## When NOT to use
+
+- Multi-component changes.
+- Anything touching tokens used across the app.
+- Anything requiring a design decision (taste, tradeoff, scope).
+- Use `/gdd:quick` or the full pipeline instead.
+
+## Steps
+
+1. Parse the task description from the argument.
+2. Use Grep/Glob to locate the target file(s). If ambiguous (>2 candidates), stop and ask the user which to edit — do not guess.
+3. Read the target file(s).
+4. Apply the described change with Edit.
+5. Run a relevant sanity check (grep for the old value to confirm it's gone; grep for the new value to confirm it's in).
+6. Commit with message: `fix: <task description>` (one commit, one change).
+7. Print: "Done: <summary of what changed>."
+
+## Do Not
+
+- No subagent spawns.
+- No `.design/` writes.
+- No STATE.md mutation.
+- No pipeline stage invocation.
+- Do not proceed if the change turns out to be non-trivial — bail out and recommend `/gdd:quick` or the full pipeline.
+
+## FAST COMPLETE

package/skills/figma-write/SKILL.md

@@ -0,0 +1,40 @@
+---
+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.
+---
+
+# get-design-done:figma-write
+
+Dispatches the `design-figma-writer` agent to write design decisions back to the open Figma file.
+
+## Usage
+
+```
+/get-design-done figma-write <mode> [--dry-run] [--confirm-shared]
+```
+
+Modes:
+- `annotate` — add design decision comments to Figma layers
+- `tokenize` — bind hard-coded color/spacing/type values to Figma variables
+- `mappings` — write Code Connect component↔code file mappings
+
+Flags:
+- `--dry-run` — emit the proposal without executing any Figma writes
+- `--confirm-shared` — authorize writes to shared team library components
+
+## Prerequisites
+
+1. Figma desktop app running with Dev Mode enabled
+2. Remote Figma MCP registered: `claude mcp add figma --transport http https://mcp.figma.com/v1/sse`
+3. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
+4. `figma: available` in `.design/STATE.md` `<connections>` block
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+<agent>design-figma-writer</agent>
+
+Pass through all flags and arguments from the invocation to the agent.

package/skills/graphify/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: get-design-done:graphify
+description: Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation.
+---
+
+# get-design-done:graphify
+
+Thin command wrapper around the GSD graphify tools integration.
+
+## Usage
+
+```
+/get-design-done graphify build          # Build or rebuild the knowledge graph
+/get-design-done graphify query <term>   # Query graph for a node and neighbors
+/get-design-done graphify status         # Check graph age, enabled, node count
+/get-design-done graphify diff           # Show topology changes since last build
+```
+
+## Behavior
+
+1. Read `.design/STATE.md` to check `graphify` status in `<connections>`.
+2. Check `graphify.enabled` in `.planning/config.json` via:
+   ```
+   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get graphify.enabled
+   ```
+3. If not enabled, print:
+   ```
+   "Graphify is not enabled. Enable with: node gsd-tools.cjs config-set graphify.enabled true"
+   "Then run /gdd:graphify build to generate the knowledge graph."
+   ```
+   STOP.
+4. Execute the requested subcommand via GSD tools:
+   - build:  `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify build`
+   - query:  `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<term>" --budget 2000`
+   - status: `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status`
+   - diff:   `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify diff`
+5. After `build` completes, update `.design/STATE.md` `<connections>`: `graphify: available`
+
+## Required Reading
+
+- `.design/STATE.md` — for graphify status in `<connections>`
+- `.planning/config.json` — for `graphify.enabled` flag
+
+## Notes
+
+- Graphify is optional. If the binary is not installed (`pip install graphifyy`), the build subcommand will fail with an install prompt.
+- Graph covers source code (`src/`, `components/`). It does NOT index `.design/` artifacts by default.
+- Use `query` with node IDs from the graph schema: `component:<name>`, `token:color/<name>`, `decision:D-<nn>`, etc.

package/skills/health/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gdd-health
+description: "Reports .design/ artifact health — staleness, missing files, token drift, broken state transitions."
+tools: Read, Bash, Glob, Grep
+---
+
+# /gdd:health
+
+**Role:** Report the health of the `.design/` directory. Print a score and list the checks that failed.
+
+## Checks
+
+1. **Artifact inventory** — `ls -la .design/*.md` with size and mtime. Print a table.
+2. **Missing expected artifacts** — by `stage:` in STATE.md:
+   - `brief` expects BRIEF.md
+   - `explore` expects DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md
+   - `plan` expects DESIGN-PLAN.md
+   - `design` expects DESIGN-SUMMARY.md
+   - `verify` expects DESIGN-VERIFICATION.md
+   FAIL per missing.
+3. **Token drift** — `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; approx tokens = bytes/4. WARN if combined >40000.
+4. **Aged DESIGN-DEBT** — items in `.design/DESIGN-DEBT.md` not touched in >14 days (file mtime). WARN.
+5. **Broken state transitions** — STATE.md `stage:` inconsistent with artifacts present (e.g. stage=`verify` but DESIGN-SUMMARY.md missing). FAIL.
+6. **Pending sketch/spike wrap-ups** — any `.design/sketches/*` or `.design/spikes/*` directory lacking a SUMMARY.md. WARN.
+7. **Seed germination** — scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match current STATE.md / CYCLES.md content. List as "Seed ready: <text>".
+
+## Output
+
+```
+━━━ Design health ━━━
+Artifacts:
+  BRIEF.md           2.1 KB   2026-04-14
+  DESIGN.md          18.4 KB  2026-04-17
+  DESIGN-CONTEXT.md  7.2 KB   2026-04-17
+
+Checks:
+  [PASS] Missing artifacts
+  [WARN] Token drift (42,100)
+  [PASS] Aged DESIGN-DEBT
+  [PASS] State transitions
+  [PASS] Sketch/spike wrap-ups
+  [PASS] Seed germination
+
+Health: 5 / 6 checks passing.
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## HEALTH COMPLETE

package/skills/help/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: gdd-help
+description: "Lists all available get-design-done commands with one-line descriptions"
+tools: Read
+---
+
+# Get Design Done — Help
+
+**Role:** Print a formatted reference of all `/gdd:` commands, grouped by purpose.
+
+---
+
+## Output
+
+Print the following table:
+
+```
+━━━ Get Design Done — Command Reference ━━━
+
+Pipeline stages (run in order):
+  brief              Stage 1 — capture problem statement, audience, constraints → BRIEF.md
+  explore            Stage 2 — inventory scan + design context interview → DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md
+  plan               Stage 3 — decompose into executable tasks → DESIGN-PLAN.md
+  design             Stage 4 — execute tasks with wave coordination → DESIGN-SUMMARY.md
+  verify             Stage 5 — audit, verify, score → DESIGN-VERIFICATION.md
+
+Standalone analysis:
+  style [Component]  Generate component handoff doc → DESIGN-STYLE-[Name].md
+  darkmode           Audit dark mode architecture + contrast → DARKMODE-AUDIT.md
+  compare            Delta between baseline and verification → COMPARE-REPORT.md
+
+Ergonomics:
+  next               Route to the next pipeline stage based on STATE.md
+  help               This reference
+  progress           Show current pipeline state
+  health             Health check of .design/ artifacts
+  quick              Fast pass through the whole pipeline
+  fast               Aggressive speed mode
+
+Exploration:
+  discuss            Open discussion thread with design-discussant agent
+  list-assumptions   Print active D-XX decisions from STATE.md
+  sketch             Open a design sketch scratchpad
+  sketch-wrap-up     Close sketch and merge learnings
+  spike              Time-boxed exploratory spike
+  spike-wrap-up      Close spike and capture outcomes
+  map                Map the codebase structure
+  audit              Run audit-only pass
+
+Maintenance:
+  note               Record a quick note to STATE.md
+  plant-seed         Record an idea for later
+  add-backlog        Append item to backlog
+  review-backlog     Review pending backlog
+  todo               List/manage design TODOs
+  stats              Print pipeline stats
+  settings           View/edit plugin settings
+  update             Update the plugin
+  reapply-patches    Reapply any pending patches
+  debug              Enter systematic debugging mode
+  undo               Revert the last stage action
+
+Lifecycle:
+  new-project        Initialize STATE.md + .design/ directory
+  new-cycle          Start a new design cycle on an existing project
+  complete-cycle     Archive the current cycle
+  pause              Pause work and save context
+  resume             Resume paused work
+  do                 Execute a specific task
+  ship               Create PR from completed work
+  pr-branch          Create/switch PR branch
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## HELP COMPLETE

package/skills/list-assumptions/SKILL.md

@@ -0,0 +1,60 @@
+---
+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
+---
+
+# /gdd:list-assumptions
+
+**Role:** Surface implicit design assumptions that were never explicitly decided. Output a numbered list tagging each as `[EXPLICIT]` (found in STATE.md/DESIGN-CONTEXT.md decisions) or `[IMPLICIT]` (inferred from code patterns).
+
+## Step 1 — Read explicit decisions
+
+Read `.design/STATE.md` `<decisions>` and `.design/DESIGN-CONTEXT.md` (if present). Collect every D-XX as `[EXPLICIT]` entries keyed by category.
+
+## Step 2 — Scan codebase for implicit patterns
+
+If `--area <name>` is given, restrict to that area. Otherwise scan all.
+
+**Layout**
+- Grep for `@media` queries → "Is mobile-first or desktop-first assumed?"
+- Grep for `grid-template`, `flex-direction` → "Is F-pattern or Z-pattern layout assumed?"
+
+**Typography**
+- Grep for `font-family` declarations → "Does the chosen font stack assume brand acceptance?"
+- Grep for `font-size: [0-9]+px` with varying values → "Is a modular scale assumed or ad-hoc sizing?"
+
+**Color**
+- Grep for hex literals `#[0-9a-fA-F]{3,8}` → "Is the palette assumed to be fixed without a token layer?"
+
+**Motion**
+- Grep for `@keyframes`, `transition`, `animate` → "Does the brand tolerate animation?"
+- Grep for `prefers-reduced-motion` → "Is reduced-motion honored or assumed ignored?"
+
+**A11y**
+- Grep for `aria-`, `role=`, `alt=` coverage → "Is WCAG AA the target, or AAA?"
+- Grep for `outline: none`, `outline: 0` → "Are focus rings intentionally removed?"
+
+For each hit, emit `Detected assumption: [pattern] at [file:line]` and flag as `[IMPLICIT]`.
+
+## Step 3 — Output
+
+```
+━━━ Design assumptions ━━━
+
+Typography
+  01 [EXPLICIT] D-03: Font family Inter
+  02 [IMPLICIT] 18 px font-size values found — scale not explicit (src/Card.css:12, ...)
+
+Color
+  03 [IMPLICIT] 47 hex literals — no token layer (see /gdd:discuss color)
+
+...
+
+N assumptions total — M implicit.
+Next: /gdd:discuss --all to resolve implicit ones.
+━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## LIST-ASSUMPTIONS COMPLETE

package/skills/map/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: gdd-map
+description: "Dispatches 5 specialist codebase mappers in parallel. Produces .design/map/*.md files consumed by the explore stage."
+argument-hint: "[--only tokens|components|visual-hierarchy|a11y|motion]"
+tools: Read, Write, Bash, Task
+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.
+
+## Mapper → Output
+
+| Mapper | Output |
+|--------|--------|
+| `token-mapper` | `.design/map/tokens.md` |
+| `component-taxonomy-mapper` | `.design/map/components.md` |
+| `visual-hierarchy-mapper` | `.design/map/visual-hierarchy.md` |
+| `a11y-mapper` | `.design/map/a11y.md` |
+| `motion-mapper` | `.design/map/motion.md` |
+
+## Step 1 — Setup
+
+- Ensure `.design/map/` exists (create if missing).
+- Read `.design/config.json` → `parallelism` object. Use `reference/config-schema.md` defaults if absent.
+- Read `.design/STATE.md` — note `<connections>` (Figma availability for token-mapper).
+- Parse `$ARGUMENTS`. If `--only <name>`, restrict the dispatch set to one mapper.
+
+## 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**.
+
+Write the verdict to STATE.md:
+
+```xml
+<parallelism_decision>
+  stage: map
+  verdict: parallel
+  reason: "5 mappers, parallel-safe: auto, writes disjoint, est savings ~165s"
+  agents: ["token-mapper", "component-taxonomy-mapper", "visual-hierarchy-mapper", "a11y-mapper", "motion-mapper"]
+  ruled_out: []
+  timestamp: [ISO 8601 now]
+</parallelism_decision>
+```
+
+If `--only` was passed, 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:
+
+```
+Task("<mapper-name>", """
+<required_reading>
+@.design/STATE.md
+@reference/audit-scoring.md
+[@reference/accessibility.md — a11y-mapper only]
+[@reference/motion.md — motion-mapper only]
+</required_reading>
+
+You are <mapper-name>. Scan the codebase per your agent spec and write your
+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`
+
+## 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.
+
+If `--only <name>` was passed (single mapper), skip this step entirely.
+
+## 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."
+
+## Step 5 — Report
+
+```
+━━━ Map complete ━━━
+Files: .design/map/tokens.md, components.md, visual-hierarchy.md, a11y.md, motion.md
+Index: .design/DESIGN-MAP.md
+Next: /gdd:explore (consumes .design/DESIGN-PATTERNS.md on happy path; .design/map/*.md available for drill-down)
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## MAP COMPLETE

package/skills/new-cycle/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gdd-new-cycle
+description: "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs."
+argument-hint: "[<goal>]"
+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.
+
+## Steps
+
+1. Read `.design/STATE.md`. If `cycle:` field is populated and no `complete` flag, ask: "Cycle <N> is active. End it first with `/gdd:complete-cycle`?" Abort if user declines.
+2. If no goal was passed as an argument, ask (AskUserQuestion): "What is the goal for this design cycle? (e.g., 'Redesign the checkout flow', 'Improve dashboard accessibility')"
+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>
+   **Status**: active
+   **Goal**: <goal>
+   **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."
+
+## Do Not
+
+- Do not archive prior artifacts here — that's `/gdd:complete-cycle`.
+- Do not overwrite the existing CYCLES.md — append only.
+
+## NEW-CYCLE COMPLETE