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. One command takes you from idea to ready-for-planning.

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>

@.codex/get-shit-done/references/questioning.md @.codex/get-shit-done/references/ui-brand.md @.codex/get-shit-done/templates/project.md @.codex/get-shit-done/templates/requirements.md

</execution_context>

Phase 1: Setup

MANDATORY FIRST STEP — Execute these checks before ANY user interaction:

•

Abort if project exists:

bash

[ -f .planning/PROJECT.md ] && echo "ERROR: Project already initialized. Use $gsd-progress" && exit 1

•

Initialize git repo in THIS directory (required even if inside a parent repo):

bash

if [ -d .git ] || [ -f .git ]; then
    echo "Git repo exists in current directory"
else
    git init
    echo "Initialized new git repo"
fi

•

Detect existing code (brownfield detection):

bash

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")

You MUST run all bash commands above using the Bash tool before proceeding.

Phase 2: Brownfield Offer

If existing code detected and .planning/codebase/ doesn't exist:

Check the results from setup step:

•If CODE_FILES is non-empty OR HAS_PACKAGE is "yes"
•AND HAS_CODEBASE_MAP is NOT "yes"

Use AskUserQuestion:

•header: "Existing Code"
•question: "I detected existing code in this directory. Would you like to map the codebase first?"
•
options:
- •"Map codebase first" — Run $gsd-map-codebase to understand existing architecture (Recommended)
- •"Skip mapping" — Proceed with project initialization

If "Map codebase first":

code

Run `$gsd-map-codebase` first, then return to `$gsd-new-project`

Exit command.

If "Skip mapping": Continue to Phase 3.

If no existing code detected OR codebase already mapped: Continue to Phase 3.

Phase 3: Deep Questioning

Display stage banner:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► QUESTIONING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Open the conversation:

Ask inline (freeform, NOT AskUserQuestion):

"What do you want to build?"

Wait for their response. This gives you the context needed to ask intelligent follow-up questions.

Follow the thread:

Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.

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

Consult questioning.md for techniques:

•Challenge vagueness
•Make abstract concrete
•Surface assumptions
•Find edges
•Reveal motivation

Check context (background, not out loud):

As you go, mentally check the context checklist from questioning.md. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.

Decision gate:

When you could write a clear PROJECT.md, use AskUserQuestion:

•header: "Ready?"
•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.

Loop until "Create PROJECT.md" selected.

Phase 4: Write PROJECT.md

Synthesize all context into .planning/PROJECT.md using the template from templates/project.md.

For greenfield projects:

Initialize requirements as hypotheses:

markdown

## Requirements

### Validated

(None yet — ship to validate)

### Active

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]

### Out of Scope

- [Exclusion 1] — [why]
- [Exclusion 2] — [why]

All Active requirements are hypotheses until shipped and validated.

For brownfield projects (codebase map exists):

Infer Validated requirements from existing code:

•Read .planning/codebase/ARCHITECTURE.md and STACK.md
•Identify what the codebase already does
•These become the initial Validated set

markdown

## Requirements

### Validated

- ✓ [Existing capability 1] — existing
- ✓ [Existing capability 2] — existing
- ✓ [Existing capability 3] — existing

### Active

- [ ] [New requirement 1]
- [ ] [New requirement 2]

### Out of Scope

- [Exclusion 1] — [why]

Key Decisions:

Initialize with any decisions made during questioning:

markdown

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Choice from questioning] | [Why] | — Pending |

Last updated footer:

markdown

---
*Last updated: [date] after initialization*

Do not compress. Capture everything gathered.

Commit PROJECT.md:

bash

mkdir -p .planning
git add .planning/PROJECT.md
git commit -m "$(cat <<'EOF'
docs: initialize project

[One-liner from PROJECT.md What This Is section]
EOF
)"

Phase 5: Workflow Preferences

Ask all workflow preferences in a single AskUserQuestion call (3 questions):

code

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" }
    ]
  }
]

Create .planning/config.json with chosen mode, depth, and parallelization.

Commit config.json:

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 5.5: Git Identity Configuration

Goal: Ensure git identity is configured before agents make commits.

Check if git is already configured:

bash

GIT_NAME=$(git config user.name 2>/dev/null)
GIT_EMAIL=$(git config user.email 2>/dev/null)

if [ -n "$GIT_NAME" ] && [ -n "$GIT_EMAIL" ]; then
    echo "Git identity already configured:"
    echo "  Name: $GIT_NAME"
    echo "  Email: $GIT_EMAIL"
    
    # Store source in config.json
    python3 << PYTHON
import json
import os

git_name = os.environ.get('GIT_NAME', '')
git_email = os.environ.get('GIT_EMAIL', '')

with open('.planning/config.json', 'r') as f:
    config = json.load(f)

config['git'] = {
    'author': {
        'name': git_name,
        'email': git_email
    },
    'source': 'global'
}

with open('.planning/config.json', 'w') as f:
    json.dump(config, f, indent=2)
PYTHON
    
    # Continue to next phase
fi

If not configured, use AskUserQuestion:

yaml

header: "Git Identity Configuration"
question: |
  Git user information is needed for commit attribution. Automated agents 
  (like gsd-executor) will commit using this identity.
  
  How would you like to proceed?
options:
  - id: configure-global
    label: "Configure git globally (recommended)"
    description: "I'll set it in git config for all repositories"
  - id: project-only
    label: "Store in this project only"
    description: "Keep identity in .planning/config.json for this project"
  - id: already-done
    label: "I already configured it"
    description: "Skip this step and verify configuration"

