Sub-Agent Orchestration Patterns

Why Sub-Agents?

A single AI agent, no matter how capable, has hard limits. Context windows fill up. Execution is sequential -- one tool call at a time, one file at a time. There is no redundancy: if the agent misinterprets a requirement, that misinterpretation propagates unchecked through every subsequent step. A single point of failure in both understanding and verification.

Sub-agents solve these limitations by introducing parallelism, isolation, specialization, and verification through separation. Instead of one agent doing everything, you split the work across multiple agent instances -- each with its own context window, its own execution loop, its own set of tools, and its own perspective on the problem. The coordination cost is real, but for tasks that are large, multi-faceted, or require independent verification, sub-agents produce measurably better results than any single-agent approach.

Per the SWE-Agent paper from Princeton NLP (arXiv:2310.03837), the highest-performing autonomous coding agents use multi-pass strategies where different passes apply different prompting strategies. This is sub-agent orchestration at its core: the same task, viewed through different lenses, produces a more robust solution than any single pass.

Three Core Patterns

All sub-agent orchestration boils down to three fundamental patterns. Every production framework -- Claude Code, Cursor 2.0, CrewAI, OpenAI Swarm -- implements some combination of these three.

Pattern 1: Parallel Isolation

Multiple agents work on independent tasks simultaneously. Each agent gets its own context window, its own working directory, and its own execution loop. The tasks must be genuinely independent -- no shared mutable state, no ordering dependencies.

Task Queue                          Results
    |                                  |
    v                                  ^
+--------+  +--------+  +--------+     |
|Agent A |  |Agent B |  |Agent C |     |
|Task 1  |  |Task 2  |  |Task 3  |     |
|Own ctx |  |Own ctx |  |Own ctx |     |
|Own dir |  |Own dir |  |Own dir |     |
+--------+  +--------+  +--------+     |
    |             |             |        |
    +------+------+-------------+--------+
           Merge / Aggregate

Claude Code implements parallel isolation through worktree-based isolation. When you spawn a sub-agent with isolation: worktree, Claude Code creates a separate Git worktree -- a full, independent checkout of the repository at a new path. Each sub-agent operates in complete filesystem isolation, reading and writing files in its own worktree without any risk of conflicting with other agents. This is the same mechanism Git uses for git worktree add, but orchestrated automatically by the agent framework.

The key requirement for parallel isolation: tasks must commute. If Task B depends on Task A's output, you cannot run them in parallel. The task decomposition must produce genuinely independent work units.

Pattern 2: Maker-Checker

One agent implements the solution. A separate agent reviews it. The writer and the reviewer are different model instances with different context -- preventing the fundamental self-blindness that plagues single-agent systems.

Maker Agent                    Checker Agent
    |                                |
    v                                |
+------------------+                 |
| Write code       |                 |
| Write tests      |                 |
| Run tests        |                 |
+------------------+                 |
    |                                |
    +-- Output (code + tests) ------>+
                                     v
                              +------------------+
                              | Review code      |
                              | Check edge cases |
                              | Verify tests     |
                              | Grade quality    |
                              +------------------+
                                     |
                                     v
                              Pass / Fail / Request Changes

This pattern exploits a principle well-documented in software engineering: separation of duties. The same cognitive biases that cause a developer to miss their own bugs cause an AI agent to miss its own errors. A fresh agent instance with a fresh context window approaches the code without the assumptions that guided its creation.

Claude Code uses the maker-checker pattern for code review. The agent that wrote the code is not the one that grades it. This is enforced at the framework level -- the code-review skill spawns a separate review agent with its own context, its own system prompt, and its own evaluation criteria. The review agent has no access to the maker's reasoning traces, only to the final code and test output. This eliminates confirmation bias.

In the SWE-Agent framework, the maker-checker pattern appears as multi-pass resolution. The agent attempts a fix, then re-evaluates its own solution from scratch. While this is a weaker form of maker-checker (same agent, different passes), it still produces better results than single-pass approaches because each pass starts with a clean context focused on a different objective.

Pattern 3: Specialized Delegation

Assign distinct roles to different agents -- each with its own system prompt, its own tool set, and its own domain expertise. The researcher agent has web search and document analysis tools. The coder agent has file editing and terminal tools. The tester agent has test runners and assertion frameworks. The reviewer agent has diff analysis and static checking tools.

Orchestrator
    |
    +-- Researcher Agent
    |       Tools: web_search, read_documents
    |       Prompt: "Gather requirements, analyze APIs, document dependencies"
    |
    +-- Coder Agent
    |       Tools: read, write, edit, bash
    |       Prompt: "Implement the solution following the research findings"
    |
    +-- Tester Agent
    |       Tools: bash (pytest, jest, cargo test)
    |       Prompt: "Write tests, run them, report failures with full context"
    |
    +-- Reviewer Agent
            Tools: read, diff analysis
            Prompt: "Review for correctness, security, performance, and style"

