@hegemonart/get-design-done 1.14.7 → 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.7"
+    "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.7",
+      "version": "1.14.8",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.14.7",
+  "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",
@@ -52,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,31 @@ 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)

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
@@ -525,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/` |

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-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/hooks/first-run-nudge.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# get-design-done — first-run nudge (Phase 14.7)
+# SessionStart hook. Silent-on-failure by policy: exits 0 on every error path.
+# Prints exactly one restrained line pointing at /gdd:start when all gates pass,
+# and nothing otherwise.
+
+set -u  # intentionally no -e: we want to fall through to exit 0
+
+# Silent logger — writes nothing by default. Set GDD_NUDGE_DEBUG=1 to enable stderr.
+log() {
+  if [ "${GDD_NUDGE_DEBUG:-0}" = "1" ]; then
+    printf '[gdd first-run-nudge] %s\n' "$*" >&2
+  fi
+}
+
+DESIGN_DIR="$(pwd)/.design"
+STATE="${DESIGN_DIR}/STATE.md"
+CONFIG="${DESIGN_DIR}/config.json"
+DISMISS_FLAG="${HOME:-$USERPROFILE}/.claude/gdd-nudge-dismissed"
+
+# Gate 1 — repo already has GDD state, suppress.
+has_design_state() {
+  [ -f "${CONFIG}" ] || [ -f "${STATE}" ]
+}
+
+# Gate 2 — per-install dismissal flag.
+is_dismissed() {
+  [ -f "${DISMISS_FLAG}" ]
+}
+
+# Gate 3 — STATE.md stage belongs to an active pipeline window.
+# Inherits the shape used by Phase 13.3 update-check.sh.
+read_state_stage() {
+  [ -f "${STATE}" ] || { printf ''; return; }
+  grep -E '^stage:' "${STATE}" 2>/dev/null | head -n1 | \
+    sed -E 's/^stage:[[:space:]]*"?([^"[:space:]]+)"?.*/\1/'
+}
+
+is_active_stage() {
+  local s
+  s="$(read_state_stage)"
+  case "${s}" in
+    plan|design|verify|executing|discussing) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Gate 4 — recent session history has a gdd:* command. We cannot reliably read
+# session history from a hook in all runtimes; when the signal is unavailable,
+# treat it as "unknown → not suppressed". This preserves the nudge's
+# usefulness without creating false suppression.
+has_recent_gdd_command() {
+  # Placeholder: no portable transcript path exposed to SessionStart hooks today.
+  # Keep the function for future wiring; for now always returns non-zero (unknown).
+  return 1
+}
+
+# MANDATORY sourcing guard: unit tests source this script to test the helper
+# functions without executing the main flow. Non-negotiable.
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  if has_design_state; then
+    log "design state present — suppress"
+    exit 0
+  fi
+  if is_dismissed; then
+    log "dismissal flag present — suppress"
+    exit 0
+  fi
+  if is_active_stage; then
+    log "active stage — suppress"
+    exit 0
+  fi
+  if has_recent_gdd_command; then
+    log "recent gdd:* command detected — suppress"
+    exit 0
+  fi
+  # All gates passed — emit the locked one-line nudge.
+  printf 'Tip: run /gdd:start to let GDD inspect this codebase and suggest one first fix.\n'
+  exit 0
+fi
+# When sourced (BASH_SOURCE != $0), fall through with function definitions loaded
+# and without side effects.

package/hooks/hooks.json

@@ -16,6 +16,14 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/update-check.sh\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/first-run-nudge.sh\""
+          }
+        ]
       }
     ],
     "PreToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.14.7",
+  "version": "1.14.8",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/registry.json

@@ -29,6 +29,7 @@
     { "name": "model-tiers",             "path": "reference/model-tiers.md",             "type": "data",                           "description": "Per-agent default tier map and rationale" },
     { "name": "figma-sandbox",           "path": "reference/figma-sandbox.md",           "type": "defaults",                       "description": "Four Figma plugin-sandbox pitfalls encoded as hard rules" },
     { "name": "mcp-budget.default",      "path": "reference/mcp-budget.default.json",    "type": "defaults",                       "description": "Default MCP per-task budget (calls + consecutive-timeout thresholds)" },
-    { "name": "protected-paths.default", "path": "reference/protected-paths.default.json","type": "defaults",                       "description": "Default glob list the plugin refuses to Edit/Write/mutate-via-Bash without override" }
+    { "name": "protected-paths.default", "path": "reference/protected-paths.default.json","type": "defaults",                       "description": "Default glob list the plugin refuses to Edit/Write/mutate-via-Bash without override" },
+    { "name": "start-interview",         "path": "reference/start-interview.md",         "type": "preamble",                       "description": "Locked 5-question interview consumed by /gdd:start (Phase 14.7) — pain, target-area, budget, framework/DS confirmation, Figma/canvas workflow" }
   ]
 }

package/reference/start-interview.md

@@ -0,0 +1,84 @@
+# /gdd:start — Locked 5-Question Interview
+
+**Purpose:** collect the minimum signal needed to steer the findings engine without slowing first-run completion past 30 seconds of interview wall-clock. Autodetectable dimensions collapse to a one-key confirmation; genuinely non-derivable dimensions are asked explicitly.
+
+**Hard constraint:** v1.14.7 ships this fixed question set. Do not branch, re-order, or insert new questions without an explicit `/gsd-discuss-phase` override captured in a future DISCUSSION.md.
+
+---
+
+## Q1 — Pain point *(required, free text)*
+
+**Prompt:**
+
+> What's the one design issue you'd most like to see fixed first? One line, ≤120 chars. Examples: "buttons feel jittery on hover", "colors are inconsistent across forms", "mobile nav breaks on the hero", "a11y on our modal".
+
+**Default when `--skip-interview`:** empty string (pain hint disabled; scorer runs without boost).
+
+**Validation:** max 120 chars; trim leading/trailing whitespace. No charset restrictions — the hint is free text.
+
+**Failure posture:** if the user aborts at Q1, abort the whole skill with a one-line pointer to `/gdd:scan`.
+
+---
+
+## Q2 — Target area confirmation *(autodetected, single select)*
+
+**Prompt:**
+
+> I detected your UI code at `<detected.path>` (`<detected.kind>`, confidence=`<detected.confidence>`). Use this surface? [Yes / choose another path / skip demo]
+
+**Default when `--skip-interview`:** accept detected path as-is.
+
+**Validation:** if the user picks "choose another path", ask for a repo-relative path and validate that at least one UI-extension file (.tsx/.jsx/.ts/.js/.svelte/.vue) exists inside. Re-prompt on failure. Two rejections → fall back to detected path with a warning.
+
+**Failure posture:** if the user picks "skip demo", exit clean with `## START COMPLETE` and no `.design/` footprint.
+
+---
+
+## Q3 — Budget / latency preference *(enum, default=balanced)*
+
+**Prompt:**
+
+> Report speed vs thoroughness? [fast (≤90s, tokens-only) / balanced (≤3min, default) / thorough (≤5min, includes a11y + motion checks)]
+
+**Default when `--skip-interview`:** `balanced`.
+
+**Validation:** must be one of `fast | balanced | thorough`. Any other input → re-prompt once, then default to `balanced`.
+
+**Failure posture:** n/a — this is non-blocking; defaulting is safe.
+
+---
+
+## Q4 — Framework + design-system confirmation *(autodetected, combined)*
+
+**Prompt:**
+
+> Detected framework=`<framework>`, design-system=`<design_system>`. Correct? [Yes / override framework / override design-system / skip (use detected)]
+
+**Default when `--skip-interview`:** accept both detected values.
+
+**Validation:** "override framework" → ask for a free-text label (`next | remix | vite | cra | svelte | vue | astro | solid | unknown`). "override design-system" → same, values (`tailwind | css-modules | vanilla-extract | styled | linaria | emotion | panda | unknown`). Invalid → default to `unknown`.
+
+**Failure posture:** n/a — detection output is always available even if the user skips.
+
+---
+
+## Q5 — Figma / canvas workflow *(enum, non-blocking)*
+
+**Prompt:**
+
+> Do you work with visual references? [Figma / .canvas file / neither / skip]
+
+**Default when `--skip-interview`:** `skip`.
+
+**Validation:** enum; any other → `skip`.
+
+**Effect:** result steers the `Visual Proof Readiness` section only — never gates the happy path or the findings engine. The writer uses this to decide whether to surface `/gdd:connections figma` or `.canvas` guidance.
+
+---
+
+## Do Not
+
+- Do not ask for email, org name, team size, or any identity data.
+- Do not ask more than five questions.
+- Do not branch based on Q1 content (adaptive branching is explicitly deferred per the ROADMAP).
+- Do not write STATE.md, config.json, or any source file as a side effect of the interview.

