@hegemonart/get-design-done 1.0.7 → 1.14.1

package/connections/connections.md

@@ -8,15 +8,18 @@ This directory contains connection specifications for external tools and MCPs th
 
 | Connection | Status | Spec File | Notes |
 |-----------|--------|-----------|-------|
-| Figma | Active | [`connections/figma.md`](connections/figma.md) | Uses `mcp__figma-desktop__*` tools (official Figma Desktop MCP) |
+| Figma | Active | [`connections/figma.md`](connections/figma.md) | Uses `mcp__figma__*` tools (remote Figma MCP; reads + writes) |
 | 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 |
+| paper.design | Active | [`connections/paper-design.md`](connections/paper-design.md) | Uses `mcp__paper-design__*` tools; free tier: 100 calls/week |
+| pencil.dev | Active | [`connections/pencil-dev.md`](connections/pencil-dev.md) | File-based; `.pen` YAML specs; git-tracked; no MCP |
+| 21st.dev Magic MCP | Active | [`connections/21st-dev.md`](connections/21st-dev.md) | Uses `mcp__21st*` tools; `TWENTY_FIRST_API_KEY` required |
+| Magic Patterns | Active | [`connections/magic-patterns.md`](connections/magic-patterns.md) | Claude connector (`mcp__magic_patterns*`) + API key fallback |
 
 ---
 
@@ -24,17 +27,20 @@ This directory contains connection specifications for external tools and MCPs th
 
 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 |
+| Connection | scan | discover | plan | design | verify | canvas | generator |
+|-----------|------|----------|------|--------|--------|--------|-----------|
+| Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | write tokens/annotations/Code Connect via `use_figma` (FWR-01..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) | — | — |
+| 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 | — | — |
+| paper.design | — | canvas read: `get_selection`, `get_jsx`, `get_computed_styles` | — | paper-writer: annotate/tokenize/roundtrip | `get_screenshot` for `? VISUAL` | ✓ | — |
+| pencil.dev | `.pen` discovery | `.pen` as canonical design source | — | pencil-writer: annotate/roundtrip | spec-vs-impl diff | ✓ | — |
+| 21st.dev | — | prior-art gate: marketplace search before greenfield build | — | component-generator (21st impl) | — | — | ✓ |
+| Magic Patterns | — | — | — | component-generator (magic-patterns impl) | preview_url → `? VISUAL` check | — | ✓ |
 
 **Column definitions:**
 
@@ -43,6 +49,8 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 - **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
+- **canvas** — whether the connection provides bidirectional canvas read+write (see `reference/ai-native-tool-interface.md`)
+- **generator** — whether the connection provides AI component generation (see `reference/ai-native-tool-interface.md`)
 
 ---
 
@@ -75,16 +83,18 @@ refero: not_configured
 
 **Figma probe (execute at stage entry, after reading STATE.md):**
 
+One probe covers both reads and writes — the remote Figma MCP is a single server exposing `get_metadata`, `get_variable_defs`, `get_design_context`, `get_screenshot`, and `use_figma` together.
+
 ```
 Step A1 — ToolSearch check:
-  ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+  ToolSearch({ query: "select:mcp__figma__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)
+  call mcp__figma__get_metadata
+  → Success           → figma: available   (reads AND use_figma writes both available)
+  → Error             → figma: unavailable (skip all Figma steps)
 
 Write figma status to STATE.md <connections>.
 ```
@@ -156,19 +166,6 @@ 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):**
 
 ```
@@ -189,7 +186,7 @@ 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).
+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), and [`connections/graphify.md`](connections/graphify.md).
 
 ---
 
@@ -203,7 +200,7 @@ To add a new connection to the pipeline:
 
 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.
+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+write remote MCPs, use `connections/figma.md` as the model. For read-only remote MCPs with headless / API-key-free setup, use `connections/pinterest.md`.
 
 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>`.
 
@@ -215,4 +212,24 @@ To add a new connection to the pipeline:
 
 - `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`.
