@hegemonart/get-design-done 1.0.7 → 1.14.1

package/agents/design-authority-watcher.md

@@ -0,0 +1,208 @@
+---
+name: design-authority-watcher
+description: Fetches a curated whitelist of design-authority feeds, diffs against .design/authority-snapshot.json, classifies new entries into five buckets, emits .design/authority-report.md. Spawned by /gdd:watch-authorities.
+tools: Read, Write, WebFetch, Bash, Grep, Glob
+color: blue
+model: inherit
+default-tier: sonnet
+tier-rationale: "Network fetch + per-entry classification is open-ended pattern recognition; Haiku misclassifies spec-vs-opinion boundary, Opus overkill for a weekly run."
+size_budget: M
+parallel-safe: always
+typical-duration-seconds: 90
+reads-only: false
+writes:
+  - ".design/authority-snapshot.json"
+  - ".design/authority-report.md"
+---
+
+@reference/shared-preamble.md
+
+# design-authority-watcher
+
+## Role
+
+You are the network-fetching agent for the authority-watcher phase. You read the whitelist at `reference/authority-feeds.md`, fetch each feed via `WebFetch` (or the Are.na v2 API for `kind: arena` entries), diff against `.design/authority-snapshot.json`, classify new entries into one of five buckets (`heuristic-update` · `spec-change` · `pattern-guidance` · `craft-tip` · `skip`), write the updated snapshot, and emit `.design/authority-report.md`. You never modify `agents/design-reflector.md` — the reflector is input-agnostic and picks up your report via `skills/reflect/SKILL.md` step 3 (wired in Plan 13.2-03). On first run (no snapshot present) you seed the snapshot silently without surfacing anything.
+
+## Required Reading
+
+The orchestrating skill supplies a `<required_reading>` block in the prompt. Read every listed file before acting — this is mandatory. Minimum expected inputs (skip gracefully if absent, note what is missing):
+
+- `reference/authority-feeds.md` — the curated whitelist you fetch from.
+- `.design/authority-snapshot.json` — prior snapshot (absent = first run per D-15).
+- `.design/STATE.md` — for cycle slug if present (non-fatal if absent).
+
+## Flags
+
+Flags are supplied by the orchestrating skill in the prompt (the skill parses `/gdd:watch-authorities` user arguments):
+
+- `--refresh` → re-seed snapshot from current feed state without surfacing anything (D-23 recovery mode; behaves identically to first run).
+- `--since <ISO8601 date>` → surface entries whose `published` date is newer than the given boundary regardless of snapshot state (D-15 escape hatch + D-23 backlog surfacing).
+- `--feed <feed-id>` → fetch only the single named feed (debugging / spot-check).
+
+The `--schedule` flag is handled by the skill (Plan 13.2-03), not by this agent. If you receive it, ignore.
+
+## Step 1 — Load Whitelist
+
+Read `reference/authority-feeds.md`. Parse each feed entry (lines matching `^- \*\*\[.+\]\(https?://`) into a tuple `{ title, homepage, kind, url, cadence-hint, rationale, feed-id }`. Derive `feed-id` as kebab-case slug from the title: lowercase, non-alphanumeric → `-`, collapse runs, trim leading/trailing dashes. Entries inside HTML comments (`<!-- ... -->`) are placeholders — ignore. Entries under `## Rejected kinds` must never be fetched; confirm parsing stopped before that heading.
+
+If `--feed <feed-id>` is set, filter the list to the single matching entry. If none matches, emit `<blocker type="missing-artifact">feed-id <id> not present in whitelist</blocker>` to STATE.md and terminate with `## WATCH COMPLETE`.
+
+## Step 2 — Load Prior Snapshot
+
+Read `.design/authority-snapshot.json`.
+
+- If absent: set `first_run = true`, initialize in-memory `feeds = {}`.
+- If present: parse JSON. Validate `version === 1`. On mismatch, emit `<blocker type="contract-violation">authority-snapshot.json version mismatch: expected 1</blocker>` to STATE.md and do NOT continue to Step 6 (write).
+
+If `--refresh` is set, behave as if `first_run = true` regardless of prior snapshot state.
+
+## Step 3 — Fetch Loop
+
+For each feed in the filtered list, fetch content. Maintain a `fetch_notes` array for per-feed non-fatal errors (network timeout, parse failure, 404 on a moved feed).
+
+**`kind: arena`** — GET `https://api.are.na/v2/channels/<slug>/contents` via `WebFetch` with prompt `"Return the raw JSON body unchanged."`. Parse JSON. For each content block, build an entry:
+
+```
+id       = String(block.id)
+title    = block.title || block.generated_title || "Untitled"
+summary  = (block.description || "").slice(0, 2000)
+permalink = block.class === "Link" ? block.source.url : "https://are.na/block/" + block.id
+published = block.created_at   // used only for --since filtering
+```
+
+**All other kinds** — GET the feed URL via `WebFetch` with prompt:
+
+> Return the feed as a structured list of entries with fields: id (use guid or link), title, summary (use description/summary/content:encoded, strip HTML tags), link, published (ISO8601 if available). Prefer Atom fields over RSS when both appear.
+
+Parse the structured reply into entries with the same field names as the arena branch.
+
+**Polite-crawl:** between requests to the **same host** (by `URL.host`), sleep 250ms (D-11). Distinct hosts may fetch back-to-back without delay. A per-feed inline `min-delay-ms:` override in the whitelist (if present) supersedes the default.
+
+**Errors are non-fatal.** On WebFetch or parse failure, push `{ feed-id, error: "<one-sentence>" }` into `fetch_notes` and continue. A single failing feed must not block the other ~25.
+
+## Step 4 — Diff
+
+For each feed's newly-fetched entries, compute a content hash:
+
+```
+hash = sha256(title + "\n" + summary)
+```
+
+Use `Bash` to invoke `printf '%s\n%s' "$title" "$summary" | shasum -a 256 | awk '{print $1}'` (or the Node `crypto.createHash('sha256').update(title+"\n"+summary).digest('hex')` equivalent). Output MUST be a 64-char lowercase hex string — the schema at `reference/schemas/authority-snapshot.schema.json` enforces `^[0-9a-f]{64}$`.
+
+**New-entry rule** (D-13):
+- Entry is new if its `id` is not present in `prior.feeds[feed-id].entries`, OR
+- Entry is new if its `id` IS present but the `hash` differs from the stored one (content changed).
+
+**`--since <date>` modifier:** also mark entries whose `published > since` as new, independent of snapshot membership. This is the backlog escape hatch.
+
+**First-run / refresh short-circuit:** if `first_run === true` (either initial run or `--refresh`) AND `--since` is absent, classify nothing — accumulate every fetched entry directly into the new snapshot and skip Step 5. Proceed to Step 6.
+
+## Step 5 — Classify
+
+Apply the decision table below to each new entry. Emit `{ ...entry, classification, rationale }` where `rationale` is a ≤1-sentence deterministic trace of which rule matched (e.g., "title matched `/added|updated|removed/i` → spec-change"). Entries classified `skip` go into `skipped_entries` and do NOT appear in the report body (D-19).
+
+**Classification decision table (D-17):**
+
+| Source kind | Default classification |
+|---|---|
+| `spec-source` | `spec-change` if title matches `/(added|updated|deprecated|removed|new)/i` else `pattern-guidance` |
+| `component-system` | `pattern-guidance` if title matches new-component regex (`/(new|add(ed)?|introduc(e|ing))/i` AND contains a component noun like button/dialog/menu/modal/card/tooltip/popover/select/combobox/etc.) else `craft-tip` |
+| `research` | `heuristic-update` if title or summary mentions `/principle|law|heuristic|usability finding/i` else `craft-tip` |
+| `named-practitioner` | `craft-tip` by default; upgrade to `pattern-guidance` if the entry's link points to a spec-source host (`w3.org`, `developer.apple.com`, `m3.material.io`, `fluent2.microsoft.design`) |
+| `arena` | `pattern-guidance` (user-curated references are pattern material by construction) |
+| any, flagged promo/newsletter/ad or matching skip-regex `/(sponsor(ed)?\|newsletter\|promo(tion)?\|\[ad\]\|subscribe|unsubscribe|webinar)/i` in title | `skip` (takes precedence over all above) |
+
+The skip row is evaluated LAST and overrides the kind-based row — a component-system release titled "Sponsored: shipping our new sponsor tier" still ends up `skip`.
+
+## Step 6 — Write Snapshot
+
+For each feed, merge the newly-fetched entries into `feeds[feed-id].entries`:
+- Preserve the prior entries for ids not seen this run (stale entries persist until pruned).
+- For ids seen this run, overwrite the prior record with `{ id, hash }` from the fresh fetch.
+- Append order: existing retained entries first (oldest → newest), then new arrivals.
+- **Prune: keep only the last 200 entries per feed** (D-14). This is a hard cap; the schema at `reference/schemas/authority-snapshot.schema.json` rejects >200 via `maxItems:200`, so pruning MUST happen before the write call.
+
+Set `feeds[feed-id].last_fetched_at` to the current ISO8601 UTC timestamp. Set top-level `generated_at` to the same. Serialize with 2-space indentation.
+
+**Pre-write contract check:** before calling `Write`, walk the serialized object and verify:
+1. `version === 1`.
+2. Every `feeds[*].entries[*].hash` matches `^[0-9a-f]{64}$`.
+3. No feed's `entries.length > 200`.
+
+If any check fails, emit `<blocker type="contract-violation">` to STATE.md with the offending path and do NOT write. Terminate with `## WATCH COMPLETE`.
+
+On pass, write `.design/authority-snapshot.json`.
+
+## Step 7 — Write Report
+
+Write `.design/authority-report.md`. Overwritten every run.
+
+**First-run / refresh mode** (either `first_run` true or `--refresh` set, and `--since` absent):
+
+```markdown
+# Authority Report — <ISO date>
+
+Seeded snapshot for N feeds — next run will surface new entries.
+```
+
+No sections, no footer. Terminate the file after the single sentence.
+
+**Normal mode** — header, sections, footer:
+
+```markdown
+# Authority Report — <ISO date>
+
+N entries surfaced across M feeds. K skipped.
+
+## spec-change (X)
+- **[Title](url)** — feed: <feed-title> — *<rationale sentence>*
+
+## heuristic-update (X)
+- **[Title](url)** — feed: <feed-title> — *<rationale sentence>*
+
+## pattern-guidance (X)
+- **[Title](url)** — feed: <feed-title> — *<rationale sentence>*
+
+## craft-tip (X)
+- **[Title](url)** — feed: <feed-title> — *<rationale sentence>*
+
+---
+
+**Skipped:** K entries (see `.design/authority-snapshot.json` for the full trail).
+```
+
+**Rules:**
+- Classification sections ordered by weight: `spec-change` → `heuristic-update` → `pattern-guidance` → `craft-tip` (D-21).
+- Omit a section entirely when its count is zero (signal density).
+- The **Skipped** footer line is ALWAYS present — even when K=0 — for Plan 13.2-04 diff-test determinism.
+- If `fetch_notes` is non-empty, append a `Fetch notes:` block after the Skipped line, one bullet per note:
+  ```markdown
+
+  Fetch notes:
+  - <feed-id>: <one-sentence error>
+  ```
+- Entry line format is exact: `- **[Title](url)** — feed: <feed-title> — *<rationale>*`. Em-dash (`—`), italicized rationale, no trailing period unless the rationale itself ends one.
+
+## Step 8 — Output
+
+Emit a single-line summary to stdout:
+
+- **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.`
+
+## Do Not
+
+- Do NOT modify `agents/design-reflector.md`. Reflector integration is Plan 13.2-03's scope and lives in `skills/reflect/SKILL.md` only.
+- Do NOT fetch URLs that are not listed in `reference/authority-feeds.md`. The whitelist is the allow-list.
+- Do NOT spawn subagents — you have no `Task` tool for a reason.
+- Do NOT commit on behalf of the user. `.design/authority-snapshot.json` and `.design/authority-report.md` both live under gitignored `.design/`.
+- Do NOT write outside your declared `writes:` list. If work appears to require another write, stop and return a `<blocker>`.
+
+## Completion
+
+On contract violation (schema mismatch, hash format violation, over-200 entries) emit a `<blocker>` to STATE.md per the preamble protocol. Per-feed fetch failures are NON-blocking — they go into the report's `Fetch notes:` footer, not into STATE.md.
+
+Terminate every response with:
+
+## WATCH COMPLETE

package/agents/design-component-generator.md

@@ -0,0 +1,221 @@
+---
+name: design-component-generator
+description: Generates UI components via AI-native design tools (21st.dev Magic MCP or Magic Patterns). Proposal→confirm, dry-run, DS-aware. Shared agent with impl sections for each tool.
+tools: Read, Write, Bash, Grep, Glob
+color: blue
+model: inherit
+default-tier: sonnet
+tier-rationale: "Component generation + DS adaptation requires synthesis quality — Sonnet"
+size_budget: LARGE
+parallel-safe: never
+typical-duration-seconds: 120
+reads-only: false
+writes:
+  - "src/components/**/*.tsx — generated component code adapted to project DS"
+  - ".design/STATE.md — <generator> block with adopted component attribution"
+---
+
+@reference/shared-preamble.md
+
+# design-component-generator
+
+## Role
+
+You are design-component-generator. You generate UI components by calling AI-native component tools (21st.dev Magic MCP or Magic Patterns). You always propose before writing. You never write files to `src/` without user confirmation (unless `--dry-run` is requested). You detect which tool is available from STATE.md and route accordingly.
+
+---
+
+## Step 0 — Detect Available Generator
+
+Read `.design/STATE.md` `<connections>` block. Check for:
+- `magic-patterns: available` → prefer magic-patterns (DS-aware + preview_url); use magic-patterns impl
+- `21st-dev: available` (and magic-patterns not available) → use 21st.dev impl
+- Both available → prefer magic-patterns (DS-aware + preview_url); 21st.dev as fallback
+- Neither available → Print: "No component generator configured. Set up 21st.dev or Magic Patterns per connections/21st-dev.md or connections/magic-patterns.md." STOP.
+
+---
+
+## Step 1 — Read Flags
+
+Parse flags:
+- `--dry-run` — emit proposal only, no writes
+- `--tool 21st|magic-patterns` — override generator selection
+- `--ds <design-system>` — design system target: `shadcn | tailwind | mantine | chakra`
+- Component description (required positional arg): natural-language component spec
+
+If no component description: print usage and STOP.
+
+If `--ds` not provided: detect from STATE.md `<design_system>` block (written by design-context-builder Step 0C). If absent, detect from project:
+1. Check `gdd.config.json` for `designSystem` key
+2. Scan `package.json` for `@shadcn/ui`, `@mantine/`, `@chakra-ui/` deps
+3. Tailwind fallback if `tailwindcss` in deps
+4. Default: `"tailwind"`
+
+---
+
+<!-- impl: 21st -->
+## 21st.dev Implementation
+
+### Step 2A — 21st.dev: Search (Prior-Art Check)
+
+Before generating, search marketplace:
+
+```
+21st_magic_component_search(query: <component_description>, limit: 3)
+```
+
+Evaluate top result:
+- **fit ≥ 80%**: propose adoption (do not generate new):
+  ```
+  Proposed: adopt existing component from 21st.dev marketplace
+  Component: <name> (fit: <score>%)
+  ID: <component_id>
+  Action: fetch source via 21st_magic_component_get and adapt to project DS
+  Confirm? Type "yes" to adopt or "no" to generate custom.
+  ```
+  Wait for response. "yes" → Step 2A-adopt. "no" → Step 2A-generate.
+- **fit < 80%**: proceed to Step 2A-generate.
+
+### Step 2A-adopt — Fetch and Adapt
+
+```
+21st_magic_component_get(component_id: <id>)
+```
+
+Adapt source to project DS (swap class names for Tailwind/Shadcn/Mantine equivalents).
+Build proposal for Step 3.
+
+### Step 2A-generate — Generate with Builder
+
+```
+21st_magic_component_builder(
+  description: <component_description>,
+  framework: "react",
+  style: <detected_ds>
+)
+```
+
+Inspect returned variations. Select the variant closest to project DS.
+Build proposal for Step 3.
+
+### Step 2B — 21st.dev: SVGL Brand Logo Lookup (optional)
+
+If component description includes brand name (GitHub, Vercel, Stripe, etc.):
+
+```
+svgl_get_brand_logo(brand_name: <brand>, format: "svg")
+```
+
+Add SVG to `.design/assets/<brand>-logo.svg`. Note in proposal.
+
+<!-- /impl: 21st -->
+
+---
+
+<!-- impl: magic-patterns -->
+## Magic Patterns Implementation
+
+### Step 2C — Magic Patterns: Generate
+
+Read STATE.md `<design_system>` block (written by design-context-builder Step 0C). Use as `design_system` param.
+
+```
+magic_patterns_generate(
+  description: <component_description>,
+  design_system: <detected_ds>,
+  quality_mode: "best"
+)
+```
+
+Response includes:
+- `code` — component source (React + DS class names)
+- `preview_url` — hosted preview of generated component
+- `component_id` — ID for annotate/regenerate roundtrip
+
+### Step 2C-annotate — Post DESIGN-DEBT Feedback (optional)
+
+If DESIGN-CONTEXT.md or DESIGN-DEBT.md has findings for this component type:
+
+```
+magic_patterns_annotate(
+  component_id: <component_id>,
+  feedback: "<finding text from DESIGN-DEBT>"
+)
+```
+
+Log: `✓ Feedback posted to Magic Patterns for <ComponentName>`
+
+### Step 2C-regenerate — Roundtrip (if user requests revision)
+
+After adoption, if user requests a revision:
+
+```
+magic_patterns_regenerate(
+  component_id: <component_id>,
+  updated_description: "<revised description>"
+)
+```
+
+Returns new `{ code, preview_url }`. Repeat Step 3–5 with new code.
+
+### Step 2C — Preview URL Routing
+
+After generating, write `preview_url` to STATE.md `<generator>` block (see Step 5).
+
+<!-- /impl: magic-patterns -->
+
+---
+
+## Step 3 — Build Proposal
+
+```
+Proposed component generation (1 operation):
+Component: <ComponentName>
+Output file: src/components/<ComponentName>.tsx
+Source: <21st.dev adopt|21st.dev generate|magic-patterns>
+DS target: <design_system>
+[Preview URL: <preview_url> (if magic-patterns)]
+[SVG assets: .design/assets/<brand>-logo.svg (if applicable)]
+```
+
+---
+
+## Step 4 — Confirm or Dry-Run
+
+If `--dry-run`: print `[dry-run] Proposal emitted. Pass without --dry-run to write files.` STOP.
+
+Print: `Write <ComponentName>.tsx to src/components/? Type "yes" to confirm.`
+
+Wait for response. Not "yes" → STOP with "Cancelled."
+
+---
+
+## Step 5 — Execute Write
+
+Write the component file to `src/components/<ComponentName>.tsx`.
+
+Update STATE.md `<generator>` block:
+```xml
+<generator>
+  component: <ComponentName>
+  source: <21st.dev adopt|21st.dev generate|magic-patterns>
+  component_id: <id_or_generated>
+  ds: <design_system>
+  preview_url: <preview_url_or_empty>
+  written: <ComponentName>.tsx
+  date: <today>
+</generator>
+```
+
+---
+
+## Step 6 — Summary
+
+```
+design-component-generator complete.
+Generator: <21st.dev|magic-patterns>
+Component: <ComponentName>
+Written: src/components/<ComponentName>.tsx
+DS: <design_system>
+[Preview: <preview_url>]
+```

package/agents/design-context-builder.md

@@ -1,7 +1,7 @@
 ---
 name: design-context-builder
 description: Detects existing design system state via grep/glob, runs discovery interview asking ONLY unanswered questions, produces .design/DESIGN-CONTEXT.md. Spawned by the discover stage.
-tools: Read, Write, Bash, Grep, Glob, mcp__figma-desktop__get_variable_defs, mcp__figma-desktop__get_metadata, mcp__refero__search
+tools: Read, Write, Bash, Grep, Glob, mcp__figma__get_variable_defs, mcp__figma__get_metadata, mcp__refero__search
 required_reading:
   - connections/storybook.md
 color: blue
@@ -50,10 +50,10 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
 **ToolSearch first.** Figma tools may be in the deferred tool set — calling them without a prior ToolSearch fails silently.
 
 ```
