Gsd guide

GSD Guide — Quick Reference + Workflow Explainer

Combines the GSD tutorial/command reference (formerly gsd-onboard) with the per-command workflow explainer (formerly gsd-explain). Section 1 is the compact reference; Section 2 is the detailed "what will this do before I run it" explainer.

---

Section 1 — Quick Reference

GSD = question → research → plan → execute → verify.

Files

.planning/
├── PROJECT.md       # Vision, decisions
├── REQUIREMENTS.md  # REQ-IDs
├── ROADMAP.md       # Phases
├── STATE.md         # Current position
├── config.json      # Settings
├── phases/NN-name/  # Plans + summaries
└── milestones/      # Archives

Commands

Command	Purpose
/gsd:new-project	Init project
/gsd:new-milestone	New version
/gsd:progress	State + next action
/gsd:discuss-phase N	Gather context
/gsd:plan-phase N	Create plans
/gsd:execute-phase N	Build plans
/gsd:quick	Small tasks
/gsd:verify-work N	Test deliverables
/gsd:audit-milestone	Completion check
/gsd:complete-milestone	Archive
/gsd:debug	Debug with state
/gsd:pause-work	Checkpoint
/gsd:resume-work	Restore

Workflow

plan-phase N → /clear → execute-phase N → verify-work N

Concepts

• Atomic commits: One per plan, surgical rollback
• Fresh context: /clear + STATE.md
• Wave execution: Parallel independent plans
• Modes: yolo (auto) or interactive

---

Section 2 — Detailed Explanations

Helps users understand what a GSD command will do before they run it, reducing hesitation and preventing incorrect usage.

When to Use

Activate when the user:

• Asks "what does /gsd:plan-phase do?"
• Wants to preview changes before running a command
• Is learning GSD and needs explanations
• Mentions wanting to understand a workflow

What This Skill Does

1. Reads the workflow file from .claude/get-shit-done/workflows/
2. Parses the workflow structure (trigger, purpose, process steps)
3. Explains in plain language what will happen
4. Shows file previews (what files will be created/modified)
5. Estimates resources (time, context usage, user prompts)

Explanation Template

When explaining a GSD workflow, use this structure:

## /gsd:command-name - [Purpose]

**What it does:**
[2-3 sentence overview]

**Process:**
1. [First step - what happens]
2. [Second step - what happens]
3. [Third step - what happens]

**Files created/modified:**
- `.planning/path/to/file.md` - [purpose]
- `.planning/other/file.json` - [purpose]

**Agents spawned:**
- `agent-name` (model) - [what it does]

**User interaction:**
- [Number] prompts expected
- [Type of input needed]

**Estimated:**
- Time: [duration estimate]
- Context: [percentage of window]

**After completion:**
- [What state the project will be in]
- [Next recommended command]

Key Workflows to Explain

Initialization Workflows

/gsd:new-project

• Spawns 4 parallel researchers (stack, features, architecture, pitfalls)
• Creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md
• Estimates: 15-30 minutes, high context usage
• User prompts: 10-15 questioning rounds

/gsd:new-milestone

• Updates PROJECT.md with new milestone context
• Creates new REQUIREMENTS.md for milestone scope
• Routes to roadmap creation
• Estimates: 5-10 minutes
• User prompts: 5-8 for requirements

Planning Workflows

/gsd:discuss-phase N

• Gathers user vision for phase before planning
• Creates .planning/phases/NN-name/NN-CONTEXT.md
• No agents spawned (direct conversation)
• Estimates: 3-5 minutes
• User prompts: 5-10 contextual questions

/gsd:plan-phase N

• Optionally spawns gsd-phase-researcher (if enabled)
• Spawns gsd-planner to create PLAN.md files
• Spawns gsd-plan-checker to verify plans
• Creates multiple plan files (NN-01-PLAN.md, NN-02-PLAN.md, …)
• Estimates: 3-8 minutes
• User prompts: 0-2 (only if plan checker finds issues)

/gsd:research-phase N

• Spawns gsd-phase-researcher standalone
• Creates NN-RESEARCH.md with findings
• WebSearch intensive
• Estimates: 5-10 minutes
• User prompts: 0

Execution Workflows

/gsd:execute-phase N

• Spawns gsd-executor agents (1 per wave)
• Executes all plans in phase with parallelization
• Creates NN-NN-SUMMARY.md for each plan
• Atomic commits per plan
• Estimates: Varies widely by plan complexity
• User prompts: 0 in YOLO mode, varies in interactive mode

/gsd:quick

• Lightweight execution without full planning
• Single gsd-executor agent
• Creates STATE.md entry
• Atomic commit
• Estimates: 2-5 minutes
• User prompts: 0

Validation Workflows

/gsd:verify-work N