+- Phase 14 added four AI-native design tool connections (paper.design, pencil.dev, 21st.dev, Magic Patterns) and the canvas/generator capability columns.
+- The capability matrix columns map to the five pipeline stages: `scan | discover | plan | design | verify`, plus `canvas` and `generator` sub-categories.
+
+---
+
+## Future AI-Native Tools (Backlog)
+
+Candidate tools to integrate using the contract in `reference/ai-native-tool-interface.md`.
+
+| Tool | Sub-category | Priority |
+|------|-------------|----------|
+| Subframe | canvas | high |
+| v0.dev | generator | high |
+| Galileo AI | generator | medium |
+| Builder.io Visual Copilot | canvas + generator | medium |
+| Locofy | generator | low |
+| Anima | canvas | low |
+| Plasmic | generator | medium |
+| TeleportHQ | generator | low |
+
+To add any of these: follow the steps in `reference/ai-native-tool-interface.md §Extending with Future Tools`.

package/connections/figma.md

@@ -1,6 +1,6 @@
 # Figma MCP — Connection Specification
 
-This file is the connection specification for the official Figma Desktop MCP within the get-design-done pipeline. It provides the setup guide, tool inventory, per-stage usage, probe pattern, fallback behavior, and anti-patterns. See `connections/connections.md` for the full connection index and capability matrix.
+This file is the connection specification for the Figma MCP (remote, read + write) within the get-design-done pipeline. One server exposes both read tools (`get_metadata`, `get_design_context`, `get_variable_defs`, `get_screenshot`) and the write tool `use_figma`. See `connections/connections.md` for the full connection index and capability matrix.
 
 ---
 
@@ -8,49 +8,77 @@ This file is the connection specification for the official Figma Desktop MCP wit
 
 **Prerequisites:**
 
-- Figma desktop app installed and running
-- Dev Mode enabled in the Figma desktop app (File menu → Enable Dev Mode, or toggle in the toolbar)
+- A Figma account (OAuth on first use at `mcp.figma.com`).
+- Figma file access for any file you intend to read or write. No desktop app install required.
 
 **Install command (Claude Code):**
 
 ```
-claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
+claude mcp add figma --transport http https://mcp.figma.com/v1/sse
 ```
 
-After running this command, restart the Claude Code session. The MCP server connects via HTTP to the Figma desktop app's local MCP endpoint.
+After running this command, restart the Claude Code session. On first use, Claude Code prompts you to complete the OAuth flow at `mcp.figma.com`. One `claude mcp add` unlocks both reads and writes — there is no separate writer MCP.
 
 **Verification:**
 
 After session restart, run:
 
 ```
-ToolSearch({ query: "figma-desktop", max_results: 10 })
+ToolSearch({ query: "select:mcp__figma__get_metadata,mcp__figma__use_figma", max_results: 2 })
 ```
 
-Expect non-empty results listing `mcp__figma-desktop__*` tools. If results are empty, the desktop app is not running or Dev Mode is not enabled — fix both and restart.
+Expect two non-empty results. If results are empty, the remote MCP is not registered — re-run the install command above and restart the session.
 
-**Warning — wrong MCP confusion:**
+**Migration from the legacy dual-MCP setup:**
 
-This spec targets the **official Figma Desktop MCP** (`mcp__figma-desktop__*` prefix, server name `figma-desktop`, HTTP transport).
+Earlier versions of this plugin used two separate Figma MCPs — `figma-desktop` (local HTTP, read-only) and `figma` (remote, writes-only). As of **v1.0.7.1**, the remote MCP exposes full read parity and is the single supported Figma connection. If you installed `figma-desktop` previously, you can remove it:
 
-Do NOT confuse with the southleft `figma-console-mcp` package (registered as `"figma-console"` in `~/.claude/mcp.json`, uses `figma_*` prefix). Both can be active simultaneously. The pipeline uses `mcp__figma-desktop__*` exclusively — it is stable, official, and requires no external package dependency beyond the Figma desktop app.
+```
+claude mcp remove figma-desktop
+```
+
+No data is lost — the remote MCP reads the same Figma files.
 
 ---
 
 ## Tools
 
