@hegemonart/get-design-done 1.14.5 → 1.14.8

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,115 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.14.8] — 2026-04-24
+
+### Added — Phase 14.7 First-Run Proof Path
+
+A new user can now install the plugin, run one command, and see GDD inspect their own UI code in under five minutes — with a concrete "first fix" pointer on the way out.
+
+- **`/gdd:start` skill** (`skills/start/SKILL.md`) — leaf command with a locked 5-question interview (`reference/start-interview.md`) that collects pain hint, target-area confirmation, budget preference, framework/design-system confirmation, and visual-workflow selection. Writes only `.design/START-REPORT.md` and a temporary `.design/.start-context.json`; never mutates `STATE.md`, `config.json`, or source files.
+- **`detect-ui-root` helper** (`scripts/lib/detect-ui-root.cjs`) — deterministic priority-ordered detector that identifies the user's UI surface across `packages/ui/src/`, `apps/*/components/`, Next.js app-router `app/components/`, Vite `src/components/`, CRA `src/components/`, root `components/`, and Svelte/Remix `src/routes/`. Backend-only repos get a clean diagnostic and exit with zero `.design/` footprint.
+- **`start-findings-engine` helper** (`scripts/lib/start-findings-engine.cjs`) — read-only scanner with seven regex-based detectors (transition-all, will-change-all, tinted-image-outline, scale-on-press-drift, same-radius-nested, missing-reduced-motion-guard, non-root-font-smoothing), budget-bounded walk (fast / balanced / thorough), and a deterministic **safe-fix rubric** that picks exactly one `best_first_proof` per report.
+- **`design-start-writer` agent** (`agents/design-start-writer.md`) — Haiku-tier writer with `allowed-write-paths: [.design/START-REPORT.md]`. Output contract locks seven H2 sections (`What I inspected`, `Three findings`, `Best first proof`, `Suggested next command`, `Visual Proof Readiness`, `Full pipeline path`, `Connections / writeback optional`) plus one trailing machine-readable JSON block that future `/gdd:fast` / `/gdd:do` invocations can consume.
+- **First-run nudge** (`hooks/first-run-nudge.sh`) — SessionStart hook that surfaces one restrained line pointing at `/gdd:start` only when `.design/config.json` is absent, no dismissal flag exists, and no active pipeline stage is in progress. Per-install dismissal lives at `~/.claude/gdd-nudge-dismissed`. Silent-on-failure posture inherited from Phase 13.3.
+- **Regression fixtures** at `test-fixture/baselines/phase-14.7/` (context-input.json, expected-report-shape.md) and `test-fixture/src/ui-detection/` covering Next.js, Vite, CRA, Remix, two monorepo shapes, backend-only, and empty-repo paths.
+- **Plugin keywords** extended with `onboarding`, `first-run`, `demo`, `proof-path`.
+
+### Non-breaking
+
+Phase 15 target version unchanged (`v1.15.0`). `v1.14.6` remains reserved for Phase 14.6 (test-coverage-completion); this release does not block or reshape that phase.
+
+### Scope notes
+
+- The first-run report **recommends** commands; it never auto-applies fixes. `/gdd:fast` suggestions are printed as ready-to-run text.
+- `/gdd:do` is intentionally **not** surfaced as a suggested command in v1.14.8 (revisit at Phase 15 per Phase 14.7 D-05).
+
+---
+
+## [1.14.7] — 2026-04-24
+
+### Phase 14.6 — Test Coverage Completion (Phase 12 Wave C closeout)
+
+Closes the Phase 12 test-coverage slate that had Waves A + B shipped but Wave C (plans `12-05` / `12-06` / `12-07`) never executed. The plans were migrated to **Phase 14.6** (`.planning/phases/14.6-test-coverage-completion/`) and the gdd-unique test files those plans targeted are now validated end-to-end alongside the pre-existing suite.
+
+### Verified — gdd-unique test coverage (no code diff vs 1.14.6)
+
+Inspection during Phase 14.6 execution confirmed that all 13 gdd-unique test files from the Wave-C migration are present in `tests/` and pass under `npm test`. No net-new test source ships with this release — Phase 14.6's substantive deliverable is the validation, documentation, and closeout bump.
+
+| Area | Test files covered |
+|---|---|
+| Pipeline + data | `pipeline-smoke`, `mapper-schema`, `parallelism-engine`, `touches-analysis`, `cycle-lifecycle`, `intel-consistency` |
+| Feature correctness | `sketch-determinism`, `connection-probe`, `figma-writer-dry-run`, `reflection-proposal`, `deprecation-redirect`, `nng-coverage`, `read-injection-scanner` |
+
+Full suite: **343 tests, 342 pass, 1 skipped, 0 fail**.
+
+### Changed
+
+- `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (outer + `plugins[0]`), `package.json` — version `1.14.6` → `1.14.7`.
+- `tests/semver-compare.test.cjs` — `1.14.7` registered in `OFF_CADENCE_VERSIONS`.
+
+### Notes
+
+- Phase 12 ROADMAP entry remains **Complete** (scope-reduced); Phase 14.6 is now marked **Complete** with the Wave-C + closeout scope that was split out on 2026-04-24.
+- Phase 14.7 (First-Run Proof Path) retains its reserved release slot and will ship as a subsequent PATCH bump (the original `v1.14.7` reservation shifts forward to the next available patch when Phase 14.7 ships).
+
+---
+
+## [1.14.6] — 2026-04-24
+
+### Phase 14.5 — Safety + Recall Floor
+
+Closes two unrelated risks before the Phase 15–19 reference-library expansion and the Phase 20+ autonomy ramp: (a) agents had no typed reference index and no cache-stable L0 preamble; (b) no defense-in-depth around prompt-injected bash, protected-paths violations, runaway blast radius, or the Figma plugin-sandbox hill-climb failure mode. Ships the minimum-viable version of both tracks as one cohesive release.
+
+### Added
+
+**Safety hooks**
+- `hooks/gdd-bash-guard.js` — PreToolUse:Bash guard. 45 dangerous-pattern regexes across 10 families (filesystem destruction, permission escalation, pipe-to-shell, git destruction, system mutation, process nuking, credential exfil, shell obfuscation, path traversal, npm/docker/firewall abuse). `scripts/lib/dangerous-patterns.cjs` normalizes Unicode NFKC + strips ANSI escapes + strips zero-width / bidi overrides before matching so obfuscated attacks (`rm\u200B -rf /`, bidi overrides, hex-encoded `\x72\x6d\x20\x2d\x72\x66`) fail closed.
+- `hooks/gdd-protected-paths.js` + `reference/protected-paths.default.json` — PreToolUse:Edit|Write|Bash guard blocking mutation of `reference/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/archive/**`, `.design/config.json`, `.design/telemetry/**`, `.git/**`, both plugin manifests. User additions in `.design/config.json.protected_paths` MERGE into the default list — users cannot reduce the default-protected set. `scripts/lib/glob-match.cjs` ships a dependency-free `**` glob matcher.
+- `scripts/lib/blast-radius.cjs` — `estimate({touchedPaths, diffStats})` + `estimateMCPCalls({toolCalls})` preflight called by `design-executor` before the first Edit/Write of each task. Defaults: `max_files_per_task: 10`, `max_lines_per_task: 400`, `max_mcp_calls_per_task: 30`. Zero-value limits disable that ceiling. `design-executor` gains a new `## Preflight — Blast-Radius Check` section.
+
+**Injection-scanner extension**
+- `scripts/injection-patterns.cjs` extended from 7 to 22 patterns: classic prompt-injection verbs (incl. `forget previous`), **invisible-Unicode** (zero-width, BOM, bidi overrides), **HTML-comment instruction hijacks** (`<!-- system: …`, hidden divs/spans, zero-font-size tricks), **secret-exfil triggers** (`curl $OPENAI_API_KEY`, `cat .env`, `tar ~ | nc`, `process.env._KEY fetch`, SSH private-key reads). Single source of truth consumed by `hooks/gdd-read-injection-scanner.js`.
+
+**Decision-injector hook (first cross-cycle recall primitive)**
+- `hooks/gdd-decision-injector.js` — PreToolUse:Read on any `.design/**.md | reference/**.md | .planning/**.md` ≥ 1500 bytes. Surfaces the top-15 matching D-XX decisions, L-NN learnings, and cycle-N summary excerpts that reference the opened file's basename or path. Grep backend (ripgrep when available, Node fs fallback); Phase 19.5 will swap in FTS5 transparently.
+
+**Reference registry + L0/L2 cache split**
+- `reference/registry.schema.json` + `reference/registry.json` — typed index of every `reference/*.md` and `.default.json` file (18 entry types: `preamble | meta-rules | heuristic | output-contract | defaults | schema | data | motion | surfaces | authority-feed | influences | easing | taxonomy | principles | emotional-design | experience | palette | style-vocabulary`). Round-trip enforced by `scripts/lib/reference-registry.cjs.validateRegistry()`.
+- `scripts/build-intel.cjs` re-runs `validateRegistry()` on any `reference/**` change.
+- `reference/meta-rules.md` (tier L0) — 5 framework-invariant subsections extracted verbatim from `reference/shared-preamble.md`. `shared-preamble.md` becomes an L0 aggregator (imports `meta-rules.md` first), shrunk from ~6.5KB to <4KB. Stabilizes the Anthropic 5-min prompt-cache prefix.
+- `reference/cycle-handoff-preamble.md` — "reference, not current requests" framing prose imported by `/gdd:pause` and `/gdd:resume`.
+- `reference/retrieval-contract.md` — 3-layer `search → metadata → full-doc` protocol with per-row token-cost labels. Imported by `/gdd:progress`, `/gdd:resume`, `/gdd:reflect`, `/gdd:pause`.
+
+**Figma authoring-intent guard + MCP circuit-breaker**
+- `reference/figma-sandbox.md` — 4 Figma plugin-sandbox pitfalls encoded as hard rules (`loadFontAsync` no-cache, `findOne` O(N), `appendChild` AutoLayout recomputation, per-call ~5–10s timeout).
+- `reference/mcp-budget.default.json` + `reference/schemas/mcp-budget.schema.json` — defaults: `max_calls_per_task: 30`, `max_consecutive_timeouts: 3`, `reset_on_success: true`, tracked tools `mcp__*use_figma | use_paper | use_pencil`.
+- `agents/design-figma-writer` Step 0.5 **Authoring-Intent Guard** — bilingual EN/RU pattern set classifies invocations as author-intent vs decision-intent. Author-intent STOPs with a redirect to `figma:figma-generate-design` and cites the 4 pitfalls. Decision-intent proceeds. Bumped `size_budget` LARGE → XL.
+- `hooks/gdd-mcp-circuit-breaker.js` — PostToolUse on `mcp__*use_figma | use_paper | use_pencil`. Appends `{ts, tool, outcome, consecutive_timeouts, total_calls}` rows to `.design/telemetry/mcp-budget.jsonl`. Breaks with `{continue:false}` at threshold + appends a STATE.md blocker.
+- README.md + `connections/figma.md` gain the authoring-redirect callout + 4-pitfalls summary.
+
+**Tests** (8 new files, ~60 new assertions):
+- `bash-guard`, `protected-paths`, `blast-radius`, `decision-injector`, `reference-registry`, `meta-rules-split`, `figma-authoring-guard`, `mcp-circuit-breaker` all added. `read-injection-scanner.test.cjs` extended with bidi-override + HTML-comment hijack + secret-exfil + benign-regression cases.
+
+### Changed
+
+- `agents/design-executor.md` — new Preflight Blast-Radius Check + MCP Budget sections.
+- `agents/design-figma-writer.md` — Step 0.5 Authoring-Intent Guard; `size_budget: XL`.
+- `reference/shared-preamble.md` — rewritten as L0 aggregator.
+- `scripts/build-intel.cjs` — registry round-trip on `reference/**` changes.
+- `skills/{progress,resume,reflect,pause}/SKILL.md` — import `reference/retrieval-contract.md` (+ `cycle-handoff-preamble.md` for pause + resume).
+- `hooks/hooks.json` — registers bash-guard, protected-paths, decision-injector, MCP circuit-breaker.
+- Plugin manifests — add `safety-hardening`, `protected-paths`, `decision-injector`, `reference-registry`, `mcp-circuit-breaker` keywords.
+- `tests/semver-compare.test.cjs` — `1.14.6` added to `OFF_CADENCE_VERSIONS`.
+
+### Security
+
+- Bash guard normalizes Unicode (NFKC + strip zero-width + bidi) and ANSI escapes before pattern match — blocks bidi-override obfuscation, zero-width-injected verbs, and ANSI-colored reformulations.
+- Read-injection scanner flags invisible-Unicode sequences, HTML-comment hijacks, and secret-exfil triggers (7 → 22 patterns).
+- Protected-paths enforces a merge-only glob list — user configs cannot reduce the default-protected set.
+
+---
+
 ## [1.14.5] — 2026-04-23
 
 ### Fixed — Preview MCP silently skipped in verify even when available ([#19](https://github.com/hegemonart/get-design-done/issues/19))

package/README.md

@@ -101,6 +101,16 @@ That's it. The installer writes a `get-design-done` marketplace entry and enable
 
 On first Claude Code launch after install, a `SessionStart` bootstrap hook provisions the companion reference library `~/.claude/libs/awesome-design-md` (idempotent — subsequent sessions run `git pull --ff-only`).
 
+### First run — `/gdd:start` *(v1.14.7+)*
+
+```
+/gdd:start
+```
+
+Run this once in any frontend repo. The skill asks five short questions, scans your `components/` directory (with framework-aware fallback for `src/components/`, `app/components/`, `packages/ui/`, `apps/*/components/`), and writes `.design/START-REPORT.md` with three concrete findings — each with file:line evidence — plus one `best_first_proof` and a single suggested next command. Takes ≤5 minutes, never touches source code, and never enters the pipeline state machine.
+
+A one-line SessionStart nudge surfaces `/gdd:start` in fresh repos; run `/gdd:start --dismiss-nudge` to silence it per install.
+
 ### Non-interactive install (CI, Docker, scripts)
 
 ```bash
