LEGION — Parallel Execution at Scale

The instinct when a task is large is to make Claude work harder. Longer prompts, more context, more back-and-forth. This instinct is wrong for a specific class of tasks: tasks that decompose into independent work that can execute simultaneously.

A feature that touches 5 independent files can take 90 minutes as a sequential implementation and 20 minutes as a parallel one. The difference is not Claude's capability — it is the architecture of the work.

Multi-agent swarms deploy multiple Claude instances simultaneously, each working on an isolated piece of the implementation. This lesson covers when to use swarms, how to design them, how to manage context budgets, and how to resolve conflicts when agents produce incompatible outputs.

When to Auto-Trigger a Swarm

The LEGION skill defines explicit triggering conditions. All three must be met:

1. 3 or more independent files — the work decomposes into discrete, non-overlapping pieces
2. No sequential dependencies — no agent needs the output of another agent to start its work
3. Estimated > 20 minutes single-threaded — the overhead of coordination is justified

Examples of tasks that auto-trigger:

• "Add tests for all 6 API endpoints" (6 independent test files)
• "Migrate these 4 database models to the new ORM format" (4 independent model files)
• "Implement the notification module: email, SMS, push, and webhook handlers" (4 independent handlers)

Never auto-trigger for:

• Bug fixes (shared state, usually sequential)
• Tasks touching fewer than 3 files
• Tasks with output dependencies between parts (Agent A's output feeds Agent B)
• Shared state changes (database schema migrations, shared config changes)

If any of the "never trigger" conditions applies, swarms make the task harder, not easier. The coordination overhead exceeds the parallelism benefit, and shared state changes from multiple agents create conflicts that require more work to resolve than the parallelism saved.

Swarm Topologies

Not all parallel work has the same structure. Choose the topology that matches the work shape.

Parallel (independent agents, shared coordinator):

Coordinator
├── Agent A: feature A in isolation
├── Agent B: feature B in isolation
└── Agent C: feature C in isolation

Use when: multiple independent features or files, no shared state, coordinator merges results. This is the most common topology. The coordinator dispatches, waits for all agents to complete, reviews outputs, and resolves any conflicts.

Pipeline (sequential stages, parallel within stages):

Stage 1: 2 agents in parallel
    ↓
Stage 2: 3 agents in parallel (using Stage 1 output)
    ↓
Stage 3: Review agent

Use when: work has phases where within-phase tasks are independent but cross-phase tasks depend on the previous stage. Example: Phase 1 (schema design) feeds Phase 2 (implementation of multiple services using the schema).

Hierarchical (coordinator with sub-coordinators):

Master Coordinator
├── Sub-coordinator 1
│   ├── Agent A
│   └── Agent B
└── Sub-coordinator 2
    ├── Agent C
    └── Agent D

Use when: very large tasks with natural groupings. Each sub-coordinator manages a logical subsystem. Master coordinator resolves cross-subsystem conflicts. High overhead — only justified for tasks that genuinely require 6+ agents.

Mesh (agents that communicate with each other):

Use only for research or exploration tasks where agents need to share intermediate findings. Not recommended for implementation tasks — the cross-agent communication creates unpredictable dependencies.

Context Budgets Per Agent Type

Each agent type has a recommended context budget. Exceeding these limits causes context overflow, which degrades quality.

| Agent Type | Context Budget | What it covers | |-----------|----------------|----------------| | Implementer | 300 tokens | Task description, file to implement, interface contract | | Reviewer | 500 tokens | Implementation to review, review criteria, domain checklist | | Debugger | 400 tokens | Bug description, reproduction steps, evidence collected | | Researcher | 200 tokens | Research question, scope boundaries | | Coordinator | 600 tokens | Task decomposition, agent assignments, merge strategy |

These budgets are tight for a reason. Agents with smaller context budgets are more focused. A 300-token implementer context forces you to define the task precisely — which produces a better implementation than a 2000-token context where the agent has to figure out what you actually want.

The context budget template for an implementer agent:

TASK: Implement the email notification handler
FILE: src/notifications/email_handler.py
INTERFACE: Must satisfy the NotificationHandler protocol (see below)
CONSTRAINTS: Use only the SMTP client already in lib/smtp_client.py
TESTS: Tests at tests/test_email_handler.py — make them pass

[Paste the interface definition: ~50 tokens]
[Paste the failing test file: ~150 tokens]
[Remaining budget: ~100 tokens for task-specific context]

Dispatching Agents

When you decide to use a swarm, announce the topology before dispatching:

SWARM ACTIVATION
━━━━━━━━━━━━━━━━━━━━━━━━━━
Trigger: 4 independent notification handlers, no shared state
Topology: Parallel
Agents: 4 implementers + 1 coordinator
Agent contexts:
  - Email handler: email_handler.py, tests/test_email_handler.py
  - SMS handler: sms_handler.py, tests/test_sms_handler.py
  - Push handler: push_handler.py, tests/test_push_handler.py
  - Webhook handler: webhook_handler.py, tests/test_webhook_handler.py
Merge plan: Run all tests, resolve interface conflicts, coordinator review
━━━━━━━━━━━━━━━━━━━━━━━━━━

This announcement creates a shared plan before any code is written. You can review and correct the decomposition before agents start working.

Dispatch each agent with the isolated worktree pattern:

isolation: worktree

This gives each agent a separate git branch and working directory, preventing file conflicts during parallel execution.

Conflict Resolution

When agents complete, their outputs sometimes conflict. The coordinator's job is to identify and resolve conflicts before merging.

Types of conflicts and resolution strategies:

Interface conflicts: Agent A implemented a function as send_notification(user_id, message) and Agent B implemented it as send_notification(user_id, message, channel). Resolution: establish the interface in the coordinator before dispatching agents. The coordinator defines the contract; agents implement to the contract.

Import conflicts: Multiple agents added different versions of the same import or both added entries to a shared registry file. Resolution: coordinator handles all shared file writes. Agents that need shared file changes flag them but do not write them.

Style conflicts: One agent used async/await, another used callbacks. Resolution: establish the style convention in the task dispatch. Include a one-sentence style note in each agent's context.

Logic conflicts: Two agents implemented the same feature differently (one uses caching, one does not). Resolution: coordinator reviews both implementations and selects or merges the best approach. Both implementations may be valid; pick the one that better fits the system constraints.

Byzantine fault tolerance: For high-stakes implementations (security code, financial calculations), deploy 3 agents with the same task and use majority vote for the final implementation. If 2 of 3 agents produce equivalent outputs, use that. If all 3 differ significantly, escalate to human review. This is expensive but catches subtle implementation errors.

Merge Protocol

When all agents complete:

1. Run all tests for all modified files
2. Check for interface conflicts across agent outputs
3. Check for shared file conflicts (imports, registries, config)
4. Resolve conflicts using the strategies above
5. Run the full test suite (not just the agent-specific tests)
6. Invoke SENTINEL confidence gate
7. Invoke tribunal with DOMAIN set appropriately

Do not mark the task complete until step 7. Merging agent outputs often reveals integration issues that individual agents' tests did not catch.

The Coordinator Role

The coordinator is not an agent that writes code. It is a planning and integration role.

Before dispatching:

• Define the interface contracts every agent must satisfy
• Identify shared files and designate who handles them (usually: coordinator only)
• Specify style and pattern conventions in a shared context block
• Establish the merge sequence (which agents depend on which others)

After all agents complete:

• Review each agent's output for quality and interface compliance
• Run the full test suite
• Identify and resolve conflicts
• Write the integration layer if agents produced independent modules
• Verify the integrated system works end-to-end

The coordinator may be Claude itself in a fresh session, or it may be you manually reviewing and merging agent outputs. For complex swarms (6+ agents), the coordinator should be a dedicated Claude session with a high context budget.

What Multi-Agent Swarms Are Not

Swarms are not a shortcut for tasks that are just large. A 300-line function is not a swarm task just because it is large — it is a single-agent implementation with a planning phase.

Swarms are not appropriate when agents would need to communicate during execution. Once agents are dispatched, they work in isolation. If Agent A's output affects what Agent B should do, the work is sequential, not parallel.

Swarms are not automatic. The triggering conditions exist for a reason. Forcing a swarm on sequential work creates merge conflicts, interface mismatches, and a coordination overhead that makes the task take longer.

Estimating the Speedup

The theoretical speedup is the single-threaded time divided by the number of parallel agents. In practice, coordination overhead, merge time, and conflict resolution reduce this.

Practical speedup estimates:

• 3-4 parallel implementers: 2-3× speedup over sequential
• 5-6 parallel implementers: 2.5-4× speedup
• 7+ parallel implementers: diminishing returns, rarely more than 4×

The overhead floor is approximately 20 minutes (dispatch, coordination, merge, verification). A task that would take 25 minutes single-threaded should not use a swarm — the overhead exceeds the benefit. A task that would take 90 minutes single-threaded benefits significantly from a 3-agent swarm (target: 30-40 minutes).

Key Takeaway

Multi-agent swarms are a coordination architecture for work that genuinely decomposes into parallel, independent tasks. Trigger conditions are strict: 3+ independent files, no sequential dependencies, estimated > 20 minutes single-threaded. Choose topology based on work shape: parallel for independent tasks, pipeline for phased work, hierarchical for very large systems. Keep agent context budgets tight (300 tokens for implementers). The coordinator owns interface contracts, shared files, and conflict resolution. Run the full test suite and verification gate after merging all agent outputs. Swarms are not a shortcut for large sequential tasks — they are an architecture for genuinely parallel work.