@hegemonart/get-design-done 1.36.3 → 1.37.2

package/connections/penpot.md

@@ -0,0 +1,148 @@
+# Penpot — Connection Specification
+
+This file is the connection specification for **Penpot** within the get-design-done pipeline. Penpot is an open-source, self-hostable design and prototyping platform — an AI-native (Wave 2) alternative to Figma. It is a **canvas-category** tool: GDD reads boards and components, exports tokens, and writes design proposals back. See `connections/connections.md` for the full connection index and capability matrix, and `connections/figma.md` for the sibling canvas-category connection.
+
+GDD connects to **your** Penpot instance. It does **not** install, bundle, or host Penpot — there is no bundled dependency. You bring a running Penpot (self-hosted or cloud) plus an access token.
+
+---
+
+## Setup
+
+### Prerequisites
+
+- **A Penpot instance.** One of two deployment shapes:
+  - **Cloud** — the hosted service at [penpot.app](https://penpot.app). Base URL is `https://design.penpot.app`. No infrastructure to run.
+  - **Self-hosted** — a Penpot deployment you operate (Docker/Kubernetes), reachable at your own origin, e.g. `https://penpot.internal.example.com`. See [help.penpot.app](https://help.penpot.app) for deployment guidance.
+- **An access token.** Generated from your Penpot profile under **Settings → Access tokens**. Tokens are scoped to your account on whichever instance issued them — a cloud token does not authenticate against a self-hosted instance, and vice versa.
+- **One access path** — either:
+  - the **Penpot REST API / plugin** reached over `PENPOT_BASE_URL` + token (the env path), or
+  - a **Penpot MCP server** registered in the session (the MCP path).
+
+### Configuration
+
+The pipeline supports two interchangeable access paths. You only need one; if both are present, the probe resolves precedence (see **Probe Pattern**).
+
+**Env path (REST API / plugin).** Set two environment variables:
+
+```bash
+export PENPOT_BASE_URL="https://design.penpot.app"   # cloud
+# or, self-hosted:
+export PENPOT_BASE_URL="https://penpot.internal.example.com"
+export PENPOT_ACCESS_TOKEN="<your-penpot-access-token>"
+```
+
+`PENPOT_BASE_URL` is the **distinguishing signal** between cloud and self-hosted. The pipeline records the host so downstream stages know which deployment they are talking to.
+
+**MCP path.** Register a Penpot MCP server in Claude Code settings (`mcpServers.penpot`), passing `PENPOT_BASE_URL` and `PENPOT_ACCESS_TOKEN` through the server's `env`. Restart the session after install.
+
+### Verification
+
+```
+ToolSearch({ query: "penpot", max_results: 5 })
+```
+
+A non-empty result confirms the MCP path. For the env path, a `200` from `GET $PENPOT_BASE_URL/api/rpc/command/get-profile` (header `Authorization: Token $PENPOT_ACCESS_TOKEN`) confirms the credentials resolve. If the env path is unset and `ToolSearch` is empty, Penpot is `not_configured`.
+
+---
+
+## Probe Pattern
+
+Penpot exposes **two independent access paths**, and the probe checks **both** before resolving. This is the load-bearing distinction for this connection (SC#2): the env path additionally carries the **self-hosted-vs-cloud** signal, which downstream stages need.
+
+```
+Step 1 — Env probe (self-hosted vs cloud):
+  Read PENPOT_BASE_URL and PENPOT_ACCESS_TOKEN from the environment.
+    Both set    → env path present.
+                  Classify deployment from the host of PENPOT_BASE_URL:
+                    host == design.penpot.app   → deployment=cloud
+                    any other host              → deployment=self-hosted
+    Either unset → env path absent.
+
+Step 2 — MCP probe:
+  ToolSearch({ query: "penpot", max_results: 5 })
+    Non-empty → MCP path present (record resolved prefix mcp__<name>__).
+    Empty     → MCP path absent.
+
+Step 3 — Resolve which is present:
+  env + MCP   → available  (path=mcp, deployment=<cloud|self-hosted>)   # prefer MCP for tool calls; keep deployment from env
+  MCP only    → available  (path=mcp, deployment=unknown)              # deployment not derivable without PENPOT_BASE_URL
+  env only    → available  (path=api, deployment=<cloud|self-hosted>)
+  neither     → not_configured
+```
+
+Write the result to `.design/STATE.md` `<connections>` immediately after probing, using the **three-value schema** below:
+
+```xml
+<connections>
+penpot: available (path=mcp, deployment=self-hosted)
+figma: not_configured
+</connections>
+```
+
+Other valid values: `penpot: available (path=api, deployment=cloud)`, `penpot: available (path=mcp, deployment=unknown)`, `penpot: not_configured`.
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| status | `available` / `not_configured` | At least one access path resolved, or none did |
+| `path` | `mcp` / `api` | Which access path the stage should use for tool/REST calls |
+| `deployment` | `cloud` / `self-hosted` / `unknown` | Derived from `PENPOT_BASE_URL` host; `unknown` when only the MCP path is present and no base URL is exported |
+
+Consumers MUST read `path` to decide whether to call MCP tools (`mcp__<prefix>__*`) or REST endpoints, and SHOULD surface `deployment` when an operation differs by host (e.g. rate limits or shared-library scope on cloud vs self-hosted).
+
+---
+
+## Penpot Tools
+
+Tools are described generically — the concrete tool names depend on the resolved `path` (MCP tool names `mcp__<prefix>__<tool>`, or REST commands under `$PENPOT_BASE_URL/api/...`). All capabilities below exist on both cloud and self-hosted instances.
+
+| Capability | Stage | Purpose |
+|------------|-------|---------|
+| **List/read boards** | design | Enumerate projects, files, and boards (frames); read the node tree, names, and layout of a selected board |
+| **Read components** | design | Resolve components and component instances from the file's component library; read variants and overrides |
+| **Export tokens** | scan + discover | Read design tokens (color, spacing, typography) and library assets; Penpot's token format is W3C-style design tokens, so values export cleanly into DESIGN.md |
+| **Read prototype/flows** | design (secondary) | Inspect interactions and flows between boards for reference |
+| **Write proposals** | design (write) | Create or annotate boards/frames with proposed design changes; attach comments carrying D-XX decisions onto the relevant boards |
+
+Reads are the default. Writes are gated behind the same **proposal → confirm** UX used by the Figma connection (see `connections/figma.md`): the agent builds a numbered operation list and presents it before any write executes. No automatic insertion into the user's Penpot file.
+
+---
+
+## Pipeline Integration
+
+Penpot is a **canvas-category** connection. It feeds the **design** stage like Figma and paper.design — the same slot in the pipeline, a different backing tool.
+
+| Stage | What Penpot provides |
+|-------|----------------------|
+| scan | **Token augmentation**: export Penpot design tokens to supplement grep-based CSS token extraction. DESIGN.md notes `source: penpot-tokens` |
+| discover | **Decisions pre-population**: pre-fill D-XX color/spacing/typography decisions from exported tokens before the interview |
+| design | **Board/component reads** for design context; **write proposals** (boards, frames, comments) via the proposal→confirm path when `path` resolves |
+| plan | Not used |
+| verify | Not used |
+
+When multiple canvas-category connections are `available` (e.g. both `figma` and `penpot`), the design stage uses whichever the active design source points to; it does not merge them. The user's source-of-truth selection decides.
+
+---
+
+## Fallback Behavior
+
+When `penpot` is `not_configured`, stages **degrade to code-only** — Penpot is an enhancement, never a requirement, and a missing connection **never blocks** the pipeline.
+
+**scan stage:**
+
+- Skip Penpot token export.
+- Rely on grep-based CSS custom property extraction alone.
+- DESIGN.md token section uses `source: CSS custom properties` (not `source: penpot-tokens`).
+
+**discover stage:**
+
+- Skip token pre-population.
+- Populate D-XX decisions via interview only (manual elicitation from the user).
+
+**design stage:**
+
+- `penpot: not_configured` → skip the write-proposal offer entirely (no prompt, no output).
+- `penpot: available` → offer the opt-in proposal prompt after the design step completes.
+
+Stages do not append a `<blocker>` for a missing Penpot connection. Only if a `must_have` explicitly requires Penpot data (reads or writes) does a stage append a blocker. Always re-probe at stage entry — both the access `path` and the resolved MCP prefix can change between sessions.
+
+Do NOT edit the connection index here — the 37.1 wiring plan adds the Active-Connections row + matrix entry.

package/connections/plasmic.md

@@ -0,0 +1,112 @@
+# Plasmic — Connection Specification
+
+This file is the connection specification for Plasmic within the get-design-done pipeline. Plasmic is a **dual-category** tool: it is both a **visual canvas** (a hosted design/builder surface whose pages and components can be read as a design source, like Figma) **and** a **code generator** (it emits real component code via its codegen loader/API). Because of this, Plasmic earns entries in **both** the `canvas` column **and** the `generator` column of the capability matrix. It integrates via the Plasmic MCP (preferred) or via a project token + loader/codegen API. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+
+**Path A — Plasmic MCP (preferred):**
+- The Plasmic MCP enabled in your Claude environment
+- A Plasmic project (the design lives at [plasmic.app](https://plasmic.app))
+- No additional manual setup when the MCP is present
+
+**Path B — Token + loader/codegen API fallback:**
+- A Plasmic account and a project at [plasmic.app](https://plasmic.app)
+- A project ID + API token (project tokens, found in the project's Code/Configure panel)
+- `PLASMIC_PROJECT_ID` and `PLASMIC_API_TOKEN` environment variables set
+- Loader/codegen access per the docs at [docs.plasmic.app](https://docs.plasmic.app)
+
+### Verification
+
+```
+ToolSearch({ query: "plasmic", max_results: 5 })
+```
+
+Non-empty results (canvas-read + codegen tools) → Plasmic MCP available (Path A).
+Empty → check `PLASMIC_PROJECT_ID` / `PLASMIC_API_TOKEN` and use Path B, then restart the Claude Code session.
+
+---
+
+## Probe Pattern
+
+Plasmic uses an MCP-first, two-path probe. Check the MCP first; fall back to the token env path.
+
+```
+ToolSearch({ query: "plasmic", max_results: 5 })
+→ Non-empty  → plasmic: available (mcp)
+→ Empty      → check PLASMIC_PROJECT_ID + PLASMIC_API_TOKEN env vars
+               both set → plasmic: available (token)
+               either unset → plasmic: not_configured
+```
+
+Write the three-value result to `.design/STATE.md` `<connections>`: `plasmic: <status>`
+where `<status>` ∈ { `available (mcp)`, `available (token)`, `not_configured` }.
+
+Because Plasmic is dual-category, a single `available` status enables **both** roles at once — the canvas read **and** the generator emit. The pipeline decides which role to invoke per stage (see Pipeline Integration); the probe does not split the status.
+
+---
+
+## Plasmic Tools
+
+Plasmic exposes tools spanning **both** capability columns. Describe them generically — exact tool names resolve at probe time via `ToolSearch`.
+
+| Tool (generic) | Column | Stage | Purpose |
+|----------------|--------|-------|---------|
+| `plasmic_list_projects` / `plasmic_get_project` | canvas | canvas | Enumerate Plasmic projects and read project/page/component metadata |
+| `plasmic_read_component` / `plasmic_get_design` | canvas | canvas | Read a page or component from the visual canvas as a design source (structure, props, tokens) |
+| `plasmic_get_tokens` | canvas | canvas | Extract design tokens (color, spacing, typography) defined in the Plasmic project |
+| `plasmic_generate_code` / `plasmic_emit_component` | generator | generator | Emit real component code for a canvas component (codegen / loader) |
+| `plasmic_sync` | generator | generator | Sync/regenerate emitted code after canvas changes (roundtrip) |
+
+Token-path equivalents: the loader/codegen API at [docs.plasmic.app](https://docs.plasmic.app) provides the same two roles — read the project (canvas) and pull generated component code (generator) — when the MCP is absent.
+
+---
+
+## Pipeline Integration
+
+Plasmic plugs into **two distinct stages**, one per capability column. This is the explicit dual-column behavior (SC#5): the same connection is a design **source** at the canvas stage and a code **emitter** at the generator stage.
+
+| Stage | Column | What Plasmic provides |
+|-------|--------|-----------------------|
+| canvas | canvas | **Read the Plasmic design as a source** — pages, components, and tokens, the same way Figma is read. Feeds DESIGN.md and `.design/STATE.md` `<design_system>` token blocks. |
+| generator | generator | **Emit component code** — via `agents/design-component-generator.md`'s `<!-- impl: plasmic -->` section. Returns component source the generator stage writes into the project. |
+
+### Canvas stage — design as source
+
+When `plasmic: available`, the canvas stage may treat a Plasmic project as a first-class design source (peer to Figma):
+
+1. `plasmic_list_projects` → resolve the target project (or read `PLASMIC_PROJECT_ID`).
+2. `plasmic_read_component` / `plasmic_get_design` → pull the page/component structure into the design read.
+3. `plasmic_get_tokens` → extract tokens into `.design/STATE.md` `<design_system>` for downstream generator targeting.
+
+This is a **read** — no code is emitted at this stage. The canvas read is what later stages reason about.
+
+### Generator stage — emit code
+
+The generator stage delegates to `agents/design-component-generator.md`. That agent's `<!-- impl: plasmic -->` section calls the Plasmic codegen path:
+
+1. The agent resolves the canvas component to emit (from the canvas-stage read).
+2. It calls `plasmic_generate_code` / `plasmic_emit_component` (or the loader/codegen API on the token path).
+3. The emitted source is surfaced as a **proposal**, not auto-inserted.
+
+### Proposal → Confirm
+
+Both roles are non-destructive. The canvas read is informational; the generator emit is a **proposal**. The design-executor surfaces the proposed component code to the user/executor, who confirms before any code is written into the project. No automatic insertion, no automatic overwrite of existing components.
+
+---
+
+## Fallback Behavior
+
+When `plasmic: not_configured`:
+- Print: `Plasmic not configured — canvas read and code emit skipped.`
+- **Canvas role** degrades gracefully: the canvas stage falls back to other available design sources (e.g. Figma); Plasmic is simply not offered as a source.
+- **Generator role** degrades to code-only: the generator stage falls back to other available generators (Magic Patterns if `magic-patterns: available`, then 21st.dev if `21st-dev: available` — see `connections/21st-dev.md`), and finally to a manual component build.
+
+Plasmic is **additive and never blocks**: with neither role configured, the pipeline proceeds on its existing canvas source and existing generators exactly as before.
+
+---
+
+Do NOT edit the connection index here — the 37.1 wiring plan adds the Active-Connections row + matrix entries (canvas + generator).

package/connections/v0-dev.md

@@ -0,0 +1,100 @@
+# v0.dev — Connection Specification
+
+This file is the connection specification for v0.dev within the get-design-done pipeline. v0.dev is Vercel's generative-UI tool (AI-native, Wave 2): prompt in, React/Tailwind/shadcn component code out. It is a **generator-category** connection — same family as [21st.dev](21st-dev.md) and [Magic Patterns](magic-patterns.md) — and plugs into the shared component-generator agent as a new implementation (Phase 14 pattern). See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+
+**Path A — MCP (preferred):**
+- A v0.dev MCP server reachable from your Claude environment (probe surfaces the tools).
+- No additional setup once the server is registered and the session is restarted.
+
+**Path B — REST + API key (fallback, phase default):**
+- A v0.dev account and API key from [v0.dev](https://v0.dev) (Vercel's **v0 Platform API**).
+- `V0_API_KEY` environment variable set.
+- Calls hit the v0 Platform API over HTTPS; no local server required.
+
+Per the phase default, **probe MCP first, then fall back to REST + `V0_API_KEY`**. The Platform API is the stable contract; MCP tool names may evolve, so treat MCP as the fast path and the key as the durable one.
+
+### Verification
+
+```
+ToolSearch({ query: "v0", max_results: 5 })
+```
+
+Non-empty results including a v0 generate tool → MCP available (Path A).
+Empty → check `V0_API_KEY`; if set, Path B is active. If unset, v0.dev is not configured.
+
+---
+
+## Probe Pattern
+
+v0.dev uses a two-path probe — MCP-first, then API key.
+
+```
+ToolSearch({ query: "v0", max_results: 5 })
+→ Non-empty  → v0: available (mcp)
+→ Empty      → check V0_API_KEY env var
+               set   → v0: available (api)
+               unset → v0: not_configured
+```
+
+This resolves to a **three-value** status. Write the result to `.design/STATE.md` `<connections>`:
+
+```
+v0: <not_configured | available (mcp) | available (api)>
+```
+
+The generator stage reads this value to decide whether the v0 implementation path is selectable.
+
+---
+
+## v0.dev Tools / API
+
+v0.dev contributes a single core capability at the generator stage: **generate a component from a prompt plus design-system context**. Exact tool/endpoint names are not pinned here — verify them at runtime via the probe (MCP) or the current Platform API docs (REST).
+
+| Capability | Stage | Purpose |
+|------------|-------|---------|
+| generate component | generator | Prompt + DS context → React/Tailwind/shadcn source; returns `{ code, preview_url }` (shape verified at runtime) |
+| iterate / refine | generator | Follow-up prompt against a prior generation to refine output before any write |
+
+**MCP path:** call the discovered generate tool with the DS-aware prompt; read code + preview from its response.
+**REST path:** POST the prompt to the v0 Platform API generate endpoint with `Authorization: Bearer ${V0_API_KEY}`; parse code + preview from the JSON response.
+
+Both paths return generated source plus (typically) a hosted preview URL. Field names differ by transport — resolve them at runtime, do not hardcode against this table.
+
+---
+
+## Pipeline Integration
+
+v0.dev is **generator-category**: it contributes at the **generator** stage only, as one implementation inside the shared generator agent. The agent's `<!-- impl: v0 -->` section in `agents/design-component-generator.md` holds the v0-specific prompt assembly and response handling.
+
+| Stage | What v0.dev provides |
+|-------|----------------------|
+| generator | Prompt + DS context → component source via the `<!-- impl: v0 -->` path in `agents/design-component-generator.md` |
+| generator | `preview_url` (when returned) written to `.design/STATE.md` `<generator>` block for the verify stage |
+
+### DS-Aware Prompting
+
+Before invoking v0.dev, the generator reads the detected design system from `.design/STATE.md` `<design_system>` (populated upstream — see [Magic Patterns](magic-patterns.md) for the shared DS-detection logic). The `<!-- impl: v0 -->` section folds that context into the prompt: target framework (React), styling (Tailwind), and component library (shadcn/ui when present), plus any token or convention notes. v0.dev is shadcn-native, so a shadcn target maps cleanly; other systems are passed as explicit prompt constraints.
+
+### Proposal → Confirm
+
+v0.dev output is **proposed, never auto-written**. The generator surfaces the generated code (and preview, if any) as a proposal; the executor confirms with the user before anything lands in `src/`. This matches the prior-art and proposal gates used by the sibling generator implementations — no automatic code insertion.
+
+---
+
+## Fallback Behavior
+
+When `v0: not_configured`:
+- Print: `v0.dev not configured — generator impl skipped.`
+- Falls back to another generator implementation if available: [21st.dev](21st-dev.md) or [Magic Patterns](magic-patterns.md).
+- If no generator is configured, the generator stage proceeds with a code-only manual build.
+- v0.dev **never blocks** the pipeline — it degrades to a sibling generator or to manual code, and the stage continues either way.
+
+---
+
+Do NOT edit the connection index here — the 37.1 wiring plan adds the Active-Connections row + matrix entry.

package/connections/webflow.md

@@ -0,0 +1,107 @@
+# Webflow — Connection Specification
+
+This file is the connection specification for Webflow within the get-design-done (GDD) pipeline. Webflow is an AI-native Wave 2 generator-category, code-capable canvas: GDD reads a Webflow site's structure and styles and uses them as a **design-adaptation source** — it reads the site's existing design language and emits it as a source for adaptation. GDD does **not** author Webflow CMS schemas, publish content, or write back to the site. See `connections/21st-dev.md` for the structural template this spec follows, and `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+## Setup
+
+### Prerequisites
+
+You need a Webflow site to read from, plus one read path:
+
+**Path A — Webflow MCP (preferred):**
+- The Webflow MCP server registered in your Claude environment (exposes the Webflow Data API as tools).
+- No additional env setup required once the connector is enabled.
+
+**Path B — API token fallback:**
+- A Webflow account with at least one site, at [webflow.com](https://webflow.com).
+- A Data API token (Site settings → Apps & integrations → API access) scoped read-only.
+- `WEBFLOW_API_TOKEN` environment variable set, used against the Data API at [developers.webflow.com](https://developers.webflow.com).
+
+### Verification
+
+```
+ToolSearch({ query: "webflow", max_results: 5 })
+```
+
+Non-empty results (e.g. a site-list / pages / styles read tool) → Webflow MCP available (Path A).
+Empty → check `WEBFLOW_API_TOKEN` and fall back to direct Data API reads (Path B), then restart the Claude Code session if you just registered the connector.
+
+---
+
+## Probe Pattern
+
+Webflow uses an MCP-first probe with an API-token env fallback. Resolve to one of three values and write it to `.design/STATE.md` `<connections>`.
+
+```
+ToolSearch({ query: "webflow", max_results: 5 })
+→ Non-empty  → webflow: available        (MCP path)
+→ Empty      → check WEBFLOW_API_TOKEN env var
+               set    → webflow: available     (API-token path)
+               unset  → webflow: not_configured
+```
+
+A separate `unavailable` status is reserved for the case where the MCP tool is present in the session but errors on probe (auth failure, site offline, rate-limited) — treat it the same as `not_configured` for gating (skip Webflow steps), but record it distinctly.
+
+Three-value status schema (mirrors `connections/connections.md`):
+
+| Status | Meaning |
+|--------|---------|
+| `available` | Webflow read path confirmed (MCP tool responsive, or `WEBFLOW_API_TOKEN` set) |
+| `unavailable` | MCP tool present but errored on probe (auth/site/rate-limit) |
+| `not_configured` | No MCP tool and no API token — Webflow not wired in this session |
+
+Write result to STATE.md `<connections>`: `webflow: <status>`
+
+---
+
+## Webflow Tools
+
+Tools are described generically — exact names depend on the registered MCP server (Path A) or are equivalent Data API read calls (Path B). All are **read-only** in GDD's usage.
+
+| Tool (generic) | Stage | Purpose |
+|----------------|-------|---------|
+| read site structure | design | Enumerate the site's pages and DOM/element hierarchy — the structural skeleton of the existing design |
+| read styles | design | Read style classes, typography, color, spacing, and breakpoint definitions — the site's existing design language |
+| read components | design | Read reusable components / symbols and their composition, for pattern adaptation |
+
+These reads supply raw material for adaptation. GDD never calls a Webflow write/publish/CMS-mutation tool, even when the registered MCP server exposes one.
+
+---
+
+## Pipeline Integration
+
+Webflow is a **generator-category** connection that contributes at the **design** stage as a structure/adaptation source.
+
+| Stage | What Webflow provides |
+|-------|------------------------|
+| design | **Adaptation source**: read the existing site's structure, styles, and components; emit the design language as a source the design stage adapts from |
+
+### Adaptation-source flow (design stage)
+
+1. Probe resolves `webflow: available`.
+2. Read site structure + styles (+ components) via the available path.
+3. Emit the extracted design language as an **adaptation source** for the design stage — structure and style become reference material the generator adapts, alongside other sources (e.g. the project design system, 21st.dev prior art).
+4. The design-executor produces GDD-native output (code / DESIGN.md) informed by that source. Nothing is written back to Webflow.
+
+This is a **read-and-adapt** integration, not a round trip. The Webflow site is treated as inspiration and structural reference; GDD owns the emitted output.
+
+### Explicitly out of scope
+
+- GDD reads structure; it does **not** author or mutate Webflow **CMS schemas** (collections, fields, items). It is a design-adaptation source, not a CMS authoring tool.
+- No publishing, no content writes, no site mutations of any kind.
+
+---
+
+## Fallback Behavior
+
+When `webflow: not_configured` (or `unavailable`):
+
+- Print: `Webflow not configured — adaptation source skipped, proceeding code-only.`
+- The design stage **degrades to code-only**: it proceeds from the project design system and any other available sources without the Webflow design language.
+- Webflow never blocks the pipeline. A missing Webflow connection only removes one optional adaptation source; the design stage continues normally.
+
+---
+
+Do NOT edit the connection index here — the 37.1 wiring plan adds the Active-Connections row + matrix entry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.36.3",
+  "version": "1.37.2",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/ds-bootstrap-rubric.md

@@ -0,0 +1,51 @@
+# Greenfield Design-System Bootstrap Rubric
+
+Emission rules for `/gdd:bootstrap-ds` + `agents/ds-generator.md` — how to turn a brand input (a primary color + optional secondary + tone tags + target framework) into a coherent token system, **without inventing a brand**. The deterministic math lives in `scripts/lib/ds/token-scale.cjs`; the color-theory grounding lives in `reference/color-theory.md`. This file is the rulebook the generator obeys.
+
+GDD does not author a brand identity (logomarks, voice) — it emits a **starter token system + a few proof components** a greenfield project can build on.
+
+---
+
+## Color
+
+- **Primary → 9 tints/shades.** Convert the brand primary to OKLCH `{l, c, h}`, then call `oklchScale(primary)` → 9 stops (`100`…`900`) emitted as native CSS `oklch()`. Stop `500` is the primary exactly; lighter stops interpolate L toward white with damped chroma; darker stops toward black. Native `oklch()` — **no hex conversion, no color library**.
+- **Never auto-generate more than 2 brand colors.** Primary is always emitted. A **secondary** scale is emitted **only if the user supplies one**. Never invent a third brand hue.
+- **Neutrals** — a low-chroma gray ramp (chroma ≤ 0.02) sharing the primary's hue for a subtle tint, or pure neutral (`c = 0`). 9 stops via `oklchScale({ l, c: 0.012, h: primary.h })`.
+- **Semantic colors** — success / warning / danger / info derived at fixed hues (≈145 / 85 / 25 / 255) at the brand's mid-lightness + chroma, so they sit in the same family. These are functional, not "brand" colors (they do not count against the ≤2 rule).
+- **Contrast** — every text-on-surface pairing must clear WCAG AA (see `reference/color-theory.md`); the generator checks the chosen `500`/`700` against white/`50`.
+
+## Typography
+
+- **Modular scale** via `typeScale(baseRem, ratio, steps)`. Base `1rem` (16px). **Ratio ∈ {1.2 (minor third), 1.25 (major third), 1.333 (perfect fourth)}** — pick by tone (calm → 1.2, default → 1.25, editorial/bold → 1.333).
+- Emit named steps (`xs`…`5xl`) from the scale; line-height pairs (tight 1.2 for headings, 1.5 for body).
+- Font family is a **slot**, not a choice — emit a system-font stack placeholder + a `--font-sans` / `--font-mono` variable the user swaps. GDD does not pick a typeface (brand territory).
+
+## Spacing
+
+- **4pt or 8pt baseline** via `spacingScale(basePx, count)` (8pt is the default; 4pt for dense/data UIs). Emit the standard `[1,2,3,4,6,8,12,16]` multiples as `--space-*`.
+
+## Radius + Motion
+
+- **Radius** via `radiusScale(basePx)` → `sm/md/lg/xl/full` (`full = 9999` pill).
+- **Motion defaults** — durations `fast 150ms / base 250ms / slow 400ms`; easing `ease-out` for enters, a standard curve for moves; **always** respect `prefers-reduced-motion` (emit the media-query guard).
+
+## The 3 variants (D-02 — user picks one)
+
+The generator emits three coherent variants; the user picks ONE before first-component scaffolding:
+
+| Variant | Chroma | Type ratio | Spacing | Radius | Feel |
+|---|---|---|---|---|---|
+| **conservative** | damped (×0.8) | 1.2 | 8pt | sm (4) | calm, corporate, dense-friendly |
+| **balanced** (default) | as given | 1.25 | 8pt | md (8) | versatile default |
+| **bold** | boosted (×1.15, clamped) | 1.333 | 8pt | lg (12) | expressive, marketing-forward |
+
+## Emission format
+
+- Emit **CSS custom properties** (`:root { --color-primary-500: oklch(...); --space-4: 16px; ... }`) as the canonical artifact, plus a target-framework mapping:
+  - **web (default)** — a Tailwind `theme.extend` block (or shadcn CSS variables) + the `:root` tokens.
+  - **native** — route the token set through `reference/native-platforms.md` (Phase 34) for SwiftUI / Compose / Flutter theme objects.
+- Tokens are **named by role, not value** (`--color-primary-500`, not `--blue-500`) so a rebrand is a one-line hue change.
+
+## First-component scaffolding (proof artifact)
+
+After the user picks a variant, emit **button + input + card** in the detected target framework, consuming only the emitted tokens — a proof the system is coherent, not a full component library (that is out of scope).

package/reference/registry.json

@@ -972,6 +972,13 @@
       "type": "heuristic",
       "phase": 36.3,
       "description": "Phase 36.3 Tier-3 conversational-UI patterns (voice + chatbot): voice-flow no-input/no-match reprompts + confirmation + human handoff, multi-turn dialogue (context carryover, slot-filling, repair), prompt-as-UX (the assistant persona/tone/boundaries as a versioned design artifact), chatbot empty-states + suggested replies, voice-first onboarding, error recovery + accessibility (transcripts/captions). Carries Detection signals + an Audit checklist; loaded by design-context-builder for the conversational project type. CLI/REPL UX out of scope."
+    },
+    {
+      "name": "ds-bootstrap-rubric",
+      "path": "reference/ds-bootstrap-rubric.md",
+      "type": "heuristic",
+      "phase": 37.2,
+      "description": "Phase 37.2 greenfield DS emission rules for /gdd:bootstrap-ds + agents/ds-generator.md: primary→9 OKLCH tints (native oklch(), no color library), never >2 brand colors, neutrals + semantic colors, modular type scale (ratio 1.2/1.25/1.333), 4pt/8pt spacing, radius + motion defaults, the 3 variants (conservative/balanced/bold), role-named CSS-custom-property emission + framework mapping, and button/input/card proof scaffolding. Deterministic math in scripts/lib/ds/token-scale.cjs."
     }
   ]
 }

package/scripts/lib/ds/token-scale.cjs

@@ -0,0 +1,88 @@
+'use strict';
+/**
+ * scripts/lib/ds/token-scale.cjs — Phase 37.2 greenfield token-scale generator.
+ *
+ * Pure + dep-free (D-01): zero `require`, no color-conversion library. Emits native CSS
+ * `oklch(L C H)` strings — modern browsers render OKLCH directly, so no OKLab→sRGB→hex
+ * conversion is needed. Deterministic: same input → byte-identical output (hermetic tests).
+ *
+ * - oklchScale(primary, opts?)  → 9 tint/shade stops {stop, oklch}, anchored at the primary,
+ *     interpolating lightness toward white/black and damping chroma at the extremes.
+ * - typeScale(baseRem, ratio, steps?) → a modular type scale {step, rem}.
+ * - spacingScale(basePx, count?)      → a 4pt/8pt geometric spacing scale (px).
+ * - radiusScale(basePx?)              → sm/md/lg/xl/full radii (px / 9999 for full).
+ */
+
+const round = (n, d) => {
+  const f = Math.pow(10, d);
+  return Math.round(n * f) / f;
+};
+
+const DEFAULT_STOPS = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+
+/**
+ * oklchScale({ l, c, h }, opts) — l ∈ 0..1 (lightness), c ∈ 0..~0.4 (chroma), h ∈ 0..360 (hue).
+ * Anchors the `anchorStop` (default 500) at the primary, then interpolates L toward `lLight`
+ * for lighter stops and `lDark` for darker stops, damping chroma toward the extremes.
+ */
+function oklchScale(primary, opts = {}) {
+  const { l, c, h } = primary || {};
+  if (typeof l !== 'number' || typeof c !== 'number' || typeof h !== 'number') {
+    throw new TypeError('oklchScale: primary must be { l:number, c:number, h:number }');
+  }
+  const stops = opts.stops || DEFAULT_STOPS;
+  const anchor = opts.anchorStop || 500;
+  const lLight = opts.lLight != null ? opts.lLight : 0.97;
+  const lDark = opts.lDark != null ? opts.lDark : 0.22;
+  const i500 = stops.indexOf(anchor) === -1 ? Math.floor(stops.length / 2) : stops.indexOf(anchor);
+
+  return stops.map((stop, i) => {
+    let L;
+    let C;
+    if (i === i500) {
+      L = l; C = c;
+    } else if (i < i500) {
+      const t = (i500 - i) / i500;                 // 0..1 toward the lightest stop
+      L = l + (lLight - l) * t;
+      C = c * (1 - 0.75 * t);                       // damp chroma toward white
+    } else {
+      const t = (i - i500) / (stops.length - 1 - i500); // 0..1 toward the darkest stop
+      L = l + (lDark - l) * t;
+      C = c * (1 - 0.45 * t);                       // damp chroma toward black (less than toward white)
+    }
+    return { stop, oklch: `oklch(${round(L, 3)} ${round(Math.max(C, 0), 4)} ${round(h, 2)})` };
+  });
+}
+
+/**
+ * typeScale(baseRem, ratio, steps) — a modular scale. Returns `steps.length` entries,
+ * each `{ step, rem }` with rem = baseRem * ratio^step (step 0 = base). Default steps -1..5.
+ */
+function typeScale(baseRem = 1, ratio = 1.25, steps = [-1, 0, 1, 2, 3, 4, 5]) {
+  if (!(baseRem > 0) || !(ratio > 1)) throw new TypeError('typeScale: baseRem > 0 and ratio > 1 required');
+  return steps.map((step) => ({ step, rem: round(baseRem * Math.pow(ratio, step), 3) }));
+}
+
+/**
+ * spacingScale(basePx, count) — a geometric spacing scale off a 4pt/8pt baseline.
+ * Returns `count` entries `{ step, px }` following the standard [1,2,3,4,6,8,12,16,...] multiples.
+ */
+function spacingScale(basePx = 4, count = 8) {
+  if (![4, 8].includes(basePx)) throw new RangeError('spacingScale: basePx must be 4 or 8 (a 4pt/8pt baseline)');
+  const mult = [1, 2, 3, 4, 6, 8, 12, 16, 24, 32];
+  return mult.slice(0, count).map((m, i) => ({ step: i + 1, px: basePx * m }));
+}
+
+/** radiusScale(basePx) — sm/md/lg/xl/full. full = 9999 (pill). */
+function radiusScale(basePx = 8) {
+  if (!(basePx > 0)) throw new TypeError('radiusScale: basePx > 0 required');
+  return {
+    sm: round(basePx / 2, 2),
+    md: basePx,
+    lg: basePx * 2,
+    xl: basePx * 3,
+    full: 9999,
+  };
+}
+
+module.exports = { oklchScale, typeScale, spacingScale, radiusScale, DEFAULT_STOPS };