@hegemonart/get-design-done 1.0.7

package/skills/new-project/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: gdd-new-project
+description: "Initialize a new get-design-done project. Gathers project context, creates PROJECT.md and STATE.md, initializes first cycle. Run once per project before any pipeline stage."
+argument-hint: "[--name <project-name>]"
+tools: Read, Write, AskUserQuestion, Bash, Glob
+---
+
+# /gdd:new-project
+
+One-time project initialization. Replaces "run scan cold" by gathering context up front and producing PROJECT.md + STATE.md + cycle-1.
+
+## Steps
+
+1. **Existing check**: If `.design/STATE.md` exists, ask (AskUserQuestion): "Project already initialized. Re-initialize? (This does not delete existing work.)" Abort if declined.
+2. **Create directory**: `mkdir -p .design` via Bash.
+3. **Auto-detect from codebase** (do this before asking):
+   - Read `package.json` for framework (React/Next.js/Vue/SvelteKit/etc.).
+   - Glob for `tailwind.config.*`, `components/`, `src/`, `shadcn.json` to guess the design system.
+   - Use directory name as default project name.
+4. **Gather context** (AskUserQuestion, one at a time, pre-filled with detected values):
+   - Project name
+   - Project type (framework)
+   - Main design goal
+   - Primary user
+   - Design system / component library
+5. **Write `.design/PROJECT.md`**:
+   ```markdown
+   # Project: <name>
+   **Type**: <framework>
+   **Design system**: <system>
+   **Main goal**: <goal>
+   **Primary user**: <user>
+   **Initialized**: <date>
+   ```
+6. **Initialize STATE.md**: Copy from `reference/STATE-TEMPLATE.md`, fill in project name, set stage to `brief`, cycle to `cycle-1`.
+7. **Create `.design/config.json`** with defaults from `reference/config-schema.md`.
+8. **Initialize first cycle**: Write `.design/CYCLES.md` with a `cycle-1` entry (goal copied from PROJECT.md main goal, status `active`).
+9. **Seed project-local skills directory**: Create `./.claude/skills/` and write `./.claude/skills/README.md`:
+   ```markdown
+   # Project-Local Skills
+
+   Auto-loaded by gdd pipeline stages. See `reference/project-skills-guide.md` in the plugin.
+   Files named `design-*-conventions.md` are read by explore/plan/design.
+   Populated by `/gdd:sketch-wrap-up` and manual edits.
+   ```
+10. Print: "Project initialized. Run `/gdd:brief` to capture your design problem, or `/gdd:explore` to scan directly."
+
+## Do Not
+
+- Do not delete or overwrite existing `.design/` artifacts if re-initializing.
+- Do not run any pipeline stage automatically — this is init only.
+
+## NEW-PROJECT COMPLETE

package/skills/next/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gdd-next
+description: "Routes to the next pipeline stage based on current STATE.md position"
+tools: Read, Write
+---
+
+# Get Design Done — Next
+
+**Role:** Lightweight router. Read `.design/STATE.md` and recommend the next command.
+
+---
+
+## Logic
+
+1. Check if `.design/STATE.md` exists.
+   - **No STATE.md** → Print: "No STATE.md found. Run `/gdd:new-project` to initialize, or `@get-design-done brief` to start the pipeline."
+2. If STATE.md exists, parse frontmatter `stage:` field and map:
+
+| Current `stage:` | Recommendation |
+|---|---|
+| `brief` | Run `@get-design-done explore` to scan and interview |
+| `explore` | Run `@get-design-done plan` to create design plan |
+| `plan` | Run `@get-design-done design` to execute design tasks |
+| `design` | Run `@get-design-done verify` to audit and verify |
+| `verify` | Pipeline complete. Run `/gdd:new-cycle` for next cycle or `/gdd:ship` to create PR |
+
+3. Print the recommendation as a single formatted block:
+
+```
+━━━ Next step ━━━
+Current stage: <stage>
+Status: <status>
+→ <recommendation>
+━━━━━━━━━━━━━━━━━━
+```
+
+## Do Not
+
+- Do not modify STATE.md.
+- Do not invoke the next stage automatically — only recommend.
+
+## NEXT COMPLETE

package/skills/note/SKILL.md