package/scripts/lib/detect-ui-root.cjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+
+// Component-directory detection helper for /gdd:start (Phase 14.7-02).
+// Deterministic, read-only, pure Node — no LLM, no subprocess, no interactive prompts.
+//
+// Contract:
+//   detectUiRoot(cwd) -> { kind, path, confidence, reason } | { kind: "backend-only", path: null, confidence, reason } | null
+//
+// `path` is always relative to cwd and uses forward slashes.
+
+const fs = require('fs');
+const path = require('path');
+
+const UI_EXT = new Set(['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue']);
+const BACKEND_DEPS = ['express', 'fastify', 'koa', '@nestjs/core', 'hapi', 'restify'];
+const UI_DEPS = ['react', 'preact', 'vue', 'svelte', 'solid-js', '@remix-run/react', 'next'];
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function hasUiFiles(absDir) {
+  let stack;
+  try {
+    stack = [absDir];
+  } catch {
+    return false;
+  }
+  // Bounded BFS — stop at 3 levels deep or after 200 entries to keep fast.
+  let checked = 0;
+  let depth = 0;
+  const maxEntries = 200;
+  const maxDepth = 3;
+  while (stack.length && checked < maxEntries && depth < maxDepth) {
+    const next = [];
+    for (const dir of stack) {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const e of entries) {
+        if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+        const full = path.join(dir, e.name);
+        if (e.isFile()) {
+          if (UI_EXT.has(path.extname(e.name))) return true;
+          checked += 1;
+          if (checked >= maxEntries) return false;
+        } else if (e.isDirectory()) {
+          next.push(full);
+        }
+      }
+    }
+    stack = next;
+    depth += 1;
+  }
+  return false;
+}
+
+function firstExistingUiDir(cwd, relPath) {
+  const abs = path.join(cwd, relPath);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return null;
+  if (!hasUiFiles(abs)) return null;
+  return relPath.split(path.sep).join('/');
+}
+
+function firstMonorepoAppsComponents(cwd) {
+  const appsDir = path.join(cwd, 'apps');
+  if (!fs.existsSync(appsDir) || !fs.statSync(appsDir).isDirectory()) return null;
+  let children;
+  try {
+    children = fs.readdirSync(appsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const c of children) {
+    if (!c.isDirectory()) continue;
+    const rel = `apps/${c.name}/components`;
+    const abs = path.join(cwd, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory() && hasUiFiles(abs)) {
+      return rel;
+    }
+  }
+  return null;
+}
+
+function detectFramework(pkg) {
+  if (!pkg) return 'unknown';
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  if (deps.next) return 'next';
+  if (deps['@remix-run/react'] || deps['@remix-run/node']) return 'remix';
+  if (deps['react-scripts']) return 'cra';
+  if (deps.vite) return 'vite';
+  if (deps.svelte || deps['@sveltejs/kit']) return 'svelte';
+  if (deps.vue) return 'vue';
+  if (deps.solid) return 'solid';
+  if (deps.astro) return 'astro';
+  if (deps.react || deps.preact) return 'react';
+  return 'unknown';
+}
+
+function hasAnyDep(pkg, names) {
+  if (!pkg) return false;
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  return names.some((n) => Object.prototype.hasOwnProperty.call(deps, n));
+}
+
+function detectUiRoot(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  const pkg = readJsonSafe(pkgPath);
+
+  // Priority-ordered checks. First match wins.
+  const checks = [
+    { rel: 'packages/ui/src', kind: 'monorepo-ui-pkg', confidence: 0.95 },
+    { rel: null, custom: firstMonorepoAppsComponents, kind: 'monorepo-apps', confidence: 0.9 },
+    { rel: 'app/components', kind: 'next-app-router', confidence: 0.9 },
+    { rel: 'src/app/components', kind: 'next-app-router-src', confidence: 0.85 },
+    { rel: 'src/components', kind: 'src-components', confidence: 0.85 },
+    { rel: 'components', kind: 'root-components', confidence: 0.8 },
+  ];
+
+  for (const c of checks) {
+    const found = c.custom ? c.custom(cwd) : firstExistingUiDir(cwd, c.rel);
+    if (found) {
+      const framework = detectFramework(pkg);
+      return {
+        kind: c.kind,
+        path: found,
+        confidence: c.confidence,
+        reason: `Found UI files at ${found} (framework=${framework}, kind=${c.kind})`,
+        framework,
+      };
+    }
+  }
+
+  // Routes-based detection — Svelte/Remix sometimes colocate inside routes
+  const routesAbs = path.join(cwd, 'src/routes');
+  if (fs.existsSync(routesAbs) && fs.statSync(routesAbs).isDirectory() && hasUiFiles(routesAbs)) {
+    return {
+      kind: 'routes-based',
+      path: 'src/routes',
+      confidence: 0.7,
+      reason: 'Found UI files inline at src/routes — framework colocation pattern',
+      framework: detectFramework(pkg),
+    };
+  }
+
+  // Backend-only path — package.json present with only backend deps and no UI deps
+  if (pkg) {
+    const isBackend = hasAnyDep(pkg, BACKEND_DEPS) && !hasAnyDep(pkg, UI_DEPS);
+    if (isBackend) {
+      return {
+        kind: 'backend-only',
+        path: null,
+        confidence: 0.9,
+        reason: `Backend-only repo detected (deps: ${BACKEND_DEPS.filter((d) =>
+          Object.prototype.hasOwnProperty.call(
+            { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) },
+            d
+          )
+        ).join(', ')}) — frontend-only diagnostic applies`,
+        framework: 'backend',
+      };
+    }
+  }
+
+  return null;
+}
+
+module.exports = detectUiRoot;
+module.exports.detectUiRoot = detectUiRoot;
+
+if (require.main === module) {
+  const cwd = process.argv[2] || process.cwd();
+  const result = detectUiRoot(path.resolve(cwd));
+  if (result == null) {
+    process.stdout.write(JSON.stringify({ kind: null, path: null, confidence: 0, reason: 'No UI directory detected and no backend signal either.' }) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(result) + '\n');
+  }
+}

package/scripts/lib/start-findings-engine.cjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+'use strict';
+
+// Top-3 findings engine for /gdd:start (Phase 14.7-03).
+//
+// Deterministic, read-only, no LLM, no child_process. Reads the detected UI root,
+// runs a bank of regex-based detectors, applies the D-02 safe-fix rubric to pick
+// exactly one `best_first_proof`, and returns the shape {findings, bestFirstProofId, partial}.
+//
+// Budget tiers (wall-clock cap):
+//   fast      -> 90_000 ms
+//   balanced  -> 180_000 ms
+//   thorough  -> 300_000 ms
+
+const fs = require('fs');
+const path = require('path');
+
+const BUDGET_MS = { fast: 90_000, balanced: 180_000, thorough: 300_000 };
+const UI_EXT = new Set(['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue', '.css', '.scss']);
+const MAX_FILES = 400;
+
+function isCommentLine(ln) {
+  const t = ln.trimStart();
+  return t.startsWith('//') || t.startsWith('/*') || t.startsWith('*') || t.startsWith('<!--');
+}
+
+/* --------------------------- detector registry --------------------------- */
+
+// Each detector returns an array of partial findings (without `id`/`blastRadius` assigned).
+// Shape: {category, title, file, line, severity, evidence, visibleDelta, ambiguous, crossFile}
+
+const DETECTORS = [
+  {
+    category: 'transition-all',
+    applies: (ext) => ['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue', '.css', '.scss'].includes(ext),
+    run(file, text) {
+      const out = [];
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        const ln = lines[i];
+        if (isCommentLine(ln)) continue;
+        if (/transition:\s*all|transition-property:\s*all/.test(ln)) {
+          out.push({
+            category: 'transition-all',
+            title: 'CSS `transition: all` applied',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: ln.trim().slice(0, 160),
+            visibleDelta: true,
+            ambiguous: false,
+            crossFile: false,
+          });
+        } else if (/\bclassName\s*=\s*["'`][^"'`]*\btransition\b(?!-|\[)/.test(ln)) {
+          out.push({
+            category: 'transition-all',
+            title: 'Tailwind bare `transition` (implicitly all)',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: ln.trim().slice(0, 160),
+            visibleDelta: true,
+            ambiguous: false,
+            crossFile: false,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    category: 'will-change-all',
+    applies: () => true,
+    run(file, text) {
+      const out = [];
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        if (/will-change:\s*all/.test(lines[i])) {
+          out.push({
+            category: 'will-change-all',
+            title: '`will-change: all` GPU hint',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: lines[i].trim().slice(0, 160),
+            visibleDelta: false,
+            ambiguous: false,
+            crossFile: false,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    category: 'tinted-image-outline',
+    applies: (ext) => ['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue'].includes(ext),
+    run(file, text) {
+      const out = [];
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        if (/<img[^>]*outline-(?:slate|zinc|neutral|gray|stone)-\d+/.test(lines[i])) {
+          out.push({
+            category: 'tinted-image-outline',
+            title: 'Tinted outline on <img>',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: lines[i].trim().slice(0, 160),
+            visibleDelta: true,
+            ambiguous: false,
+            crossFile: false,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    category: 'scale-on-press-drift',
+    applies: (ext) => ['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue', '.css', '.scss'].includes(ext),
+    run(file, text) {
+      const out = [];
+      const lines = text.split('\n');
+      // Canonical is 0.96 per Phase 15 decisions. 0.95 and 0.97 are drift signals.
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        const m = /(?:active:scale-9[57]|scale\(0\.9[57]\))/.exec(lines[i]);
+        if (m) {
+          out.push({
+            category: 'scale-on-press-drift',
+            title: 'Scale-on-press drift from canonical 0.96',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: lines[i].trim().slice(0, 160),
+            visibleDelta: true,
+            ambiguous: false,
+            crossFile: false,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    category: 'same-radius-nested',
+    applies: (ext) => ['.tsx', '.jsx', '.ts', '.js', '.svelte', '.vue'].includes(ext),
+    run(file, text) {
+      const out = [];
+      // Multiline: Tailwind parent rounded-X wrapping a child with the same rounded-X.
+      // Cheap approximation — single-line scan for parent+child pattern on same line.
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i += 1) {
+        if (isCommentLine(lines[i])) continue;
+        const m = /(rounded-[a-z0-9-]+)[^"'`]*["'`][^>]*>\s*<[^>]*\1/.exec(lines[i]);
+        if (m) {
+          out.push({
+            category: 'same-radius-nested',
+            title: 'Same border-radius on nested surfaces',
+            file,
+            line: i + 1,
+            severity: 'minor',
+            evidence: lines[i].trim().slice(0, 160),
+            visibleDelta: true,
+            ambiguous: false,
+            crossFile: false,
+          });
+        }
+      }
+      return out;
+    },
+  },
+  {
+    category: 'missing-reduced-motion-guard',
+    applies: (ext) => ['.tsx', '.jsx', '.ts', '.js'].includes(ext),
+    run(file, text) {
+      if (!/framer-motion/.test(text)) return [];
+      if (/useReducedMotion\s*\(/.test(text)) return [];
+      // One finding per file (not per line) — this is a file-level omission.
+      const lineIdx = text.split('\n').findIndex((ln) => /framer-motion/.test(ln));
+      return [
+        {
+          category: 'missing-reduced-motion-guard',
+          title: 'framer-motion imported without `useReducedMotion()` guard',
+          file,
+          line: Math.max(1, lineIdx + 1),
+          severity: 'minor',
+          evidence: 'framer-motion imported; no `useReducedMotion()` reference in file',
+          visibleDelta: false,
+          ambiguous: false,
+          crossFile: true,
+        },
+      ];
+    },
+  },
+  {
+    category: 'non-root-font-smoothing',
+    applies: (ext) => ['.css', '.scss'].includes(ext),
+    run(file, text) {
+      const out = [];
+      const lines = text.split('\n');
+      // Find `-webkit-font-smoothing:` inside a block that isn't html/body/:root
+      let currentSelector = '';
+      for (let i = 0; i < lines.length; i += 1) {
+        const open = /^([^{]+?)\s*\{/.exec(lines[i]);
+        if (open) currentSelector = open[1].trim();
+        if (/-webkit-font-smoothing:/.test(lines[i])) {
+          if (!/^(?:html|body|:root)\b/.test(currentSelector)) {
+            out.push({
+              category: 'non-root-font-smoothing',
+              title: '`-webkit-font-smoothing` set outside html/body/:root',
+              file,
+              line: i + 1,
+              severity: 'minor',
+              evidence: lines[i].trim().slice(0, 160),
+              visibleDelta: false,
+              ambiguous: false,
+              crossFile: false,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+];
+
+/* --------------------------- scoring rubric ---------------------------- */
+
+// Phase 14.7 D-02 — a finding qualifies for /gdd:fast if all five hold.
+function qualifiesAsSafeFix(f) {
+  // 1. single file
+  const singleFile = !f.crossFile;
+  // 2. ≤2 affected selectors (proxy: not a cross-file finding + non-ambiguous)
+  const selectorsOk = true; // engine emits ≤2 lines per file per detector by design
+  // 3. no shared-token migration — approximated by the category allowlist below
+  const TOKEN_SAFE_CATEGORIES = new Set([
+    'transition-all',
+    'will-change-all',
+    'tinted-image-outline',
+    'scale-on-press-drift',
+    'same-radius-nested',
+    'non-root-font-smoothing',
+  ]);
+  const tokenOk = TOKEN_SAFE_CATEGORIES.has(f.category);
+  // 4. not ambiguous
+  const unambiguous = !f.ambiguous;
+  // 5. likely visible delta
+  const visible = !!f.visibleDelta;
+  return singleFile && selectorsOk && tokenOk && unambiguous && visible;
+}
+
+function scoreFinding(f, painHint) {
+  const sevWeight = { major: 1.0, minor: 0.7, info: 0.4 }[f.severity] || 0.5;
+  const visibility = f.visibleDelta ? 1.0 : 0.5;
+  const blast = f.crossFile ? 0.6 : 1.0; // more blast => lower score
+  let score = sevWeight * visibility * blast;
+  if (painHint && matchesPainHint(f, painHint)) score *= 1.2;
+  return score;
+}
+
+function matchesPainHint(f, hint) {
+  const h = String(hint).toLowerCase();
+  const map = {
+    motion: ['transition-all', 'scale-on-press-drift', 'missing-reduced-motion-guard', 'will-change-all'],
+    animation: ['transition-all', 'scale-on-press-drift', 'missing-reduced-motion-guard', 'will-change-all'],
+    a11y: ['missing-reduced-motion-guard'],
+    accessibility: ['missing-reduced-motion-guard'],
+    color: ['tinted-image-outline'],
+    radius: ['same-radius-nested'],
+    corners: ['same-radius-nested'],
+    typography: ['non-root-font-smoothing'],
+    font: ['non-root-font-smoothing'],
+  };
+  for (const key of Object.keys(map)) {
+    if (h.includes(key) && map[key].includes(f.category)) return true;
+  }
+  return false;
+}
+
+function pickBestFirstProof(findings, painHint) {
+  const candidates = findings.filter(qualifiesAsSafeFix);
+  if (candidates.length === 0) return null;
+  const ranked = [...candidates].sort((a, b) => {
+    const sb = scoreFinding(b, painHint);
+    const sa = scoreFinding(a, painHint);
+    if (sb !== sa) return sb - sa;
+    // tiebreak by file length, then alphabetical
+    if (a.file.length !== b.file.length) return a.file.length - b.file.length;
+    return a.file.localeCompare(b.file);
+  });
+  return ranked[0].id;
+}
+
+/* --------------------------- file walker --------------------------- */
+
+function walkUiFiles(root, maxFiles, deadline) {
+  const result = [];
+  const stack = [root];
+  while (stack.length && result.length < maxFiles) {
+    if (Date.now() > deadline) return { files: result, partial: true };
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile() && UI_EXT.has(path.extname(e.name))) {
+        result.push(full);
+        if (result.length >= maxFiles) break;
+      }
+    }
+  }
+  return { files: result, partial: false };
+}
+
+/* --------------------------- public scan() --------------------------- */
+
+function scan({ root, budget = 'balanced', painHint = '', rootCwd }) {
+  if (!root) return { findings: [], bestFirstProofId: null, partial: false };
+  const budgetMs = BUDGET_MS[budget] || BUDGET_MS.balanced;
+  const deadline = Date.now() + budgetMs;
+  const absRoot = path.isAbsolute(root) ? root : path.resolve(rootCwd || process.cwd(), root);
+  const { files, partial: walkPartial } = walkUiFiles(absRoot, MAX_FILES, deadline);
+
+  const raw = [];
+  let timedOut = walkPartial;
+  for (const f of files) {
+    if (Date.now() > deadline) {
+      timedOut = true;
+      break;
+    }
+    let text;
+    try {
+      text = fs.readFileSync(f, 'utf8');
+    } catch {
+      continue;
+    }
+    const ext = path.extname(f);
+    const rel = path.relative(rootCwd || process.cwd(), f).split(path.sep).join('/');
+    for (const det of DETECTORS) {
+      if (!det.applies(ext)) continue;
+      raw.push(...det.run(rel, text));
+    }
+  }
+
+  // Assign stable IDs after sorting by category+file+line for determinism.
+  raw.sort((a, b) => {
+    if (a.category !== b.category) return a.category.localeCompare(b.category);
+    if (a.file !== b.file) return a.file.localeCompare(b.file);
+    return a.line - b.line;
+  });
+
+  // Cap raw at 10 for upstream consumers; pick top 3 for the report.
+  const capped = raw.slice(0, 10).map((f, i) => ({ ...f, id: `R${i + 1}`, blastRadius: f.crossFile ? 'cross-file' : 'single-file' }));
+  const topThree = rankTopThree(capped, painHint).map((f, i) => ({ ...f, id: `F${i + 1}` }));
+  const bestFirstProofId = pickBestFirstProof(topThree, painHint);
+
+  return {
+    findings: topThree,
+    bestFirstProofId,
+    partial: timedOut,
+    inspected: { files: files.length, root: absRoot },
+  };
+}
+
+function rankTopThree(findings, painHint) {
+  const sorted = [...findings].sort((a, b) => {
+    const sb = scoreFinding(b, painHint);
+    const sa = scoreFinding(a, painHint);
+    if (sb !== sa) return sb - sa;
+    if (a.file !== b.file) return a.file.localeCompare(b.file);
+    return a.line - b.line;
+  });
+  return sorted.slice(0, 3);
+}
+
+module.exports = { scan, qualifiesAsSafeFix, pickBestFirstProof };
+
+/* --------------------------- CLI --------------------------- */
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const opts = { root: null, budget: 'balanced', painHint: '' };
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '--root') opts.root = args[++i];
+    else if (a === '--budget') opts.budget = args[++i];
+    else if (a === '--pain') opts.painHint = args[++i];
+  }
+  if (!opts.root) {
+    process.stderr.write('usage: start-findings-engine --root <path> [--budget fast|balanced|thorough] [--pain "<hint>"]\n');
+    process.exit(2);
+  }
+  const result = scan({ ...opts, rootCwd: process.cwd() });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/skills/start/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: start
+description: "First-Run Proof Path — one command that scans your UI code and returns one concrete first fix. Leaf command, no STATE.md writes, no pipeline entry. Writes .design/START-REPORT.md and exits."
+argument-hint: "[--budget <fast|balanced|thorough>] [--skip-interview] [--dismiss-nudge]"
+tools: Read, Grep, Glob, Bash, Write, Task
+---
+
+# Get Design Done — /gdd:start
+
+**Role:** the canonical 0→1 proof path. A new user runs `/gdd:start`, answers five short questions, and receives `.design/START-REPORT.md` with three concrete findings in the user's own code, one `best_first_proof` selected by a deterministic rubric, and a single next command to run.
+
+**Non-goals** (do not do any of these):
+
+- Do NOT write or mutate `.design/STATE.md`.
+- Do NOT enter the pipeline state machine.
+- Do NOT modify source code.
+- Do NOT auto-install MCPs or run `/gdd:connections`.
+- Do NOT capture before/after screenshots — that belongs to the full pipeline.
+
+---
+
+## When to use
+
+- First time opening a repo with the get-design-done plugin installed.
+- The user wants a single proof-of-value pass without committing to the pipeline.
+
+## When NOT to use
+
+- `.design/STATE.md` already exists — route to `/gdd:progress` instead.
+- User asked for a full audit — route to `/gdd:scan`.
+- User asked to fix a specific file — route to `/gdd:fast`.
+
+---
+
+## Arguments
+
+| Flag | Effect |
+|------|--------|
+| `--budget fast` | 90-second wall-clock cap on the findings scan. Skips thorough detectors. |
+| `--budget balanced` *(default)* | 3-minute wall-clock cap. All detectors, bounded file walk. |
+| `--budget thorough` | 5-minute wall-clock cap. Used only when the user opts in. |
+| `--skip-interview` | Skip the 5-question interview; use sane defaults (pain=unspecified, area=detected, budget=balanced, framework=detected, figma=skip). |
+| `--dismiss-nudge` | Touch `~/.claude/gdd-nudge-dismissed` and exit. Does not run the scan. |
+
+---
+
+## Step 0 — Dismiss-only shortcut
+
+If invoked with `--dismiss-nudge`:
+
+1. `touch ~/.claude/gdd-nudge-dismissed` (Windows: equivalent). Ignore errors silently.
+2. Print exactly: `Nudge dismissed. Delete ~/.claude/gdd-nudge-dismissed to re-enable.`
+3. Exit with `## START COMPLETE` marker.
+
+Do not proceed to any other step.
+
+---
+
+## Step 1 — Detect UI root
+
+Run the detector:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-ui-root.cjs" "$(pwd)"
+```
+
+Capture the JSON output. Branches:
+
+- `kind: "backend-only"` → print the frontend-only diagnostic below, write nothing, exit with `## START COMPLETE`. The diagnostic copy is:
+  > `/gdd:start` is for frontend codebases. This repo looks backend-only (detected `<framework>`). The plugin can still help with design references and component libraries imported by your clients — but there is no UI surface here to scan. Exiting without creating `.design/`.
+- `kind: null` (no package.json, no UI dir) → print a short "Nothing recognizable here — point me at a frontend repo and try again." and exit.
+- Any other `kind` → proceed with `detected.path` as the scan root.
+
+---
+
+## Step 2 — Run the 5-question interview
+
+Read `reference/start-interview.md` for the exact question copy, defaults, and validation rules.
+
+If `--skip-interview`, skip this step and use the defaults documented in that file.
+
+Otherwise, ask the five questions in order using `AskUserQuestion`:
+
+1. Pain point (text, required, single-line cap 120 chars)
+2. Target area confirmation (detected path)
+3. Budget / latency preference (enum: fast / balanced / thorough)
+4. Framework + design-system confirmation (from detection)
+5. Figma / canvas workflow (enum: figma / canvas / neither / skip)
+
+Any early exit at Q1 → abort with a one-line pointer to `/gdd:scan`.
+
+Store the answers + detection result in `.design/.start-context.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": { "kind": "...", "path": "...", "framework": "...", "design_system": "...", "confidence": 0.85 },
+  "interview": { "pain": "...", "target_area": "...", "budget": "balanced", "framework_confirmed": true, "design_system_confirmed": true, "figma_workflow": "skip" },
+  "generated_at": "<ISO-8601>"
+}
+```
+
+`.design/` is created here for the first time. `.design/STATE.md` is NOT written.
+
+---
+
+## Step 3 — Scan findings
+
+Run the findings engine:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/start-findings-engine.cjs" \
+  --root "<detected.path>" \
+  --budget "<budget>" \
+  --pain "<pain_point>"
+```
+
+Capture the JSON. The output carries at most three findings, each with stable IDs `F1`..`F3`, plus `bestFirstProofId` (may be null).
+
+Append the engine output to `.design/.start-context.json` under a `scan` key.
+
+---
+
+## Step 4 — Spawn the writer
+
+Dispatch `Task` with:
+
+- `subagent_type: design-start-writer`
+- `description: "Write .design/START-REPORT.md"`
+- `prompt:` a short instruction pointing the agent at `.design/.start-context.json` and asking it to emit the report per its Output contract. Include a reminder that it must produce exactly 7 H2 sections plus the JSON block, and must not write `STATE.md`.
+
+Wait for the agent to complete. The agent writes `.design/START-REPORT.md`.
+
+---
+
+## Step 5 — Print the handoff
+
+Read the final line of `.design/START-REPORT.md` to capture the suggested command.
+
+Print exactly (one line, no emoji):
+
+```
+Report written to .design/START-REPORT.md. Next: run <suggested_command> to see the first proof.
+```
+
+If `bestFirstProofId` was null, the suggested command is `/gdd:brief` (the default fallback).
+
+Emit `## START COMPLETE` and exit.
+
+---
+
+## Failure handling
+
+Every error path exits with `## START COMPLETE` and a one-line pointer. Do not half-write files: if the writer agent fails, keep `.design/.start-context.json` and tell the user they can rerun. Do not delete `.design/` unless it was empty before the run.
+
+---
+
+## Do Not
+
+- Do not write or mutate `.design/STATE.md`.
+- Do not modify source code.
+- Do not auto-install MCPs or write to `.design/config.json`.
+- Do not take more than the budgeted wall-clock — let the engine truncate findings rather than hang.
+- Do not invent findings — the findings engine output is the sole source of truth.
+
+## START COMPLETE