@hegemonart/get-design-done 1.14.2 → 1.14.4

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.14.4] — 2026-04-20
+
+### Fixed — Figma MCP install URL was stale
+
+The docs everywhere referenced the legacy `https://mcp.figma.com/v1/sse` endpoint. Users following the current Claude Code Figma MCP flow hit "Failed to connect" because Figma has since moved the server to `https://mcp.figma.com/mcp` (Streamable HTTP). Every skill, agent, and reference doc that prints Figma install steps now uses the current URL, and the migration note tells existing users how to remove a stale registration.
+
+### Changed — Variant-agnostic Figma MCP probe
+
+- The `mcp__figma__` prefix is no longer hardcoded. The probe matches any server whose name fits `/figma/i` — remote `figma`, `Figma`, local `figma-desktop`, UUID-prefixed instances — via keyword `ToolSearch`, applies a tiebreaker (both-sets > reads-only > canonical `figma` > alphabetical), and writes the resolved `prefix=` and `writes=` capability flags to `.design/STATE.md <connections>`. Consumer skills and agents read the resolved prefix from `STATE.md` instead of hardcoding it.
+- Added preferred install path: `claude plugin install figma@claude-plugins-official` (bundles the MCP + Figma's agent skills). Manual `claude mcp add` remains supported.
+- Tool table extended with `generate_figma_design`, `search_design_system`, `create_new_file`, `whoami`, `generate_diagram`, `get_figjam`, `get_code_connect_suggestions`, `send_code_connect_mappings` — split by reads (remote + desktop) vs writes (remote-only).
+- `design-figma-writer` now STOPs early with a clear install message when only a reads-only variant (e.g. `figma-desktop`) is detected.
+- `tests/semver-compare.test.cjs` — registered `1.14.4` as a recognized off-cadence version.
+
+Cherry-picked from `c11cd7b` on `claude/upbeat-fermi-199627` — the Figma MCP fix that was authored before v1.14.2 but never merged to main, so every install doc was printing the outdated URL until this release.
+
+---
+
+## [1.14.3] — 2026-04-20
+
+### Added — `npx @hegemonart/get-design-done` installer
+
+- **`scripts/install.cjs`** — new npm-bin entrypoint (the bin slot referenced from `package.json` since v1.0.7 but never shipped). Running `npx @hegemonart/get-design-done` now atomically merges an `extraKnownMarketplaces["get-design-done"]` entry (source: `github:hegemonart/get-design-done`) and an `enabledPlugins["get-design-done@get-design-done"] = true` flag into `$CLAUDE_CONFIG_DIR/settings.json` (default `~/.claude/settings.json`). Flags: `--dry-run`, `--help`. Idempotent; preserves unrelated keys; rejects malformed settings JSON with a clear error.
+
+### Fixed — Plugin manifest bugs blocking v1.14.2 install
+
+- **`.claude-plugin/plugin.json`** — dropped `"./"` from the `skills` array. The Claude Code plugin loader rejects it as `Path escapes plugin directory: ./` even though the spec describes it as legal. Manifest now declares `"skills": ["./skills/"]` only; the plugin loads cleanly from the marketplace.
+- **`.claude-plugin/plugin.json`** — removed the explicit `"hooks": "./hooks/hooks.json"` pointer. Claude Code auto-detects `hooks/hooks.json` at the standard location, so the manifest pointer triggered `Duplicate hooks file`. Hooks still register the same PreToolUse/SessionStart/PostToolUse commands — only the redundant pointer is gone.
+- **`reference/schemas/plugin.schema.json`** — `hooks` is no longer a required field (still permitted for plugins that keep the file elsewhere).
+- **`skills/explore/SKILL.md`** — design interview now runs inline inside `/gdd:explore` instead of being delegated to a `design-discussant` subagent via `Task()`. Subagent spawns in Claude Desktop collapse `AskUserQuestion` to plain markdown; inlining restores the native-picker widget so the interview renders as interactive UI instead of chat text. `/gdd:discuss` and the handoff confirmation flow still use the subagent — only the explore-stage interview moved inline.
+- **`tests/semver-compare.test.cjs`** — registered `1.14.2` and `1.14.3` as recognized off-cadence versions.
+- **`tests/install-script.test.cjs`** — new suite (7 tests) covering the installer: bin wiring, `--help`, fresh install, idempotency, key preservation, `--dry-run` no-write, malformed-JSON exit code.
+
+---
+
 ## [1.14.2] — 2026-04-20
 
 ### Added — Multi-format Claude Design handoff ingestion

package/README.md

@@ -2,24 +2,26 @@
 
 # GET DESIGN DONE
 
+**English** · [简体中文](README.zh-CN.md)
+
 **Agent-orchestrated design pipeline for Claude Code. Five stages, thirty-three specialized agents, twelve tool connections — from brief to verified shipping work.**
 
 **Solves the "Claude made it look fine but nothing ties together" problem: no design system extraction, no reference grounding, no verification against the brief.**
 
 [![npm version](https://img.shields.io/npm/v/@hegemonart/get-design-done?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hegemonart/get-design-done)
+[![npm downloads](https://img.shields.io/npm/dm/@hegemonart/get-design-done?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hegemonart/get-design-done)
+[![GitHub stars](https://img.shields.io/github/stars/hegemonart/get-design-done?style=for-the-badge&logo=github&color=181717)](https://github.com/hegemonart/get-design-done)
 [![CI](https://img.shields.io/github/actions/workflow/status/hegemonart/get-design-done/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/hegemonart/get-design-done/actions/workflows/ci.yml)
 [![Node](https://img.shields.io/badge/node-22%20%7C%2024-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
-[![Plugin](https://img.shields.io/badge/plugin-v1.14.0-blue?style=for-the-badge)](https://github.com/hegemonart/get-design-done/releases/tag/v1.14.0)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
 <br>
 
 ```bash
-claude plugin marketplace add hegemonart/get-design-done
-claude plugin install get-design-done@get-design-done
+npx @hegemonart/get-design-done@latest
 ```
 
-**Works on macOS, Linux, and Windows. Requires Claude Code + Node 22/24.**
+**One command. Works on macOS, Linux, and Windows. Requires Claude Code + Node 22/24.**
 
 <br>
 
@@ -84,25 +86,43 @@ Built-in quality gates catch real problems: Handoff Faithfulness scoring on Clau
 
 ## Getting Started
 
-### Option A — Claude Code marketplace (recommended)
+```bash
+npx @hegemonart/get-design-done@latest
+```
+
+That's it. The installer writes a `get-design-done` marketplace entry and enables the plugin in `~/.claude/settings.json` atomically. Restart Claude Code (or run `/reload-plugins`), and the pipeline is live.
+
+**What the installer does**
+
+- Registers the `github:hegemonart/get-design-done` marketplace in `extraKnownMarketplaces`
+- Flips `enabledPlugins["get-design-done@get-design-done"]` to `true`
+- Preserves every other key in your settings — theme, permissions, other marketplaces — untouched
+- Idempotent: safe to re-run; no duplicate entries
+
+On first Claude Code launch after install, a `SessionStart` bootstrap hook provisions the companion reference library `~/.claude/libs/awesome-design-md` (idempotent — subsequent sessions run `git pull --ff-only`).
+
+### Non-interactive install (CI, Docker, scripts)
 
 ```bash
-claude plugin marketplace add hegemonart/get-design-done
-claude plugin install get-design-done@get-design-done
+# Dry-run: print the diff, don't write
+npx @hegemonart/get-design-done@latest --dry-run
+
+# Custom config dir (Docker, non-default Claude root)
+CLAUDE_CONFIG_DIR=/workspace/.claude npx @hegemonart/get-design-done@latest
 ```
 
-### Option B — npm / pnpm
+### Alternative: Claude Code CLI
 
-Published as a scoped package. Works with any npm-compatible client:
+Prefer to skip the npm package entirely? Use the native plugin CLI:
 
 ```bash
-npm  install -g @hegemonart/get-design-done
-pnpm add     -g @hegemonart/get-design-done
+claude plugin marketplace add hegemonart/get-design-done
+claude plugin install get-design-done@get-design-done
 ```
 
-Either path installs the pipeline skill and triggers a `SessionStart` bootstrap hook, which provisions the companion reference library `~/.claude/libs/awesome-design-md` on first run (idempotent — subsequent sessions run `git pull --ff-only`).
+This is what the installer wires up for you — `npx` is just one command instead of two.
 
-Verify with:
+Verify any install path with:
 
 ```
 /gdd:help
@@ -111,6 +131,22 @@ Verify with:
 > [!TIP]
 > Run Claude Code with `--dangerously-skip-permissions` for the intended frictionless flow. GDD is built for autonomous multi-stage execution; approving every file read and `git commit` defeats the purpose.
 
+### Staying Updated
+
+Get Design Done ships frequent patch releases. To pick up the latest plugin contract, run the installer again — it's idempotent and upgrades the registered marketplace entry in place:
+
+```bash
+npx @hegemonart/get-design-done@latest
+```
+
+Or from inside Claude Code:
+
+```
+/gdd:update
+```
+
+`/gdd:update` previews the changelog before applying. Local customizations in `reference/` are preserved — use `/gdd:reapply-patches` if they need re-stitching after a structural release. A `SessionStart` hook surfaces a one-line banner when a newer release is available, gated so it never interrupts an active pipeline stage.
+
 ---
 
 ## How It Works
@@ -293,7 +329,7 @@ Every connection is optional. The pipeline degrades gracefully — a grep-based
 
 | Connection | Type | Purpose |
 |-----------|------|---------|
-| Figma | MCP (`mcp__figma__*`, remote) | Token extraction, design context pre-population, write-back via `use_figma` (annotate, tokenize, Code Connect) |
+| Figma | MCP (auto-detects any `/figma/i` server — remote or desktop) | Token extraction, design context pre-population, write-back via `use_figma` (remote only; annotate, tokenize, Code Connect) |
 | Refero | MCP (`mcp__refero__*`) | Reference design search during exploration |
 | Pinterest | MCP (`mcp__mcp-pinterest__*`) | Visual inspiration boards alongside Refero |
 | Preview (Playwright) | MCP (`mcp__Claude_Preview__*`) | Live page screenshots for visual verification |
@@ -567,13 +603,23 @@ All connections are optional — the pipeline degrades gracefully when any conne
 
 ### Figma MCP (reads + writes)
 
-One remote MCP covers both reads and writes. When active, `explore` reads Figma variables and pre-populates design decisions from your file, and `design-figma-writer` writes decisions back via `use_figma` — annotates frames, tokenizes local styles, registers Code Connect mappings. Proposal → confirm discipline with `--dry-run` and `--confirm-shared` guards. Falls back to code-only analysis when the MCP is not configured. One install command unlocks both:
+The pipeline auto-detects any Figma MCP variant — remote (reads + writes) or desktop (reads only). When active, `explore` reads Figma variables and pre-populates design decisions from your file, and `design-figma-writer` writes decisions back via `use_figma` — annotates frames, tokenizes local styles, registers Code Connect mappings. Proposal → confirm discipline with `--dry-run` and `--confirm-shared` guards. Falls back to code-only analysis when no Figma MCP is configured.
+
+**Preferred install (Claude Code plugin — bundles MCP + Figma's official skills):**
 
 ```
-claude mcp add figma --transport http https://mcp.figma.com/v1/sse
+claude plugin install figma@claude-plugins-official
 ```
 
-Setup: [`connections/figma.md`](connections/figma.md). If you previously installed the local `figma-desktop` MCP, you can remove it — its read tools are now exposed on the remote server.
+**Manual install (remote MCP — reads + writes):**
+
+```
+claude mcp add --transport http figma https://mcp.figma.com/mcp
+```
+
+**Desktop MCP (reads only):** optionally enabled via the Figma desktop app's Dev Mode. Useful when writes are not needed. Register under server name `figma-desktop` — the probe auto-detects it.
+
+Setup: [`connections/figma.md`](connections/figma.md). If you previously registered the remote MCP with the legacy URL `https://mcp.figma.com/v1/sse`, remove and re-add with the current URL `https://mcp.figma.com/mcp` (Streamable HTTP).
 
 ### Refero MCP
 
@@ -823,10 +869,7 @@ The forensic mode runs a 6-check integrity audit — stale artifacts, dangling d
 Set `enforcement_mode: "log"` in `.design/budget.json` — the hook writes every decision to `.design/telemetry/costs.jsonl` without blocking.
 
 **Updating to the latest version?**
-```
-/gdd:update
-```
-Previews the changelog before applying. Local customizations in `reference/` are preserved; use `/gdd:reapply-patches` if they need re-stitching after a structural update.
+See [Staying Updated](#staying-updated). Short version: `npx @hegemonart/get-design-done@latest` or `/gdd:update`.
 
 ### Uninstall
 
@@ -834,13 +877,13 @@ Previews the changelog before applying. Local customizations in `reference/` are
 claude plugin uninstall get-design-done@get-design-done
 ```
 
-Or, if installed via npm:
+To reverse the `npx` installer, remove the two keys it wrote — either by hand or with a one-liner:
 
 ```bash
-npm uninstall -g @hegemonart/get-design-done
+node -e "const f=require('os').homedir()+'/.claude/settings.json';const j=require(f);delete j.extraKnownMarketplaces?.['get-design-done'];delete j.enabledPlugins?.['get-design-done@get-design-done'];require('fs').writeFileSync(f,JSON.stringify(j,null,2))"
 ```
 
-This removes all GDD skills, agents, hooks, and settings while preserving your other configurations and your `.design/` project artifacts.
+This removes all GDD skills, agents, hooks, and registration while preserving your other configurations and your `.design/` project artifacts.
 
 ---
 

package/README.zh-CN.md

@@ -0,0 +1,353 @@
+<div align="center">
+
+# GET DESIGN DONE
+
+[English](README.md) · **简体中文**
+
+**面向 Claude Code 的 Agent 编排设计工作流。五个阶段，三十三个专用 Agent，十二个工具接入 —— 从设计简报直达可发布的验证结果。**
+
+**专治 "Claude 看起来做得还行，但整套东西对不上" 的老毛病：没有抽取设计系统、没有参考对齐、没有回到简报做验证。**
+
+[![npm version](https://img.shields.io/npm/v/@hegemonart/get-design-done?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hegemonart/get-design-done)
+[![npm downloads](https://img.shields.io/npm/dm/@hegemonart/get-design-done?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hegemonart/get-design-done)
+[![GitHub stars](https://img.shields.io/github/stars/hegemonart/get-design-done?style=for-the-badge&logo=github&color=181717)](https://github.com/hegemonart/get-design-done)
+[![CI](https://img.shields.io/github/actions/workflow/status/hegemonart/get-design-done/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI)](https://github.com/hegemonart/get-design-done/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/badge/node-22%20%7C%2024-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx @hegemonart/get-design-done@latest
+```
+
+**一条命令即可安装。支持 macOS、Linux、Windows。依赖 Claude Code + Node 22/24。**
+
+<br>
+
+*"Claude 写代码很快。Get Design Done 让它也能把设计交付出来。"*
+
+<br>
+
+[为什么做这个](#为什么做这个) · [快速开始](#快速开始) · [工作流程](#工作流程) · [命令列表](#命令列表) · [配置](#配置) · [故障排查](#故障排查)
+
+</div>
+
+---
+
+> [!IMPORTANT]
+> ### 已有 Claude Design 导出包？
+>
+> 如果你从 [claude.ai/design](https://claude.ai/design) 导出了设计，可以直接跳过前三个阶段：
+>
+> ```
+> /gdd:handoff ./my-design.html
+> ```
+>
+> 此命令会把导出包里的 CSS 自定义属性解析成 D-XX 设计决策，运行带 Handoff Faithfulness 评分的验证流程，并可选地把实现状态写回 Figma。格式说明见 [`connections/claude-design.md`](connections/claude-design.md)。
+
+---
+
+## 为什么做这个
+
+我是一个用 Claude Code 发布产品的设计师。代码侧的工作流（GSD、Speckit、BMAD）已经很成熟，设计侧还没有。
+
+反复遇到的问题是：Claude 生成 UI 很乐意，但输出是**脱节的**。Token 对不上既有设计系统、对比度悄悄跌破 WCAG、层级每个页面都重新发明一遍、旧项目里的反模式渗进新项目。所有这些问题要到 PR review 才被发现，因为没人把结果回到最初的设计简报上做校验。
+
+所以我做了 Get Design Done。哲学与 GSD 一致 —— **复杂度在系统里，不在你的工作流里**。幕后：三十三个专用 Agent、一个可查询的 intel 存储、按模型分层的路由、十二个工具接入、基于遥测的自我改进循环。台前：几个直接能用的命令。
+
+流水线既完成工作，也对工作做验证。我信任这个流程。它把设计交付出来。
+
+— **Hegemon**
+
+---
+
+设计侧的 "vibecoding" 和代码侧一样会失败：你描述想要什么，AI 生成看起来像回事的东西，一上规模就垮 —— 因为没有任何东西把产出回拴到最初的简报。
+
+Get Design Done 修的就是这个。它是 Claude Code 里设计工作的上下文工程层。捕获简报、清点系统、在真实参考里扎根、拆解成原子化的设计任务、回到简报上做验证 —— 然后发布。
+
+---
+
+## 适合谁
+
+任何用 Claude Code 发布 UI、且希望结果确实站得住的人 —— 工程师、设计师、design engineer、solo 创始人都合适。如果你在意 token 对齐、对比度过 WCAG、结果能回到最初需求，这就是给你的。
+
+你不必是专业设计师。流水线自己承担设计专业部分 —— 它抽取系统、在参考里扎根、回到简报做校验，并捕获那些普通人常漏掉的问题。
+
+内建的质量闸门会抓真实问题：Claude Design 导出包的 Handoff Faithfulness 评分、调色板 × 表面矩阵的完整对比度审计、NNG 反模式目录检测、暗色模式架构校验、以及动效系统一致性检查。
+
+### v1.14.0 亮点
+
+- **AI-native 画布工具** —— paper.design（MCP 画布读写、截图验证）和 pencil.dev（git 追踪的 `.pen` 规格文件，不需要 MCP）补齐了一条完整的 canvas→code→verify→canvas 往返链路。
+- **组件生成器** —— 21st.dev Magic MCP 在任何 greenfield 构建前加入先例匹配闸门；Magic Patterns 生成带 `preview_url` 的 DS-aware 组件用于视觉校验。两者都接入同一个 `design-component-generator` Agent。
+- **十二个工具接入** —— 新增四个（paper.design、pencil.dev、21st.dev、Magic Patterns），加上原有的八个。全部可选；任何接入缺席时流水线会优雅地降级到回退方案。
+
+---
+
+## 快速开始
+
+```bash
+npx @hegemonart/get-design-done@latest
+```
+
+就这一条。安装器会**原子地**把 `get-design-done` 市场条目写入 `~/.claude/settings.json`，并启用插件。重启 Claude Code（或运行 `/reload-plugins`）之后，流水线就上线了。
+
+**安装器做了什么**
+
+- 在 `extraKnownMarketplaces` 里注册 `github:hegemonart/get-design-done` 市场
+- 将 `enabledPlugins["get-design-done@get-design-done"]` 置为 `true`
+- 保留 settings 里的其他所有键 —— 主题、权限、其他市场 —— 完全不动
+- 幂等：可以重复运行；不会产生重复条目
+
+首次启动 Claude Code 时，`SessionStart` bootstrap 钩子会自动准备参考库 `~/.claude/libs/awesome-design-md`（幂等，后续会话只执行 `git pull --ff-only`）。
+
+### 非交互安装（CI、Docker、脚本）
+
+```bash
+# 预演：只打印 diff，不实际写入
+npx @hegemonart/get-design-done@latest --dry-run
+
+# 自定义配置目录（Docker，或非默认 Claude 根目录）
+CLAUDE_CONFIG_DIR=/workspace/.claude npx @hegemonart/get-design-done@latest
+```
+
+### 另一种方式：Claude Code CLI
+
+不想经过 npm 包？直接用原生插件 CLI：
+
+```bash
+claude plugin marketplace add hegemonart/get-design-done
+claude plugin install get-design-done@get-design-done
+```
+
+这就是安装器帮你做的事情 —— `npx` 只是把两条命令合成了一条。
+
+任何安装方式都可以通过下面这条命令验证：
+
+```
+/gdd:help
+```
+
+> [!TIP]
+> 建议以 `--dangerously-skip-permissions` 方式运行 Claude Code，以获得流畅的自动化体验。GDD 设计用于自主的多阶段执行；每次读文件和 `git commit` 都要人工批准会抵消全部意义。
+
+### 保持最新
+
+Get Design Done 发版频繁。要拿到最新的插件契约，只需要**再跑一次安装器** —— 它是幂等的，会就地更新已注册的市场条目：
+
+```bash
+npx @hegemonart/get-design-done@latest
+```
+
+也可以在 Claude Code 里直接运行：
+
+```
+/gdd:update
+```
+
+`/gdd:update` 会在应用前预览 changelog。`reference/` 目录下的本地修改会被保留 —— 如果结构性更新后需要重新 stitch，用 `/gdd:reapply-patches`。当有新版本时，`SessionStart` 钩子会显示一行横幅通知，并被门控逻辑保护，绝不会打断正在运行的流水线阶段。
+
+---
+
+## 工作流程
+
+> **新接入既有代码库？** 先运行 `/gdd:map`。它会并行派出 5 个专业 mapper（tokens、components、visual hierarchy、a11y、motion）并写入 `.design/map/` —— 这些结构化数据是 Explore 阶段的高质量输入，比基于 grep 的回退方案好得多。
+
+### 1. Brief（简报）
+
+```
+/gdd:brief
+```
+
+一条命令在任何扫描或探索之前先捕获设计问题。此 skill 通过 `AskUserQuestion` 一次一问 —— 只针对未回答的部分：问题、受众、约束、成功指标、范围。
+
+### 2. Explore（勘察）
+
+```
+/gdd:explore
+```
+
+清点当前代码库的设计系统：颜色、排版、间距、组件、动效、可访问性、暗色模式。产出 `.design/DESIGN.md`、`.design/DESIGN-DEBT.md`、`.design/DESIGN-CONTEXT.md`。也会以 `AskUserQuestion` 采访方式补充未在代码里暴露的决策。
+
+### 3. Plan（计划）
+
+```
+/gdd:plan
+```
+
+将 Explore 产出分解为原子化、带 wave 编排和依赖分析的设计任务，写入 `DESIGN-PLAN.md`。每个任务有明确的 Touches 字段、可并行性标签和验收准则。
+
+### 4. Design（执行）
+
+```
+/gdd:design
+```
+
+按 wave 顺序执行计划中的任务。每个任务派出专用 executor Agent，带原子 git commit，并根据代码内上下文偏差规则自动处理偏差。
+
+### 5. Verify（验证）
+
+```
+/gdd:verify
+```
+
+回到简报做验证 —— 必须达成项、NNG 启发式、审计评分、token 集成检查。失败时产出结构化 gap 列表；可通过 `/gdd:audit` 进入 verify→fix 循环。
+
+### 6. Ship → Reflect → 下一轮
+
+验证通过之后，`/gdd:ship` 生成干净的 PR 分支，`/gdd:reflect` 输出改进建议，`/gdd:apply-reflections` 审核并应用；`/gdd:new-cycle` 开启新的设计周期。
+
+---
+
+## 为什么能行
+
+### 上下文工程
+
+Claude Code 功能强大，**前提是**你给它喂足了上下文。多数人没有。
+
+GDD 替你处理：
+
+| 文件 | 作用 |
+|------|------|
+| `.design/BRIEF.md` | 本次周期的设计问题、受众、成功指标 |
+| `.design/DESIGN.md` | 当前设计系统快照（tokens、组件、层级） |
+| `.design/DESIGN-CONTEXT.md` | D-XX 决策、采访答案、上下游约束 |
+| `.design/DESIGN-PLAN.md` | 原子化任务、wave 编排、依赖 |
+| `.design/DESIGN-VERIFICATION.md` | 验证结果、gap 列表、Handoff Faithfulness 评分 |
+| `.design/intel/` | 可查询的知识层：token 扇出、组件 call-graph、决策溯源 |
+
+### 33 个专用 Agent
+
+每个阶段都是 "薄编排器 + 专用 Agent" 的模式。编排器本身很轻，重活由 Agent 在全新的 200k 上下文窗口里做，不占用你会话的主上下文。
+
+### 12 个工具接入
+
+Figma、Refero、Pinterest、Storybook、Chromatic、Claude Design、Playwright 预览、Graphify 知识图谱、paper.design、pencil.dev、21st.dev、Magic Patterns。全部可选；任何一个缺席时流水线都会优雅降级到回退方案。
+
+### 原子化 git commit
+
+每个设计任务独立提交。Git bisect 能精确定位失败任务；每个任务都可以独立 revert；在 AI 自动化流程里带来更好的可观测性。
+
+### 自我改进
+
+每次周期结束后，reflector Agent 读取遥测、learnings 和 Agent 指标，生成 `reflections/<slug>.md` 具体改进提案。用 `/gdd:apply-reflections` 审核并选择性应用。
+
+---
+
+## 命令列表
+
+### 核心流水线
+
+| 命令 | 作用 |
+|------|------|
+| `/gdd:brief` | 阶段 1 — 捕获设计简报 |
+| `/gdd:explore` | 阶段 2 — 清点代码库 + 采访补齐上下文 |
+| `/gdd:plan` | 阶段 3 — 生成 DESIGN-PLAN.md |
+| `/gdd:design` | 阶段 4 — 按 wave 执行计划 |
+| `/gdd:verify` | 阶段 5 — 回到简报做验证 |
+| `/gdd:ship` | 生成干净的 PR 分支 |
+| `/gdd:next` | 根据 STATE.md 自动路由到下一阶段 |
+
+### 生命周期
+
+| 命令 | 作用 |
+|------|------|
+| `/gdd:new-project` | 初始化新的 GDD 项目 |
+| `/gdd:new-cycle` | 开启新的设计周期 |
+| `/gdd:complete-cycle` | 归档当前周期 |
+| `/gdd:pause` / `/gdd:resume` | 会话暂停/恢复 |
+
+### 独立命令（无需流水线初始化）
+
+| 命令 | 作用 |
+|------|------|
+| `/gdd:handoff` | 直接摄取 Claude Design 导出包 |
+| `/gdd:style` | 为单个组件生成交付文档 |
+| `/gdd:darkmode` | 暗色模式审计 |
+| `/gdd:figma-write` | 把决策写回 Figma |
+| `/gdd:sketch` / `/gdd:spike` | 丢弃式原型 / 技术验证 |
+| `/gdd:fast` / `/gdd:quick` | 轻量任务的快速路径 |
+
+完整命令列表运行 `/gdd:help` 查看。
+
+---
+
+## 配置
+
+核心配置在 `.design/config.json`。通过 `/gdd:settings` 管理。
+
+### 模型档位
+
+| 档位 | 规划 | 执行 | 验证 |
+|------|------|------|------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced`（默认） | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
+| `inherit` | 跟随当前运行时 | 跟随 | 跟随 |
+
+切换档位：
+
+```
+/gdd:settings profile budget
+```
+
+### 预算与优化
+
+- `.design/budget.json` 里的 `per_task_cap_usd` / `per_phase_cap_usd` 由 PreToolUse `budget-enforcer` 钩子强制执行
+- 成本遥测写到 `.design/telemetry/costs.jsonl`
+- `/gdd:warm-cache` 跨所有 Agent 预热 Anthropic 的 5 分钟 prompt 缓存
+- `/gdd:optimize` 基于遥测与 Agent 指标给出规则化建议
+
+---
+
+## 故障排查
+
+**安装后找不到命令？**
+- 重启 Claude Code 以重新加载 skills
+- 用 `/gdd:help` 确认插件已注册
+- 确认 `~/.claude/settings.json` 里有 `enabledPlugins["get-design-done@get-design-done"]: true`
+
+**流水线卡住或产物缺失？**
+
+```
+/gdd:health
+/gdd:progress --forensic
+```
+
+Forensic 模式运行一个 6 项检查的完整性审计 —— 陈旧产物、悬空决策、未完成的 handoff、孤立 cycle、schema 漂移、injection scanner 告警。
+
+**想看 router 和 budget-enforcer 在做什么？**
+
+在 `.design/budget.json` 里把 `enforcement_mode` 设为 `"log"` —— 钩子会把每个决策记录到 `.design/telemetry/costs.jsonl` 但不做阻断。
+
+**升级到最新版？**
+
+见 [保持最新](#保持最新)。短版本：`npx @hegemonart/get-design-done@latest` 或 `/gdd:update`。
+
+### 卸载
+
+```bash
+claude plugin uninstall get-design-done@get-design-done
+```
+
+若要回滚 `npx` 安装器写入的两个键，手动删除或用下面这条命令：
+
+```bash
+node -e "const f=require('os').homedir()+'/.claude/settings.json';const j=require(f);delete j.extraKnownMarketplaces?.['get-design-done'];delete j.enabledPlugins?.['get-design-done@get-design-done'];require('fs').writeFileSync(f,JSON.stringify(j,null,2))"
+```
+
+这会移除所有 GDD 的 skill、agent、hook 和注册信息，同时保留你的其他配置和项目 `.design/` 产物。
+
+---
+
+## License
+
+MIT License。详见 [LICENSE](LICENSE)。
+
+---
+
+<div align="center">
+
+**Claude Code 很强。Get Design Done 让它能把设计交付出来。**
+
+</div>

package/agents/design-context-builder.md

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

package/agents/design-discussant.md

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