@hegemonart/get-design-done 1.14.4 → 1.14.5

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.14.4"
+    "version": "1.14.5"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
-      "version": "1.14.4",
+      "version": "1.14.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.14.4",
+  "version": "1.14.5",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.14.5] — 2026-04-23
+
+### Fixed — Preview MCP silently skipped in verify even when available ([#19](https://github.com/hegemonart/get-design-done/issues/19))
+
+`design-verifier` was spawned with `tools: Read, Write, Bash, Grep, Glob` only. The verify skill's orchestrator-level probe correctly classified the session as `preview: available` and wrote it to `STATE.md`, but the subagent's tool allowlist blocked every `mcp__Claude_Preview__*` call, causing Phase 4B to silently skip screenshot capture and leave all `? VISUAL` heuristic flags unresolved.
+
+**Fix:** Added six Preview MCP tools to `design-verifier`'s `tools:` frontmatter — `preview_list`, `preview_navigate`, `preview_screenshot`, `preview_eval`, `preview_snapshot`, `preview_inspect` — so Phase 4B runs in the same permission context as the probe.
+
+**Probe hardening:** The availability probe in `connections/preview.md` and `skills/verify/SKILL.md` now distinguishes three failure modes instead of collapsing them to `not_configured`/`unavailable`:
+
+| New status | Meaning |
+|---|---|
+| `not_loaded` | ToolSearch empty — MCP not registered in this session |
+| `permission_denied` | ToolSearch found the tool but the live call was rejected by the tool permission layer |
+| `unreachable` | Tool loaded but live call errored for a non-permission reason (no dev server, timeout) |
+
+The Phase 4B gate in `design-verifier` skips on all non-`available` statuses and emits a targeted message on `permission_denied` to aid diagnosis.
+
+`connections/preview.md` now documents the **execution-context requirement**: the probe and the `preview_*` calls must run in the same context; a parent-session probe does not transfer to a spawned subagent.
+
+---
+
 ## [1.14.4] — 2026-04-20
 
 ### Fixed — Figma MCP install URL was stale

package/agents/design-verifier.md

@@ -1,7 +1,7 @@
 ---
 name: design-verifier
 description: Goal-backward verification of design outcomes against .design/STATE.md must-haves, NNG heuristics, and audit rubric. Returns pass result or structured gap list. Spawned by the verify stage.
-tools: Read, Write, Bash, Grep, Glob
+tools: Read, Write, Bash, Grep, Glob, mcp__Claude_Preview__preview_list, mcp__Claude_Preview__preview_navigate, mcp__Claude_Preview__preview_screenshot, mcp__Claude_Preview__preview_eval, mcp__Claude_Preview__preview_snapshot, mcp__Claude_Preview__preview_inspect
 color: green
 model: inherit
 default-tier: haiku
@@ -267,7 +267,7 @@ Record each response. For `no` responses, capture the user's issue description v
 
 ## Phase 4B — Screenshot Evidence (when preview: available)
 
-**Gate:** Skip this entire Phase 4B block if `preview` is `not_configured` or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Phase 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Phase 5.
+**Gate:** Skip this entire Phase 4B block if `preview` is `not_loaded`, `not_configured`, `permission_denied`, `unreachable`, or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Phase 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Phase 5. When skipping due to `permission_denied`, also log: `Preview MCP tools missing from agent allowlist — contact the pipeline maintainer.`
 
 **Step 1 — ToolSearch first:**
 

package/connections/connections.md

@@ -2,6 +2,8 @@
 
 This directory contains connection specifications for external tools and MCPs that the get-design-done pipeline integrates with. Each connection has its own spec file. This file is the index.
 
+**Getting started:** run `/gdd:connections` for the interactive onboarding wizard — it probes all 12 connections, recommends setup based on your project type, and walks you through installing each one (auto-run for reversible MCP adds, copy-command for everything else). You can also run `/gdd:connections list` for a read-only status check or `/gdd:connections <name>` to jump to a single connection's setup.
+
 ---
 
 ## Active Connections

package/connections/preview.md

@@ -67,16 +67,19 @@ All tools use the `mcp__Claude_Preview__` prefix.
 
 **Preview probe sequence:**
 