@@ -489,6 +499,21 @@ See [`connections/magic-patterns.md`](connections/magic-patterns.md) for probe p
 
 ---
 
+## Safety + Recall Floor
+
+Starting with v1.14.6, GDD ships three defense-in-depth hooks, the first cross-cycle recall primitive, and a typed reference index:
+
+- **Bash guard** (`hooks/gdd-bash-guard.js`) — PreToolUse:Bash blocks ~45 dangerous shell patterns after Unicode NFKC + ANSI + zero-width/bidi normalization, so `rm\u200B -rf /`, bidi-override obfuscations, and hex-encoded exec sequences fail closed.
+- **Protected paths** (`hooks/gdd-protected-paths.js`) — PreToolUse:Edit|Write|Bash refuses to mutate `reference/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/archive/**`, `.design/config.json`, `.design/telemetry/**`, `.git/**`, both plugin manifests, and anything the user appends under `.design/config.json.protected_paths` (merge-only — user configs cannot reduce the default set).
+- **Blast-radius preflight** (`scripts/lib/blast-radius.cjs`) — `design-executor` refuses tasks above `.design/config.json.blast_radius.max_files_per_task` (default 10), `max_lines_per_task` (default 400), or `max_mcp_calls_per_task` (default 30); writes a blocker to STATE.md with a diff summary.
+- **Decision-injector** (`hooks/gdd-decision-injector.js`) — PreToolUse:Read on any `.design/**.md | reference/**.md | .planning/**.md` ≥ 1500 bytes surfaces the top-15 matching D-XX decisions, L-NN learnings, and prior-cycle summary excerpts that reference the opened file. Grep backend; Phase 19.5 upgrades to FTS5 transparently.
+
+**Reference index** — `reference/registry.json` (schema: `reference/registry.schema.json`) indexes every `reference/*.md` by typed category (`heuristic | preamble | motion | defaults | meta-rules | …`). Agents can query `list({type: "heuristic"})` instead of grep-hunting import strings. `scripts/build-intel.cjs` enforces round-trip on every `reference/**` change: missing entries, dangling entries, and duplicates fail the build.
+
+**L0/L2 cache-locality split** — the 5 framework-invariant rules (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget Awareness) now live in `reference/meta-rules.md` (tier L0). `reference/shared-preamble.md` becomes an L0 aggregator importing `meta-rules.md` first, so Phase 15+ L2 churn (heuristics, anti-patterns, checklists) no longer invalidates the L0 prompt-cache prefix.
+
+**Figma authoring-redirect** — `/gdd:figma-write` is a decision-writer (annotations, token bindings, Code Connect, implementation-status). For authoring new Figma content (create pages, populate library components, build layouts from scratch), use `figma:figma-generate-design` from the Figma plugin — it runs outside the Figma plugin sandbox. `design-figma-writer` Step 0.5 detects author-intent (EN + RU) and emits a bilingual redirect citing the four sandbox pitfalls in `reference/figma-sandbox.md`. The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) caps `use_figma | use_paper | use_pencil` at 30 calls/task and 3 consecutive timeouts by default (see `reference/mcp-budget.default.json`), logging per-call JSONL at `.design/telemetry/mcp-budget.jsonl`.
+
 ## Commands
 
 All commands use the `/gdd:` namespace.