@@ -0,0 +1,47 @@
+---
+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
+---
+
+# /gdd:note
+
+**Role:** Ephemeral design notes. Zero ceremony — no priority, no due date. Backing store: `.design/NOTES.md`.
+
+## File format
+
+```markdown
+# Design Notes
+
+- [2026-04-18 04:55] Consider revisiting the card border-radius after Phase 7 ships
+- [2026-04-18 05:10] [promoted → todo] Try a glassmorphism treatment for the sidebar
+```
+
+## Subcommands
+
+### add [text]
+Create `.design/NOTES.md` with header if missing. Append one line:
+```
+- [YYYY-MM-DD HH:MM] <text>
+```
+If text omitted, append a blank timestamped entry for the user to fill later:
+```
+- [YYYY-MM-DD HH:MM] 
+```
+
+### list
+Read `.design/NOTES.md`. Print each note line with its line number for use with `promote`.
+
+### promote [line-number]
+Read the note at that line. Delegate to `/gdd:todo add` by writing a new P2 entry into `.design/TODO.md` directly (format: `- [ ] [YYYY-MM-DD] <text>` under `## P2 — Normal`). Rewrite the original note line in NOTES.md with `[promoted → todo]` prefix before the text:
+```
+- [2026-04-18 05:10] [promoted → todo] <original text>
+```
+
+## Constraints
+
+- Never overwrite prior notes on `add`.
+- Preserve exact line order on `promote`.
+
+## NOTE COMPLETE

