Advanced GSD Usage

The Core Lifecycle

The standard GSD flow follows a repeatable cycle. Understanding this loop is foundational to using GSD effectively:

/gsd:new-project
/gsd:discuss-phase N
/gsd:plan-phase N
/gsd:execute-phase N
/gsd:verify-work N
# Repeat for each phase
/gsd:complete-milestone
/gsd:new-milestone

Project Kickoff Best Practices

How you start a project shapes everything downstream. These strategies help GSD understand your codebase and vision from the beginning.

For Existing Codebases: Always map-codebase First

This is the single biggest mistake people make — jumping straight to /gsd:new-project on a brownfield project. Running /gsd:map-codebase first 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.

This creates a suite of documents in .planning/codebase/: STACK.md (languages, frameworks, dependencies), ARCHITECTURE.md (patterns, layers, data flow), STRUCTURE.md (directory layout, key files), CONVENTIONS.md (coding standards, naming), TESTING.md (test setup, patterns), INTEGRATIONS.md (external services, APIs), and CONCERNS.md (tech debt, known issues).

Prompting During new-project

This is where most people leave quality on the table. The system asks you questions until it understands your idea, but how you answer matters enormously.

Tips for better project initialization prompts:

• Be opinionated about tech choices upfront. Don't say "whatever framework works best." Say "I want Next.js 14 with App Router, Tailwind, Drizzle ORM, and Postgres." The more specific you are about stack preferences, the less the system has to guess.
• State anti-goals explicitly. "No SSR for the dashboard — it should be fully client-side." "No Redux — use Zustand or React context." Anti-goals constrain the solution space and prevent Claude from defaulting to the most common pattern.
• Describe the user, not just the feature. Instead of "add authentication," say "solo creators who hate friction — magic link auth, no passwords, remember device for 30 days." This flows into CONTEXT.md and shapes every implementation decision.
• Name your v2 explicitly. GSD separates v1 from v2 requirements. If you don't name things as v2, they'll creep into v1 scope and bloat your roadmap.

The Discuss Phase Advantage

/gsd:discuss-phase N is where most people either skip or give shallow answers. Your roadmap has a sentence or two per phase. That's not enough context to build something the way you imagine it. This step captures your preferences before anything gets researched or planned.

The system analyzes the phase and identifies gray areas based on what's being built — visual features get layout/density/interaction questions, APIs get response format/error handling questions, content systems get structure/tone questions.

The output of this step, CONTEXT.md, feeds directly into both the researcher and planner. The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get your vision.

Command Reference

GSD includes 35+ commands organized by how frequently you'll use them. Here's the complete reference by frequency tier.

Core Workflow Commands

These are the commands you'll use in every project following the standard lifecycle.

Power User Commands

These commands handle edge cases, debugging, and workflow customization.

Edge Case and Utility Commands

Power User Command Details

Let's dive deeper into the power user commands that unlock advanced workflows.

/gsd:quick — The Fast Lane

For ad-hoc tasks that don't need full planning. Quick mode gives you GSD guarantees (atomic commits, state tracking) with a faster path — same agents, skips optional steps like research and plan checker, and uses separate tracking in .planning/quick/.

Use this for bug fixes, config changes, small features, and one-off tasks. Don't force everything through the full phase lifecycle.

/gsd:consider-issues

This command reviews deferred issues with codebase context, closes resolved ones, and identifies urgent ones. During development, things get logged to ISSUES.md — deferred enhancements, edge cases noticed during execution, technical debt. This command revisits them intelligently rather than letting them rot.

/gsd:insert-phase

Inserts urgent work as a decimal phase between existing phases — for example, creating phase 7.1 between phases 7 and 8. Useful for discovered work that must happen mid-milestone. This is the escape hatch for when you realize mid-build that something critical was missed without blowing up your entire roadmap.

/gsd:add-phase

Adds a phase to the end of the current milestone in the roadmap. Use this when scope grows but it's genuinely v1 work, not v2 creep.

/gsd:debug

Spawns a debugger agent with scientific debugging methodology, hypothesis testing, and 7+ investigation techniques. Instead of manually poking around when something fails, this gives you a structured investigation.

/gsd:progress

Your session-resumption command. When you come back to a project after closing Claude Code, this tells GSD where you left off and what to do next. Way better than trying to remember which phase you were on.

/gsd:settings

GSD stores project settings in .planning/config.json. You can configure during /gsd:new-project or update later with /gsd:settings. Key things you can toggle:

• Model profiles — Control which Claude model each agent uses. Balance quality vs token spend.
• Workflow toggles — Enable/disable plan_check, research, and other optional agents that add quality but cost tokens.
• Branch modes — Control how GSD handles branches during execution.
• Parallelization — Control wave-based parallel execution.

Advanced Tips and Tricks

These power-user techniques help you get more out of GSD and avoid common friction points.

Run with --dangerously-skip-permissions

GSD is designed for frictionless automation. Stopping to approve date and git commit 50 times defeats the purpose. If you're not comfortable with that, use the granular permissions config from the README.

Gap Closure After Verification

When /gsd:verify-work finds issues, don't manually debug. You can use the gap closure workflow to systematically fix verification failures:

# Create fix plans for verification gaps
/gsd:plan-phase N --gaps

# Execute only gap closure plans
/gsd:execute-phase N --gaps-only

# Re-verify implementation
/gsd:verify-work N

/clear Does Not Lose State

State is preserved in .planning/ files. You can /clear and resume with the next command, for example /gsd:execute-phase 3. Use /clear aggressively when your context window is getting full. This is actually part of GSD's core design — the whole point is that agents get fresh 200k token contexts.

The XML Task Structure

Every GSD plan uses structured XML that Claude parses extremely well. Each task specifies the type, name, files involved, action instructions, verification steps, and done criteria. If you ever need to write a manual plan or tweak one, follow this format — it's not arbitrary, it's optimized for Claude's attention patterns.

Protect Your Secrets

Add sensitive files to Claude Code's deny list in settings.json to prevent Claude from reading them entirely:

{
  "denylist": [
    "Read(.env)",
    "Read(.env.*)",
    "Read(**/secrets/*)",
    "Read(**/*.pem)",
    "Read(**/*.key)"
  ]
}

Context Budget Awareness

The reason GSD works is context engineering. Orchestrators maintain 10-15% context usage while coordinating complex multi-agent workflows. The main session stays responsive even during hours-long phase execution. Each subagent gets a fresh 200k token window. If you're doing things outside GSD's commands in the same session, you're eating into orchestrator context — keep manual exploration minimal during execution.

Common Gotchas

Watch out for these common issues that trip up even experienced GSD users.

The bottom line: GSD's power is in treating Claude Code as a managed development system rather than a chatbot. The more structure you feed in (especially during discuss phases and project init), the better the output. And reach for the utility commands — they exist because the creator hit the same walls you will.