Retired system (July 2026). GSD, the methodology this artifact documents, was retired on 2026-07-06 in favor of a lighter unit of execution: a loop with a goal, a deterministic gate, an iteration budget, and a receipt. The /gsd:* commands no longer exist. This artifact stays published as a record of the system that built this site. The full story: Why I retired the system I documented.

GSD Complete Command Reference

GSD (Get Shit Done) transforms project execution into a systematic workflow optimized for solo development with Claude Code. The framework creates hierarchical plans, executes them with atomic commits, and tracks progress through persistent state files. Every command routes to the next logical action, eliminating the cognitive overhead of deciding what to do next.

The framework structures work into three tiers: Projects contain Milestones, which contain Phases, which contain Plans. Each level has its own commands for initialization, execution, and verification. This reference organizes commands by when they're used in the workflow.

Quick Start

The minimal path from idea to execution:

1. /gsd:new-project - Initialize project (research, requirements, roadmap)
2. /gsd:plan-phase 1 - Create detailed plan for first phase
3. /gsd:execute-phase 1 - Execute the phase

The framework handles everything between these steps: researching the domain, breaking work into actionable tasks, verifying deliverables, and routing to the next action.

Project Initialization

These commands establish the project foundation. They run once per project (or once per milestone for ongoing work).

/gsd:new-project

Initialize a new project through unified flow: questioning, research, requirements, roadmap.

This is the most leveraged moment in any project. Deep questioning here produces better plans, which produce better execution. One command takes raw idea to ready-for-planning.

What it creates:

• .planning/PROJECT.md - Project vision and context
• .planning/config.json - Workflow preferences (mode, depth, parallelization)
• .planning/research/ - Domain research (optional, 4 parallel researcher agents)
• .planning/REQUIREMENTS.md - Scoped requirements with REQ-IDs
• .planning/ROADMAP.md - Phase breakdown mapped to requirements
• .planning/STATE.md - Project memory across sessions

The questioning phase probes for what matters: What problem sparked this? What does success look like? What's explicitly out of scope? The framework follows threads rather than running through a checklist - each answer opens new threads to explore.

The research phase (optional) spawns four parallel researcher agents investigating stack, features, architecture, and pitfalls. The synthesis produces actionable guidance for the planning that follows.

Usage: /gsd:new-project

/gsd:map-codebase

Map an existing codebase for brownfield projects.

When initializing a project in an existing codebase, the framework needs to understand what already exists. This command spawns parallel Explore agents that analyze the codebase and produce seven focused documents covering stack, architecture, structure, conventions, testing, integrations, and concerns.

Run this before /gsd:new-project on existing codebases. The framework uses this context to avoid re-planning what already exists and to understand constraints the current architecture imposes.

What it creates:

• .planning/codebase/STACK.md - Languages, frameworks, dependencies
• .planning/codebase/ARCHITECTURE.md - Patterns, layers, data flow
• .planning/codebase/STRUCTURE.md - Directory layout, key files
• .planning/codebase/CONVENTIONS.md - Coding standards, naming patterns
• .planning/codebase/TESTING.md - Test setup, patterns, coverage
• .planning/codebase/INTEGRATIONS.md - External services, APIs
• .planning/codebase/CONCERNS.md - Tech debt, known issues

Usage: /gsd:map-codebase

/gsd:new-milestone

Start a new milestone through the same unified flow as new-project.

Milestones are the unit of shipped work. After completing and archiving a milestone, this command gathers context for the next cycle. It mirrors the new-project flow (questioning, research, requirements, roadmap) but builds on existing PROJECT.md rather than creating from scratch.

Phase numbering continues from where the previous milestone ended. If v1.0 finished at phase 5, v1.1 starts at phase 6.

Usage: /gsd:new-milestone "v2.0 Features"

Phase Planning

These commands prepare phases for execution. Planning produces PLAN.md files - executable prompts that specify exactly what to build, in what order, with what verification.

/gsd:discuss-phase

Capture your vision for a phase before planning begins.

Some phases benefit from conversation before structure. This command explores how you imagine the phase working, what's essential versus nice-to-have, what patterns you prefer. The output is a CONTEXT.md file that feeds into planning.

When to use: When you have specific ideas about implementation, UX, or constraints that wouldn't surface through standard planning.

Usage: /gsd:discuss-phase 2

/gsd:research-phase

Comprehensive ecosystem research for complex domains.

For phases touching specialized domains - 3D, games, audio, ML, blockchain - standard planning may miss ecosystem patterns and pitfalls. This command spawns a researcher agent that goes beyond "which library" to discover how experts build similar systems.

The output is a RESEARCH.md file with standard stack recommendations, architecture patterns, and specific gotchas to avoid. The planner consumes this research when creating execution plans.

Usage: /gsd:research-phase 3

/gsd:list-phase-assumptions

See what Claude intends to build before planning starts.

Claude makes assumptions based on requirements and context. This command surfaces those assumptions so you can course-correct before planning begins. No files created - purely conversational output.

