How gsd-build Coordinates Subagents Without Context Bleed: The Orchestrator Architecture

GSD-Build eliminates context bleed by using a lean orchestrator that delegates work to isolated sub-agents, each running in a fresh Claude-Code session with only relevant file references rather than embedded content.

The gsd-build/get-shit-done repository implements a novel multi-agent architecture that solves one of the hardest problems in AI-assisted software development: how to coordinate subagents without context bleed. By strictly separating the orchestration logic from execution logic, the system ensures that no single agent accumulates the entire project history, keeping each context window focused and efficient.

The Context Bleed Problem in Multi-Agent Systems

Context bleed occurs when an AI assistant retains information from previous tasks that should not influence current work. In traditional single-session approaches, as a project grows, the context window fills with irrelevant file contents, conversation history, and intermediate outputs. This contamination causes hallucinations, conflicting instructions, and degraded performance.

GSD-Build addresses this by ensuring no single Claude-Code session ever holds the full state of the entire project.

The Lean Orchestrator Pattern

At the heart of the architecture lies the orchestrator, implemented in commands/gsd/execute-phase.md and get-shit-done/workflows/execute-phase.md. This component acts as a traffic controller rather than a worker, consuming only approximately 15% of the total context budget.

Orchestrator Responsibilities in execute-phase.md

The orchestrator performs three critical functions:

1. Roadmap Parsing: Reads ROADMAP.md and STATE.md to understand current project status
2. Wave Grouping: Organizes plans into dependency-based waves for parallel execution
3. Sub-Agent Dispatch: Spawns isolated workers via the Task() primitive

Crucially, the orchestrator never embeds large file contents in its own context. It only passes paths to sub-agents, as seen in the execute-phase workflow definition at lines 99-105.

Context Budget Management

By strictly limiting its own context to ~15% of available tokens, the orchestrator maintains sufficient room to coordinate multiple waves of sub-agents without truncation. This lean approach contrasts with monolithic agents that attempt to hold entire codebases in context.

Isolated Sub-Agent Architecture

Sub-agents are the actual workers in the GSD-Build system. Each runs as a separate Claude-Code instance with a fresh ≈200KB context window, ensuring complete isolation from previous operations.

Fresh Context Per Task

The Task() primitive, documented in get-shit-done/workflows/execute-phase.md (lines 99-105), creates a hard boundary:

• No conversation history persists between tasks
• Each sub-agent receives only the explicitly provided prompt
• Context windows reset to zero tokens at spawn time

This architectural decision eliminates context bleed at the hardware level—there is simply no mechanism for information to leak between sessions.

Specialized Agent Types

GSD-Build defines distinct sub-agent roles, each optimized for specific tasks:

• gsd-planner: Creates implementation plans from phase requirements
• gsd-executor: Implements code changes and commits atomically
• gsd-verifier: Validates outcomes against must_haves criteria
• gsd-debugger: Diagnoses failures without access to previous execution context

Each agent type receives only the prompt template relevant to its function, as defined in get-shit-done/templates/planner-subagent-prompt.md (lines 9-15).

Wave-Based Execution Without Context Accumulation

GSD-Build groups independent plans into waves that execute simultaneously. This parallelism does not compromise context isolation because each plan runs in its own sub-agent.

The execute-phase workflow (lines 74-78) implements this pattern:

1. Wave Sequencing: Execute Wave 1 completely before Wave 2 begins
2. Parallel Dispatch: All plans within a wave spawn simultaneously via separate Task() calls
3. Result Aggregation: The orchestrator only collects SUMMARY.md paths and exit codes, not full execution logs

This approach maximizes throughput while maintaining the invariant that no single agent accumulates the work of multiple plans.

Reference-Based Prompt Engineering

Rather than embedding file contents directly into prompts, GSD-Build uses reference syntax (@path/to/file) that instructs sub-agents to read files independently within their own context windows.

The @ Syntax for File References

Prompt templates in get-shit-done/templates/planner-subagent-prompt.md (lines 9-15) demonstrate this pattern:

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

When the sub-agent receives this prompt, it issues its own Read calls to load these files. This ensures that:

