Skip to main content

​
General Questions

GSD is a meta-prompting, context engineering, and spec-driven development system for Claude Code, OpenCode, Gemini CLI, and Codex. It solves context rot — the quality degradation that happens as Claude fills its context window.Instead of vibecoding (describe what you want, get inconsistent garbage), GSD uses structured workflows, subagent orchestration, and XML prompting to build reliable software.
People who want to describe what they want and have it built correctly — without pretending they’re running a 50-person engineering org.Ideal for:
  • Solo developers building with AI
  • Creators who don’t write code themselves
  • Teams prototyping new features quickly
  • Anyone frustrated with AI code quality degradation
Other tools (BMAD, SpecKit) add enterprise theater: sprint ceremonies, story points, stakeholder syncs, retrospectives, Jira workflows.GSD focuses on what actually matters:
  • Context engineering — Give Claude exactly what it needs
  • Fresh context per task — 200K tokens purely for implementation
  • Atomic commits — Clear history, easy rollback
  • Thin orchestrators — Complexity in the system, not your workflow
What you see: a few commands that just work.
Yes! Run /gsd:map-codebase first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then /gsd:new-project knows your codebase — questions focus on what you’re adding, and planning automatically loads your patterns.
GSD works with:
  • Claude Code (Anthropic’s official CLI)
  • OpenCode (open source, supports free models)
  • Gemini CLI (Google’s Gemini models)
  • Codex (skills-first architecture)
Install for any or all of them:
npx get-shit-done-cc@latest --all --global

​
Workflow Questions

Full cycle:
  1. Initialize: /gsd:new-project — Questions → Research → Requirements → Roadmap
  2. For each phase:
    • /gsd:discuss-phase N — Lock in your preferences
    • /gsd:plan-phase N — Research + Plan + Verify
    • /gsd:execute-phase N — Parallel execution in fresh contexts
    • /gsd:verify-work N — Manual UAT with auto-diagnosis
  3. Complete: /gsd:audit-milestone → /gsd:complete-milestone
  4. Next version: /gsd:new-milestone
Quick fixes:
/gsd:quick
> "Fix the login button"
No! The workflow is modular:
  • Skip discuss-phase if you trust Claude’s defaults
  • Skip research with --skip-research if the domain is familiar
  • Skip verification if you’re prototyping
  • Use Quick Mode for ad-hoc tasks
Configure defaults:
/gsd:settings
/gsd:discuss-phase captures your preferences before planning:
  • UI layout, component density, interactions
  • API response formats, error handling
  • Content structure, tone, depth
  • Naming conventions, grouping criteria
Output: CONTEXT.md — feeds directly into researcher and planner./gsd:plan-phase creates implementation plans:
  • Researches how to build it
  • Creates 2-3 atomic task plans
  • Verifies plans achieve phase goals
Output: PLAN.md files — ready for execution.Skip discuss-phase and you get reasonable defaults. Use discuss-phase and you get your vision.
Yes! The system is modular:
# Append phase
/gsd:add-phase

# Insert urgent work (creates decimal phase like 3.1)
/gsd:insert-phase 3

# Remove future phase and renumber
/gsd:remove-phase 7
You’re never locked in.
Two options:Quick status check:
/gsd:progress
Full context restoration:
/gsd:resume-work
Both read state files and tell you exactly where you are and what’s next.
Quick Mode executes ad-hoc tasks with GSD guarantees but skips optional agents:
/gsd:quick
> "Add dark mode toggle to settings"
  • Same agents — Planner + executor, same quality
  • Skips — Research, plan checker, verifier
  • Separate tracking — Lives in .planning/quick/, not phases
Use for: bug fixes, small features, config changes.Full quick mode (includes verification):
/gsd:quick --full
Discuss first (gather context):
/gsd:quick --discuss

​
Technical Questions

Fresh context = consistent quality.Each subagent gets a clean 200K token window. No accumulated garbage, no degradation. Your main session stays at 30-40% context usage even during massive phases.Example: Planning phase
  • Orchestrator: 30-40% context (coordination only)
  • Researcher: Fresh 200K (domain investigation)
  • Planner: Fresh 200K (plan creation)
  • Checker: Fresh 200K (verification)
The work happens in fresh contexts. You get consistent output.
.planning/
  PROJECT.md              # Vision (always loaded)
  REQUIREMENTS.md         # Scoped v1/v2 requirements
  ROADMAP.md              # Phase breakdown
  STATE.md                # Decisions, blockers, memory
  config.json             # Workflow configuration
  research/               # Domain research
  phases/
    XX-phase-name/
      XX-YY-PLAN.md       # Execution plans
      XX-YY-SUMMARY.md    # What happened
      CONTEXT.md          # Your preferences
      RESEARCH.md         # Ecosystem research
      VERIFICATION.md     # Verification results
Each file is size-limited based on where Claude’s quality degrades. Stay under, get consistent excellence.
Claude performs better with structured XML than unstructured text.Every plan is XML:
<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    Use jose for JWT (not jsonwebtoken - CommonJS issues).
    Validate credentials against users table.
    Return httpOnly cookie on success.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
  <done>Valid credentials return cookie, invalid return 401</done>
</task>
Precise instructions. No guessing. Verification built in.
Plans are grouped into “waves” based on dependencies:
Wave 1 (parallel):
  ├── Plan 01: User Model
  └── Plan 02: Product Model
         ↓