• Spawns gsd-verifier agent
• UAT-style testing of phase deliverables
• Creates VERIFICATION.md report
• Estimates: 3-7 minutes
• User prompts: Multiple (testing scenarios)

/gsd:audit-milestone

• Spawns gsd-verifier and gsd-integration-checker
• Comprehensive completion check
• Creates MILESTONE-AUDIT.md
• Estimates: 5-10 minutes
• User prompts: 0

File Structure Reference

Help users visualize what files GSD creates:

.planning/
├── PROJECT.md           # Vision, requirements, decisions
├── REQUIREMENTS.md      # What we're building (REQ-IDs)
├── ROADMAP.md           # Phase structure and status
├── STATE.md             # Session memory, current position
├── config.json          # Workflow preferences
│
├── phases/
│   ├── 01-foundation/
│   │   ├── 01-CONTEXT.md      # User vision for phase
│   │   ├── 01-RESEARCH.md     # Optional research findings
│   │   ├── 01-01-PLAN.md      # Executable plan
│   │   └── 01-01-SUMMARY.md   # What was built
│   │
│   └── 02-features/
│       └── [same structure]
│
└── milestones/
    └── v1.0-ROADMAP.md        # Archived completed milestones

Agent Type Reference

Agent Type	Purpose	Spawned By
gsd-project-researcher	Research domain before roadmap	/gsd:new-project
gsd-research-synthesizer	Synthesize parallel research	/gsd:new-project
gsd-roadmapper	Create project roadmap	/gsd:new-project
gsd-phase-researcher	Research implementation approach	/gsd:plan-phase, /gsd:research-phase
gsd-planner	Create executable plans	/gsd:plan-phase
gsd-plan-checker	Verify plans match goals	/gsd:plan-phase
gsd-executor	Execute plans with atomic commits	/gsd:execute-phase, /gsd:quick
gsd-verifier	Test phase deliverables	/gsd:verify-work
gsd-debugger	Systematic debugging	/gsd:debug
gsd-integration-checker	Cross-phase integration tests	/gsd:audit-milestone

Common User Questions

"How long will this take?" — Initialization: 15-30 minutes. Planning a phase: 3-8 minutes. Executing a phase: 5-40 minutes depending on complexity. Verification: 3-7 minutes.

"Will this modify my code?" — Planning workflows only create .planning/ files. Execution workflows modify code with atomic commits. Verification workflows are read-only.

"Can I undo this?" — All GSD commits are atomic (one per plan). Use git revert <commit> to undo specific plans. STATE.md tracks what was done.

"What happens if I /clear mid-workflow?" — GSD writes .continue-here.md files at checkpoints. /gsd:resume-work or /gsd:progress restores context. STATE.md maintains session continuity.

Example Explanation

User asks: "What does /gsd:plan-phase 3 do?"

## /gsd:plan-phase 3 - Create Executable Plans for Phase 3

**What it does:**
Reads Phase 3 from your ROADMAP.md and creates detailed, executable
PLAN.md files that break the phase goal into atomic tasks with
verification criteria.

**Process:**
1. Reads Phase 3 details from .planning/ROADMAP.md
2. Checks for .planning/phases/03-name/03-CONTEXT.md (optional)
3. Spawns gsd-phase-researcher if research enabled in config
4. Spawns gsd-planner to create PLAN.md files
5. Spawns gsd-plan-checker to verify plans achieve phase goal
6. Commits plans to git

**Files created:**
- `.planning/phases/03-name/03-RESEARCH.md` (if research enabled)
- `.planning/phases/03-name/03-01-PLAN.md` (first plan)
- `.planning/phases/03-name/03-02-PLAN.md` (additional plans)

**Agents spawned:**
- gsd-phase-researcher (Opus) - Optional, researches implementation
- gsd-planner (Opus/Sonnet) - Creates executable plans
- gsd-plan-checker (Opus) - Verifies plans match phase goals

**User interaction:**
- 0-2 prompts (only if plan checker finds issues)

**Estimated:**
- Time: 3-8 minutes (longer if research enabled)
- Context: ~30-40% of window

**After completion:**
- Phase 3 plans ready in .planning/phases/03-name/
- Ready to run /gsd:execute-phase 3

Tips for Better Explanations

1. Use plain language — avoid jargon, explain technical terms.
2. Show file paths — help users visualize what's created.
3. Estimate honestly — base estimates on actual workflow complexity.
4. Mention alternatives — if there's another way, mention it.
5. Link to next steps — what command typically follows?

Integration with GSD

This skill complements GSD by reducing onboarding friction, providing "what if" previews before running commands, explaining GSD's internal agent orchestration, and helping users choose the right workflow. It does not replace GSD — users still run the actual commands, no workflow logic is duplicated, and this is purely educational.