Claude Code implements specialized delegation through the .claude/agents/ directory. Each agent is defined as a Markdown file with its own name, system prompt, tool permissions, and behavioral constraints. The orchestrator (the main Claude Code session or a Workflow pipeline) delegates tasks to these specialized agents based on the current phase of work.

CrewAI provides the most explicit role-based delegation system. Each Agent has a role, goal, and backstory that shapes its behavior. The framework's documentation at docs.crewai.com describes how specialized agents produce higher-quality outputs than generalist agents because each agent's context is focused entirely on its domain.

OpenAI Swarm (github.com/openai/swarm), a lightweight multi-agent framework, implements specialized delegation through handoff functions. Each agent defines which other agents it can hand off to, creating explicit delegation pathways:

from swarm import Agent, handoff

researcher = Agent(
    name="Researcher",
    instructions="You research technical topics and provide structured findings.",
    functions=[handoff(coder)]
)

coder = Agent(
    name="Coder",
    instructions="You implement solutions based on research findings.",
    functions=[handoff(tester)]
)

tester = Agent(
    name="Tester",
    instructions="You write and run tests, then report results."
)

Implementation in Real Tools

Claude Code

Claude Code (github.com/anthropics/claude-code) provides the most complete sub-agent orchestration toolkit in production today. The three key mechanisms are:

1. .claude/agents/ directory: Each Markdown file defines a reusable sub-agent with its own name, system prompt, and allowed tools. These agents can be invoked by name from any Claude Code session.

2. Worktree isolation: The EnterWorktree tool creates an isolated Git worktree for a sub-agent. The sub-agent's file operations are completely sandboxed -- no other agent can see or modify its files. When the sub-agent completes, its worktree can be committed to a branch, merged, or discarded.

3. Workflow orchestration: The Workflow tool supports both pipeline and parallel execution modes. In pipeline mode, tasks flow through stages sequentially. In parallel mode, independent tasks execute concurrently, with the Workflow tool handling the merge.

4. Inter-agent communication: The SendMessage tool enables direct message passing between sub-agents. A researcher agent can send its findings to a coder agent without going through the orchestrator.

CrewAI

CrewAI (github.com/crewAIInc/crewAI) offers role-based delegation with two process modes. Sequential mode passes tasks linearly from agent to agent. Hierarchical mode adds a manager agent that dynamically delegates to workers. Each agent in a Crew has an independent context and tool set, and the framework handles all inter-agent message routing.

OpenAI Swarm

OpenAI Swarm (github.com/openai/swarm) is the minimalist end of the spectrum. It provides only handoff functions -- no shared state, no built-in parallelism, no orchestration. An agent calls handoff(other_agent) and control transfers. This simplicity makes Swarm ideal for proof-of-concept delegation patterns, but it lacks the isolation and parallelism infrastructure that production systems require.

Pipeline vs. Parallel: When to Use Which

One of the most consequential architectural decisions in sub-agent orchestration is whether to use pipeline execution (each work item passes through all stages before the next item starts) or parallel/barrier execution (all items go through stage 1, then all items go through stage 2).

Pipeline (per-item sequential):
  Item 1: [Research] -> [Code] -> [Test] -> [Review] --|
  Item 2:                                         [Research] -> [Code] -> [Test] -> [Review]
  Item 3:                                                                         [Research] -> ...
  Latency per item: T_research + T_code + T_test + T_review

Parallel/Barrier (per-stage sequential):
  Stage 1: [Research 1] [Research 2] [Research 3]  (parallel)
  Stage 2:            [Code 1]     [Code 2]     [Code 3]  (parallel)
  Stage 3:                        [Test 1]     [Test 2]     [Test 3]  (parallel)
  Stage 4:                                     [Review 1] [Review 2] [Review 3]
  Latency per item: T_total (all stages), but throughput is 3x

Pipeline is almost always better unless you genuinely need cross-item context at each stage. Here is why:

• Lower latency per item: The first result completes as soon as it finishes all stages, rather than waiting for all items to finish stage 1.
• Less memory pressure: Only one item is in flight per agent at a time, reducing peak context window usage.
• Easier debugging: Each item's journey through the pipeline is a linear trace, not a complex cross-referenced log.
• Natural for Claude Code worktrees: Each pipeline item gets its own worktree, completes its full lifecycle, and produces a mergeable result.

Use parallel/barrier execution only when:

• Later stages genuinely need to see all items from earlier stages (e.g., a reviewer that checks consistency across all implementations)
• You need to enforce a global quality standard that requires comparing all results
• Resource constraints prevent running all stages simultaneously

Maker-Checker Configuration in Claude Code

Here is a practical .claude/agents/ configuration implementing the maker-checker pattern. Two agent definitions -- one for implementation, one for review:

<!-- .claude/agents/implementer.md -->
# Implementer Agent

You are an implementation specialist. Your job is to write code that satisfies the given requirements.

