@hegemonart/get-design-done 1.36.3 → 1.37.2

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.36.3"
+    "version": "1.37.2"
   },
   "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.36.3",
+      "version": "1.37.2",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.36.3",
+  "version": "1.37.2",
   "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",

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.37.2] - 2026-06-01
+
+### Phase 37.2 — Greenfield Design-System Bootstrap (`/gdd:bootstrap-ds`) — completes Phase 37
+
+Second and **FINAL** sub-phase of the split **Phase 37** — completing it marks the **parent Phase 37 COMPLETE** (AI-Native Tools Wave 2 + Greenfield DS Bootstrap). Closes the greenfield gap: GDD assumed a design system already existed (in code or Figma) — a brand-new project has none. `/gdd:bootstrap-ds` turns a brand input into a coherent token system + proof components. **No new runtime dependency** — the token math emits native CSS `oklch()` (no color-conversion library).
+
+### Added
+
+- **`scripts/lib/ds/token-scale.cjs`** — a pure, dependency-free (zero `require`) token generator. `oklchScale(primary)` → 9 tint/shade stops as native CSS `oklch()`, anchored at the primary, lightness interpolated toward white/black, chroma damped at the extremes (no OKLab→sRGB conversion, no color library); `typeScale` (modular), `spacingScale` (4pt/8pt), `radiusScale`. Deterministic.
+- **`reference/ds-bootstrap-rubric.md`** — greenfield emission rules: primary → 9 tints; **never more than 2 brand colors**; neutrals + semantic colors; type ratios 1.2/1.25/1.333; 4pt/8pt spacing; radius + motion defaults; the 3 variants; role-named CSS-custom-property emission + framework mapping; proof scaffolding. Registered (`type: heuristic`, `phase: 37.2`; 150 → 151).
+- **`agents/ds-generator.md`** — brand-input → token system via `token-scale.cjs` + the rubric + `color-theory.md`. Emits **3 variants** (conservative / balanced / bold), the user picks one, then scaffolds **button / input / card** in the detected framework (web default; native via Phase 34). Never invents a brand; never overwrites an existing DS; proposal→confirm.
+- **`skills/bootstrap-ds/SKILL.md`** (`/gdd:bootstrap-ds`) — brand-input intake (primary + secondary + tone tags + target framework) → `ds-generator`. 43 lines (≤100 Phase-28.5 contract).
+
+### Notes
+
+- **No new runtime dependency** (native `oklch()`), **no new egress**.
+- 6-manifest lockstep at **v1.37.2** + `OFF_CADENCE_VERSIONS.add('1.37.2')` + the 27 live-pinned `manifests-version.txt` baselines forward-propagated 1.37.1 → 1.37.2.
+- Inventory relock: skill-list 75 → 76 (+`bootstrap-ds`, both `current/` + `phase-20/`), phase-20 agent-list 49 → 50 (+`ds-generator`) + both frontmatter-snapshots, registry-diff 150 → 151, tarball golden 676 → 680 (+4); root `SKILL.md` command table + `command-count-sync` gate updated.
+- **This completes the parent Phase 37 (AI-Native Tools Wave 2 + Greenfield DS Bootstrap).**
+
+---
+
+## [1.37.1] - 2026-06-01
+
+### Phase 37.1 — AI-Native Tools Wave 2 (Framer + Penpot + Webflow + v0.dev + Plasmic + Builder.io)
+
+First sub-phase of the split **Phase 37**. Schedules Phase 14's explicit backlog: six AI-native design tools, each under the existing connection capability contract (canvas | generator | shared probe). **No new runtime dependency, no new egress** — each tool is an opt-in user-connected MCP/API, probed via ToolSearch/env; absent → degrade-to-code-only.
+
+### Added
+
+- **`connections/framer.md`** + **`penpot.md`** + **`webflow.md`** — canvas-category specs. Framer (read frames + write proposals), Penpot (open-source Figma alt; self-hosted-vs-cloud probe), Webflow (read site structure as a design-adaptation source — not CMS authoring). Contribute at the **design** stage.
+- **`connections/v0-dev.md`** + **`plasmic.md`** + **`builder-io.md`** — generator-category specs. v0.dev (MCP-first → REST + `V0_API_KEY`), Plasmic (dual: canvas read + code emission), Builder.io Visual Copilot (pull-only this phase). Drive the **generator** stage.
+- **`agents/design-component-generator.md`** — Step-0 detection + `--tool` flag extended to `v0|plasmic|builder-io`, plus compact `<!-- impl: v0 -->` / `<!-- impl: plasmic -->` / `<!-- impl: builder-io -->` sections that cross-link to the connection specs (231 → 259, under the LARGE budget). Priority: magic-patterns > 21st.dev > v0 > plasmic > builder-io; `--tool` overrides.
+- **`connections/connections.md`** + onboarding — 21 → 27 onboarded (6 Active rows + 6 capability-matrix rows: framer/penpot → canvas, webflow/v0/builder-io → generator, **Plasmic → canvas + generator dual**; probes + value-prop + setup matrix).
+
+### Notes
+
+- **No new runtime dependency, no new egress** — opt-in MCP/API connections; the generator never writes to `src/` without proposal→confirm.
+- 6-manifest lockstep at **v1.37.1** + `OFF_CADENCE_VERSIONS.add('1.37.1')` + the 26 live-pinned `manifests-version.txt` baselines forward-propagated 1.36.3 → 1.37.1 (opens the v1.37.x arc).
+- Inventory relock: connection-list 29 → 35 (+6), onboarding → 27, tarball golden 670 → 676 (+6). Registry unchanged (no `reference/` doc); no new skill/agent dir (the generator agent pre-exists).
+
+---
+
 ## [1.36.3] - 2026-06-01
 
 ### Phase 36.3 — Knowledge Tier-3: Conversational UI — completes Phase 36

package/README.md

@@ -162,6 +162,14 @@ GDD now opens the motion **exports** a project ships. The pure, dependency-free
 
 [`reference/conversational-ui.md`](reference/conversational-ui.md) closes a zero-coverage surface: voice flows + chatbots. It codifies voice-flow reprompts (no-input / no-match → human handoff), multi-turn dialogue (context carryover, slot-filling, repair), **prompt-as-UX** (the assistant's persona/tone/boundaries as a versioned design artifact), chatbot empty-states + suggested replies, voice-first onboarding, and error recovery + accessibility. [`design-context-builder`](agents/design-context-builder.md) detects a `conversational` project type (brief keywords + chatbot/voice deps like `botpress` / `dialogflow` / `actions-on-google` / `ask-sdk-core`) and loads the pack into context. **No new runtime dependency.** This is the **final sub-phase of Phase 36 — which is now complete** (domain packs + motion-tool verification + conversational UI).
 
+### AI-native tools — Wave 2 (v1.37.1)
+
+Six more AI-native design tools join the connection layer (Phase 14's backlog, now scheduled): **Framer**, **Penpot**, and **Webflow** (canvas-category — read frames/boards/structure as design sources) plus **v0.dev**, **Plasmic**, and **Builder.io** (generator-category — prompt→component, wired into [`design-component-generator`](agents/design-component-generator.md) as `<!-- impl: -->` sections). Plasmic is dual (canvas + generator). Onboarding grows 21 → 27. Each is an opt-in MCP/API connection that degrades to code-only when absent — **no new runtime dependency**. First sub-phase of Phase 37 (Greenfield DS Bootstrap follows).
+
+### Greenfield design-system bootstrap (v1.37.2)
+
+`/gdd:bootstrap-ds` gives a brand-new project a coherent design system from a brand input (a primary color + optional secondary + tone tags + target framework). The pure [`token-scale`](scripts/lib/ds/token-scale.cjs) helper emits a 9-stop OKLCH color scale as native CSS `oklch()` (no color-conversion library), a modular type scale, a 4pt/8pt spacing scale, and radius/motion defaults; [`ds-generator`](agents/ds-generator.md) offers **3 variants** (conservative / balanced / bold) to pick from per [`reference/ds-bootstrap-rubric.md`](reference/ds-bootstrap-rubric.md), then scaffolds button/input/card proof components. Never invents a brand; never overwrites an existing DS. **No new runtime dependency.** This **completes Phase 37** (AI-native Wave 2 + greenfield bootstrap).
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/SKILL.md

@@ -100,6 +100,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
 | `benchmark <component\|--wave N\|--list\|--refresh component>` | `get-design-done:gdd-benchmark` | Harvest + synthesize per-component design specs from 18 design systems → `reference/components/<name>.md` |
 | `export <cycle> --format html\|pdf\|notion [--pseudonymize] [--pr]` | `get-design-done:gdd-export` | Phase 35.5 — package a finished cycle's design output into a stakeholder-shareable artifact (self-contained HTML / Paged.js-print PDF / Notion page); redacts always, `--pseudonymize` masks identity for external sharing, `--pr` posts the HTML preview via pr-commenter |
+| `bootstrap-ds [--primary <color>] [--secondary <color>] [--tone <tags>] [--framework <t>]` | `get-design-done:gdd-bootstrap-ds` | Phase 37.2 — bootstrap a design system for a GREENFIELD project (no DS): brand input → OKLCH token system (color tints + modular type + 4pt/8pt spacing + radius/motion) in 3 variants to pick, then button/input/card proof scaffolding via `ds-generator` |
 
 ## Handoff Routing
 

package/agents/design-component-generator.md

@@ -31,7 +31,11 @@ Read `.design/STATE.md` `<connections>` block. Check for:
 - `magic-patterns: available` → prefer magic-patterns (DS-aware + preview_url); use magic-patterns impl
 - `21st-dev: available` (and magic-patterns not available) → use 21st.dev impl
 - Both available → prefer magic-patterns (DS-aware + preview_url); 21st.dev as fallback
-- Neither available → Print: "No component generator configured. Set up 21st.dev or Magic Patterns per connections/21st-dev.md or connections/magic-patterns.md." STOP.
+- `v0-dev: available` → use the v0 impl (generator; MCP-first → REST + `V0_API_KEY`)
+- `plasmic: available` → use the plasmic impl (canvas read + code emission)
+- `builder-io: available` → use the builder-io impl (Visual Copilot; pull-only this phase)
+- Priority when several are available: magic-patterns > 21st.dev > v0 > plasmic > builder-io (DS-awareness + preview first); `--tool` overrides.
+- None available → Print: "No component generator configured. Set up 21st.dev / Magic Patterns / v0.dev / Plasmic / Builder.io per the matching `connections/<tool>.md`." STOP.
 
 ---
 
@@ -39,7 +43,7 @@ Read `.design/STATE.md` `<connections>` block. Check for:
 
 Parse flags:
 - `--dry-run` — emit proposal only, no writes
-- `--tool 21st|magic-patterns` — override generator selection
+- `--tool 21st|magic-patterns|v0|plasmic|builder-io` — override generator selection
 - `--ds <design-system>` — design system target: `shadcn | tailwind | mantine | chakra`
 - Component description (required positional arg): natural-language component spec
 
@@ -164,6 +168,30 @@ After generating, write `preview_url` to STATE.md `<generator>` block (see Step
 
 <!-- /impl: magic-patterns -->
 
+<!-- impl: v0 -->
+## v0.dev Implementation
+
+### Step 2D — v0.dev: Generate
+
+Probe per `connections/v0-dev.md` (MCP-first → REST + `V0_API_KEY`). Generate from the description + DS context: MCP available → call the v0 generate tool (verify the name via ToolSearch) with the spec + `--ds` target; REST fallback → POST the spec to the v0 Platform API with `V0_API_KEY`. v0 emits React + Tailwind + shadcn by default — reconcile to the project `--ds`. Carry into Step 3 (proposal); never write to `src/` without confirmation. Full tool catalogue + setup: `connections/v0-dev.md`.
+<!-- /impl: v0 -->
+
+<!-- impl: plasmic -->
+## Plasmic Implementation
+
+### Step 2E — Plasmic: Read canvas + emit code
+
+Probe per `connections/plasmic.md`. Plasmic is dual: **canvas read** → pull the Plasmic project's components as a design source (like Figma); **code emission** → emit the component code for the `--ds` target. Reconcile emitted code to the project DS; carry into Step 3 (proposal). Detail: `connections/plasmic.md`.
+<!-- /impl: plasmic -->
+
+<!-- impl: builder-io -->
+## Builder.io Implementation
+
+### Step 2F — Builder.io: Visual Copilot (pull-only)
+
+Probe per `connections/builder-io.md` (MCP-first → `BUILDER_API_KEY`). **Pull-only this phase**: generate / ingest patterns via Visual Copilot, reconcile to `--ds`, carry into Step 3 (proposal). NO write-back this phase. Detail: `connections/builder-io.md`.
+<!-- /impl: builder-io -->
+
 ---
 
 ## Step 3 — Build Proposal

package/agents/ds-generator.md

@@ -0,0 +1,74 @@
+---
+name: ds-generator
+description: Greenfield design-system generator. Turns a brand input (primary color + optional secondary + tone tags + target framework) into a coherent token system — OKLCH color tints/shades, a modular type scale, a 4pt/8pt spacing scale, radius + motion defaults — via the pure scripts/lib/ds/token-scale.cjs and reference/ds-bootstrap-rubric.md. Emits 3 variants (conservative/balanced/bold) for the user to pick, then scaffolds proof components (button/input/card) in the detected framework. Proposal→confirm; never overwrites an existing design system.
+tools: Read, Write, Bash, Glob, Grep
+color: green
+default-tier: opus
+tier-rationale: "Greenfield token-system synthesis is a design-judgment task (OKLCH color relationships, scale selection, tone→ratio mapping grounded in color-theory) — Opus-tier, not a mechanical worker."
+size_budget: LARGE
+size_budget_rationale: "Honest tier sized to the ~120-line body. The agent states the brand-input → token-system → 3-variants → scaffold flow and DELEGATES the deterministic math to scripts/lib/ds/token-scale.cjs and the emission rules to reference/ds-bootstrap-rubric.md (the pdf-executor→validate-print-css precedent)."
+parallel-safe: false
+typical-duration-seconds: 90
+reads-only: false
+writes:
+  - ".design/tokens/**"
+  - "src/** (proof components, on confirm only)"
+---
+
+@reference/shared-preamble.md
+
+# ds-generator
+
+## Role
+
+Bootstrap a coherent design system for a **greenfield** project that has none — no Figma, no token file, no component library. Take a brand input and emit a token system + a few proof components, grounded in `reference/ds-bootstrap-rubric.md` + `reference/color-theory.md`, using the deterministic `scripts/lib/ds/token-scale.cjs`. **Never invent a brand** (no logomark, no typeface, no third brand color) and **never overwrite an existing DS** — if `design-context-builder` already mapped one, stop and defer to it.
+
+## When invoked
+
+By `/gdd:bootstrap-ds` (the skill collects the brand input). Also reachable when `design-context-builder` detects a greenfield project (no DS signals) and the user opts in.
+
+## Inputs (brand input)
+
+- **primary** (required) — a brand color (hex / rgb / `oklch()`). Convert to OKLCH `{l, c, h}`.
+- **secondary** (optional) — a second brand color. Emitted only if supplied (rubric ≤2-colors rule).
+- **tone tags** (optional) — e.g. `calm`, `corporate`, `editorial`, `playful`, `bold` → maps to the type ratio + chroma treatment per the rubric.
+- **target framework** (optional) — `web` (default) / `native-ios` / `native-android` / `flutter` (Phase 34 routing). Detect from the project if absent.
+
+## Step 1 — Resolve the primary to OKLCH
+
+Parse the brand primary to `{ l, c, h }`. If given as hex/rgb, convert to OKLCH (state the conversion; do NOT add a color library — use a documented inline conversion or ask the user for the `oklch()` value). Validate `l ∈ 0..1`, `c ≥ 0`, `h ∈ 0..360`.
+
+## Step 2 — Generate the 3 variants
+
+For each of **conservative / balanced / bold** (rubric table), run the pure generator and assemble a token set:
+
+```bash
+node -e "const t=require('./scripts/lib/ds/token-scale.cjs'); \
+  console.log(JSON.stringify({ \
+    color: t.oklchScale({l:L,c:C,h:H}), \
+    type: t.typeScale(1, RATIO), \
+    space: t.spacingScale(BASE, 8), \
+    radius: t.radiusScale(R) }, null, 2))"
+```
+
+Vary chroma (×0.8 / ×1.0 / ×1.15-clamped), type ratio (1.2 / 1.25 / 1.333), and radius (4 / 8 / 12) per the rubric. Emit neutrals (low-chroma ramp) + semantic colors (success/warning/danger/info at fixed hues) the same way. Verify text/surface pairings clear WCAG AA (`reference/color-theory.md`).
+
+## Step 3 — Present + pick (D-02)
+
+Show the 3 variants compactly (the `500` primary, the type ratio, the spacing baseline, the radius, a one-line feel). The user picks ONE. Do not scaffold before the pick.
+
+## Step 4 — Emit the chosen token set (proposal → confirm)
+
+Emit role-named CSS custom properties (`:root { --color-primary-500: oklch(...); --space-4: 16px; --radius-md: 8px; ... }`) as the canonical artifact, plus the target-framework mapping (web → Tailwind `theme.extend` / shadcn CSS vars; native → `reference/native-platforms.md`). Propose the file(s); write only on confirm.
+
+## Step 5 — First-component scaffolding (proof)
+
+Emit **button + input + card** in the target framework, consuming only the emitted tokens — a coherence proof, not a component library. Proposal→confirm; never write to `src/` without it.
+
+## Record
+
+Emit a `## Bootstrap summary` for the cycle: the chosen variant, the token counts (9 color stops + neutrals + semantics, N type steps, N spacing steps), the framework, and the scaffolded components. Close with:
+
+```
+## DS BOOTSTRAP COMPLETE
+```

package/connections/builder-io.md

@@ -0,0 +1,131 @@
+# Builder.io — Connection Specification
+
+This file is the connection specification for Builder.io Visual Copilot within the get-design-done pipeline. Builder.io Visual Copilot is an AI-native **generator-category** tool — it converts designs (Figma frames, imported layouts) into framework code and generates UI components from descriptions. It integrates via the Builder MCP / Visual Copilot or via a direct API key. See `connections/connections.md` for the full connection index and capability matrix.
+
+**Scope this phase: PULL-ONLY.** Builder.io is used to *ingest patterns* and *generate* code into the pipeline. Write-back (publishing components or content models back to Builder.io spaces) is **deferred** — not wired this phase. See [21st.dev](21st-dev.md) for the sibling generator-category spec.
+
+---
+
+## Setup
+
+### Prerequisites
+
+**Path A — Builder MCP / Visual Copilot (preferred):**
+- A [Builder.io](https://www.builder.io) account
+- The Builder MCP or Visual Copilot enabled in your Claude environment
+- No additional manual setup when the connector is enabled
+
+**Path B — API key fallback:**
+- A Builder.io account and API key (public/private key for your Builder space)
+- `BUILDER_API_KEY` environment variable set
+- MCP server install (example):
+  ```bash
+  claude mcp add builder-io --transport http https://mcp.builder.io/sse \
+    -e BUILDER_API_KEY=$BUILDER_API_KEY
+  ```
+
+### Verification
+
+```
+ToolSearch({ query: "builder", max_results: 5 })
+```
+
+Non-empty results including a Builder generate/figma-import tool → connector available (Path A).
+Empty → check `BUILDER_API_KEY`; if set, install Path B and restart the Claude Code session.
+
+---
+
+## Probe Pattern
+
+Builder.io uses a **MCP-first, env-fallback** probe. Check for Builder tools first; fall back to the API key env var.
+
+```
+ToolSearch({ query: "builder", max_results: 5 })
+→ Non-empty  → builder-io: available (MCP / Visual Copilot)
+→ Empty      → check BUILDER_API_KEY env var
+               set    → builder-io: available (API key path)
+               unset  → builder-io: not_configured
+```
+
+Three-value schema written to `.design/STATE.md` `<connections>`:
+
+| Value | Meaning |
+|-------|---------|
+| `available` | Builder MCP tools found, OR `BUILDER_API_KEY` is set |
+| `not_configured` | No Builder tools and no API key — skip all Builder.io steps |
+| `error` | Tools present but probe/auth failed — degrade, surface the error, never block |
+
+Write result to STATE.md `<connections>`: `builder-io: <status>`
+
+Fallback: when `not_configured`, the generator stage skips Builder.io and falls back to another generator (if available) or degrades to manual code-only build.
+
+---
+
+## Builder.io Tools
+
+Builder.io exposes Visual Copilot capabilities through MCP tools. Names and exact signatures vary by connector version — discover them via the probe (`ToolSearch({ query: "builder" })`) rather than hardcoding. Described generically, the relevant **pull-only** capabilities are:
+
+| Capability | Stage | Purpose |
+|------------|-------|---------|
+| Figma → code generate | generator | Convert a selected Figma frame/URL into framework code (React, Vue, Svelte, Angular, etc.) |
+| Describe → component generate | generator | Generate a UI component from a natural-language description |
+| Pull / ingest pattern | generator | Fetch an existing Builder block/pattern as a starting point for adaptation |
+
+### Typical generate inputs (generic)
+
+| Input | Values | Notes |
+|-------|--------|-------|
+| `source` | Figma frame URL / selection, or description | Pull-side input — the design or spec to convert |
+| `framework` | `"react" \| "vue" \| "svelte" \| "angular"` | Auto-detected from the project in the explore stage |
+| `styling` | `"tailwind" \| "css" \| "styled-components"` | Auto-detected; defaults to the project's active styling |
+
+Returns generated source code (and, where supported, a preview reference) for the generator stage to consume.
+
+---
+
+## Pipeline Integration
+
+Builder.io is wired as a **generator-category** connection: it feeds the **generator** stage only.
+
+| Stage | What Builder.io provides |
+|-------|--------------------------|
+| generator | Figma → code / describe → component generation via `agents/design-component-generator.md` |
+| generator | Pull / ingest an existing Builder pattern as adaptation source |
+
+### Generator wiring
+
+The generator stage dispatches to Builder.io through the `<!-- impl: builder-io -->` section of `agents/design-component-generator.md`. That agent:
+
+1. Reads `builder-io: available` from STATE.md `<connections>` before dispatching.
+2. Resolves the generate inputs (Figma source or description; `framework`; `styling`) from project context.
+3. Calls the Builder generate/pull capability and captures the returned source code.
+4. Writes the generated component into the project as a **proposal**, not a direct commit.
+
+### Pull-only scope (write-back deferred)
+
+This phase wires **ingest + generate only**:
+
+- **Ingest**: pull existing Builder patterns/blocks as adaptation sources.
+- **Generate**: Figma → code and describe → component into the pipeline.
+- **NO write-back**: the pipeline does **not** publish components, content models, or edits back to Builder.io spaces this phase. Write-back / roundtrip is explicitly **deferred** to a later phase.
+
+### Proposal → confirm
+
+Generated code is **never** auto-inserted. The generator surfaces the result as a proposal; the design-executor confirms adoption with the user before the code is written into the working tree. This mirrors the decision-gate pattern used by sibling generators (see [21st.dev](21st-dev.md)) — the agent surfaces candidates, the user/executor decides.
+
+---
+
+## Fallback Behavior
+
+When `builder-io: not_configured`:
+- Print: `Builder.io not configured — Visual Copilot generator skipped.`
+- Falls back to another generator-category connection if one is `available` (e.g. 21st.dev, Magic Patterns).
+- If no generator is configured, the generator stage **degrades to code-only**: the design-executor proceeds with a manual component build.
+- Builder.io **never blocks** the pipeline — a missing or errored connection only removes one generator option; the generator stage always has a code-only path.
+
+When `builder-io: error`:
+- Surface the probe/auth error to the user, mark the connection degraded, and fall back as above. Do not retry in a loop and do not block.
+
+---
+
+Do NOT edit the connection index here — the 37.1 wiring plan adds the Active-Connections row + matrix entry.

package/connections/connections.md

@@ -2,7 +2,7 @@
 
 This directory contains connection specifications for external tools and MCPs that the get-design-done pipeline integrates with. Each connection has its own spec file. This file is the index.
 
-**Getting started:** run `/gdd:connections` for the interactive onboarding wizard — it probes all 21 connections, recommends setup based on your project type, and walks you through installing each one (auto-run for reversible MCP adds, copy-command for everything else). You can also run `/gdd:connections list` for a read-only status check or `/gdd:connections <name>` to jump to a single connection's setup.
+**Getting started:** run `/gdd:connections` for the interactive onboarding wizard — it probes all 27 connections, recommends setup based on your project type, and walks you through installing each one (auto-run for reversible MCP adds, copy-command for everything else). You can also run `/gdd:connections list` for a read-only status check or `/gdd:connections <name>` to jump to a single connection's setup.
 
 ---
 
@@ -37,6 +37,12 @@ This directory contains connection specifications for external tools and MCPs th
 | Notion | Active | [`connections/notion.md`](connections/notion.md) | **Export** write-path (not a pipeline stage) — `mcp__notion__*` (ToolSearch probe); `/gdd:export --format notion`; redact + `GDD_DISABLE_NOTION` kill-switch; degrade-to-HTML |
 | Lottie | Active | [`connections/lottie.md`](connections/lottie.md) | **Optional** motion verify (Lottie JSON); static floor = `validate-motion.cjs` (MO-* warnings + perf budget); player opt-in; WARN-never-block, degrade-to-static/code-only (36.2, D-02/D-03) |
 | Rive | Active | [`connections/rive.md`](connections/rive.md) | **Optional** motion verify (Rive `.riv`); size + RIVE-header floor; deep state-machine graph via opt-in Rive runtime, else manual-review advisory; WARN-never-block (36.2, D-02/D-04) |
+| Framer | Active | [`connections/framer.md`](connections/framer.md) | **AI-native** (Wave 2, canvas) — read frames + write proposals; MCP probe; degrade-to-code-only (37.1) |
+| Penpot | Active | [`connections/penpot.md`](connections/penpot.md) | **AI-native** (Wave 2, canvas) — open-source Figma alt; self-hosted-vs-cloud probe; degrade-to-code-only (37.1) |
+| Webflow | Active | [`connections/webflow.md`](connections/webflow.md) | **AI-native** (Wave 2, generator) — read site structure as an adaptation source (not CMS authoring); degrade-to-code-only (37.1) |
+| v0.dev | Active | [`connections/v0-dev.md`](connections/v0-dev.md) | **AI-native** (Wave 2, generator) — Vercel v0; MCP-first → REST + `V0_API_KEY`; component-generator `v0` impl (37.1) |
+| Plasmic | Active | [`connections/plasmic.md`](connections/plasmic.md) | **AI-native** (Wave 2, dual) — canvas read + code emission; component-generator `plasmic` impl (37.1) |
+| Builder.io | Active | [`connections/builder-io.md`](connections/builder-io.md) | **AI-native** (Wave 2, generator) — Visual Copilot, pull-only this phase; component-generator `builder-io` impl (37.1) |
 
 ---
 
@@ -66,6 +72,12 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 | Print-Renderer | — | — | — | print render-test target (pdf-executor) | rendered PDF/page evidence when the print-render is available, else degrade to the static print-CSS validator / code-only (D-03) | — | — | — | — |
 | Lottie | — | — | — | — | Lottie-export motion check: `validate-motion.cjs` (MO-FR/DUR/IMG/BUDGET) when present, WARN-never-block (D-02) | — | — | — | — |
 | Rive | — | — | — | — | Rive-export motion check: size + RIVE-header floor; state-machine graph via opt-in runtime, else manual-review advisory; WARN (D-02/D-04) | — | — | — | — |
+| Framer | — | — | — | canvas source (read frames, write proposals) | — | ✓ | — | — | — |
+| Penpot | — | — | — | canvas source (read boards/components) | — | ✓ | — | — | — |
+| Webflow | — | — | — | structure / adaptation source | — | — | ✓ | — | — |
+| v0.dev | — | — | — | component-generator (v0 impl) | — | — | ✓ | — | — |
+| Plasmic | — | — | — | component-generator (plasmic impl) + canvas read | — | ✓ | ✓ | — | — |
+| Builder.io | — | — | — | component-generator (builder-io impl) | — | — | ✓ | — | — |
 | Lazyweb | — | reference search via `lazyweb_search` (**Tier 1 — free, tried first**; D-01); complements refero/pinterest | — | — | — | — | — | — | — |
 | Mobbin | — | reference search via mobbin tools (**Tier 2 — paid, mobile/flow-level**; D-01); complements refero/lazyweb | — | — | — | — | — | — | — |
 | Slack | — | — | — | — | — | — | — | verify-fail/audit-pass/ship → Slack webhook (routed, redacted, degrade-to-noop; D-04/D-05) | — |

package/connections/framer.md

@@ -0,0 +1,126 @@
+# Framer — Connection Specification
+
+This file is the connection specification for **Framer** within the get-design-done pipeline. Framer is an AI-native canvas design tool (Wave 2). Like Figma, it is a **canvas-category** connection: GDD reads the current Framer selection/frames as a design source and writes annotated design proposals back. It is **not** a code generator — the pipeline never asks Framer to emit production components. See `connections/connections.md` for the full connection index and capability matrix.
+
+This is an **opt-in, user-connected** tool. There is no bundled dependency — GDD ships no Framer client. The connection only activates when the user has independently registered a Framer MCP (or plugin bridge) in their session.
+
+---
+
+## Setup
+
+### Prerequisites
+- A [Framer](https://www.framer.com) account with edit access to the target project.
+- A Framer API token (or plugin authorization) — generated from the Framer account/workspace settings and scoped to the projects GDD may read or propose against.
+- A Framer MCP server **or** the Framer plugin bridge registered in the Claude Code session. Framer's surface evolves quickly; resolve the exact transport at runtime via the probe below rather than hardcoding it.
+
+### How to connect
+
+**Option A — Framer MCP (preferred).** Register the Framer MCP over HTTP transport, supplying the API token via environment:
+
+```
+claude mcp add --transport http framer https://<framer-mcp-endpoint>
+```
+
+Set the token in the session environment (name as documented by the Framer MCP — commonly `FRAMER_API_TOKEN`). Restart the Claude Code session after registering. Auth prompts on first tool call.
+
+**Option B — Framer plugin bridge.** If Framer exposes a desktop/plugin bridge instead of a hosted MCP, install that plugin inside Framer and register its local endpoint as an MCP server named `framer`. This path mirrors Figma's desktop Dev Mode bridge: it serves the current open project to the session over local HTTP.
+
+The pipeline auto-detects any server whose name matches `/framer/i` (e.g., `framer`, `Framer`, UUID-prefixed instances) and records the resolved tool prefix in `STATE.md`. Exact tool names are **not** assumed — they are discovered at runtime.
+
+### Verification
+
+After session restart, run:
+
+```
+ToolSearch({ query: "framer", max_results: 10 })
+```
+
+Expect non-empty results under a `/framer/i` prefix, including at least one read tool (selection/frame reader) and, for write-back, a proposal/annotation tool. If empty, re-register the MCP and restart the session.
+
+---
+
+## Probe Pattern
+
+**MCP-first. Call `ToolSearch` before any Framer tool — always.** Framer tools are commonly in the deferred tool set and are not loaded into context at session start. Calling a deferred tool directly fails. `ToolSearch` loads the tools and confirms their presence in one call.
+
+```
+ToolSearch({ query: "framer", max_results: 10 })
+→ Empty       → framer: not_configured   (no Framer MCP registered; skip all Framer steps)
+→ Non-empty   → resolve prefix matching /framer/i, then live-probe a read tool:
+                 → read tool succeeds  → framer: available (prefix=mcp__<prefix>__)
+                 → read tool errors    → framer: unavailable (auth expired / no project open / rate-limited)
+```
+
+Three-value schema written to `.design/STATE.md` under `<connections>`:
+
+| Value | Meaning |
+|-------|---------|
+| `available` | A `/framer/i` read tool resolved and the live call succeeded. |
+| `unavailable` | A Framer tool is in the session but errored (auth expired, no project open, rate-limited). |
+| `not_configured` | No server matching `/framer/i` — MCP not registered. |
+
+Example STATE block:
+
+```xml
+<connections>
+framer: available (prefix=mcp__framer__)
+figma: not_configured
+</connections>
+```
+
+Re-probe at every stage entry, even if Framer was `available` previously — the resolved prefix and availability can change between sessions.
+
+---
+
+## Framer Tools
+
+Tool names take the form `mcp__<prefix>__<tool>` where `<prefix>` is the resolved server name from the probe (commonly `framer`). **Verify exact tool names via `ToolSearch` at runtime** — the table below describes capabilities generically, not literal identifiers.
+
+**Reads (design source):**
+
+| Capability | Returns | Pipeline use |
+|------------|---------|--------------|
+| Selection reader | The currently selected frame(s)/layer(s): node IDs, names, types, geometry | **In scope** — design source for the current selection; also the availability probe |
+| Frame / canvas reader | Frame tree for the open project or page: hierarchy, layout, component instances | **In scope** — reads frames as a design source for the design stage |
+| Token / style reader | Color, spacing, typography, and shared-style definitions used in the project | **In scope (when present)** — supplements token extraction, mirroring Figma `get_variable_defs` |
+| Screenshot / preview | Rendered image of the selected frame | **In scope (opt-in)** — visual reference capture; not invoked by default |
+
+**Writes (design proposals):**
+
+| Capability | Returns | Pipeline use |
+|------------|---------|--------------|
+| Annotation / proposal writer | Write operation result | **In scope** — writes annotated design proposals (notes, decision callouts) back onto frames |
+
+GDD only ever writes **annotated proposals** — design-decision notes and callouts attached to frames. It does not author production components or replace user content. Every write goes through a **proposal → confirm** UX: the agent builds a numbered operation list and the user confirms before any write tool is called. There is no auto-approve path.
+
+---
+
+## Pipeline Integration
+
+Framer is a **canvas-category** connection. It contributes at the **design** stage exactly as Figma and paper.design do (see `connections/figma.md`): read frames as a design source, write annotated proposals back. It does not participate in `scan`, `plan`, or `verify` as a code authority.
+
+| Stage | What Framer provides |
+|-------|----------------------|
+| design (read) | Read the current selection/frames as a **design source** — geometry, hierarchy, and (when present) token/style definitions feed the design proposal. |
+| design (write) | After the design proposal is built, offer to write **annotated proposals** back onto Framer frames via the proposal → confirm UX — only when `framer: available`. |
+| scan / plan / verify | Not used. Framer is a design-stage source, not a code authority. |
+
+The read path requires an open Framer project/selection. If nothing is selected, the frame reader is used for the open page; if no project is open, the live probe falls to `unavailable` and the stage continues on its non-Framer path. The write offer appears only when `framer: available` — never on `unavailable` or `not_configured`.
+
+---
+
+## Fallback Behavior
+
+When `framer` is `not_configured` or `unavailable`, the pipeline **degrades to code-only** and **never blocks**:
+
+- **design (read):** skip the Framer design-source step. Proceed with code-derived context and any other available canvas connection. No error is raised.
+- **design (write):** skip the proposal write-back offer entirely — no prompt, no output — on both `not_configured` and `unavailable`.
+- A standalone request to write proposals to Framer against `framer: not_configured` STOPs with a short install note (point the user at the Setup section above).
+
+Framer is an **enhancement, not a requirement**. Stages do not append a `<blocker>` for a missing Framer connection. Only if a `must_have` explicitly requires Framer data (reads or writes) should a blocker be appended.
+
+**Consumer contract.** Agents that call Framer tools MUST read the resolved prefix from `STATE.md` and construct tool names dynamically (`{prefix}<read_tool>`, `{prefix}<write_tool>`) rather than hardcoding `mcp__framer__`, and MUST treat `unavailable` and `not_configured` identically for the purpose of skipping Framer steps.
+
+---
+
+> ⚠︎ **Do NOT edit the connection index here** — the Active-Connections row and the capability-matrix entry in `connections/connections.md` are added by the **37.1 wiring plan**, not by this spec. This file documents the Framer connection in isolation; wiring it into the index is a separate, tracked step.