-All tools use the `mcp__figma-desktop__` prefix.
+All tools use the `mcp__figma__` prefix (remote MCP).
 
-| Tool | Full name | Returns | Phase 4 use |
-|------|-----------|---------|-------------|
-| `get_variable_defs` | `mcp__figma-desktop__get_variable_defs` | Variable collection tree: collection ID, mode names, variable names (hierarchical, e.g. `colors/primary/500`), resolved values (hex for COLOR, float for FLOAT), descriptions, scopes | **In scope** — scan: token augmentation (CONN-03); discover: decisions pre-population (CONN-04) |
-| `get_design_context` | `mcp__figma-desktop__get_design_context` | Structured React+Tailwind component tree of the current Figma selection | **In scope (secondary)** — discover: existing design decisions for established Figma systems |
-| `get_screenshot` | `mcp__figma-desktop__get_screenshot` | Screenshot image of the selected Figma layer or frame | Out of scope Phase 4 |
-| `get_metadata` | `mcp__figma-desktop__get_metadata` | Lightweight XML outline: layer IDs, names, types, position/size. Works with no selection open. | **In scope** — used as the availability probe (no file must be open) |
-| `get_code_connect_map` | `mcp__figma-desktop__get_code_connect_map` | Maps Figma component instances to code implementations (file paths, framework labels) | Out of scope Phase 4 |
-| `create_design_system_rules` | `mcp__figma-desktop__create_design_system_rules` | Generates rule files for design system alignment during code generation | Out of scope Phase 4 |
+| Tool | Full name | Returns | Pipeline use |
+|------|-----------|---------|--------------|
+| `get_metadata` | `mcp__figma__get_metadata` | Lightweight outline: node IDs, names, types, position/size. Also the availability probe. | **In scope** — probe (works without a selection); metadata snapshot for figma-write proposal review |
+| `get_variable_defs` | `mcp__figma__get_variable_defs` | Variable collection tree: collection ID, mode names, variable names (hierarchical, e.g. `colors/primary/500`), resolved values, descriptions, scopes | **In scope** — scan: token augmentation (CONN-03); discover: decisions pre-population (CONN-04); figma-write: tokenize mode source |
+| `get_design_context` | `mcp__figma__get_design_context` | Structured React+Tailwind component tree of the current Figma selection | **In scope (secondary)** — discover: existing design decisions for established Figma systems |
+| `get_screenshot` | `mcp__figma__get_screenshot` | Screenshot image of the selected Figma layer or frame | **In scope (opt-in)** — visual reference capture for discovery; not invoked by default |
+| `use_figma` | `mcp__figma__use_figma` | Write operation result | **In scope** — figma-write: all three modes (annotate, tokenize, mappings) |
+| `get_code_connect_map` | `mcp__figma__get_code_connect_map` | Maps Figma component instances to code file paths | Out of scope this phase (reserved for future Code Connect work) |
+| `add_code_connect_map` | `mcp__figma__add_code_connect_map` | Adds Code Connect mapping entries | Out of scope this phase (reserved for future Code Connect work) |
+| `create_design_system_rules` | `mcp__figma__create_design_system_rules` | Generates rule files for design system alignment during code generation | Out of scope this phase |
 
