@hegemonart/get-design-done 1.30.6 → 1.31.5

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). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.30.6"
+    "version": "1.31.5"
   },
   "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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.30.6",
+      "version": "1.31.5",
       "author": {
         "name": "hegemonart"
       },
@@ -68,7 +68,10 @@
         "gemini",
         "mcp",
         "parallel-agents",
-        "agent-sdk"
+        "agent-sdk",
+        "figma",
+        "extractor",
+        "design-system-sync"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.30.6",
+  "version": "1.31.5",
   "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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",
@@ -62,7 +62,10 @@
     "agent-sdk",
     "mcp-server",
     "context-loading",
-    "cross-session"
+    "cross-session",
+    "figma",
+    "extractor",
+    "design-system-sync"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,111 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.31.5] - 2026-05-29
+
+### Phase 31.5 — Repo Structure Consolidation
+
+One audit-clean repo layout with **zero changes to the public surface** (commands, agents, skills, hooks, connections, install flow) and **no file content lost**. The SDK that `plugin.json` has advertised since v1.20.0 now actually lives in `sdk/`; the npm tarball ships only what plugin users need; the repo root is decluttered. Every move was history-preserving (`git mv`), guarded by three independent regression nets (test-parity, tarball-diff golden, headless-E2E install) and a one-minor deprecation-shim grace window. 10 plans + 1 follow-up across Waves A–E (31-5-01..31-5-10 + 31-5-9.5).
+
+### Added
+
+- **`sdk/` — the public SDK, collected.** `git mv` consolidated the strewn modules into one place: `sdk/cli`, `sdk/state`, `sdk/event-stream`, `sdk/errors`, `sdk/primitives/*` (the 4 typed `.cjs`+`.d.cts` pairs), and **both** MCP servers under `sdk/mcp/` (`sdk/mcp/gdd-state`, `sdk/mcp/gdd-mcp` — D-08). A `sdk/index.ts` barrel re-exports the surface, and `sdk/README.md` (≤120 lines, D-06) documents what the SDK is with a per-module import-path table (module → public import → helpers → stability tag). Public import paths are explicit per-module (`/sdk/cli`, `/sdk/state`, `/sdk/event-stream`, `/sdk/primitives/*`, `/sdk/errors`, `/sdk/mcp/gdd-state`, `/sdk/mcp/gdd-mcp`) plus the barrel (D-04).
+- **3 SDK bins that now work from an npm install.** `bin/gdd-sdk`, `bin/gdd-state-mcp`, and `bin/gdd-mcp` are dual-mode trampolines (prefer a compiled `.js` sibling, fall back to `.ts` strip in-repo). A `prepack` step (`npm run build:sdk` → esbuild) bundles the three TS-entry bins to self-contained CommonJS siblings that ship in the tarball — fixing a **pre-existing latent break**: raw `.ts` bins cannot run under `--experimental-strip-types` from inside `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), which had silently shipped since the TS bins were introduced. The `.ts` remain the source of truth; the `.js` are gitignored build artifacts (`postpack` cleans them).
+- **`recipes/` scaffold** — `recipes/` + a recipe-loader + `reference/schemas/recipe.schema.json`. Ships empty of recipes (the loading machinery, not content).
+- **`docs/i18n/`** — the 6 `README.{de,fr,it,ja,ko,zh-CN}.md` translations relocated from the repo root (D-11). English `README.md` stays at root; its language-selector links were repointed.
+- **`.npmignore`** — a defense-in-depth duplicate of the `package.json` `files` allowlist (D-10).
+- **Private-files CI guard** — `test/suite/no-private-files-tracked.test.cjs` asserts 0 tracked `.planning/` / `REVIEW.md` / `tmp_support_preview*` files so the (already-remediated) leak stays closed (D-03).
+- **`no-stale-internal-refs` static guard** — `test/suite/no-stale-internal-refs.test.cjs` greps the shipped user-facing surface (hooks/, agents/, skills/, bin/, scripts/cli/, scripts/install.cjs) for any reference to an OLD moved-SDK path and fails on any hit outside a deprecation shim. Proves every internal caller was repointed to `sdk/`.
+
+### Changed
+
+- **`package.json` `files` narrowed to an explicit allowlist (+ `.npmignore`).** Maintainer-only top-level scripts no longer reach a user's `node_modules`. **Tarball diff vs the prior (v1.31.0) tarball:**
+  - **ADDED:** `sdk/` (the SDK, incl. the 3 compiled-bin `.js` siblings), `recipes/`, `docs/i18n/`, `NOTICE`.
+  - **DROPPED (23 maintainer-only files):** `scripts/` wholesale + the top-level `bootstrap*`, `rollback-release.sh`, `apply-branch-protection.sh`, `release-smoke-test.cjs`, `verify-version-sync.cjs`, `extract-changelog-section.cjs`, `detect-stale-refs.cjs`, `run-injection-scanner-ci.cjs`, `injection-patterns.cjs`, `build-*.cjs`, `validate-*` (`.cjs`/`.ts`), `codegen-schema-types.ts`, `aggregate-agent-metrics.ts`, `lint-agentskills-spec.cjs`, `scripts/e2e/`, `scripts/tests/`.
+  - **KEPT (runtime subtrees, D-09) — a "drop `scripts/` wholesale" allowlist would have shipped a *broken* package:** `scripts/lib/` (incl. `scripts/lib/graph/` for `gdd-graph` per D-14 and `scripts/lib/figma-extract/` for the figma-extract SKILL per D-15), `scripts/mcp-servers/` (the residual MCP deprecation shims), `scripts/cli/` (the `gdd-events` target), and `scripts/install.cjs`.
+  - Tarball golden manifest pinned at **620 paths** (paths-only per D-07).
+- **`tests/` → `test/suite/` and `test-fixture/` → `test/fixtures/`** (D-12) — a pure mechanical, history-preserving relocation done with an identical full-suite pass before/after. Contributor-facing only; not shipped in the tarball. All subsequent tests are authored into `test/suite/`.
+
+### Deprecated
+
+- **`scripts/lib/{cli,gdd-state,event-stream,gdd-errors}/`, the 4 primitive `.cjs` (`error-classifier`, `iteration-budget`, `jittered-backoff`, `lockfile`), and `scripts/mcp-servers/{gdd-state,gdd-mcp}/server.ts` are now thin deprecation shims** that re-export from `sdk/*` and emit a one-time `DeprecationWarning`. They exist for undocumented EXTERNAL importers who reached into `node_modules/.../scripts/lib/...` directly. **Removed in v1.33.0** (D-02). Grace window: v1.31.5 ships with shims → v1.32.0 still has them → v1.33.0 removes them with a breaking-change note. **If you imported from `node_modules/@hegemonart/get-design-done/scripts/lib/...` directly, switch to `sdk/...`** (e.g. `scripts/lib/cli` → `sdk/cli`, `scripts/lib/error-classifier.cjs` → `sdk/primitives/error-classifier.cjs`, `scripts/mcp-servers/gdd-state/server.ts` → `sdk/mcp/gdd-state/server.ts`). Internal callers already use `sdk/`.
+
+### Backward compatibility
+
+- Public surface unchanged — no command, agent, skill, hook, or connection was renamed (zero-rename discipline). All install flows and all 6 bins resolve identically; MCP handshakes and primitive imports verified by the headless pack→install→run E2E.
+- 6-manifest lockstep at v1.31.5 (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`).
+
+### Decisions
+
+- **D-01**: Target version is **v1.31.5** (the stale ROADMAP v1.28.0 was a pre-renumber artifact — the phase was renumbered 2026-05-16 to monotonic-with-phase-number).
+- **D-02**: Deprecation-shim removal target is **v1.33.0** (the stale ROADMAP v1.29.0 is already shipped/past). One-minor grace window.
+- **D-03**: The private-file leak was already remediated on main; Plan 01 ships only the CI guard.
+- **D-08**: `gdd-mcp` (Phase 27.7) folded in for full symmetry with `gdd-state-mcp` — both MCP servers live under `sdk/mcp/`.
+- **D-09**: The `files` allowlist keeps the runtime subtrees `scripts/lib` + `scripts/mcp-servers` + `scripts/cli` + `scripts/install.cjs` so `gdd-graph`, `figma-extract`, and `gdd-mcp` keep working.
+
+---
+
+## [1.31.0] - 2026-05-29
+
+### Phase 31 — Figma Off-Context Extractor + Variables Sync Plugin
+
+Ships `gdd-figma-extract` — pull a whole Figma design system into a compact, queryable local digest (`DESIGN.md` + `tokens.json` + `components.json`) **without the raw JSON ever entering Claude's context**. One command extracts the file via the Figma REST API to a local raw cache; a separate digest stage reduces it to an LLM-readable spec. Plus a thin **"GDD Sync"** Figma plugin that fills the Variables-API-Enterprise gap by reading `figma.variables` from inside Figma (works on any plan — including Free) and POSTing them to an ephemeral localhost receiver. 10 plans across 4 waves: Wave A (raw puller + digest + styles resolver + SKILL), Wave B (plugin scaffold + export + receiver), Wave C (`--component` slice + `figma_extract` health check), Wave D (closeout).
+
+### Motivation — the spike trail
+
+Spike 001 (commit `c3a9cf6`, `.planning/spikes/001-figma-offcontext-extractor/`) validated the economics: **898× compression** (223 MB raw → 254 KB digest), a 15.7K-token DESIGN.md (under the 20K target), 127 component sets + 40 singletons captured with variants/props/defaults, ~33s wall time, and crucially **0 Claude tokens + 0 Figma MCP calls during extraction**. This is the economic alternative to Figma MCP for whole-design-system workflows (Figma MCP remains correct for spot questions on individual components). The spike surfaced two gaps, both closed by this phase:
+
+1. **Variables API → 403 (Enterprise-only)** — closed by **Path C** (the GDD Sync plugin reads variables locally and POSTs to the receiver).
+2. **Legacy styles → 0 tokens** — closed by **Path B** (two-step `/styles` + `/nodes?ids=` lookup; published-style source nodes live in canvas frames, not the main document tree).
+
+### Added
+
+- **`gdd-figma-extract` off-context extractor** — the two-stage pipeline (D-01: extract → digest stay separated, re-digest without re-pulling):
+  - `scripts/lib/figma-extract/pull.cjs` — productionized Figma REST puller (retry/backoff, version-based cache invalidation with 1h TTL fallback per D-11, drops `geometry=paths` per D-03). Writes raw JSON to disk only; raw bodies never returned to a logging caller.
+  - `scripts/lib/figma-extract/digest.cjs` — reads the raw cache, walks the node tree with **variant rollup** (D-02 — naive walk inflates ~16×), assembles tokens via the 3-path chain, renders `DESIGN.md` + `tokens.json` + `components.json`.
+  - `scripts/lib/figma-extract/styles-resolver.cjs` — **Path B** two-step `/styles` + `/nodes?ids=` resolver (fixes the spike's 0-tokens bug).
+  - `scripts/lib/figma-extract/render-md.cjs` + `walk.cjs` — deterministic, byte-stable DESIGN.md renderer + the variant-rollup walker.
+- **Three-path token extraction (D-04)** with a fallback chain — Path A (Variables API, Enterprise; 403 skipped silently), Path B (`/styles` + `/nodes`), Path C (plugin sync). Resolution priority on collision: Variables > plugin sync > styles, with a `--prefer-styles` escape hatch.
+- **"GDD Sync" Figma plugin** (`figma-plugin/`, D-05) — TypeScript, single "Export to GDD" button. Reads ALL local variables (D-13 — digest filters later), resolves aliases + modes, and POSTs to the localhost receiver.
+- **Localhost receiver** (`scripts/lib/figma-extract/receiver.cjs`, D-06) — ephemeral, **127.0.0.1-only**, port hardcoded to 5179, schema-validated, refuses non-loopback remotes, exits on first valid receipt or timeout.
+- **`--component <name|glob>` digest slice** (D-08) — a ~500-token per-component slice instead of the full ~16K digest; strictly additive (omitting it reproduces the full digest unchanged).
+- **`figma_extract` health check** (Plan 31-09) — `/gdd:health` now reports one of three exact states: `figma extract: ready (token set)`, `figma extract: token missing`, or `figma extract: plugin sync needed for variables (Free tier detected)`. Presence-only token check (D-10); the Free-tier signal is read from the local raw-pull cache only (no network call).
+- **`skills/figma-extract/SKILL.md`** (`name: gdd-figma-extract`) — off-context orchestration that never instructs reading `raw/*.json` (D-12).
+- **`tests/phase-31-baseline.test.cjs`** + 6 baseline files at `test-fixture/baselines/phase-31/` (design-md, components-json, tokens-json, health-line, manifest-network-scope, token-isolation-static), **`tests/phase-31-end-to-end.test.cjs`** (offline pull+digest against fixtures), and **`tests/figma-extract-token-isolation.test.cjs`** (the D-10 static scanner + meta-tests).
+
+### Security & guarantees
+
+- **Off-context guarantee (D-12) — statically enforced.** The SKILL never instructs reading `raw/*.json`; the digest is a pure function of the raw cache. The raw pull consumes 0 Claude tokens.
+- **Token isolation (D-10) — statically enforced.** `FIGMA_TOKEN` (fallback `FIGMA_PERSONAL_ACCESS_TOKEN`) is read from the environment only and is sent ONLY as the `X-Figma-Token` request header — never logged, never written to disk. `tests/figma-extract-token-isolation.test.cjs` scans every file under `scripts/lib/figma-extract/` for any `writeFile`/`appendFile`/`console.*`/`logger.*`/`process.std*.write` call referencing the token and fails on a non-zero count (meta-tested to prove the scanner is not vacuous).
+- **Receiver network scope (D-06).** The plugin manifest's `allowedDomains` is exactly the localhost pair (`http://localhost:5179`, `http://127.0.0.1:5179`) — any widening trips the baseline test. No external host, no wildcard.
+
+### Deferred
+
+- **Live Figma validation (D-07).** The phase ships with hermetic offline tests (stubbed fetch against committed fixtures); a one-time end-to-end run against a real Figma file with a live token is a maintainer follow-up, not a v1.31.0 blocker. Plugin Community-directory submission is likewise deferred (dev-install path ships now).
+
+### Decisions (D-01 through D-13)
+
+- **D-01**: Two-stage pipeline (extract → digest) stays separated. Re-run digest without re-pulling.
+- **D-02**: Variant rollup default-on — skip COMPONENT children of a COMPONENT_SET; record variants as a field on the parent (naive walk inflates ~16×).
+- **D-03**: Drop the `geometry=paths` query param (~30% smaller raw; geometry is discarded in the digest).
+- **D-04**: Three-path token extraction with a fallback chain (Variables > plugin sync > styles; `--prefer-styles` escape).
+- **D-05**: "GDD Sync" plugin as a separate `figma-plugin/` package (TypeScript, single button).
+- **D-06**: Receiver is ephemeral + 127.0.0.1-only + hardcoded port 5179; refuses non-loopback; closes on receipt or timeout.
+- **D-07**: Plugin distribution is dev-build now, Community submission as a follow-up; live-Figma validation is a maintainer follow-up — neither blocks v1.31.0.
+- **D-08**: `--component <name|glob>` filter on digest for per-component slicing (~500 tokens vs ~16K).
+- **D-09**: Raw cache gitignored (`.figma-extract-cache/`), reproducible from `pull.cjs`; `digest/` artifacts may be committed.
+- **D-10**: Token never logged or persisted — `FIGMA_TOKEN` from env only; CI static-analysis test enforces it library-wide.
+- **D-11**: Cache invalidation is content-based via Figma's `version` field, with a 1h wall-clock TTL fallback.
+- **D-12**: Off-context guarantee enforced statically — the skill never instructs reading `raw/*.json`.
+- **D-13**: Plugin emits ALL local variables (not just published-collection ones); filtering happens at the digest stage.
+
+### Backward compatibility
+
+- 4-manifest + 2 Tier-2 manifest lockstep at v1.31.0 (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`). Keywords `figma`, `extractor`, `design-system-sync` added across the manifest keyword arrays.
+- `NOTICE` preserved verbatim — Phase 31 productionizes our own spike (`c3a9cf6`) and uses Figma's official REST + plugin APIs plus `@figma/plugin-typings` (a normal npm devDependency, not a vendored code transplant). No third-party CODE was vendored, so no new attribution is owed.
+
+---
+
 ## [1.30.6] - 2026-05-28
 
 ### Phase 30.6 — Graphify Self-Ownership

package/NOTICE

@@ -0,0 +1,224 @@
+get-design-done
+Copyright (c) 2026 hegemonart
+
+This product includes software developed by third parties under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for the full license text.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 27 — Peer-CLI Delegation Layer (v1.27.0, 2026-04-30)
+──────────────────────────────────────────────────────────────────────────────
+
+The peer-CLI delegation layer ports protocol shapes and skill patterns from:
+
+  greenpolo/cc-multi-cli-plugin (https://github.com/greenpolo/cc-multi-cli-plugin)
+  License: Apache License, Version 2.0
+  Version reference: cc-multi-cli v2.0.0 (shipped 2026-04-24)
+
+The following gdd files re-derive logic, contracts, or procedural patterns
+from cc-multi-cli's source. We re-derive in our own runtime (CommonJS in
+gdd's case; cc-multi-cli ships ESM); we do NOT vendor their runtime —
+their hub assumes Claude-as-host while gdd needs any-runtime-as-host.
+Attribution is provided here per Apache 2.0 §4.
+
+  scripts/lib/peer-cli/acp-client.cjs
+    └─ Adapts the line-delimited JSON-RPC + initialize/prompt/notification
+       framing from cc-multi-cli's `acp-client.mjs`.
+
+  scripts/lib/peer-cli/asp-client.cjs
+    └─ Adapts the App Server Protocol thread-start + thread-resume + turn
+       lifecycle from cc-multi-cli's `asp-client.mjs`. service_name and
+       experimentalRawEvents conventions match cc-multi-cli.
+
+  scripts/lib/peer-cli/spawn-cmd.cjs
+    └─ Implements the Windows `.cmd` EINVAL workaround documented in
+       cc-multi-cli's `transport-decisions.md`
+       (`spawn(`"<absolute-fwd-slash-path>" <args>`, [], {shell: true})`).
+
+  skills/peer-cli-customize/SKILL.md
+    └─ Procedural pattern adapted from cc-multi-cli's `customize` skill.
+
+  skills/peer-cli-add/SKILL.md
+    └─ Procedural pattern adapted from cc-multi-cli's `multi-cli-anything`
+       skill, including the verification ladder, model-ID `-preview`-suffix
+       trap, and Windows quirk handling.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 28.5 — Skill Authoring Contract + Rework + Project Artifacts (v1.28.5, 2026-05-18)
+──────────────────────────────────────────────────────────────────────────────
+
+The skill-authoring contract, project-artifact format files, the
+debug-feedback-loops reference, and the new zoom-out micro-skill port
+content from:
+
+  mattpocock/skills (https://github.com/mattpocock/skills)
+  License: MIT
+  Adapted with permission.
+
+The following gdd files contain content adapted from mattpocock/skills:
+
+  reference/skill-authoring-contract.md
+    └─ Adapts the SKILL.md <=100-line cap, description-format contract
+       (lax-mode default per Phase 33 A/B pending), frontmatter required
+       fields, and progressive-disclosure-one-level-deep rules from
+       mattpocock's productivity/write-a-skill/SKILL.md.
+
+  reference/context-md-format.md
+    └─ Adapts mattpocock's productivity/grill-with-docs/CONTEXT-FORMAT.md
+       (DDD-style ubiquitous-language glossary schema, inline-write
+       trigger, multi-context CONTEXT-MAP.md pattern). GDD additions:
+       optional first-seen + aliases on term entries.
+
+  reference/adr-format.md
+    └─ Adapts mattpocock's productivity/grill-with-docs/ADR-FORMAT.md
+       (3-criteria offer gate: hard-to-reverse AND surprising-without-
+       context AND real-tradeoff; 4-state status lifecycle). GDD
+       additions: optional cycle-id + phase-id cross-refs back to
+       STATE.md.
+
+  reference/architecture-vocabulary.md
+    └─ Ports Ousterhout's *A Philosophy of Software Design* glossary via
+       mattpocock's improve-codebase-architecture/LANGUAGE.md (8 core
+       terms — Module / Interface / Implementation / Depth / Seam /
+       Adapter / Leverage / Locality — plus 3 principles: deletion test,
+       interface-is-test-surface, two-adapters-rule).
+
+  reference/debug-feedback-loops.md
+    └─ Adapts mattpocock's engineering/diagnose Phase 1 — feedback-loop
+       discipline, 10 construction paths in priority order (failing test
+       -> curl -> CLI fixture -> headless browser -> trace replay ->
+       throwaway harness -> fuzz -> bisect harness -> differential loop
+       -> HITL bash), iterate-on-loop sub-discipline, non-determinism
+       reproduction-rate branch.
+
+  skills/zoom-out/SKILL.md
+    └─ Direct port of mattpocock's engineering/zoom-out (~10 lines body,
+       disable-model-invocation: true, zoom-out-and-map-the-area
+       instruction). User-invoked-only shortcut.
+
+  skills/debug/SKILL.md (Phase 1 ordering)
+    └─ Adopts the feedback-loop-discipline-first ordering — build the
+       deterministic, fast, agent-runnable signal before hypothesizing.
+       (Skill body itself is GDD original; the Phase 1 ordering +
+       cross-link to reference/debug-feedback-loops.md is adapted.)
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 28.7 — Multi-Runtime Install Architecture (v1.28.7, 2026-05-19)
+──────────────────────────────────────────────────────────────────────────────
+
+The multi-runtime install pipeline shipped in v1.28.7 — the runtime-homes /
+runtime-artifact-layout / runtime-slash trio plus the per-runtime content
+converters — is a re-implementation of the architecture from:
+
+  gsd-build/get-shit-done (https://github.com/gsd-build/get-shit-done)
+  License: MIT
+
+The following gdd modules are an architectural port from gsd-build's MIT-
+licensed install machinery. We re-implemented in GDD's existing module
+conventions rather than byte-copying source, per Phase 28.7 D-02, to keep
+the GDD codebase free of upstream version drift and the bundled
+`bin/install.js` monolith:
+
+  scripts/lib/install/runtime-homes.cjs
+    └─ Per-runtime config-dir resolver (env-var + XDG + special-case nests).
+       Same shape as gsd-build's `bin/lib/runtime-homes.cjs`.
+
+  scripts/lib/install/runtime-artifact-layout.cjs
+    └─ Per-(runtime, scope) layout table mapping to kinds[]. Same shape as
+       gsd-build's `bin/lib/runtime-artifact-layout.cjs`. Adapted to GDD's
+       14-runtime set (gsd-build's Hermes is omitted per D-03 + D-10).
+
+  scripts/lib/install/runtime-slash.cjs
+    └─ Per-runtime slash-command surface emitter. Adapted from gsd-build's
+       `bin/lib/runtime-slash.cjs`. Codex uses `$gdd-<name>` shell-var form;
+       other runtimes use `/gdd-<name>`.
+
+  scripts/lib/install/converters/{antigravity,augment,cline,codebuddy,codex,
+                                  copilot,cursor,gemini,kilo,opencode,qwen,
+                                  shared,trae,windsurf}.cjs
+    └─ Per-runtime content converters. Each translates a Claude SKILL.md
+       source into the runtime's expected shape (path rewrite, tool-name
+       rewrite via Phase 21 cross-harness maps, frontmatter pass-through).
+       gsd-build implements these as `convertClaudeCommandTo<Runtime>Skill`
+       functions inside a bundled `bin/install.js`; we factor them into
+       per-runtime `.cjs` files for independent testability.
+
+Per-file headers in the ported modules carry the same attribution. This
+NOTICE block is the rollup citation.
+
+The upstream gsd-build project remains the authoritative reference for the
+install-pipeline architecture; bug reports specific to the architecture's
+shape should also be filed there.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 30 — Privacy Layer (v1.30.0, 2026-05-20)
+──────────────────────────────────────────────────────────────────────────────
+
+scripts/lib/pseudonymize.cjs and scripts/lib/issue-reporter/payload-assembly.cjs
+were authored from scratch for Phase 30 (consent-first issue reporter). No
+third-party privacy or anonymization patterns were adapted into either file
+— verified by inspection of the file contents (no "adapted from" / "from
+<library>" / source-citation comments) and by git log on both files (commits
+ed478fe, e5fc79a, e86c648 — all original to this repo).
+
+The regex rules in pseudonymize.cjs target generic identity-correlatable
+fields (usernames, hostnames, filesystem paths, repo origin URLs, env-var
+values, email patterns, IP addresses). The patterns were derived from the
+canonical shapes of these surfaces as they appear in plugin runtime output;
+they were NOT sourced from any upstream anonymization or pseudonymization
+library.
+
+The Phase 30 — Inbound Feedback Channel design itself (consent-first issue
+reporter, hardcoded destination, no plugin-side credentials, gh-CLI-only
+outbound) is original to get-design-done. The architectural rationale lives
+in .planning/phases/30-issue-reporter/CONTEXT.md.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 30.6 — Graphify Self-Ownership (v1.30.6, 2026-05-28)
+──────────────────────────────────────────────────────────────────────────────
+
+Version 1.30.6 removes the last runtime touchpoint between get-design-done
+and the user's `~/.claude/get-shit-done/` install. Eight callsites
+previously dispatched `node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs"
+graphify *` at runtime; they now dispatch a native `bin/gdd-graph` CLI
+owned end-to-end in this repository.
+
+No historical MIT/Apache attributions in this NOTICE are removed or
+modified by this change. The Phase 27 / Phase 28.5 / Phase 28.7
+attribution subsections above are preserved verbatim per Phase 30.6 D-06.
+Those describe historical architectural ports:
+
+  - Phase 27 — peer-CLI delegation protocol shapes adapted from
+    cc-multi-cli-plugin (Apache 2.0).
+  - Phase 28.5 — skill-authoring contract + project-artifact formats +
+    debug feedback-loop reference + zoom-out micro-skill, ported from
+    mattpocock/skills (MIT).
+  - Phase 28.7 — multi-runtime install pipeline architecture, ported
+    from gsd-build/get-shit-done (MIT).
+
+Phase 30.6 removes a runtime touchpoint, NOT a historical port. The
+architectural ports listed above remain in our tree under their original
+MIT/Apache terms.
+
+For context: the upstream `gsd-build/get-shit-done` project has since been
+archived (TÂCHES rug-pull, May 2026). The community continuation lives at
+`open-gsd/get-shit-done-redux` and is bit-perfect with the pre-rug tree.
+The Phase 28.7 attribution above remains pointed at the original upstream
+URL because that is the source of the architectural port; the redux fork
+is referenced in `README.md` for users seeking a current download.
+
+See `.planning/phases/30.6-graphify-self-ownership/` for full phase
+documentation including the 10 architectural decisions (D-01 through D-10)
+and the migration of the 8 dispatching callsites to native `bin/gdd-graph`.
+
+────────────────────────────────────────────────────────────────────────
+
+Note on the broader codebase: get-design-done as a whole is licensed under
+the MIT License (see LICENSE). The Apache 2.0 attribution above applies
+specifically to the cc-multi-cli-derived files listed under the Phase 27
+block. The MIT attributions under Phase 28.5 and Phase 28.7 cover content
+adapted from mattpocock/skills (MIT) and gsd-build/get-shit-done (MIT)
+respectively — the MIT-to-MIT re-licensing is straightforward and the
+attributions above provide the required source citation. The MIT and
+Apache 2.0 licenses are compatible — see
+https://www.apache.org/legal/resolved.html#category-a.

package/README.md

@@ -2,7 +2,7 @@
 
 # GET DESIGN DONE
 
-**English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Deutsch](README.de.md)
+**English** · [简体中文](docs/i18n/README.zh-CN.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Français](docs/i18n/README.fr.md) · [Italiano](docs/i18n/README.it.md) · [Deutsch](docs/i18n/README.de.md)
 
 **A design-quality pipeline for AI coding agents: brief → explore → plan → implement → verify.**
 
@@ -256,6 +256,27 @@ When K=3 stable clusters surface across M=10 reflection cycles (defaults in `ref
 **Discipline preserved.** Reflector authors nothing that auto-ships. `/gdd:apply-reflections` remains the single human gate (Phase 11 SC-8). Stage 1 never auto-flips — user opts in.
 
 
+### Figma off-context extraction (v1.31.0+)
+
+Pull an entire Figma design system into a compact, LLM-readable local digest — **without the raw JSON ever entering Claude's context**. One command extracts the file via the Figma REST API into a local raw cache; a separate digest stage reduces it to `DESIGN.md` + `tokens.json` + `components.json`.
+
+```bash
+# Stage 1 — raw pull (0 Claude tokens; writes a gitignored cache)
+node scripts/lib/figma-extract/pull.cjs <figma-file-url-or-key>
+# Stage 2 — digest (reads the cache, writes the compact spec)
+node scripts/lib/figma-extract/digest.cjs --raw <cache>/raw/<key> --out .design/figma
+```
+
+**The economics.** A spike measured **898× compression** (223 MB raw → 254 KB digest) with a ~15.7K-token `DESIGN.md`, capturing 127 component sets + 40 singletons (variants, props, defaults) in ~33s — at **0 Claude tokens and 0 Figma MCP calls during extraction**. This is the cost-sane alternative to the Figma MCP for whole-design-system work, which can run tens of minutes and 50–500K+ tokens for the same data. (The Figma MCP remains the right tool for spot questions on a single component.)
+
+- **Token-safe by construction.** `FIGMA_TOKEN` is read from the environment only and sent solely as a request header — never logged, never written to disk (a CI static-analysis test enforces this across the whole extract library). The digest never reads raw JSON into context.
+- **Works on any Figma plan.** The optional **"GDD Sync"** Figma plugin (`figma-plugin/`) fills the Variables-API-Enterprise gap: it reads `figma.variables` from inside Figma and POSTs them to an ephemeral, 127.0.0.1-only receiver — so Free-tier users get full token coverage too.
+- **Per-component slices.** `digest --component <name|glob>` renders a ~500-token slice of just the components you ask for, instead of the full digest.
+- **Health-aware.** `/gdd:health` reports a `figma_extract` readiness line (token set / token missing / Free-tier plugin-sync needed).
+
+See [`skills/figma-extract/SKILL.md`](skills/figma-extract/SKILL.md) and [`figma-plugin/README.md`](figma-plugin/README.md) for the full flow.
+
+
 ## How It Works
 
 > **New to an existing codebase?** Run `/gdd:map` first. It dispatches 5 specialist mappers in parallel (tokens, components, visual hierarchy, a11y, motion) and writes structured JSON to `.design/map/` — much higher signal than the grep-based fallback in Explore.

package/SKILL.md

@@ -35,6 +35,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `darkmode` | `get-design-done:gdd-darkmode` | Audit dark mode architecture + contrast + anti-patterns → .design/DARKMODE-AUDIT.md |
 | `compare` | `get-design-done:gdd-compare` | Delta between DESIGN.md baseline and DESIGN-VERIFICATION.md → .design/COMPARE-REPORT.md |
 | `figma-write <mode>` | `get-design-done:gdd-figma-write` | Write design decisions to Figma (annotate/tokenize/mappings) |
+| `figma-extract <file-url-or-key>` | `get-design-done:gdd-figma-extract` | Off-context Figma design-system extraction → compact local digest (DESIGN.md + tokens.json + components.json), zero raw JSON in context |
 | `graphify <subcommand>` | `get-design-done:gdd-graphify` | Manage Graphify knowledge graph (build/query/status/diff) |
 | `discuss [topic] [--all] [--spec] [--cycle <name>]` | `get-design-done:gdd-discuss` | Adaptive design interview — spawns design-discussant; appends D-XX decisions to STATE.md |
 | `list-assumptions [--area]` | `get-design-done:gdd-list-assumptions` | Surface implicit design assumptions baked into the codebase |

package/agents/design-authority-watcher.md

@@ -194,7 +194,7 @@ After classifying the new entries (Step 5) but BEFORE writing the snapshot (Step
 - `/known issues/i`
 - `/pitfalls/i`
 
-For each entry whose `title` matches ANY pattern, emit a single `kfm-candidate` event to the events stream (`.design/telemetry/events.jsonl`) via `scripts/lib/event-stream/writer.ts` (or the Bash equivalent — `printf '%s\n' "<json>" >> .design/telemetry/events.jsonl`).
+For each entry whose `title` matches ANY pattern, emit a single `kfm-candidate` event to the events stream (`.design/telemetry/events.jsonl`) via `sdk/event-stream/writer.ts` (or the Bash equivalent — `printf '%s\n' "<json>" >> .design/telemetry/events.jsonl`).
 
 Event payload shape — validates against `reference/schemas/events.schema.json` definitions `KfmCandidatePayload` (allOf[1] branch). Required 7 fields:
 

package/agents/perf-analyzer.md

@@ -80,7 +80,7 @@ For each regression, emit a `perf.regression_detected` event via `appendEvent` f
 
 ```javascript
 // Pseudo-instruction for the executor — the agent runs Bash with this shape
-const { appendEvent } = require('./scripts/lib/event-stream');
+const { appendEvent } = require('./sdk/event-stream');
 appendEvent({
   type: 'perf.regression_detected',
   timestamp: new Date().toISOString(),
@@ -89,7 +89,7 @@ appendEvent({
 });
 ```
 
-The `perf.regression_detected` event type is additive to the Phase 22 registry — the writer accepts unknown types (per `scripts/lib/event-stream/types.ts` envelope invariant: "unknown types are allowed; validation is structural, not a closed enum").
+The `perf.regression_detected` event type is additive to the Phase 22 registry — the writer accepts unknown types (per `sdk/event-stream/types.ts` envelope invariant: "unknown types are allowed; validation is structural, not a closed enum").
 
 If `detectCostRegressions` returns `summary.regressions_count === 0`, write a single line: `No token-cost regressions detected (threshold 25%, >=3 cycles).` and skip event emission for this section.
 

package/bin/gdd-mcp

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// bin/gdd-mcp — Plan 31-5-05 (SDK-04, D-08); dual-mode since Plan 31-5-9.5 (D-16).
+//
+// DUAL-MODE CJS trampoline for the `gdd-mcp` MCP server. Resolves the server
+// entry and re-launches it under `node`, forwarding argv + exit code/signal.
+// Two modes:
+//
+//   • COMPILED (installed / packed): if the esbuild-bundled sibling
+//     `sdk/mcp/gdd-mcp/server.js` exists, spawn `node <js>` with NO flag.
+//     This is the path a user gets from `npm i` — the entry lives under
+//     node_modules where Node refuses --experimental-strip-types on `.ts`
+//     (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). `prepack` compiles the .js
+//     before every pack/publish (see scripts/build-sdk-bins.cjs).
+//   • SOURCE (in-repo dev): otherwise spawn
+//     `node --experimental-strip-types sdk/mcp/gdd-mcp/server.ts` — raw TS, no
+//     build step, exactly as before this plan.
+//
+// Why a trampoline at all:
+//   POSIX shebangs can use `#!/usr/bin/env -S node --experimental-strip-types`,
+//   but Windows cmd.exe does not honor shebangs and npm's auto-generated .cmd
+//   shim invokes plain `node bin/gdd-mcp` with no way to inject the flag.
+//   Mirrors the proven bin/gdd-sdk trampoline pattern.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Sibling compiled JS (preferred) and the TS source (dev fallback).
+const compiled = path.resolve(
+  __dirname,
+  '..',
+  'sdk',
+  'mcp',
+  'gdd-mcp',
+  'server.js',
+);
+const source = path.resolve(
+  __dirname,
+  '..',
+  'sdk',
+  'mcp',
+  'gdd-mcp',
+  'server.ts',
+);
+
+const useCompiled = fs.existsSync(compiled);
+const entry = useCompiled ? compiled : source;
+const nodeArgs = useCompiled
+  ? [entry, ...process.argv.slice(2)]
+  : ['--experimental-strip-types', entry, ...process.argv.slice(2)];
+
+const child = spawn(process.execPath, nodeArgs, {
+  stdio: 'inherit',
+  shell: false,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal to ourselves so the parent shell sees the same
+    // termination mode (e.g., Ctrl+C propagates as SIGINT exit).
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(typeof code === 'number' ? code : 0);
+});
+
+child.on('error', (err) => {
+  // Failure to spawn node itself — extremely rare; surface to stderr.
+  // eslint-disable-next-line no-console
+  console.error('gdd-mcp: failed to launch MCP server entry:', err.message);
+  process.exit(3);
+});