@@ -510,6 +535,7 @@ All commands use the `/gdd:` namespace.
 
 | Command | What it does |
 |---------|--------------|
+| `/gdd:start [--budget] [--skip-interview] [--dismiss-nudge]` | First-Run Proof Path — scans UI code, emits `.design/START-REPORT.md`, never enters pipeline state |
 | `/gdd:new-project [--name]` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
 | `/gdd:new-cycle [<goal>]` | Start new design cycle |
 | `/gdd:complete-cycle [<note>]` | Archive cycle to `.design/archive/cycle-N/` |
@@ -621,6 +647,8 @@ claude mcp add --transport http figma https://mcp.figma.com/mcp
 
 Setup: [`connections/figma.md`](connections/figma.md). If you previously registered the remote MCP with the legacy URL `https://mcp.figma.com/v1/sse`, remove and re-add with the current URL `https://mcp.figma.com/mcp` (Streamable HTTP).
 
+> ⚠︎ **Authoring new Figma content?** `/gdd:figma-write` is a *decision-writer* (annotations, token bindings, Code Connect). For **creating pages, populating with library components, building doc layouts from scratch**, use `figma:figma-generate-design` from the Figma plugin — it runs outside the plugin sandbox. See [`reference/figma-sandbox.md`](reference/figma-sandbox.md) for the four sandbox pitfalls the MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) protects you from (defaults: 30 calls/task, 3 consecutive timeouts → break).
+
 ### Refero MCP
 
 When Refero is active, `explore` pulls visual references to ground design decisions. Requires an API token in `~/.claude.json`:

