@hegemonart/get-design-done 1.19.6 → 1.20.0

package/skills/design/SKILL.md

@@ -3,6 +3,7 @@ name: design
 description: "Stage 4 of 5 — reads DESIGN-PLAN.md, spawns design-executor per task with wave coordination and parallel/sequential routing. Thin orchestrator."
 argument-hint: "[--auto] [--parallel]"
 user-invocable: true
+tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint
 ---
 
 # Get Design Done — Design
@@ -11,13 +12,12 @@ user-invocable: true
 
 ---
 
-## State Integration
+## Stage entry
 
-1. Read `.design/STATE.md`.
-   - **If missing:** create minimal skeleton from `reference/STATE-TEMPLATE.md` with `stage: design`, `status: in_progress`; log warning: "STATE.md not found — creating from template. Prior stage outputs may be incomplete."
-   - **If present and `stage == design` and `status == in_progress`:** RESUME — use `task_progress` numerator as source of truth; skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
-   - **Otherwise:** normal transition — set `stage: design`, `status: in_progress`.
-2. Probe `<connections>`, update `last_checkpoint`, write STATE.md.
+1. Call `mcp__gdd_state__transition_stage` with `to: "design"`.
+   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
+   - If the transition succeeds and the prior stage was already `design` with `status: in_progress`, this is a RESUME — use `task_progress` numerator as source of truth and skip tasks that already have a corresponding `.design/tasks/task-NN.md` file.
+2. Call `mcp__gdd_state__get` → snapshot `state`; read `state.position.wave` to decide execution plan.
 
 Abort only if `.design/DESIGN-PLAN.md` is missing:
 > "No plan found. Run `/get-design-done:plan` first."
@@ -82,9 +82,22 @@ For each wave:
 1. Read `.design/config.json` `parallelism` (or defaults from `reference/config-schema.md`).
 2. Collect candidates in the wave; check `Touches:`, `writes:`, `parallel-safe`, and `typical-duration-seconds` fields.
 3. Apply rules in order from `reference/parallelism-rules.md` (hard → soft). Overlapping Touches split into sequential sub-waves.
-4. Write `<parallelism_decision>` to STATE.md per wave (stage: design, wave: N).
+4. Record the parallelism decision for this wave via `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallelism: <parallel|serial>, reason=<short-reason>"` — the status string is the canonical carrier (mirrors the plan-stage convention from Plan 20-09; a dedicated tool may be added in a follow-on plan).
 5. If `parallel`: spawn all candidates via concurrent `Task()` calls in one response. If `serial`: spawn sequentially.
 
+### Executor prompt template (applies to every spawned design-executor)
+
+Every spawned executor receives the following STATE.md contract in its prompt:
+
+> **STATE.md mutation protocol** — When you complete a task in your assigned batch, update STATE.md ONLY via the `gdd-state` MCP tools. Specifically:
+> - Report task progress: `mcp__gdd_state__update_progress` with your new `task_progress` fraction.
+> - Add blockers: `mcp__gdd_state__add_blocker` with `{ stage: "design", date: <today>, text: "..." }`.
+> - Resolve your own blockers on fix: `mcp__gdd_state__resolve_blocker` with the blocker id.
+>
+> Do NOT `Read` + `Write` `.design/STATE.md` directly — the MCP tools enforce the lockfile and emit mutation events. Direct writes corrupt parallel state.
+
+Inline this protocol block verbatim inside every design-executor prompt in both the parallel-batch and sequential-tail spawns below. Concurrent executors (Phase 10.1 parallel mode) each emit `update_progress` calls; the lockfile (Plan 20-01) and event stream (Plan 20-06) serialize them safely.
+
 ## Step 2 — Wave-by-Wave Execution
 
 For each Wave in order (Wave 1, Wave 2, ...):
@@ -151,7 +164,10 @@ Merging worktrees...
 
 Merge each worktree branch back into the working directory. Each agent touched non-overlapping files (guaranteed by the conflict check on `Touches:` fields). If an unexpected merge conflict appears, flag it and ask the user to resolve before continuing.
 
-Update STATE.md `task_progress` after merge.
+After merge, roll up the batch's progress:
+
+- Call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_parallel_batch_complete"`.
+- Call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
 
 ### Sequential tail (Parallel: false tasks, or all tasks if `parallel_mode=false`)
 
