GSD Plugin

What Is GSD?

GSD is a plugin that extends Claude Code with powerful project automation capabilities. It's not a standalone tool — you need Claude Code installed first. Once added, GSD introduces structured planning workflows, autonomous task execution, and state management that persists across sessions.

Think of Claude Code as your AI pair programmer, and GSD as the project manager who keeps everything organized. GSD asks clarifying questions about your project, researches the best technical approaches, creates detailed execution plans, and then autonomously implements those plans with checkpoints for human verification.

GSD is particularly valuable for projects that span multiple sessions, require coordination across many files, or benefit from upfront planning before implementation. It brings discipline and structure to AI-assisted development without sacrificing flexibility.

The GSD Workflow

GSD follows a systematic approach to project execution. Each phase builds on the previous one, creating a clear path from initial idea to working software:

1. Questioning

GSD starts by asking clarifying questions about your project. What are you building? Who is it for? What constraints do you have? This phase captures requirements and ensures everyone understands the goals before any code is written.

2. Research

Based on your requirements, GSD investigates libraries, APIs, design patterns, and best practices for your tech stack. It documents findings, compares alternatives, and makes informed recommendations about how to structure your project.

3. Planning

GSD creates a phased roadmap with detailed task breakdowns. Each phase has specific objectives, required files, verification steps, and success criteria. Plans are written in Markdown and stored in your project so you can review and modify them before execution.

4. Execution

This is where GSD shines. It autonomously executes plans, completing tasks one by one with atomic commits for each. If it encounters issues, it handles them according to built-in deviation rules. Human checkpoints ensure you stay in control at critical decision points.

5. Verification

After execution, GSD checks that the implementation matches the original requirements. It runs tests, validates functionality, and produces summary documentation showing what was built, what changed, and any deviations from the plan.

Key Commands

GSD adds several slash commands to Claude Code. These commands trigger specific workflows and help you navigate the project lifecycle:

• /gsd:init — Initialize a new project with GSD. Creates the .planning/ directory structure and PROJECT.md definition.
• /gsd:discuss-phase — Discuss and refine phase requirements. Use this to ask questions and clarify goals before planning.
• /gsd:research-phase — Research libraries, APIs, and patterns for a specific phase. Produces RESEARCH.md with findings and recommendations.
• /gsd:plan-phase — Create detailed execution plans for a phase. Generates one or more PLAN.md files with task breakdowns.
• /gsd:execute-phase — Run plans autonomously. Executes tasks, commits changes, handles deviations, and creates summary documentation.
• /gsd:verify-phase — Verify implementation against requirements. Checks that all must-haves are satisfied and documents any gaps.

/gsd:init
/gsd:plan-phase 1
/gsd:execute-phase 1

Each command is designed for a specific part of the workflow. Start with initialization, plan your work, execute the plans, and verify the results.

What GSD Creates

When you initialize GSD in a project, it creates a .planning/ directory that holds all project management artifacts. Everything is stored as plain Markdown files, making it easy to read, edit, and version-control alongside your code:

• PROJECT.md — Project definition and requirements. Describes what you're building, core value proposition, constraints, and key decisions.
• ROADMAP.md — Phased delivery plan. Breaks the project into logical phases with dependencies and deliverables clearly defined.
• STATE.md — Current progress and session continuity. Tracks which phase and plan you're on, performance metrics, decisions, and blockers.
• phases/ — Per-phase subdirectories containing RESEARCH.md files, PLAN.md files, and SUMMARY.md files after execution.

When to Use GSD

GSD shines in specific scenarios where structure and planning provide clear benefits. Understanding when to use it helps you work more effectively:

Great for:

• Multi-file features that touch several parts of your codebase
• New projects you're building from scratch with clear requirements
• Complex refactors requiring careful coordination across files
• Any work spanning multiple sessions that benefits from state tracking
• Projects where you want documentation of decisions and changes

Less ideal for:

• Quick one-off edits that take minutes and don't need planning
• Exploratory coding where you're still figuring out the approach
• Simple bug fixes that don't require coordination
• Emergency hotfixes where speed matters more than documentation

The sweet spot: Projects that benefit from planning before building. If you'd normally sketch out an approach or create a checklist before coding, GSD formalizes that process and then executes it for you.

GSD builds on top of Claude Code. If you haven't used Claude Code yet, start with Getting Started.

How GSD Differs from Plain Claude Code

GSD and Claude Code work together, but they serve different purposes. Here's what GSD adds to the base Claude Code experience:

Claude Code is excellent for interactive development — asking questions, exploring ideas, and getting immediate assistance. GSD adds structure when you want to work more systematically across sessions with clear milestones and deliverables.

For the complete command reference organized by frequency tier, project kickoff best practices, and expert tips, see Advanced GSD Usage.