Skip to main content

​
System Design

GSD is a context engineering and meta-prompting system built on a foundation of specialized agents, structured artifacts, and wave-based execution. The architecture prioritizes:
  • Context efficiency — Orchestrators stay lean (~10-15%), subagents get fresh 200K contexts
  • Modular workflows — Each workflow is independent, composable, and resumable
  • State persistence — Every decision, position, and blocker tracked across sessions
  • Parallel execution — Independent work runs simultaneously via wave coordination

​
Core Principles

Orchestrator Pattern: Thin coordinators spawn specialized agents. The orchestrator NEVER does heavy lifting — it discovers, routes, waits, and integrates results.
Context degradation awareness: Claude’s quality drops as context fills:
Context UsageQualityClaude’s State
0-30%PEAKThorough, comprehensive
30-50%GOODConfident, solid work
50-70%DEGRADINGEfficiency mode begins
70%+POORRushed, minimal
GSD keeps orchestrators lean and spawns fresh subagents to avoid degradation.

​
Directory Structure

​
Source Repository (get-shit-done/)

get-shit-done/
├── workflows/           # Orchestrator workflows (one per command)
│   ├── new-project.md
│   ├── plan-phase.md
│   ├── execute-phase.md
│   ├── verify-work.md
│   └── ...
├── templates/           # Document templates
│   ├── project.md
│   ├── state.md
│   ├── roadmap.md
│   ├── requirements.md
│   ├── summary.md
│   └── ...
├── references/          # Shared knowledge modules
│   ├── verification-patterns.md
│   ├── questioning.md
│   ├── model-profiles.md
│   ├── git-integration.md
│   └── ...
└── bin/                 # Node.js CLI tools
    ├── gsd-tools.cjs    # Core utilities
    └── lib/
        ├── config.cjs
        ├── roadmap.cjs
        ├── state.cjs
        └── ...

​
Agent Definitions (agents/)

agents/
├── gsd-planner.md              # Creates phase plans
├── gsd-executor.md             # Executes plans atomically
├── gsd-verifier.md             # Verifies goal achievement
├── gsd-plan-checker.md         # Validates plan quality
├── gsd-phase-researcher.md     # Domain research
├── gsd-project-researcher.md   # Project-level research
├── gsd-research-synthesizer.md # Aggregates research
├── gsd-roadmapper.md           # Creates roadmaps
├── gsd-debugger.md             # Systematic debugging
├── gsd-codebase-mapper.md      # Brownfield analysis
├── gsd-integration-checker.md  # Integration validation
└── gsd-nyquist-auditor.md      # Test coverage auditing

​
Project Artifacts (.planning/)

Created in each user project: 
.planning/
├── PROJECT.md              # Vision, always loaded
├── REQUIREMENTS.md         # Scoped v1/v2 with traceability
├── ROADMAP.md              # Phase breakdown + status
├── STATE.md                # Session memory, decisions, position
├── config.json             # Workflow configuration
├── MILESTONES.md           # Completed milestone archive
├── research/               # Domain research from new-project
│   ├── STACK.md
│   ├── FEATURES.md
│   ├── ARCHITECTURE.md
│   └── PITFALLS.md
├── codebase/               # Brownfield mapping
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   └── CONCERNS.md
├── todos/
│   ├── pending/            # Captured ideas
│   └── done/               # Completed todos
├── debug/                  # Active debug sessions
│   └── resolved/
└── phases/
    └── XX-phase-name/
        ├── XX-YY-PLAN.md       # Atomic execution plans
        ├── XX-YY-SUMMARY.md    # Execution outcomes
        ├── CONTEXT.md          # User preferences (from discuss-phase)
        ├── RESEARCH.md         # Phase-specific research
        ├── VERIFICATION.md     # Goal verification results
        └── VALIDATION.md       # Test coverage mapping
Size Constraints: Every file has limits based on where Claude’s quality degrades:
  • STATE.md: Under 100 lines (digest, not archive)
  • PLAN.md: 2-3 tasks max (complete within ~50% context)
  • SUMMARY.md: Under 200 lines

​
File Organization

​
Separation of Concerns

