GSD: Recommended Workflow
A step-by-step workflow for GSD projects — from initialization through milestones, phases, verification, and shipping. Updated as GSD evolves.
This is a living reference for how to run a GSD project. It reflects the current state of the tool as of v1.28. For background on how GSD works, see the original post. For what changed recently, see What’s New in GSD: March 2026.
The discussion phase is where you shape the approach — what gets built, how it behaves, which tradeoffs to make. That’s worth doing yourself. Planning and execution follow from those decisions. This workflow is designed around keeping you in control of the parts that matter.
Project setup
/gsd:new-project — One-time initialization. Answer the project questions, let GSD gather context, build requirements, and create the roadmap. This produces PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md — the foundation everything else builds on. For brownfield projects, GSD automatically offers to run /gsd:map-codebase first — four parallel agents that produce seven documents about your existing codebase (stack, architecture, conventions, etc.). You can also run it anytime to refresh GSD’s understanding.
Milestone
A milestone is a scoped set of work — v1.0, v1.1, a feature release. Your first milestone is created during project setup. For subsequent milestones, run /gsd:new-milestone — it updates PROJECT.md, gathers new requirements, and creates a fresh roadmap that continues phase numbering from where the last milestone left off.
Phases
Each milestone is broken into phases. This is where you spend most of your time.
1. Discuss — /gsd:discuss-phase 1 --analyze --batch. The --analyze flag gives you trade-off tables for each decision. --batch groups questions so you’re not answering one at a time. This is where your input matters most — shape the approach, then let the system run with it.
2. Check assumptions (optional) — /gsd:list-phase-assumptions 1. Surfaces what Claude thinks the plan will look like before committing to it.
3. UI contract (if the phase has frontend work) — /gsd:ui-phase 1. Locks visual decisions before planning starts. GSD recommends this automatically for UI-heavy phases.
4. Plan and execute — /gsd:plan-phase 1 then /gsd:execute-phase 1. Planning and execution follow from the decisions you made during discussion. Each phase gets automatic goal-backward verification during execution. After execution finishes, loop back to step 1 for the next phase. The old --auto flag on discuss-phase used to chain this entire pipeline for one phase (due to a bug), so you could walk away after discussing and come back at the next discussion. That chaining doesn’t have a single-command replacement yet — you advance between steps yourself.
5. Verify — /gsd:verify-work. Interactive UAT on top of the automatic verification that already ran during execution. Claude presents expected behaviors and you confirm or deny. Failures spawn debug agents automatically. You can also just tell Claude to run the checks autonomously — if it has browser access (via MCP or OS-level tools), it can navigate the app, test flows, and report back what passed or failed without you walking through each one.
6. UI review (if frontend phases) — /gsd:ui-review. This is not automatic — you run it manually after implementation to audit the frontend against the UI-SPEC.md contract. Scores each of six quality pillars from one to four.
7. Validate coverage — /gsd:validate-phase. Audits test coverage against requirements and generates missing tests. If you enabled Nyquist during setup, don’t skip this step — it’s not yet part of the automatic pipeline (details).
8. Ship (optional) — /gsd:ship. Creates a PR with an auto-generated body from planning artifacts. If you’re working on a personal project without PR requirements, just commit and push — ship is for PR-based workflows.
Complete the milestone
/gsd:audit-milestone — Verifies requirements coverage, cross-phase integration, and end-to-end flows before you close out. If it finds gaps, /gsd:plan-milestone-gaps creates phases to address them.
/gsd:complete-milestone — Archives the roadmap and requirements to .planning/milestones/, updates PROJECT.md, creates a git tag, and prepares for the next cycle. From here, /gsd:new-milestone starts the next one.
Between sessions
/gsd:pause-work — Creates a handoff file capturing your complete work state — current phase, what’s done, what’s remaining, decisions, and blockers. Commits as WIP. Use when you need to stop mid-phase.
/gsd:resume-work — Restores context from STATE.md and checkpoints, shows where things stand, and routes to the next action. Use when you come back the next day, switch machines, or start a fresh context window.
Settings
Most of the useful settings default to on: research, plan checking, verification, Nyquist validation, and UI phase support. Run /gsd:settings to review them — it presents each toggle with recommended defaults. The main decision is the model profile. balanced (Sonnet) is the default. quality (Opus) generally makes fewer mistakes and gets stuck less often. Switch with /gsd:set-profile quality.
Written with AI assistance. How that works →
Found this useful?
Get notified when I publish something new. No spam, unsubscribe anytime.