@hegemonart/get-design-done 1.0.7 → 1.13.3

package/skills/check-update/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: gdd-check-update
+description: "Manual plugin-update check. Shows cached state by default; --refresh bypasses the 24h TTL; --dismiss hides the nudge until a newer release ships; --prompt spawns design-update-checker for a richer summary."
+argument-hint: "[--refresh] [--dismiss] [--prompt]"
+tools: Read, Write, Bash, Task
+---
+
+# /gdd:check-update
+
+**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| *(none)* | Print cached state (latest_tag, delta, is_newer). If the cache is older than 24h, trigger `--refresh` implicitly. |
+| `--refresh` | Invoke `hooks/update-check.sh --refresh` — bypasses the 24h TTL and re-fetches immediately. |
+| `--dismiss` | Write `update_dismissed: "<latest_tag>"` to `.design/config.json` atomically and delete `.design/update-available.md`. Sticky until a newer release ships. |
+| `--prompt` | Spawn `design-update-checker` agent (Haiku) to produce a 3–5-line "what this release changes for you" summary. Does not alter the banner or cache. |
+
+Flags can be combined: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
+
+## Steps
+
+1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Any unknown flag: print `Unknown flag: <flag>` and exit.
+
+2. **--refresh path** (if `--refresh` in flags):
+    Run the hot-path hook with the refresh flag:
+    ```bash
+    bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/hooks/update-check.sh" --refresh
+    ```
+    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to the same state/dismissal gates.
+
+3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If it does not exist:
+    - Print: `No cache. Network may be unreachable or the hook has not run yet. Try /gdd:check-update --refresh.`
+    - Exit.
+
+4. **Dismiss path** (if `--dismiss` in flags):
+    Compute new config contents and write atomically. The python heredoc receives CONFIG_PATH and LATEST_TAG via the ENVIRONMENT (env-prefix form — `KEY=VALUE python3 <<PY`), NOT via trailing argv. Passing `python3 -c '...' KEY=VALUE` makes Python treat the assignments as `sys.argv`, which the old draft did incorrectly; env-prefix form is the portable fix.
+
+    ```bash
+    CONFIG_PATH=".design/config.json"
+    LATEST_TAG="$(grep -E '"latest_tag"' .design/update-cache.json | head -n1 | sed -E 's/.*"latest_tag"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
+    [ -n "$LATEST_TAG" ] || { echo 'No latest_tag in cache — nothing to dismiss.'; exit 0; }
+
+    mkdir -p .design
+
+    # Env-prefix form: CONFIG_PATH and LATEST_TAG are placed into the child process env,
+    # then python3 reads them via os.environ. Heredoc body is flat at column 0 (required —
+    # any leading indentation breaks Python parsing in a heredoc).
+    CONFIG_PATH="$CONFIG_PATH" LATEST_TAG="$LATEST_TAG" python3 <<'PY'
+import json, os, sys, tempfile
+
+config_path = os.environ['CONFIG_PATH']
+latest_tag = os.environ['LATEST_TAG']
+
+# Load existing config if present; otherwise start fresh. Preserve every unknown key.
+try:
+    with open(config_path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        data = {}
+except (FileNotFoundError, json.JSONDecodeError):
+    data = {}
+
+# Set ONLY the dismissal key — every other pre-existing key is preserved verbatim.
+data['update_dismissed'] = latest_tag
+
+# Atomic write: write to tmp on the SAME filesystem, then os.replace() (POSIX rename(2)).
+target_dir = os.path.dirname(config_path) or '.'
+fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
+try:
+    with os.fdopen(fd, 'w', encoding='utf-8') as f:
+        json.dump(data, f, indent=2)
+        f.write('\n')
+    os.replace(tmp_path, config_path)  # atomic on same filesystem
+except Exception as exc:
+    try:
+        os.unlink(tmp_path)
+    except OSError:
+        pass
+    sys.exit(1)
+PY
+
+    # Remove the rendered banner (user dismissed — stop showing it until a newer release ships).
+    rm -f .design/update-available.md
+    echo "Dismissed $LATEST_TAG. The nudge will return when a newer release ships."
+    ```
+
+    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem — an interrupted write leaves the original config intact. The `json.load → set single key → json.dump` round-trip guarantees every unknown top-level key (e.g. `model_profile`, `parallelism`) is preserved verbatim.
+
+5. **Print default state** (always, unless the skill exited early):
+    ```
+    ━━━ /gdd:check-update ━━━
+    Current:   v<X.Y.Z>
+    Latest:    v<A.B.C>   (delta: <major|minor|patch|off-cadence|none>)
+    Newer:     <true|false>
+    Checked:   <ISO time of checked_at>
+    Dismissed: <tag or "no">
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━
+    ```
+    Parse these fields from `.design/update-cache.json` using `grep + sed` (no jq dependency). Read dismissal from `.design/config.json` via the same pattern as hooks/update-check.sh:
+    ```bash
+    [ -f .design/config.json ] && grep -E '"update_dismissed"' .design/config.json | sed -E 's/.*"update_dismissed"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/'
+    ```
+
+6. **--prompt path** (if `--prompt` in flags):
+    Spawn the `design-update-checker` agent via the Task tool. Pass as context:
+    - `current_tag` — from `.design/update-cache.json`
+    - `latest_tag` — from `.design/update-cache.json`
+    - `delta` — from `.design/update-cache.json`
+    - `release_body` — the `changelog_excerpt` from the cache (may be pre-truncated to 500 chars; that's fine — the agent knows)
+
+    Display the agent's inline response verbatim below the state banner. The agent ends with `## UPDATE-CHECKER COMPLETE` — the skill's own completion marker (below) is the final line.
+
+## Defaults
+
+- No flags → behave as: `--refresh (only if cache >24h old) → print state`. Silent no-op if cache is fresh and there is no newer version.
+
+## Do Not
+
+- Do not fetch from GitHub in this skill directly — always go through `hooks/update-check.sh --refresh` so the caching + state-guard + dismissal logic stays in one place.
+- Do not modify `.design/update-available.md` except to delete it on `--dismiss`. The hot-path hook is the only writer of that banner (D-06).
+- Do not rewrite `.design/config.json` wholesale — the atomic python rewrite preserves every unknown key (D-14).
+- Do not pass variables to the python heredoc via trailing `KEY=VALUE` argv — that assigns to `sys.argv`, not `os.environ`. Use env-prefix form only.
+
+## Completion marker
+
+Last line of output:
+
+```
+## CHECK-UPDATE COMPLETE
+```

package/skills/complete-cycle/SKILL.md

@@ -30,4 +30,14 @@ Closes the current cycle: marks CYCLES.md entry complete, archives pipeline arti
 - Do not delete source files in `src/` — only archive `.design/` artifacts.
 - Do not auto-start a new cycle — user invokes `/gdd:new-cycle` explicitly.
 
+## Step 6 — Update notice (post-closeout surface)
+
+After the archive has been written and STATE.md has been cleared for the next cycle, emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
 ## COMPLETE-CYCLE COMPLETE

package/skills/design/SKILL.md

@@ -41,7 +41,7 @@ Skip if `auto_mode=true`.
 
 ## Pre-execution — Project-local conventions
 
-When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists � global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
+When spawning the executor, include any `./.claude/skills/design-*-conventions.md` files in `<required_reading>` so the executor sees project-local design conventions (typography, color, layout, motion, component, interaction decisions codified from prior sketch wrap-ups). Also include any `~/.claude/gdd/global-skills/*.md` files if the directory exists � global skills are cross-project conventions that inform but do not override project-local D-XX decisions.
 
 ---
 
@@ -256,13 +256,13 @@ Next: /get-design-done:verify
 
 After design-executor has finished and DESIGN-PLAN.md tasks are complete:
 
-1. Read `figma_writer:` status from `.design/STATE.md` `<connections>`:
-   - If `figma_writer: not_configured` or absent → skip this block entirely (no prompt, no output)
-   - If `figma_writer: available` → proceed to step 2
+1. Read `figma:` status from `.design/STATE.md` `<connections>` (the unified remote MCP covers both reads and writes as of v1.0.7.1):
+   - If `figma: not_configured` or `figma: unavailable` or absent → skip this block entirely (no prompt, no output)
+   - If `figma: available` → proceed to step 2
 
 2. Offer the user a prompt:
    ```
-   figma-writer is available — propagate design decisions back to Figma?
+   figma write-back is available — propagate design decisions back to Figma?
    Modes: annotate (layer comments) | tokenize (variable bindings) | mappings (Code Connect)
    Run figma-write? (y/N):
    ```

package/skills/discover/SKILL.md

@@ -22,9 +22,9 @@ user-invocable: true
    **A — Figma probe:**
 
    ```
-   A1. ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+   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-desktop__get_metadata
+       Non-empty result → call mcp__figma__get_metadata
          Success → figma: available
          Error   → figma: unavailable
    ```

package/skills/explore/SKILL.md

@@ -19,9 +19,9 @@ Probe connection availability and update `.design/STATE.md` `<connections>`:
 
 **A — Figma probe:**
 ```
-ToolSearch({ query: "select:mcp__figma-desktop__get_metadata", max_results: 1 })
+ToolSearch({ query: "select:mcp__figma__get_metadata", max_results: 1 })
 Empty → figma: not_configured
-Non-empty → call mcp__figma-desktop__get_metadata; success → available; error → unavailable
+Non-empty → call mcp__figma__get_metadata; success → available; error → unavailable
 ```
 
 **B — Refero probe:**

package/skills/health/SKILL.md

@@ -45,4 +45,14 @@ Health: 5 / 6 checks passing.
 ━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Update notice (safe-window surface)
+
+After the health table, emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
 ## HEALTH COMPLETE

package/skills/help/SKILL.md

@@ -73,4 +73,14 @@ Lifecycle:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Update notice (safe-window surface)
+
+After the command reference, emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
 ## HELP COMPLETE

package/skills/progress/SKILL.md

@@ -57,4 +57,14 @@ Seeds ready: 0
 ━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Step 4 — Update notice (safe-window surface)
+
+After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+No-op when: no new release exists, state-machine guard is active (stage in plan|design|verify), or the latest tag has been dismissed via `/gdd:check-update --dismiss`.
+
 ## PROGRESS COMPLETE

package/skills/reflect/SKILL.md

@@ -27,6 +27,7 @@ Run `design-reflector` on demand against the current (or specified) cycle. Produ
    .design/agent-metrics.json
    .design/learnings/question-quality.jsonl
    .design/cycles/<slug>/CYCLE-SUMMARY.md
+   .design/authority-report.md
    ```
    Use the resolved slug where `<slug>` appears.
 

package/skills/scan/SKILL.md

@@ -39,17 +39,17 @@ At scan entry, before running any step:
 
 Run both probes below. MCP tools may be in the deferred tool set — **always call ToolSearch first**; without it, a deferred tool invocation fails silently.
 
-**Figma probe:**
+**Figma probe (single probe covers both reads and writes — remote MCP exposes `get_metadata`, `get_variable_defs`, `use_figma` on the same server):**
 
 ```
 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
+  call mcp__figma__get_metadata
+  → Success           → figma: available   (reads AND use_figma writes both available)
   → Error             → figma: unavailable  (skip all Figma steps)
 ```
 
@@ -66,7 +66,9 @@ Note: scan probes **both** connections because the State Integration block is th
 
 ### Phase 8 Connection Probes
 
-Run all 5 Phase 8 probes at scan entry. Results are written to STATE.md `<connections>` so downstream stages (verify, compare, darkmode, plan, design) do not re-probe unless needed.
+Run all 4 Phase 8 probes at scan entry. Results are written to STATE.md `<connections>` so downstream stages (verify, compare, darkmode, plan, design) do not re-probe unless needed.
+
+Note: as of v1.0.7.1, Figma is a single connection (`figma:` key) covering reads + writes — no separate `figma_writer:` probe. The Wave A Figma probe above is the sole Figma availability check.
 
 **preview:**
 
@@ -118,17 +120,6 @@ Step C2 — Token check:
 Write: chromatic: <status> to STATE.md <connections>
 ```
 
-**figma_writer:**
-
-```
-ToolSearch({ query: "select: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: ToolSearch-only probe (same pattern as Refero). No live call at scan time.
-```
-
 **graphify:**
 
 ```
@@ -145,7 +136,7 @@ Step G2 — Graph file check:
 Write: graphify: <status> to STATE.md <connections>
 ```
 
-After all 5 probes, STATE.md `<connections>` contains all 5 status entries. Downstream plans (08-02 through 08-05) read these values without re-probing.
+After all 4 probes, STATE.md `<connections>` contains all 4 status entries (plus the Wave A `figma:` and `refero:` probes = 6 total entries). Downstream plans (08-02 through 08-05) read these values without re-probing.
 
 ### Write STATE.md
 
@@ -158,7 +149,6 @@ refero: <available | not_configured>
 preview: <available | unavailable | not_configured>
 storybook: <available | unavailable | not_configured>
 chromatic: <available | unavailable | not_configured>
-figma_writer: <available | not_configured>
 graphify: <available | unavailable | not_configured>
 </connections>
 ```
@@ -238,7 +228,7 @@ Produce a color inventory table:
 
 ### If `figma: available`
 
-Call `mcp__figma-desktop__get_variable_defs` (no arguments — returns all variables in the active Figma file).
+Call `mcp__figma__get_variable_defs` (no arguments — returns all variables in the active Figma file).
 
 > If no Figma file is open, the call errors. Treat any error as a graceful skip: update STATE.md `<connections>` to `figma: unavailable` and continue with Step 2 results only.
 

package/skills/ship/SKILL.md

@@ -28,4 +28,14 @@ Closes the verify → merge gap: runs `/gdd:pr-branch` for a clean branch, assem
 - Do not include `.design/` or `.planning/` files in the PR branch — that is `/gdd:pr-branch`'s job.
 - Do not skip the verify pre-flight silently — always surface a failure and ask.
 
+## Step 7 — Update notice (post-closeout surface)
+
+ONLY on the success path — after the PR has been created and the URL has been printed — emit the plugin-update banner. If PR creation failed earlier, skip this step (do not suggest upgrades in the middle of a PR-creation failure).
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
 ## SHIP COMPLETE

package/skills/watch-authorities/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gdd-watch-authorities
+description: "Fetches the design-authority feed whitelist, diffs against .design/authority-snapshot.json, and writes .design/authority-report.md (consumed by /gdd:reflect). Authority monitoring only — no trend-watching."
+argument-hint: "[--refresh] [--since <date>] [--feed <name>] [--schedule <weekly|daily|monthly>]"
+tools: Read, Write, Task, Bash
+---
+
+# /gdd:watch-authorities
+
+Runs `design-authority-watcher` on demand. Fetches the curated design-authority feed whitelist, diffs against the prior snapshot, classifies new entries into five buckets, and writes `.design/authority-report.md`. Phase 11's reflector picks up the report automatically when you next run `/gdd:reflect`.
+
+Authority-monitoring only. Not trend-watching. See `reference/authority-feeds.md` §"Rejected kinds" for what this skill will never fetch.
+
+## Steps
+
+1. **Parse args.** Extract optional flags: `--refresh`, `--since <date>`, `--feed <name>`, `--schedule <cadence>`. Anything that doesn't match one of these is an error — print `Unknown flag: <arg>. Valid flags: --refresh --since <date> --feed <name> --schedule <weekly|daily|monthly>.` and STOP.
+
+   Mutual exclusion rules:
+   - `--schedule` is handled entirely by this skill — it does not combine with the other three. If `--schedule` is present alongside any of `--refresh | --since | --feed`, print `--schedule cannot combine with other flags. Schedule registration runs this skill with no flags at the configured cadence.` and STOP.
+   - `--refresh` and `--since` are mutually exclusive — print `--refresh and --since are mutually exclusive. --refresh re-seeds the snapshot silently; --since surfaces a backlog from a boundary date. Pick one.` and STOP.
+
+2. **Handle `--schedule <cadence>` branch** (early-return).
+
+   If `--schedule` is set:
+   - Validate cadence ∈ {`weekly`, `daily`, `monthly`}; else print `Unknown cadence: <value>. Use one of: weekly, daily, monthly.` and STOP.
+   - Probe for the scheduled-tasks MCP via ToolSearch:
+
+     ```
+     ToolSearch({ query: "scheduled-tasks", max_results: 3 })
+     ```
+
+   - If the probe returns an empty result set: print `scheduled-tasks MCP not connected. Install it with: claude mcp add scheduled-tasks ... then retry with --schedule.` — this is a documented fallback (not an error). Terminate with `## WATCH COMPLETE` and exit 0.
+   - If the probe returns one or more `scheduled-tasks` tools: register the cron. Discover the MCP's registration tool name at runtime from the ToolSearch result and follow its schema. Target command: `/gdd:watch-authorities` with NO flags (the cron invokes the default diff-and-report behavior). Cadence → cron expression mapping:
+     - `weekly`  → `0 9 * * 1` (Mondays 09:00 local)
+     - `daily`   → `0 9 * * *` (every day 09:00 local)
+     - `monthly` → `0 9 1 * *` (1st of each month 09:00 local)
+   - After registration: print `Scheduled /gdd:watch-authorities to run <cadence>.` and terminate with `## WATCH COMPLETE`.
+
+3. **Validate `--since <date>`** (if present).
+
+   Accept ISO8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Sanity-check via Bash `date -d "<value>" +%s` (GNU) or the POSIX equivalent `python3 -c "from datetime import datetime; datetime.fromisoformat('<value>'.replace('Z','+00:00'))"`. On parse failure: print `Invalid --since value: <value>. Use ISO8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).` and STOP.
+
+   If the parsed date is earlier than `2020-01-01`, ask: `Very old --since value: <value>. Did you mean something more recent? Proceed? [y/N]`. On anything other than `y`/`Y`, STOP.
+
+4. **Spawn the watcher.**
+
+   Build the `Task(subagent_type="design-authority-watcher", ...)` prompt. The prompt supplies the agent's required-reading block (watcher step 0), echoes the invocation flags verbatim (watcher Flags section), and instructs the agent to follow its own fetch/diff/classify/write loop:
+
+   ```
+   Task("design-authority-watcher", """
+   <required_reading>
+   @reference/authority-feeds.md
+   @.design/authority-snapshot.json
+   @.design/STATE.md
+   </required_reading>
+
+   Invocation flags: <joined flag list or "none">
+
+   Fetch the feeds listed in reference/authority-feeds.md, diff against .design/authority-snapshot.json,
+   classify new entries per the D-17 decision table, write .design/authority-snapshot.json and
+   .design/authority-report.md.
+
+   Terminate with ## WATCH COMPLETE.
+   """)
+   ```
+
+   `<joined flag list>` is the subset of `--refresh | --since <date> | --feed <name>` actually passed — e.g., `--refresh`, `--since 2026-03-01`, `--feed wai-aria-apg`, `--refresh --feed radix-ui-releases`, or literally `none` when no flags were supplied.
+
+5. **Print summary.**
+
+   After the agent returns:
+   - If STATE.md gained a `<blocker type="contract-violation">` on this run (snapshot version mismatch, hash-format violation, or over-200 entries per feed), surface the blocker verbatim and stop — do not print the default "review and reflect" line.
+   - Otherwise print the agent's one-line stdout summary (normal mode: `Surfaced N entries across M feeds. K skipped. See .design/authority-report.md.`; first-run / refresh mode: `Seeded snapshot for N feeds — next run will surface new entries.`) followed by: `Review and reflect: /gdd:reflect`.
+
+6. **Terminate with `## WATCH COMPLETE`.**
+
+## Do Not
+
+- Do not modify `agents/design-authority-watcher.md`.
+- Do not modify `agents/design-reflector.md` — Phase 13.2 does not touch the reflector agent (CONTEXT.md D-25).
+- Do not write to `.design/authority-snapshot.json` or `.design/authority-report.md` directly — those are the agent's writes.
+- Do not fetch URLs outside `reference/authority-feeds.md`. The whitelist is the allow-list.

package/connections/figma-writer.md

@@ -1,139 +0,0 @@
-# Figma Writer — Connection Specification
-
-This file is the connection specification for the figma-writer capability within the get-design-done pipeline. The figma-writer is a proposal→confirm write agent (`design-figma-writer`) that wraps the `mcp__figma__use_figma` remote MCP to write design decisions back to Figma. It is distinct from the Figma Desktop MCP read connection documented in `connections/figma.md`. See `connections/connections.md` for the full connection index and capability matrix.
-
----
-
-## Setup
-
-**Prerequisites:**
-
-- Figma desktop app installed and running (required for read operations via `mcp__figma-desktop__*`)
-- Dev Mode enabled in the Figma desktop app
-- Remote Figma MCP registered for write operations
-
-**Register remote MCP (Claude Code):**
-
-```
-claude mcp add figma --transport http https://mcp.figma.com/v1/sse
-```
-
-After running this command, restart the Claude Code session. The remote MCP server authenticates via OAuth at `mcp.figma.com`. On first use, Claude Code will prompt you to complete the OAuth flow.
-
-**Verification:**
-
-After session restart, run:
-
-```
-ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
-```
-
-Expect a non-empty result listing `mcp__figma__use_figma`. If empty, the remote MCP is not registered — run the registration command above and restart.
-
----
-
-## Tools
-
-All write operations use the `mcp__figma__` prefix (remote MCP). Read operations use the `mcp__figma-desktop__` prefix (desktop MCP).
-
-| Tool | Full name | Returns | Pipeline use |
-|------|-----------|---------|--------------|
-| `use_figma` | `mcp__figma__use_figma` | operation result | all write operations (annotate, tokenize, mappings) |
-
-**Important distinction:** `mcp__figma-desktop__*` tools are used for reads only (get_metadata, get_variable_defs). `mcp__figma__use_figma` is the remote MCP used exclusively for writes. The desktop MCP does NOT expose `use_figma` — it is remote-only. Do not attempt to call `mcp__figma-desktop__use_figma` — that tool does not exist.
-
----
-
-## 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 |
-
-All three modes follow the proposal→confirm UX: the agent builds a numbered operation list and presents it to the user before executing any write. The user must confirm before `use_figma` is called.
-
----
-
-## Which Stages Use This Connection
-
-| Stage | Agent/Skill | Tool used | Purpose |
-|-------|-------------|-----------|---------|
-| figma-write | `agents/design-figma-writer.md` | `mcp__figma__use_figma` | Write design decisions back to Figma in three modes (annotate/tokenize/mappings) |
-| design | `skills/design/SKILL.md` | (dispatch only) | Offer to spawn design-figma-writer after design-executor completes, when figma_writer: available |
-
----
-
-## Availability Probe (ToolSearch-only)
-
-The figma-writer probe is ToolSearch-only — no live call at probe time. This matches the Refero connection pattern (opt-in tool, no live call needed to confirm availability).
-
-```
-ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
-→ Empty result      → figma_writer: not_configured  (skip figma-write entirely; log to STATE.md)
-→ Non-empty result  → figma_writer: available
-```
-
-Write `figma_writer:` status to `.design/STATE.md` `<connections>` immediately after probing.
-
-Note: The status key is `figma_writer:` (with underscore). This is distinct from `figma:` (desktop MCP status) and `figma_write:` is not used — the canonical key is `figma_writer:`.
-
----
-
-## Fallback Behavior
-
-When `figma_writer` is `not_configured`, the pipeline degrades gracefully — no error is raised.
-
-**figma-write stage:**
-- `figma_writer: not_configured` → skip with note: "Figma write skipped — remote MCP not installed. Register with: claude mcp add figma --transport http https://mcp.figma.com/v1/sse"
-
-**design stage:**
-- `figma_writer: not_configured` or absent → skip the figma-write dispatch offer entirely (no prompt, no output)
-- `figma_writer: available` → offer opt-in prompt after design-executor completes
-
-**Special case — desktop MCP present but remote absent:**
-If `figma: available` (desktop MCP) but `figma_writer: not_configured` (remote MCP absent), the figma-write capability is still not available. Desktop MCP cannot perform writes. Do not offer figma-write dispatch in this state.
-
----
-
-## STATE.md Integration
-
-The scan stage writes the initial `figma_writer:` status. Subsequent stages read from STATE.md without re-probing.
-
-Example `<connections>` block after probing:
-
-```xml
-<connections>
-figma: available
-figma_writer: available
-refero: not_configured
-</connections>
-```
-
-**Status key:** `figma_writer:` (underscore separator)
-
-**Status values:**
-
-| Value | Meaning |
-|-------|---------|
-| `available` | ToolSearch returned non-empty for `mcp__figma__use_figma` |
-| `not_configured` | ToolSearch returned empty — remote MCP not registered |
-
-Note: There is no `unavailable` state for figma_writer — the ToolSearch-only probe cannot detect auth failures. Auth issues surface at execution time when `use_figma` is first called.
-
----
-
-## Caveats and Pitfalls
-
-1. **`mcp__figma__use_figma` is the remote MCP only.** It is registered as server `figma` via `claude mcp add`. It is NOT the same as the desktop MCP (`mcp__figma-desktop__*`). Running ToolSearch for `figma-desktop` will NOT find `use_figma`. Always use `select:mcp__figma__use_figma` as the probe query.
-
-2. **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.
-
-3. **Use `--dry-run` to inspect the proposal without risk.** Pass `--dry-run` to emit the full operation list without calling `use_figma`. Safe to run on production Figma files.
-
-4. **Use `--confirm-shared` for team library components.** Before any write, the agent detects shared team library components via `get_metadata`. If shared components are in the operation list and `--confirm-shared` was not passed, the agent halts and requires the flag. This prevents accidental modification of team-wide design tokens.
-
-5. **Operations execute sequentially, not atomically.** If one operation fails mid-sequence, the agent logs the error and continues with remaining operations. The Figma file may be left in a partially-updated state. The summary lists all failures for manual follow-up.