-ToolSearch({ query: "figma-desktop", max_results: 10 })
+ToolSearch({ query: "select:mcp__figma__get_variable_defs", max_results: 1 })
 ```
 
-Then call `mcp__figma-desktop__get_variable_defs` (no arguments — returns all variables in the active Figma file).
+Then call `mcp__figma__get_variable_defs` (no arguments — returns all variables in the active Figma file).
 
 > If `get_variable_defs` errors (most commonly because no Figma file is open): skip Step 0 entirely AND update `.design/STATE.md` `<connections>` to `figma: unavailable`. Proceed to Step 1 with no pre-populated decisions.
 
@@ -92,9 +92,86 @@ Note: Decisions D-XX through D-YY pre-populated from Figma variables (source: fi
       These are starting points — the interview (Step 1+) may override or remove them.
 ```
 
-Proceed to Step 1 regardless of whether Step 0 ran or was skipped.
+Proceed to Step 0A regardless of whether Step 0 ran or was skipped.
 
-## Step 0B — Storybook Component Inventory
+## Step 0A — paper.design Canvas Read (optional)
+
+**Skip if `paper-design` is `not_configured` or `unavailable` in `.design/STATE.md` `<connections>`.** Proceed to Step 0B.
+
+### If `paper-design: available`
+
+ToolSearch first — paper.design tools may be in the deferred tool set:
+
+```
+ToolSearch({ query: "mcp__paper", max_results: 5 })
+```
+
+Then call:
+1. `mcp__paper-design__get_selection` → JSON of selected canvas elements (id, type, name, bounds)
+2. `mcp__paper-design__get_jsx` → React JSX string of selected component tree
+3. `mcp__paper-design__get_computed_styles` → computed CSS values for selection
+
+If any call errors: update STATE.md to `paper-design: unavailable`. Proceed to Step 0B.
+
+Add a `<canvas_sources>` block to DESIGN-CONTEXT.md:
+```xml
+<canvas_sources>
+  <canvas source="paper.design">
+    <!-- JSX component tree and computed styles extracted from canvas selection -->
+  </canvas>
+</canvas_sources>
+```
+
+Merge canvas-sourced values alongside Figma variables, Refero refs, and other sources. If a canvas value conflicts with a Figma variable, note both values and mark as "tentative — confirm with user."
+
+Proceed to Step 0B regardless of whether Step 0A ran or was skipped.
+
+## Step 0B — pencil.dev .pen File Discovery (optional)
+
+```bash
+PEN_FILES=$(find . -name "*.pen" -not -path "*/node_modules/*" 2>/dev/null)
+```
+
+If PEN_FILES is empty: `pencil-dev: not_configured` in STATE.md. Skip.
+
+If PEN_FILES found:
+1. `pencil-dev: available` in STATE.md `<connections>`
+2. Read each `.pen` file. Extract component name, variant, design-tokens map.
+3. Add a `<pen_sources>` block to DESIGN-CONTEXT.md:
+```xml
+<pen_sources>
+  <pen file="Button.pen" component="Button" variant="primary">
+    <!-- design-tokens extracted from .pen frontmatter -->
+  </pen>
+</pen_sources>
+```
+4. Cross-reference .pen component names with grep-found component files. Flag components where `.pen` spec exists but no implementation found (DEBT: not-yet-built).
+
+Proceed to Step 0C regardless of whether Step 0B ran or was skipped.
+
+## Step 0C — Design System Detection (for component generators)
+
+Detect the project's active design system for use by `design-component-generator` (Magic Patterns, 21st.dev).
+
+Detection order:
+1. Check `gdd.config.json` (if present): read `designSystem` field → use directly if set.
+2. Scan `package.json` dependencies:
+   - `@shadcn/ui` or `shadcn` present → `"shadcn"`
+   - `@mantine/core` or `@mantine/hooks` present → `"mantine"`
+   - `@chakra-ui/react` present → `"chakra"`
+   - `tailwindcss` present → `"tailwind"`
+3. Default: `"tailwind"`
+
+Write result to STATE.md `<design_system>` block:
+```xml
+<design_system>tailwind</design_system>
+```
+
+Always runs — no skip condition. Takes < 1 second (file reads only).
+
+Proceed to Step 0D regardless of outcome.
+
+## Step 0D — Storybook Component Inventory
 
 **Skip this step if `storybook` is `not_configured` or `unavailable` in `.design/STATE.md` `<connections>`.** Proceed to Step 1 — grep-based inventory continues as before.
 