package/skills/optimize/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: optimize
+description: "Reads .design/telemetry/costs.jsonl + .design/agent-metrics.json, runs rule-based analysis, writes .design/OPTIMIZE-RECOMMENDATIONS.md. Pure advisory — no auto-apply. User reviews + decides."
+argument-hint: "[--refresh] [--min-spawns=N]"
+user-invocable: true
+tools: Read, Bash, Grep, Write
+---
+
+# /gdd:optimize — Optimization Advisor
+
+## Role
+
+You are the optimization advisor. You read the telemetry ledger (`.design/telemetry/costs.jsonl`) and the per-agent metrics aggregate (`.design/agent-metrics.json`), apply a fixed set of rule-based heuristics, and emit recommendations to `.design/OPTIMIZE-RECOMMENDATIONS.md`. You never modify agent files, budget config, or cache state. Your output is a markdown table of proposals the user reviews manually, mirroring the Phase 11 `/gdd:apply-reflections` discipline.
+
+This skill is **advisory only**. It never edits `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. The skill never makes model calls — every rule is deterministic.
+
+## Refresh Step
+
+Before analysis, invoke the aggregator to ensure metrics are current:
+
+```bash
+node scripts/aggregate-agent-metrics.js
+```
+
+This is idempotent. If `--refresh` flag is absent and `.design/agent-metrics.json` was generated within the last 60 seconds, the skill may skip this step.
+
+## Inputs
+
+- `.design/telemetry/costs.jsonl` — append-only; skill reads tail. Tolerant of malformed lines.
+- `.design/agent-metrics.json` — per-agent aggregate produced by `scripts/aggregate-agent-metrics.js`. Source of truth for `cache_hit_rate`, `lazy_skip_rate`, `total_cost_usd`, `total_spawns`.
+- `agents/*.md` — frontmatter cross-reference when checking tier override churn + typical-duration drift.
+- `.design/budget.json` — `tier_overrides` table for cross-check (optional; proceed if missing).
+
+## Optional Arguments
+
+- `--refresh` — force aggregator refresh even if metrics file is fresh.
+- `--min-spawns=N` — only emit recommendations for agents with ≥ N spawns (default: 5; raise for high-traffic projects to suppress noise).
+
+## Rules
+
+Rule-based analysis, applied in this order. Each rule inspects per-agent aggregates and emits zero or more rows to the recommendations table.
+
+   **Rule R1 — Low cache hit rate.**
+   > IF an agent has `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20`
+   > THEN emit: `"Consider batching tasks for agent {agent} — cache hit rate is {rate*100}%. Investigate cache-aligned ordering (see reference/shared-preamble.md) and whether input paths can be normalized."`
+   > PROPOSED: Batch similar tasks; confirm shared-preamble import ordering.
+
+   **Rule R2 — Expensive and rarely lazy-skipped.**
+   > IF an agent has `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10`
+   > THEN emit: `"Agent {agent} is expensive (${cost}) and rarely skipped ({rate*100}% lazy-skip). Consider adding a lazy gate heuristic at agents/{agent}-gate.md (see plan 10.1-04 pattern)."`
+   > PROPOSED: Add lazy-gate agent.
+
+   **Rule R3 — Tier override churn.**
+   > IF for multiple telemetry rows an agent's recorded `tier` differs from its frontmatter `default-tier` (e.g., frontmatter says `opus` but measured rows consistently show `haiku` from budget.json override or soft-threshold downgrade)
+   > THEN emit: `"Tier override churn detected for {agent}: frontmatter says {frontmatter-tier} but measured tier is {measured-tier} in {N} of last {M} rows. Consider updating frontmatter default-tier or removing the budget.json override."`
+   > PROPOSED: Update frontmatter default-tier OR prune budget.json tier_overrides entry.
+
+   **Rule R4 — Typical duration drift.**
+   > IF measured `typical_duration_seconds` (computed as average wall-clock duration from telemetry `ts` deltas when paired spawn/complete rows exist; fall back to frontmatter value if pairing unavailable in v1) differs from frontmatter `typical-duration-seconds` by more than 50%
+   > THEN emit: `"Typical duration for {agent} has drifted: frontmatter {old}s vs measured {new}s ({delta_pct}% drift). Update frontmatter typical-duration-seconds: {new}."`
+   > PROPOSED: Edit agents/{agent}.md frontmatter.
+
+   (Note: v1 only computes wall-clock duration if the telemetry ledger carries both spawn and complete rows with matching correlation IDs. If it doesn't — 10.1's PreToolUse-only writer doesn't — Rule R4 flags "insufficient data" for affected agents rather than emitting a false proposal. Phase 11 reflector can add a PostToolUse writer to close this gap; out of 10.1 scope.)
+
+## Output Format
+
+Write `.design/OPTIMIZE-RECOMMENDATIONS.md` with this exact structure:
+
+```markdown
+# Optimization Recommendations
+
+**Generated:** {ISO-8601 timestamp}
+**Telemetry rows analyzed:** {N}
+**Agents analyzed:** {M}
+**Min spawns threshold:** {--min-spawns value}
+
+> Advisory only. No changes have been applied. Review each proposal and apply manually via the suggested action.
+
+## Proposals
+
+| Rule | Agent | Current | Proposed | Rationale |
+|------|-------|---------|----------|-----------|
+| R1 | design-verifier | cache_hit_rate: 8% | Batch tasks; audit shared-preamble ordering | Low cache reuse; likely causing 3× cost on repeated calls |
+| R2 | design-planner | $1.23 cost, 2% lazy-skip | Add agents/design-planner-gate.md | High spend with minimal gating |
+| R3 | design-verifier | frontmatter opus / measured haiku (9/12 rows) | Update frontmatter default-tier: haiku | budget.json overrides are effectively permanent |
+
+## Summary
+
+- R1 matches: {count}
+- R2 matches: {count}
+- R3 matches: {count}
+- R4 matches: {count}
+
+## OPTIMIZE COMPLETE
+```
+
+The `## OPTIMIZE COMPLETE` marker is the completion sentinel — automated graders and downstream tools detect completion by grepping for this exact line.
+
+## No Auto-Apply
+
+This skill **never modifies** `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. It **never auto-applies** proposals. It only writes `.design/OPTIMIZE-RECOMMENDATIONS.md`. If the user wants to act on a proposal, they do so manually (or via a future Phase 12 command that cross-references these proposals).
+
+The discipline mirrors `/gdd:apply-reflections` from Phase 11: advisory output, user review, manual application.
+
+## Integration with Phase 11 Reflector
+
+The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` and `agent-metrics.json` on its own cadence. `/gdd:optimize` is the user-facing advisor; the reflector is the automation-facing one. Both output to different files (`.design/OPTIMIZE-RECOMMENDATIONS.md` vs `.design/reflections/*.md`) and never collide.
+
+## Non-Goals
+
+- Does not make model calls (rule-based, deterministic).
+- Does not modify config.
+- Does not propose changes outside the four rules — future rules added by future phases.
+- Does not learn from history — Phase 11 reflector territory.
+
+## Failure Modes
+
+- Missing `.design/telemetry/costs.jsonl` → emit a single line `"No telemetry data yet — run one or more /gdd:* commands to accumulate data, then retry."` and still write the `## OPTIMIZE COMPLETE` marker.
+- Missing `.design/agent-metrics.json` after refresh → emit `"Aggregator failed — check \`node scripts/aggregate-agent-metrics.js\` output manually."`.
+- Zero rules matched → still write the recommendations file with `"No recommendations — all agents within healthy thresholds."` and the `## OPTIMIZE COMPLETE` marker.

package/skills/pause/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: gdd-pause
+description: "Write session handoff so work can resume in a new session without re-running completed stages."
+argument-hint: "[context note]"
+tools: Read, Write, AskUserQuestion
+---
+
+# /gdd:pause
+
+Captures enough state that a killed or stopped session can resume cleanly via `/gdd:resume`.
+
+## Steps
+
+1. Read `.design/STATE.md`. Extract:
+   - Current `stage:` and `cycle:`
+   - Last activity timestamp
+   - Completed tasks in the current pipeline run
+   - Open todos (from `.design/TODO.md` if present)
+   - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
+2. If no context argument was passed, ask (AskUserQuestion): "What are you in the middle of? (optional context to capture)"
+3. Write `.design/HANDOFF.md`:
+   ```markdown
+   # Session Handoff
+   **Paused**: <ISO timestamp>
+   **Stage**: <stage>
+   **Cycle**: <cycle-N>
+   **In progress**: <task description + wave/index>
+   **Next**: <next step>
+   **Context**: <user note>
+   **Active sketch**: <path or none>
+   **Open todos**: <N items (see .design/TODO.md)>
+   **Completed this session**: <list>
+   ```
+4. Print: "Session paused. Run `/gdd:resume` to pick back up."
+
+## Do Not
+
+- Do not modify STATE.md itself — HANDOFF.md is the only write.
+- Do not abort in-progress sketches; just record them.
+
+## PAUSE COMPLETE

package/skills/plan/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: plan
+description: "Stage 3 of 5 — reads DESIGN-CONTEXT.md, spawns design-phase-researcher (optional) + design-planner + design-plan-checker, writes DESIGN-PLAN.md. Thin orchestrator."
+argument-hint: "[--auto] [--parallel]"
+user-invocable: true
+---
+
+# Get Design Done — Plan
+
+**Stage 3 of 5** in the get-design-done pipeline. Thin orchestrator. All planning intelligence lives in agents/design-planner.md.
+
+## State Integration
+
+1. Read `.design/STATE.md`.
+   - If missing: create minimal skeleton from `reference/STATE-TEMPLATE.md` with stage=plan, status=in_progress, task_progress=0/3, and log warning "STATE.md not found — created fresh. If this is a resumed session, run /get-design-done:scan first."
+   - If present and frontmatter stage==plan and `<position>` status==in_progress: RESUME — skip already-complete agent invocations (use task_progress numerator as source of truth).
+   - Otherwise: normal transition — set frontmatter stage=plan, `<position>` stage=plan, status=in_progress, task_progress=0/3.
+2. Update `<connections>` by probing MCP availability (figma, refero).
+3. Update last_checkpoint. Write STATE.md.
+
+Abort with a clear error only if the user is trying to plan without DESIGN-CONTEXT.md — that is the true prerequisite, not STATE.md.
+
+## Flag Parsing
+
+Parse $ARGUMENTS:
+- `--auto` → auto_mode=true (skip approvals, skip optional research)
+- `--parallel` → parallel_mode=true (planner fills Touches:/Parallel: fields)
+
+## Parallelism Decision (before any multi-agent spawn)
+
+- Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
+- Apply rules from `reference/parallelism-rules.md`.
+- Plan's pipeline is inherently sequential (researcher → pattern-mapper → planner → checker). Expected verdict: **serial** (rule 1).
+- Write `<parallelism_decision>` to STATE.md with the verdict and reason before spawning agents.
+
+## Probe Chromatic connection
+
+Run at stage entry, after reading STATE.md:
+
+Step C1 — CLI presence:
+  Bash: command -v chromatic 2>/dev/null || npx chromatic --version 2>/dev/null
+  → found → proceed to Step C2
+  → not found → chromatic: not_configured (skip all Chromatic steps)
+
+Step C2 — Token check:
+  Bash: test -n "${CHROMATIC_PROJECT_TOKEN}"
+  → true → chromatic: available
+  → false → chromatic: unavailable
+
+Also check: if storybook: not_configured → chromatic effectively unavailable (emit note, do not run).
+Write chromatic status to .design/STATE.md <connections>.
+
+## Chromatic Change-Risk Scoping (when chromatic: available)
+
+Before writing DESIGN-PLAN.md, if chromatic: available:
+1. Identify token/component files to be changed (from DESIGN-CONTEXT.md scope)
+2. Run: Bash: npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --trace-changed=expanded --dry-run 2>&1
+3. Parse output — count story files that depend on changed source files
+4. Pass story count to design-planner.md (see design-planner.md Chromatic Change-Risk section)
+If unavailable: design-planner proceeds without story-count annotation.
+
+## Step 1 — Optional Research (skip if auto_mode)
+
+Complexity heuristic: if DESIGN-CONTEXT.md `<domain>` spans 3+ scopes OR `<decisions>` count > 6 → spawn design-phase-researcher. Otherwise skip.
+
+If spawning:
+
+```
+Task("design-phase-researcher", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-phase-researcher agent. Identify the project type from DESIGN-CONTEXT.md
+and research relevant design patterns, pitfalls, and stack-specific conventions.
+
+Output file: .design/DESIGN-RESEARCH.md
+Target: ~100 lines, ~2 min budget.
+
+Emit `## RESEARCH COMPLETE` when done.
+""")
+```
+
+Wait for `## RESEARCH COMPLETE`. Update STATE.md task_progress 1/3.
+
+## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
+
+```
+Task("design-pattern-mapper", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+</required_reading>
+
+You are design-pattern-mapper. Grep the codebase for existing design patterns
+(color tokens, spacing scale, typography conventions, component styling) and
+write .design/DESIGN-PATTERNS.md. Classify by design concern — NOT by code
+architecture (no controllers, services, middleware vocabulary).
+
+Output file: .design/DESIGN-PATTERNS.md
+Emit `## MAPPING COMPLETE` when done.
+""")
+```
+
+Wait for `## MAPPING COMPLETE`. Update STATE.md task_progress 1/3.
+
+## Step 1.6 — Assumptions Analysis (optional, same flag as research)
+
+If assumptions analysis enabled (skip if auto_mode):
+
+```
+Task("design-assumptions-analyzer", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@.design/DESIGN-PATTERNS.md
+</required_reading>
+
+You are design-assumptions-analyzer. Surface hidden design assumptions with
+confidence levels and evidence citations.
+
+Emit `## ANALYSIS COMPLETE` when done.
+""")
+```
+
+Wait for `## ANALYSIS COMPLETE`.
+
+## Step 1.7 — Synthesize pre-plan research inputs (Plan 10.1-04, D-13/D-15)
+
+If 2+ of the pre-plan research agents ran (`design-phase-researcher` Step 1, `design-pattern-mapper` Step 1.5, `design-assumptions-analyzer` Step 1.6), invoke synthesize to merge their outputs into a single compact brief. If only one ran, skip this step.
+
+    Skill("synthesize", {
+      outputs: [
+        (if Step 1 ran)   "=== from design-phase-researcher ===\n" + <read .design/DESIGN-RESEARCH.md>,
+        (if Step 1.5 ran) "=== from design-pattern-mapper ===\n"   + <read .design/DESIGN-PATTERNS.md>,
+        (if Step 1.6 ran) "=== from design-assumptions-analyzer ===\n" + <read .design/DESIGN-ASSUMPTIONS.md>
+      ],
+      directive: "Merge into a single compact pre-plan brief. Preserve per-source section headers so the planner can trace provenance. Consolidate duplicate recommendations with source tags. Target ~150 lines.",
+      output_shape: "markdown"
+    })
+
+Wait for `## SYNTHESIS COMPLETE`. Write to `.design/DESIGN-PREPLAN-BRIEF.md` (overwrite if present). Add `@.design/DESIGN-PREPLAN-BRIEF.md` to the planner's `<required_reading>` in Step 2 — individual files remain on disk for drill-down.
+
+**Parallel synthesizer note (future):** if a future plan variant spawns N parallel phase-researchers (e.g., one per project-type family), wire synthesize the same way as `skills/map/` Step 3.5.
+
+## Step 2 — Plan
+
+```
+Task("design-planner", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-CONTEXT.md
+@reference/audit-scoring.md
+@.design/DESIGN-PATTERNS.md
+[@.design/DESIGN-RESEARCH.md — only include if research step ran]
+[@.design/DESIGN-ASSUMPTIONS.md — only include if assumptions analysis ran]
+[@.design/DESIGN-PREPLAN-BRIEF.md — include if Step 1.7 synthesize ran; planner prefers this compact brief over the individual files above]
+[@.design/sketches/*/WINNER.md — include all completed sketch winners if present]
+[@.design/spikes/*/FINDINGS.md — include all completed spike findings if present]
+[@./.claude/skills/design-*-conventions.md — include all project-local design conventions if present]
+[@~/.claude/gdd/global-skills/*.md — include all global skills if directory exists; global conventions inform but do not override project-local D-XX decisions]
+</required_reading>
+
+You are the design-planner agent. Read DESIGN-CONTEXT.md and produce .design/DESIGN-PLAN.md
+with wave-ordered tasks, acceptance criteria, and (if parallel mode) Touches:/Parallel: fields.
+
+Context:
+- Pipeline stage: plan
+- auto_mode: <true|false>
+- parallel_mode: <true|false>
+
+Output file: .design/DESIGN-PLAN.md
+Format: per agents/design-planner.md Output Format section.
+
+Emit `## PLANNING COMPLETE` when done.
+""")
+```
+
+Wait for `## PLANNING COMPLETE`. Update STATE.md task_progress 2/3.
+
+## Step 3 — Check
+
+```
+Task("design-plan-checker", """
+<required_reading>
+@.design/STATE.md
+@.design/DESIGN-PLAN.md
+@.design/DESIGN-CONTEXT.md
+</required_reading>
+
+You are the design-plan-checker agent. Validate DESIGN-PLAN.md will achieve DESIGN-CONTEXT.md
+brief goals across 5 dimensions: requirement coverage, task completeness, wave ordering,
+must-have derivation, auto mode compliance.
+
+Context:
+- auto_mode: <true|false>
+
+Output: structured result as response text (no file). Start with `## PLAN CHECK RESULT: PASS`
+or `## PLAN CHECK RESULT: ISSUES FOUND`.
+
+Emit `## PLAN CHECK COMPLETE` when done.
+""")
+```
+
+Wait for `## PLAN CHECK COMPLETE`. Update STATE.md task_progress 3/3.
+
+If `## PLAN CHECK RESULT: ISSUES FOUND` and any BLOCKER issues:
+- Present issues to user and offer: (a) revise plan now — re-spawn design-planner with issue list, (b) accept and proceed, (c) abort.
+- If auto_mode: auto-accept WARNING issues, abort on BLOCKER issues.
+
+## State Update (exit)
+
+1. Set `<position>` status=completed.
+2. Set `<timestamps>` plan_completed_at=now.
+3. Update last_checkpoint. Write STATE.md.
+
+## After Completion
+
+Print user-facing summary:
+- Plan tasks: N waves, M total tasks
+- Files: .design/DESIGN-PLAN.md (and .design/DESIGN-RESEARCH.md if research ran)
+- Next: `/get-design-done:design` to execute the plan
+
+## PLAN COMPLETE
+
+---
+
+## Exploration artifacts & project-local conventions
+
+When building the planner spawn prompt, also glob for:
+- `.design/sketches/*/WINNER.md` — winning sketch rationale (informs directional tasks)
+- `.design/spikes/*/FINDINGS.md` — spike verdicts (inform task feasibility)
+- `./.claude/skills/design-*-conventions.md` — project-local design conventions
+
+Include each matching file in `<files_to_read>` / `<required_reading>` so the planner sees them when creating tasks. Spike findings from `.design/spikes/` inform task feasibility; sketch winners inform directional choice; project-local conventions override defaults.
+
+## --research mode (removed)
+
+V2-04 deferred the `--research` flag. Rationale: complexity of an additional
+agent spawn + Context7 integration outweighs the benefit of discover-stage
+auto-detect for most projects. Use /discover's Auto Mode for research-assisted
+discovery instead.
+
+The optional research step that already exists (Step 1, triggered by complexity
+heuristic: 3+ domain scopes OR 6+ decisions) covers the core use case without
+a separate CLI flag.
+
+If --research is reintroduced in a future version, define its scope in
+ROADMAP.md V2+ and update this section.

package/skills/plant-seed/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: gdd-plant-seed
+description: "Forward-looking design idea with a trigger condition. Seeds surface automatically when trigger is met. Writes to .design/SEEDS.md."
+argument-hint: "[--trigger <condition>] [text]"
+tools: Read, Write, AskUserQuestion
+---
+
+# /gdd:plant-seed
+
+**Role:** Capture an idea that is too early to act on now but should surface when a future condition is met. Backing store: `.design/SEEDS.md`.
+
+## Step 1 — Gather inputs
+
+- `<text>`: free-text idea. If empty, ask the user: "What's the seed idea?"
+- `--trigger <condition>`: the surfacing condition. If missing, ask: "What trigger condition should surface this idea? (e.g., 'when we add dark mode', 'when the nav component is redesigned', 'at next cycle start')"
+
+## Step 2 — Append to .design/SEEDS.md
+
+Create the file with `# Design Seeds` header if missing. Append:
+
+```markdown
+## Seed: <first 60 chars of text>
+**Trigger**: <condition>
+**Planted**: YYYY-MM-DD
+**Status**: dormant
+
+<full text>
+
+---
+```
+
+## Step 3 — Surfacing contract
+
+Seeds are surfaced automatically by `/gdd:progress` and `/gdd:health`. Those commands do a keyword match of each seed's trigger text against current STATE.md + `.design/CYCLES.md` content and print any matches as `Seed ready to germinate: <text>`.
+
+This skill does NOT surface seeds itself — it only plants them.
+
+## Output
+
+```
+━━━ Seed planted ━━━
+Trigger: when we add dark mode
+Status: dormant
+━━━━━━━━━━━━━━━━━━━━
+```
+
+## PLANT-SEED COMPLETE

package/skills/pr-branch/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gdd-pr-branch
+description: "Create a clean PR branch by filtering out .design/ and .planning/ commits. Code-review-ready branch for the design implementation work."
+argument-hint: "[<base-branch>]"
+tools: Read, Write, Bash
+---
+
+# /gdd:pr-branch
+
+Produces a branch that contains only code changes (under `src/`) so reviewers are not forced to read through `.design/` planning churn.
+
+## Steps
+
+1. **Determine base**: Use the argument if provided; otherwise read the current branch's merge base with `main` via `git merge-base HEAD main`.
+2. **List commits**: `git log --oneline <base>..HEAD` via Bash.
+3. **Classify each commit**: For each SHA, run `git show --name-only <sha>` and inspect the changed paths:
+   - **code-only**: all paths under `src/` (or other code dirs, not `.design/` / `.planning/`) → include
+   - **design-only**: all paths under `.design/` or `.planning/` → skip
+   - **mixed**: both kinds → include and log a note
+4. **Get cycle name**: Read `.design/STATE.md` for the current `cycle:` ID (default `cycle-1`).
+5. **Create branch**: `git checkout -b pr/<cycle>-clean <base>`.
+6. **Cherry-pick**: For every included SHA (in original order), run `git cherry-pick <sha>`. On conflict, abort the whole operation with a clear message and reset to the pre-op branch.
+7. **Print summary**: "PR branch `pr/<cycle>-clean` created with <N> commits. `.design/` and `.planning/` commits excluded. Mixed commits flagged: <list>."
+
+## Do Not
+
+- Do not rewrite history on the original branch.
+- Do not include `.design/` or `.planning/` paths — if a mixed commit contains them, the cherry-pick carries them through, but reviewers are warned.
+- Do not push the branch automatically — let `/gdd:ship` or the user push.
+
+## PR-BRANCH COMPLETE