@@ -195,7 +211,9 @@ Emit `## EXECUTION COMPLETE` when done.
 """, subagent_type="design-executor")
 ```
 
-Update STATE.md `task_progress` after each task completes.
+After each task completes, call `mcp__gdd_state__update_progress` with the new `task_progress: "<completed>/<total>"` and `status: "design_wave_<N>_task_<NN>_complete"`.
+
+After the final sequential task of the wave, call `mcp__gdd_state__checkpoint` — records the wave boundary in `<timestamps>` and bumps `last_checkpoint`.
 
 ---
 
@@ -220,17 +238,17 @@ Skip checkpoint if `auto_mode=true`.
 
 After each wave, check task-NN.md files for `status: deviation`. If any found:
 
-- Present affected task IDs and their blocker descriptions (from `.design/STATE.md <blockers>`)
+- Call `mcp__gdd_state__get` → read `state.blockers`; present affected task IDs and their blocker descriptions from the returned snapshot.
 - Offer: (a) stop stage, (b) continue remaining tasks
 - In `auto_mode`: continue automatically, log all deviations
+- When a blocker is addressed (fix committed by a follow-up task), call `mcp__gdd_state__resolve_blocker` with the blocker id to clear it from the live state.
 
 ---
 
 ## State Update (exit)
 
-1. Set `<position> status: completed`, `stage: design`.
-2. Set `<timestamps> design_completed_at: [now ISO 8601]`.
-3. Write STATE.md.
+1. Call `mcp__gdd_state__set_status` with `status: "design_complete"` — marks the stage completed without transitioning; verify calls `transition_stage` on its entry, keeping the transition atomic with the owning stage.
+2. Call `mcp__gdd_state__checkpoint` — stamps `last_checkpoint` and appends a `design_completed_at` entry to `<timestamps>`.
 
 ---
 

package/skills/explore/SKILL.md

@@ -2,7 +2,7 @@
 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, AskUserQuestion
+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
@@ -13,9 +13,18 @@ tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion
 
 ---
 
+## 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 and update `.design/STATE.md` `<connections>`:
+Probe connection availability (the batched write lands at the end of this step — see "Commit probe results" below):
 
 **A — Figma probe (variant-agnostic):**
 ```
@@ -68,11 +77,27 @@ Empty → pencil-dev: not_configured
 Found → pencil-dev: available
 ```
 
-Write all results to STATE.md `<connections>`.
+## 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 `21st-dev: not_configured` in STATE.md: skip this step entirely.
+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):
 
@@ -101,7 +126,7 @@ If no greenfield components in scope: skip this step.
 **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.
+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):
@@ -117,11 +142,11 @@ 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.
+Record scan progress: call `mcp__gdd_state__update_progress` with `task_progress: "<completed>/<total>"` to reflect 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.
+**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.
 
@@ -134,13 +159,13 @@ Mark STATE.md `task_progress` for the scan pass.
 ### 3.a — Pre-load context
 
 Read in this order:
-1. `.design/STATE.md` — existing `<decisions>` D-XX entries (do NOT re-ask anything covered)
+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 `<connections>` in STATE.md shows `figma: available`, read the resolved `prefix=` from the same line and call `{prefix}get_variable_defs`, then draft tentative D-XX entries (mark `(tentative — confirm with user)`) before asking.
+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
 
@@ -164,27 +189,26 @@ Reject generic answers ("modern", "clean", "professional"). If the answer is vag
 ### 3.d — Record after each answer
 
 After each confirmed answer:
-1. Append a `D-XX` entry to `.design/STATE.md` `<decisions>` block. Format:
+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:
    ```
-   D-NN: [Category] Decision summary — short rationale
+   [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. Save STATE.md immediately (incremental save — survives crash mid-interview).
+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 — Update STATE.md
+## Step 4 — Close out explore
 
-- Set frontmatter `stage: plan`.
-- Set `<position>` `status: completed` for explore.
-- Set `<timestamps>` `explore_completed_at` = now.
-- Update `last_checkpoint`. Write STATE.md.
+- 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
 

package/skills/health/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gdd-health
 description: "Reports .design/ artifact health — staleness, missing files, token drift, broken state transitions."
-tools: Read, Bash, Glob, Grep
+tools: Read, Bash, Glob, Grep, mcp__gdd_state__get
 ---
 
 # /gdd:health
@@ -11,7 +11,7 @@ tools: Read, Bash, Glob, Grep
 ## Checks
 
 1. **Artifact inventory** — `ls -la .design/*.md` with size and mtime. Print a table.
-2. **Missing expected artifacts** — by `stage:` in STATE.md:
+2. **Missing expected artifacts** — by `stage` field from the `mcp__gdd_state__get` snapshot:
    - `brief` expects BRIEF.md
    - `explore` expects DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md
    - `plan` expects DESIGN-PLAN.md
@@ -20,9 +20,16 @@ tools: Read, Bash, Glob, Grep
    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.
+5. **Broken state transitions** — `stage` field from the snapshot 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>".
+7. **Seed germination** — scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content. List as "Seed ready: <text>".
+
+## State snapshot
+
+Call `mcp__gdd_state__get` once at the start to pull the snapshot used by checks 2, 5, and 7. Aggregate health math stays prose-level:
+- Count available connections from `<connections>`.
+- Count open blockers from `<blockers>` where `resolved` is absent.
+- Count pending must-haves from `<must_haves>` where `status: "pending"`.
 
 ## Output
 
@@ -55,4 +62,8 @@ 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.
 
+## Do Not
+
+- Do not mutate STATE.md — this skill is read-only. Only `mcp__gdd_state__get` is permitted.
+
 ## HEALTH COMPLETE

package/skills/optimize/SKILL.md

@@ -19,7 +19,7 @@ This skill is **advisory only**. It never edits `agents/*.md`, `.design/budget.j
 Before analysis, invoke the aggregator to ensure metrics are current:
 
 ```bash
-node scripts/aggregate-agent-metrics.js
+node --experimental-strip-types scripts/aggregate-agent-metrics.ts
 ```
 
 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.
@@ -27,7 +27,7 @@ This is idempotent. If `--refresh` flag is absent and `.design/agent-metrics.jso
 ## 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`.
+- `.design/agent-metrics.json` — per-agent aggregate produced by `scripts/aggregate-agent-metrics.ts`. 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).
 
@@ -116,5 +116,5 @@ The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` a
 ## 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."`.
+- Missing `.design/agent-metrics.json` after refresh → emit `"Aggregator failed — check \`node --experimental-strip-types scripts/aggregate-agent-metrics.ts\` 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

@@ -2,7 +2,7 @@
 name: gdd-pause
 description: "Write a numbered checkpoint so work can resume in a new session without re-running completed stages."
 argument-hint: "[context note]"
-tools: Read, Write, Bash, AskUserQuestion
+tools: Read, Write, Bash, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint
 ---
 
 @reference/retrieval-contract.md
@@ -16,11 +16,11 @@ Each invocation writes an **immutable numbered checkpoint** — it does not over
 
 ## Steps
 
-1. **Read `.design/STATE.md`**. Extract:
-   - `stage:` and `cycle:`
-   - Last activity timestamp
-   - Completed tasks in the current pipeline run
-   - Open todos (scan `.design/TODO.md` if present)
+1. `mcp__gdd_state__get` → snapshot current pipeline state. Extract:
+   - Current `stage` and `cycle`
+   - `last_checkpoint` timestamp
+   - `task_progress` and `status` for the current run
+   - Open todos (from `.design/TODO.md` if present — this file is outside the MCP catalog, so `Read` is still used)
    - Active sketch/spike directories (scan `.design/sketches/` and `.design/spikes/` for in-progress markers)
 
 2. **Determine checkpoint number**: run
@@ -32,7 +32,12 @@ Each invocation writes an **immutable numbered checkpoint** — it does not over
 3. **Collect context**: if no context argument was passed, ask (AskUserQuestion):
    "What are you in the middle of? (optional context to capture)"
 
-4. **Write numbered checkpoint**: create `.design/checkpoints/` with `mkdir -p`, then write:
+4. **Flip status via MCP** so `/gdd:resume` can detect the pause and recover the prior status:
+   1. `mcp__gdd_state__set_status` with `status: "paused:<prior-status>"` — the `paused:` prefix preserves the prior status for resume parsing.
+   2. If the user supplied a context/blocker message: `mcp__gdd_state__add_blocker` with `{ stage: <current>, date: <today>, text: <message> }`.
+   3. `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` via MCP.
+
+5. **Write numbered checkpoint**: create `.design/checkpoints/` with `mkdir -p`, then write:
    ```
    .design/checkpoints/NN-<stage>-<ISO-date>.md
    ```
@@ -52,19 +57,20 @@ Each invocation writes an **immutable numbered checkpoint** — it does not over
    **Completed this session**: <list>
    ```
 
-5. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
+6. **Update HANDOFF.md pointer**: write `.design/HANDOFF.md` with:
    ```markdown
    # Session Handoff (pointer)
    Latest checkpoint: `.design/checkpoints/NN-<stage>-<ISO-date>.md`
    Run `/gdd:resume` to restore, or `/gdd:resume N` for a specific checkpoint.
    ```
 
-6. Print: "Checkpoint NN saved. Run `/gdd:resume` or `/gdd:continue` to pick back up."
+7. Print: "Checkpoint NN saved. Run `/gdd:resume` or `/gdd:continue` to pick back up."
 
 ## Do Not
 
-- Do not modify STATE.md — checkpoints are the only write.
+- Do not mutate STATE.md directly — all STATE.md writes go through the `gdd-state` MCP tools above. Checkpoint files + HANDOFF.md are sibling artifacts, written with `Write`.
 - Do not abort in-progress sketches; just record them.
 - Do not delete previous checkpoint files.
+- Do not call `mcp__gdd_state__transition_stage` — pause is status-only, never a stage transition.
 
 ## PAUSE COMPLETE

package/skills/plan/SKILL.md

@@ -3,20 +3,18 @@ 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
+tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint
 ---
 
 # 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
+## Stage entry
 
-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.
+1. `mcp__gdd_state__transition_stage` with `to: "plan"`.
+   - Gate failure surfaces `error.context.blockers` to the user; do not advance.
+2. `mcp__gdd_state__get` → snapshot `state`. Use this snapshot for `<position>`, `<connections>`, `<must_haves>`, `<blockers>`, `<decisions>` in the current stage; do not re-read STATE.md directly.
 
 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.
 
@@ -31,7 +29,11 @@ Parse $ARGUMENTS:
 - 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.
+
+<!-- Parallelism decision is currently carried as the status string of an update_progress call. A dedicated tool may be added in a follow-on plan; until then, the status string is the canonical carrier. -->
+
+After the parallelism decision is made:
+- Call `mcp__gdd_state__update_progress` with `task_progress: "<current>/<total>"` and `status: "plan_parallelism_decided: batch_size=<N>, reason=<short-reason>"`.
 
 ## Probe Chromatic connection
 
@@ -48,7 +50,8 @@ Step C2 — Token check:
   → 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>.
+
+Write chromatic status to STATE.md `<connections>` via `mcp__gdd_state__probe_connections` — pass the single-entry probe result (`[{ name: "chromatic", status: "<verdict>" }]`). Do not edit `<connections>` directly.
 
 ## Chromatic Change-Risk Scoping (when chromatic: available)
 
@@ -82,7 +85,7 @@ Emit `## RESEARCH COMPLETE` when done.
 """)
 ```
 
-Wait for `## RESEARCH COMPLETE`. Update STATE.md task_progress 1/3.
+Wait for `## RESEARCH COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
 
 ## Step 1.5 — Pattern Mapping (mandatory, brownfield protection)
 
@@ -104,7 +107,7 @@ Emit `## MAPPING COMPLETE` when done.
 """)
 ```
 
-Wait for `## MAPPING COMPLETE`. Update STATE.md task_progress 1/3.
+Wait for `## MAPPING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "1/3"` and a short `status` summary.
 
 ## Step 1.6 — Assumptions Analysis (optional, same flag as research)
 
@@ -145,6 +148,18 @@ Wait for `## SYNTHESIS COMPLETE`. Write to `.design/DESIGN-PREPLAN-BRIEF.md` (ov
 
 **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.
 
+## Research-synthesis persistence (decisions + must-haves)
+
+When the synthesizer (design-phase-researcher / design-pattern-mapper / design-assumptions-analyzer) produces D-XX decisions and M-XX must-haves, persist each one through MCP instead of editing STATE.md directly.
+
+For each D-XX decision the synthesizer produces:
+- Call `mcp__gdd_state__add_decision` with `{ id: "D-XX", text: "...", status: "locked"|"tentative" }`.
+
+For each M-XX must-have the synthesizer produces:
+- Call `mcp__gdd_state__add_must_have` with `{ id: "M-XX", text: "...", status: "pending" }`.
+
+Issue these sequentially. Each call is event-emitting and lockfile-safe. Parallel issuance would serialize on the STATE.md lockfile with no throughput gain.
+
 ## Step 2 — Plan
 
 ```
@@ -178,7 +193,7 @@ Emit `## PLANNING COMPLETE` when done.
 """)
 ```
 
-Wait for `## PLANNING COMPLETE`. Update STATE.md task_progress 2/3.
+Wait for `## PLANNING COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "2/3"` and a short `status` summary.
 
 ## Step 3 — Check
 
