@hegemonart/get-design-done 1.30.5 → 1.31.0

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.5"
+    "version": "1.31.0"
   },
   "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.5",
+      "version": "1.31.0",
       "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.5",
+  "version": "1.31.0",
   "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,135 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+Removes the **last runtime touchpoint** between get-design-done and the user's `~/.claude/get-shit-done/` install. 8 callsites in `agents/`, `skills/`, and `connections/` previously dispatched the upstream `gsd-tools` graphify subcommands at runtime; they now dispatch native `bin/gdd-graph`. After v1.30.6, a user who has never installed GSD (or who only installs the failed upstream and not the redux fork) can still run the full GDD pipeline including everything that touches the knowledge graph. 9 plans across 3 waves: Wave A (research + spec), Wave B (`bin/gdd-graph` core + extensions + decoupling acceptance test, 56 tests), Wave C (migration + rename + cleanup + closeout).
+
+### Motivation — rug-pull resilience
+
+The `gsd-build/get-shit-done` rug-pull in May 2026 (TÂCHES drained $GSD Solana token + deleted accounts) was downstream-survivable for us — we have zero npm dependency on GSD packages, the community fork `open-gsd/get-shit-done-redux` is MIT-bit-perfect, and Phase 28.7's install-pipeline port is standalone in our tree. The remaining touchpoint was graphify runtime dispatch. Phase 30.6 closes it. After v1.30.6, our runtime is independent of upstream's release cadence and any future subcommand / schema drift.
+
+### Added
+
+- **`bin/gdd-graph`** native Node CLI with 6 subcommands: `build`, `query`, `status`, `diff`, `upsert-node`, `upsert-edge`. Output at `.design/graph/graph.json` (D-02), Ajv-validated against `scripts/lib/graph/schema.json` schema 1.0 (D-03), atomic-write seam per D-05 (tmp + rename in same dir; no `proper-lockfile`).
+- **Token-budget heuristic** for `gdd-graph query --budget N` per D-04: `Math.ceil(JSON.stringify(payload).length / 4)`; override via `GDD_GRAPH_TOKEN_FACTOR` env for tests.
+- **5-scenario decoupling test** at `tests/graph-decoupled.test.cjs` (19 tests) — renames `~/.claude/get-shit-done/` to `.bak` for test duration, exercises all 6 subcommands across 5 fixture scenarios (empty / single-node / dense / with-cycles / malformed-intel). Single most important acceptance gate of the phase.
+- **`tests/phase-30.6-baseline.test.cjs`** + 5 baseline files at `test-fixture/baselines/phase-30.6/` (manifests-version, decoupling-callsite-count, gdd-graph-subcommand-inventory, graph-schema-shape, no-gsd-runtime-touch).
+- **D-01 through D-10** locked decisions + 5 sub-decisions (D-03.a/b/c, D-04.a, D-09.a) documented in `.planning/phases/30.6-graphify-self-ownership/`.
+
+### Changed
+
+- **8 callsite files** migrated from `gsd-tools.cjs graphify *` dispatch to native `bin/gdd-graph`:
+  - `agents/gdd-graphify-sync.md` (renamed to `gdd-graph-refresh.md`)
+  - `agents/design-integration-checker.md`
+  - `agents/design-planner.md`
+  - `skills/graphify/SKILL.md`
+  - `skills/scan/scan-procedure.md`
+  - `skills/connections/connections-onboarding.md`
+  - `connections/connections.md`
+  - `connections/graphify.md` (rewritten for native CLI, no external graphifyy)
+- **`agents/gdd-graphify-sync.md`** renamed to **`agents/gdd-graph-refresh.md`** (D-08 one-way rename, no alias) — protocol simplified now that we own both ends of the intel→graph translation (single schema; no translation step).
+- **`scripts/lib/gsd-health-mirror/`** renamed to **`scripts/lib/health-mirror/`** (D-10 cosmetic, atomic with single import-site update at `scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts`). The module is pure local-file inspection; the "mirror" refers to our own `skills/health/SKILL.md` surface, never upstream.
+- **`.design/graph/`** replaces upstream's `.planning/graphs/` location (per D-02 — aligns with the rest of GDD's `.design/` artifact convention).
+- **`connections/graphify.md`** rewritten for native CLI (no external `graphifyy` dependency).
+- **`reference/start-interview.md`** updated to reference `/gdd:discuss` (our equivalent) instead of `/gsd-discuss-phase`.
+- **`README.md`** at the `gsd-build/get-shit-done (MIT — see NOTICE)` citation gains the redux-pointer parenthetical "(now archived; community continuation at `open-gsd/get-shit-done-redux`)". Citation preserved verbatim — only annotated for reader clarity.
+- **Graphify enable/disable state** (D-09) lives in `.design/config.json` at `{ "graphify": { "enabled": bool } }`. Read directly by `gdd-graph` via fs; no `config-set` / `config-get` CLI subcommand.
+
+### Removed
+
+- **Runtime dispatch into `~/.claude/get-shit-done/`** — 8 callsites no longer invoke `gsd-tools.cjs graphify *`.
+- **`.planning/get-shit-done-main/`** (10MB pre-rug-pull vendored snapshot) — used during Phase 28.7's architectural port; port shipped, snapshot dead weight.
+- Intel→graphify translation layer (dead code post-migration; intel slices are now the canonical input to `bin/gdd-graph build` with no intermediate translation step).
+
+### Backward compatibility
+
+- Phase 27 / Phase 28.5 / Phase 28.7 `NOTICE` attribution subsections **preserved verbatim** per D-06. Those describe historical MIT/Apache ports (peer-CLI delegation protocol shapes from cc-multi-cli; skill-authoring contract from mattpocock/skills; install-pipeline architecture from gsd-build/get-shit-done) — they remain in our tree under the original MIT/Apache terms. Phase 30.6 removes a **runtime touchpoint**, not a **historical port**.
+- `.design/intel/` schema unchanged — Phase 10's knowledge layer keeps its current ownership; we only consume from it differently.
+- 4-manifest + 2 Tier-2 manifest lockstep at v1.30.6 (`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 through D-10)
+
+- **D-01**: Native CLI binary name = `gdd-graph` (not `gdd-graphify`). Shorter; doesn't semantically shadow the user's `/gsd:graphify-*` redux commands.
+- **D-02**: Canonical graph file at `.design/graph/graph.json` (not upstream's `.planning/graphs/graph.json`). Aligns with the rest of GDD's `.design/` artifact convention.
+- **D-03**: Schema validated by Ajv against `scripts/lib/graph/schema.json` on every write; schema version pinned to `1.0` at ship; future migrations bump explicitly.
+- **D-04**: Token-budget heuristic = `Math.ceil(JSON.stringify(payload).length / 4)`; `GDD_GRAPH_TOKEN_FACTOR` env override for tests.
+- **D-05**: Atomic-write seam = `fs.writeFile(tmpPath); fs.rename(tmpPath, finalPath)` in same directory. No `proper-lockfile`. Single-writer assumption (revisit if Phase 41 Team Collaboration forces multi-writer).
+- **D-06**: `NOTICE` retains Phase 27 / Phase 28.5 / Phase 28.7 architectural attributions verbatim. We're removing a runtime touchpoint, not voiding a historical port.
+- **D-07**: Phase 30.6 ships off-cadence as a decimal from v1.30.5 parent (same shape v1.30.5 used coming off v1.30.0). NO 1.31.x bump.
+- **D-08**: Agent rename `gdd-graphify-sync` → `gdd-graph-refresh` is one-way (no alias). Internal name; no external callers from outside the plugin.
+- **D-09**: Graphify enable/disable state lives in `.design/config.json` at `{ "graphify": { "enabled": bool } }`. Read directly by `gdd-graph` via `JSON.parse(fs.readFileSync(...))` with sensible default (`enabled: false`). No `config-set` / `config-get` CLI subcommand — simpler than the upstream config-tool pattern.
+- **D-10**: `scripts/lib/gsd-health-mirror/` rename is one-way (no alias). Only one import site (`scripts/mcp-servers/gdd-mcp/tools/gdd_health.ts`) which is updated atomically with the rename.
+
+### Attribution preservation
+
+Phase 27 / Phase 28.5 / Phase 28.7 attribution subsections in `NOTICE` are preserved verbatim per D-06. The architectural ports they describe are historical MIT-licensed code transplants; this release removes a runtime touchpoint, **NOT** a historical port. The `gsd-build/get-shit-done (MIT — see NOTICE)` citation in `README.md` is preserved verbatim; only the redux-pointer parenthetical was added.
+
+---
+
 ## [1.30.5] - 2026-05-21
 
 ### Phase 30.5 — Failure-Mode Catalogue

package/README.md

@@ -139,7 +139,7 @@ The installer prompts you to choose:
 1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline, or all (interactive multi-select — pick multiple runtimes in a single session)
 2. **Location** — Global (all projects) or local (current project only)
 
-All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `agents/`, or `.clinerules`) via per-runtime content converters — Claude SKILL.md sources are translated to each runtime's expected shape at install time (frontmatter pass-through, path rewrite, tool-name rewrite via the Phase 21 cross-harness maps). Architecture ported from `gsd-build/get-shit-done` (MIT — see `NOTICE`).
+All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `agents/`, or `.clinerules`) via per-runtime content converters — Claude SKILL.md sources are translated to each runtime's expected shape at install time (frontmatter pass-through, path rewrite, tool-name rewrite via the Phase 21 cross-harness maps). Architecture ported from `gsd-build/get-shit-done` (MIT — see `NOTICE`; upstream is now archived following the May 2026 $GSD token rug-pull, community continuation lives at [`open-gsd/get-shit-done-redux`](https://github.com/open-gsd/get-shit-done-redux)).
 
 Verify with:
 
@@ -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-integration-checker.md

@@ -57,7 +57,7 @@ Minimum expected files:
 For each D-XX decision in DESIGN-CONTEXT.md, query the graph before grepping:
 
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "decision:D-<nn>" --budget 1500
+node bin/gdd-graph query "decision:D-<nn>" --budget 1500
 ```
 
 The query returns a subgraph of components and tokens connected to this decision. Use the returned node IDs (`component:<name>` and `token:<name>`) as the seed list for your grep searches. This reduces false-negatives where a decision is implemented but grep pattern misses it.

package/agents/design-planner.md

@@ -71,7 +71,7 @@ Each task maps to a domain with specific reference files. These types are the on
 Before scoping any task that involves a design token change (color, spacing, typography, motion):
 
 ```
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify query "<token-name>" --budget 1500
+node bin/gdd-graph query "<token-name>" --budget 1500
 ```
 
 The query returns all components that reference this token. Annotate the planned task with:

package/agents/gdd-graph-refresh.md

@@ -0,0 +1,90 @@
+---
+name: gdd-graph-refresh
+description: "Refreshes the knowledge graph at .design/graph/graph.json from .design/intel/ slices using the native bin/gdd-graph CLI. Run after gdd-intel-updater to keep the semantic graph current. Phase 30.6 simplified this agent: intel and graph now share a single {from,to,kind,weight?} schema, so no translation step is needed."
+tools: Bash, Read, Write
+color: green
+default-tier: haiku
+tier-rationale: "Refresh is a deterministic file-walk + atomic write — cheap Haiku is enough"
+parallel-safe: false
+typical-duration-seconds: 20
+reads-only: false
+writes:
+  - .design/graph/graph.json
+---
+
+@reference/shared-preamble.md
+
+# gdd-graph-refresh
+
+**Role:** Refresh the project knowledge graph at `.design/graph/graph.json` from the intel store at `.design/intel/`. Reads intel slices and (re)builds the graph via the native `bin/gdd-graph build` command. Phase 30.6 simplification: intel and graph share a single `{from,to,kind,weight?}` edge schema (D-03.b), so there is no longer a translation step — `gdd-graph build` ingests intel slices directly.
+
+## When to invoke
+
+- After `gdd-intel-updater` completes (intel store updated)
+- After a phase plan that adds new skill/agent/reference files
+- When semantic graph queries return stale results
+
+## Protocol
+
+### Step 1 — Check intel store
+
+```bash
+test -d .design/intel/ && echo "ready" || echo "missing"
+```
+
+If missing: print "Intel store not found — run node scripts/build-intel.cjs --force first." and stop.
+
+### Step 2 — Check graphify enabled
+
+```bash
+node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+```
+
+If `false`: print "Graphify not enabled in .design/config.json — skipping refresh. To enable, set `graphify.enabled: true` in .design/config.json." and stop gracefully (exit 0, do not fail).
+
+### Step 3 — Rebuild graph from intel slices
+
+Phase 30.6 simplification: with shared `{from,to,kind,weight?}` schema between intel and graph (D-03.b), the canonical refresh is a single `build` invocation. No per-node iteration, no translation step.
+
+```bash
+node bin/gdd-graph build
+```
+
+Exit code 0 indicates success; non-zero with stderr indicates a schema violation in an intel slice — report and stop.
+
+### Step 4 — Verify the rebuilt graph
+
+```bash
+node bin/gdd-graph status --format json
+```
+
+Capture `{ node_count, edge_count, built_at, schema_version }` from the JSON output.
+
+### Step 5 — Summary
+
+```
+━━━ Graph refresh complete ━━━
+Graph path:      .design/graph/graph.json
+Nodes:           <node_count>
+Edges:           <edge_count>
+Schema version:  <schema_version>
+Built at:        <built_at>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Required reading (conditional)
+
+@.design/intel/graph.json (if present)
+@.design/intel/files.json (if present)
+
+## GRAPH-REFRESH COMPLETE
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/bin/gdd-graph

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// bin/gdd-graph — Plan 30.6-02 Task 3
+//
+// Native CLI replacing every `gsd-tools.cjs graphify *` dispatch in our
+// tree. This bin is a thin CJS dispatcher that dynamic-imports the ESM
+// handler modules (package.json has no "type":"module", so the no-ext
+// bin file is resolved as CJS by Node — we bridge with `await import()`).
+//
+// Subcommands shipped in 30.6-02:
+//   build         — read .design/intel/graph.json, write .design/graph/graph.json
+//   status        — report graph file state (configured/exists/counts/stale)
+//   diff <a> <b>  — emit added/removed/changed nodes + edges
+//
+// Subcommands shipped in 30.6-03 (this plan):
+//   query <term> [--budget N]   — search graph, return ranked matches +
+//                                 1-hop neighbors, budget-truncated per D-04
+//   upsert-node --json '<json>' — create/update a node by id (idempotent)
+//   upsert-edge --json '<json>' — create/update an edge by (from,to,kind);
+//                                 fails if either endpoint node is absent
+
+'use strict';
+
+const path = require('node:path');
+
+const SUBCOMMANDS = new Set([
+  'build', 'status', 'diff', 'query', 'upsert-node', 'upsert-edge',
+]);
+
+function printUsage(stream) {
+  stream.write([
+    'Usage: gdd-graph <subcommand> [options]',
+    '',
+    'Subcommands:',
+    '  build  [--intel <path>] [--out <path>] [--now <iso>]',
+    '         Build .design/graph/graph.json from .design/intel/graph.json.',
+    '  status [--graph <path>] [--intel <path>] [--format json|text]',
+    '         Report graph store state (configured/exists/counts/stale).',
+    '  diff   <from> <to> [--format json|text]',
+    '         Diff two graph.json files; emit added/removed/changed nodes+edges.',
+    '  query  <term> [--budget N] [--graph <path>]',
+    '         Search graph; return ranked matches + 1-hop neighbors,',
+    '         budget-truncated per D-04 (chars/4 heuristic, default 8000).',
+    '  upsert-node {--json \'<obj>\' | --id <id> --type <type> [--label <l>] [--source <s>] [--attrs <json>]}',
+    '         Idempotent node upsert by id; bootstraps graph file if absent.',
+    '  upsert-edge {--json \'<obj>\' | --from <id> --to <id> --kind <kind> [--weight N] [--source <s>] [--attrs <json>]}',
+    '         Idempotent edge upsert by (from,to,kind); requires both endpoint',
+    '         nodes to exist — emits GDD_GRAPH_MISSING_ENDPOINT otherwise.',
+    '',
+    'Env:',
+    '  GDD_GRAPH_DEBUG=1            include stack traces in error JSON',
+    '  GDD_GRAPH_TOKEN_FACTOR <int>  override chars-per-token divisor (D-04)',
+    '',
+    'Exit codes:',
+    '  0 success / 1 failure (structured-error JSON on stderr)',
+    '',
+  ].join('\n'));
+}
+
+function parseArgs(rest) {
+  // Minimal hand-rolled parser. Positional args land in `_`; flags with
+  // `--name value` (and `--name=value`) land in `opts`.
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--' ) { positional.push(...rest.slice(i + 1)); break; }
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq !== -1) {
+        opts[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        const next = rest[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          opts[arg.slice(2)] = true;
+        } else {
+          opts[arg.slice(2)] = next;
+          i++;
+        }
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { _: positional, opts };
+}
+
+function emitError(subcommand, err, exitCode = 1) {
+  const payload = {
+    ok: false,
+    subcommand,
+    message: err && err.message ? err.message : String(err),
+  };
+  if (err && err.code) payload.code = err.code;
+  if (err && err.schemaErrors) payload.schemaErrors = err.schemaErrors;
+  if (err && err.missingEndpoints) payload.missingEndpoints = err.missingEndpoints;
+  if (process.env.GDD_GRAPH_DEBUG && err && err.stack) payload.stack = err.stack;
+  process.stderr.write(JSON.stringify(payload) + '\n');
+  process.exit(exitCode);
+}
+
+async function dispatch(subcommand, parsed) {
+  const lib = await import(
+    // Resolve via relative require root — bin/ is sibling of scripts/.
+    'file://' + path.resolve(__dirname, '..', 'scripts', 'lib', 'graph', 'index.mjs').replace(/\\/g, '/')
+  );
+
+  if (subcommand === 'build') {
+    const r = lib.buildGraph({
+      intelPath: parsed.opts.intel,
+      outPath: parsed.opts.out,
+      now: parsed.opts.now,
+    });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+
+  if (subcommand === 'status') {
+    const r = lib.statusGraph({
+      graphPath: parsed.opts.graph,
+      intelPath: parsed.opts.intel,
+    });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+
+  if (subcommand === 'diff') {
+    const [fromPath, toPath] = parsed._;
+    if (!fromPath || !toPath) {
+      const err = new Error('diff requires two positional args: <from> <to>');
+      err.code = 'DIFF_ARGS_MISSING';
+      throw err;
+    }
+    const r = lib.diffGraph({ fromPath, toPath });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+
+  if (subcommand === 'query') {
+    const [term] = parsed._;
+    if (!term) {
+      const err = new Error('query requires a positional argument: <term>');
+      err.code = 'QUERY_TERM_MISSING';
+      throw err;
+    }
+    const budget = parsed.opts.budget !== undefined
+      ? Number.parseInt(parsed.opts.budget, 10)
+      : undefined;
+    if (parsed.opts.budget !== undefined && !Number.isFinite(budget)) {
+      const err = new Error(`query --budget must be an integer (got: ${parsed.opts.budget})`);
+      err.code = 'QUERY_BUDGET_INVALID';
+      throw err;
+    }
+    const r = lib.queryGraph({
+      graphPath: parsed.opts.graph,
+      query: term,
+      budget,
+    });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+
+  if (subcommand === 'upsert-node') {
+    const node = parseUpsertInput(parsed, 'upsert-node');
+    const r = lib.upsertNode({
+      graphPath: parsed.opts.graph,
+      node,
+    });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+
+  if (subcommand === 'upsert-edge') {
+    const edge = parseUpsertInput(parsed, 'upsert-edge');
+    const r = lib.upsertEdge({
+      graphPath: parsed.opts.graph,
+      edge,
+    });
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return;
+  }
+}
+
+/**
+ * Parse the upsert payload from argv. Supports two shapes:
+ *  - `--json '<json-string>'` (preferred — single source of truth for batch
+ *    callers in agents/gdd-graph-refresh.md and skills/graphify)
+ *  - flat flags `--id ... --type ... --label ... --from ... --to ... --kind ...
+ *    --weight N --source ... --attrs '<json>'` (convenience for shell users
+ *    + matches the upstream gsd-tools.cjs graphify flag surface verbatim
+ *    per RESEARCH.md §8-callsite inventory)
+ *
+ * Conflict: `--json` wins when both are provided.
+ */
+function parseUpsertInput(parsed, subcommand) {
+  if (parsed.opts.json !== undefined) {
+    try {
+      const obj = JSON.parse(parsed.opts.json);
+      if (!obj || typeof obj !== 'object') {
+        throw new Error(`${subcommand} --json must decode to an object`);
+      }
+      return obj;
+    } catch (e) {
+      const err = new Error(`${subcommand} --json parse failed: ${e.message}`);
+      err.code = 'UPSERT_JSON_PARSE_FAILED';
+      throw err;
+    }
+  }
+  // Flat-flag mode — assemble from individual --field flags.
+  const obj = {};
+  for (const key of ['id', 'type', 'label', 'from', 'to', 'kind', 'source']) {
+    if (parsed.opts[key] !== undefined && parsed.opts[key] !== true) {
+      obj[key] = parsed.opts[key];
+    }
+  }
+  if (parsed.opts.weight !== undefined) {
+    const w = Number.parseFloat(parsed.opts.weight);
+    if (!Number.isFinite(w)) {
+      const err = new Error(`${subcommand} --weight must be a number (got: ${parsed.opts.weight})`);
+      err.code = 'UPSERT_WEIGHT_INVALID';
+      throw err;
+    }
+    obj.weight = w;
+  }
+  if (parsed.opts.attrs !== undefined) {
+    try {
+      obj.attrs = JSON.parse(parsed.opts.attrs);
+    } catch (e) {
+      const err = new Error(`${subcommand} --attrs parse failed: ${e.message}`);
+      err.code = 'UPSERT_ATTRS_PARSE_FAILED';
+      throw err;
+    }
+  }
+  return obj;
+}
+
+(async () => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    printUsage(process.stderr);
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  const subcommand = argv[0];
+  if (!SUBCOMMANDS.has(subcommand)) {
+    process.stderr.write(JSON.stringify({
+      ok: false,
+      message: `unknown subcommand: ${subcommand}`,
+    }) + '\n');
+    process.exit(1);
+  }
+  const parsed = parseArgs(argv.slice(1));
+  try {
+    await dispatch(subcommand, parsed);
+    process.exit(0);
+  } catch (err) {
+    emitError(subcommand, err, 1);
+  }
+})().catch((err) => {
+  // Last-resort guard. dispatch() already routes via emitError; this only
+  // fires for bugs in argv parsing or the dispatch glue itself.
+  emitError('<bootstrap>', err, 1);
+});

package/connections/connections.md

@@ -185,15 +185,16 @@ Note: First Chromatic run has no baseline — all stories become new snapshots.
 **Graphify probe (execute at agent entry, before using graph):**
 
 ```
-Step G1 — Config check:
-  node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" graphify status
-  → Error or { enabled: false }  → graphify: not_configured
-  → { enabled: true }            → proceed to Step G2
-
-Step G2 — Graph file check:
-  Check if graphify-out/graph.json exists in project root
-  → Absent    → graphify: unavailable  (graph not built yet)
-  → Present   → graphify: available
+Step G1 — Config check (per D-09 direct read, no CLI subcommand):
+  Bash: node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+  → false → graphify: not_configured
+  → true  → proceed to Step G2
+
+Step G2 — Graph file check (native CLI):
+  Bash: node bin/gdd-graph status --format json
+  → { configured: true, exists: true }  → graphify: available
+  → { configured: true, exists: false } → graphify: unavailable  (graph not built yet)
+  → { configured: false, exists: ... }  → graphify: not_configured  (mirrors G1)
 
 Write graphify status to STATE.md <connections>.
 ```