-`get_metadata` is preferred for probing because it works without a file or selection open, keeping the probe lightweight. `get_variable_defs` is the primary workhorse for token extraction and decisions pre-population.
+`get_metadata` is preferred for probing because it works without a file or selection open, keeping the probe lightweight. `get_variable_defs` is the primary workhorse for token extraction and decisions pre-population. `use_figma` is the single entry point for every write.
+
+---
+
+## Writes (`use_figma`)
+
+`use_figma` is the single write tool. The `design-figma-writer` agent (`agents/design-figma-writer.md`) wraps it in a **proposal → confirm** UX — it builds a numbered operation list and presents it to the user before executing any write. The user must confirm before `use_figma` is called.
+
+### Three Modes
+
+The figma-writer operates in one of three modes per invocation:
+
+| Mode | Description | Source data | Figma target |
+|------|-------------|-------------|--------------|
+| `annotate` | Write design-decision annotations onto Figma layer comments | D-XX decisions from DESIGN-CONTEXT.md | Layer comments on affected frames/components |
+| `tokenize` | Replace hard-coded color/spacing/type literals with Figma variable references | Color/spacing/typography values from DESIGN-CONTEXT.md; existing variables from `get_variable_defs` | Variable bindings on layer fill/stroke/spacing properties |
+| `mappings` | Write Code Connect mappings linking component instances to code file paths | Component names and file paths from DESIGN-CONTEXT.md | Code Connect entries on Figma component nodes |
+
+### Write-Time Safety
+
+1. **`--dry-run`** — emit the full operation list without calling `use_figma`. Safe to run on production Figma files.
+2. **`--confirm-shared`** — when the proposal includes shared team-library components, the agent halts and requires this flag. Prevents accidental team-wide token modification.
+3. **Sequential, not atomic execution.** If one operation fails mid-sequence, the agent logs the error and continues with remaining operations. The summary lists all failures for manual follow-up. The Figma file may be left in a partially-updated state — this is a property of `use_figma`, not of the wrapper.
 
 ---
 
@@ -59,9 +87,11 @@ All tools use the `mcp__figma-desktop__` prefix.
 | Stage | Skill/Agent | Tool used | Purpose |
 |-------|------------|-----------|---------|
 | scan | `skills/scan/SKILL.md` | `get_variable_defs` | Token augmentation — supplements grep-based CSS token extraction with Figma variable definitions (CONN-03) |
-| discover | `agents/design-context-builder.md` | `get_variable_defs` | Decisions pre-population — pre-fills D-XX color/spacing/typography decisions from Figma variables before the interview (CONN-04) |
-| plan | — | — | Not currently used |
-| verify | — | — | Not currently used |
+| discover | `agents/design-context-builder.md` | `get_variable_defs`, `get_design_context` | Decisions pre-population — pre-fills D-XX color/spacing/typography decisions from Figma variables before the interview (CONN-04) |
+| design | `skills/design/SKILL.md` (dispatch only) | — | Offer to spawn design-figma-writer after design-executor completes, when `figma: available` |
+| figma-write | `agents/design-figma-writer.md` | `use_figma` (writes), `get_metadata` + `get_variable_defs` (proposal-time reads) | Write design decisions back to Figma in three modes (annotate / tokenize / mappings) |
+| plan | — | — | Not used |
+| verify | — | — | Not used |
 
 Both scan and discover call `get_variable_defs` with no explicit selection to retrieve all variables in the active Figma file. If no file is open, the call errors and the stage falls back to its non-Figma path.
 
@@ -69,29 +99,31 @@ Both scan and discover call `get_variable_defs` with no explicit selection to re
 
 ## Availability Probe
 
-**Call ToolSearch first — always.** In Claude Code sessions with many MCP servers, `mcp__figma-desktop__*` tools may be in the deferred tool set (not loaded into context at session start). Calling a deferred tool directly fails silently or errors. ToolSearch loads the tools into context and confirms their presence in a single call.
+**Call ToolSearch first — always.** In Claude Code sessions with many MCP servers, `mcp__figma__*` tools may be in the deferred tool set (not loaded into context at session start). Calling a deferred tool directly fails silently or errors. ToolSearch loads the tools into context and confirms their presence in a single call.
+
+One probe covers both reads and writes — the remote MCP is a single server that exposes `get_metadata`, `get_variable_defs`, `get_design_context`, `get_screenshot`, and `use_figma` together. Presence of `get_metadata` implies `use_figma` is available on the same server.
 
 **Figma probe sequence:**
 
 ```
 Step 1 — ToolSearch check:
-  ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
-  → Empty result      → figma: not_configured  (MCP not registered or app not running)
+  ToolSearch({ query: "select:mcp__figma__get_metadata", max_results: 1 })
+  → Empty result      → figma: not_configured  (MCP not registered; OAuth not completed)
   → Non-empty result  → proceed to Step 2
 
 Step 2 — Live tool call:
-  call mcp__figma-desktop__get_metadata
-  → Success           → figma: available
-  → Error             → figma: unavailable
+  call mcp__figma__get_metadata
+  → Success           → figma: available   (reads AND writes both available on this server)
+  → Error             → figma: unavailable (auth expired, rate-limited, or no file open)
 ```
 