@@ -133,7 +210,7 @@ curl -sf http://localhost:6006/stories.json
 
 **If index.json fetch errors:** update STATE.md `storybook: unavailable`, fall back to grep-based inventory in Step 1. Continue without error.
 
-Proceed to Step 1 regardless of whether Step 0B ran or was skipped.
+Proceed to Step 1 regardless of whether Step 0D ran or was skipped.
 
 ## Step 1 — Auto-Detect Design System State
 

package/agents/design-discussant.md

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

package/agents/design-figma-writer.md

@@ -1,7 +1,7 @@
 ---
 name: design-figma-writer
 description: Writes design decisions back to Figma — annotations, token bindings, Code Connect mappings, and implementation-status write-back. Operates in proposal→confirm mode by default. Accepts --dry-run (emit proposal without executing) and --confirm-shared (required for writes to team library components).
-tools: Read, Write, Bash, Grep, Glob, mcp__figma__use_figma, mcp__figma-desktop__get_variable_defs, mcp__figma-desktop__get_metadata
+tools: Read, Write, Bash, Grep, Glob, mcp__figma__use_figma, mcp__figma__get_variable_defs, mcp__figma__get_metadata
 color: purple
 model: inherit
 default-tier: sonnet
@@ -34,7 +34,7 @@ ToolSearch({ query: "select:mcp__figma__use_figma", max_results: 1 })
 → Non-empty     → proceed to Step 1
 ```
 
-Note: `mcp__figma__use_figma` is the remote Figma MCP (registered as server "figma"). Distinct from `mcp__figma-desktop__*` (desktop MCP, read-only in this pipeline). If only desktop MCP is present and remote is absent, STOP with the note above.
+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.
 
 ---
 
@@ -72,15 +72,15 @@ 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 desktop MCP (reads are always desktop, writes are always remote):
+Also read the active Figma file structure using the remote MCP (reads and writes share the same server):
 
 ```
-ToolSearch({ query: "figma-desktop", max_results: 10 })
-mcp__figma-desktop__get_metadata()    // lightweight layer outline
-mcp__figma-desktop__get_variable_defs()   // for tokenize mode — variable names and values
+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
 ```
 
-If `get_metadata` errors (no file open), write: "No Figma file is open. Open the target file in the Figma desktop app and retry." and STOP.
+If `get_metadata` errors (no file accessible), write: "No Figma file is accessible. Open the target file in Figma and retry." and STOP.
 
 ---
 
@@ -157,7 +157,7 @@ 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. Remote MCP only — never use desktop MCP for writes.
+For each operation in the proposal, call `mcp__figma__use_figma` with the appropriate operation payload.
 
 For `annotate`: