@hegemonart/get-design-done 1.14.2 → 1.14.4

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/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

@@ -8,7 +8,7 @@ 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__*` 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 +83,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.

package/package.json

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

package/reference/schemas/plugin.schema.json

@@ -14,8 +14,7 @@
     "repository",
     "license",
     "keywords",
-    "skills",
-    "hooks"
+    "skills"
   ],
   "properties": {
     "name": {

package/scripts/install.cjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+'use strict';
+
+// npx @hegemonart/get-design-done
+// One-command installer for the get-design-done Claude Code plugin.
+//
+// Registers the github.com/hegemonart/get-design-done marketplace and enables
+// the plugin in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json).
+// Claude Code fetches the plugin payload from the marketplace on next launch.
+//
+// Usage:
+//   npx @hegemonart/get-design-done           # install
+//   npx @hegemonart/get-design-done --dry-run # show what would change
+//   npx @hegemonart/get-design-done --help
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const REPO = 'hegemonart/get-design-done';
+const MARKETPLACE_NAME = 'get-design-done';
+const PLUGIN_NAME = 'get-design-done';
+const ENABLED_KEY = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+
+const args = new Set(process.argv.slice(2));
+
+if (args.has('--help') || args.has('-h')) {
+  process.stdout.write(
+    [
+      'npx @hegemonart/get-design-done — install the plugin',
+      '',
+      'Registers the github.com/hegemonart/get-design-done marketplace and',
+      'enables the get-design-done plugin in your Claude Code settings.',
+      '',
+      'Flags:',
+      '  --dry-run    Print the diff without writing',
+      '  --help, -h   Show this message',
+      '',
+      'Environment:',
+      '  CLAUDE_CONFIG_DIR   Override the Claude config directory',
+      '                      (default: ~/.claude)',
+      '',
+      'After install, restart Claude Code to load the plugin.',
+      '',
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
+const DRY_RUN = args.has('--dry-run');
+
+function resolveConfigDir() {
+  if (process.env.CLAUDE_CONFIG_DIR && process.env.CLAUDE_CONFIG_DIR.trim()) {
+    return process.env.CLAUDE_CONFIG_DIR.trim();
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+function loadSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    const raw = fs.readFileSync(settingsPath, 'utf8');
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch (err) {
+    process.stderr.write(
+      `get-design-done installer: cannot parse ${settingsPath} as JSON\n` +
+        `  ${err.message}\n` +
+        `  Fix the file manually or delete it, then re-run.\n`,
+    );
+    process.exit(1);
+  }
+}
+
+function mergeSettings(existing) {
+  const next = { ...existing };
+
+  const marketplaces = { ...(next.extraKnownMarketplaces || {}) };
+  const marketplaceEntry = {
+    source: { source: 'github', repo: REPO },
+  };
+  const marketplaceChanged =
+    JSON.stringify(marketplaces[MARKETPLACE_NAME]) !==
+    JSON.stringify(marketplaceEntry);
+  marketplaces[MARKETPLACE_NAME] = marketplaceEntry;
+  next.extraKnownMarketplaces = marketplaces;
+
+  const enabled = { ...(next.enabledPlugins || {}) };
+  const enabledChanged = enabled[ENABLED_KEY] !== true;
+  enabled[ENABLED_KEY] = true;
+  next.enabledPlugins = enabled;
+
+  return { next, changed: marketplaceChanged || enabledChanged };
+}
+
+function atomicWrite(target, contents) {
+  const tmp = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(tmp, target);
+}
+
+function main() {
+  const configDir = resolveConfigDir();
+  const settingsPath = path.join(configDir, 'settings.json');
+
+  if (!fs.existsSync(configDir)) {
+    if (DRY_RUN) {
+      process.stdout.write(
+        `[dry-run] would create ${configDir}\n`,
+      );
+    } else {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+  }
+
+  const existing = loadSettings(settingsPath);
+  const { next, changed } = mergeSettings(existing);
+  const formatted = `${JSON.stringify(next, null, 2)}\n`;
+
+  if (!changed) {
+    process.stdout.write(
+      `get-design-done is already registered in ${settingsPath}\n` +
+        `Nothing to do. Restart Claude Code if you haven't yet.\n`,
+    );
+    return;
+  }
+
+  if (DRY_RUN) {
+    process.stdout.write(
+      `[dry-run] would update ${settingsPath}\n` +
+        `  extraKnownMarketplaces["${MARKETPLACE_NAME}"] = { source: { source: "github", repo: "${REPO}" } }\n` +
+        `  enabledPlugins["${ENABLED_KEY}"] = true\n`,
+    );
+    return;
+  }
+
+  atomicWrite(settingsPath, formatted);
+
+  process.stdout.write(
+    [
+      `✓ get-design-done registered in ${settingsPath}`,
+      `  marketplace: github:${REPO}`,
+      `  plugin:      ${ENABLED_KEY}`,
+      '',
+      'Next steps:',
+      '  1. Restart Claude Code (or run /reload-plugins).',
+      '  2. Claude Code will fetch the plugin on first launch.',
+      '  3. Verify with: /plugin list',
+      '',
+    ].join('\n'),
+  );
+}
+
+main();

package/skills/discover/SKILL.md

@@ -19,13 +19,20 @@ user-invocable: true
    - Otherwise: normal transition — set frontmatter stage=discover, <position> stage=discover, status=in_progress, task_progress=0/1.
 2. **Probe connection availability** — ToolSearch runs FIRST because MCP tools may be in the deferred tool set. This is the canonical probe pattern (spec lives in `connections/connections.md`; copied inline because SKILL.md has no include mechanism — if the probe pattern changes, update all stages that copied it).
 
-   **A — Figma probe:**
+   **A — Figma probe (variant-agnostic):**
 
    ```
-   A1. ToolSearch({ query: "select:mcp__figma__get_metadata", max_results: 1 })
-   A2. Empty result → figma: not_configured (skip all Figma paths)
-       Non-empty result → call mcp__figma__get_metadata
-         Success → figma: available
+   A1. ToolSearch({ query: "figma get_metadata use_figma", max_results: 10 })
+   A2. Parse tool names matching /^mcp__([^_]*figma[^_]*)__(get_metadata|use_figma)$/i
+       into read-capable and write-capable prefix sets.
+   A3. Empty read set → figma: not_configured (skip all Figma paths)
+       One or more matches → pick prefix via tiebreaker:
+         (1) both-sets > reads-only,
+         (2) `figma` > others,
+         (3) non-`figma-desktop` > desktop,
+         (4) alphabetical.
+   A4. Call {prefix}get_metadata:
+         Success → figma: available (prefix=mcp__<prefix>__, writes=<true|false>)
          Error   → figma: unavailable
    ```