package/SKILL.md

@@ -45,6 +45,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `pause [context]` | `get-design-done:gdd-pause` | Write session handoff to `.design/HANDOFF.md` |
 | `resume` | `get-design-done:gdd-resume` | Restore session context from `.design/HANDOFF.md` and route to next step |
 | **Lifecycle** | | |
+| `start [--budget <t>] [--skip-interview] [--dismiss-nudge]` | `get-design-done:start` | First-Run Proof Path — scans UI code, returns one concrete first fix. No STATE.md writes. |
 | `new-project [--name <n>]` | `get-design-done:gdd-new-project` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
 | `new-cycle [<goal>]` | `get-design-done:gdd-new-cycle` | Start a new design cycle; writes `.design/CYCLES.md` entry |
 | `complete-cycle [<note>]` | `get-design-done:gdd-complete-cycle` | Archive cycle artifacts to `.design/archive/cycle-N/`; reset STATE.md |
@@ -205,6 +206,7 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:pause              → Skill("get-design-done:gdd-pause")
 /gdd:resume          → Skill("get-design-done:gdd-resume")
 # --- Lifecycle ---
+/gdd:start           → Skill("get-design-done:start")          # leaf command, no STATE.md
 /gdd:new-project     → Skill("get-design-done:gdd-new-project")
 /gdd:new-cycle       → Skill("get-design-done:gdd-new-cycle")
 /gdd:complete-cycle  → Skill("get-design-done:gdd-complete-cycle")

