@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/compare/compare-rubric.md

@@ -0,0 +1,171 @@
+---
+name: compare-rubric
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [compare, delta, drift, scoring, rubric, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/compare/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing workflow stays in `../skills/compare/SKILL.md`; this file holds the
+delta-computation methodology, anti-pattern set arithmetic, drift-detection coverage map,
+and the `COMPARE-REPORT.md` template the skill writes.
+
+# Compare Rubric — Baseline vs Result Delta Methodology
+
+Detailed methodology for the `get-design-done:compare` standalone command — companion to
+`../skills/compare/SKILL.md`. Read this file when executing a specific compare step (score
+delta math, anti-pattern set arithmetic, drift coverage map, report layout). The SKILL.md
+keeps the load-bearing pre-flight checks + step routing; this file holds the deep methodology.
+
+See `./shared-preamble.md#output-contract-reminders` for the per-skill output discipline and
+`./audit-scoring.md` for the 0–10 category-scoring rubric the delta is computed against.
+
+---
+
+## Step 1 — Parse Category Scores
+
+**Extract baseline scores from `.design/DESIGN.md`:** locate the category score table (rows like `| Accessibility | 6/10 | ... |`). Parse each row: extract category name + numeric score. Store as `baseline_scores` map.
+
+**Extract result scores from `.design/DESIGN-VERIFICATION.md`:** locate the same table in the Phase 1 output section. Store as `result_scores` map.
+
+**Normalize category names:**
+- Strip leading/trailing whitespace.
+- Apply title-case normalization (e.g., `anti-patterns` → `Anti-Patterns`).
+- Match categories case-insensitively between the two tables.
+
+**Unmatched categories:**
+- Baseline-only → flag `[UNMATCHED-BASELINE]`, exclude from score delta.
+- Result-only → flag `[UNMATCHED-RESULT]`, exclude from score delta.
+- Report all unmatched categories in the Notes section. Do NOT silently paper over mismatches.
+
+## Step 2 — Compute Score Delta (COMP-03)
+
+For each matched category: `delta = result_scores[category] - baseline_scores[category]`.
+
+Classify:
+- `improvement` — delta > 0
+- `no_change` — delta == 0
+- `regression` — delta < 0
+
+Record per category: name, baseline score, result score, signed delta, classification. Collect regressed categories for drift detection in Step 5.
+
+## Step 3 — Anti-Pattern Delta
+
+Enumerate anti-patterns in both files (entries identified by BAN-*, SLOP-*, or labeled as anti-patterns). Collect identifiers or descriptions as sets.
+
+Compute set arithmetic:
+
+```
+resolved  = baseline_anti_patterns - result_anti_patterns
+           (present in baseline, absent in result — fixed)
+
+new       = result_anti_patterns - baseline_anti_patterns
+           (absent in baseline, present in result — introduced)
+
+unchanged = intersection of both sets
+           (still present in both)
+```
+
+Report all three groups in the output report.
+
+## Step 4 — Must-Have Pass/Fail Change
+
+**Skip condition:** if `.design/DESIGN-CONTEXT.md` is absent → emit note and skip this section.
+
+Read `<must_haves>` from `DESIGN-CONTEXT.md` (each must-have has ID + description). Read pass/fail status from `DESIGN-VERIFICATION.md` (must-have status table). For each must-have: record `pass`, `fail`, or `not-evaluated`. If `DESIGN.md` contained a prior must-have status section, compute the change (`pass→fail`, `fail→pass`); otherwise report current status only.
+
+## Step 5 — Design Drift Detection (COMP-04)
+
+**Skip condition:** if `.design/DESIGN-PLAN.md` is absent → emit `"Drift detection skipped: DESIGN-PLAN.md not found."` in the Drift section.
+
+**Coverage map:** read `DESIGN-PLAN.md` and extract the `Type:` field from each task. Build a map of which design categories have at least one task of matching Type:
+
+```
+Type: accessibility   → covers "Accessibility" category
+Type: color           → covers "Color" category
+Type: typography      → covers "Typography" category
+Type: visual-hierarchy → covers "Visual Hierarchy" category
+```
+
+Category-to-Type matching is case-insensitive and normalized.
+
+**Drift check:** for each category classified as `regression` in Step 2: if category NOT in coverage_map → emit `DRIFT: [category] regressed from <baseline> to <result> without a design task of Type:<category>`.
+
+Emit `"No drift detected. All regressed categories are covered by tasks in DESIGN-PLAN.md."` if all regressed categories are covered. Emit `"No drift detected. No score regressions found."` if no regressions in Step 2.
+
+## Step 5B — Screenshot Delta (when preview: available)
+
+Check `preview` status from `.design/STATE.md <connections>` (written by the probe at stage entry — see `./shared-preamble.md#connection-handshake-summary`).
+
+**If `preview: available`:**
+
+1. `preview_start` if no session is already running.
+2. For each route inferred from `DESIGN-PLAN.md` tasks or `src/app/` / `src/pages/` file structure:
+   a. `preview_navigate` to route URL (e.g., `http://localhost:3000/<route>`).
+   b. `preview_screenshot` → save to `.design/screenshots/before/<route>.png` (only if a prior baseline exists at this path) and `.design/screenshots/after/<route>.png` (current render).
+   c. Record reference paths (NOT base64) for embedding in the `## Screenshot Delta` section.
+3. `preview_stop` when all routes are captured.
+
+**If `preview: unavailable` or `preview: not_configured`:** emit exactly `Screenshot delta skipped — preview not configured.`
+
+## Step 6 — COMPARE-REPORT.md Template
+
+Output path: `.design/COMPARE-REPORT.md`. This file MUST NOT be written to any pipeline-reserved path.
+
+```markdown
+# Compare Report: Baseline vs Result
+
+**Generated:** <ISO 8601 date>
+**Baseline:** .design/DESIGN.md
+**Result:** .design/DESIGN-VERIFICATION.md
+
+## Score Delta by Category
+
+| Category | Baseline | Result | Delta | Status |
+|----------|----------|--------|-------|--------|
+| Accessibility | 6 | 8 | +2 | improvement |
+| Visual Hierarchy | 5 | 5 | 0 | no_change |
+| Anti-Patterns | 4 | 3 | -1 | regression |
+
+## Anti-Pattern Delta
+
+**Resolved** (present in baseline, absent in result):
+- <anti-pattern id or description>
+
+**New** (absent in baseline, present in result):
+- <anti-pattern id or description>
+
+**Unchanged:**
+- <anti-pattern id or description>
+
+## Must-Have Status
+
+| Must-Have | Status |
+|-----------|--------|
+| <id / description> | pass |
+| <id / description> | fail |
+| <id / description> | not-evaluated |
+
+## Design Drift
+
+<One of: "No drift detected. ..." | "DRIFT: [Category] regressed ..." | "Drift detection skipped: DESIGN-PLAN.md not found.">
+
+## Screenshot Delta
+
+<Per-route screenshot pairs OR "Screenshot delta skipped — preview not configured.">
+
+## Notes
+
+Scope: delta between two existing artifacts (.design/DESIGN.md → .design/DESIGN-VERIFICATION.md).
+No snapshot mechanism — multi-snapshot compare deferred to V2-06.
+This report does not modify DESIGN.md, DESIGN-VERIFICATION.md, or any other pipeline artifact.
+<List any UNMATCHED-BASELINE or UNMATCHED-RESULT categories here, if any.>
+```
+
+If a section has no items (e.g., no anti-patterns in baseline), write "None."
+
+---
+
+*Imported by: `../skills/compare/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework — D-10).*

package/skills/complete-cycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-complete-cycle
-description: "Archive current cycle artifacts and prepare for the next cycle. Updates CYCLES.md, moves artifacts to .design/archive/cycle-N/."
+description: "Cycle closeout command that marks CYCLES.md entry complete, archives pipeline artifacts to .design/archive/cycle-N/, generates EXPERIENCE.md, rebuilds the search index, and resets STATE.md. Use when a design cycle has shipped and you're ready to start the next one."
 argument-hint: "[<retrospective note>]"
 tools: Read, Write, Bash, AskUserQuestion
 ---

package/skills/connections/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Interactive onboarding wizard for the 12 external integrations the pipeline supports — probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
 argument-hint: "[list | <connection-name> | --auto]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
@@ -10,7 +10,9 @@ tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch
 
 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.
+Canonical per-connection specs live in `../../connections/<name>.md` (one file per integration). The capability matrix + probe-pattern spec live in `../../connections/connections.md`. This skill is the **user-facing front end** for those specs.
+
+For the 12 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ---
 
@@ -27,444 +29,36 @@ Canonical connection specs live in `connections/*.md`. The capability matrix and
 
 ## State Integration
 
-1. Read `.design/STATE.md` — if missing, that's fine; this skill does not require a pipeline run to be in progress.
+1. Read `.design/STATE.md` — if missing, that's fine; this skill does not require a pipeline run.
 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).
+3. Read `connections.skip[]` from config — never re-prompt for skipped connections.
 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
-```
+## Workflow
 
-### Non-MCP probes
+1. **Probe all 12 connections** — run every probe script per `./connections-onboarding.md#step-1--probe-all-12-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) — never add new values.
+2. **Categorize + build summary** — bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
+3. **Print summary table** — show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
+4. **Route by mode** — `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
+5. **Per-connection setup screen** — for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
+6. **Verification pass** — re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
 
-**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.
+If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `./connections-onboarding.md#resumability`.
 
 ---
 
 ## 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.
+Per `./connections-onboarding.md#do-not`:
+
+- Never run `npm install -g` globals automatically.
+- Never write to `~/.bashrc`, `~/.zshrc`, or shell RC files.
 - 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.
+- Never auto-restart the Claude Code session.
+- Never re-prompt for names in `connections.skip[]`.
+- Never overwrite existing `<connections>` entries that this skill did not probe — merge only.
 
 ---