Agent System

Multi-Agent Orchestration

GSD uses a thin orchestrator, specialized agents pattern. Every workflow follows the same structure:

Orchestrator (main Claude session) — Coordinates, routes, waits
Agents (fresh subagent contexts) — Execute, research, verify, plan

Core Principle: The orchestrator never does heavy lifting. It spawns agents, waits for results (blocking on Task tool), integrates outputs, and routes to the next step.

Why This Architecture?

Problem: Claude’s quality degrades as context fills. At 70%+ usage, output becomes rushed and incomplete. Solution: Keep the orchestrator lean. Heavy work happens in fresh 200K contexts (subagents), each starting at 0% usage. Result: You can run an entire phase — deep research, multiple plans, thousands of lines of code — and your main session stays at 30-40% context. Fast, responsive, consistent quality.

Orchestrator Pattern

Responsibilities

What Orchestrators Do	What They DON’T Do
Load STATE.md	Read codebase files
Parse CLI tool JSON	Write implementation code
Spawn agents with context	Perform analysis
Block on Task (wait for completion)	Make planning decisions
Collect and route results	Execute verification
Update state files	Research ecosystems
Commit tracking artifacts	Debug issues

Orchestrator Lifecycle

┌────────────────────────────────────────────┐
│  ORCHESTRATOR (Main Claude Session)        │
│  Context: 10-15%                           │
├────────────────────────────────────────────┤
│  1. Load STATE.md (current position)       │
│  2. Call CLI tool (discover, validate)     │
│  3. Spawn agents (Task tool, parallel)     │
│     ↓                                      │
│  4. WAIT (Task blocks until complete)      │
│     ↓                                      │
│  5. Collect results (read artifacts)       │
│  6. Route next (another agent, or done)    │
└────────────────────────────────────────────┘
         │
         ├──→ Agent A (200K context) ──→ RESEARCH.md
         ├──→ Agent B (200K context) ──→ PLAN.md
         └──→ Agent C (200K context) ──→ SUMMARY.md

Example: `plan-phase` Orchestrator

Load STATE.md → current phase, decisions
CLI: Discover phase directory, context files
Spawn 4 researchers (parallel):
   - Stack researcher
   - Features researcher  
   - Architecture researcher
   - Pitfalls researcher
WAIT for all 4 to complete
Spawn research synthesizer → RESEARCH.md
WAIT for synthesis
Spawn planner → PLAN.md files
WAIT for planning
Spawn plan-checker → validation
If fails: loop back to step 7 (max 3x)
Update ROADMAP.md, commit
Report to user

Orchestrator stays at ~15% context. Heavy lifting in fresh agents.

Agent Roles

Each agent is a markdown file in agents/ with:

Frontmatter: Name, description, tools, skills, color
Role definition: Purpose, spawning context, responsibilities
Workflow instructions: Step-by-step execution protocol
Output specification: What artifact to create

Core Agents

gsd-planner

Purpose: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by: /gsd:plan-phase orchestrator Context loaded:

PROJECT.md (vision)
REQUIREMENTS.md (scoped requirements)
ROADMAP.md (current phase)
CONTEXT.md (user decisions from discuss-phase)
RESEARCH.md (domain knowledge)
Existing codebase patterns (via grep)

Outputs: XX-YY-PLAN.md files (2-3 tasks each) Key responsibilities:

Parse and honor user decisions from CONTEXT.md (NON-NEGOTIABLE)
Decompose phases into parallel-optimized plans
Build dependency graphs, assign execution waves
Derive must-haves using goal-backward methodology
Handle both standard planning and gap closure mode

Critical: Planner MUST honor locked decisions from CONTEXT.md. If user said “use library X”, plan must use library X, not an alternative.

Quality checks:

Every locked decision has a task implementing it
No task implements a deferred idea
Plans complete within ~50% context (2-3 tasks max)
Dependencies clearly marked

gsd-executor

Purpose: Executes plans atomically with per-task commits, deviation handling, and checkpoint protocols. Spawned by: /gsd:execute-phase orchestrator (one per plan in a wave) Context loaded:

PLAN.md (their assignment)
STATE.md (current position, decisions)
PROJECT.md (vision, constraints)
CONTEXT.md (user preferences)
CLAUDE.md (project-specific guidelines, if exists)
Project skills (if .claude/skills/ or .agents/skills/ exists)

Outputs:

Code implementation
Per-task git commits
XX-YY-SUMMARY.md

Key responsibilities:

Execute each task completely
Apply deviation rules automatically (handle blockers without stopping)
Commit atomically (one commit per task)
Pause at checkpoints (human-verify, decision, human-action)
Create SUMMARY.md with key decisions, deviations, next steps
Update STATE.md position

Execution patterns:

Pattern A: Fully autonomous (no checkpoints) → execute all, create summary, done
Pattern B: Has checkpoints → execute until checkpoint, STOP, return structured state
Pattern C: Continuation → verify previous commits, resume from specified task

Fresh context per plan: Each executor gets 200K tokens for implementation. Zero accumulated garbage, peak quality.

gsd-verifier

Purpose: Verifies phase achieved its GOAL (not just completed tasks) via goal-backward analysis. Spawned by: /gsd:execute-phase orchestrator (after all plans complete) Context loaded:

ROADMAP.md (phase goal)
REQUIREMENTS.md (must-haves with IDs)
All PLAN.md files (what was supposed to be built)
All SUMMARY.md files (what was claimed)
Codebase (what actually exists)

Outputs: XX-VERIFICATION.md Key responsibilities:

Verify goal achievement (not task completion)
Check must-haves against actual code
Cross-reference requirement IDs (traceability)
Identify gaps (stubs, missing features, broken wiring)
Flag items needing human verification

Critical mindset: Do NOT trust SUMMARY.md claims. Verify what ACTUALLY exists in code. Verification levels:

Truths: Must be demonstrably true (“User can log in with email”)
Artifacts: Files/features must exist and be substantive (not stubs)
Key Links: Wiring between components must work (API called correctly, props passed)

Outputs:

status: passed → all must-haves verified
status: human_needed → automated checks passed, manual testing required
status: gaps_found → missing features, stubs detected

gsd-plan-checker

Purpose: Validates plan quality before execution. Prevents bad plans from wasting execution cycles. Spawned by: /gsd:plan-phase orchestrator (after planner completes) Context loaded:

All PLAN.md files created by planner
ROADMAP.md (phase goal)
REQUIREMENTS.md (must-haves)
CONTEXT.md (user decisions)

Outputs: Pass/fail decision with feedback 8 verification dimensions:

Coverage: Plans achieve phase goal
Completeness: All phase requirements mapped to tasks
Atomicity: Each plan 2-3 tasks, completable in single context
Clarity: Tasks have clear actions and verification
Dependency logic: Wave assignments make sense
Decision fidelity: User’s locked decisions honored
Traceability: Requirements IDs present in plan frontmatter
Validation: Automated verify commands for each task (Nyquist validation)

Loop behavior: If fails, feedback returned to planner → revise → re-check (max 3 iterations)

gsd-phase-researcher

Purpose: Investigates domain knowledge before planning a phase. Spawned by: /gsd:plan-phase orchestrator (4 researchers in parallel) Specializations:

Stack researcher: Libraries, frameworks, best practices for the tech involved
Features researcher: How similar features are implemented in the wild
Architecture researcher: Patterns, structure, organization for this type of work
Pitfalls researcher: Common mistakes, gotchas, anti-patterns to avoid

Outputs: 4 markdown sections → synthesized into RESEARCH.md Tools: WebFetch, Context7 (MCP), grep (existing codebase patterns)

gsd-debugger

Purpose: Systematic debugging with persistent state, spawned for failures during verify-work. Spawned by: /gsd:verify-work orchestrator (when UAT fails) Context loaded:

UAT failure description
Related PLAN.md and SUMMARY.md
Codebase files involved

Outputs:

DEBUG-{slug}.md (debug session)
Root cause analysis
Verified fix plan (ready for execution)

Process:

Reproduce the issue
Trace execution (logs, network, state)
Identify root cause
Propose fix
Verify fix works
Create fix plan for /gsd:execute-phase --gaps-only

gsd-codebase-mapper

Purpose: Analyzes existing codebases for brownfield projects. Spawned by: /gsd:map-codebase orchestrator (4-7 agents in parallel) Outputs:

codebase/STACK.md (technologies, versions)
codebase/ARCHITECTURE.md (structure, patterns)
codebase/CONVENTIONS.md (code style, naming)
codebase/CONCERNS.md (debt, smells, risks)

Used by: /gsd:new-project — questions focus on what you’re ADDING, not re-documenting what exists

Supporting Agents

Agent	Purpose	Spawned By
gsd-roadmapper	Creates roadmaps from requirements	`/gsd:new-project`
gsd-research-synthesizer	Aggregates parallel research findings	`/gsd:plan-phase`
gsd-project-researcher	Project-level domain research	`/gsd:new-project`
gsd-integration-checker	Validates cross-boundary wiring	`/gsd:execute-phase` (optional)
gsd-nyquist-auditor	Maps test coverage to requirements	`/gsd:validate-phase`

Agent Communication

Agents do NOT communicate with each other. All communication flows through artifacts:

Orchestrator
    ↓
  Agent A → writes RESEARCH.md
    ↓
Orchestrator reads RESEARCH.md
    ↓
  Agent B → reads RESEARCH.md, writes PLAN.md
    ↓
Orchestrator reads PLAN.md
    ↓
  Agent C → reads PLAN.md, writes SUMMARY.md

This ensures:

Stateless agents: Each agent is independent, resumable
Artifact-driven: State lives in files (git-tracked, versioned)
Debuggable: You can read exactly what each agent saw and produced