• The orchestrator's context remains small (no file contents)
• The sub-agent only loads what it needs
• Large files never traverse the orchestrator-subagent boundary

Verification Without Memory Leak

The verification phase exemplifies this isolation. According to get-shit-done/templates/phase-prompt.md (lines 137-144), the gsd-verifier sub-agent:

1. Receives only the must_haves list and file paths
2. Reads the generated SUMMARY.md files directly
3. Examines the actual codebase (src/) to verify implementation
4. Reports back without accessing the orchestrator's execution history

This goal-backward verification ensures that validation is based on actual outcomes rather than the orchestrator's potentially stale memory.

Implementation Example: Spawning a Sub-Agent

The following excerpt from get-shit-done/workflows/execute-phase.md demonstrates how the orchestrator spawns an executor sub-agent while maintaining strict context boundaries:

Task(
  subagent_type="gsd-executor",
  model="{executor_model}",
  prompt="
    <objective>
      Execute plan {plan_number} of phase {phase_number}-{phase_name}.
      Commit each task atomically. Create SUMMARY.md. Update STATE.md.
    </objective>

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

    <files_to_read>
      - Plan: {phase_dir}/{plan_file}
      - State: .planning/STATE.md
    </files_to_read>
  "
)

Key observations about this implementation:

• No file content embedding: The orchestrator only passes paths like {phase_dir}/{plan_file} and .planning/STATE.md
• Reference syntax: Uses @ notation for workflow templates that the executor will read independently
• Fresh context: The Task() primitive ensures this executor runs in isolation with no access to previous wave executions

Summary

GSD-Build coordinates subagents without context bleed through a strict separation of concerns and architectural boundaries:

• Lean Orchestrator: The execute-phase command maintains only ~15% context budget, never embedding file contents, only passing paths
• Isolated Sub-Agents: Each Task() spawns a fresh Claude-Code session with ~200KB context, ensuring zero history leakage between plans
• Reference-Based Prompts: Using @path syntax instead of embedded content keeps orchestrator prompts small and delegates file reading to sub-agents
• Wave Parallelism: Grouping plans into waves allows parallel execution without shared state, with each plan running in its own isolated context
• Independent Verification: The gsd-verifier sub-agent validates outcomes by reading SUMMARY.md and source code directly, without accessing orchestrator memory

This architecture ensures that no single agent ever accumulates the full project state, eliminating context bleed while maintaining coordinated, multi-phase project execution.

Frequently Asked Questions

What is context bleed in AI coding assistants?

Context bleed occurs when an AI assistant retains information from previous tasks, conversations, or file contents that should not influence current work. As context windows fill with irrelevant historical data, the AI may hallucinate dependencies, apply outdated patterns, or generate conflicting code. GSD-Build prevents this by spawning each sub-agent in a fresh Claude-Code session with no access to previous conversation history.

How does the orchestrator maintain low context usage?

The orchestrator maintains low context usage by strictly limiting its role to coordination rather than execution. Implemented in commands/gsd/execute-phase.md, it consumes only ~15% of the available token budget by passing file paths rather than contents, using reference-based prompts with @ syntax, and delegating all file I/O to sub-agents. This lean approach allows the orchestrator to manage multiple execution waves without context truncation.

Can sub-agents communicate with each other directly?

No, sub-agents cannot communicate directly with each other. Each sub-agent runs as an isolated Claude-Code instance spawned via the Task() primitive, with no shared memory or conversation history. Communication occurs only through the filesystem (reading and writing STATE.md, SUMMARY.md, and source files) and through the orchestrator, which dispatches work and collects results. This strict isolation prevents context bleed between parallel executions.

What happens if a sub-agent fails during wave execution?

If a sub-agent fails during wave execution, the orchestrator detects the failure through the Task() return status and halts progression to the next wave. Because each plan runs in isolation, the failure does not corrupt the context of other agents in the same wave. The orchestrator can then spawn a gsd-debugger sub-agent with a fresh context to diagnose the specific failure, or retry the specific plan without reloading the entire project state into any single agent's context window.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}