+> **Execution-context requirement:** The probe and the subsequent `preview_*` calls must run in the **same execution context**. If the probe runs in the orchestrator and the calls run inside a spawned subagent, the subagent's tool allowlist may block the calls even when the probe succeeds. Run the probe where the calls will actually happen, or ensure the spawned agent's `tools:` frontmatter includes `mcp__Claude_Preview__*` tools.
+
 ```
 Step P1 — ToolSearch check:
   ToolSearch({ query: "Claude_Preview", max_results: 5 })
-  → Empty result      → preview: not_configured  (skip all Preview steps)
+  → Empty result      → preview: not_loaded  (MCP not registered in this session — skip all Preview steps)
   → Non-empty result  → proceed to Step P2
 
 Step P2 — Live tool call:
   call mcp__Claude_Preview__preview_list
-  → Success (returns array, even empty)  → preview: available
-  → Error                                → preview: unavailable
+  → Success (returns array, even empty)       → preview: available
+  → Error containing "permission" or blocked  → preview: permission_denied
+  → Any other error                           → preview: unreachable
 ```
 
 Write the result to `.design/STATE.md <connections>` immediately after probing.
@@ -142,8 +145,9 @@ preview: available
 | Value | Meaning |
 |-------|---------|
 | `available` | `preview_list` returned a successful response (array, even empty) |
-| `unavailable` | Tool is in the session but errored (no running server, tool timeout, internal error) |
-| `not_configured` | ToolSearch returned empty for `Claude_Preview` — MCP not registered in this session |
+| `permission_denied` | Tool is in the session (ToolSearch found it) but the live call was rejected by the tool permission layer — likely missing from the agent's `tools:` frontmatter |
+| `unreachable` | Tool is in the session but the live call errored for a non-permission reason (no running server, timeout, internal error) |
+| `not_loaded` | ToolSearch returned empty for `Claude_Preview` — MCP not registered in this session |
 
 **Which stages probe vs. read:**
 

package/hooks/budget-enforcer.js

@@ -288,8 +288,8 @@ async function main() {
       process.stdout.write(JSON.stringify(response));
       return;
     }
