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 /home/foxy/.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