Skip to main content

​
Agent System Overview

Get Shit Done uses a multi-agent orchestration pattern where specialized agents handle specific workflow stages while thin orchestrators coordinate execution and manage state.

​
The Orchestrator Pattern

Every GSD workflow follows the same pattern:
1

Orchestrator receives command

User runs /gsd:plan-phase 1 — orchestrator receives the request
2

Orchestrator spawns specialized agents

Orchestrator spawns planner, checker, and researcher agents in parallel or sequence
3

Agents return structured results

Each agent completes its task and returns structured data to orchestrator
4

Orchestrator routes to next step

Based on results, orchestrator either spawns next agent or returns to user
The orchestrator never does heavy lifting. It spawns agents, waits, integrates results, and manages transitions.

​
Why This Architecture?

​
Context Window Efficiency

You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.

​
Parallelization

Independent work runs simultaneously:
  • 4 researchers investigate stack, features, architecture, and pitfalls in parallel
  • 3 plans with no dependencies execute in parallel
  • Multiple debuggers diagnose different UAT issues in parallel

​
Specialization

Each agent has a focused role with domain-specific instructions:
  • Planner knows how to break phases into tasks and build dependency graphs
  • Verifier knows goal-backward methodology and stub detection
  • Debugger knows scientific method and hypothesis testing

​
Agent Coordination

​
Stage-Based Workflow

StageOrchestratorAgents
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

​
Orchestrator Responsibilities

State Management

Reads and writes STATE.md, ROADMAP.md, config.json

Agent Spawning

Creates fresh agent instances with specific context

Result Integration

Collects and combines outputs from parallel agents

Flow Control

Routes to next step based on agent results

​
Agent Responsibilities

Focused Execution

Single purpose: research, plan, execute, verify, or debug

Structured Returns

Return formatted results for orchestrator consumption

File Creation

Write artifacts (PLAN.md, SUMMARY.md, RESEARCH.md)

Stateless Operation

Don’t manage global state — orchestrator handles this

​
Wave Execution Pattern

Plans are grouped into waves based on dependencies. Within each wave, plans run in parallel. Waves run sequentially. 
┌─────────────────────────────────────────────────────────────────────┐
│  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).

​
Agent Lifecycle

​
Spawning

Orchestrator creates agent with specific context: 
<files_to_read>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-setup/01-CONTEXT.md
</files_to_read>

<user_decisions>
Locked: Use Tailwind for styling
Discretion: Database choice
Deferred: Dark mode
</user_decisions>

Create plans for Phase 1: Project Setup
Agent receives:
  • Files to read (mandatory initial context)
  • User decisions (constraints and freedom)
  • Specific task and expected output

​
Execution

Agent operates autonomously:
  1. Reads mandatory files from <files_to_read> block
  2. Executes workflow using domain-specific instructions
  3. Writes artifacts (PLAN.md, SUMMARY.md, etc.)
  4. Returns structured result to orchestrator

​
Return

Agent returns one of:
  • Success: ## PLANNING COMPLETE with summary
  • Checkpoint: ## CHECKPOINT REACHED with state and awaiting info
  • Blocked: ## PLANNING BLOCKED with issue and options
Orchestrator uses these structured returns to determine next action: proceed, spawn continuation agent, or return control to user.

​
Communication Patterns

​
Orchestrator → Agent

  • Files to read — Context for the task
  • Specific instructions — What to create/verify
  • User input — Decisions, feedback, approvals

​
Agent → Orchestrator

  • Structured results — Success/checkpoint/blocked with data
  • File paths — Artifacts created for commit
  • Next steps — What should happen next

​
Agent → File System

  • Writes artifacts — PLAN.md, SUMMARY.md, RESEARCH.md
  • Reads context — PROJECT.md, ROADMAP.md, existing plans
  • Never commits — Orchestrator handles git operations

​
Error Handling

​
Agent Failures

If agent encounters an error:
  1. Return structured failure to orchestrator
  2. Include error context for debugging
  3. Suggest recovery options when possible
Orchestrator decides:
  • Retry with adjusted context
  • Spawn different agent type
  • Return to user for input

​
Context Overflow

If agent approaches context limit:
  1. Complete current task with available context
  2. Return checkpoint with state and continuation point
  3. Orchestrator spawns fresh agent with checkpoint state
Checkpoint state includes: completed tasks, current task, next action, all previous evidence/decisions.

​
Next Steps

Explore the specific agents:

Planner

Creates executable phase plans with task breakdown

Executor

Executes plans with atomic commits

Verifier

Verifies phase goal achievement

Debugger

Investigates bugs using scientific method

Plan Checker

Verifies plans will achieve goals before execution

Researchers

Research domains before planning and execution