-Write the result to `.design/STATE.md <connections>` immediately after probing.
+Write the result to `.design/STATE.md` `<connections>` immediately after probing.
 
 ---
 
 ## Fallback Behavior
 
-When figma is `not_configured` or `unavailable`, stages degrade gracefully — no error is raised.
+When `figma` is `not_configured` or `unavailable`, stages degrade gracefully — no error is raised.
 
 **scan stage:**
 
@@ -106,7 +138,13 @@ When figma is `not_configured` or `unavailable`, stages degrade gracefully — n
 - Populate D-XX decisions via interview only (manual elicitation from the user)
 - DESIGN-CONTEXT.md omits the "Token decisions pre-populated from Figma variables" note
 
-Neither stage appends a `<blocker>` for a missing Figma connection — Figma is an enhancement, not a requirement. If a `must_have` explicitly requires Figma data, THEN append a blocker.
+**design stage + figma-write:**
+
+- `figma: not_configured` or `figma: unavailable` → skip the figma-write dispatch offer entirely (no prompt, no output)
+- `figma: available` → offer opt-in prompt after design-executor completes
+- Standalone `/gdd:figma-write` invocation against `figma: not_configured` → STOP with install note
+
+Stages do not append a `<blocker>` for a missing Figma connection — Figma is an enhancement, not a requirement. If a `must_have` explicitly requires Figma data (reads or writes), THEN append a blocker.
 
 ---
 
@@ -125,11 +163,11 @@ refero: not_configured
 
 | Value | Meaning |
 |-------|---------|
-| `available` | `get_metadata` returned a successful response |
-| `unavailable` | Tool is in the session but errored (app offline, no file open, rate-limited) |
-| `not_configured` | ToolSearch returned empty for `figma-desktop` — MCP not registered |
+| `available` | `get_metadata` returned a successful response; both reads and `use_figma` writes are expected to work |
+| `unavailable` | Tool is in the session but errored (auth expired, no file open, rate-limited) |
+| `not_configured` | ToolSearch returned empty for `mcp__figma__*` — MCP not registered |
 
-The `<connections>` schema is minimal by design. Traceability of which outputs came from Figma is handled via source annotations in DESIGN.md (`source: figma-variables`) and DESIGN-CONTEXT.md ("pre-populated from Figma variables"), not via richer STATE.md fields.
+The `<connections>` schema is minimal by design. Traceability of which outputs came from Figma is handled via source annotations in DESIGN.md (`source: figma-variables`) and DESIGN-CONTEXT.md ("pre-populated from Figma variables"), not via richer STATE.md fields. There is no separate `figma_writer:` key — one remote server, one status.
 
 ---
 
@@ -137,10 +175,14 @@ The `<connections>` schema is minimal by design. Traceability of which outputs c
 
 - **`get_variable_defs` returns resolved values, not alias chains.** If a semantic token (`colors/semantic/brand`) aliases a primitive (`colors/blue/500`), only the resolved hex is returned. When recording variables in DESIGN.md, use the variable NAME alongside the hex: `colors/semantic/brand = #3B82F6`. Add a note: "resolved value — may alias a primitive; verify in Figma if the token layer matters."
 
