Questions — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
Research — Spawns parallel agents to investigate the domain (optional but recommended)
Requirements — Extracts what’s v1, v2, and out of scope
Roadmap — Creates phases mapped to requirements
You approve the roadmap. Now you’re ready to build.
Already have code? Run /gsd:map-codebase first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then /gsd:new-project knows your codebase — questions focus on what you’re adding, and planning automatically loads your patterns.
Creates:
PROJECT.md — Project vision and context
REQUIREMENTS.md — Scoped v1/v2 requirements with IDs
This is where you shape the implementation.Your roadmap has a sentence or two per phase. That’s not enough context to build something the way you imagine it. This step captures your preferences before anything gets researched or planned.The system analyzes the phase and identifies gray areas based on what’s being built:
Visual features
Layout, density, interactions, empty states
APIs/CLIs
Response format, flags, error handling, verbosity
Content systems
Structure, tone, depth, flow
Organization tasks
Grouping criteria, naming, duplicates, exceptions
For each area you select, it asks until you’re satisfied. The output — CONTEXT.md — feeds directly into the next two steps:
Researcher reads it — Knows what patterns to investigate (“user wants card layout” → research card component libraries)
Planner reads it — Knows what decisions are locked (“infinite scroll decided” → plan includes scroll handling)
The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get your vision.
During plan-phase research, GSD maps automated test coverage to each phase requirement before any code is written. This ensures that when Claude’s executor commits a task, a feedback mechanism already exists to verify it within seconds.The researcher:
Detects your existing test infrastructure
Maps each requirement to a specific test command
Identifies any test scaffolding that must be created before implementation begins (Wave 0 tasks)
The plan-checker enforces this as an 8th verification dimension: plans where tasks lack automated verify commands will not be approved.
Output:{phase}-VALIDATION.md — the feedback contract for the phase.
Disable with workflow.nyquist_validation: false in /gsd:settings for rapid prototyping phases where test infrastructure isn’t the focus.
Creates:
{phase_num}-RESEARCH.md — Domain research findings
This is where you confirm it actually works.Automated verification checks that code exists and tests pass. But does the feature work the way you expected? This is your chance to use it.The system:
Extracts testable deliverables — What you should be able to do now
Walks you through one at a time — “Can you log in with email?” Yes/no, or describe what’s wrong
Creates verified fix plans — Ready for immediate re-execution
If everything passes, you move on. If something’s broken, you don’t manually debug — you just run /gsd:execute-phase again with the fix plans it created.
Manual user acceptance testing (UAT) was contributed by reddit user OracleGreyBeard.
Creates:{phase_num}-UAT.md, fix plans if issues found
Loop discuss → plan → execute → verify until milestone complete.Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.When all phases are done, /gsd:complete-milestone archives the milestone and tags the release.Then /gsd:new-milestone starts the next version — same flow as new-project but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
Planner creates plans, checker verifies, loop until pass
Execution
Groups into waves, tracks progress
Executors implement in parallel, each with fresh 200k context
Verification
Presents results, routes next
Verifier checks codebase against goals, debuggers diagnose failures
The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
The result: You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
