12 specialized Claude Code agents: debug, quick, health, plan-phase, execute-phase, that route each task to the right tool automatically.
Running the same general Claude Code session for a small fix, a root-cause investigation, a multi-phase plan, and a pipeline health check produces inconsistent results. GSD installs one agent per task shape. Each one knows exactly what it needs to do, how to verify it, and when to stop.
Steps
The fastest path is npx. It always installs the latest version. Alternatively, use the Claude plugin marketplace if GSD appears there. After install, restart Claude Code and run `/gsd:quick --help` to verify.
gsd:quick is the workhorse for small, scoped tasks: fix this bug, add this field, update this test. It enforces a time box. If the task cannot complete in one focused pass, it stops and tells you to break it down. This is the agent you open most often.
gsd:debug applies a root-cause-first protocol: it refuses to propose fixes before identifying the cause. It reads the error, traces the call path, forms a hypothesis, and verifies it. The first thing it outputs is the suspected root cause, not code.
gsd:health scans running daemons, plan progress, checkpoint freshness, task queue depth, and service health. Run it at session start or after a long break. If a plan is stuck, it tells you where.
With a structured plan from Superpowers writing-plans or GSD plan-phase, gsd:execute-phase picks up the current phase, works through its tasks, runs verification gates, and hands off to the next phase. You do not need to read the plan file and manage context manually.
How do you know it worked?
If something looks off
Skills & Commands Reference
GSD is a sequential workflow system. Commands build on each other in order. For new projects: new-project → create-roadmap → plan-phase → execute-plan → repeat. For existing codebases: map-codebase first, then the same sequence.
| Command / Skill | What it does | When to use it |
|---|---|---|
/gsd:new-projectbasic | Structured interview that extracts your project vision, constraints, and scope into PROJECT.md | Starting any new project, this is always step 1 |
/gsd:create-roadmapbasic | Generates ROADMAP.md (phases from start to finish) and STATE.md (living memory across sessions) | After new-project, creates the execution blueprint |
/gsd:plan-phase Nbasic | Breaks phase N into 2-3 atomic tasks with XML-structured plans and built-in verification steps | Before executing any phase, planning and execution are always separate steps |
/gsd:execute-planbasic | Runs the current PLAN.md in a fresh subagent with 200k tokens of clean context, no drift | After plan-phase, each task runs in isolation for consistent quality |
/gsd:map-codebasebasic | Spawns parallel agents to analyze your repo; creates 7 docs (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS) | Brownfield projects, always run before new-project so GSD knows your existing patterns |
/gsd:complete-milestonebasic | Archives the completed milestone, prepares STATE.md for the next iteration | When all phases of a milestone are done, keeps the roadmap clean |
/gsd:add-phaseadvanced | Appends a new phase to the end of the current roadmap | New requirements come in after the roadmap is created, avoids restarting from scratch |
/gsd:insert-phase Nadvanced | Slips a new phase between existing phases, renumbering as needed | Urgent work or a blocking dependency that must happen before a planned phase |
/gsd:helpbasic | Shows all available GSD commands with brief descriptions | Any time you forget the command syntax or want to see what's available |