-- **`get_variable_defs` requires an open Figma file.** If no file is open in the desktop app, the call errors. The probe falls to `unavailable` in this case — the stage skips Figma steps and continues with non-Figma fallbacks.
+- **`get_variable_defs` requires an open Figma file.** If no file is open or none is in the current context, the call errors. The probe falls to `unavailable` in this case — the stage skips Figma steps and continues with non-Figma fallbacks.
 
 - **Multi-mode variables (Light/Dark).** Variables may carry values for multiple modes. When present, extract both: `#3B82F6 (light) / #60A5FA (dark)`. DESIGN.md can note dark-mode token existence in the color section.
 
-- **Deferred-tool loading.** Always call `ToolSearch` before any `mcp__figma-desktop__*` tool invocation. This applies at every stage entry, even if Figma was `available` in a previous run — tool availability can change between sessions.
+- **Deferred-tool loading.** Always call `ToolSearch` before any `mcp__figma__*` tool invocation. This applies at every stage entry, even if Figma was `available` in a previous run — tool availability can change between sessions.
+
+- **All writes require user confirmation.** The proposal→confirm UX in `design-figma-writer` ensures the user reviews all operations before any write is executed. There is no auto-approve mode. See `agents/design-figma-writer.md` for the proposal contract.
+
+- **OAuth re-auth.** If `get_metadata` starts returning auth errors after previously working, the OAuth session expired. Re-running the MCP install command is not required — the session refreshes on the next tool call that returns a `reauth` hint. A clean `claude mcp remove figma && claude mcp add ...` is always safe.
 
-- **Wrong-MCP confusion.** This spec covers `mcp__figma-desktop__*` (official Figma Desktop MCP). The southleft `figma-console-mcp` uses `figma_*` prefix and serves different use cases. Do not mix them. If ToolSearch returns results prefixed `figma_` but not `mcp__figma-desktop__`, the Figma Desktop MCP is still not configured.
+- **No `figma-desktop` fallback.** As of v1.0.7.1 the desktop MCP is no longer a supported read path. If you need offline/no-network reads for some reason, run the pipeline's non-Figma fallbacks (grep-based token extraction, interview-only decisions).

package/connections/magic-patterns.md

