get-shit-done-cc 1.38.0 → 1.38.2

package/README.md

@@ -624,6 +624,7 @@ You're never locked in. The system adapts.
 | Command | What it does |
 |---------|--------------|
 | `/gsd-map-codebase [area]` | Analyze existing codebase before new-project |
+| `/gsd-ingest-docs [dir]` | Scan a repo of mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full `.planning/` setup in one pass — parallel classification, synthesis with precedence rules, and a three-bucket conflicts report |
 
 ### Phase Management
 

package/bin/install.js

@@ -10,6 +10,8 @@ const crypto = require('crypto');
 const cyan = '\x1b[36m';
 const green = '\x1b[32m';
 const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const bold = '\x1b[1m';
 const dim = '\x1b[2m';
 const reset = '\x1b[0m';
 
@@ -5825,6 +5827,7 @@ function install(isGlobal, runtime = 'claude') {
             let content = fs.readFileSync(srcFile, 'utf8');
             content = content.replace(/'\.claude'/g, configDirReplacement);
             content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
+            content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
             if (isQwen) {
               content = content.replace(/CLAUDE\.md/g, 'QWEN.md');
               content = content.replace(/\bClaude Code\b/g, 'Qwen Code');
@@ -5950,6 +5953,7 @@ function install(isGlobal, runtime = 'claude') {
           let content = fs.readFileSync(srcFile, 'utf8');
           content = content.replace(/'\.claude'/g, configDirReplacement);
           content = content.replace(/\/\.claude\//g, `/${getDirName(runtime)}/`);
+          content = content.replace(/\.claude\//g, `${getDirName(runtime)}/`);
           content = content.replace(/\{\{GSD_VERSION\}\}/g, pkg.version);
           fs.writeFileSync(destFile, content);
           try { fs.chmodSync(destFile, 0o755); } catch (e) { /* Windows */ }
@@ -6643,8 +6647,94 @@ function promptLocation(runtimes) {
  * every /gsd-* command that depends on newer query handlers.
  *
  * Skip if --no-sdk. Skip if already on PATH (unless --sdk was explicit).
- * Failures are warnings, not fatal.
+ * Failures are FATAL — we exit non-zero so install does not complete with a
+ * silently broken SDK (issue #2439). Set GSD_ALLOW_OFF_PATH=1 to downgrade the
+ * post-install PATH verification to a warning (exit code 2) for users with an
+ * intentionally restricted PATH who will wire things up manually.
  */
+
+/**
+ * Resolve `gsd-sdk` on PATH. Uses `command -v` via `sh -c` on POSIX (portable
+ * across sh/bash/zsh) and `where` on Windows. Returns trimmed path or null.
+ */
+function resolveGsdSdk() {
+  const { spawnSync } = require('child_process');
+  if (process.platform === 'win32') {
+    const r = spawnSync('where', ['gsd-sdk'], { encoding: 'utf-8' });
+    if (r.status === 0 && r.stdout && r.stdout.trim()) {
+      return r.stdout.trim().split('\n')[0].trim();
+    }
+    return null;
+  }
+  const r = spawnSync('sh', ['-c', 'command -v gsd-sdk'], { encoding: 'utf-8' });
+  if (r.status === 0 && r.stdout && r.stdout.trim()) {
+    return r.stdout.trim();
+  }
+  return null;
+}
+
+/**
+ * Best-effort detection of the user's shell rc file for PATH remediation hints.
+ */
+function detectShellRc() {
+  const path = require('path');
+  const shell = process.env.SHELL || '';
+  const home = process.env.HOME || '~';
+  if (/\/zsh$/.test(shell)) return { shell: 'zsh', rc: path.join(home, '.zshrc') };
+  if (/\/bash$/.test(shell)) return { shell: 'bash', rc: path.join(home, '.bashrc') };
+  if (/\/fish$/.test(shell)) return { shell: 'fish', rc: path.join(home, '.config', 'fish', 'config.fish') };
+  return { shell: 'sh', rc: path.join(home, '.profile') };
+}
+
+/**
+ * Emit a red fatal banner and exit. Prints actionable PATH remediation when
+ * the global install succeeded but the bin dir is not on PATH.
+ *
+ * If exitCode is 2, this is the "off-PATH" case and GSD_ALLOW_OFF_PATH respect
+ * is applied by the caller; we only print.
+ */
+function emitSdkFatal(reason, { globalBin, exitCode }) {
+  const { shell, rc } = detectShellRc();
+  const bar = '━'.repeat(72);
+  const redBold = `${red}${bold}`;
+
+  console.error('');
+  console.error(`${redBold}${bar}${reset}`);
+  console.error(`${redBold}  ✗ GSD SDK install failed — /gsd-* commands will not work${reset}`);
+  console.error(`${redBold}${bar}${reset}`);
+  console.error(`  ${red}Reason:${reset} ${reason}`);
+
+  if (globalBin) {
+    console.error('');
+    console.error(`  ${yellow}gsd-sdk was installed to:${reset}`);
+    console.error(`    ${cyan}${globalBin}${reset}`);
+    console.error('');
+    console.error(`  ${yellow}Your shell's PATH does not include this directory.${reset}`);
+    console.error(`  Add it by running:`);
+    if (shell === 'fish') {
+      console.error(`    ${cyan}fish_add_path "${globalBin}"${reset}`);
+      console.error(`    (or append to ${rc})`);
+    } else {
+      console.error(`    ${cyan}echo 'export PATH="${globalBin}:$PATH"' >> ${rc}${reset}`);
+      console.error(`    ${cyan}source ${rc}${reset}`);
+    }
+    console.error('');
+    console.error(`  Then verify: ${cyan}command -v gsd-sdk${reset}`);
+    if (exitCode === 2) {
+      console.error('');
+      console.error(`  ${dim}(GSD_ALLOW_OFF_PATH=1 set → exit ${exitCode} instead of hard failure)${reset}`);
+    }
+  } else {
+    console.error('');
+    console.error(`  Build manually to retry:`);
+    console.error(`    ${cyan}cd <install-dir>/sdk && npm install && npm run build && npm install -g .${reset}`);
+  }
+
+  console.error(`${redBold}${bar}${reset}`);
+  console.error('');
+  process.exit(exitCode);
+}
+
 function installSdkIfNeeded() {
   if (hasNoSdk) {
     console.log(`\n  ${dim}Skipping GSD SDK install (--no-sdk)${reset}`);
@@ -6656,9 +6746,9 @@ function installSdkIfNeeded() {
   const fs = require('fs');
 
   if (!hasSdk) {
-    const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['gsd-sdk'], { stdio: 'ignore' });
-    if (probe.status === 0) {
-      console.log(`  ${green}✓${reset} GSD SDK already installed (gsd-sdk on PATH)`);
+    const resolved = resolveGsdSdk();
+    if (resolved) {
+      console.log(`  ${green}✓${reset} GSD SDK already installed (gsd-sdk on PATH at ${resolved})`);
       return;
     }
   }
@@ -6671,17 +6761,8 @@ function installSdkIfNeeded() {
   const sdkDir = path.resolve(__dirname, '..', 'sdk');
   const sdkPackageJson = path.join(sdkDir, 'package.json');
 
-  const warnManual = (reason) => {
-    console.warn(`  ${yellow}⚠${reset}  ${reason}`);
-    console.warn(`     Build manually from the repo sdk/ directory:`);
-    console.warn(`       ${cyan}cd ${sdkDir} && npm install && npm run build && npm install -g .${reset}`);
-    console.warn(`     Then restart your shell so the updated PATH is picked up.`);
-    console.warn(`     Without it, /gsd-* commands will fail with "command not found: gsd-sdk".`);
-  };
-
   if (!fs.existsSync(sdkPackageJson)) {
-    warnManual(`SDK source tree not found at ${sdkDir}.`);
-    return;
+    emitSdkFatal(`SDK source tree not found at ${sdkDir}.`, { globalBin: null, exitCode: 1 });
   }
 
   console.log(`\n  ${cyan}Building GSD SDK from source (${sdkDir})…${reset}`);
@@ -6690,36 +6771,43 @@ function installSdkIfNeeded() {
   // 1. Install sdk build-time dependencies (tsc, etc.)
   const installResult = spawnSync(npmCmd, ['install'], { cwd: sdkDir, stdio: 'inherit' });
   if (installResult.status !== 0) {
-    warnManual('Failed to `npm install` in sdk/.');
-    return;
+    emitSdkFatal('Failed to `npm install` in sdk/.', { globalBin: null, exitCode: 1 });
   }
 
   // 2. Compile TypeScript → sdk/dist/
   const buildResult = spawnSync(npmCmd, ['run', 'build'], { cwd: sdkDir, stdio: 'inherit' });
   if (buildResult.status !== 0) {
-    warnManual('Failed to `npm run build` in sdk/.');
-    return;
+    emitSdkFatal('Failed to `npm run build` in sdk/.', { globalBin: null, exitCode: 1 });
   }
 
   // 3. Install the built package globally so `gsd-sdk` lands on PATH.
   const globalResult = spawnSync(npmCmd, ['install', '-g', '.'], { cwd: sdkDir, stdio: 'inherit' });
   if (globalResult.status !== 0) {
-    warnManual('Failed to `npm install -g .` from sdk/.');
-    return;
+    emitSdkFatal('Failed to `npm install -g .` from sdk/.', { globalBin: null, exitCode: 1 });
   }
 
-  // Verify gsd-sdk is actually resolvable on PATH. npm's global bin dir is
-  // not always on the current shell's PATH (Homebrew prefixes, nvm setups,
-  // unconfigured npm prefix), so a zero exit status from `npm install -g`
-  // alone is not proof of a working binary.
-  const resolverCmd = process.platform === 'win32' ? 'where' : 'which';
-  const verify = spawnSync(resolverCmd, ['gsd-sdk'], { encoding: 'utf-8' });
-  if (verify.status === 0 && verify.stdout && verify.stdout.trim()) {
-    console.log(`  ${green}✓${reset} Built and installed GSD SDK from source (gsd-sdk resolved at ${verify.stdout.trim().split('\n')[0]})`);
-  } else {
-    warnManual('Built and installed GSD SDK from source but gsd-sdk is not on PATH — npm global bin may not be in your PATH.');
-    if (verify.stderr) console.warn(`     resolver stderr: ${verify.stderr.trim()}`);
+  // 4. Verify gsd-sdk is actually resolvable on PATH. npm's global bin dir is
+  //    not always on the current shell's PATH (Homebrew prefixes, nvm setups,
+  //    unconfigured npm prefix), so a zero exit status from `npm install -g`
+  //    alone is not proof of a working binary (issue #2439 root cause).
+  const resolved = resolveGsdSdk();
+  if (resolved) {
+    console.log(`  ${green}✓${reset} Built and installed GSD SDK from source (gsd-sdk resolved at ${resolved})`);
+    return;
   }
+
+  // Off-PATH: resolve npm global bin dir for actionable remediation.
+  const prefixResult = spawnSync(npmCmd, ['config', 'get', 'prefix'], { encoding: 'utf-8' });
+  const prefix = prefixResult.status === 0 ? (prefixResult.stdout || '').trim() : null;
+  const globalBin = prefix
+    ? (process.platform === 'win32' ? prefix : path.join(prefix, 'bin'))
+    : null;
+
+  const allowOffPath = process.env.GSD_ALLOW_OFF_PATH === '1';
+  emitSdkFatal(
+    'Built and installed GSD SDK, but `gsd-sdk` is not on your PATH.',
+    { globalBin, exitCode: allowOffPath ? 2 : 1 },
+  );
 }
 
 /**

package/commands/gsd/set-profile.md

@@ -9,4 +9,4 @@ allowed-tools:
 
 Show the following output to the user verbatim, with no extra commentary:
 
-!`gsd-sdk query config-set-model-profile $ARGUMENTS --raw`
+!`if ! command -v gsd-sdk >/dev/null 2>&1; then printf '⚠ gsd-sdk not found in PATH — /gsd-set-profile requires it.\n\nInstall the GSD SDK:\n  npm install -g @gsd-build/sdk\n\nOr update GSD to get the latest packages:\n  /gsd-update\n'; exit 1; fi; gsd-sdk query config-set-model-profile $ARGUMENTS --raw`

package/commands/gsd/sketch.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:sketch
-description: Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration
-argument-hint: "<design idea to explore> [--quick]"
+description: Sketch UI/design ideas with throwaway HTML mockups, or propose what to sketch next (frontier mode)
+argument-hint: "[design idea to explore] [--quick] [--text] or [frontier]"
 allowed-tools:
   - Read
   - Write
@@ -10,11 +10,20 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 <objective>
 Explore design directions through throwaway HTML mockups before committing to implementation.
 Each sketch produces 2-3 variants for comparison. Sketches live in `.planning/sketches/` and
-integrate with GSD commit patterns, state tracking, and handoff workflows.
+integrate with GSD commit patterns, state tracking, and handoff workflows. Loads spike
+findings to ground mockups in real data shapes and validated interaction patterns.
+
+Two modes:
+- **Idea mode** (default) — describe a design idea to sketch
+- **Frontier mode** (no argument or "frontier") — analyzes existing sketch landscape and proposes consistency and frontier sketches
 
 Does not require `/gsd-new-project` — auto-creates `.planning/sketches/` if needed.
 </objective>
@@ -41,5 +50,5 @@ Design idea: $ARGUMENTS
 
 <process>
 Execute the sketch workflow from @~/.claude/get-shit-done/workflows/sketch.md end-to-end.
-Preserve all workflow gates (intake, decomposition, variant evaluation, MANIFEST updates, commit patterns).
+Preserve all workflow gates (intake, decomposition, target stack research, variant evaluation, MANIFEST updates, commit patterns).
 </process>

package/commands/gsd/spike.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:spike
-description: Rapidly spike an idea with throwaway experiments to validate feasibility before planning
-argument-hint: "<idea to validate> [--quick]"
+description: Spike an idea through experiential exploration, or propose what to spike next (frontier mode)
+argument-hint: "[idea to validate] [--quick] [--text] or [frontier]"
 allowed-tools:
   - Read
   - Write
@@ -10,11 +10,20 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 <objective>
-Rapid feasibility validation through focused, throwaway experiments. Each spike answers one
-specific question with observable evidence. Spikes live in `.planning/spikes/` and integrate
-with GSD commit patterns, state tracking, and handoff workflows.
+Spike an idea through experiential exploration — build focused experiments to feel the pieces
+of a future app, validate feasibility, and produce verified knowledge for the real build.
+Spikes live in `.planning/spikes/` and integrate with GSD commit patterns, state tracking,
+and handoff workflows.
+
+Two modes:
+- **Idea mode** (default) — describe an idea to spike
+- **Frontier mode** (no argument or "frontier") — analyzes existing spike landscape and proposes integration and frontier spikes
 
 Does not require `/gsd-new-project` — auto-creates `.planning/spikes/` if needed.
 </objective>
@@ -33,9 +42,10 @@ Idea: $ARGUMENTS
 
 **Available flags:**
 - `--quick` — Skip decomposition/alignment, jump straight to building. Use when you already know what to spike.
+- `--text` — Use plain-text numbered lists instead of AskUserQuestion (for non-Claude runtimes).
 </context>
 
 <process>
 Execute the spike workflow from @~/.claude/get-shit-done/workflows/spike.md end-to-end.
-Preserve all workflow gates (decomposition, risk ordering, verification, MANIFEST updates, commit patterns).
+Preserve all workflow gates (prior spike check, decomposition, research, risk ordering, observability assessment, verification, MANIFEST updates, commit patterns).
 </process>

package/get-shit-done/workflows/ingest-docs.md

@@ -50,7 +50,7 @@ If `PATH_NOT_FOUND` or `MANIFEST_NOT_FOUND`: display error and exit.
 Run the init query:
 
 ```bash
-INIT=$(gsd-sdk query init.ingest-docs 2>/dev/null || gsd-sdk query init.default)
+INIT=$(gsd-sdk query init.ingest-docs)
 ```
 
 Parse `project_exists`, `planning_exists`, `has_git`, `project_path` from INIT.

package/get-shit-done/workflows/sketch-wrap-up.md

@@ -255,15 +255,16 @@ The sketch-findings skill will auto-load when building the UI.
 
 ## ▶ Next Up
 
-**Start building** — implement the validated design
+**Explore frontier sketches** — see what else is worth sketching based on what we've explored
 
-`/gsd-plan-phase`
+`/gsd-sketch` (run with no argument — its frontier mode analyzes the sketch landscape and proposes consistency and frontier sketches)
 
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
+- `/gsd-plan-phase` — start building the real UI
 - `/gsd-ui-phase` — generate a UI design contract for a frontend phase
-- `/gsd-sketch` — sketch additional design areas
+- `/gsd-sketch [idea]` — sketch a specific new design area
 - `/gsd-explore` — continue exploring
 
 ───────────────────────────────────────────────────────────────
@@ -279,5 +280,6 @@ The sketch-findings skill will auto-load when building the UI.
 - [ ] Reference files contain design decisions, CSS patterns, HTML structures, anti-patterns
 - [ ] `.planning/sketches/WRAP-UP-SUMMARY.md` written for project history
 - [ ] Project CLAUDE.md has auto-load routing line
-- [ ] Summary presented with next-step routing
+- [ ] Summary presented
+- [ ] Next-step options presented (including frontier sketch exploration via `/gsd-sketch`)
 </success_criteria>

package/get-shit-done/workflows/sketch.md

@@ -2,6 +2,10 @@
 Explore design directions through throwaway HTML mockups before committing to implementation.
 Each sketch produces 2-3 variants for comparison. Saves artifacts to `.planning/sketches/`.
 Companion to `/gsd-sketch-wrap-up`.
+
+Supports two modes:
+- **Idea mode** (default) — user describes a design idea to sketch
+- **Frontier mode** — no argument or "frontier" / "what should I sketch?" — analyzes existing sketch landscape and proposes consistency and frontier sketches
 </purpose>
 
 <required_reading>
@@ -25,9 +29,60 @@ Read all files referenced by the invoking prompt's execution_context before star
 Parse `$ARGUMENTS` for:
 - `--quick` flag → set `QUICK_MODE=true`
 - `--text` flag → set `TEXT_MODE=true`
+- `frontier` or empty → set `FRONTIER_MODE=true`
 - Remaining text → the design idea to sketch
 
-**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
+**Text mode:** If TEXT_MODE is enabled, replace AskUserQuestion calls with plain-text numbered lists.
+</step>
+
+<step name="route">
+## Routing
+
+- **FRONTIER_MODE is true** → Jump to `frontier_mode`
+- **Otherwise** → Continue to `setup_directory`
+</step>
+
+<step name="frontier_mode">
+## Frontier Mode — Propose What to Sketch Next
+
+### Load the Sketch Landscape
+
+If no `.planning/sketches/` directory exists, tell the user there's nothing to analyze and offer to start fresh with an idea instead.
+
+Otherwise, load in this order:
+
+**a. MANIFEST.md** — the design direction, reference points, and sketch table with winners.
+
+**b. Findings skills** — glob `./.claude/skills/sketch-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain curated design decisions from prior wrap-ups.
+
+**c. All sketch READMEs** — read `.planning/sketches/*/README.md` for design questions, winners, and tags.
+
+### Analyze for Consistency Sketches
+
+Review winning variants across all sketches. Look for:
+
+- **Visual consistency gaps:** Two sketches made independent design choices that haven't been tested together.
+- **State combinations:** Individual states validated but not seen in sequence.
+- **Responsive gaps:** Validated at one viewport but the real app needs multiple.
+- **Theme coherence:** Individual components look good but haven't been composed into a full-page view.
+
+If consistency risks exist, present them as concrete proposed sketches with names and design questions. If no meaningful gaps, say so and skip.
+
+### Analyze for Frontier Sketches
+
+Think laterally about the design direction from MANIFEST.md and what's been explored:
+
+- **Unsketched screens:** UI surfaces assumed but unexplored.
+- **Interaction patterns:** Static layouts validated but transitions, loading, drag-and-drop need feeling.
+- **Edge case UI:** 0 items, 1000 items, errors, slow connections.
+- **Alternative directions:** Fresh takes on "fine but not great" sketches.
+- **Polish passes:** Typography, spacing, micro-interactions, empty states.
+
+Present frontier sketches as concrete proposals numbered from the highest existing sketch number.
+
+### Get Alignment and Execute
+
+Present all consistency and frontier candidates, then ask which to run. When the user picks sketches, update `.planning/sketches/MANIFEST.md` and proceed directly to building them starting at `build_sketches`.
 </step>
 
 <step name="setup_directory">
@@ -49,27 +104,45 @@ COMMIT_DOCS=$(gsd-sdk query config-get commit_docs 2>/dev/null || echo "true")
 </step>
 
 <step name="mood_intake">
-**If `QUICK_MODE` is true:** Skip mood intake. Use whatever the user provided in `$ARGUMENTS` as the design direction. Jump to `decompose`.
+**If `QUICK_MODE` is true:** Skip mood intake. Use whatever the user provided in `$ARGUMENTS` as the design direction. Jump to `load_spike_context`.
 
 **Otherwise:**
 
-**Text mode:** If TEXT_MODE is enabled (set in the banner step), replace AskUserQuestion calls with plain-text numbered lists — emit the options and ask the user to type the number of their choice.
-
-Before sketching anything, explore the design intent through conversation. Ask one question at a time — using AskUserQuestion in normal mode, or a plain-text numbered list if TEXT_MODE is active — with a paragraph of context and reasoning for each.
+Before sketching anything, explore the design intent through conversation. Ask one question at a time — using AskUserQuestion in normal mode, or a plain-text numbered list if TEXT_MODE is active.
 
 **Questions to cover (adapt to what the user has already shared):**
 
-1. **Feel:** "What should this feel like? Give me adjectives, emotions, or a vibe." (e.g., "clean and clinical", "warm and playful", "dense and powerful")
-2. **References:** "What apps, sites, or products have a similar feel to what you're imagining?" (gives concrete visual anchors)
-3. **Core action:** "What's the single most important thing a user does here?" (focuses the sketch on what matters)
+1. **Feel:** "What should this feel like? Give me adjectives, emotions, or a vibe."
+2. **References:** "What apps, sites, or products have a similar feel to what you're imagining?"
+3. **Core action:** "What's the single most important thing a user does here?"
 
-You may need more or fewer questions depending on how much the user shares upfront. After each answer, briefly reflect what you heard and how it shapes your thinking.
+After each answer, briefly reflect what you heard and how it shapes your thinking.
 
 When you have enough signal, ask: **"I think I have a good sense of the direction. Ready for me to sketch, or want to keep discussing?"**
 
 Only proceed when the user says go.
 </step>
 
+<step name="load_spike_context">
+## Load Spike Context
+
+If spikes exist for this project, read them to ground the sketches in reality. Mockups are still pure HTML, but they should reflect what's actually been proven — real data shapes, real component names, real interaction patterns.
+
+**a.** Glob for `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain validated patterns and requirements.
+
+**b.** Read `.planning/spikes/MANIFEST.md` if it exists — check the Requirements section for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
+
+**c.** Read `.planning/spikes/CONVENTIONS.md` if it exists — the established stack informs what's buildable and what interaction patterns are idiomatic.
+
+**How spike context improves sketches:**
+- Use real field names and data shapes from spike findings instead of generic placeholders
+- Show realistic UI states that match what the spikes proved (e.g., if streaming was validated, show a streaming message state)
+- Reference real component names and patterns from the target stack
+- Include interaction states that reflect what the spikes discovered (loading, error, reconnection states)
+
+**If no spikes exist**, skip this step.
+</step>
+
 <step name="decompose">
 Break the idea into 2-5 design questions. Present as a table:
 
@@ -92,6 +165,28 @@ Bad sketches:
 Present the table and get alignment before building.
 </step>
 
+<step name="research_stack">
+## Research the Target Stack
+
+Before sketching, ground the design in what's actually buildable. Sketches are HTML, but they should reflect real constraints of the target implementation.
+
+**a. Identify the target stack.** Check for package.json, Cargo.toml, etc. If the user mentioned a framework (React, SwiftUI, Flutter, etc.), note it.
+
+**b. Check component/pattern availability.** Use context7 (resolve-library-id → query-docs) or web search to answer:
+- What layout primitives does the target framework provide?
+- Are there existing component libraries in use? What components are available?
+- What interaction patterns are idiomatic?
+
+**c. Note constraints that affect design:**
+- Platform conventions (iOS nav patterns, desktop menu bars, terminal grid constraints)
+- Framework limitations (what's easy vs requires custom work)
+- Existing design tokens or theme systems already in the project
+
+**d. Let research inform variants.** At least one variant should follow the path of least resistance for the target stack.
+
+**Skip when unnecessary.** Greenfield project with no stack, or user says "just explore visually." The point is grounding, not gatekeeping.
+</step>
+
 <step name="create_manifest">
 Create or update `.planning/sketches/MANIFEST.md`:
 
@@ -124,26 +219,24 @@ Build each sketch in order.
 
 ### For Each Sketch:
 
-**a.** Find next available number by checking existing `.planning/sketches/NNN-*/` directories.
-Format: three-digit zero-padded + hyphenated descriptive name.
+**a.** Find next available number. Format: three-digit zero-padded + hyphenated descriptive name.
 
 **b.** Create the sketch directory: `.planning/sketches/NNN-descriptive-name/`
 
 **c.** Build `index.html` with 2-3 variants:
 
-**First round — dramatic differences:** Build 2-3 meaningfully different approaches to the design question. Different layouts, different visual structures, different interaction models.
-
-**Subsequent rounds — refinements:** Once the user has picked a direction or cherry-picked elements, build subtler variations within that direction.
+**First round — dramatic differences:** 2-3 meaningfully different approaches.
+**Subsequent rounds — refinements:** Subtler variations within the chosen direction.
 
 Each variant is a page/tab in the same HTML file. Include:
 - Tab navigation to switch between variants (see `sketch-variant-patterns.md`)
 - Clear labels: "Variant A: Sidebar Layout", "Variant B: Top Nav", etc.
 - The sketch toolbar (see `sketch-tooling.md`)
 - All interactive elements functional (see `sketch-interactivity.md`)
-- Real-ish content, not lorem ipsum
+- Real-ish content, not lorem ipsum (use real field names from spike context if available)
 - Link to `../themes/default.css` for shared theme variables
 
-**All sketches are plain HTML with inline CSS and JS.** No build step, no npm, no framework. Opens instantly in a browser.
+**All sketches are plain HTML with inline CSS and JS.** No build step, no npm, no framework.
 
 **d.** Write `README.md`:
 
@@ -190,16 +283,16 @@ Compare: {what to look for between variants}
 ──────────────────────────────────────────────────────────────
 
 **f.** Handle feedback:
-- **Pick a direction:** "I like variant B" → mark winner in README, move to next sketch
-- **Cherry-pick elements:** "Rounded edges from A, color treatment from C" → build a synthesis as a new variant, show again
-- **Want more exploration:** "None of these feel right, try X instead" → build new variants
+- **Pick a direction:** mark winner, move to next sketch
+- **Cherry-pick elements:** build synthesis as new variant, show again
+- **Want more exploration:** build new variants
 
-Iterate until the user is satisfied with a direction for this sketch.
+Iterate until satisfied.
 
 **g.** Finalize:
-1. Mark the winning variant in the README frontmatter (`winner: "B"`)
-2. Add ★ indicator to the winning tab in the HTML
-3. Update `.planning/sketches/MANIFEST.md` with the sketch row
+1. Mark winning variant in README frontmatter (`winner: "B"`)
+2. Add ★ indicator to winning tab in HTML
+3. Update `.planning/sketches/MANIFEST.md`
 
 **h.** Commit (if `COMMIT_DOCS` is true):
 ```bash
@@ -215,7 +308,7 @@ gsd-sdk query commit "docs(sketch-NNN): [winning direction] — [key visual insi
 </step>
 
 <step name="report">
-After all sketches complete, present the summary:
+After all sketches complete:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -243,8 +336,8 @@ After all sketches complete, present the summary:
 ───────────────────────────────────────────────────────────────
 
 **Also available:**
+- `/gsd-sketch` — sketch more (or run with no argument for frontier mode)
 - `/gsd-plan-phase` — start building the real UI
-- `/gsd-explore` — continue exploring the concept
 - `/gsd-spike` — spike technical feasibility of a design pattern
 
 ───────────────────────────────────────────────────────────────
@@ -255,7 +348,9 @@ After all sketches complete, present the summary:
 <success_criteria>
 - [ ] `.planning/sketches/` created (auto-creates if needed, no project init required)
 - [ ] Design direction explored conversationally before any code (unless --quick)
-- [ ] Each sketch has 2-3 variants for comparison
+- [ ] Spike context loaded — real data shapes, requirements, and conventions inform mockups
+- [ ] Target stack researched — component availability, constraints, idioms (unless greenfield/skipped)
+- [ ] Each sketch has 2-3 variants for comparison (at least one follows path of least resistance)
 - [ ] User can open and interact with sketches in a browser
 - [ ] Winning variant selected and marked for each sketch
 - [ ] All variants preserved (winner marked, not others deleted)