When to use: Before /gsd:plan-phase when you want to verify Claude understood your intent.

Usage: /gsd:list-phase-assumptions 3

/gsd:plan-phase

Create detailed execution plans for a specific phase.

This is where phases become actionable. The command spawns a planner agent that breaks the phase goal into concrete tasks with verification criteria. Output is one or more PLAN.md files - executable prompts that the executor will follow.

Default flow: Research (if enabled) -> Plan -> Verify -> Done

The plan-checker agent validates that plans will actually achieve the phase goal. If issues are found, the planner revises (up to 3 iterations) until plans pass verification or the user overrides.

Flags:

• --research - Force re-research even if RESEARCH.md exists
• --skip-research - Skip research entirely
• --gaps - Gap closure mode (creates plans for gaps found by verifier)
• --skip-verify - Skip planner verification loop

Usage: /gsd:plan-phase 1

Result: Creates .planning/phases/01-foundation/01-01-PLAN.md

Execution

These commands do the actual work. Execution produces code, commits, and SUMMARY.md files documenting what was built.

/gsd:execute-phase

Execute all plans in a phase using wave-based parallel execution.

Plans within a phase can have dependencies. The executor groups plans by wave (from frontmatter) and executes waves sequentially - plans within each wave run in parallel via subagents. Each subagent gets fresh context for optimal quality.

What happens:

1. Discover incomplete plans (those without SUMMARY.md)
2. Group plans by wave
3. For each wave, spawn parallel executor agents
4. Each executor follows its PLAN.md, commits atomically per task
5. After all plans complete, spawn verifier to check phase goal
6. Update ROADMAP.md, STATE.md, REQUIREMENTS.md

Deviation handling: Executors automatically fix bugs, add missing critical functionality, and resolve blockers. Only architectural changes pause for user decision.

Usage: /gsd:execute-phase 5

/gsd:quick

Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.

Quick mode provides atomic commits and state tracking without the full research/verification cycle. Use when you know exactly what to do and the task is small enough that research would be overhead.

Quick tasks live in .planning/quick/ separate from planned phases. They update STATE.md but not ROADMAP.md.

What it does:

1. Spawn gsd-planner in quick mode (1-3 focused tasks)
2. Spawn gsd-executor
3. Update STATE.md "Quick Tasks Completed" table
4. Commit all artifacts

Usage: /gsd:quick

Result: Creates .planning/quick/NNN-slug/PLAN.md and SUMMARY.md

State Management

These commands help track progress and resume work across sessions.

/gsd:progress

Check project status and intelligently route to next action.

This command provides situational awareness: where you are, what you've done recently, what's next. It reads STATE.md, ROADMAP.md, and recent SUMMARY files to build context, then offers the logical next command.

What it shows:

• Visual progress bar and completion percentage
• Recent work summaries
• Current position (phase, plan, status)
• Key decisions and blockers
• Pending todos and active debug sessions
• Recommended next action

Routing logic: If unexecuted plans exist, offers /gsd:execute-phase. If phase needs planning, offers /gsd:plan-phase. If milestone complete, offers /gsd:complete-milestone.

Usage: /gsd:progress

/gsd:resume-work

Resume work from previous session with full context restoration.

Claude Code sessions are ephemeral. This command reconstructs where you were: current position, recent progress, pending decisions, and next actions. It reads STATE.md and offers appropriate continuation commands.

Usage: /gsd:resume-work

/gsd:pause-work

Create context handoff when pausing work mid-phase.

When stopping in the middle of a phase, this command captures current state in a .continue-here file and updates STATE.md. The next session can resume exactly where you stopped.

Usage: /gsd:pause-work

Verification

These commands validate that built features actually work and meet requirements.

/gsd:verify-work

Validate built features through conversational user acceptance testing.

This command extracts testable deliverables from SUMMARY.md files and presents them one at a time for manual verification. Simple yes/no responses - no interrogation. When issues are found, it spawns debug agents to diagnose root causes, then creates fix plans ready for execution.

Flow:

1. Find SUMMARY.md files for the phase
2. Extract testable deliverables
3. Present tests one at a time
4. Log results in UAT.md
5. If issues found: diagnose, create fix plans, verify plans
6. Offer /gsd:execute-phase with --gaps-only to run fixes

Usage: /gsd:verify-work 3

/gsd:audit-milestone

Audit milestone completion against original intent.

Before archiving a milestone, this command verifies that requirements were actually met. It reads all phase VERIFICATION.md files, checks requirements coverage, and spawns an integration checker for cross-phase wiring. Output is MILESTONE-AUDIT.md with gaps and tech debt.

Usage: /gsd:audit-milestone

/gsd:plan-milestone-gaps

Create phases to close gaps identified by audit.

When audit finds gaps, this command groups them into new phases, prioritizes by requirement priority, and adds them to ROADMAP.md. Then run /gsd:plan-phase on the new phases.

Usage: /gsd:plan-milestone-gaps

Debugging

These commands provide systematic debugging with persistent state.