If "configure-global" selected:

bash

echo "Please configure git globally by running:"
echo ""
echo "  git config --global user.name \"Your Name\""
echo "  git config --global user.email \"you@example.com\""
echo ""
echo "After running these commands, type 'done' to continue."

# Wait for user confirmation (via AskUserQuestion)
# Then re-check git config and store source as "global"

GIT_NAME=$(git config user.name 2>/dev/null)
GIT_EMAIL=$(git config user.email 2>/dev/null)

if [ -z "$GIT_NAME" ] || [ -z "$GIT_EMAIL" ]; then
    echo "ERROR: Git config not detected. Please try again."
    # Loop back to question
else
    # Store in config.json
    python3 << PYTHON
import json
import os

git_name = os.environ.get('GIT_NAME', '')
git_email = os.environ.get('GIT_EMAIL', '')

with open('.planning/config.json', 'r') as f:
    config = json.load(f)

config['git'] = {
    'author': {
        'name': git_name,
        'email': git_email
    },
    'source': 'global'
}

with open('.planning/config.json', 'w') as f:
    json.dump(config, f, indent=2)
PYTHON
fi

If "project-only" selected:

yaml

# Ask for name
header: "Git Author Name"
question: "Enter your full name for git commits:"
input_type: freeform

# Ask for email
header: "Git Author Email"
question: "Enter your email for git commits:"
input_type: freeform

# Validate and store

bash

# After receiving inputs (USER_NAME, USER_EMAIL)
# Validate email contains @
if [[ ! "$USER_EMAIL" =~ "@" ]]; then
    echo "ERROR: Invalid email format (must contain @)"
    # Loop back
fi

# Store in config.json
python3 << PYTHON
import json
import os

user_name = os.environ.get('USER_NAME', '')
user_email = os.environ.get('USER_EMAIL', '')

with open('.planning/config.json', 'r') as f:
    config = json.load(f)

config['git'] = {
    'author': {
        'name': user_name,
        'email': user_email
    },
    'source': 'config'
}

with open('.planning/config.json', 'w') as f:
    json.dump(config, f, indent=2)
PYTHON

echo "Git identity stored in .planning/config.json"

If "already-done" selected:

bash

# Verify git config returns values
GIT_NAME=$(git config user.name 2>/dev/null)
GIT_EMAIL=$(git config user.email 2>/dev/null)

if [ -z "$GIT_NAME" ] || [ -z "$GIT_EMAIL" ]; then
    echo "ERROR: Git identity not found. Please configure it first."
    # Loop back to question
else
    echo "Git identity verified."
    # Store source as "global"
    python3 << PYTHON
import json
import os

git_name = os.environ.get('GIT_NAME', '')
git_email = os.environ.get('GIT_EMAIL', '')

with open('.planning/config.json', 'r') as f:
    config = json.load(f)

config['git'] = {
    'author': {
        'name': git_name,
        'email': git_email
    },
    'source': 'global'
}

with open('.planning/config.json', 'w') as f:
    json.dump(config, f, indent=2)
PYTHON
fi

Success criteria for Phase 5.5:

• Git identity exists in git config OR .planning/config.json
• Identity includes valid name (non-empty) and email (contains @)
• Source recorded in config.json ("global", "config", or "local")

Phase 6: Research Decision

Use AskUserQuestion:

•header: "Research"
•question: "Research the domain ecosystem before defining requirements?"
•
options:
- •"Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
- •"Skip research" — I know this domain well, go straight to requirements

If "Research first":

Display stage banner:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Researching [domain] ecosystem...

Create research directory:

bash

mkdir -p .planning/research

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:

code

◆ Spawning 4 researchers in parallel...
  → Stack research
  → Features research
  → Architecture research
  → Pitfalls research

Spawn 4 parallel gsd-project-researcher agents with rich context:

code

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: .codex/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: .codex/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: .codex/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: .codex/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:

code

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: .codex/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:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 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:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 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:

code

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]

---

## [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 AskUserQuestion:

•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 AskUserQuestion:

•header: "Additions"
•question: "Any requirements research missed? (Features specific to your vision)"
•
options:
- •"No, research covered it" — Proceed
- •"Yes, let me add some" — Capture additions

Validate core value:

Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.

Generate REQUIREMENTS.md:

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)

REQ-ID format: [CATEGORY]-[NUMBER] (AUTH-01, CONTENT-02)

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:

code

## 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/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'
docs: define v1 requirements

[X] requirements across [N] categories
[Y] requirements deferred to v2
EOF
)"

Phase 8: Create Roadmap

Display stage banner:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► CREATING ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Spawning roadmapper...

Spawn gsd-roadmapper agent with context:

code

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:

If ## ROADMAP BLOCKED:

•Present blocker information
•Work with user to resolve
•Re-spawn when resolved

If ## ROADMAP CREATED:

Read the created ROADMAP.md and present it nicely inline:

code

---

## Proposed Roadmap

**[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 AskUserQuestion:

•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:

code

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:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 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

**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]

`$gsd-discuss-phase 1` — gather context and clarify approach

<sub>`/clear` first → fresh context window</sub>

---

**Also available:**
- `$gsd-plan-phase 1` — skip discussion, plan directly

───────────────────────────────────────────────────────────────

</process> <output>

•.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>

Atomic commits: Each phase commits its artifacts immediately. If context is lost, artifacts persist.

</success_criteria>