Overview
Thegsd:plan-phase command creates executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. It follows a default flow: Research (if needed) → Plan → Verify → Done.
Usage
Parameters
The phase number to plan. If omitted, auto-detects the next unplanned phase.
Automatic mode with minimal interaction.
Force re-research even if RESEARCH.md already exists for this phase.
Skip research entirely and go straight to planning.
Gap closure mode. Reads VERIFICATION.md and skips research. Use when addressing issues found during verification.
Skip the verification loop that checks plan quality.
Use a PRD or acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically and skips discuss-phase entirely.Example:
--prd requirements.mdHow It Works
The orchestrator manages the full workflow:- Parse Arguments - Validates flags and phase number
- Validate Phase - Ensures phase exists in ROADMAP.md
- Research Domain (unless skipped) - Gathers relevant domain knowledge
- Spawn gsd-planner - Specialized agent creates the plan
- Verify with gsd-plan-checker - Quality assurance loop
- Iterate - Continues until pass or max iterations reached
- Present Results - Shows final plan and next steps
The verification loop ensures plans are executable, complete, and aligned with project context.
Auto-Detection
When you run/gsd:plan-phase without a phase number:
Research Behavior
By default, the system intelligently decides whether research is needed:- Conducts research when domain knowledge would help
- Skips research for straightforward implementation tasks
- Reuses research if RESEARCH.md already exists
Use
--research to force fresh research, or --skip-research to bypass it entirely.Gap Closure Mode
When verification finds issues, use gap closure mode:- Reads VERIFICATION.md to understand what failed
- Skips research (issues are already understood)
- Creates targeted fix plans
PRD Mode
If you have a detailed PRD or acceptance criteria document:- Parses the PRD into CONTEXT.md automatically
- Skips the discuss-phase step entirely
- Proceeds directly to planning
Files Created
Executable phase plan with detailed tasks, dependencies, and implementation guidance
Domain research findings (created when research is conducted)
Implementation context (created when using —prd flag)
Examples
Plan Next Phase
Plan Specific Phase with Research
Fast Planning (No Verification)
Plan from PRD
Gap Closure
Workflow Gates
All workflow gates are preserved:- Validation - Phase must exist in ROADMAP.md
- Research - Domain knowledge gathering (when appropriate)
- Planning - Specialized gsd-planner agent execution
- Verification Loop - Quality checks until pass or max iterations
- Routing - Automatic next-step suggestions
Next Steps
After planning a phase, execute it:Allowed Tools
This command has access to:- Read - Read context and code files
- Write - Create plan files
- Bash - Execute shell commands
- Glob - Find files by pattern
- Grep - Search file contents
- Task - Spawn specialized agents (gsd-planner, gsd-plan-checker)
- WebFetch - Fetch web resources for research
- mcp__context7__* - Library documentation lookup