/gsd:debug

Systematic debugging with persistent state across context resets.

Debugging burns context fast - reading files, forming hypotheses, testing fixes. This command spawns a debugger agent with fresh context while persisting state in .planning/debug/. If you run out of context, /clear and run /gsd:debug again to resume.

Flow:

1. Gather symptoms (expected, actual, errors, timeline, reproduction)
2. Spawn gsd-debugger agent
3. Agent investigates using scientific method
4. On root cause found: offer fix options
5. On checkpoint: present to user, spawn continuation

Usage:

• /gsd:debug "login button doesn't work" - Start new session
• /gsd:debug - Resume active session

Roadmap Management

These commands modify the phase structure within a milestone.

/gsd:add-phase

Add new phase to end of current milestone.

Sometimes scope expands. This command appends a new phase to ROADMAP.md with the next sequential number.

Usage: /gsd:add-phase "Add admin dashboard"

/gsd:insert-phase

Insert urgent work as decimal phase between existing phases.

When discovered work must happen mid-milestone, this command creates an intermediate phase. Phase 7.1 runs after phase 7 but before phase 8. Maintains ordering without renumbering.

Usage: /gsd:insert-phase 7 "Fix critical auth bug"

Result: Creates Phase 7.1

/gsd:remove-phase

Remove a future phase and renumber subsequent phases.

Only works on unstarted phases. Deletes the phase directory and all references, renumbers subsequent phases to close the gap. Git commit preserves historical record.

Usage: /gsd:remove-phase 17

Result: Phase 17 deleted, phases 18-20 become 17-19

Milestone Completion

These commands archive completed work and prepare for the next cycle.

/gsd:complete-milestone

Archive completed milestone and prepare for next version.

After all phases execute and verify, this command packages the milestone for archival. Creates MILESTONES.md entry with stats, archives full details to milestones/ directory, creates git tag, and prepares workspace for the next version.

Usage: /gsd:complete-milestone 1.0.0

Todo Management

These commands capture and process ideas outside the planned workflow.

/gsd:add-todo

Capture idea or task as todo from current conversation.

During work, ideas surface that don't fit the current task. This command extracts context from the conversation (or uses provided description), creates a structured todo file, and updates STATE.md. Duplicates are checked before creating.

Usage:

• /gsd:add-todo - Infer from conversation context
• /gsd:add-todo Add auth token refresh - Explicit description

/gsd:check-todos

List pending todos and select one to work on.

Reviews pending todos with title, area, and age. Optional area filter. Loads full context for selected todo and routes to appropriate action: work now, add to phase, or brainstorm further.

Usage:

• /gsd:check-todos - All pending
• /gsd:check-todos api - Filter by area

Configuration

These commands modify workflow behavior.

/gsd:settings

Configure workflow toggles and model profile interactively.

Toggle researcher, plan checker, and verifier agents on or off. Select model profile (quality/balanced/budget). Updates .planning/config.json.

Usage: /gsd:settings

/gsd:set-profile

Quick switch model profile for GSD agents.

• quality - Opus everywhere except verification (highest cost, deepest analysis)
• balanced - Opus for planning, Sonnet for execution (default, good quality/cost ratio)
• budget - Sonnet for writing, Haiku for research/verification (fastest, lowest cost)

Usage: /gsd:set-profile budget

Utility Commands

/gsd:help

Show this command reference.

/gsd:update

Update GSD to latest version with changelog preview.

Shows installed vs latest version, displays changelog for versions you've missed, highlights breaking changes, confirms before running install.

Usage: /gsd:update

/gsd:join-discord

Join the GSD Discord community for help, updates, and sharing what you're building.

Usage: /gsd:join-discord

File Structure

GSD creates and maintains this directory structure:

Workflow Modes

Set during /gsd:new-project, changeable in config.json:

Interactive Mode: Confirms each major decision, pauses at checkpoints for approval, more guidance throughout. Good for learning the framework or high-stakes projects.

YOLO Mode: Auto-approves most decisions, executes plans without confirmation, only stops for critical checkpoints. Good for experienced users or when velocity matters.

Common Workflows

Starting a new project

Resuming after a break

This shows where you left off and offers the next command.

Adding urgent mid-milestone work

Completing a milestone

Capturing ideas during work

Debugging an issue

Planning Configuration

Configure how planning artifacts are managed in .planning/config.json:

commit_docs (default: true)

• true: Planning artifacts committed to git
• false: Planning artifacts kept local-only

When commit_docs: false, add .planning/ to .gitignore. Useful for OSS contributions or client projects where planning should stay private.

search_gitignored (default: false)

• true: Include gitignored files in project-wide searches
• Only needed when .planning/ is gitignored and searches should include it

Getting Help

• Read .planning/PROJECT.md for project vision
• Read .planning/STATE.md for current context
• Check .planning/ROADMAP.md for phase status
• Run /gsd:progress to check where you are

The framework is designed to make the next action obvious. If you're unsure what to do, /gsd:progress will tell you.