From 7de17fca8a97f9a4eae87cbb5beaae5df5620df8 Mon Sep 17 00:00:00 2001 From: Pablo Alonso Date: Mon, 9 Feb 2026 14:12:35 +0100 Subject: [PATCH] docs: add User Guide with workflow diagrams, troubleshooting, and config reference Create docs/USER-GUIDE.md as a detailed companion to the README, covering: - Workflow diagrams (project lifecycle, planning coordination, execution waves, brownfield) - Command reference with "When to Use" guidance for each command - Full config.json schema including workflow toggles, git branching, and per-agent model profiles - Practical usage examples for common scenarios - Troubleshooting section for common issues - Recovery quick reference table Add link from README navigation bar and Configuration section to the User Guide. Closes #457 Co-Authored-By: Claude Opus 4.6 --- README.md | 4 +- docs/USER-GUIDE.md | 451 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 453 insertions(+), 2 deletions(-) create mode 100644 docs/USER-GUIDE.md diff --git a/README.md b/README.md index 7f3c4bb4f..f6eb97130 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ npx get-shit-done-cc@latest **Trusted by engineers at Amazon, Google, Shopify, and Webflow.** -[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) +[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works) · [User Guide](docs/USER-GUIDE.md) @@ -479,7 +479,7 @@ You're never locked in. The system adapts. ## Configuration -GSD stores project settings in `.planning/config.json`. Configure during `/gsd:new-project` or update later with `/gsd:settings`. +GSD stores project settings in `.planning/config.json`. Configure during `/gsd:new-project` or update later with `/gsd:settings`. For the full config schema, workflow toggles, git branching options, and per-agent model breakdown, see the [User Guide](docs/USER-GUIDE.md#configuration-reference). ### Core Settings diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md new file mode 100644 index 000000000..2352623c2 --- /dev/null +++ b/docs/USER-GUIDE.md @@ -0,0 +1,451 @@ +# GSD User Guide + +A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the [README](../README.md). + +--- + +## Table of Contents + +- [Workflow Diagrams](#workflow-diagrams) +- [Command Reference](#command-reference) +- [Configuration Reference](#configuration-reference) +- [Usage Examples](#usage-examples) +- [Troubleshooting](#troubleshooting) +- [Recovery Quick Reference](#recovery-quick-reference) + +--- + +## Workflow Diagrams + +### Full Project Lifecycle + +``` + ┌──────────────────────────────────────────────────┐ + │ NEW PROJECT │ + │ /gsd:new-project │ + │ Questions -> Research -> Requirements -> Roadmap│ + └─────────────────────────┬────────────────────────┘ + │ + ┌──────────────▼─────────────┐ + │ FOR EACH PHASE: │ + │ │ + │ ┌────────────────────┐ │ + │ │ /gsd:discuss-phase │ │ <- Lock in preferences + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd:plan-phase │ │ <- Research + Plan + Verify + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd:execute-phase │ │ <- Parallel execution + │ └──────────┬─────────┘ │ + │ │ │ + │ ┌──────────▼─────────┐ │ + │ │ /gsd:verify-work │ │ <- Manual UAT + │ └──────────┬─────────┘ │ + │ │ │ + │ Next Phase?────────────┘ + │ │ No + └─────────────┼──────────────┘ + │ + ┌───────────────▼──────────────┐ + │ /gsd:audit-milestone │ + │ /gsd:complete-milestone │ + └───────────────┬──────────────┘ + │ + Another milestone? + │ │ + Yes No -> Done! + │ + ┌───────▼──────────────┐ + │ /gsd:new-milestone │ + └──────────────────────┘ +``` + +### Planning Agent Coordination + +``` + /gsd:plan-phase N + │ + ├── Phase Researcher (x4 parallel) + │ ├── Stack researcher + │ ├── Features researcher + │ ├── Architecture researcher + │ └── Pitfalls researcher + │ │ + │ ┌──────▼──────┐ + │ │ RESEARCH.md │ + │ └──────┬──────┘ + │ │ + │ ┌──────▼──────┐ + │ │ Planner │ <- Reads PROJECT.md, REQUIREMENTS.md, + │ │ │ CONTEXT.md, RESEARCH.md + │ └──────┬──────┘ + │ │ + │ ┌──────▼───────────┐ ┌────────┐ + │ │ Plan Checker │────>│ PASS? │ + │ └──────────────────┘ └───┬────┘ + │ │ + │ Yes │ No + │ │ │ │ + │ │ └───┘ (loop, up to 3x) + │ │ + │ ┌─────▼──────┐ + │ │ PLAN files │ + │ └────────────┘ + └── Done +``` + +### Execution Wave Coordination + +``` + /gsd:execute-phase N + │ + ├── Analyze plan dependencies + │ + ├── Wave 1 (independent plans): + │ ├── Executor A (fresh 200K context) -> commit + │ └── Executor B (fresh 200K context) -> commit + │ + ├── Wave 2 (depends on Wave 1): + │ └── Executor C (fresh 200K context) -> commit + │ + └── Verifier + └── Check codebase against phase goals + │ + ├── PASS -> VERIFICATION.md (success) + └── FAIL -> Issues logged for /gsd:verify-work +``` + +### Brownfield Workflow (Existing Codebase) + +``` + /gsd:map-codebase + │ + ├── Stack Mapper -> codebase/STACK.md + ├── Arch Mapper -> codebase/ARCHITECTURE.md + ├── Convention Mapper -> codebase/CONVENTIONS.md + └── Concern Mapper -> codebase/CONCERNS.md + │ + ┌───────▼──────────┐ + │ /gsd:new-project │ <- Questions focus on what you're ADDING + └──────────────────┘ +``` + +--- + +## Command Reference + +### Core Workflow + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd:new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project | +| `/gsd:new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready | +| `/gsd:discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built | +| `/gsd:plan-phase [N]` | Research + plan + verify | Before executing a phase | +| `/gsd:execute-phase ` | Execute all plans in parallel waves | After planning is complete | +| `/gsd:verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes | +| `/gsd:audit-milestone` | Verify milestone met its definition of done | Before completing milestone | +| `/gsd:complete-milestone` | Archive milestone, tag release | All phases verified | +| `/gsd:new-milestone [name]` | Start next version cycle | After completing a milestone | + +### Navigation + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd:progress` | Show status and next steps | Anytime -- "where am I?" | +| `/gsd:resume-work` | Restore full context from last session | Starting a new session | +| `/gsd:pause-work` | Save context handoff | Stopping mid-phase | +| `/gsd:help` | Show all commands | Quick reference | +| `/gsd:update` | Update GSD with changelog preview | Check for new versions | +| `/gsd:join-discord` | Open Discord community invite | Questions or community | + +### Phase Management + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd:add-phase` | Append new phase to roadmap | Scope grows after initial planning | +| `/gsd:insert-phase [N]` | Insert urgent work (decimal numbering) | Urgent fix mid-milestone | +| `/gsd:remove-phase [N]` | Remove future phase and renumber | Descoping a feature | +| `/gsd:list-phase-assumptions [N]` | Preview Claude's intended approach | Before planning, to validate direction | +| `/gsd:plan-milestone-gaps` | Create phases for audit gaps | After audit finds missing items | +| `/gsd:research-phase [N]` | Deep ecosystem research only | Complex or unfamiliar domain | + +### Brownfield & Utilities + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/gsd:map-codebase` | Analyze existing codebase | Before `/gsd:new-project` on existing code | +| `/gsd:quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes | +| `/gsd:debug [desc]` | Systematic debugging with persistent state | When something breaks | +| `/gsd:add-todo [desc]` | Capture an idea for later | Think of something during a session | +| `/gsd:check-todos` | List pending todos | Review captured ideas | +| `/gsd:settings` | Configure workflow toggles and model profile | Change model, toggle agents | +| `/gsd:set-profile ` | Quick profile switch | Change cost/quality tradeoff | +| `/gsd:reapply-patches` | Restore local modifications after update | After `/gsd:update` if you had local edits | + +--- + +## Configuration Reference + +GSD stores project settings in `.planning/config.json`. Configure during `/gsd:new-project` or update later with `/gsd:settings`. + +### Full config.json Schema + +```json +{ + "mode": "interactive", + "depth": "standard", + "model_profile": "balanced", + "planning": { + "commit_docs": true, + "search_gitignored": false + }, + "workflow": { + "research": true, + "plan_check": true, + "verifier": true + }, + "git": { + "branching_strategy": "none", + "phase_branch_template": "gsd/phase-{phase}-{slug}", + "milestone_branch_template": "gsd/{milestone}-{slug}" + } +} +``` + +### Core Settings + +| Setting | Options | Default | What it Controls | +|---------|---------|---------|------------------| +| `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | +| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness: 3-5, 5-8, or 8-12 phases | +| `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Model tier for each agent (see table below) | + +### Planning Settings + +| Setting | Options | Default | What it Controls | +|---------|---------|---------|------------------| +| `planning.commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git | +| `planning.search_gitignored` | `true`, `false` | `false` | Add `--no-ignore` to broad searches to include `.planning/` | + +> **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value. + +### Workflow Toggles + +| Setting | Options | Default | What it Controls | +|---------|---------|---------|------------------| +| `workflow.research` | `true`, `false` | `true` | Domain investigation before planning | +| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) | +| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals | + +Disable these to speed up phases in familiar domains or when conserving tokens. + +### Git Branching + +| Setting | Options | Default | What it Controls | +|---------|---------|---------|------------------| +| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created | +| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy | +| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy | + +**Branching strategies explained:** + +| Strategy | Creates Branch | Scope | Best For | +|----------|---------------|-------|----------| +| `none` | Never | N/A | Solo development, simple projects | +| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback | +| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version | + +**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"). + +### Model Profiles (Per-Agent Breakdown) + +| Agent | `quality` | `balanced` | `budget` | +|-------|-----------|------------|----------| +| gsd-planner | Opus | Opus | Sonnet | +| gsd-roadmapper | Opus | Sonnet | Sonnet | +| gsd-executor | Opus | Sonnet | Sonnet | +| gsd-phase-researcher | Opus | Sonnet | Haiku | +| gsd-project-researcher | Opus | Sonnet | Haiku | +| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | +| gsd-debugger | Opus | Sonnet | Sonnet | +| gsd-codebase-mapper | Sonnet | Haiku | Haiku | +| gsd-verifier | Sonnet | Sonnet | Haiku | +| gsd-plan-checker | Sonnet | Sonnet | Haiku | +| gsd-integration-checker | Sonnet | Sonnet | Haiku | + +**Profile philosophy:** +- **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical. +- **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason. +- **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases. + +--- + +## Usage Examples + +### New Project (Full Cycle) + +```bash +claude --dangerously-skip-permissions +/gsd:new-project # Answer questions, configure, approve roadmap +/clear +/gsd:discuss-phase 1 # Lock in your preferences +/gsd:plan-phase 1 # Research + plan + verify +/gsd:execute-phase 1 # Parallel execution +/gsd:verify-work 1 # Manual UAT +/clear +/gsd:discuss-phase 2 # Repeat for each phase +... +/gsd:audit-milestone # Check everything shipped +/gsd:complete-milestone # Archive, tag, done +``` + +### New Project from Existing Document + +```bash +/gsd:new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc +/clear +/gsd:discuss-phase 1 # Normal flow from here +``` + +### Existing Codebase + +```bash +/gsd:map-codebase # Analyze what exists (parallel agents) +/gsd:new-project # Questions focus on what you're ADDING +# (normal phase workflow from here) +``` + +### Quick Bug Fix + +```bash +/gsd:quick +> "Fix the login button not responding on mobile Safari" +``` + +### Resuming After a Break + +```bash +/gsd:progress # See where you left off and what's next +# or +/gsd:resume-work # Full context restoration from last session +``` + +### Preparing for Release + +```bash +/gsd:audit-milestone # Check requirements coverage, detect stubs +/gsd:plan-milestone-gaps # If audit found gaps, create phases to close them +/gsd:complete-milestone # Archive, tag, done +``` + +### Speed vs Quality Presets + +| Scenario | Mode | Depth | Profile | Research | Plan Check | Verifier | +|----------|------|-------|---------|----------|------------|----------| +| Prototyping | `yolo` | `quick` | `budget` | off | off | off | +| Normal dev | `interactive` | `standard` | `balanced` | on | on | on | +| Production | `interactive` | `comprehensive` | `quality` | on | on | on | + +### Mid-Milestone Scope Changes + +```bash +/gsd:add-phase # Append a new phase to the roadmap +# or +/gsd:insert-phase 3 # Insert urgent work between phases 3 and 4 +# or +/gsd:remove-phase 7 # Descope phase 7 and renumber +``` + +--- + +## Troubleshooting + +### "Project already initialized" + +You ran `/gsd:new-project` but `.planning/PROJECT.md` already exists. This is a safety check. If you want to start over, delete the `.planning/` directory first. + +### Context Degradation During Long Sessions + +Clear your context window between major commands: `/clear` in Claude Code. GSD is designed around fresh contexts -- every subagent gets a clean 200K window. If quality is dropping in the main session, clear and use `/gsd:resume-work` or `/gsd:progress` to restore state. + +### Plans Seem Wrong or Misaligned + +Run `/gsd:discuss-phase [N]` before planning. Most plan quality issues come from Claude making assumptions that `CONTEXT.md` would have prevented. You can also run `/gsd:list-phase-assumptions [N]` to see what Claude intends to do before committing to a plan. + +### Execution Fails or Produces Stubs + +Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope. + +### Lost Track of Where You Are + +Run `/gsd:progress`. It reads all state files and tells you exactly where you are and what to do next. + +### Need to Change Something After Execution + +Do not re-run `/gsd:execute-phase`. Use `/gsd:quick` for targeted fixes, or `/gsd:verify-work` to systematically identify and fix issues through UAT. + +### Model Costs Too High + +Switch to budget profile: `/gsd:set-profile budget`. Disable research and plan-check agents via `/gsd:settings` if the domain is familiar to you (or to Claude). + +### Working on a Sensitive/Private Project + +Set `commit_docs: false` during `/gsd:new-project` or via `/gsd:settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git. + +### GSD Update Overwrote My Local Changes + +Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd:reapply-patches` to merge your changes back. + +### Subagent Appears to Fail but Work Was Done + +A known workaround exists for a Claude Code classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded. + +--- + +## Recovery Quick Reference + +| Problem | Solution | +|---------|----------| +| Lost context / new session | `/gsd:resume-work` or `/gsd:progress` | +| Phase went wrong | `git revert` the phase commits, then re-plan | +| Need to change scope | `/gsd:add-phase`, `/gsd:insert-phase`, or `/gsd:remove-phase` | +| Milestone audit found gaps | `/gsd:plan-milestone-gaps` | +| Something broke | `/gsd:debug "description"` | +| Quick targeted fix | `/gsd:quick` | +| Plan doesn't match your vision | `/gsd:discuss-phase [N]` then re-plan | +| Costs running high | `/gsd:set-profile budget` and `/gsd:settings` to toggle agents off | +| Update broke local changes | `/gsd:reapply-patches` | + +--- + +## Project File Structure + +For reference, here is what GSD creates in your project: + +``` +.planning/ + PROJECT.md # Project vision and context (always loaded) + REQUIREMENTS.md # Scoped v1/v2 requirements with IDs + ROADMAP.md # Phase breakdown with status tracking + STATE.md # Decisions, blockers, session memory + config.json # Workflow configuration + MILESTONES.md # Completed milestone archive + research/ # Domain research from /gsd:new-project + todos/ + pending/ # Captured ideas awaiting work + done/ # Completed todos + debug/ # Active debug sessions + resolved/ # Archived debug sessions + codebase/ # Brownfield codebase mapping (from /gsd:map-codebase) + phases/ + XX-phase-name/ + XX-YY-PLAN.md # Atomic execution plans + XX-YY-SUMMARY.md # Execution outcomes and decisions + CONTEXT.md # Your implementation preferences + RESEARCH.md # Ecosystem research findings + VERIFICATION.md # Post-execution verification results +```