@@ -0,0 +1,105 @@
+# Magic Patterns — Connection Specification
+
+This file is the connection specification for Magic Patterns within the get-design-done pipeline. Magic Patterns is a component-generator tool — it generates DS-aware UI components from natural-language descriptions. It integrates via the Magic Patterns Claude connector (no manual setup when enabled) or via a direct API key. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+
+**Path A — Claude connector (preferred):**
+- Magic Patterns Claude connector enabled in your Claude environment
+- No additional setup required
+
+**Path B — API key fallback:**
+- A Magic Patterns account and API key at [magicpatterns.com](https://magicpatterns.com)
+- `MAGIC_PATTERNS_API_KEY` environment variable set
+- MCP server install:
+  ```bash
+  claude mcp add magic-patterns --transport http https://mcp.magicpatterns.com/sse \
+    -e MAGIC_PATTERNS_API_KEY=$MAGIC_PATTERNS_API_KEY
+  ```
+
+### Verification
+
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+```
+
+Non-empty results including `magic_patterns_generate` → Claude connector available (Path A).
+Empty → install Path B and restart Claude Code session.
+
+---
+
+## Probe Pattern
+
+Magic Patterns uses a two-path probe. Check Claude connector first; fall back to API key path.
+
+```
+ToolSearch({ query: "mcp__magic_patterns", max_results: 5 })
+→ Non-empty  → magic-patterns: available (Claude connector)
+→ Empty      → check MAGIC_PATTERNS_API_KEY env var
+               set → magic-patterns: available (API key path)
+               unset → magic-patterns: not_configured
+```
+
+Write result to STATE.md `<connections>`: `magic-patterns: <status>`
+
+Fallback: when `not_configured`, the design stage skips Magic Patterns and falls back to 21st.dev (if available) or manual component build.
+
+---
+
+## Magic Patterns Tools
+
+| Tool | Stage | Purpose |
+|------|-------|---------|
+| `magic_patterns_generate` | design | Generate component from description; returns `{ code, preview_url, component_id }` |
+| `magic_patterns_annotate` | design | Post DESIGN-DEBT findings back to a component by ID |
+| `magic_patterns_regenerate` | design | Roundtrip: regenerate with updated description |
+
+### `magic_patterns_generate` parameters
+
+| Parameter | Values | Notes |
+|-----------|--------|-------|
+| `description` | string | Natural-language component spec |
+| `design_system` | `"shadcn" \| "tailwind" \| "mantine" \| "chakra"` | Auto-detected from project in explore stage |
+| `quality_mode` | `"fast" \| "best"` | `fast` for explore iterations; `best` for final design stage output |
+
+---
+
+## Pipeline Integration
+
+| Stage | What Magic Patterns provides |
+|-------|------------------------------|
+| explore | DS detection → STATE.md `<design_system>` block for generator targeting |
+| design | `magic_patterns_generate(description, design_system, quality_mode: "best")` → component source + `preview_url` |
+| verify | `preview_url` from generate response → feeds Phase 8 Preview `? VISUAL` check |
+| design | `magic_patterns_annotate(component_id, feedback)` → roundtrip mode; post DESIGN-DEBT notes back |
+
+### Design-System Auto-Detection
+
+Before invoking `magic_patterns_generate`, the explore stage detects the project's active design system (see `agents/design-context-builder.md` Step 0C):
+
+1. Check `gdd.config.json` (if present): read `designSystem` field → use directly if set.
+2. Scan `package.json` dependencies:
+   - `@shadcn/ui` or `shadcn` present → `"shadcn"`
+   - `@mantine/core` or `@mantine/hooks` present → `"mantine"`
+   - `@chakra-ui/react` present → `"chakra"`
+   - `tailwindcss` present → `"tailwind"`
+3. Default: `"tailwind"`
+
+Write result to STATE.md `<design_system>` block.
+
+### Preview Integration
+
+`magic_patterns_generate` returns `preview_url`. The design-component-generator agent writes this URL to STATE.md `<generator>` block. The verify stage's `? VISUAL` check reads `preview_url` from STATE.md and opens it in Phase 8 Preview for visual comparison.
+
+---
+
+## Fallback Behavior
+
+When `magic-patterns: not_configured`:
+- Print: `Magic Patterns not configured — component generator skipped.`
+- Falls back to 21st.dev if `21st-dev: available`.
+- If both not configured, design stage proceeds with manual component build.

package/connections/paper-design.md

@@ -0,0 +1,137 @@
+# paper.design MCP — Connection Specification
+
+This file is the connection specification for paper.design within the get-design-done pipeline. paper.design is a canvas tool — it treats the design canvas as both source AND destination, enabling a full canvas→code→verify→canvas round-trip. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+- A paper.design account
+- paper.design MCP server registered in your Claude Code session
+
+### Install command (Claude Code)
+
+```bash
+claude mcp add paper-design --transport http https://mcp.paper.design/sse
+```
+
+After running this command, restart the Claude Code session.
+
+### Verification
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+```
+
+Expect non-empty results including `mcp__paper-design__get_selection` or similar. If empty, re-run the install command above and restart the Claude Code session.
+
+### Budget
+
+paper.design **free tier**: 100 MCP calls/week. Pro tier: 1M calls/week. The pipeline tracks `budget_used` in STATE.md `<connections>` and warns at 90 calls.
+
+---
+
+## Probe Pattern
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+→ Empty       → paper-design: not_configured (skip all paper.design steps)
+→ Non-empty   → proceed to live call
+
+call mcp__paper-design__get_selection
+→ Success     → paper-design: available
+→ Error       → paper-design: unavailable
+```
+
+Write result to STATE.md `<connections>`: `paper-design: <status>`
+
+Also write initial budget state:
+```xml
+<connections>
+paper-design: available | budget_used: 0 | budget_limit: 100
+</connections>
+```
+
+---
+
+## paper.design MCP Tools
+
+| Tool | Stage | Purpose |
+|------|-------|---------|
+| `mcp__paper-design__get_selection` | explore | JSON of selected canvas elements (id, type, name, bounds) |
+| `mcp__paper-design__get_jsx` | explore | React JSX string of selected component tree |
+| `mcp__paper-design__get_computed_styles` | explore | CSS computed styles for current selection |
+| `mcp__paper-design__get_screenshot` | verify | Base64 PNG screenshot of selected canvas element |
+| `mcp__paper-design__add_comment` | design | Add annotation comment to a canvas node |
+| `mcp__paper-design__update_styles` | design | Update CSS properties of a canvas node |
+| `mcp__paper-design__set_text_content` | design | Write text content to a canvas text layer |
+| `mcp__paper-design__write_html` | design | Write HTML snippet to a canvas layer |
+
+---
+
+## Pipeline Integration
+
+| Stage | What paper.design provides |
+|-------|---------------------------|
+| explore | Canvas read: `get_selection` (node list), `get_jsx` (React component tree), `get_computed_styles` (CSS values) → merged into DESIGN-CONTEXT.md |
+| design | `design-paper-writer` agent: annotate / tokenize / roundtrip modes via write tools |
+| verify | `get_screenshot` for components flagged `? VISUAL` — element-scoped (complements route-scoped Preview screenshots) |
+
+### Canvas Read (Explore Stage)
+
+The explore stage context-builder reads the paper.design canvas via:
+
+1. `mcp__paper-design__get_selection` — get selected element IDs and names
+2. `mcp__paper-design__get_jsx` — get full React component tree of selection
+3. `mcp__paper-design__get_computed_styles` — get computed CSS values
+
+Results are merged into DESIGN-CONTEXT.md as a `<canvas_sources>` block alongside Figma variables, Refero refs, and other sources.
+
+### Write-Back (Design Stage)
+
+The `design-paper-writer` agent handles write-back in three modes:
+- **annotate** — add design-decision comments to canvas nodes (`add_comment`)
+- **tokenize** — sync CSS token values to paper.design node styles (`update_styles`)
+- **roundtrip** — write implementation status back as text/HTML layers (`set_text_content`, `write_html`)
+
+All writes require user confirmation via proposal→confirm flow. See `agents/design-paper-writer.md`.
+
+### Screenshot Verification (Verify Stage)
+
+`mcp__paper-design__get_screenshot(node_id)` captures a PNG of a specific canvas element.
+
+- Canvas-element-scoped (NOT route-scoped like Phase 8 Preview)
+- Both are complementary: paper.design → canvas component view; Preview → rendered browser route
+- Screenshots saved to `.design/screenshots/paper-<component>-<date>.png`
+
+---
+
+## Budget Tracking
+
+After every write tool call, increment `budget_used` in STATE.md:
+
+```xml
+<connections>
+paper-design: available | budget_used: 12 | budget_limit: 100
+</connections>
+```
+
+Warn when `budget_used >= 90`: `Warning: paper.design budget at 90/100 calls this week.`
+
+Read tools (`get_selection`, `get_jsx`, `get_computed_styles`, `get_screenshot`) also consume budget — track them as well.
+
+---
+
+## Fallback Behavior
+
+When `paper-design: not_configured`:
+- Skip all paper.design steps. Print: `paper.design not configured — canvas integration skipped.`
+- Explore stage proceeds with code-only context (grep + Figma + Storybook if available).
+- Verify stage uses Preview screenshots only (no canvas-element screenshots).
+- Design stage does not offer paper-writer.
+
+When `paper-design: unavailable`:
+- Update STATE.md to `paper-design: unavailable`.
+- Print: `paper.design unavailable — check MCP connection and try again.`
+- Degrade as above.