## Rules
- Always write tests alongside implementation
- Run tests before marking a task complete
- Commit your work to the current branch with descriptive messages
- If tests fail, iterate up to 5 times before escalating

## Tools
- Read, Write, Edit, Bash (for running tests and builds)
- EnterWorktree (for isolated development)

## Output Format
- Return a summary of what you implemented
- Include the test results
- List any known limitations or trade-offs

<!-- .claude/agents/reviewer.md -->
# Reviewer Agent

You are a code review specialist. You review code written by another agent.

## Rules
- You did NOT write this code. Approach it with fresh eyes.
- Check for correctness, security vulnerabilities, and performance issues
- Verify that tests adequately cover the implementation
- Grade the implementation: PASS, PASS WITH NOTES, or REQUEST CHANGES
- Be specific about what needs to change -- point to files, line numbers, and exact issues

## Tools
- Read (for reviewing code)
- Bash (for running static analysis, linters, and tests)
- SendMessage (for returning review results to the orchestrator)

## Anti-Bias Guard
- Do not assume the implementer's intent was correct. Verify against the original requirements.
- Do not give credit for effort. Grade only the output quality.
- Flag anything that would not pass a senior engineer's code review.

The orchestrator -- a Workflow pipeline or the main Claude Code session -- invokes the implementer first, then passes its output to the reviewer. The reviewer has no access to the implementer's reasoning, only to the final code and test results. This separation is the entire point.

Anti-Patterns

Too Many Agents

There is a coordination tax for every agent you add. Each agent needs its own context loaded, its own task description, its own result collected and merged. Beyond 8 agents, the coordination overhead typically exceeds the parallelism benefit. Claude Code supports up to approximately 1000 sub-agents in theory, but the practical sweet spot is 3-8 agents. Cursor 2.0 caps at 8 parallel agents, which is a reasonable upper bound for most tasks.

The failure mode looks like this: you spawn 20 agents for a 20-file refactoring, but the orchestrator spends more time managing agent lifecycle (spawn, context load, result collection, merge) than the agents spend doing actual work. Net throughput goes down, not up.

Shared Mutable State

When multiple agents read and write the same files, you get race conditions. Agent A reads config.json, sees value X, and plans to update it to Y. Meanwhile Agent B reads config.json, sees value X, and updates it to Z. Agent A then writes Y, overwriting Agent B's change. Both agents believe they succeeded.

The fix is worktree isolation. Each agent works in its own copy of the filesystem. Merging happens explicitly, at a defined point, with conflict resolution. This is what Claude Code's worktree pattern provides, and what Git itself was designed for.

Identical Agents

Spawning three copies of the same agent with the same system prompt and same tools produces no diversity of perspective. You get the same errors three times, just faster. Sub-agents should differ meaningfully -- in their system prompts, their tools, their evaluation criteria, or their model parameters. If you need three agents to do the same task, you are better off with one agent doing it three times sequentially with different prompting strategies (the SWE-Agent multi-pass approach).

Scaling Considerations

Factor	Guideline	Rationale
Agent count	3-8 for most tasks	Beyond 8, coordination overhead exceeds parallelism gain
Context per agent	Minimum viable for its role	More context per agent means less total budget for other agents
Token budget	Allocate 60% to coders, 25% to reviewers, 15% to researchers	Code generation is token-hungry; review needs less but focused context
Concurrency limits	Match to API rate limits	Claude API has request-per-minute limits; parallel agents share these limits
Worktree count	One per parallel agent	No sharing worktrees between agents; defeats isolation
Model selection	Use smaller models for sub-agents when possible	Claude Haiku for sub-agents and Claude Sonnet/Opus for orchestrator can cut costs significantly

A practical approach: start with 2-3 agents. Measure the coordination overhead (time spent on task assignment, result collection, and merging versus actual work). Add agents only if the marginal throughput improvement justifies the marginal coordination cost.

Putting It All Together

The best sub-agent orchestration combines all three patterns. A typical production workflow for a multi-file feature:

1. Researcher agent (specialized delegation) analyzes the codebase, documents dependencies, and produces a structured implementation plan.
2. Coder agents (parallel isolation, 2-4 agents) each implement a subset of the plan in separate worktrees, running simultaneously.
3. Reviewer agent (maker-checker) reviews each coder's output, running tests and static analysis in a fresh context.
4. Orchestrator (pipeline) sequences these stages, collects results, handles failures, and manages the merge.

This combination is not theoretical. It matches the architecture of Claude Code's Workflow tool, Cursor 2.0's parallel agents with review, and CrewAI's hierarchical process with sequential task execution. The same pattern, implemented differently across tools, because it solves a real problem that single-agent systems cannot.

The orchestration overhead is the price you pay for reliability. A single agent is faster for trivial tasks. But for any task where the cost of a missed bug, a misunderstood requirement, or an untested edge case exceeds the cost of running a few extra agent instances, sub-agent orchestration is the engineering-correct choice.