Wave 2 (parallel):
  ├── Plan 03: Orders API (needs Plan 01)
  └── Plan 04: Cart API (needs Plan 02)
         ↓
Wave 3:
  └── Plan 05: Checkout UI (needs Plans 03 + 04)
  • Independent plans → Same wave → Run in parallel
  • Dependent plans → Later wave → Wait for dependencies
  • File conflicts → Sequential plans or same plan
Configure:
/gsd:settings
# Toggle: parallelization.enabled
Each task gets its own commit immediately after completion:
abc123f docs(08-02): complete user registration plan
def456g feat(08-02): add email confirmation flow
hij789k feat(08-02): implement password hashing
lmn012o feat(08-02): create registration endpoint
Benefits:
  • git bisect finds exact failing task
  • Each task independently revertable
  • Clear history for Claude in future sessions
  • Better observability in AI-automated workflow
Yes! Configure branching:
/gsd:settings
Options:
  • none (default) — Commit to current branch
  • phase — Create branch per phase (gsd/phase-3-auth)
  • milestone — Create branch per milestone (gsd/v1.0-mvp)
At milestone completion, GSD offers squash merge (recommended) or merge with history.

​
Configuration Questions

ProfilePlanningExecutionVerificationBest For
qualityOpusOpusSonnetCritical work, quota available
balancedOpusSonnetSonnetDefault — good quality, reasonable cost
budgetSonnetSonnetHaikuHigh-volume, less critical work
Switch profiles:
/gsd:set-profile budget
  1. Switch to budget profile: 
    /gsd:set-profile budget
  2. Disable optional agents: 
    /gsd:settings
# Toggle off:
# - workflow.research (skip domain research)
# - workflow.plan_check (skip plan verification)
# - workflow.verifier (skip post-execution verification)
  3. Use coarser granularity: 
    /gsd:settings
# Set granularity to "coarse" (3-5 phases instead of 8-12)
  4. Skip research when familiar: 
    /gsd:plan-phase --skip-research
Yes! For OSS contributions, client work, or privacy:During setup:
  • Answer “no” when asked about git tracking
After setup:
/gsd:settings
# Set: commit_docs = false
Add to .gitignore:
echo ".planning/" >> .gitignore
Planning artifacts stay local and never touch git.
mode: yolo auto-approves all decisions.Interactive mode (default):
  • Confirms roadmap before starting
  • Confirms plans before execution
  • Asks for approval at checkpoints
YOLO mode:
  • Auto-approves everything
  • Runs end-to-end without stopping
  • You walk away, come back to completed work
Configure:
/gsd:settings
# Set: mode = yolo
Recommended for familiar domains or when you trust the system.
Yes! Since v1.19.2:Edit .planning/config.json:
{
  "model_profile": "balanced",
  "model_overrides": {
    "gsd-executor": "opus",
    "gsd-verifier": "haiku"
  }
}
Overrides take precedence over the profile.

​
Best Practices

Always use for:
  • Visual features (UI/UX)
  • User-facing content
  • APIs with multiple design choices
  • Complex state management
Can skip for:
  • CRUD operations with obvious patterns
  • Well-defined technical tasks
  • Bug fixes or refactoring
The deeper you go in discuss-phase, the more the system builds what you actually want.
GSD creates USER-SETUP.md for external service configuration.Checkpoints handle setup:
  • Claude attempts automated setup first
  • If it requires auth/credentials, presents a checkpoint
  • You complete the setup, respond, execution continues
Types:
  • human-verify — “Did this work?” (yes/no)
  • human-action — “Please do X, then confirm” (auth gates)
  • human-decide — “Option A or B?” (decisions)
Between major commands:
  • After /gsd:new-project
  • Between phases
  • When you notice quality degradation
GSD’s main orchestrators stay lean (30-40% context), but clearing between phases ensures maximum freshness.Restore state after clearing:
/gsd:progress
# or
/gsd:resume-work
Commit if:
  • Solo project or trusted team
  • You want planning history tracked
  • You value reproducibility
Don’t commit if:
  • OSS project (planning is your private workflow)
  • Client work (keep your process separate)
  • Privacy concerns (planning may contain sensitive info)
Configure during setup or via /gsd:settings.

​
Troubleshooting

Solution: Use /gsd:discuss-phase before planning.Most plan quality issues come from Claude making assumptions that CONTEXT.md would have prevented.Preview intended approach:
/gsd:list-phase-assumptions [N]
Cause: Plan scope too large for a single context window.Solution:
  1. Increase granularity: /gsd:settings → fine
  2. Delete phase plans: rm -rf .planning/phases/XX-phase-name/
  3. Re-plan: /gsd:plan-phase XX
Plans should have 2-3 tasks maximum.
/gsd:progress
Reads all state files and shows:
  • Current milestone and version
  • Current phase and status
  • What to do next
  • Recent decisions and blockers
/gsd:debug "Description of what's broken"
GSD spawns a debugger agent that:
  • Forms hypotheses
  • Investigates systematically
  • Creates fix plans
  • Tracks state in .planning/debug/
For more troubleshooting, see the Troubleshooting Guide.

​
Community & Support

Discord Community

Join the GSD Discord for help from the community and developers.

GitHub Discussions

Ask questions and share feedback on GitHub Discussions.

Report Issues

Found a bug? Report it on GitHub Issues.

X (Twitter)

Follow @gsd_foundation for updates and announcements.