> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/gsd-build/get-shit-done/llms.txt > Use this file to discover all available pages before exploring further. # Agent System Overview > Understanding the multi-agent orchestration architecture in Get Shit Done # 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: User runs `/gsd:plan-phase 1` — orchestrator receives the request Orchestrator spawns planner, checker, and researcher agents in parallel or sequence Each agent completes its task and returns structured data to orchestrator 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 | Stage | Orchestrator | Agents | | ------------ | ---------------------------------- | -------------------------------------------------------------------------- | | Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls | | Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass | | Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context | | Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures | ### Orchestrator Responsibilities Reads and writes STATE.md, ROADMAP.md, config.json Creates fresh agent instances with specific context Collects and combines outputs from parallel agents Routes to next step based on agent results ### Agent Responsibilities Single purpose: research, plan, execute, verify, or debug Return formatted results for orchestrator consumption Write artifacts (PLAN.md, SUMMARY.md, RESEARCH.md) 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: ```markdown theme={null} @.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phases/01-setup/01-CONTEXT.md Locked: Use Tailwind for styling Discretion: Database choice Deferred: Dark mode 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 `` 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: Creates executable phase plans with task breakdown Executes plans with atomic commits Verifies phase goal achievement Investigates bugs using scientific method Verifies plans will achieve goals before execution Research domains before planning and execution