Agent Spawning

Task Tool Syntax

Task(
  subagent_type="gsd-executor",
  model="claude-opus-4-20250514",  // From model profile
  prompt="
    <objective>
    Execute plan 03-02 of phase 03-user-authentication.
    </objective>

    <execution_context>
    @~/.claude/get-shit-done/workflows/execute-plan.md
    @~/.claude/get-shit-done/templates/summary.md
    </execution_context>

    <files_to_read>
    Read these files at execution start:
    - .planning/phases/03-user-authentication/03-02-PLAN.md
    - .planning/STATE.md
    - .planning/PROJECT.md
    </files_to_read>

    <success_criteria>
    - [ ] All tasks executed
    - [ ] Each task committed individually
    - [ ] SUMMARY.md created
    </success_criteria>
  "
)

Key elements:

subagent_type: Matches agent filename (gsd-executor.md)
model: From config’s model profile (quality/balanced/budget)
prompt: @-references for context, explicit file list, success criteria

Parallel vs Sequential

Parallel (multiple Task calls in one message):

Task(subagent_type="gsd-phase-researcher", prompt="Research stack...")
Task(subagent_type="gsd-phase-researcher", prompt="Research features...")
Task(subagent_type="gsd-phase-researcher", prompt="Research architecture...")
Task(subagent_type="gsd-phase-researcher", prompt="Research pitfalls...")
// All 4 run simultaneously

Sequential (one Task call, wait, next Task call):

Task(subagent_type="gsd-planner", ...)
// Wait for completion
// Read PLAN.md
Task(subagent_type="gsd-plan-checker", ...)
// Wait for validation

Task tool blocks — execution pauses until agent completes. No polling, no callbacks. This makes orchestration simple and reliable.

Model Profiles

Each agent uses a model tier based on the active profile:

Agent	Quality	Balanced	Budget
gsd-planner	Opus	Opus	Sonnet
gsd-executor	Opus	Sonnet	Sonnet
gsd-verifier	Sonnet	Sonnet	Haiku
gsd-phase-researcher	Opus	Sonnet	Haiku
gsd-debugger	Opus	Sonnet	Sonnet

Philosophy:

Quality: Opus for decisions, Sonnet for verification
Balanced: Opus for planning, Sonnet for everything else (default)
Budget: Sonnet for code, Haiku for research/verification

Switch profiles:

/gsd:set-profile budget

Agent Workflow Toggles

Some agents are optional (configurable via /gsd:settings):

Setting	Agent	Default	Purpose
`workflow.research`	gsd-phase-researcher	`true`	Domain research before planning
`workflow.plan_check`	gsd-plan-checker	`true`	Plan validation loop
`workflow.verifier`	gsd-verifier	`true`	Post-execution verification
`workflow.nyquist_validation`	gsd-nyquist-auditor	`true`	Test coverage mapping

Disable to speed up phases in familiar domains or conserve tokens.

Next Steps

Wave Execution

How parallel execution with dependencies works

State Management

STATE.md, decision tracking, session continuity

Overview

Getting Started

Core Concepts

Workflow

Guides

Advanced

Multi-Agent Orchestration

Why This Architecture?

Orchestrator Pattern

Responsibilities

Orchestrator Lifecycle

Example: `plan-phase` Orchestrator

Agent Roles

Core Agents

gsd-planner

gsd-executor

gsd-verifier

gsd-plan-checker

gsd-phase-researcher

gsd-debugger

gsd-codebase-mapper

Supporting Agents

Agent Communication

Agent Spawning

Task Tool Syntax

Parallel vs Sequential

Model Profiles

Agent Workflow Toggles

Next Steps

Wave Execution

State Management

Overview

Getting Started

Core Concepts

Workflow

Guides

Advanced

​Multi-Agent Orchestration

​Why This Architecture?

​Orchestrator Pattern

​Responsibilities

​Orchestrator Lifecycle

​Example: plan-phase Orchestrator

​Agent Roles

​Core Agents

​gsd-planner

​gsd-executor

​gsd-verifier

​gsd-plan-checker

​gsd-phase-researcher

​gsd-debugger

​gsd-codebase-mapper

​Supporting Agents

​Agent Communication

​Agent Spawning

​Task Tool Syntax

​Parallel vs Sequential

​Model Profiles

​Agent Workflow Toggles

​Next Steps

Wave Execution

State Management

Multi-Agent Orchestration

Why This Architecture?

Orchestrator Pattern

Responsibilities

Orchestrator Lifecycle

Example: `plan-phase` Orchestrator

Agent Roles

Core Agents

gsd-planner

gsd-executor

gsd-verifier

gsd-plan-checker

gsd-phase-researcher

gsd-debugger

gsd-codebase-mapper

Supporting Agents

Agent Communication

Agent Spawning

Task Tool Syntax

Parallel vs Sequential

Model Profiles

Agent Workflow Toggles

Next Steps