-    // 80% soft-threshold downgrade (D-03)
-    if (budget.auto_downgrade_on_cap && (phaseSpend + estCost) >= (0.80 * budget.per_task_cap_usd)) {
+    // 80% soft-threshold downgrade (D-03): task-scoped, per reference/model-tiers.md
+    if (budget.auto_downgrade_on_cap && estCost >= (0.80 * budget.per_task_cap_usd)) {
       toolInput._tier_override = 'haiku';
       toolInput._tier_downgraded = true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.14.4",
+  "version": "1.14.5",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/STATE-TEMPLATE.md

@@ -56,12 +56,21 @@ skipped_stages: ""
 </must_haves>
 
 <connections>
-<!-- Detected at scan entry; updated if connections become available mid-pipeline. -->
+<!-- Detected at scan entry or via /gdd:connections; updated if connections become available mid-pipeline. -->
 <!-- Format: <connection_name>: <available | unavailable | not_configured> -->
+<!-- Key normalization: hyphens become underscores; leading digits are spelled out (21st-dev → twenty_first). -->
 figma: not_configured
 refero: not_configured
+preview: not_configured
+storybook: not_configured
+chromatic: not_configured
+graphify: not_configured
 pinterest: not_configured
 claude_design: not_configured
+paper_design: not_configured
+pencil_dev: not_configured
+twenty_first: not_configured
+magic_patterns: not_configured
 </connections>
 
 <blockers>

package/reference/config-schema.md

@@ -81,6 +81,35 @@ When `true`, parallel agents run in dedicated git worktrees. Default: `false` (l
 
 Keyed by stage name (`brief`, `explore`, `plan`, `design`, `verify`). Any field above may be overridden per stage.
 
+### `connections.skip`
+
+Optional array of connection names the user has explicitly opted out of. `/gdd:connections` reads this list and never re-prompts for skipped connections. Users re-enable a skipped connection by invoking `/gdd:connections <name>` directly (bypasses the skip list for that run).
+
+```json
+{
+  "connections": {
+    "skip": ["pinterest", "graphify"]
+  }
+}
+```
+
+Valid names: `figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`.
+
+### `connections_onboarding` (scratch block)
+
+Transient state written by `/gdd:connections` while a setup flow is in progress. Not hand-edited. Shape:
+
+```json
+{
+  "connections_onboarding": {
+    "started_at": "<ISO 8601>",
+    "pending_verification": ["figma", "chromatic"]
+  }
+}
+```
+
+`/gdd:connections` deletes this block when `pending_verification` drains. Its presence after a session restart is the signal that a resume is required (the skill jumps straight to verification).
+
 ## How Agents Read The Profile
 
 Stages are the only code that read `.design/config.json`. When spawning an agent, the stage:

package/scripts/aggregate-agent-metrics.js

@@ -76,6 +76,10 @@ function readTelemetryRows() {
 function aggregate(rows) {
   const byAgent = new Map();
   for (const r of rows) {
+    // Blocked rows represent a spawn that was denied at the hook — the agent
+    // never actually ran, so it must not contribute to spawn counts, cost, or
+    // token totals. Skip them here (mirror of the filter in aggregateByPhase).
+    if (r.block_reason) continue;
     const agent = r.agent || 'unknown';
     if (!byAgent.has(agent)) {
       byAgent.set(agent, {
@@ -129,6 +133,11 @@ function writeAtomic(filePath, content) {
 function aggregateByPhase(rows) {
   const byPhase = {};
   for (const r of rows) {
+    // Blocked rows represent spawns that were denied by the hook — the agent
+    // never ran, so their est_cost_usd must not inflate cumulative phase spend.
+    // Counting them would make future hard-block and soft-threshold checks
+    // stricter than intended on every repeat cap hit.
+    if (r.block_reason) continue;
     const phase = r.phase || 'unknown';
     byPhase[phase] = (byPhase[phase] || 0) + Number(r.est_cost_usd || 0);
   }

package/skills/connections/SKILL.md

@@ -0,0 +1,477 @@
+---
+name: gdd-connections
+description: "Onboarding wizard for external integrations. Probes all 12 connections, recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to STATE.md <connections>. Re-runnable anytime — not tied to project init. Invoke after /gdd:new-project, or whenever you want to add, inspect, or skip a connection."
+argument-hint: "[list | <connection-name> | --auto]"
+user-invocable: true
+tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
+---
+
+# /gdd:connections
+
+Interactive onboarding for the 12 external integrations the pipeline supports. Replaces "probe silently at scan entry and hope the user noticed" with an explicit "here is what can plug in, here is how."
+
+Canonical connection specs live in `connections/*.md`. The capability matrix and probe-pattern spec live in `connections/connections.md`. This skill is the **user-facing front end** for those specs.
+
+---
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `/gdd:connections` | Interactive wizard (default). Probes all, shows summary, asks what to configure. |
+| `/gdd:connections list` | Read-only table. Probes all, writes STATE.md, no prompts, exits. |
+| `/gdd:connections <name>` | Jump straight to setup for one connection (e.g. `/gdd:connections figma`). |
+| `/gdd:connections --auto` | CI mode. Probes, writes STATE.md, no prompts, no install attempts. |
+
+---
+
+## State Integration
+
+1. Read `.design/STATE.md` — if missing, that's fine; this skill does not require a pipeline run to be in progress.
+2. Read `.design/config.json` — if missing, use defaults. If `connections_onboarding` block is present with `pending_verification`, this is a resume — see Step 6.
+3. Read `connections.skip[]` from config — never re-prompt for skipped connections (user opted out).
+4. Update `last_checkpoint` in STATE.md at skill exit if STATE.md exists.
+
+---
+
+## Step 1 — Probe all 12 connections
+
+Run every probe below in order. MCP probes call `ToolSearch` first (deferred tools fail silently without it). Write every result to `STATE.md <connections>` when done.
+
+### MCP-based probes
+
+**figma:**
+```
+ToolSearch({ query: "select:mcp__figma__get_metadata", max_results: 1 })
+→ Empty         → figma: not_configured
+→ Non-empty     → call mcp__figma__get_metadata
+                    Success → figma: available
+                    Error   → figma: unavailable
+```
+
+**refero:**
+```
+ToolSearch({ query: "refero", max_results: 5 })
+→ Empty → refero: not_configured
+→ Non-empty → refero: available
+```
+
+**preview:**
+```
+ToolSearch({ query: "Claude_Preview", max_results: 5 })
+→ Empty → preview: not_configured
+→ Non-empty → call mcp__Claude_Preview__preview_list
+              Success → preview: available
+              Error   → preview: unavailable
+```
+
+**pinterest:**
+```
+ToolSearch({ query: "mcp-pinterest", max_results: 5 })
+→ Empty → pinterest: not_configured
+→ Non-empty → pinterest: available
+```
+
+**paper-design:**
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+→ Empty → paper_design: not_configured
+→ Non-empty → paper_design: available
+```
+
+**21st-dev:**
+```
+ToolSearch({ query: "mcp__21st", max_results: 5 })
+→ Empty → twenty_first: not_configured
+→ Non-empty → twenty_first: available
+```
+
+**magic-patterns:**
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+→ Empty → magic_patterns: not_configured
+→ Non-empty → magic_patterns: available
+```
+
+### Non-MCP probes
+
+**storybook** (HTTP):
+```
+Bash: curl -sf http://localhost:6006/index.json 2>/dev/null
+  → Success → storybook: available
+  → Fail    → curl -sf http://localhost:6006/stories.json 2>/dev/null
+              Success → storybook: available
+              Fail    → storybook: not_configured
+```
+
+**chromatic** (CLI + env):
+```
+Bash: command -v chromatic >/dev/null 2>&1 || npx --yes chromatic --version 2>/dev/null
+  → Fail (non-zero) → chromatic: not_configured
+  → Success         → check env CHROMATIC_PROJECT_TOKEN
+                       Empty → chromatic: unavailable
+                       Set   → chromatic: available
+```
+
+**graphify** (CLI + file):
+```
+Bash: node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status 2>/dev/null
+  → Error or enabled:false → graphify: not_configured
+  → enabled:true → check graphify-out/graph.json exists
+                    Absent  → graphify: unavailable
+                    Present → graphify: available
+```
+
+**pencil-dev** (file probe):
+```
+Bash: find . -name "*.pen" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -1
+  → Empty       → pencil_dev: not_configured
+  → Non-empty   → pencil_dev: available
+```
+
+**claude-design** (file probe — handoff bundle):
+```
+Bash: ls .design/handoff/ 2>/dev/null || find . -maxdepth 3 \
+        \( -name "*.claude-design.html" -o -name "*.claude-design.zip" \
+           -o -name "claude-design-*.html" \) 2>/dev/null | head -1
+  → Empty     → claude_design: not_configured
+  → Non-empty → claude_design: available
+```
+
+After all 12 probes complete, merge results into STATE.md `<connections>`. Preserve the three-value schema verbatim (`available | unavailable | not_configured`). Do not add new values.
+
+---
+
+## Step 2 — Categorize and build summary
+
+For each probe result, assign to one of four buckets:
+
+### Project-hint detection
+
+Run once, cache in-memory:
+
+```bash
+# Framework / stack hints
+HAS_TAILWIND=$( ls tailwind.config.* 2>/dev/null | head -1 )
+HAS_STORYBOOK_DIR=$( test -d .storybook && echo yes )
+HAS_PEN_FILES=$( find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null | head -1 )
+HAS_REACT=$( grep -l '"react"' package.json 2>/dev/null )
+HAS_FIGMA_HINT=$( grep -r "figma\.com/file" -l . --include="*.md" 2>/dev/null | head -1 )
+```
+
+### Bucketing rules
+
+| Bucket | Criteria |
+|---|---|
+| **available** | probe returned `available` |
+| **recommended** | probe returned `not_configured` AND matches a project hint below |
+| **optional** | probe returned `not_configured` AND no project hint match |
+| **skipped** | name appears in `config.json connections.skip[]` |
+| **unavailable** | probe returned `unavailable` (configured but broken — needs attention) |
+
+### Recommendation mapping
+
+| Project hint | Recommend |
+|---|---|
+| `HAS_TAILWIND` or `HAS_FIGMA_HINT` | figma |
+| `HAS_STORYBOOK_DIR` or storybook available | storybook, chromatic |
+| `HAS_PEN_FILES` | pencil-dev |
+| `HAS_REACT` | 21st-dev, magic-patterns |
+| Always | refero, preview |
+
+---
+
+## Step 3 — Print summary table
+
+```
+━━━ Connections ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Available (<N>)
+  ✓ <name>             <one-line detail from probe>
+  ...
+
+Unavailable (<N>) — configured but not responding
+  ✗ <name>             <reason>
+  ...
+
+Recommended for this project (<N>)
+  ○ <name>             <one-line value prop>
+  ...
+
+Optional (<N>)
+  ○ <name>             <one-line value prop>
+  ...
+
+Skipped by you (<N>)
+  — <name>             (re-enable: /gdd:connections <name>)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+One-line value props (use verbatim):
+
+| Name | Value prop |
+|---|---|
+| figma | design-token extraction, annotations, Code Connect |
+| refero | design reference search for discover stage |
+| preview | live browser screenshots for verify visual checks |
+| storybook | component inventory + per-story a11y |
+| chromatic | visual regression against your Storybook baseline |
+| graphify | knowledge-graph queries over component↔token↔decision |
+| pinterest | visual inspiration collection |
+| claude-design | Claude Design handoff bundle ingestion |
+| paper-design | bidirectional canvas (free tier: 100 calls/week) |
+| pencil-dev | `.pen` spec files as canonical design source |
+| 21st-dev | AI component generator (marketplace search) |
+| magic-patterns | AI component generator (DS-aware) |
+
+---
+
+## Step 4 — Route by mode
+
+### Mode: `list` or `--auto`
+
+After printing the summary, write STATE.md, append one-line hint: `Run /gdd:connections to configure.` Emit `## CONNECTIONS COMPLETE`. Exit.
+
+### Mode: `<connection-name>`
+
+Skip the top-level AskUserQuestion. Jump directly to Step 5 for that single connection.
+
+### Mode: interactive (default)
+
+AskUserQuestion:
+
+```
+question: "What would you like to do?"
+options:
+  - "Configure recommended (<N>)"     → loop Step 5 over recommended bucket
+  - "Pick one by one"                 → loop Step 5 over all not_configured
+  - "Configure all optional"          → loop Step 5 over optional bucket
+  - "Re-check a specific connection"  → prompt for name, run Step 1 for it only
+  - "Exit"                            → emit ## CONNECTIONS COMPLETE, exit
+```
+
+If recommended bucket is empty, swap that option for "Show all 12 and pick."
+
+---
+
+## Step 5 — Per-connection setup screen
+
+For each target connection:
+
+### 5.1 Read the spec
+
+Read `connections/<name>.md`. Extract:
+- The "Setup" section (prerequisites + install command)
+- The "Contributes at" row from the capability matrix (stages affected)
+
+### 5.2 Present the screen
+
+Print:
+
+```
+┌─ <name> ──────────────────────────────────────
+│ Status: <current probe result>
+│ Contributes: <one-line value prop from Step 3>
+│ Stages affected: <list from capability matrix>
+│ Requires: <prereqs line from spec>
+│
+│ Setup command:
+│   <install command from spec>
+└───────────────────────────────────────────────
+```
+
+### 5.3 AskUserQuestion
+
+```
+question: "Install <name>?"
+options:
+  - "Run install command now"       → 5.4a (auto-run path)
+  - "Copy command — I'll run it"    → 5.4b (manual path)
+  - "Skip for now"                  → 5.4c (no config change)
+  - "Never ask again"               → 5.4d (add to skip list)
+```
+
+### 5.4 Auto-run eligibility matrix
+
+**Only auto-run if the install command is reversible.** The matrix:
+
+| Connection | Install kind | Auto-run? | Rationale |
+|---|---|---|---|
+| figma | `claude mcp add` (remote MCP) | ✓ yes | Reversible via `claude mcp remove` |
+| preview | built-in, no install | — | Already present or not — no command to run |
+| paper-design | `claude mcp add` | ✓ yes | Reversible |
+| magic-patterns | `claude mcp add` | ✓ yes | Reversible |
+| pinterest | `npx -y @smithery/cli install` | ✓ yes | Smithery CLI manages entry |
+| refero | vendor-specific install | ✗ no | Vendor doesn't document a stable CLI — print link only |
+| storybook | `npx storybook init` | ✗ no | Mutates repo files — force manual |
+| chromatic | `npm install --save-dev chromatic` + env var | ✗ no | Writes package.json + needs `CHROMATIC_PROJECT_TOKEN` — force manual |
+| graphify | `pip install` + `gsd-tools config-set` | ✗ no | Python install + cross-tool config — force manual |
+| 21st-dev | `npx @21st-dev/magic init` + env var | ✗ no | Env var required — force manual |
+| pencil-dev | VS Code extension | ✗ no | IDE-level install — force manual |
+| claude-design | handoff bundle drop | ✗ no | User-driven file drop — force manual |
+
+For non-auto-run connections, hide the "Run install command now" option entirely in 5.3. Only show the three remaining options.
+
+### 5.4a — Auto-run path
+
+Bash the install command. On success:
+- Print stdout.
+- Print: `"Installed. Session restart required before <name> is usable."`
+- Append `<name>` to `.design/config.json > connections_onboarding.pending_verification[]`.
+
+On failure:
+- Print stderr.
+- Print: `"Install failed. Copy the command and run it manually, then rerun /gdd:connections <name> to verify."`
+- Do not record pending_verification.
+
+### 5.4b — Manual path
+
+Print the install command inside a fenced code block for easy copy:
+
+````
+```bash
+<install command>
+```
+````
+
+Print: `"After installing, restart the session and run /gdd:connections <name> to verify."`
+
+Append `<name>` to `connections_onboarding.pending_verification[]`.
+
+### 5.4c — Skip for now
+
+No config change. Continue loop.
+
+### 5.4d — Never ask again
+
+Read `.design/config.json`. Ensure `connections.skip` is an array. Append `<name>` if not present. Write back.
+
+### 5.5 After every per-connection screen
+
+If mode is `<connection-name>` (single-target invocation), skip straight to Step 6. Otherwise continue the loop.
+
+---
+
+## Step 6 — Verification pass
+
+Re-probe every connection whose name appears in `connections_onboarding.pending_verification[]`. For each:
+
+- Now `available` → remove from `pending_verification[]`. Update STATE.md.
+- Still `not_configured` → leave in `pending_verification[]`. User probably needs a session restart.
+- Now `unavailable` → leave in `pending_verification[]`, print: `"<name> installed but probe errored — OAuth or auth may be required."`
+
+Write STATE.md `<connections>` and `.design/config.json`.
+
+### Print summary
+
+```
+━━━ Setup complete ━━━
+Newly available: <list>
+Still pending (needs session restart): <list>
+Skipped permanently: <list>
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+If any pending remain, print: `"After restarting the session, run /gdd:connections to verify remaining."`
+
+If no pending remain and at least one install happened, print: `"Run /gdd:scan to start your first cycle, or /gdd:brief to capture a design problem."`
+
+---
+
+## Resumability
+
+If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry, this is a resumed session (most likely after a restart for a just-installed MCP):
+
+1. Print: `"Resuming — <N> connections pending verification: <list>"`
+2. Run Step 6 (verification pass) immediately.
+3. If resumption completes cleanly (empty pending list), emit `## CONNECTIONS COMPLETE` and exit — do not re-enter the wizard.
+4. Otherwise, fall through to Step 3 (summary) with the still-pending connections visible as `unavailable`.
+
+---
+
+## Config file writes
+
+### `.design/config.json > connections.skip[]`
+
+Pattern: read whole file, merge one field, write back (matches `/gdd:settings` pattern).
+
+```json
+{
+  "model_profile": "balanced",
+  "parallelism": { ... },
+  "connections": {
+    "skip": ["pinterest", "graphify"]
+  }
+}
+```
+
+### `.design/config.json > connections_onboarding` (scratch block)
+
+Deleted automatically when empty after a verification pass:
+
+```json
+{
+  "connections_onboarding": {
+    "started_at": "<ISO 8601>",
+    "pending_verification": ["figma", "chromatic"]
+  }
+}
+```
+
+### `STATE.md <connections>` write
+
+Always merge, never replace — other stages may have written entries this skill did not probe. Example merge:
+
+Before:
+```xml
+<connections>
+figma: not_configured
+refero: not_configured
+</connections>
+```
+
+After running this skill with figma install succeeded:
+```xml
+<connections>
+figma: available
+refero: not_configured
+pinterest: not_configured
+preview: available
+storybook: available
+chromatic: not_configured
+graphify: not_configured
+claude_design: not_configured
+paper_design: not_configured
+pencil_dev: not_configured
+twenty_first: not_configured
+magic_patterns: not_configured
+</connections>
+```
+
+Key normalization:
+- `21st-dev` → `twenty_first` in STATE.md (no leading digit in XML-ish key).
+- `magic-patterns` → `magic_patterns`.
+- `paper-design` → `paper_design`.
+- `pencil-dev` → `pencil_dev`.
+- `claude-design` → `claude_design`.
+- All other names map 1:1.
+
+---
+
+## Do Not
+
+- Never run `npm install -g` globals automatically. Always force manual path for globals.
+- Never write to `~/.bashrc`, `~/.zshrc`, or shell RC files. Env-var setup is always manual.
+- Never run `claude mcp add` without explicit `"Run install command now"` confirmation.
+- Never auto-restart the Claude Code session. Print the instruction and let the user act.
+- Never re-prompt for names in `connections.skip[]`. If the user wants to re-enable, they invoke `/gdd:connections <name>` explicitly.
+- Never overwrite existing `<connections>` entries that this skill did not probe. Merge only.
+
+---
+
+## Output
+
+End every invocation with:
+
+```
+## CONNECTIONS COMPLETE
+```

package/skills/new-project/SKILL.md

@@ -43,7 +43,7 @@ One-time project initialization. Replaces "run scan cold" by gathering context u
    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."
+10. Print: "Project initialized. Run `/gdd:brief` to capture your design problem, or `/gdd:explore` to scan directly. Run `/gdd:connections` to wire up optional integrations (Figma, Storybook, Chromatic, etc.)."
 
 ## Do Not
 

package/skills/progress/SKILL.md

@@ -31,6 +31,16 @@ Next: /gdd:<next-stage>
 
 Recommend next stage via the same logic as `/gdd:next` (route by which artifacts exist).
 
+### 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:
+
+```
+Tip: run /gdd:connections to see what integrations can plug in (Figma, Storybook, Chromatic, etc.).
+```
+
+Suppress the nudge on subsequent invocations in the same session (track via a transient marker file `.design/.connections-nudge-shown` written at first emit, deleted on next session start by no mechanism — so effectively once per session).
+
 ## Step 3 — Forensic audit (only if `--forensic`)
 
 Run these six checks and print PASS/WARN/FAIL per check:

package/skills/scan/SKILL.md

@@ -150,6 +150,14 @@ Write: graphify: <status> to STATE.md <connections>
 
 After all 4 probes, STATE.md `<connections>` contains all 4 status entries (plus the Wave A `figma:` and `refero:` probes = 6 total entries). Downstream plans (08-02 through 08-05) read these values without re-probing.
 
+**First-run connection nudge:** after writing STATE.md, check whether every probed connection came back `not_configured` AND `.design/config.json > connections_onboarding` is absent. If so, print once at the end of scan output:
+
+```
+Tip: run /gdd:connections to walk through setup for Figma, Storybook, Chromatic, and 9 other integrations.
+```
+
+Suppress the nudge if any probe returned `available` or `unavailable`, or if the user has already run `/gdd:connections` (marker: `connections_onboarding` block present or previously drained).
+
 ### Write STATE.md
 
 Update `.design/STATE.md` with probe results:

package/skills/verify/SKILL.md

@@ -28,13 +28,14 @@ Run at stage entry, after reading STATE.md:
 ```
 Step P1 — ToolSearch check:
   ToolSearch({ query: "Claude_Preview", max_results: 5 })
-  → Empty result      → preview: not_configured  (skip all Preview steps in this stage)
+  → Empty result      → preview: not_loaded  (MCP not registered — skip all Preview steps in this stage)
   → Non-empty result  → proceed to Step P2
 
 Step P2 — Live tool call:
   call mcp__Claude_Preview__preview_list
-  → Success           → preview: available
-  → Error             → preview: unavailable
+  → Success                               → preview: available
+  → Error containing "permission"/blocked → preview: permission_denied
+  → Any other error                       → preview: unreachable
 
 Write preview status to .design/STATE.md <connections>.
 ```