@zigrivers/scaffold 3.10.0 → 3.11.0

package/README.md

@@ -1,6 +1,6 @@
 # Scaffold
 
-A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
+A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 11 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
 
 By the end, you'll have a fully planned, standards-documented, implementation-ready project with working code.
 
@@ -1381,9 +1381,10 @@ These are orthogonal to the pipeline — usable at any time, not tied to pipelin
 | `scaffold run review-code` | Run all 3 code review channels on local code before commit or push. |
 | `scaffold run review-pr` | Run all 3 code review channels (Codex CLI, Gemini CLI, Superpowers) on a PR. |
 | `scaffold run post-implementation-review` | Full 3-channel codebase review after an AI agent completes all tasks — checks requirements coverage, security, architecture alignment, and more. |
+| `scaffold run spark` | Explore and expand a raw project idea through Socratic questioning, competitive research, and innovation expansion. Produces a `docs/spark-brief.md` that feeds into `create-vision`. At depth 4+, dispatches to external models for independent research and adversarial red-teaming. |
 | `scaffold run session-analyzer` | Analyze Claude Code session logs for patterns and insights. |
 
-Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
+Use `scaffold run spark` before `create-vision` when you have a vague idea that needs sharpening. Use `scaffold run review-code` before commit or push when you want a local gate on the current delivery candidate. Use `scaffold run review-pr` after a GitHub PR exists.
 
 Run any of these via the CLI or ask the scaffold runner skill in Claude Code or Gemini.
 

package/content/knowledge/core/multi-model-research-dispatch.md

@@ -0,0 +1,208 @@
+---
+name: multi-model-research-dispatch
+description: Patterns for dispatching research and adversarial challenge to external AI models (Codex, Gemini) with reconciliation rules and single-model fallback
+topics: [multi-model, research, competitive-analysis, red-team, codex, gemini, dispatch, reconciliation]
+---
+
+# Multi-Model Research Dispatch
+
+At higher methodology depths (4+), idea exploration and adversarial challenge benefit from independent research by external AI models. This entry provides dispatch patterns, reconciliation rules, and fallback strategies for research and red-team workflows.
+
+## Summary
+
+### When to Dispatch
+| Depth | Research Dispatch | Challenge Dispatch |
+|-------|-------------------|-------------------|
+| 1-3 | Skip | Skip |
+| 4 | 1 external model | 1 external model |
+| 5 | Multi-model with reconciliation | Multi-model with reconciliation |
+
+### Graceful Fallback Chain
+1. Check if external CLI is available (`which codex`, `which gemini`)
+2. If available, check auth (`codex login status`, `NO_BROWSER=true gemini -p "respond with ok" -o json`)
+3. If auth succeeds, dispatch with timeout
+4. If CLI unavailable or auth fails, skip that model — note in Session Metadata
+5. If no external models available, fall back to primary model with distinct framing prompts
+6. Never block the session waiting for unavailable tools
+
+### Reconciliation Rules
+- **2+ models agree** on the same finding = **consensus** — high confidence, present as validated
+- **Models disagree** = **divergent** — present ALL perspectives including minority views. Do NOT suppress the minority. A 2-1 split where the lone dissent flags a real risk is more valuable than a comfortable consensus.
+- **Single model** (fallback) = skip reconciliation labels. Present findings directly without consensus/divergent framing.
+
+## Deep Guidance
+
+### CLI Availability Check
+
+Before dispatching, verify CLI tools are installed and authenticated:
+
+```bash
+# Codex CLI
+which codex >/dev/null 2>&1 && codex login status 2>/dev/null
+# Exit 0 = ready. Non-zero = skip Codex.
+
+# Gemini CLI
+which gemini >/dev/null 2>&1 && NO_BROWSER=true gemini -p "respond with ok" -o json 2>&1
+# Check for "ok" in response. Exit 41 = auth failure.
+```
+
+If auth fails, tell the user which tool failed and how to fix it:
+- Codex: "Codex auth expired — run `! codex login` to re-authenticate"
+- Gemini: "Gemini auth expired — run `! gemini -p \"hello\"` to re-authenticate"
+
+Auth failures are NOT silent fallbacks — surface them explicitly.
+
+### Timeout Handling
+
+| Dispatch type | Timeout |
+|---------------|---------|
+| Research dispatch (idea summary + questions) | 120 seconds |
+| Challenge dispatch (full brief review) | 180 seconds |
+
+If a dispatch times out:
+- Use whatever partial response was received (if parseable)
+- Note the timeout in Session Metadata
+- Do NOT retry — proceed with available data
+
+### Research Dispatch Mode
+
+**When**: Phase 2 at depth 4-5.
+
+**Prompt template for external model:**
+
+```
+You are conducting independent competitive research for a product idea.
+
+IDEA: [1-2 sentence summary of the idea from Phase 1]
+
+RESEARCH QUESTIONS:
+1. What are the direct competitors in this space? For each, note what they do well and where they fall short.
+2. What indirect alternatives exist — different approaches to the same problem?
+3. How do users currently cope without a dedicated solution?
+4. What recent market signals exist — funding rounds, product launches, shutdowns, regulatory changes?
+5. What adjacent markets or analogous systems could inform this idea?
+
+Be thorough and honest. Acknowledge competitor strengths — do not dismiss them.
+Respond in structured markdown with one section per question.
+```
+
+**Execution:**
+
+```bash
+# Codex
+codex exec --skip-git-repo-check -s read-only --ephemeral "RESEARCH_PROMPT" 2>&1
+
+# Gemini
+NO_BROWSER=true gemini -p "RESEARCH_PROMPT" --output-format json --approval-mode yolo 2>/dev/null
+```
+
+**Processing results:**
+- Parse the response as structured markdown
+- Extract key findings per research question
+- If multi-model (depth 5), run reconciliation (see below)
+- Present findings to the user conversationally, not as raw output
+
+### Challenge Dispatch Mode (Red-Team)
+
+**When**: Phase 6 at depth 4-5.
+
+**Prompt template for external model:**
+
+```
+You are an adversarial reviewer stress-testing a product idea brief.
+Your job is to find weaknesses, challenge assumptions, and surface missed opportunities.
+
+SPARK BRIEF:
+[Full content of the draft spark-brief.md]
+
+CHALLENGE INSTRUCTIONS:
+1. For each section, identify the weakest assumption and explain why it might be wrong.
+2. What competitors or market dynamics does the brief underestimate?
+3. What technical feasibility risks are glossed over?
+4. What user segments or use cases are missing?
+5. If you could only flag ONE critical risk, what would it be?
+
+Be constructive but ruthless. The goal is to strengthen the idea, not validate it.
+Respond in structured markdown with one section per challenge area.
+```
+
+**Processing results:**
+- Parse challenges from response
+- Present each challenge to the user one at a time
+- For each challenge, ask: "Accept (update the brief), dismiss (explain why it's not applicable), or defer (note as open question)?"
+- Track dispositions and update the brief accordingly
+
+### Single-Model Fallback
+
+When no external models are available, the primary model simulates multiple perspectives:
+
+**Perspective 1 — Venture Capitalist**: "Analyze this idea as a VC evaluating a pitch. What's the market size? What's the defensibility? What are the unit economics? Would you invest?"
+
+**Perspective 2 — Competitor's Product Lead**: "You're the product lead at [biggest competitor]. You just learned about this idea. What's your reaction? What would you do to defend your position? What aspects worry you?"
+
+**Perspective 3 — Skeptical End User**: "You're a potential user who has tried and abandoned 3 similar products. What would make you try this one? What would make you abandon it after a week? What's the one thing that would keep you?"
+
+Run each perspective as a separate reasoning pass. Synthesize the three viewpoints into findings the user can act on.
+
+### Model Selection
+
+| Task | Recommended model | Rationale |
+|------|-------------------|-----------|
+| Research dispatch | Either Codex or Gemini | Both capable of web-informed reasoning |
+| Challenge dispatch | Either Codex or Gemini | Adversarial analysis is model-agnostic |
+| Depth 4 (1 model) | Prefer Gemini (Google search built-in) | Strongest for competitive research |
+| Depth 5 (multi) | Both Codex AND Gemini | Diverse perspectives from different architectures |
+
+### Reconciliation Process (Depth 5)
+
+When two or more models return research findings, reconcile them:
+
+1. **Extract findings**: Parse each model's response into discrete findings (one competitor, one market signal, one risk = one finding).
+2. **Match findings**: Compare findings across models. Two findings match if they reference the same entity (competitor, trend, risk) even if the wording differs.
+3. **Classify each finding**:
+   - **Consensus**: 2+ models independently identified the same finding. High confidence.
+   - **Divergent**: Models disagree about the same entity (e.g., one says competitor X is strong, another says X is weak). Present both perspectives with reasoning.
+   - **Unique**: Only one model surfaced this finding. Not necessarily wrong — may be the most valuable insight. Present it without discounting.
+4. **Synthesize for the user**: Present findings grouped by classification. Lead with consensus (highest confidence), then unique (potential insights), then divergent (needs user judgment).
+5. **Never suppress minority views**: A lone model flagging a risk that others missed may be the most important finding in the entire research pass.
+
+### Quality Gates
+
+Before presenting research findings to the user, verify:
+
+- At least 2 competitors or alternatives identified (even at depth 4 with single model)
+- Each competitor has both a strength and a weakness documented
+- The "do nothing" option is addressed (how users cope without any tool)
+- Market timing signals are present (why now?)
+- If multi-model: reconciliation labels (consensus/divergent/unique) are applied
+
+### Common Anti-Patterns
+
+| Anti-pattern | Problem | Fix |
+|-------------|---------|-----|
+| Dismissing competitors | "They're not really competition" — every alternative is competition | Acknowledge strengths honestly |
+| Echo chamber | Both models agree because both drew from the same training data | Look for unique findings, not just consensus |
+| Recency bias | Focusing only on recent launches, ignoring established players | Include both established and emerging competitors |
+| Feature-list comparison | Comparing feature lists instead of positioning | Compare on audience, value prop, and differentiation |
+| Silent fallback | External model fails, no mention in output | Always note which models were used and any failures |
+| Over-synthesis | Merging distinct findings into one summary, losing nuance | Preserve individual findings before synthesizing |
+
+### Output Format
+
+When presenting research findings to the user, structure them as:
+
+**Competitive Landscape:**
+- [Competitor 1]: Strengths — [specifics]. Weaknesses — [specifics]. Why users choose them — [specifics].
+- [Competitor 2]: ...
+- "Do nothing" option: How users cope today — [specifics]. Why it's insufficient — [specifics].
+
+**Market Signals:**
+- [Signal 1]: [What happened, when, why it matters for this idea]
+- [Signal 2]: ...
+
+**Expansion Opportunities** (from adjacent market research):
+- [Opportunity 1]: [What it is, why it's relevant, how it connects]
+
+**Red-Team Challenges** (from adversarial review):
+- [Challenge 1]: [Weakness identified, why it matters, recommended action]
+  - Disposition: [accept/dismiss/defer — tracked after user response]

package/content/knowledge/game/game-ideation.md

@@ -0,0 +1,100 @@
+---
+name: game-ideation
+description: Game-specific ideation techniques for spark — core loop, player fantasy, retention, session design, monetization
+topics: [game-dev, ideation, core-loop, player-fantasy, retention, monetization, session-design]
+---
+
+Game ideation applies game-specific lenses — core loop, player fantasy, retention mechanics, session design, and monetization — to the spark tool's ideation flow. It supplements the general ideation-craft entry when a user is exploring a game idea.
+
+## Summary
+
+### Game Ideation Lenses
+Five lenses to apply during idea exploration: **Core loop** (what the player does every 30 seconds), **Player fantasy** (the emotional experience, not mechanics), **Retention** (what brings players back), **Session design** (how long and how satisfying), **Monetization** (how the game sustains itself).
+
+### Quick Tests
+- **Core loop**: Can you describe it in one sentence without "and"?
+- **Player fantasy**: Does every major mechanic reinforce it?
+- **Retention**: What happens if the player leaves for a week?
+
+## Deep Guidance
+
+### Core Loop Identification
+- **What is the core loop?** The repeating cycle of actions the player performs most often. In a shooter: aim → shoot → loot → repeat. In a puzzle game: observe → plan → execute → evaluate → repeat.
+- **Ask the user**: "What does the player do every 30 seconds? Every 5 minutes? Every session?"
+- **Test**: Can you describe the core loop in one sentence without using the word "and"? If not, it's too complex or undefined.
+
+### Player Fantasy
+- **What fantasy does the player live out?** Not the game mechanics — the emotional experience. "I am a powerful wizard" not "I cast spells with mana."
+- **Ask the user**: "When the player tells their friend about your game, what do they say it feels like?"
+- **Test**: Does every major mechanic reinforce the fantasy? If a mechanic exists but doesn't serve the fantasy, question why it's there.
+
+### Retention Mechanics
+- **Session hooks**: What brings the player back tomorrow? (Daily rewards, story cliffhangers, social obligations, unfinished goals)
+- **Progression**: What does the player invest that makes leaving costly? (Character levels, base building, collection progress, social reputation)
+- **Ask the user**: "What happens if the player doesn't open the game for a week? Do they lose anything? Miss anything?"
+
+### Session Design
+- **Session length**: How long is a typical play session? (Mobile: 3-5 min. PC: 30-90 min. Console: 60+ min.)
+- **Session arc**: Does each session have a beginning, middle, and satisfying end? Can the player stop mid-session without frustration?
+- **Ask the user**: "Where and when does your player play? Commute? Couch? Desk? This determines session length."
+
+### Monetization Models
+- **Premium**: Pay once, play forever. Best for narrative, creative, or skill-based games.
+- **Free-to-play**: Free entry, monetize through cosmetics, battle pass, or convenience. Best for multiplayer/social games.
+- **Subscription**: Recurring payment for ongoing content. Best for live-service games.
+- **Ask the user**: "How does your player feel about spending money in your game? What would they pay for? What would feel unfair?"
+
+### Applying Game Lenses During Spark Phases
+
+**Phase 1 (Seed)**: Ask about the core loop and player fantasy early. These are the foundation — if they're unclear, everything else is built on sand.
+
+**Phase 2 (Research)**: Research competitors through a game lens. For each competitor: What's their core loop? What fantasy do they deliver? How do they monetize? What's their session design? Where do player reviews complain?
+
+**Phase 3 (Expand)**: Use game-specific expansion angles:
+- "What if the core loop had a social/multiplayer dimension?"
+- "What if you added a metagame layer on top of the core loop?"
+- "What platform would change the experience most? (Mobile → PC, or vice versa)"
+- "What if monetization was through player-created content?"
+
+**Phase 4 (Challenge)**: Challenge through game-specific risk lenses:
+- "Core loop fatigue — will this still be fun after 100 hours?"
+- "Monetization pressure — does the business model conflict with the player fantasy?"
+- "Scope vs. team — can a [team size] team build this in [timeline]?"
+- "Platform expectations — does the session design match the platform's usage patterns?"
+
+### Game-Specific Brief Sections
+
+When writing the spark brief for a game idea, adapt sections:
+- **Idea & Problem Space** → Include the core loop and player fantasy
+- **Landscape** → Frame competitors by core loop and fantasy, not just features
+- **Expansion Ideas** → Tag which ideas affect the core loop vs. metagame vs. content
+- **Risks** → Include core loop fatigue, monetization/fantasy tension, and scope risks
+
+### Scoping by Project Scale
+
+| Scale | Core loop | Content depth | Monetization | Session design |
+|-------|-----------|---------------|-------------|----------------|
+| Game jam (48-72h) | One mechanic, tight loop | Minimal — procedural or template | None (free) | 5-15 min total |
+| Indie (solo/small team) | 1-2 mechanics, polished | Handcrafted, limited scope | Premium or F2P with cosmetics | 15-60 min sessions |
+| AA/studio | Multiple interlocking systems | Extensive content pipeline | Any model, balanced | Platform-appropriate |
+
+### Common Game Ideation Anti-Patterns
+
+- **The Kitchen Sink**: Trying to combine too many mechanics before any one is fun. Focus the core loop first.
+- **Fantasy Mismatch**: The monetization model undermines the player fantasy. (Pay-to-win in a skill-based competitive game.)
+- **Platform Blindness**: Designing a 90-minute session game for mobile, or a 3-minute session for PC/console.
+- **Retention Treadmill**: Relying on FOMO and daily login rewards instead of intrinsic motivation. Players resent obligation.
+- **Scope Denial**: "We'll just add multiplayer later." Multiplayer is an architecture decision, not a feature toggle.
+- **Clone Trap**: "Like [popular game] but with [small twist]." The twist must be fundamental enough to justify switching costs.
+
+### Core Loop Evaluation Worksheet
+
+When evaluating a proposed core loop, walk through these questions:
+
+1. **Primary loop**: What does the player do every 30 seconds? Is it inherently satisfying?
+2. **Secondary loop**: What does the player do every 5 minutes? Does it give meaning to the primary loop?
+3. **Tertiary loop**: What does the player do every session? Does it create a sense of progress?
+4. **Friction test**: Remove one mechanic from the loop. Does the game still work? If yes, that mechanic may be unnecessary.
+5. **Fantasy alignment**: Does every step in the loop reinforce the player fantasy? If a step breaks immersion, redesign it.
+6. **Depth test**: Can a skilled player execute the loop differently than a novice? If not, the loop may lack depth.
+7. **Social test**: Would watching someone else do this loop be entertaining? If not, the loop may lack spectacle or surprise.

package/content/knowledge/product/ideation-craft.md

@@ -0,0 +1,209 @@
+---
+name: ideation-craft
+description: Questioning techniques, research methodology, lightweight expansion patterns, and brief synthesis for early-stage idea exploration
+topics: [ideation, questioning, research, competitive-analysis, brief-synthesis, socratic-method]
+---
+
+# Ideation Craft
+
+Ideation craft covers the questioning, research, and synthesis techniques used during early-stage idea exploration. It guides a conversational flow from a raw idea through competitive research to a structured idea brief.
+
+## Summary
+
+### Key Techniques
+- **Questioning**: Socratic method (what → who → why → why not), 5 Whys for root cause, "What would have to be true?" for assumptions. Batch 2-3 questions per turn.
+- **Research**: Scan direct competitors, indirect alternatives, and the "do nothing" option. Capture strengths, weaknesses, positioning per competitor. Check adjacent markets and market timing.
+- **Expansion**: Lightweight one-liner prompts — adjacent markets, ecosystem plays, contrarian angles, tech enablers, AI-native rethinking. These are conversation starters, not full strategic methodology.
+- **Synthesis**: 2-4 sentences per brief section. Tag confidence: validated, hypothesized, or speculative. Never fabricate — write "None identified" for empty sections.
+
+## Deep Guidance
+
+### Questioning Techniques
+
+- **Socratic method**: Ask progressively deeper questions. Start with "what" (the idea), move to "who" (the audience), then "why" (the problem), then "why not" (the assumptions).
+- **The 5 Whys**: When the user states a problem, ask "why?" five times to reach the root cause. Surface-level problems hide deeper opportunities.
+- **"What would have to be true?"**: For every assumption, ask what conditions must hold for it to work. This surfaces hidden dependencies and risks.
+- **Batching**: Group 2-3 related questions per turn. Don't pepper the user with single questions (wastes turns) or overwhelm with 10 at once (causes shallow answers).
+
+### Progressive Questioning Framework
+
+**Turn 1 — Capture the spark**: What are you building? Who is it for? What problem does it solve?
+
+**Turn 2 — Dig into the problem**: How do people solve this today? What's painful about the current approach? How often do they experience this pain?
+
+**Turn 3 — Understand the audience**: Describe the person who needs this most. What are they doing the moment before they reach for your product? What does "success" look like from their perspective?
+
+**Turn 4 — Challenge assumptions**: You said [X] — what evidence do you have? What would have to be true for [Y] to work? If [Z] turned out to be wrong, would the idea still make sense?
+
+**Turn 5+ — Deepen based on gaps**: Follow the thread. If the audience is unclear, keep pulling on that. If the problem is well-defined but the solution is vague, focus there. Don't follow a script — follow the gaps.
+
+### Research Methodology
+
+- **Competitor scan**: Search for direct competitors (same problem, same audience), indirect alternatives (different approach, same problem), and the "do nothing" option (how users cope today).
+- **What to capture per competitor**: Name, what they do well (be specific), where they fall short (be honest), pricing model, target audience, and why a user might choose them over the idea.
+- **Adjacent markets**: Look for products solving related problems for the same audience, or the same problem for a different audience. These are expansion opportunities.
+- **Market timing**: Why now? What changed (technology, regulation, culture, behavior) that makes this idea viable today when it wasn't before?
+
+### Expansion Patterns (Lightweight)
+
+- **Adjacent market**: "Your users also need X — have you considered expanding into that?"
+- **Ecosystem play**: "If you solve A, you become the natural place to also solve B and C."
+- **Contrarian angle**: "Everyone in this space does X. What if you deliberately did the opposite?"
+- **Technology enabler**: "A new capability (API, model, platform) makes Y possible now — could that reshape your approach?"
+- **AI-native rethinking**: "If you assumed AI could handle Z, how would that change the product?"
+
+These are conversation starters for Phase 3 (Expand), not full strategic methodology. The pipeline's `innovate-vision` step covers comprehensive strategic expansion later.
+
+### Brief Synthesis
+
+- A good directional hypothesis names a specific audience, problem, and approach — not vague aspirations.
+- Bad: "This app will help people be more productive." Good: "Freelance designers who lose 5+ hours/week to invoice tracking — a tool that auto-generates invoices from their time-tracking data."
+- Tag confidence levels: "validated" (user confirmed + research supports), "hypothesized" (user stated but unresearched), "speculative" (surfaced during expansion, unconfirmed).
+- Each brief section should be 2-4 sentences or concise bullet points. If a section has nothing, write "None identified" — don't fabricate.
+
+### Competitive Research Process
+
+1. **Start with the obvious**: Search for "[problem] app" or "[problem] tool." The first 5-10 results are the landscape the user will compete against.
+2. **Check review sites**: App Store reviews, G2, Capterra, ProductHunt comments. Users complain about exactly the gaps a new product can fill.
+3. **Look for failures**: Search "[category] startup failed" or "[competitor] shutdown." Failed attempts tell you what didn't work and why.
+4. **Find the "do nothing" option**: How do people cope without any tool? Spreadsheets, manual processes, asking friends? This is often the biggest competitor.
+5. **Assess timing**: Search for recent news, funding rounds, regulatory changes, or technology launches in the space. Timing explains why an idea works now when it didn't before.
+
+### Framing Research for External Model Dispatch
+
+When dispatching to an external model for competitive research (depth 4+), frame the prompt as:
+
+> "Research the competitive landscape for [idea summary]. Identify: (1) Direct competitors solving the same problem for the same audience, (2) Indirect alternatives — different approaches to the same problem, (3) The 'do nothing' option — how users cope today, (4) Recent market signals — funding, launches, shutdowns, regulatory changes. For each competitor, note what they do well and where they fall short. Be honest — acknowledge genuine strengths."
+
+### Brief Section Guidance
+
+| Section | Source Phase | What to write | Common mistakes |
+|---------|-------------|---------------|-----------------|
+| Idea & Problem Space | Phase 1 (Seed) | Core idea, specific problem, target audience, why they need it | Too vague ("helps people"), no audience specificity |
+| Landscape | Phase 2 (Research) | 2-5 competitors with strengths/weaknesses, positioning | Dismissing competitors, listing without analysis |
+| Expansion Ideas | Phase 3 (Expand) | Accepted ideas tagged as preliminary, deferred ideas noted | Treating preliminary as committed scope |
+| Constraints & Scope | Phase 4 (Challenge) | Confirmed assumptions, what's in/out, locked decisions | Scope too broad, no explicit "out" list |
+| Technology Opportunities | Phase 2-3 | Tech enablers discovered during research/expansion | Listing technologies without explaining why they matter |
+| Open Questions | All phases | Unresolved items that need answers before building | Ignoring questions that feel uncomfortable |
+| Risks | Phase 4 (Challenge) | Market, technical, feasibility risks with severity | Only listing technical risks, ignoring market risks |
+
+### Audience Definition Techniques
+
+Avoid demographic-only definitions ("18-35 year old professionals"). Instead, define audiences by behavior and motivation:
+
+**Behavior-based**: "People who currently track expenses in a spreadsheet because existing apps are too complex."
+**Motivation-based**: "Freelancers who want to spend less than 10 minutes per week on invoicing so they can focus on client work."
+**Context-based**: "The moment someone finishes a client project and thinks 'now I have to figure out the invoice' — that's when they need this."
+
+**Questions to sharpen audience definition:**
+- What is this person doing the moment before they reach for your product?
+- What is the last thing they tried? Why did it fail them?
+- How would they describe their problem to a friend (not in your language — in theirs)?
+- If you could only serve ONE type of user, who would it be and why?
+
+### Problem Validation Framework
+
+Before accepting a problem statement, test it:
+
+1. **Specificity test**: Can you name a real person (or type of person) who has this problem? If "everyone has this problem," it's too vague.
+2. **Frequency test**: How often does this problem occur? Daily problems are more valuable than annual ones.
+3. **Severity test**: When this problem occurs, how painful is it? Mild inconvenience or hair-on-fire emergency?
+4. **Workaround test**: How do people cope today? If they have a workable (even if imperfect) solution, your product must be dramatically better.
+5. **Willingness test**: Would someone pay money / change habits / switch tools to solve this? If not, the problem may not be valuable enough.
+
+### Scope Sharpening Techniques
+
+When the idea is too broad, use these techniques to find the core:
+
+- **The one-feature test**: "If your product could only do ONE thing, what would it be?" This reveals the core value proposition.
+- **The removal test**: "If you removed [feature X], would anyone still use the product?" If yes, X is not core.
+- **The first-user test**: "Who is the first person who would use this, and what exactly would they do with it?" This grounds abstract ideas in concrete behavior.
+- **The MVP boundary**: "What is the smallest thing you could build that would make one person's life measurably better?" This defines the initial scope.
+- **The anti-scope list**: Explicitly list what the product does NOT do. This is as important as what it does.
+
+### Positioning Against Competitors
+
+When the landscape is crowded, help the user find genuine differentiation:
+
+- **Head-to-head**: "Competitor X does this well. You would need to be 10x better at this specific thing to win users away. Can you be?"
+- **Underserved segment**: "Competitor X serves enterprise. Is there an underserved segment (freelancers, students, non-profits) that you could own?"
+- **Different job**: "Competitor X solves problem A. Could you solve a related but different problem B for the same audience?"
+- **Channel advantage**: "Competitor X requires a desktop app. Could you win by being mobile-first, browser-based, or embedded in an existing workflow?"
+- **Timing advantage**: "What has changed (new technology, regulation, cultural shift) that makes your approach viable now when it wasn't when competitors launched?"
+
+### Ideation Anti-Patterns
+
+| Anti-pattern | What it sounds like | Why it's dangerous | How to challenge |
+|-------------|--------------------|--------------------|-----------------|
+| Solution-first | "I want to build an app that..." | Skips the problem entirely | "What problem does this solve? For whom?" |
+| Everyone-needs-this | "Everyone could use this" | No target audience = no product | "Who needs this MOST? Who would pay?" |
+| Feature soup | "It'll do X and Y and Z and..." | No core value proposition | "Remove one feature. Does it still work?" |
+| Competitor blindness | "Nobody else does this" | Almost certainly false | "How do people solve this today?" |
+| Technology hammer | "I learned [tech] and want to use it" | Technology seeking a problem | "Forget the tech. What problem exists?" |
+| Scale fantasy | "Once we have millions of users..." | Ignores the path to the first user | "How do you get user #1? User #10?" |
+| Uniqueness obsession | "We need a totally new idea" | Execution beats novelty almost always | "What existing idea could you execute 10x better?" |
+
+### Worked Example: From Vague to Sharp
+
+**Vague starting point**: "An app for recipes"
+
+**After Phase 1 (Seed):**
+- Who: Home cooks who meal prep on weekends but waste food because they buy ingredients for recipes they never make.
+- Problem: Planning meals for the week takes 45+ minutes, and existing apps have 50,000 recipes but no help deciding which ones to cook together.
+- Core idea: A meal planning tool that suggests complementary recipes sharing ingredients, minimizing waste and shopping time.
+
+**After Phase 2 (Research):**
+- Competitors: Mealime (good UI but no ingredient overlap), Paprika (great for saving recipes but no planning), Eat This Much (calorie-focused, not taste-focused).
+- Gap: No tool optimizes for ingredient reuse across a week of meals.
+
+**After Phase 3 (Expand):**
+- Accepted: Grocery list auto-generation from the meal plan (directly supports core value).
+- Deferred: Social sharing of meal plans (not core, revisit later).
+- Rejected: Calorie tracking (different problem, different audience).
+
+**After Phase 4 (Challenge):**
+- Confirmed: The ingredient-overlap algorithm is the differentiator.
+- Revised: Scope down from "all cuisines" to "weeknight dinners, 30 min or less" for MVP.
+- Locked out: No restaurant recommendations, no diet tracking, no social features for v1.
+
+This progression from "an app for recipes" to a tightly scoped meal planning tool with a clear differentiator is what a good spark session produces.
+
+### Confidence Tagging Guide
+
+Every claim in the spark brief should carry an implicit confidence level. This helps `create-vision` know what to validate vs. what to build on.
+
+**Validated** (highest confidence):
+- User stated it AND research supports it.
+- Example: "3 competitors exist in this space" (user said, you verified via search).
+- create-vision can build on this without re-exploring.
+
+**Hypothesized** (medium confidence):
+- User stated it but it hasn't been independently verified.
+- Example: "Target users are freelance designers" (user's claim, no research to confirm market size).
+- create-vision should probe deeper on these — targeted follow-up questions.
+
+**Speculative** (lowest confidence):
+- Surfaced during expansion or challenge, not yet confirmed by user.
+- Example: "Meal planning apps retain 3x better than recipe apps" (research finding, user hasn't decided whether to pivot).
+- create-vision should present these as open questions, not assumptions.
+
+**How to apply in the brief:**
+- Don't tag every sentence explicitly (clutters the document).
+- Tag at the section level: "This section is largely validated — user confirmed the audience and research supports the competitive gap."
+- Call out speculative items explicitly: "Note: the social sharing angle is speculative — surfaced during expansion, not yet confirmed."
+
+### Market Timing Analysis
+
+When assessing "why now?", look for these signals:
+
+**Technology shifts**: A new API, platform, or capability that makes something possible (or dramatically cheaper) that wasn't before. Example: LLMs making personalized recommendation affordable for indie tools.
+
+**Regulatory changes**: New laws or standards that create demand or remove barriers. Example: GDPR creating demand for privacy-first alternatives.
+
+**Behavioral changes**: Shifts in how people work, communicate, or consume. Example: Remote work increasing demand for async collaboration tools.
+
+**Market failures**: Recent shutdowns, pivots, or public failures that leave an underserved audience. Example: A popular tool raising prices 10x, driving users to seek alternatives.
+
+**Cultural shifts**: Changing attitudes that make new products viable. Example: Growing sustainability awareness creating demand for waste-reduction tools.
+
+Each timing signal should be specific and verifiable — not "AI is trending" but "GPT-4's function calling API, launched in June 2023, makes it possible to build structured data extraction at 1/100th the cost of custom NLP pipelines."

package/content/methodology/game-overlay.yml

@@ -112,6 +112,8 @@ knowledge-overrides:
     append: [game-design-document]
   critical-path-walkthrough:
     append: [game-design-document]
+  spark:
+    append: [game-ideation]
 
 # ---------------------------------------------------------------------------
 # reads-overrides

package/content/pipeline/foundation/tech-stack.md

@@ -24,6 +24,7 @@ about ecosystem maturity, alternatives, and gotchas.
 ## Inputs
 - docs/plan.md (required) — PRD features, integrations, and technical requirements
 - User preferences (gathered via questions) — language, framework, deployment target, constraints
+- docs/spark-brief.md (optional) — Technology Opportunities section from spark ideation session. If present and not stale (compare tracking comment date against docs/vision.md and docs/plan.md — if the brief predates both, ignore it), use the Technology Opportunities section as supplementary research context when evaluating technology options.
 
 ## Expected Outputs
 - docs/tech-stack.md — complete technology reference with architecture overview,

package/content/pipeline/vision/create-vision.md

@@ -19,6 +19,7 @@ throughout the entire pipeline.
 
 ## Inputs
 - Project idea (provided by user verbally or in a brief)
+- docs/spark-brief.md (optional) — upstream context from spark ideation session
 - Existing project files (if brownfield — any README, docs, or code)
 - Market context or competitive research (if available)
 
@@ -103,11 +104,53 @@ Before starting, check if `docs/vision.md` already exists:
 - **Related docs**: `docs/plan.md`
 - **Special rules**: Never change guiding principles without user approval. Preserve any strategic decisions that were explicitly made by the user.
 
+### Spark Brief Detection
+
+**If `docs/spark-brief.md` exists**: Read it completely. Check its tracking
+comment date against the `docs/vision.md` tracking comment date (if vision
+exists). If the brief predates the current vision, ignore it and note:
+"Spark brief found but predates current vision — ignoring." Check the
+brief's heading (`# Spark Brief: [Idea Name]`) against the current
+`$ARGUMENTS` — if the idea name appears unrelated, ask the user before
+using it.
+
+Otherwise, this is upstream context from a spark ideation session — the user
+has already explored the problem space, researched competitors, expanded the
+idea, and challenged assumptions.
+
+**Accelerated mode**: Use the brief's answers as a baseline and ask targeted
+follow-up questions to expand them to create-vision's required depth. Do not
+skip phases — deepen and validate the brief's hypotheses rather than
+re-exploring from scratch.
+
+If the brief was red-teamed (Session Metadata), treat its competitive
+landscape and risk sections as pre-validated hypotheses — focus discovery on
+gaps or updates rather than re-exploring those areas.
+
+create-vision uses its own configured depth regardless of the brief's depth.
+The brief's depth metadata is informational — it tells you how thoroughly
+the idea was explored, not how thorough this vision step should be.
+
+Defer the brief's "Technology Opportunities" section to downstream phases
+(tech-stack, architecture) — the vision document is about purpose and positioning,
+not technical implementation.
+
+**If `docs/spark-brief.md` does NOT exist**: Proceed normally.
+
 ## Here's my idea:
 $ARGUMENTS
 
 ## Phase 1: Strategic Discovery
 
+### Spark Brief Context
+
+**If `docs/spark-brief.md` was read during Spark Brief Detection above**, use
+it as your baseline for this phase. Do not skip phases — use the brief's
+answers as a starting point and ask targeted follow-up questions to deepen
+and validate the brief's hypotheses to create-vision's required depth.
+
+**If no spark brief exists**, proceed normally with the discovery questions below.
+
 Use AskUserQuestionTool throughout this phase. Batch related questions together — don't ask one at a time.
 
 ### Understand the Problem Space

package/content/tools/prompt-pipeline.md

@@ -159,6 +159,7 @@ Print the following reference directly. Do not read any files or run any command
 | **Resume (multi)** | `/scaffold:multi-agent-resume <agent-name>` | Resuming a worktree agent after a break |
 | **Version Bump** | `/scaffold:version-bump` | Bump version + changelog (no tag/release) |
 | **Release** | `/scaffold:release` | Project-defined release ceremony with changelog + relevant release artifacts |
+| **Spark** | `/scaffold:spark` | Explore and expand a raw project idea |
 | **Visual Dashboard** | `/scaffold:dashboard` | HTML pipeline overview in browser |
 
 ## Process Rules