@hegemonart/get-design-done 1.0.7

package/connections/chromatic.md

@@ -0,0 +1,247 @@
+# Chromatic — Connection Specification
+
+This file is the connection specification for Chromatic within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+Chromatic is the **verify stage's visual regression tool** and the **plan stage's change-risk scoping tool**. It captures Storybook story snapshots in the cloud and compares them to approved baselines. Its pipeline role: after a design executor pass, run Chromatic to surface which stories changed visually — the verify stage narrates these changes in plain English. Before planning a token or component change, use `--trace-changed` to enumerate exactly which stories depend on the files being changed, turning vague "this might affect things" into "23 stories are at risk."
+
+**Key dependency:** Chromatic requires Storybook. If `storybook: not_configured`, Chromatic cannot function even if its project token is present.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- Storybook configured in the project (see `connections/storybook.md` — Chromatic builds require a working Storybook configuration)
+- Chromatic account created at [chromatic.com](https://www.chromatic.com) — free tier available
+
+**Install:**
+
+```bash
+npm install --save-dev chromatic
+```
+
+**Account and token:**
+
+1. Create a Chromatic account at chromatic.com
+2. Link your repository and create a project
+3. Copy the project token from the project settings page
+4. Set the environment variable — **NEVER commit the token to git or to a tracked `.env` file:**
+
+```bash
+export CHROMATIC_PROJECT_TOKEN=<your-token>
+```
+
+Add this to your shell profile or CI environment secrets. Do not add it to `.env` files that are tracked in version control.
+
+**First run (baseline establishment):**
+
+```bash
+npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN
+```
+
+The first run creates baseline snapshots for all stories. Every story appears as "new" — this is not a regression. See the Baseline Management section below.
+
+**Verification:**
+
+```bash
+command -v chromatic 2>/dev/null || npx chromatic --version
+```
+
+---
+
+## Why Chromatic is useful
+
+Visual regressions are invisible to code review. A token change from `#3B82F6` to `#2563EB` looks like a one-character diff in a CSS file but visually affects every component that uses that token — buttons, links, badges, focus rings — across every state: hover, disabled, active, dark mode.
+
+Chromatic snapshots every component state (every Storybook story) and flags pixel-level differences against approved baselines. Without Chromatic:
+
+- Manual visual review of all story states is impractical at scale
+- Token changes silently regress secondary states (disabled, loading, edge cases)
+- Dark mode parity breaks go unnoticed until user report
+
+With Chromatic:
+
+- Every story state is a regression test
+- Changes surface immediately with before/after visual diff
+- `--trace-changed` tells the planner exactly how many stories depend on a given source file before any change is made
+
+---
+
+## When to use Chromatic
+
+**Verify stage:** After the design executor runs, run Chromatic to check for visual regressions. The verify stage reads `.design/chromatic-results.json` and narrates the delta in plain English.
+
+**Plan stage:** Before writing DESIGN-PLAN.md, run `--trace-changed` to enumerate which stories are affected by the planned token or component changes. Annotate tasks with the at-risk story count.
+
+---
+
+## CLI Commands (not MCP tools — Bash)
+
+Chromatic is a CLI tool, not an MCP. All interactions are via Bash commands.
+
+| Command | Flags | Returns | Pipeline use |
+|---------|-------|---------|--------------|
+| `npx chromatic` | `--project-token $TOKEN --output json` | JSON build results → `.design/chromatic-results.json` | verify: delta narration (CHR-01) |
+| `npx chromatic` | `--project-token $TOKEN --trace-changed=expanded --dry-run` | Story dependency tree (stdout) | plan: change-risk scoping (CHR-02) |
+| `npx chromatic` | `--project-token $TOKEN --junit-report` | JUnit XML report | CI integration (optional) |
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| 0 | Build OK — no visual changes detected |
+| 1 | Build has visual changes detected (not necessarily regressions — needs review on chromatic.com) |
+| 2 | Build has errors |
+| 11 | Account quota reached |
+
+**Important:** Exit code 1 means changes were detected, NOT that an error occurred. In CI scripts, use `|| true` or check the exit code explicitly — do not treat exit code 1 as a build failure without review.
+
+**Full verify run command:**
+
+```bash
+npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --output json 2>&1 | tee .design/chromatic-results.json
+```
+
+**TurboSnap change-risk command:**
+
+```bash
+npx chromatic --project-token $CHROMATIC_PROJECT_TOKEN --trace-changed=expanded --dry-run 2>&1
+```
+
+`--dry-run` skips publishing to the Chromatic cloud. `--trace-changed=expanded` outputs the full dependency tree showing which story files are affected by which source file changes.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Agent | Command | Purpose |
+|-------|-------|---------|---------|
+| verify | `agents/design-verifier.md` | `npx chromatic --project-token $TOKEN --output json` | Delta narration; visual regression flagging (CHR-01) |
+| plan | `agents/design-planner.md` | `npx chromatic --project-token $TOKEN --trace-changed=expanded --dry-run` | Story-count annotation for change-risk scoping (CHR-02) |
+
+---
+
+## Availability Probe
+
+Chromatic is a CLI tool — the probe is Bash-based, not ToolSearch-based.
+
+**Step C1 — CLI presence:**
+
+```bash
+command -v chromatic 2>/dev/null || npx chromatic --version 2>/dev/null
+```
+
+- Command found → proceed to Step C2
+- Not found → `chromatic: not_configured` (skip all Chromatic steps)
+
+**Step C2 — Token check:**
+
+```bash
+test -n "${CHROMATIC_PROJECT_TOKEN}"
+```
+
+- Non-empty → `chromatic: available`
+- Empty → `chromatic: unavailable` (CLI present but no project token)
+
+**Also check:** If `storybook: not_configured` in STATE.md `<connections>`, Chromatic is effectively unavailable even if the token is present. Emit: "Chromatic requires Storybook — storybook not configured" and skip all Chromatic steps.
+
+**Write chromatic status to `.design/STATE.md` `<connections>` after probing.**
+
+---
+
+## Baseline Management
+
+Chromatic requires an approved baseline build before it can compute visual diffs. The first run establishes the baseline.
+
+**First run behavior:**
+
+- Every story snapshot appears with `status: "new"` — this means "first snapshot captured", NOT a regression
+- All stories are automatically accepted as the baseline
+- Subsequent runs compare against these accepted baselines
+
+**Subsequent run behavior:**
+
+- `status: "unchanged"` — story matches baseline
+- `status: "changed"` — story differs from baseline (regression candidate — review required on chromatic.com)
+- `status: "accepted"` — change was intentionally approved by a reviewer on chromatic.com
+- `status: "new"` — new story added since last build (not a regression)
+- `status: "error"` — story failed to render
+
+**Narration rules:**
+
+- **First run** (all entries have `status: "new"`): emit "Baseline established — no regressions detected (first run creates baseline)."
+- **Subsequent runs with changes** (`status: "changed"` entries exist): emit "VISUAL REGRESSION CANDIDATES: N stories changed — review required on chromatic.com before merging."
+- **Clean run** (all `status: "unchanged"` or `status: "accepted"`): emit "Visual regression check passed — all stories match baseline."
+
+---
+
+## Fallback Behavior
+
+**verify stage:**
+
+- `chromatic: unavailable` → skip delta narration; skip visual regression check; note in DESIGN-VERIFICATION.md: "Visual regression check skipped — CHROMATIC_PROJECT_TOKEN not set."
+- `chromatic: not_configured` → same as unavailable; note: "Visual regression check skipped — chromatic CLI not installed (npm install --save-dev chromatic)."
+- `storybook: not_configured` → skip; note: "Visual regression check skipped — Chromatic requires Storybook, which is not configured."
+
+**plan stage:**
+
+- `chromatic: unavailable` or `not_configured` → skip story-count annotation; design-planner proceeds without at-risk story counts.
+- `storybook: not_configured` → same skip behavior.
+
+**Graceful degradation required:** The pipeline must continue when Chromatic is unavailable. Missing visual regression data is a quality reduction, not a blocking error.
+
+---
+
+## STATE.md Integration
+
+Every stage that probes Chromatic writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+storybook: unavailable
+chromatic: available
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | CLI present AND `CHROMATIC_PROJECT_TOKEN` is set |
+| `unavailable` | CLI present but `CHROMATIC_PROJECT_TOKEN` is empty |
+| `not_configured` | CLI not found — chromatic not installed |
+
+**Note:** Even with `chromatic: available`, if `storybook: not_configured`, Chromatic cannot run. Stages must check both statuses before invoking Chromatic.
+
+---
+
+## Caveats and Pitfalls
+
+**1. First run is always 100% "new" — not regressions**
+
+On the first Chromatic run (no existing baseline), every story registers as `status: "new"`. This is expected and correct — Chromatic is establishing the baseline, not detecting regressions. The verify stage must detect this condition (all entries `status: "new"`) and emit the baseline-establishment message rather than a regression alert.
+
+**2. CHROMATIC_PROJECT_TOKEN security**
+
+`CHROMATIC_PROJECT_TOKEN` grants write access to your Chromatic project (publish builds, approve snapshots). Treat it like a password:
+- Set it as an environment variable in your shell profile or CI secrets
+- Never commit it to git (not in source files, not in `.env`, not in configuration files)
+- Never log it in CI output
+- Rotate it if it is exposed
+
+**3. Exit code 1 is not an error**
+
+Exit code 1 means visual changes were detected — it is expected and normal after a design pass. Do not configure CI to fail on exit code 1 without a review step. Use `|| true` in scripts if you want the command to not block CI, then check the results separately.
+
+**4. `--dry-run` and `--output json` are separate, incompatible for narration**
+
+`--dry-run` skips publishing to Chromatic cloud — it does NOT produce chromatic-results.json. Use `--output json` (without `--dry-run`) for verify-stage narration. Use `--trace-changed=expanded --dry-run` for plan-stage scoping (which doesn't need the results file).
+
+**5. Storybook dependency is hard**
+
+Chromatic builds your Storybook and uploads the output to the cloud. If Storybook is not installed or `storybook build` fails, Chromatic will fail. Always check `storybook: not_configured` before attempting to run Chromatic.

package/connections/claude-design.md

@@ -0,0 +1,190 @@
+# Claude Design — Connection Specification
+
+This file is the connection specification for Claude Design (https://claude.ai/design, Anthropic Labs) within the get-design-done pipeline. Its primary role is to enable handoff-first workflows: when a Claude Design handoff bundle is available, users can skip the scan/discover/plan stages and route directly to verify. Claude Design is not an MCP server — it is a browser-based design tool that produces exportable handoff bundles. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## What Is a Claude Design Handoff Bundle?
+
+Claude Design produces AI-generated designs that can be exported as **handoff bundles**. A bundle contains:
+
+| Artifact | Format | Contains |
+|----------|--------|---------|
+| Standalone HTML export | `.html` | Rendered component tree, inline CSS (design tokens as CSS custom properties), component structure, color/spacing/typography values |
+| Design spec (optional) | `.md` or `.json` | Design decisions as structured text, token tables, component annotations |
+| Assets (optional) | `assets/` dir | Icons, images referenced by the HTML export |
+
+**Bundle entry point:** The primary parseable artifact is the HTML export. It contains inline `<style>` blocks with CSS custom properties (e.g., `--color-primary: #3B82F6`) and class-level token usage.
+
+**Bundle discovery:** The pipeline looks for the bundle in:
+1. The path passed via `--from-handoff <path>` flag or `handoff <path>` sub-command
+2. The value of `handoff_source` in `.design/STATE.md` (if a prior session already set it)
+3. A `claude-design-handoff.html` file in the project root (convention — not required)
+
+---
+
+## Handoff Bundle Format — Field Catalogue
+
+### From the HTML export (primary parsing target)
+
+| Field type | CSS pattern to grep | Example | D-XX mapping |
+|------------|--------------------|---------|-----------| 
+| Color tokens | `--color-[name]:` in `<style>` | `--color-primary: #3B82F6` | `[Color] Primary: #3B82F6` |
+| Spacing tokens | `--spacing-[n]:` in `<style>` | `--spacing-4: 1rem` | `[Spacing] Scale unit: 1rem (4px base)` |
+| Typography tokens | `--font-[family|size|weight]:` in `<style>` | `--font-family: Inter, sans-serif` | `[Typography] Font family: Inter` |
+| Radius tokens | `--radius-[n]:` in `<style>` | `--radius-md: 8px` | `[Radius] Default: 8px` |
+| Shadow tokens | `--shadow-[level]:` in `<style>` | `--shadow-sm: 0 1px 2px` | `[Shadow] Elevation-sm: 0 1px 2px` |
+| Component names | `<section class="component-[name]">` | `component-button` | `[Component] Button exists` |
+| Layout pattern | `display: [grid\|flex]` in component sections | `display: grid; grid-template-columns: repeat(3, 1fr)` | `[Layout] Card grid: 3-col` |
+
+### From the spec markdown/JSON (secondary, if present)
+
+Grep for `Decision:`, `Rationale:`, `Token:`, `Component:` prefixes. Treat as pre-formed D-XX entries — translate directly into STATE.md decisions with `(source: claude-design-handoff)` tag.
+
+---
+
+## Adapter Pattern — Bundle Fields → D-XX Decisions
+
+The `design-research-synthesizer` runs in `handoff` mode when `handoff_source` is present in STATE.md. It:
+
+1. Parses the HTML export for CSS custom properties (colors, spacing, typography, radius, shadows)
+2. Reads any `.md` spec file in the same directory as the HTML export
+3. Translates each found value into a D-XX decision entry
+4. Tags all entries: `(source: claude-design-handoff)` + `(tentative — confirm with user)` for inferred values, `(locked — from handoff spec)` for explicit spec values
+5. Appends all entries to STATE.md `<decisions>` block and `.design/DESIGN-CONTEXT.md`
+
+**Confidence levels:**
+
+| Source | Tag | Confidence |
+|--------|-----|-----------|
+| Explicit spec markdown `Decision: ...` | `(locked — from handoff spec)` | High — treat as confirmed |
+| CSS custom property in `<style>` | `(tentative — from handoff CSS)` | Medium — surfaced to user for confirm |
+| Inferred from class structure | `(tentative — inferred)` | Low — always surface to user |
+
+---
+
+## Stage Routing for Handoff Workflows
+
+When `handoff_source` is set in STATE.md:
+
+```
+Normal pipeline: scan → discover → plan → design → verify
+Handoff pipeline:  [scan skipped] → [discover skipped] → [plan skipped] → verify
+```
+
+**What skipped stages write to STATE.md:**
+
+```xml
+<position>
+stage: verify
+wave: 1
+task_progress: 0/0
+status: handoff-sourced
+handoff_source: claude-design-html
+skipped_stages: scan, discover, plan
+</position>
+```
+
+**Verify `--post-handoff` mode** (implemented in plan 09-05):
+- DESIGN-PLAN.md prerequisite check is relaxed (no DESIGN-PLAN.md exists for handoff flows)
+- Adds "Handoff Faithfulness" section to DESIGN-VERIFICATION.md
+- All other verify checks run normally
+
+---
+
+## Reverse Workflow — DESIGN.md → Claude Design Onboarding
+
+After a successful implementation cycle, the pipeline can produce a design spec document that can be shared back with Claude Design (or any AI design tool) as an onboarding artifact:
+
+1. Run `/gdd:style` to generate `DESIGN-STYLE-[Component].md` for key components
+2. Collect the D-XX decisions from STATE.md `<decisions>` block
+3. Combine into `DESIGN.md` (or use the existing one if it was produced by the pipeline)
+
+This `DESIGN.md` + `DESIGN-STYLE-*.md` set can be copy-pasted into a Claude Design conversation to seed a new AI design iteration with the implemented system's actual values — "feed the code back to the designer."
+
+**No automation is required for this workflow** — it is a manual copy-paste operation. The connection spec documents it so users know it is possible.
+
+---
+
+## Availability Probe
+
+Claude Design is not an MCP server — it has no tools to probe via ToolSearch. Availability is determined by whether the user has provided a handoff bundle path.
+
+**Probe pattern:**
+
+```
+At scan stage entry:
+  1. Check STATE.md <position> for handoff_source field
+  2. Check $ARGUMENTS for --from-handoff <path> flag
+  3. Check project root for claude-design-handoff.html
+
+  → Bundle path found AND file exists           → claude_design: available
+  → Bundle path provided but file missing/bad   → claude_design: unavailable
+  → No bundle path, no file                      → claude_design: not_configured
+```
+
+Write result to STATE.md `<connections>` at scan entry.
+
+**Verdict summary:**
+
+| Value | Meaning |
+|-------|---------|
+| `available` | A handoff bundle path was supplied and the file exists/parses |
+| `unavailable` | A handoff path was configured but the file is missing, unreadable, or malformed |
+| `not_configured` | No handoff bundle was supplied and none was discovered in the conventional location |
+
+---
+
+## STATE.md Integration
+
+### `<connections>` block
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+preview: available
+storybook: not_configured
+chromatic: not_configured
+figma_writer: not_configured
+graphify: not_configured
+pinterest: not_configured
+claude_design: available
+</connections>
+```
+
+### `<position>` block — handoff fields (added to STATE-TEMPLATE in plan 09-03)
+
+```xml
+<position>
+stage: verify
+wave: 1
+task_progress: 0/0
+status: handoff-sourced
+handoff_source: claude-design-html
+handoff_path: ./claude-design-handoff.html
+skipped_stages: scan, discover, plan
+</position>
+```
+
+**`handoff_source` values:**
+
+| Value | Meaning |
+|-------|---------|
+| `claude-design-html` | Bundle is a standalone HTML export from Claude Design |
+| `claude-design-bundle` | Bundle is a directory with HTML + spec markdown + assets |
+| `manual` | User manually initialized STATE.md with design decisions (no bundle file) |
+
+---
+
+## Caveats and Pitfalls
+
+1. **Handoff bundle format is undocumented by Anthropic.** The Claude Design handoff bundle format is inferred from the product announcement and common HTML export patterns. The pipeline uses defensive parsing: grep for CSS custom properties in `<style>` tags, extract component class names from `class="component-*"` patterns, and fall back to the spec markdown/JSON if CSS parsing yields no results. If the format changes in a future Claude Design release, update this spec and the synthesizer's parsing patterns.
+
+2. **`(tentative)` decisions MUST be confirmed by the user.** The discussant `--from-handoff` mode surfaces all tentative decisions for confirmation before proceeding to verify. Do NOT skip this step — implementing against unconfirmed inferred values is the primary failure mode of handoff-sourced workflows.
+
+3. **Skipped stages mean no DESIGN-PLAN.md.** Verify's normal prerequisite check requires DESIGN-PLAN.md. Handoff mode bypasses this check (plan 09-05 implements the relaxation). If running verify manually after a handoff, always pass `--post-handoff` to prevent the prerequisite check from blocking.
+
+4. **Handoff faithfulness is grep-based, not visual.** The Handoff Faithfulness score in DESIGN-VERIFICATION.md compares token values between the handoff bundle and the implemented code — it does NOT use computer vision or screenshot comparison. Visual fidelity between the Claude Design render and the implementation is currently out of scope (requires computer-use, deferred to a future phase).
+
+5. **Reverse workflow is manual — no automation.** The DESIGN.md → Claude Design onboarding flow is documentation of a manual workflow. The pipeline does not auto-post to Claude Design or call any external API.

package/connections/connections.md

@@ -0,0 +1,218 @@
+# Connections — Index and Capability Matrix
+
+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.
+
+---
+
+## Active Connections
+
+| Connection | Status | Spec File | Notes |
+|-----------|--------|-----------|-------|
+| Figma | Active | [`connections/figma.md`](connections/figma.md) | Uses `mcp__figma-desktop__*` tools (official Figma Desktop MCP) |
+| Refero | Active | [`connections/refero.md`](connections/refero.md) | Uses `mcp__refero__*` tools (verify names via ToolSearch) |
+| Preview | Active | [`connections/preview.md`](connections/preview.md) | Uses `mcp__Claude_Preview__*` tools |
+| Storybook | Active | [`connections/storybook.md`](connections/storybook.md) | HTTP probe: `localhost:6006/index.json` |
+| Chromatic | Active | [`connections/chromatic.md`](connections/chromatic.md) | CLI: `npx chromatic`; env: `CHROMATIC_PROJECT_TOKEN` |
+| Figma Writer | Active | [`connections/figma-writer.md`](connections/figma-writer.md) | Uses `mcp__figma__use_figma` (remote MCP) |
+| Graphify | Active | [`connections/graphify.md`](connections/graphify.md) | CLI: `graphify`; `gsd-tools graphify *` |
+| Pinterest | Active | [`connections/pinterest.md`](connections/pinterest.md) | `mcp__mcp-pinterest__*` tools (ToolSearch-only probe; headless scraping, no API key) |
+| Claude Design | Active | [`connections/claude-design.md`](connections/claude-design.md) | No MCP — bundle file probe; enables `/gdd:handoff` pipeline + bidirectional write-back via figma-writer |
+
+---
+
+## Capability Matrix
+
+Each cell describes what the connection contributes at that pipeline stage, or `—` if it is not used.
+
+| Connection | scan | discover | plan | design | verify |
+|-----------|------|----------|------|--------|--------|
+| Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | — | — |
+| Refero | — | reference search via `mcp__refero__search`; fallback → awesome-design-md (CONN-05) | — | — | — |
+| Preview | — | — | — | — | screenshots for `? VISUAL` checks (VIS-02) |
+| Storybook | — | component inventory (STB-01) | change-risk via story count (STB-02) | `.stories.tsx` stub (STB-03) | a11y per story (STB-02) |
+| Chromatic | — | — | change-risk scoping (CHR-02) | — | visual delta narration (CHR-01) |
+| Figma Writer | — | — | — | write tokens/annotations/Code Connect (FWR-01..04) | — |
+| Graphify | — | — | dependency scoping (GRF-03) | — | orphan detection (GRF-04) |
+| Pinterest | probe only | visual reference search via `pinterest_search`; fallback → Refero → awesome-design-md | — | — | — |
+| Claude Design | bundle probe → `claude_design: available` | synthesizer handoff mode — parses bundle → D-XX decisions; discussant `--from-handoff` confirms | — (skipped in handoff) | — (skipped in handoff) | Handoff Faithfulness section; bidirectional write-back via figma-writer `implementation-status` mode |
+
+**Column definitions:**
+
+- **scan** — what the connection provides when the scan stage runs (design tokens, source metadata)
+- **discover** — what the connection provides during discovery (visual references, design decisions)
+- **plan** — what the connection contributes to planning artifacts
+- **design** — what the connection provides during design execution
+- **verify** — what the connection checks or surfaces during verification
+
+---
+
+## Connection Probe Pattern
+
+This is the canonical probe pattern. All stages copy this prose inline — SKILL.md files have no include mechanism, so each stage repeats the relevant subset verbatim. The specification lives here; stages copy from it.
+
+**Why ToolSearch first:** MCP tools may be in the deferred tool set (not loaded into context at session start when many servers are registered). Calling a deferred tool directly fails silently. ToolSearch loads the tools into context and confirms presence in a single call — always call it before any MCP tool invocation.
+
+**Three-value status schema (fixed — do not extend):**
+
+| Status | Meaning |
+|--------|---------|
+| `available` | MCP tool confirmed present and responsive |
+| `unavailable` | MCP tool is in the session but errored (app offline, auth failure, rate-limited) |
+| `not_configured` | ToolSearch returned empty — MCP not registered in this session |
+
+**STATE.md format:**
+
+```xml
+<connections>
+figma: available
+refero: not_configured
+</connections>
+```
+
+`<connections>` is the single source of truth across stages. Every stage reads it before deciding whether to invoke an MCP tool. Every stage writes to it after probing.
+
+---
+
+**Figma probe (execute at stage entry, after reading STATE.md):**
+
+```
+Step A1 — ToolSearch check:
+  ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+  → Empty result      → figma: not_configured  (skip all Figma steps)
+  → Non-empty result  → proceed to Step A2
+
+Step A2 — Live tool call:
+  call mcp__figma-desktop__get_metadata
+  → Success           → figma: available
+  → Error             → figma: unavailable  (skip all Figma steps)
+
+Write figma status to STATE.md <connections>.
+```
+
+**Refero probe (execute at stage entry, after reading STATE.md):**
+
+```
+Step B1 — ToolSearch check:
+  ToolSearch({ query: "refero", max_results: 5 })
+  → Empty result      → refero: not_configured  (use fallback chain)
+  → Non-empty result  → refero: available
+
+Write refero status to STATE.md <connections>.
+```
+
+Note: Refero probe is ToolSearch-only (no live tool call). ToolSearch presence is sufficient; a live Refero search as probe would waste tokens before confirming the connection is even needed.
+
+---
+
+**Preview probe (execute at stage entry, after reading STATE.md):**
+
+```
+Step P1 — ToolSearch check:
+  ToolSearch({ query: "Claude_Preview", max_results: 5 })
+  → Empty result      → preview: not_configured
+  → Non-empty result  → proceed to Step P2
+
+Step P2 — Live tool call:
+  call mcp__Claude_Preview__preview_list
+  → Success (list returned, may be empty)  → preview: available
+  → Error                                   → preview: unavailable
+
+Write preview status to STATE.md <connections>.
+```
+
+**Storybook probe (execute at stage entry, after reading STATE.md):**
+
+```
+Step S1 — HTTP check (Storybook 8):
+  Bash: curl -sf http://localhost:6006/index.json 2>/dev/null
+  → Success (JSON)    → storybook: available
+  → Failure           → proceed to Step S2
+
+Step S2 — HTTP fallback (Storybook 7):
+  Bash: curl -sf http://localhost:6006/stories.json 2>/dev/null
+  → Success (JSON)    → storybook: available
+  → Failure           → storybook: not_configured
+
+Write storybook status to STATE.md <connections>.
+```
+
+Note: Storybook 8 index.json does NOT include parameters. Use id, title, name, type, kind, tags fields only.
+
+**Chromatic probe (execute at stage entry, after reading STATE.md):**
+
+```
+Step C1 — CLI check:
+  Bash: command -v chromatic || npx --yes chromatic --version 2>/dev/null
+  → Exits non-zero    → chromatic: not_configured  (skip all Chromatic steps)
+  → Exits 0           → proceed to Step C2
+
+Step C2 — Token check:
+  Check env var: CHROMATIC_PROJECT_TOKEN
+  → Absent or empty   → chromatic: unavailable  (CLI present but not configured)
+  → Present           → chromatic: available
+
+Write chromatic status to STATE.md <connections>.
+```
+
+Note: First Chromatic run has no baseline — all stories become new snapshots. This is expected; it establishes the baseline.
+
+**Figma Writer probe (execute before any write operation):**
+
+```
+Step R1 — ToolSearch check:
+  ToolSearch({ query: "mcp__figma__use_figma", max_results: 1 })
+  → Empty result      → figma_writer: not_configured
+  → Non-empty result  → figma_writer: available
+
+Write figma_writer status to STATE.md <connections>.
+```
+
+Note: figma_writer is a separate connection key from figma (desktop). Both can be active simultaneously. There is no `unavailable` state for figma_writer — the ToolSearch-only probe cannot detect auth failures; those surface at execution time.
+
+**Graphify probe (execute at agent entry, before using graph):**
+
+```
+Step G1 — Config check:
+  node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
+  → Error or { enabled: false }  → graphify: not_configured
+  → { enabled: true }            → proceed to Step G2
+
+Step G2 — Graph file check:
+  Check if graphify-out/graph.json exists in project root
+  → Absent    → graphify: unavailable  (graph not built yet)
+  → Present   → graphify: available
+
+Write graphify status to STATE.md <connections>.
+```
+
+---
+
+**Graceful degradation required:** stages MUST continue when a connection is `unavailable` or `not_configured`. Skip connection-dependent steps. If a missing connection prevents a `must_have` from being satisfied, append a `<blocker>` to `.design/STATE.md` and continue.
+
+For full per-connection fallback details, see the spec files: [`connections/figma.md`](connections/figma.md), [`connections/refero.md`](connections/refero.md), [`connections/preview.md`](connections/preview.md), [`connections/storybook.md`](connections/storybook.md), [`connections/chromatic.md`](connections/chromatic.md), [`connections/figma-writer.md`](connections/figma-writer.md), and [`connections/graphify.md`](connections/graphify.md).
+
+---
+
+## Extensibility Guide
+
+To add a new connection to the pipeline:
+
+1. **Create the spec file.** Write `connections/<connection-name>.md` following the structure of `connections/refero.md`: what the tool does, when to use it, available MCP tools, search/invocation strategy, fallbacks, anti-patterns.
+
+2. **Register in this file.** Add a row to the Active Connections table above (status, spec file path, MCP tool prefix).
+
+3. **Update the Capability Matrix.** Add a row for the new connection. Mark the stages it feeds with a short capability noun; use `—` for stages it does not affect.
+
+4. **Declare the MCP.** If the connection uses an MCP server, ensure the server is declared in `.claude-plugin/plugin.json` or documented as a user-supplied MCP in the spec file. For read-only MCP connections, use `connections/figma.md` as the model. For remote MCP write connections, use `connections/figma-writer.md` as the model.
+
+5. **Wire into stage skills (Phase 2+ work).** Update the relevant stage `SKILL.md` files to probe the connection at entry and write its status to `.design/STATE.md <connections>`.
+
+6. **Update relevant agents (Phase 2+ work).** If agents will use the connection's tools, list the MCP tools in the agent's `tools` frontmatter field.
+
+---
+
+## Notes
+
+- `connections/` is infrastructure scaffolding introduced in Phase 1. Stage integration (wiring detection and graceful degradation into each stage) is Phase 2 work.
+- Phase 8 added five new active connections. Linear and GitHub remain planned for a future phase.
+- The capability matrix columns map to the five pipeline stages: `scan | discover | plan | design | verify`.