File TypePurposeLifecycle
WorkflowsOrchestration logic, command entry pointsRead by Claude on command invocation
AgentsSpecialized worker definitions with frontmatterSpawned via Task tool with fresh context
TemplatesDocument structure, formatting rulesCopied/populated during workflow execution
ReferencesShared knowledge, reusable patterns@-referenced in prompts as needed
CLI ToolsState manipulation, git integration, utilitiesCalled via Bash from workflows/agents

​
Context Loading Strategy

Orchestrators load:
  • STATE.md (always first — current position)
  • Workflow-specific templates (inline via @-references)
  • CLI tool JSON output (parsed for routing decisions)
Agents load:
  • Plan or task definition (their assignment)
  • PROJECT.md + STATE.md (project context)
  • CONTEXT.md (user decisions for that phase)
  • References as needed (verification patterns, questioning techniques)
Why @-references? Claude Code’s @ syntax loads files directly into context without orchestrator parsing. This keeps orchestrator code minimal and context usage low.

​
Workflow Composition

Every GSD command follows the same pattern: 
┌─────────────────────────────────────────┐
│  1. Load STATE.md (where are we?)       │
├─────────────────────────────────────────┤
│  2. Parse arguments (what's requested?) │
├─────────────────────────────────────────┤
│  3. Validate preconditions              │
├─────────────────────────────────────────┤
│  4. Spawn agents (parallel if possible) │
├─────────────────────────────────────────┤
│  5. Collect results (block on Task)     │
├─────────────────────────────────────────┤
│  6. Update state (commit if needed)     │
├─────────────────────────────────────────┤
│  7. Route next action (or exit)         │
└─────────────────────────────────────────┘
Workflows compose via routing:
  • /gsd:plan-phase → spawns researchers → spawns planner → spawns plan-checker → loops if fails
  • /gsd:execute-phase → spawns executors (parallel waves) → spawns verifier
  • /gsd:verify-work → UAT loop → spawns debuggers for failures → spawns planner for fixes

​
CLI Tools Architecture

Node.js utilities (bin/gsd-tools.cjs) handle:
  • State queries: Current phase, plan inventory, requirement traceability
  • State mutations: Mark phase complete, add decision, update roadmap
  • Git integration: Atomic commits, branch management, tag releases
  • Config management: Model profiles, workflow toggles, granularity settings
Why Node.js? Cross-platform (Mac, Windows, Linux), JSON I/O, filesystem operations, git bindings. Bash would fragment across platforms.
Key modules:
ModuleResponsibility
config.cjsRead/write .planning/config.json, model profile resolution
state.cjsSTATE.md updates, position tracking, decision logging
roadmap.cjsPhase management, progress tracking, completion
phase.cjsPhase discovery, plan inventory, wave grouping
verify.cjsGit commit verification, file existence checks
template.cjsTemplate rendering with variable substitution

​
Data Flow

​
Extension Points

​
Adding a New Workflow

  1. Create workflows/your-command.md
  2. Follow orchestrator pattern (load STATE, spawn agents, collect results)
  3. Update CLI tool if new state mutations needed
  4. Register in command index

​
Adding a New Agent

  1. Create agents/gsd-your-agent.md
  2. Define frontmatter: name, description, tools, skills
  3. Document role, context reading requirements, output format
  4. Spawn via Task(subagent_type="gsd-your-agent", ...)

​
Adding a New Template

  1. Create templates/your-template.md
  2. Use {{variable}} placeholders
  3. Document purpose, lifecycle, size constraints
  4. Reference via @~/.claude/get-shit-done/templates/your-template.md
GSD’s architecture is deliberately simple. No databases, no servers, no external dependencies. Just markdown files, git, and Claude.

​
Performance Characteristics

Context efficiency:
  • Orchestrator: 10-15% context usage (stays responsive)
  • Agents: Fresh 200K each (peak quality for heavy lifting)
Parallelization:
  • Research: 4 agents simultaneously
  • Execution: N plans per wave (independent work)
  • Mapping: 4-7 agents for brownfield analysis
Session continuity:
  • /clear between major operations (context stays fresh)
  • STATE.md restored instantly via /gsd:resume-work
  • Plans executable in any order (dependency-aware but stateless)

​
Next Steps

Agent System

Deep dive into agent roles and orchestration patterns

Wave Execution

How parallel execution with dependencies works

State Management

STATE.md, decision tracking, session continuity

Security

Protecting sensitive files and deny list setup