package/agents/design-executor.md

@@ -39,6 +39,47 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
 
 ---
 
+## Preflight — Blast-Radius Check
+
+Before the FIRST Edit/Write of this task, run a blast-radius preflight:
+
+```js
+const { estimate, formatDiffSummary, loadConfig } = require('scripts/lib/blast-radius.cjs');
+const cfg = loadConfig();
+const result = estimate({
+  touchedPaths: <paths this task declares>,
+  diffStats: { insertions: <estimate>, deletions: <estimate> },
+  config: cfg,
+});
+```
+
+**Ceilings** (defaults; user may override in `.design/config.json.blast_radius`):
+- `max_files_per_task: 10`
+- `max_lines_per_task: 400`
+- `max_mcp_calls_per_task: 30` (see MCP Budget section)
+
+**If `result.exceeds === true`:** STOP. Do NOT Edit/Write. Append `formatDiffSummary({touchedPaths, diffStats, result})` to `.design/STATE.md` under a new blocker line, then emit a structured deviation:
+
+> Rule 3 — Blast-Radius Exceeds: this task would touch `<files>` files / `<lines>` lines, above the per-task ceiling. Proposed split: <suggest 2–3 sub-tasks that each stay under the limit>. User must explicitly approve a single ceiling raise or accept the split.
+
+Proceed only after the user confirms. The preflight is skipped entirely when both ceilings are set to `0` in config.
+
+---
+
+## MCP Budget — Per-Task
+
+Before every `mcp__*use_figma`, `mcp__*use_paper`, `mcp__*use_pencil`, or equivalent mutation-side MCP call, check the rolling counter:
+
+```js
+const { estimateMCPCalls, loadConfig } = require('scripts/lib/blast-radius.cjs');
+const r = estimateMCPCalls({ toolCalls: <calls-issued-so-far>, config: loadConfig() });
+if (r.exceeds) STOP;
+```
+
+The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) enforces the same ceiling at the tool boundary; the preflight here avoids wasting a MCP round-trip before the hook blocks you. Surface in `/gdd:stats` as "MCP calls this task: N/limit".
+
+---
+
 ## Prompt Context Fields
 
 The stage embeds the following fields in the prompt. Use them to locate and execute the correct task:

package/agents/design-figma-writer.md

@@ -6,7 +6,7 @@ color: purple
 model: inherit
 default-tier: sonnet
 tier-rationale: "Writer proposes + executes Figma write-backs — Sonnet handles structured proposal synthesis well"
-size_budget: LARGE
+size_budget: XL
 parallel-safe: never
 typical-duration-seconds: 120
 reads-only: false
