Skip to main content

​
Why GSD?

​
The Problem

Vibecoding has a bad reputation. You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale. Claude Code is incredibly powerful if you give it the context it needs. Most people don’t. As the context window fills, quality degrades. Claude starts being vague, skipping implementations, adding TODOs, or contradicting earlier work. This is context rot.

​
The Solution

GSD is the context engineering layer that makes Claude Code reliable. It solves context rot through:

Structured Context

Every file in .planning/ has a purpose: project vision, requirements, research, plans, state, and summaries.

Fresh Subagents

Each task gets a specialized agent with a clean 200k token context window. No accumulated garbage.

XML Prompts

Precise instructions in structured XML format. No guessing, verification built in.

Atomic Commits

Every task commits immediately after completion. Clear history, easy rollback, better observability.

​
Why It Was Built

From the creator:
I’m a solo developer. I don’t write code — Claude Code does. Other spec-driven development tools exist; BMAD, Speckit… But they all seem to make things way more complicated than they need to be (sprint ceremonies, story points, stakeholder syncs, retrospectives, Jira workflows) or lack real big picture understanding of what you’re building. I’m not a 50-person software company. I don’t want to play enterprise theater. I’m just a creative person trying to build great things that work. So I built GSD. The complexity is in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that just work. The system gives Claude everything it needs to do the work and verify it. I trust the workflow. It just does a good job. That’s what this is. No enterprise roleplay bullshit. Just an incredibly effective system for building cool stuff consistently using Claude Code. — TÂCHES

​
Design Principles

​
1. Simplicity Over Ceremony

No sprint ceremonies, story points, or retrospectives. Just commands that work: 
/gsd:new-project      # Initialize
/gsd:discuss-phase 1  # Shape the implementation
/gsd:plan-phase 1     # Research and plan
/gsd:execute-phase 1  # Build it
/gsd:verify-work 1    # Test it

​
2. Context Engineering First

Every stage has exactly what it needs. Nothing more, nothing less.
FilePurpose
PROJECT.mdProject vision, always loaded
research/Ecosystem knowledge (stack, features, architecture, pitfalls)
REQUIREMENTS.mdScoped v1/v2 requirements with phase traceability
ROADMAP.mdWhere you’re going, what’s done
STATE.mdDecisions, blockers, position — memory across sessions
PLAN.mdAtomic task with XML structure, verification steps
SUMMARY.mdWhat happened, what changed, committed to history
Files have size limits based on where Claude’s quality degrades. Stay under, get consistent excellence.

​
3. Multi-Agent Orchestration

Thin orchestrators spawn specialized agents:
StageOrchestrator DoesAgents Do
ResearchCoordinates, presents findings4 parallel researchers investigate stack, features, architecture, pitfalls
PlanningValidates, manages iterationPlanner creates plans, checker verifies, loop until pass
ExecutionGroups into waves, tracks progressExecutors implement in parallel, each with fresh 200k context
VerificationPresents results, routes nextVerifier checks codebase against goals, debuggers diagnose failures
The orchestrator never does heavy lifting. It spawns agents, waits, integrates results. This keeps your main context window at 30-40% even during complex phases.

​
4. XML Prompt Formatting

Every plan is structured XML optimized for Claude: 
<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.

​
5. Wave-Based Execution

Plans execute in waves based on dependencies: 
┌─────────────────────────────────────────────────────────────────────┐
│  PHASE EXECUTION                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  WAVE 1 (parallel)          WAVE 2 (parallel)          WAVE 3       │
│  ┌─────────┐ ┌─────────┐    ┌─────────┐ ┌─────────┐    ┌─────────┐ │
│  │ Plan 01 │ │ Plan 02 │ →  │ Plan 03 │ │ Plan 04 │ →  │ Plan 05 │ │
│  │         │ │         │    │         │ │         │    │         │ │
│  │ User    │ │ Product │    │ Orders  │ │ Cart    │    │ Checkout│ │
│  │ Model   │ │ Model   │    │ API     │ │ API     │    │ UI      │ │
│  └─────────┘ └─────────┘    └─────────┘ └─────────┘    └─────────┘ │
│       │           │              ↑           ↑              ↑       │
│       └───────────┴──────────────┴───────────┘              │       │
│              Dependencies: Plan 03 needs Plan 01            │       │
│                          Plan 04 needs Plan 02              │       │
│                          Plan 05 needs Plans 03 + 04        │       │
└─────────────────────────────────────────────────────────────────────┘
Why waves matter:
  • Independent plans → Same wave → Run in parallel
  • Dependent plans → Later wave → Wait for dependencies
  • File conflicts → Sequential plans or same plan
“Vertical slices” (Plan 01: User feature end-to-end) parallelize better than “horizontal layers” (Plan 01: All models, Plan 02: All APIs).

​
6. Atomic Git History

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

​
7. Modular by Design

You’re never locked in. The system adapts:
  • Add phases to current milestone
  • Insert urgent work between phases
  • Complete milestones and start fresh
  • Adjust plans without rebuilding everything

​
Who Should Use GSD?

Solo Developers

You want to build things quickly without enterprise overhead.

Creative Technologists

You have ideas and want them built correctly, the first time.

Product Engineers

You want to ship fast while maintaining code quality.

Technical Founders

You’re prototyping rapidly or building your MVP.

​
What GSD Is Not

GSD is not for enterprise teams wanting Jira workflows, sprint ceremonies, and stakeholder syncs. It’s for people who want to describe what they want and have it built correctly.

​
Configuration Philosophy

GSD offers configuration for flexibility, but comes with smart defaults:

​
Model Profiles

ProfilePlanningExecutionVerification
qualityOpusOpusSonnet
balanced (default)OpusSonnetSonnet
budgetSonnetSonnetHaiku
Switch profiles: 
/gsd:set-profile budget

​
Workflow Agents

Optional agents improve quality but add tokens:
SettingDefaultWhat it Does
workflow.researchtrueResearches domain before planning each phase
workflow.plan_checktrueVerifies plans achieve phase goals before execution
workflow.verifiertrueConfirms must-haves were delivered after execution
workflow.nyquist_validationtrueMaps automated test coverage during planning
Toggle these via /gsd:settings or override per-invocation with flags like --skip-research.

​
The Bottom Line

Claude Code is powerful. GSD makes it reliable. No ceremony. No theater. Just an incredibly effective system for building cool stuff consistently.