@@ -204,17 +219,18 @@ Emit `## PLAN CHECK COMPLETE` when done.
 """)
 ```
 
-Wait for `## PLAN CHECK COMPLETE`. Update STATE.md task_progress 3/3.
+Wait for `## PLAN CHECK COMPLETE`. Call `mcp__gdd_state__update_progress` with `task_progress: "3/3"` and a short `status` summary.
 
 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)
+## Stage exit
+
+1. Call `mcp__gdd_state__set_status` with `status: "plan_complete"`.
+2. Call `mcp__gdd_state__checkpoint` to stamp `last_checkpoint` and finalize the plan stage.
 
-1. Set `<position>` status=completed.
-2. Set `<timestamps>` plan_completed_at=now.
-3. Update last_checkpoint. Write STATE.md.
+The next stage (design) calls `mcp__gdd_state__transition_stage` on entry — this skill does NOT issue the transition itself, preserving the stage-owned-transition discipline established by brief→explore and explore→plan.
 
 ## After Completion
 

package/skills/progress/SKILL.md

@@ -2,7 +2,7 @@
 name: gdd-progress
 description: "Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit."
 argument-hint: "[--forensic]"
-tools: Read, Bash, Grep, Glob
+tools: Read, Bash, Grep, Glob, mcp__gdd_state__get
 ---
 
 @reference/retrieval-contract.md
@@ -13,12 +13,12 @@ tools: Read, Bash, Grep, Glob
 
 ## Step 1 — Read state
 
-Read `.design/STATE.md`. Extract:
-- `stage:`, `cycle:`, `last_checkpoint`
-- `<position>` `task_progress`, `status`
-- D-XX count, open todos from `.design/TODO.md` (count unchecked `- [ ]`)
+Call `mcp__gdd_state__get` → parsed state object. Extract:
+- `stage`, `cycle`, `last_checkpoint`
+- `task_progress`, `status` (from `<position>`)
+- `decisions.length`, open todos from `.design/TODO.md` (count unchecked `- [ ]` — this file is outside the MCP catalog, so `Read` is still used)
 
-If STATE.md does not exist, print: "No pipeline state. Run `/gdd:brief` first." and stop.
+If `mcp__gdd_state__get` returns a "STATE.md missing" error, print: "No pipeline state. Run `/gdd:brief` first." and stop.
 
 ## Step 2 — Default output
 
@@ -35,7 +35,7 @@ Recommend next stage via the same logic as `/gdd:next` (route by which artifacts
 
 ### First-run connection nudge
 
-After the pipeline state block, check STATE.md `<connections>`. If every entry is `not_configured` AND `.design/config.json > connections_onboarding` is absent (user has never run the wizard), append once:
+After the pipeline state block, check the `<connections>` field from the `mcp__gdd_state__get` snapshot. If every entry is `not_configured` AND `.design/config.json > connections_onboarding` is absent (user has never run the wizard), append once:
 
 ```
 Tip: run /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).
@@ -48,13 +48,13 @@ Suppress the nudge on subsequent invocations in the same session (track via a tr
 Run these six checks and print PASS/WARN/FAIL per check:
 
 1. **Stale artifacts** — compare mtime of `.design/DESIGN.md` against most recent file under `src/` via `ls -lt`. WARN if DESIGN.md is older by >7 days.
-2. **Missing transitions** — STATE.md `stage:` vs artifacts present. e.g. stage=`plan` requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
+2. **Missing transitions** — `stage` from the `mcp__gdd_state__get` snapshot vs artifacts present. e.g. stage=`plan` requires DESIGN-CONTEXT.md. FAIL if expected artifact missing.
 3. **Token drift** — `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; tokens ≈ bytes/4. WARN if combined >50000 tokens.
 4. **Aged DESIGN-DEBT** — read `.design/DESIGN-DEBT.md`; any item whose line predates HEAD by >14 days (check `git blame` or file mtime fallback) → WARN.
-5. **Cycle alignment** — if `cycle:` is set but `.design/CYCLES.md` has no matching heading → FAIL.
-6. **Connection status** — re-probe figma/refero via ToolSearch; compare to STATE.md `<connections>`. WARN on mismatch.
+5. **Cycle alignment** — if `cycle` from the snapshot is set but `.design/CYCLES.md` has no matching heading → FAIL.
+6. **Connection status** — re-probe figma/refero via ToolSearch; compare to the `<connections>` field in the snapshot. WARN on mismatch.
 
-Also scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match STATE.md or CYCLES.md content; list them as "Seed ready to germinate: <text>".
+Also scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content; list them as "Seed ready to germinate: <text>".
 
 Print:
 ```
@@ -79,4 +79,8 @@ After printing the pipeline state, emit the plugin-update banner if one is prese
 
 No-op when: no new release exists, state-machine guard is active (stage in plan|design|verify), or the latest tag has been dismissed via `/gdd:check-update --dismiss`.
 
+## Do Not
+
+- Do not mutate STATE.md — this skill is read-only. Only `mcp__gdd_state__get` is permitted.
+
 ## PROGRESS COMPLETE

package/skills/resume/SKILL.md

@@ -2,7 +2,7 @@
 name: gdd-resume
 description: "Restore session context from a numbered checkpoint. Lists available checkpoints when no argument given."
 argument-hint: "[<N>]"
-tools: Read, Write, Bash, Glob, AskUserQuestion
+tools: Read, Write, Bash, Glob, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__set_status, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint
 ---
 
 @reference/retrieval-contract.md
@@ -29,7 +29,15 @@ Inverse of `/gdd:pause`. Reads a checkpoint file, prints a clear "you were here"
 
 3. **Read checkpoint**: load `.design/checkpoints/NN-*.md`. If not found, try `.design/HANDOFF.md` as legacy fallback.
 
-4. **Print summary** in this exact shape:
+4. **Check paused status via MCP**: call `mcp__gdd_state__get` and inspect `status`. If it does **not** start with `paused:`, print "No pause to resume" and exit — the prior session was not paused via `/gdd:pause`, so there is nothing to restore.
+
+5. **Restore prior status via MCP**: parse the prior status from the `paused:<prior>` prefix. Call `mcp__gdd_state__set_status` with `status: <prior>` to restore the pre-pause state.
+
+6. **Clear the pause blocker**: optionally call `mcp__gdd_state__resolve_blocker` to clear the pause-related blocker (match by text containing "paused"). Skip if no such blocker exists.
+
+7. **Stamp last_checkpoint via MCP**: call `mcp__gdd_state__checkpoint`.
+
+8. **Print summary** in this exact shape:
    ```
    Checkpoint NN restored.
    Saved: <timestamp>
@@ -39,20 +47,21 @@ Inverse of `/gdd:pause`. Reads a checkpoint file, prints a clear "you were here"
    Open todos: <N>
    ```
 
-5. **Staleness check**: compare mtime of `.design/` artifacts vs `src/` via Bash `stat` when available. If `src/` has commits newer than the checkpoint timestamp, warn:
+9. **Staleness check**: compare mtime of `.design/` artifacts vs `src/` via Bash `stat` when available. If `src/` has commits newer than the checkpoint timestamp, warn:
    "Source has changed since checkpoint NN — consider re-running explore or verify."
 
-6. **Route recommendation** based on checkpoint `Stage:` field:
-   - `brief` → "Run `/gdd:brief`"
-   - `explore` → "Run `/gdd:explore`"
-   - `plan` → "Run `/gdd:plan`"
-   - `design` → "Run `/gdd:design` to continue"
-   - `verify` → "Run `/gdd:verify`"
+10. **Route recommendation** based on checkpoint `Stage:` field:
+    - `brief` → "Run `/gdd:brief`"
+    - `explore` → "Run `/gdd:explore`"
+    - `plan` → "Run `/gdd:plan`"
+    - `design` → "Run `/gdd:design` to continue"
+    - `verify` → "Run `/gdd:verify`"
 
 ## Do Not
 
 - Do not delete checkpoint files.
-- Do not modify STATE.md.
+- Do not mutate STATE.md directly — all STATE.md writes go through the `gdd-state` MCP tools above.
 - Do not auto-execute the next command — just recommend.
+- Do not call `mcp__gdd_state__transition_stage` — resume restores prior status without moving the pipeline.
 
 ## RESUME COMPLETE