@hegemonart/get-design-done 1.14.3 → 1.14.5

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.14.5] — 2026-04-23
+
+### Fixed — Preview MCP silently skipped in verify even when available ([#19](https://github.com/hegemonart/get-design-done/issues/19))
+
+`design-verifier` was spawned with `tools: Read, Write, Bash, Grep, Glob` only. The verify skill's orchestrator-level probe correctly classified the session as `preview: available` and wrote it to `STATE.md`, but the subagent's tool allowlist blocked every `mcp__Claude_Preview__*` call, causing Phase 4B to silently skip screenshot capture and leave all `? VISUAL` heuristic flags unresolved.
+
+**Fix:** Added six Preview MCP tools to `design-verifier`'s `tools:` frontmatter — `preview_list`, `preview_navigate`, `preview_screenshot`, `preview_eval`, `preview_snapshot`, `preview_inspect` — so Phase 4B runs in the same permission context as the probe.
+
+**Probe hardening:** The availability probe in `connections/preview.md` and `skills/verify/SKILL.md` now distinguishes three failure modes instead of collapsing them to `not_configured`/`unavailable`:
+
+| New status | Meaning |
+|---|---|
+| `not_loaded` | ToolSearch empty — MCP not registered in this session |
+| `permission_denied` | ToolSearch found the tool but the live call was rejected by the tool permission layer |
+| `unreachable` | Tool loaded but live call errored for a non-permission reason (no dev server, timeout) |
+
+The Phase 4B gate in `design-verifier` skips on all non-`available` statuses and emits a targeted message on `permission_denied` to aid diagnosis.
+
+`connections/preview.md` now documents the **execution-context requirement**: the probe and the `preview_*` calls must run in the same context; a parent-session probe does not transfer to a spawned subagent.
+
+---
+
+## [1.14.4] — 2026-04-20
+
+### Fixed — Figma MCP install URL was stale
+
+The docs everywhere referenced the legacy `https://mcp.figma.com/v1/sse` endpoint. Users following the current Claude Code Figma MCP flow hit "Failed to connect" because Figma has since moved the server to `https://mcp.figma.com/mcp` (Streamable HTTP). Every skill, agent, and reference doc that prints Figma install steps now uses the current URL, and the migration note tells existing users how to remove a stale registration.
+
+### Changed — Variant-agnostic Figma MCP probe
+
+- The `mcp__figma__` prefix is no longer hardcoded. The probe matches any server whose name fits `/figma/i` — remote `figma`, `Figma`, local `figma-desktop`, UUID-prefixed instances — via keyword `ToolSearch`, applies a tiebreaker (both-sets > reads-only > canonical `figma` > alphabetical), and writes the resolved `prefix=` and `writes=` capability flags to `.design/STATE.md <connections>`. Consumer skills and agents read the resolved prefix from `STATE.md` instead of hardcoding it.
+- Added preferred install path: `claude plugin install figma@claude-plugins-official` (bundles the MCP + Figma's agent skills). Manual `claude mcp add` remains supported.
+- Tool table extended with `generate_figma_design`, `search_design_system`, `create_new_file`, `whoami`, `generate_diagram`, `get_figjam`, `get_code_connect_suggestions`, `send_code_connect_mappings` — split by reads (remote + desktop) vs writes (remote-only).
+- `design-figma-writer` now STOPs early with a clear install message when only a reads-only variant (e.g. `figma-desktop`) is detected.
+- `tests/semver-compare.test.cjs` — registered `1.14.4` as a recognized off-cadence version.
+
+Cherry-picked from `c11cd7b` on `claude/upbeat-fermi-199627` — the Figma MCP fix that was authored before v1.14.2 but never merged to main, so every install doc was printing the outdated URL until this release.
+
+---
+
 ## [1.14.3] — 2026-04-20
 
 ### Added — `npx @hegemonart/get-design-done` installer

package/README.md

@@ -329,7 +329,7 @@ Every connection is optional. The pipeline degrades gracefully — a grep-based
 
 | Connection | Type | Purpose |
 |-----------|------|---------|
-| Figma | MCP (`mcp__figma__*`, remote) | Token extraction, design context pre-population, write-back via `use_figma` (annotate, tokenize, Code Connect) |
+| Figma | MCP (auto-detects any `/figma/i` server — remote or desktop) | Token extraction, design context pre-population, write-back via `use_figma` (remote only; annotate, tokenize, Code Connect) |
 | Refero | MCP (`mcp__refero__*`) | Reference design search during exploration |
 | Pinterest | MCP (`mcp__mcp-pinterest__*`) | Visual inspiration boards alongside Refero |
 | Preview (Playwright) | MCP (`mcp__Claude_Preview__*`) | Live page screenshots for visual verification |
@@ -603,13 +603,23 @@ All connections are optional — the pipeline degrades gracefully when any conne
 
 ### Figma MCP (reads + writes)
 
-One remote MCP covers both reads and writes. When active, `explore` reads Figma variables and pre-populates design decisions from your file, and `design-figma-writer` writes decisions back via `use_figma` — annotates frames, tokenizes local styles, registers Code Connect mappings. Proposal → confirm discipline with `--dry-run` and `--confirm-shared` guards. Falls back to code-only analysis when the MCP is not configured. One install command unlocks both:
+The pipeline auto-detects any Figma MCP variant — remote (reads + writes) or desktop (reads only). When active, `explore` reads Figma variables and pre-populates design decisions from your file, and `design-figma-writer` writes decisions back via `use_figma` — annotates frames, tokenizes local styles, registers Code Connect mappings. Proposal → confirm discipline with `--dry-run` and `--confirm-shared` guards. Falls back to code-only analysis when no Figma MCP is configured.
+
+**Preferred install (Claude Code plugin — bundles MCP + Figma's official skills):**
+
+```
+claude plugin install figma@claude-plugins-official
+```
+
+**Manual install (remote MCP — reads + writes):**
 
 ```
-claude mcp add figma --transport http https://mcp.figma.com/v1/sse
+claude mcp add --transport http figma https://mcp.figma.com/mcp
 ```
 
-Setup: [`connections/figma.md`](connections/figma.md). If you previously installed the local `figma-desktop` MCP, you can remove it — its read tools are now exposed on the remote server.
+**Desktop MCP (reads only):** optionally enabled via the Figma desktop app's Dev Mode. Useful when writes are not needed. Register under server name `figma-desktop` — the probe auto-detects it.
+
+Setup: [`connections/figma.md`](connections/figma.md). If you previously registered the remote MCP with the legacy URL `https://mcp.figma.com/v1/sse`, remove and re-add with the current URL `https://mcp.figma.com/mcp` (Streamable HTTP).
 
 ### Refero MCP
 

package/README.zh-CN.md

@@ -29,7 +29,7 @@ npx @hegemonart/get-design-done@latest
 
 <br>
 
-[为什么做这个](#为什么做这个) · [工作流程](#工作流程) · [画布工具](#ai-native-画布工具) · [组件生成器](#组件生成器) · [命令列表](#命令列表) · [接入的工具](#接入的工具)
+[为什么做这个](#为什么做这个) · [快速开始](#快速开始) · [工作流程](#工作流程) · [命令列表](#命令列表) · [配置](#配置) · [故障排查](#故障排查)
 
 </div>
 

package/agents/design-context-builder.md

@@ -1,7 +1,7 @@
 ---
 name: design-context-builder
 description: Detects existing design system state via grep/glob, runs discovery interview asking ONLY unanswered questions, produces .design/DESIGN-CONTEXT.md. Spawned by the discover stage.
-tools: Read, Write, Bash, Grep, Glob, mcp__figma__get_variable_defs, mcp__figma__get_metadata, mcp__refero__search
+tools: Read, Write, Bash, Grep, Glob, mcp__figma__get_variable_defs, mcp__figma__get_metadata, mcp__figma-desktop__get_variable_defs, mcp__figma-desktop__get_metadata, mcp__Figma__get_variable_defs, mcp__Figma__get_metadata, mcp__refero__search
 required_reading:
   - connections/storybook.md
 color: blue
@@ -47,13 +47,15 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
 
 ### If `figma: available`
 
+Read the resolved tool prefix from the STATE.md `<connections>` line (e.g., `figma: available (prefix=mcp__figma__, writes=true)` → prefix is `mcp__figma__`). Call this `{P}`.
+
 **ToolSearch first.** Figma tools may be in the deferred tool set — calling them without a prior ToolSearch fails silently.
 
 ```
-ToolSearch({ query: "select:mcp__figma__get_variable_defs", max_results: 1 })
+ToolSearch({ query: "figma get_variable_defs", max_results: 5 })
 ```
 
-Then call `mcp__figma__get_variable_defs` (no arguments — returns all variables in the active Figma file).
+Then call `{P}get_variable_defs` (no arguments — returns all variables in the active Figma file).
 
 > If `get_variable_defs` errors (most commonly because no Figma file is open): skip Step 0 entirely AND update `.design/STATE.md` `<connections>` to `figma: unavailable`. Proceed to Step 1 with no pre-populated decisions.
 

package/agents/design-discussant.md

@@ -30,7 +30,7 @@ The spawning prompt supplies `<required_reading>`. Read every listed file before
 
 ## Step 0 — Context pre-load (Figma only, optional)
 
-If `<connections>` in STATE.md shows `figma: available`, `ToolSearch({ query: "select:mcp__figma__get_variable_defs", max_results: 1 })` and call `mcp__figma__get_variable_defs`. For each returned variable, draft a *tentative* D-XX decision (mark "tentative — confirm with user"). Silently skip on any error. Do NOT grep the codebase.
+If `<connections>` in STATE.md shows `figma: available`, read the `prefix=` field on that line (call it `{P}`). Then `ToolSearch({ query: "figma get_variable_defs", max_results: 5 })` and call `{P}get_variable_defs`. For each returned variable, draft a *tentative* D-XX decision (mark "tentative — confirm with user"). Silently skip on any error. Do NOT grep the codebase.
 
 ## Step 1 — Mode dispatch
 

package/agents/design-figma-writer.md

@@ -1,7 +1,7 @@
 ---
 name: design-figma-writer
 description: Writes design decisions back to Figma — annotations, token bindings, Code Connect mappings, and implementation-status write-back. Operates in proposal→confirm mode by default. Accepts --dry-run (emit proposal without executing) and --confirm-shared (required for writes to team library components).
-tools: Read, Write, Bash, Grep, Glob, mcp__figma__use_figma, mcp__figma__get_variable_defs, mcp__figma__get_metadata
+tools: Read, Write, Bash, Grep, Glob, {P}use_figma, mcp__figma__get_variable_defs, mcp__figma__get_metadata, mcp__Figma__use_figma, mcp__Figma__get_variable_defs, mcp__Figma__get_metadata
 color: purple
 model: inherit
 default-tier: sonnet
@@ -11,7 +11,7 @@ parallel-safe: never
 typical-duration-seconds: 120
 reads-only: false
 writes:
-  - "Figma file (via mcp__figma__use_figma) — annotations, token bindings, Code Connect mappings"
+  - "Figma file (via {resolved_prefix}use_figma — remote MCP only) — annotations, token bindings, Code Connect mappings"
 ---
 
 @reference/shared-preamble.md
@@ -26,15 +26,17 @@ You are design-figma-writer. You write design decisions from `.design/DESIGN-CON
 
 ## Step 0 — Remote MCP Probe
 
-Run this probe at agent entry before any other action:
+Writes require a remote Figma MCP variant (`use_figma` is remote-only). Run this probe at agent entry before any other action:
 
 ```
-ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
-→ Empty result  → Write to output: "Figma remote MCP not available. Register it with: claude mcp add figma --transport http https://mcp.figma.com/v1/sse  Then restart the session." → STOP (do not proceed).
-→ Non-empty     → proceed to Step 1
+ToolSearch({ query: "figma use_figma", max_results: 10 })
+
+Parse tool names matching /^mcp__([^_]*figma[^_]*)__use_figma$/i → write-capable prefix set.
+  Empty → Write to output: "Figma remote MCP not available (writes require the remote server, not desktop). Preferred install: `claude plugin install figma@claude-plugins-official`. Manual: `claude mcp add --transport http figma https://mcp.figma.com/mcp`. Then restart the session." → STOP.
+  One+  → pick prefix via tiebreaker (1) `figma` > others (2) non-`figma-desktop` (3) alphabetical. Record resolved prefix for use in Steps 1–5.
 ```
 
-Note: `mcp__figma__use_figma` is the remote Figma MCP (registered as server `figma`). Reads (`mcp__figma__get_metadata`, `mcp__figma__get_variable_defs`) live on the same server. As of v1.0.7.1, there is no separate read-only desktop MCP — the remote MCP is the single supported Figma connection.
+Note: the remote Figma MCP (canonical server name `figma`, URL `https://mcp.figma.com/mcp`) exposes both reads (`get_metadata`, `get_variable_defs`) and writes (`use_figma`) on the same server. The desktop MCP (`figma-desktop`) exposes reads only and cannot be used for writes — this agent STOPs if only a desktop variant is detected.
 
 ---
 
@@ -72,12 +74,11 @@ Read `.design/DESIGN-CONTEXT.md`. Extract the relevant data for the selected mod
 - For `tokenize`: color/spacing/type literal values that could map to Figma variables — look for hex values, spacing scales, and typography sizes in the decisions section
 - For `mappings`: component names and their source file paths — look for component listings, file paths, and implementation references
 
-Also read the active Figma file structure using the remote MCP (reads and writes share the same server):
+Also read the active Figma file structure. Use the resolved prefix from Step 0 (written here as `{P}` for short — e.g., `mcp__figma__`). Reads and writes share the same server:
 
 ```
-ToolSearch({ query: "select:mcp__figma__get_metadata,mcp__figma__get_variable_defs", max_results: 2 })
-mcp__figma__get_metadata()       // lightweight layer outline
-mcp__figma__get_variable_defs()  // for tokenize mode — variable names and values
+{P}get_metadata()       // lightweight layer outline
+{P}get_variable_defs()  // for tokenize mode — variable names and values
 ```
 
 If `get_metadata` errors (no file accessible), write: "No Figma file is accessible. Open the target file in Figma and retry." and STOP.
@@ -157,12 +158,12 @@ Wait for user response. If response is not "yes", STOP with "Cancelled."
 
 ## Step 5 — Execute Writes
 
-For each operation in the proposal, call `mcp__figma__use_figma` with the appropriate operation payload.
+For each operation in the proposal, call `{P}use_figma` with the appropriate operation payload.
 
 For `annotate`:
 
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "add_comment",
   layerId: "<layer-id>",
   message: "<annotation text>"
@@ -172,7 +173,7 @@ mcp__figma__use_figma({
 For `tokenize`:
 
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "set_variable_binding",
   nodeId: "<node-id>",
   field: "fills[0].color",
@@ -183,7 +184,7 @@ mcp__figma__use_figma({
 For `mappings`:
 
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "set_code_connect",
   componentId: "<component-id>",
   filePath: "<relative-path>",
@@ -266,7 +267,7 @@ If user says "edit": allow user to modify proposal, then re-confirm.
 
 For each confirmed annotation:
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "add_comment",
   layerId: "<frame-node-id>",
   message: "Implementation: <status> — verified <ISO date>"
@@ -277,7 +278,7 @@ mcp__figma__use_figma({
 
 For each confirmed Code Connect mapping:
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "set_code_connect",
   componentId: "<component-node-id>",
   filePath: "<relative-code-path>",
@@ -287,7 +288,7 @@ mcp__figma__use_figma({
 
 After all individual mappings, send the batch:
 ```javascript
-mcp__figma__use_figma({
+{P}use_figma({
   operation: "send_code_connect_mappings"
 })
 ```

package/agents/design-verifier.md

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

package/agents/token-mapper.md

@@ -63,7 +63,7 @@ grep -rEn "box-shadow\s*:|shadow-(sm|md|lg|xl|2xl)" src/ --include="*.css" --inc
 
 ### Figma augmentation
 
-If STATE.md `<connections>` has `figma: available`, call `mcp__figma__get_variable_defs` to augment with named Figma variables.
+If STATE.md `<connections>` has `figma: available`, read the `prefix=` field on that line and call `{prefix}get_variable_defs` to augment with named Figma variables. Works with both remote (`mcp__figma__`) and desktop (`mcp__figma-desktop__`) variants — `get_variable_defs` is available on both.
 
 ## Output Format — `.design/map/tokens.md`
 

package/connections/connections.md

@@ -2,13 +2,15 @@
 
 This directory contains connection specifications for external tools and MCPs that the get-design-done pipeline integrates with. Each connection has its own spec file. This file is the index.
 
+**Getting started:** run `/gdd:connections` for the interactive onboarding wizard — it probes all 12 connections, recommends setup based on your project type, and walks you through installing each one (auto-run for reversible MCP adds, copy-command for everything else). You can also run `/gdd:connections list` for a read-only status check or `/gdd:connections <name>` to jump to a single connection's setup.
+
 ---
 
 ## Active Connections
 
 | Connection | Status | Spec File | Notes |
 |-----------|--------|-----------|-------|
-| Figma | Active | [`connections/figma.md`](connections/figma.md) | Uses `mcp__figma__*` tools (remote Figma MCP; reads + writes) |
+| Figma | Active | [`connections/figma.md`](connections/figma.md) | Auto-detects any Figma MCP variant (remote reads+writes, desktop reads-only); prefix resolved at probe time |
 | 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` |
@@ -83,18 +85,30 @@ 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.
+The probe is variant-agnostic — it resolves any server whose prefix matches `/figma/i` (e.g., `figma`, `Figma`, `figma-desktop`, UUID-prefixed remote instances) and records the resolved prefix plus writes capability. Remote MCP exposes `use_figma` (writes-capable). Desktop MCP exposes reads only.
 
 ```
-Step A1 — ToolSearch check:
-  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__get_metadata
-  → Success           → figma: available   (reads AND use_figma writes both available)
-  → Error             → figma: unavailable (skip all Figma steps)
+Step A1 — Keyword ToolSearch:
+  ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
+
+  Parse tool names for:
+    /^mcp__([^_]*figma[^_]*)__get_metadata$/i  → read-capable prefix set
+    /^mcp__([^_]*figma[^_]*)__use_figma$/i     → write-capable prefix set
+
+  Empty read set → figma: not_configured (skip all Figma steps)
+  One+ matches  → proceed to Step A2
+
+Step A2 — Tiebreaker selection:
+  Preference order when multiple read prefixes match:
+    (1) both-sets > reads-only
+    (2) `figma` > others
+    (3) non-`figma-desktop` > desktop
+    (4) alphabetical
+
+Step A3 — Live tool call on resolved prefix:
+  call mcp__<prefix>__get_metadata
+  → Success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
+  → Error   → figma: unavailable (skip all Figma steps)
 
 Write figma status to STATE.md <connections>.
 ```

package/connections/figma.md

@@ -1,6 +1,11 @@
 # Figma MCP — Connection Specification
 
-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.
+This file is the connection specification for the Figma MCP within the get-design-done pipeline. Figma publishes two MCP variants, both officially supported:
+
+- **Remote MCP** (`https://mcp.figma.com/mcp`) — full read + write. Exposes read tools (`get_metadata`, `get_design_context`, `get_variable_defs`, `get_screenshot`, `get_figjam`, `search_design_system`) and remote-only write tools (`use_figma`, `generate_figma_design`, `create_new_file`, `whoami`).
+- **Desktop MCP** (local HTTP, served by the Figma desktop app in Dev Mode) — reads only. Exposes the same read tools but not `use_figma`. Useful for offline/no-network reads.
+
+The pipeline auto-detects any server whose name matches `/figma/i` (e.g., `figma`, `Figma`, `figma-desktop`, UUID-prefixed instances) and records the resolved prefix plus `writes` capability in `STATE.md`. See `connections/connections.md` for the full connection index and capability matrix.
 
 ---
 
@@ -9,29 +14,46 @@ This file is the connection specification for the Figma MCP (remote, read + writ
 **Prerequisites:**
 
 - 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.
+- Figma file access for any file you intend to read or write.
+- (Optional for desktop variant) Figma desktop app running with the target file open in Dev Mode.
+
+### Option A — Claude Code plugin (preferred)
+
+Anthropic publishes an official Figma plugin that bundles the MCP configuration plus Figma's agent skills:
+
+```
+claude plugin install figma@claude-plugins-official
+```
+
+Restart the Claude Code session after install. OAuth prompts on first tool call.
 
-**Install command (Claude Code):**
+### Option B — Manual remote MCP install
 
 ```
-claude mcp add figma --transport http https://mcp.figma.com/v1/sse
+claude mcp add --transport http figma https://mcp.figma.com/mcp
 ```
 
-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.
+Restart the session. OAuth prompts on first tool call. One install unlocks both reads and writes.
+
+> **Note:** The legacy server URL `https://mcp.figma.com/v1/sse` is superseded. Current canonical URL is `https://mcp.figma.com/mcp` (Streamable HTTP). Remove any prior registration using the old URL: `claude mcp remove figma` then re-run the install command above.
+
+### Option C — Desktop MCP (reads only)
+
+The Figma desktop app exposes a local MCP server on Dev Mode. This path is useful when writes are not needed and network access is restricted. Desktop MCP is typically registered under the server name `figma-desktop` — follow the Figma desktop app's Dev Mode instructions for your Figma version.
 
 **Verification:**
 
 After session restart, run:
 
 ```
-ToolSearch({ query: "select:mcp__figma__get_metadata,mcp__figma__use_figma", max_results: 2 })
+ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
 ```
 
-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.
+The probe accepts any server prefix matching `/figma/i`. At least one result with a `get_metadata` tool is required for reads. A matching `use_figma` tool is required for writes (remote only).
 
-**Migration from the legacy dual-MCP setup:**
+**Migration from older plugin versions:**
 
-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:
+Plugin versions before v1.0.7.1 used two separate Figma MCPs — `figma-desktop` (reads) and `figma` (writes). As of v1.0.7.1, the remote MCP exposes full read parity, so a single remote install is sufficient for most users. The desktop MCP remains supported as a reads-only fallback and is auto-detected alongside remote. If you only want the remote path, remove desktop:
 
 ```
 claude mcp remove figma-desktop
@@ -43,26 +65,45 @@ No data is lost — the remote MCP reads the same Figma files.
 
 ## Tools
 
-All tools use the `mcp__figma__` prefix (remote MCP).
-
-| 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 |
+Tool names take the form `mcp__<prefix>__<tool>` where `<prefix>` is the resolved server name from the probe (commonly `figma` for remote or `figma-desktop` for local). The pipeline discovers the prefix at runtime — see **Availability Probe** below. The `mcp__figma__` examples shown here assume a server registered as `figma`.
+
+**Reads (available on remote and desktop):**
+
+| Tool | Returns | Pipeline use |
+|------|---------|--------------|
+| `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` | 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` | Structured React+Tailwind component tree of the current Figma selection | **In scope (secondary)** — discover: existing design decisions for established Figma systems |
+| `get_screenshot` | Screenshot image of the selected Figma layer or frame | **In scope (opt-in)** — visual reference capture for discovery; not invoked by default |
+| `get_figjam` | FigJam diagram metadata (XML) plus node screenshots | Out of scope this phase (not part of the design pipeline) |
+| `search_design_system` | Matching components, variables, and styles across connected libraries for a text query | Out of scope this phase (reserved for future Code Connect work) |
+| `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` | Adds Code Connect mapping entries | Out of scope this phase (reserved for future Code Connect work) |
+| `get_code_connect_suggestions` | Suggested Code Connect mappings between Figma and code components | Out of scope this phase |
+| `send_code_connect_mappings` | Confirms and finalizes Code Connect mappings | Out of scope this phase |
+| `create_design_system_rules` | Generates rule files for design system alignment during code generation | Out of scope this phase |
+
+**Writes (remote only):**
+
+| Tool | Returns | Pipeline use |
+|------|---------|--------------|
+| `use_figma` | Write operation result | **In scope** — figma-write: all three modes (annotate, tokenize, mappings) |
+| `generate_figma_design` | Imports/converts a web page into Figma design layers | Out of scope this phase |
+| `generate_diagram` | Generates a FigJam diagram from Mermaid syntax | Out of scope this phase |
+| `create_new_file` | Creates a new blank Figma Design or FigJam file | Out of scope this phase |
+| `whoami` | Authenticated user identity, plans, and seat types | Optional — useful for surfacing Dev seat status before a write |
 
 `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.
 
+**Remote-only tools** (`use_figma`, `generate_figma_design`, `create_new_file`, `whoami`, `generate_diagram`): absent from the desktop MCP. When the probe resolves to a desktop-only prefix, stages that require these tools either STOP (figma-write) or fall back silently.
+
 ---
 
 ## 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.
+`use_figma` is the single write tool and is **remote only**. 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.
+
+If the resolved probe prefix points to a desktop variant (no `use_figma`), figma-write STOPs early and instructs the user to register the remote MCP. No partial writes, no silent failures.
 
 ### Three Modes
 
@@ -99,22 +140,34 @@ 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__*` 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, 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.
+The probe is **variant-agnostic**: it accepts any server prefix matching `/figma/i` (e.g., `figma`, `Figma`, `figma-desktop`, `3860b164-...` UUID-prefixed remote instances) and records both the resolved prefix and the writes capability.
 
 **Figma probe sequence:**
 
 ```
-Step 1 — ToolSearch check:
-  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__get_metadata
-  → Success           → figma: available   (reads AND writes both available on this server)
-  → Error             → figma: unavailable (auth expired, rate-limited, or no file open)
+Step 1 — Keyword ToolSearch:
+  ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
+
+  Parse results for tool names matching:
+    - /^mcp__([^_]*figma[^_]*)__get_metadata$/i  → captures read-capable prefixes
+    - /^mcp__([^_]*figma[^_]*)__use_figma$/i     → captures write-capable prefixes
+
+  No read match       → figma: not_configured (no Figma MCP registered)
+  One or more matches → proceed to Step 2
+
+Step 2 — Tiebreaker selection:
+  Preference order when multiple prefixes match:
+    1. Prefer prefixes that appear in BOTH the read set and the write set
+    2. Among remaining prefixes, prefer `figma` (canonical remote server name)
+    3. Among remaining prefixes, prefer non-`figma-desktop`
+    4. Alphabetical
+
+Step 3 — Live tool call on resolved prefix:
+  call mcp__<prefix>__get_metadata
+  → Success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
+  → Error   → figma: unavailable (auth expired, rate-limited, or no file open)
 ```
 
 Write the result to `.design/STATE.md` `<connections>` immediately after probing.
@@ -150,24 +203,35 @@ Stages do not append a `<blocker>` for a missing Figma connection — Figma is a
 
 ## STATE.md Integration
 
-Every stage writes its probe result to `.design/STATE.md` under the `<connections>` section:
+Every stage writes its probe result to `.design/STATE.md` under the `<connections>` section. The format carries three fields for Figma: status, resolved tool prefix, and writes capability.
 
 ```xml
 <connections>
-figma: available
+figma: available (prefix=mcp__figma__, writes=true)
 refero: not_configured
 </connections>
 ```
 
+Other examples:
+
+```
+figma: available (prefix=mcp__figma-desktop__, writes=false)
+figma: available (prefix=mcp__Figma__, writes=false)
+figma: unavailable
+figma: not_configured
+```
+
 **Status values:**
 
 | Value | Meaning |
 |-------|---------|
-| `available` | `get_metadata` returned a successful response; both reads and `use_figma` writes are expected to work |
+| `available` | A matching `get_metadata` tool was resolved and the live call succeeded. The `writes=` flag indicates whether `use_figma` is also present on the same prefix. |
 | `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 |
+| `not_configured` | No server matching `/figma/i` exposes `get_metadata` — MCP not registered |
+
+**Consumer contract.** Agents that call Figma tools MUST read the resolved prefix from STATE.md and construct tool names dynamically (`{prefix}get_variable_defs`, `{prefix}use_figma`), rather than hardcoding `mcp__figma__`. Agents that need writes MUST additionally check `writes=true` and STOP early with a clear message when false.
 
-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.
+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.
 
 ---
 
@@ -179,10 +243,10 @@ The `<connections>` schema is minimal by design. Traceability of which outputs c
 
 - **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__*` 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 Figma tool invocation. This applies at every stage entry, even if Figma was `available` in a previous run — tool availability and the resolved prefix 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.
 
-- **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).
+- **Desktop MCP reads-only.** The desktop MCP (typically `figma-desktop`) exposes read tools only. It is auto-detected by the probe and is a supported fallback when writes are not needed. Stages that require writes (figma-write) STOP with an instruction to register the remote MCP.