@@ -40,6 +40,66 @@ Note: the remote Figma MCP (canonical server name `figma`, URL `https://mcp.figm
 
 ---
 
+## Step 0.5 — Authoring-Intent Guard
+
+BEFORE proceeding to Step 1, analyze the invocation text (prompt + task description + any user-facing message in the agent dispatch) for **authoring-intent**. `design-figma-writer` is a *decision-writer* (annotations, token bindings, Code Connect, implementation-status). When the user wants to *author* new Figma content (create pages, populate with library components, build doc layouts from scratch), the correct tool is `figma:figma-generate-design` from the Figma plugin — it runs outside the sandbox and has no per-call timeout.
+
+Apply the patterns below (case-insensitive, whitespace-tolerant). If ANY author-intent pattern matches AND NO decision-intent pattern dominates the text, STOP with the redirect response and do not proceed to the remote-MCP probe or any `use_figma` call.
+
+**Author-intent patterns (EN):**
+- `create .{0,30}(page|file|frame|layout|doc)`
+- `(populate|fill|build) .{0,40}(with )?(components|library)`
+- `(author|write|generate|produce|build) .{0,30}(doc|documentation|spec|design)`
+- `make .{0,30}(layout|frame|page|template)`
+- `spin up .{0,30}Figma`
+- `design .{0,30}(page|doc|spec|layout) .{0,20}(from|in) (scratch|Figma)`
+
+**Author-intent patterns (RU):**
+- `(создай|сделай|построй|свёрстай|собери|оформи) .{0,30}(страниц|макет|документац|страницу|документ|файл|лейаут|шаблон)`
+- `(новую?|новый) страниц[уыа]`
+- `документац[иия] .{0,40}токен`
+- `сгенерируй .{0,30}Figma`
+
+**Decision-intent patterns (EN) — these WIN over ambiguous author-intent:**
+- `annotate .{0,30}(selection|frame|component)`
+- `bind .{0,30}token`
+- `code connect`
+- `code-connect`
+- `update .{0,30}(status|implementation)`
+- `write .{0,30}D-\d+`
+- `sync .{0,30}(tokens?|variables?)`
+
+**Decision-intent patterns (RU):**
+- `привяжи .{0,30}токен`
+- `аннотируй`
+- `синхронизируй .{0,30}токен`
+
+### Decision rule
+- If decision-intent matches AND author-intent doesn't match, proceed normally.
+- If author-intent matches AND NO decision-intent match, STOP with redirect.
+- If BOTH match (mixed), favor decision-intent (the guard is permissive; the circuit-breaker catches runaway cases downstream).
+- If NEITHER matches, proceed normally (default is decision-writing — the guard doesn't block the common case).
+
+### Redirect response (emit verbatim and STOP)
+
+```
+This task reads as authoring new Figma content. `design-figma-writer` is a decision-writer — it uses `use_figma` inside the Figma plugin sandbox with ~5–10s per-call timeout, so multi-row docs-authoring hill-climbs against the timeout and burns MCP quota.
+
+Use `figma:figma-generate-design` from the Figma plugin instead — it runs outside the sandbox and has no per-call timeout.
+
+Four sandbox pitfalls you would hit here on raw `use_figma` calls:
+1. `loadFontAsync` does not cache across calls — preload once, clone existing nodes.
+2. `figma.root.findOne()` is O(tree-size) — pass node IDs and use `getNodeById`.
+3. `appendChild` on large trees forces full AutoLayout recomputation — build subtrees off-tree.
+4. Per-call timeout is ~5–10s — budget ≤2 row-equivalents per call.
+
+See `reference/figma-sandbox.md`.
+```
+
+After emitting the redirect, STOP with the marker `## FIGMA AUTHORING-INTENT REDIRECT` and do NOT proceed to Step 1.
+
+---
+
 ## Step 1 — Read State and Flags
 
 Read `.design/STATE.md` to confirm `figma: available` in the `<connections>` block. If `figma: not_configured` or `figma: unavailable`, write to output: "Figma connection not configured. Run the scan probe or set figma: available in .design/STATE.md." and STOP.

package/agents/design-start-writer.md

@@ -0,0 +1,221 @@
+---
+name: design-start-writer
+description: "Writes .design/START-REPORT.md — 7 fixed sections plus a machine-readable JSON block. Consumes the findings-engine output, interview answers, and detection result from .design/.start-context.json. Never writes STATE.md. Parameter-free: reads the context JSON path from the prompt and emits the report."
+tools: Read, Write, Grep, Glob
+color: green
+
+model: haiku
+default-tier: haiku
+tier-rationale: "Formatting + light synthesis over a bounded ~3KB input; Haiku is the correct tier per Phase 10.1 D-14 (Haiku = writers/formatters with fixed schemas)."
+
+parallel-safe: always
+typical-duration-seconds: 10
+reads-only: false
+writes:
+  - ".design/START-REPORT.md"
+
+allowed-read-paths:
+  - ".design/.start-context.json"
+  - ".design/START-REPORT.md"
+allowed-write-paths:
+  - ".design/START-REPORT.md"
+---
+
+## Role
+
+Write `.design/START-REPORT.md` for `/gdd:start`. The report is the single artifact the user sees after a first-run scan. It must feel like GDD understood the project, not like it printed a generic checklist. One best_first_proof, one suggested next command, no ambiguity.
+
+---
+
+## Required Reading
+
+- `.design/.start-context.json` — produced by `skills/start/SKILL.md` before spawning this agent. Contains detection result, interview answers, and the findings-engine output.
+
+## Inputs
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": {
+    "kind": "next-app-router | src-components | monorepo-ui-pkg | ...",
+    "path": "relative/path/to/components",
+    "framework": "next | vite | cra | ...",
+    "design_system": "tailwind | css-modules | ...",
+    "confidence": 0.85
+  },
+  "interview": {
+    "pain": "free text or empty",
+    "target_area": "relative/path",
+    "budget": "fast | balanced | thorough",
+    "framework_confirmed": true,
+    "design_system_confirmed": true,
+    "figma_workflow": "figma | canvas | neither | skip"
+  },
+  "scan": {
+    "findings": [{"id":"F1","category":"transition-all","title":"...","file":"...","line":123,"severity":"minor","evidence":"...","visibleDelta":true,"blastRadius":"single-file"}],
+    "bestFirstProofId": "F1",
+    "partial": false,
+    "inspected": {"files": 42, "root": "..."}
+  },
+  "generated_at": "2026-04-24T01:00:00Z"
+}
+```
+
+---
+
+## Output contract
+
+Write `.design/START-REPORT.md` exactly matching this shape. **All seven H2 sections must be present, in this order, even if empty.** The JSON block at the very end is mandatory.
+
+```markdown
+# GDD First-Run Report
+
+> Generated <generated_at> by `/gdd:start`. This report does not start a pipeline cycle — it is a 0→1 proof path. Run the suggested next command to continue.
+
+## What I inspected
+
+- **UI root:** `<detected.path>` (`<detected.kind>`, confidence `<detected.confidence>`)
+- **Framework:** `<detected.framework>` — <one-sentence confirmation or override note>
+- **Design system:** `<detected.design_system>` — <one-sentence note>
+- **Files scanned:** `<scan.inspected.files>`
+- **Pain hint:** <`interview.pain` or "none given">
+- **Budget:** `<interview.budget>` <"(timed out — partial scan)" if `scan.partial`>
+
+## Three findings
+
+<For each finding F1..F3, emit:>
+
+### <Fn> — <title>
+
+**Severity:** `<severity>` · **Evidence:** `<file>:<line>` · **Blast radius:** `<blastRadius>`
+
+<one-sentence plain-English rationale pointing at the evidence line>
+
+**Fix sketch:** <one-sentence concrete fix — e.g., "Replace `transition` with `transition-transform` on the wrapper.">
+
+<End per-finding block>
+
+## Best first proof
+
+**Pick:** `<bestFirstProofId>` — <re-state the finding title>
+
+<one paragraph: why this one. Cite the rubric condition that tipped the pick — single-file, non-ambiguous, visible delta, no token migration, low blast radius. If `bestFirstProofId` is null, write: "No finding qualified for a single-command fix under the safe-fix rubric — the report recommends the pipeline entry point below instead.">
+
+## Suggested next command
+
+```bash
+<exact command — one of:>
+/gdd:fast "<concrete description of the single fix>"
+/gdd:brief
+/gdd:scan
+```
+
+<one-line rationale: why this command and not the others.>
+
+## Visual Proof Readiness
+
+| Surface | Status | Unlock |
+|---------|--------|--------|
+| Preview MCP | <ok \| unconfigured \| unavailable> | <`/gdd:connections preview` or "already configured"> |
+| Storybook | <…> | <…> |
+| Figma | <…> | <`/gdd:connections figma` or "already configured"> |
+| Canvas (.canvas) | <…> | <…> |
+
+<one-line note if `interview.figma_workflow` picked a specific surface — nudge toward that one first.>
+
+## Full pipeline path
+
+If you want more than a single fix, the full pipeline would do this on this project: `/gdd:brief` to capture the design problem, `/gdd:explore` to inventory your components and interview for context, `/gdd:plan` to decompose the work, `/gdd:design` to execute, and `/gdd:verify` to score the result. The pipeline writes `.design/STATE.md` and runs across a real design cycle.
+
+## Connections / writeback optional
+
+If you want to push design decisions back into Figma, paper.design, pencil.dev, or a Claude Design handoff bundle, run `/gdd:connections` to wire up the surfaces. Writeback is never required — the pipeline runs code-first by default.
+
+---
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "<ISO-8601>",
+  "detected": {...copy verbatim from context...},
+  "findings": [...copy findings array with id, title, file, line, severity, category, blast_radius...],
+  "best_first_proof": "<bestFirstProofId or null>",
+  "suggested_command": { "kind": "fast|brief|scan", "text": "<exact command>" },
+  "visual_proof_readiness": { "preview": "...", "storybook": "...", "figma": "...", "canvas": "..." }
+}
+```
+```
+
+---
+
+## Section-by-section rules
+
+### What I inspected
+
+- Always list the six bullets. Mark "(timed out — partial scan)" only when `scan.partial === true`.
+- Never invent fields — only surface what is in the context JSON.
+
+### Three findings
+
+- Emit up to three entries. If fewer than three findings exist, emit what exists and add one italic note below: `> Only <N> finding raised — the engine did not hit its cap.`
+- Every finding block includes the evidence file:line. No finding may omit file:line.
+- Fix sketch is one concrete sentence — not a general principle, not a tutorial.
+
+### Best first proof
+
+- Reference `bestFirstProofId` exactly. If it is null, write the fallback paragraph.
+- Cite which rubric conditions the winning finding satisfies.
+
+### Suggested next command
+
+- If `bestFirstProofId` is non-null → emit `/gdd:fast "<task>"` where `<task>` is a one-line description tied to the finding's fix sketch.
+- If `bestFirstProofId` is null AND there are findings → emit `/gdd:brief` with rationale "the findings need a design decision the rubric cannot make for you."
+- If no findings at all → emit `/gdd:scan` with rationale "this codebase looks healthy at first glance — a full audit confirms."
+
+### Visual Proof Readiness
+
+- Always include all four rows. Unknown surfaces default to `unconfigured`.
+- Check `interview.figma_workflow` — if the user picked `figma`, `canvas`, or `neither`, phrase the unlock line to match.
+
+### Full pipeline path
+
+- Keep the paragraph short — one sentence of what the pipeline does plus the command sequence. Do not rephrase per run.
+
+### Connections / writeback optional
+
+- Keep the paragraph short. Never assert which surface is best; point at `/gdd:connections`.
+
+---
+
+## JSON block
+
+The JSON block at the bottom is the contract future `/gdd:fast` / `/gdd:do` invocations will consume. Shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "ISO-8601",
+  "detected": { "root", "kind", "framework", "design_system", "confidence" },
+  "findings": [{ "id", "title", "file", "line", "severity", "category", "blast_radius" }],
+  "best_first_proof": "F1" | null,
+  "suggested_command": { "kind": "fast" | "brief" | "scan", "text": "/gdd:fast \"...\"" },
+  "visual_proof_readiness": { "preview", "storybook", "figma", "canvas" }
+}
+```
+
+- Finding IDs stay stable `F1`..`F3`.
+- `text` is always a ready-to-run command, single-line.
+- All string values are JSON-safe — escape embedded quotes.
+
+---
+
+## Do Not
+
+- Do not write `.design/STATE.md`, `.design/config.json`, or any source file.
+- Do not invent findings that are not in the context JSON.
+- Do not re-score or re-rank findings — the engine already picked `bestFirstProofId` deterministically.
+- Do not add marketing prose, emojis, or playful copy.
+- Do not emit more than three findings.
+- Do not omit any of the seven H2 sections — even empty, they must exist for downstream regression fixtures.
+
+## START-WRITER COMPLETE

package/connections/figma.md

@@ -63,6 +63,16 @@ No data is lost — the remote MCP reads the same Figma files.
 
 ---
 
+> ⚠︎ **Authoring-redirect** — `/gdd:figma-write` (and the `design-figma-writer` agent behind it) is a *decision-writer*: annotations, token bindings, Code Connect mappings, implementation-status write-back. For **authoring new Figma content** — create pages, populate with library components, build doc layouts from scratch — use `figma:figma-generate-design` from the Figma plugin. It runs outside the plugin sandbox and has no per-call timeout.
+>
+> **Four sandbox pitfalls `use_figma` hits in authoring loops (see `reference/figma-sandbox.md`):**
+> 1. `loadFontAsync` does not cache across calls — preload once, clone existing nodes.
+> 2. `figma.root.findOne()` is O(tree-size) — pass node IDs and use `getNodeById`.
+> 3. `appendChild` on large trees forces full AutoLayout recomputation — build subtrees off-tree.
+> 4. Per-call timeout is ~5–10s — budget ≤2 row-equivalents per call for docs-authoring.
+>
+> The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) enforces a per-task ceiling of 30 calls and 3 consecutive timeouts by default; see `reference/mcp-budget.default.json`.
+
 ## Tools
 
 Tool names take the form `mcp__<prefix>__<tool>` where `<prefix>` is the resolved server name from the probe (commonly `figma` for remote or `figma-desktop` for local). The pipeline discovers the prefix at runtime — see **Availability Probe** below. The `mcp__figma__` examples shown here assume a server registered as `figma`.