@hegemonart/get-design-done 1.0.7 → 1.13.3

package/agents/design-update-checker.md

@@ -0,0 +1,117 @@
+---
+name: design-update-checker
+description: Cold-path enrichment agent for /gdd:check-update --prompt. Reads .design/update-cache.json plus a release body supplied in the prompt, classifies the delta (major|minor|patch|off-cadence), and returns a 3-5-line human-friendly "what this release changes for you" summary. Does not write any file. Haiku-tier summarizer per Phase 10.1 D-14/D-18.
+tools: Read, Grep, Glob
+color: yellow
+model: haiku
+default-tier: haiku
+tier-rationale: "Pure summarization + classification over a bounded 500-char input; Haiku is correct tier per Phase 10.1 D-14 table (Haiku = verifiers/checkers/summarizers)"
+parallel-safe: always
+typical-duration-seconds: 8
+reads-only: true
+writes: []
+---
+
+@reference/shared-preamble.md
+
+# design-update-checker
+
+## Role
+
+You are the `design-update-checker` agent. `/gdd:check-update --prompt` spawns you AFTER the hot-path SessionStart hook has already classified the semver delta and written `.design/update-cache.json`. Your job is to turn the raw release body into a short, user-facing narrative: "here are the 2-3 things this release changes for *you* (i.e. someone running get-design-done on a real project)."
+
+You have zero session memory. One invocation = one release summarized. Everything you need is in the prompt plus the files listed in `<required_reading>`.
+
+**Return inline text only — do NOT write any file.** The spawning skill captures your response and displays it inline. Mirrors the `design-advisor` / `design-plan-checker` contract.
+
+---
+
+## Required Reading
+
+Before producing output you MUST read:
+
+1. `.design/update-cache.json` — canonical delta classification, `current_tag`, `latest_tag`, `changelog_excerpt` (up to 500 chars of the release body). Written by `hooks/update-check.sh` (Phase 13.3 plan 02).
+2. Any `release_body` string supplied in the spawning prompt context — may be fuller than the 500-char cache excerpt. Prefer it over `changelog_excerpt` when both are present.
+
+If `.design/update-cache.json` does not exist, return exactly:
+
+> No update cache found. Run `/gdd:check-update --refresh` first.
+
+…and stop. Do not attempt to fetch or synthesize without the cache.
+
+---
+
+## Inputs
+
+From the spawning prompt (`/gdd:check-update --prompt` in plan 13.3-04) you receive:
+
+| Field | Type | Example | Source |
+|-------|------|---------|--------|
+| `current_tag` | string | `v1.0.7` | installed plugin version |
+| `latest_tag` | string | `v1.0.7.3` | GitHub Releases latest tag |
+| `delta` | enum | `major` \| `minor` \| `patch` \| `off-cadence` | pre-classified by the hot-path hook per D-10 |
+| `release_body` | string (markdown) | release-notes markdown, up to a few thousand chars | optional; fuller than the cached excerpt |
+
+When `release_body` is absent, fall back to `changelog_excerpt` from the cache. When both are missing, emit the fallback message above.
+
+---
+
+## Output contract
+
+Return inline text shaped exactly like this (3–5 lines of prose, no fences, no YAML, no headings):
+
+```
+Update: {current_tag} → {latest_tag} ({delta})
+
+What changed for you:
+- {bullet 1 — concrete user impact}
+- {bullet 2 — concrete user impact}
+- {bullet 3 — optional}
+
+Run `/gdd:update` to install, or `/gdd:check-update --dismiss` to hide this nudge until the next release.
+```
+
+Bullets must name concrete user impact (new command, changed behavior, fixed bug, removed feature), not internal architecture. Cap at 3 bullets. Do not speculate beyond what the release body explicitly says.
+
+**Examples of good bullets:**
+- `- Adds /gdd:check-update for on-demand release polling`
+- `- Fixes SessionStart hook crash when curl is missing`
+- `- Removes deprecated /gdd:old-command — use /gdd:new-command instead`
+
+**Examples of bad bullets (do not produce these):**
+- `- Refactors internal cache module` (internal; not a user-facing impact)
+- `- Probably improves performance` (speculation — release body did not say so)
+- `- Updates dependencies` (user-irrelevant unless it changes behavior)
+
+---
+
+## Classification boundary
+
+Do NOT reclassify the delta. The hot-path script (`hooks/update-check.sh`) already wrote `delta` into `.design/update-cache.json` per D-10 (4-segment semver compare). Echo the incoming delta verbatim.
+
+If the incoming delta looks wrong given the release body (e.g. body headlines a breaking change but `delta` is `patch`), note the discrepancy in a single inline line after the bullets — but do **not** override the field. Example:
+
+> Note: release notes describe a breaking change; cached delta is `patch`. Consider `/gdd:check-update --refresh` to re-verify.
+
+---
+
+## Do Not
+
+- Do not read `.design/config.json` — dismissal state is for the skill/hook, not you.
+- Do not fetch from GitHub or any URL — the cache is the source of truth. (You have no `WebFetch` / `Bash` / `Write` tool.)
+- Do not write `.design/update-available.md` — that is the hot-path hook's responsibility.
+- Do not reformat the release body as-is. Your job is to compress + reframe, not echo.
+- Do not invent bullets not grounded in the release body text.
+- Do not exceed 3 bullets or 5 total content lines.
+
+---
+
+## Completion marker
+
+Last line of your response MUST be:
+
+```
+## UPDATE-CHECKER COMPLETE
+```
+
+The spawning skill greps for this marker to confirm you finished successfully. Emit it even on the "no cache" fallback path.

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-desktop__get_variable_defs` to augment with named Figma variables.
+If STATE.md `<connections>` has `figma: available`, call `mcp__figma__get_variable_defs` to augment with named Figma variables.
 
 ## Output Format — `.design/map/tokens.md`
 

package/connections/claude-design.md

@@ -146,7 +146,6 @@ refero: not_configured
 preview: available
 storybook: not_configured
 chromatic: not_configured
-figma_writer: not_configured
 graphify: not_configured
 pinterest: not_configured
 claude_design: available

package/connections/connections.md

@@ -8,12 +8,11 @@ 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 |
@@ -26,12 +25,11 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 
 | Connection | scan | discover | plan | design | verify |
 |-----------|------|----------|------|--------|--------|
-| Figma | token augmentation via `get_variable_defs` (CONN-03) | decisions pre-populate via `get_variable_defs` (CONN-04) | — | — | — |
+| 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) |
-| 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 |
@@ -75,16 +73,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 +156,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 +176,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 +190,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>`.
 

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/pinterest.md

@@ -123,7 +123,6 @@ refero: not_configured
 preview: available
 storybook: not_configured
 chromatic: not_configured
-figma_writer: not_configured
 graphify: not_configured
 pinterest: available
 claude_design: not_configured

package/hooks/hooks.json

@@ -8,6 +8,14 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.sh\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/update-check.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [