gsd-opencode 1.5.2 → 1.6.0

package/command/gsd/new-project.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-new-project
 description: Initialize a new project with deep context gathering and PROJECT.md
-allowed-tools:
+tools:
   - read
   - bash
   - write
@@ -10,26 +10,34 @@ allowed-tools:
 
 <objective>
 
-Initialize a new project through comprehensive context gathering.
+Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
 
-This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
+This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. One command takes you from idea to ready-for-planning.
 
-Creates `.planning/` with PROJECT.md and config.json.
+**Creates:**
+- `.planning/PROJECT.md` — project context
+- `.planning/config.json` — workflow preferences
+- `.planning/research/` — domain research (optional)
+- `.planning/REQUIREMENTS.md` — scoped requirements
+- `.planning/ROADMAP.md` — phase structure
+- `.planning/STATE.md` — project memory
+
+**After this command:** Run `/gsd-plan-phase 1` to start execution.
 
 </objective>
 
 <execution_context>
 
-@~/.config/opencode/get-shit-done/references/principles.md
 @~/.config/opencode/get-shit-done/references/questioning.md
+@~/.config/opencode/get-shit-done/references/ui-brand.md
 @~/.config/opencode/get-shit-done/templates/project.md
-@~/.config/opencode/get-shit-done/templates/config.json
+@~/.config/opencode/get-shit-done/templates/requirements.md
 
 </execution_context>
 
 <process>
 
-<step name="setup">
+## Phase 1: Setup
 
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
@@ -40,7 +48,6 @@ Creates `.planning/` with PROJECT.md and config.json.
 
 2. **Initialize git repo in THIS directory** (required even if inside a parent repo):
    ```bash
-   # Check if THIS directory is already a git repo root (handles .git file for worktrees too)
    if [ -d .git ] || [ -f .git ]; then
        echo "Git repo exists in current directory"
    else
@@ -51,7 +58,6 @@ Creates `.planning/` with PROJECT.md and config.json.
 
 3. **Detect existing code (brownfield detection):**
    ```bash
-   # Check for existing code files
    CODE_FILES=$(find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.swift" -o -name "*.java" 2>/dev/null | grep -v node_modules | grep -v .git | head -20)
    HAS_PACKAGE=$([ -f package.json ] || [ -f requirements.txt ] || [ -f Cargo.toml ] || [ -f go.mod ] || [ -f Package.swift ] && echo "yes")
    HAS_CODEBASE_MAP=$([ -d .planning/codebase ] && echo "yes")
@@ -59,9 +65,7 @@ Creates `.planning/` with PROJECT.md and config.json.
 
    **You MUST run all bash commands above using the bash tool before proceeding.**
 
-</step>
-
-<step name="brownfield_offer">
+## Phase 2: Brownfield Offer
 
 **If existing code detected and .planning/codebase/ doesn't exist:**
 
@@ -82,65 +86,65 @@ Run `/gsd-map-codebase` first, then return to `/gsd-new-project`
 ```
 Exit command.
 
-**If "Skip mapping":** Continue to question step.
+**If "Skip mapping":** Continue to Phase 3.
 
-**If no existing code detected OR codebase already mapped:** Continue to question step.
+**If no existing code detected OR codebase already mapped:** Continue to Phase 3.
 
-</step>
+## Phase 3: Deep Questioning
 
-<step name="question">
+**Display stage banner:**
 
-**1. Open (FREEFORM — do NOT use question):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► QUESTIONING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-Ask inline: "What do you want to build?"
+**Open the conversation:**
 
-Wait for their freeform response. This gives you the context needed to ask intelligent follow-up questions.
+Ask inline (freeform, NOT question):
 
-**2. Follow the thread (NOW use question):**
+"What do you want to build?"
 
-Based on their response, use question with options that probe what they mentioned:
-- header: "[Topic they mentioned]"
-- question: "You mentioned [X] — what would that look like?"
-- options: 2-3 interpretations + "Something else"
+Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
 
-**3. Sharpen the core:**
+**Follow the thread:**
 
-Use question:
-- header: "Core"
-- question: "If you could only nail one thing, what would it be?"
-- options: Key aspects they've mentioned + "All equally important" + "Something else"
+Based on what they said, ask follow-up questions that dig into their response. Use question with options that probe what they mentioned — interpretations, clarifications, concrete examples.
 
-**4. Find boundaries:**
+Keep following threads. Each answer opens new threads to explore. Ask about:
+- What excited them
+- What problem sparked this
+- What they mean by vague terms
+- What it would actually look like
+- What's already decided
 
-Use question:
-- header: "Scope"
-- question: "What's explicitly NOT in v1?"
-- options: Things that might be tempting + "Nothing specific" + "Let me list them"
+Consult `questioning.md` for techniques:
+- Challenge vagueness
+- Make abstract concrete
+- Surface assumptions
+- Find edges
+- Reveal motivation
 
-**5. Ground in reality:**
+**Check context (background, not out loud):**
 
-Use question:
-- header: "Constraints"
-- question: "Any hard constraints?"
-- options: Relevant constraint types + "None" + "Yes, let me explain"
+As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
 
-**6. Decision gate:**
+**Decision gate:**
+
+When you could write a clear PROJECT.md, use question:
 
-Use question:
 - header: "Ready?"
-- question: "Ready to create PROJECT.md, or explore more?"
-- options (ALL THREE REQUIRED):
-  - "Create PROJECT.md" — Finalize and continue
-  - "Ask more questions" — I'll dig deeper
-  - "Let me add context" — You have more to share
-
-If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2.
-If "Let me add context" → receive input via their response → return to step 2.
-Loop until "Create PROJECT.md" selected.
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
 
-</step>
+Loop until "Create PROJECT.md" selected.
 
-<step name="project">
+## Phase 4: write PROJECT.md
 
 Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
 
@@ -173,7 +177,7 @@ All Active requirements are hypotheses until shipped and validated.
 
 Infer Validated requirements from existing code:
 
-1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
+1. read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
 2. Identify what the codebase already does
 3. These become the initial Validated set
 
@@ -217,102 +221,636 @@ Initialize with any decisions made during questioning:
 
 Do not compress. Capture everything gathered.
 
-</step>
+**Commit PROJECT.md:**
 
-<step name="mode">
+```bash
+mkdir -p .planning
+git add .planning/PROJECT.md
+git commit -m "$(cat <<'EOF'
+docs: initialize project
 
-Ask workflow mode preference:
+[One-liner from PROJECT.md What This Is section]
+EOF
+)"
+```
 
-Use question:
+## Phase 5: Workflow Preferences
 
-- header: "Mode"
-- question: "How do you want to work?"
-- options:
-  - "YOLO" — Auto-approve, just execute (Recommended)
-  - "Interactive" — Confirm at each step
+Ask all workflow preferences in a single question call (3 questions):
 
-</step>
+```
+questions: [
+  {
+    header: "Mode",
+    question: "How do you want to work?",
+    multiSelect: false,
+    options: [
+      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
+      { label: "Interactive", description: "Confirm at each step" }
+    ]
+  },
+  {
+    header: "Depth",
+    question: "How thorough should planning be?",
+    multiSelect: false,
+    options: [
+      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "Run plans in parallel?",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
+      { label: "Sequential", description: "One plan at a time" }
+    ]
+  }
+]
+```
 
-<step name="depth">
+Create `.planning/config.json` with chosen mode, depth, and parallelization.
 
-Ask planning depth preference:
+**Commit config.json:**
 
-Use question:
+```bash
+git add .planning/config.json
+git commit -m "$(cat <<'EOF'
+chore: add project config
+
+Mode: [chosen mode]
+Depth: [chosen depth]
+Parallelization: [enabled/disabled]
+EOF
+)"
+```
+
+## Phase 6: Research Decision
 
-- header: "Depth"
-- question: "How thorough should planning be?"
+Use question:
+- header: "Research"
+- question: "Research the domain ecosystem before defining requirements?"
 - options:
-  - "Quick" — Ship fast, minimal phases/plans (3-5 phases, 1-3 plans each)
-  - "Standard" — Balanced scope and speed (5-8 phases, 3-5 plans each)
-  - "Comprehensive" — Thorough coverage, more phases/plans (8-12 phases, 5-10 plans each)
+  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
+  - "Skip research" — I know this domain well, go straight to requirements
 
-**Depth controls compression tolerance, not artificial inflation.** All depths use 2-3 tasks per plan. Comprehensive means "don't compress complex work"—it doesn't mean "pad simple work to hit a number."
+**If "Research first":**
 
-</step>
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-<step name="parallelization">
+Researching [domain] ecosystem...
+```
 
-Ask parallel execution preference:
+Create research directory:
+```bash
+mkdir -p .planning/research
+```
 
-Use question:
+**Determine milestone context:**
+
+Check if this is greenfield or subsequent milestone:
+- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
+- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
+
+Display spawning indicator:
+```
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+```
+
+Spawn 4 parallel gsd-project-researcher agents with rich context:
+
+```
+Task(prompt="
+<research_type>
+Project Research — Stack dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: Research the standard stack for building [domain] from scratch.
+Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
+</milestone_context>
+
+<question>
+What's the standard 2025 stack for [domain]?
+</question>
+
+<project_context>
+[PROJECT.md summary - core value, constraints, what they're building]
+</project_context>
+
+<downstream_consumer>
+Your STACK.md feeds into roadmap creation. Be prescriptive:
+- Specific libraries with versions
+- Clear rationale for each choice
+- What NOT to use and why
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Versions are current (verify with Context7/official docs, not training data)
+- [ ] Rationale explains WHY, not just WHAT
+- [ ] Confidence levels assigned to each recommendation
+</quality_gate>
+
+<output>
+write to: .planning/research/STACK.md
+Use template: ~/.config/opencode/get-shit-done/templates/research-project/STACK.md
+</output>
+", subagent_type="gsd-project-researcher", description="Stack research")
+
+Task(prompt="
+<research_type>
+Project Research — Features dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
+Subsequent: How do [target features] typically work? What's expected behavior?
+</milestone_context>
+
+<question>
+What features do [domain] products have? What's table stakes vs differentiating?
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your FEATURES.md feeds into requirements definition. Categorize clearly:
+- Table stakes (must have or users leave)
+- Differentiators (competitive advantage)
+- Anti-features (things to deliberately NOT build)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
+- [ ] Complexity noted for each feature
+- [ ] Dependencies between features identified
+</quality_gate>
+
+<output>
+write to: .planning/research/FEATURES.md
+Use template: ~/.config/opencode/get-shit-done/templates/research-project/FEATURES.md
+</output>
+", subagent_type="gsd-project-researcher", description="Features research")
+
+Task(prompt="
+<research_type>
+Project Research — Architecture dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: How are [domain] systems typically structured? What are major components?
+Subsequent: How do [target features] integrate with existing [domain] architecture?
+</milestone_context>
+
+<question>
+How are [domain] systems typically structured? What are major components?
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your ARCHITECTURE.md informs phase structure in roadmap. Include:
+- Component boundaries (what talks to what)
+- Data flow (how information moves)
+- Suggested build order (dependencies between components)
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Components clearly defined with boundaries
+- [ ] Data flow direction explicit
+- [ ] Build order implications noted
+</quality_gate>
+
+<output>
+write to: .planning/research/ARCHITECTURE.md
+Use template: ~/.config/opencode/get-shit-done/templates/research-project/ARCHITECTURE.md
+</output>
+", subagent_type="gsd-project-researcher", description="Architecture research")
+
+Task(prompt="
+<research_type>
+Project Research — Pitfalls dimension for [domain].
+</research_type>
+
+<milestone_context>
+[greenfield OR subsequent]
+
+Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
+Subsequent: What are common mistakes when adding [target features] to [domain]?
+</milestone_context>
+
+<question>
+What do [domain] projects commonly get wrong? Critical mistakes?
+</question>
+
+<project_context>
+[PROJECT.md summary]
+</project_context>
+
+<downstream_consumer>
+Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
+- Warning signs (how to detect early)
+- Prevention strategy (how to avoid)
+- Which phase should address it
+</downstream_consumer>
+
+<quality_gate>
+- [ ] Pitfalls are specific to this domain (not generic advice)
+- [ ] Prevention strategies are actionable
+- [ ] Phase mapping included where relevant
+</quality_gate>
+
+<output>
+write to: .planning/research/PITFALLS.md
+Use template: ~/.config/opencode/get-shit-done/templates/research-project/PITFALLS.md
+</output>
+", subagent_type="gsd-project-researcher", description="Pitfalls research")
+```
+
+After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
+
+```
+Task(prompt="
+<task>
+Synthesize research outputs into SUMMARY.md.
+</task>
+
+<research_files>
+read these files:
+- .planning/research/STACK.md
+- .planning/research/FEATURES.md
+- .planning/research/ARCHITECTURE.md
+- .planning/research/PITFALLS.md
+</research_files>
+
+<output>
+write to: .planning/research/SUMMARY.md
+Use template: ~/.config/opencode/get-shit-done/templates/research-project/SUMMARY.md
+Commit after writing.
+</output>
+", subagent_type="gsd-research-synthesizer", description="Synthesize research")
+```
+
+Display research complete banner and key findings:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Key Findings
+
+**Stack:** [from SUMMARY.md]
+**Table Stakes:** [from SUMMARY.md]
+**Watch Out For:** [from SUMMARY.md]
+
+Files: `.planning/research/`
+```
+
+**If "Skip research":** Continue to Phase 7.
+
+## Phase 7: Define Requirements
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Load context:**
+
+read PROJECT.md and extract:
+- Core value (the ONE thing that must work)
+- Stated constraints (budget, timeline, tech limitations)
+- Any explicit scope boundaries
+
+**If research exists:** read research/FEATURES.md and extract feature categories.
+
+**Present features by category:**
+
+```
+Here are the features for [domain]:
+
+## Authentication
+**Table stakes:**
+- Sign up with email/password
+- Email verification
+- Password reset
+- Session management
+
+**Differentiators:**
+- Magic link login
+- OAuth (Google, GitHub)
+- 2FA
+
+**Research notes:** [any relevant notes]
+
+---
 
-- header: "Parallelization"
-- question: "Enable parallel phase execution?"
+## [Next Category]
+...
+```
+
+**If no research:** Gather requirements through conversation instead.
+
+Ask: "What are the main things users need to be able to do?"
+
+For each capability mentioned:
+- Ask clarifying questions to make it specific
+- Probe for related capabilities
+- Group into categories
+
+**Scope each category:**
+
+For each category, use question:
+
+- header: "[Category name]"
+- question: "Which [category] features are in v1?"
+- multiSelect: true
+- options:
+  - "[Feature 1]" — [brief description]
+  - "[Feature 2]" — [brief description]
+  - "[Feature 3]" — [brief description]
+  - "None for v1" — Defer entire category
+
+Track responses:
+- Selected features → v1 requirements
+- Unselected table stakes → v2 (users expect these)
+- Unselected differentiators → out of scope
+
+**Identify gaps:**
+
+Use question:
+- header: "Additions"
+- question: "Any requirements research missed? (Features specific to your vision)"
 - options:
-  - "Enabled" — Run independent plans in parallel (Recommended)
-  - "Disabled" — Execute plans sequentially
+  - "No, research covered it" — Proceed
+  - "Yes, let me add some" — Capture additions
 
-**Parallelization** spawns multiple agents for independent plans within a phase. Wave-based execution handles dependencies automatically. Can be changed later in config.json.
+**Validate core value:**
 
-</step>
+Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
 
-<step name="config">
+**Generate REQUIREMENTS.md:**
 
-Create `.planning/config.json` with chosen mode, depth, and parallelization using `templates/config.json` structure.
+Create `.planning/REQUIREMENTS.md` with:
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (explicit exclusions with reasoning)
+- Traceability section (empty, filled by roadmap)
 
-</step>
+**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
 
-<step name="commit">
+**Requirement quality criteria:**
+
+Good requirements are:
+- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
+- **User-centric:** "User can X" (not "System does Y")
+- **Atomic:** One capability per requirement (not "User can login and manage profile")
+- **Independent:** Minimal dependencies on other requirements
+
+Reject vague requirements. Push for specificity:
+- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
+- "Support sharing" → "User can share post via link that opens in recipient's browser"
+
+**Present full requirements list:**
+
+Show every requirement (not counts) for user confirmation:
+
+```
+## v1 Requirements
+
+### Authentication
+- [ ] **AUTH-01**: User can create account with email/password
+- [ ] **AUTH-02**: User can log in and stay logged in across sessions
+- [ ] **AUTH-03**: User can log out from any page
+
+### Content
+- [ ] **CONT-01**: User can create posts with text
+- [ ] **CONT-02**: User can edit their own posts
+
+[... full list ...]
+
+---
+
+Does this capture what you're building? (yes / adjust)
+```
+
+If "adjust": Return to scoping.
+
+**Commit requirements:**
 
 ```bash
-git add .planning/PROJECT.md .planning/config.json
+git add .planning/REQUIREMENTS.md
 git commit -m "$(cat <<'EOF'
-docs: initialize [project-name]
+docs: define v1 requirements
 
-[One-liner from PROJECT.md]
-
-Creates PROJECT.md with requirements and constraints.
+[X] requirements across [N] categories
+[Y] requirements deferred to v2
 EOF
 )"
 ```
 
-</step>
+## Phase 8: Create Roadmap
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning roadmapper...
+```
+
+Spawn gsd-roadmapper agent with context:
+
+```
+Task(prompt="
+<planning_context>
+
+**Project:**
+@.planning/PROJECT.md
+
+**Requirements:**
+@.planning/REQUIREMENTS.md
+
+**Research (if exists):**
+@.planning/research/SUMMARY.md
+
+**Config:**
+@.planning/config.json
+
+</planning_context>
+
+<instructions>
+Create roadmap:
+1. Derive phases from requirements (don't impose structure)
+2. Map every v1 requirement to exactly one phase
+3. Derive 2-5 success criteria per phase (observable user behaviors)
+4. Validate 100% coverage
+5. write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+6. Return ROADMAP CREATED with summary
+
+write files first, then return. This ensures artifacts persist even if context is lost.
+</instructions>
+", subagent_type="gsd-roadmapper", description="Create roadmap")
+```
+
+**Handle roadmapper return:**
 
-<step name="done">
+**If `## ROADMAP BLOCKED`:**
+- Present blocker information
+- Work with user to resolve
+- Re-spawn when resolved
 
-Present completion with next steps (see ~/.config/opencode/get-shit-done/references/continuation-format.md):
+**If `## ROADMAP CREATED`:**
+
+read the created ROADMAP.md and present it nicely inline:
 
 ```
-Project initialized:
+---
+
+## Proposed Roadmap
 
-- Project: .planning/PROJECT.md
-- Config: .planning/config.json (mode: [chosen mode])
-[If .planning/codebase/ exists:] - Codebase: .planning/codebase/ (7 documents)
+**[N] phases** | **[X] requirements mapped** | All v1 requirements covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |
+| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
+...
+
+### Phase Details
+
+**Phase 1: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+3. [criterion]
+
+**Phase 2: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+
+[... continue for all phases ...]
 
 ---
+```
+
+**CRITICAL: Ask for approval before committing:**
+
+Use question:
+- header: "Roadmap"
+- question: "Does this roadmap structure work for you?"
+- options:
+  - "Approve" — Commit and continue
+  - "Adjust phases" — Tell me what to change
+  - "Review full file" — Show raw ROADMAP.md
+
+**If "Approve":** Continue to commit.
+
+**If "Adjust phases":**
+- Get user's adjustment notes
+- Re-spawn roadmapper with revision context:
+  ```
+  Task(prompt="
+  <revision>
+  User feedback on roadmap:
+  [user's notes]
+
+  Current ROADMAP.md: @.planning/ROADMAP.md
+
+  Update the roadmap based on feedback. edit files in place.
+  Return ROADMAP REVISED with changes made.
+  </revision>
+  ", subagent_type="gsd-roadmapper", description="Revise roadmap")
+  ```
+- Present revised roadmap
+- Loop until user approves
+
+**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
+
+**Commit roadmap (after approval):**
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+git commit -m "$(cat <<'EOF'
+docs: create roadmap ([N] phases)
+
+Phases:
+1. [phase-name]: [requirements covered]
+2. [phase-name]: [requirements covered]
+...
+
+All v1 requirements mapped to phases.
+EOF
+)"
+```
+
+## Phase 10: Done
+
+Present completion with next steps:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► PROJECT INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[Project Name]**
+
+| Artifact       | Location                    |
+|----------------|-----------------------------|
+| Project        | `.planning/PROJECT.md`      |
+| Config         | `.planning/config.json`     |
+| Research       | `.planning/research/`       |
+| Requirements   | `.planning/REQUIREMENTS.md` |
+| Roadmap        | `.planning/ROADMAP.md`      |
+
+**[N] phases** | **[X] requirements** | Ready to build ✓
+
+───────────────────────────────────────────────────────────────
 
 ## ▶ Next Up
 
-**[Project Name]** — create roadmap
+**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-`/gsd-create-roadmap`
+`/gsd-discuss-phase 1` — gather context and clarify approach
 
 *`/new` first → fresh context window*
 
 ---
-```
 
-</step>
+**Also available:**
+- `/gsd-plan-phase 1` — skip discussion, plan directly
+
+───────────────────────────────────────────────────────────────
+```
 
 </process>
 
@@ -320,16 +858,38 @@ Project initialized:
 
 - `.planning/PROJECT.md`
 - `.planning/config.json`
+- `.planning/research/` (if research selected)
+  - `STACK.md`
+  - `FEATURES.md`
+  - `ARCHITECTURE.md`
+  - `PITFALLS.md`
+  - `SUMMARY.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
 
 </output>
 
 <success_criteria>
 
-- [ ] Deep questioning completed (not rushed)
-- [ ] PROJECT.md captures full context with evolutionary structure
-- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
-- [ ] Key Decisions table initialized
-- [ ] config.json has workflow mode, depth, and parallelization
-- [ ] All committed to git
+- [ ] .planning/ directory created
+- [ ] Git repo initialized
+- [ ] Brownfield detection completed
+- [ ] Deep questioning completed (threads followed, not rushed)
+- [ ] PROJECT.md captures full context → **committed**
+- [ ] config.json has workflow mode, depth, parallelization → **committed**
+- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
+- [ ] Requirements gathered (from research or conversation)
+- [ ] User scoped each category (v1/v2/out of scope)
+- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
+- [ ] gsd-roadmapper spawned with context
+- [ ] Roadmap files written immediately (not draft)
+- [ ] User feedback incorporated (if any)
+- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
+- [ ] STATE.md initialized
+- [ ] REQUIREMENTS.md traceability updated
+- [ ] User knows next step is `/gsd-discuss-phase 1`
+
+**Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
 
 </success_criteria>