gh-basher83-lunar-claude-plugins-meta-meta-claude/skills/multi-agent-composition/examples/case-studies.md

# Multi-Agent Case Studies

Real-world examples of multi-agent systems in production, drawn from field experience.

## Case Study Index

| # | Name | Pattern | Agents | Key Lesson |
|---|------|---------|--------|------------|
| 1 | AI Docs Loader | Sub-agent delegation | 8-10 | Parallel work without context pollution |
| 2 | SDK Migration | Scout-plan-build | 6 | Search + plan + implement workflow |
| 3 | Codebase Summarization | Orchestrator + QA | 3 | Divide and conquer with synthesis |
| 4 | UI Component Creation | Scout-builder | 2 | Precise targeting before building |
| 5 | PLAN-BUILD-REVIEW-SHIP | Task board lifecycle | 4 | Quality gates between phases |
| 6 | Meta-Agent System | Agent building agents | Variable | Recursive agent creation |
| 7 | Observability Dashboard | Fleet monitoring | 5-10+ | Real-time multi-agent visibility |
| 8 | AFK Agent Device | Autonomous background work | 3-5 | Out-of-loop while you sleep |

---

## Case Study 1: AI Docs Loader

**Pattern:** Sub-agent delegation for parallel work

**Problem:** Loading 10 documentation URLs consumes 30k+ tokens per scrape. Single agent would hit 150k+ tokens.

**Solution:** Delegate each scrape to isolated sub-agent

**Architecture:**

```text
Primary Agent (9k tokens)
├→ Sub-Agent 1: Scrape doc 1 (3k tokens, isolated)
├→ Sub-Agent 2: Scrape doc 2 (3k tokens, isolated)
├→ Sub-Agent 3: Scrape doc 3 (3k tokens, isolated)
...
└→ Sub-Agent 10: Scrape doc 10 (3k tokens, isolated)

Total work: 39k tokens
Primary agent: Only 9k tokens ✅
Context protected: 30k tokens kept out of primary
```

**Implementation:**

```bash
# Single command
/load-ai-docs

# Agent reads list from ai-docs/README.md
# For each URL older than 24 hours:
#   - Spawn sub-agent
#   - Sub-agent scrapes URL
#   - Sub-agent saves to file
#   - Sub-agent reports completion
# Primary agent never sees scrape content
```

**Key techniques:**

- **Sub-agents for isolation** - Each scrape in separate context
- **Parallel execution** - All 10 scrapes run simultaneously
- **Context delegation** - 30k tokens stay out of primary

**Results:**

- **Time:** 10 scrapes in parallel vs. sequential (10x faster)
- **Context:** Primary agent stays at 9k tokens throughout
- **Scalability:** Can handle 50+ URLs without primary context issues

**Source:** Elite Context Engineering transcript

---

## Case Study 2: SDK Migration

**Pattern:** Scout-plan-build with multiple perspectives

**Problem:** Migrating codebase to new Claude Agent SDK across 8 applications

**Challenge:**

- 100+ files potentially affected
- Agent reading everything = 150k+ tokens
- Planning without full context = mistakes

**Solution:** Three-phase workflow with delegation

**Phase 1: Scout (Reduce context for planner)**

```text
Orchestrator spawns 4 scout agents (parallel):
├→ Scout 1: Gemini Lightning (fast, different perspective)
├→ Scout 2: CodeX (specialized for code search)
├→ Scout 3: Gemini Flash Preview
└→ Scout 4: Haiku (cheap, fast)

Each scout:
- Searches codebase for SDK usage
- Identifies exact files and line numbers
- Notes patterns (e.g., "system prompt now explicit")

Output: relevant-files.md (5k tokens)
├── File paths
├── Line number offsets
├── Character ranges
└── Relevant code snippets
```

**Why multiple models?** Diverse perspectives catch edge cases single model might miss.

**Phase 2: Plan (Focus on relevant subset)**

```text
Planner agent (new instance):
├── Reads relevant-files.md (5k tokens)
├── Scrapes SDK documentation (8k tokens)
├── Analyzes migration patterns
└── Creates detailed-plan.md (3k tokens)

Context used: 16k tokens
vs. 150k if reading entire codebase
Savings: 89% reduction
```

**Phase 3: Build (Execute plan)**

```text
Builder agent (new instance):
├── Reads detailed-plan.md (3k tokens)
├── Implements changes across 8 apps
├── Updates system prompts
├── Tests each application
└── Reports completion

Context used: ~80k tokens
Still within safe limits
```

**Final context analysis:**

```text
If single agent:
├── Search: 40k tokens
├── Read files: 60k tokens
├── Plan: 20k tokens
├── Implement: 30k tokens
└── Total: 150k tokens (75% used)

With scout-plan-build:
├── Primary orchestrator: 10k tokens
├── 4 scouts (parallel, isolated): 4 × 15k = 60k total, 0k in primary
├── Planner (new agent): 16k tokens
├── Builder (new agent): 80k tokens
└── Max per agent: 80k tokens (40% per agent)
```

**Key techniques:**

- **Composable workflows** - Chain /scout, /plan, /build
- **Multiple scout models** - Diverse perspectives
- **Context offloading** - Scouts protect planner's context
- **Fresh agents per phase** - No context accumulation

**Results:**

- **8 applications migrated** successfully
- **51% context used** in builder phase (safe margins)
- **No context explosions** across entire workflow
- **Completed in single session** (~30 minutes)

**Near miss:** "We were 14% away from exploding our context" due to autocompact buffer

**Lesson:** Disable autocompact buffer. That 22% matters at scale.

**Source:** Claude 2.0 transcript

---

## Case Study 3: Codebase Summarization

**Pattern:** Orchestrator with specialized QA agents

**Problem:** Summarize large codebase (frontend + backend) with architecture docs

**Approach:** Divide and conquer with synthesis

**Architecture:**

```text
Orchestrator Agent
├→ Creates Frontend QA Agent
│  ├─ Summarizes frontend components
│  └─ Outputs: frontend-summary.md
├→ Creates Backend QA Agent
│  ├─ Summarizes backend APIs
│  └─ Outputs: backend-summary.md
└→ Creates Primary QA Agent
   ├─ Reads both summaries
   ├─ Synthesizes unified view
   └─ Outputs: codebase-overview.md
```

**Orchestrator behavior:**

```text
1. Parse user request: "Summarize codebase"
2. Create 3 agents with specialized tasks
3. Command each agent with detailed prompts
4. SLEEP (not observing their work)
5. Wake every 15s to check status
6. Agents complete → Orchestrator wakes
7. Collect results (read produced files)
8. Summarize for user
9. Delete all 3 agents
```

**Prompts from orchestrator:**

```markdown
Frontend QA Agent:
"Analyze all files in src/frontend/. Create markdown summary with:
- Key components and their responsibilities
- State management approach
- Routing structure
- Technology stack
Output to docs/frontend-summary.md"

Backend QA Agent:
"Analyze all files in src/backend/. Create markdown summary with:
- API endpoints and their purposes
- Database schema
- Authentication/authorization
- External integrations
Output to docs/backend-summary.md"

Primary QA Agent:
"Read frontend-summary.md and backend-summary.md. Create unified overview with:
- High-level architecture
- How components interact
- Data flow
- Key technologies
Output to docs/codebase-overview.md"
```

**Observability interface shows:**

```text
[Agent 1] Frontend QA
├── Status: Complete ✅
├── Context: 28k tokens used
├── Files consumed: 15 files
├── Files produced: frontend-summary.md
└── Time: 45 seconds

[Agent 2] Backend QA
├── Status: Complete ✅
├── Context: 32k tokens used
├── Files consumed: 12 files
├── Files produced: backend-summary.md
└── Time: 52 seconds

[Agent 3] Primary QA
├── Status: Complete ✅
├── Context: 18k tokens used
├── Files consumed: 2 files (summaries)
├── Files produced: codebase-overview.md
└── Time: 30 seconds

Orchestrator:
├── Context: 12k tokens (commands only, not observing work)
├── Total time: 52 seconds (parallel execution)
└── All agents deleted after completion
```

**Key techniques:**

- **Parallel frontend/backend** - 2x speedup
- **Orchestrator sleeps** - Protects its context
- **Synthesis agent** - Combines perspectives
- **Deletable agents** - Freed after use

**Results:**

- **3 comprehensive docs** created
- **Max context per agent:** 32k tokens (16%)
- **Orchestrator context:** 12k tokens (6%)
- **Time:** 52 seconds (vs. 2+ minutes sequential)

**Source:** One Agent to Rule Them All transcript

---

## Case Study 4: UI Component Creation

**Pattern:** Scout-builder two-stage

**Problem:** Create gray pills for app header information display

**Challenge:** Codebase has specific conventions. Need to find exact files and follow patterns.

**Solution:** Scout locates, builder implements

**Phase 1: Scout**

```text
Scout Agent:
├── Task: "Find header UI component files"
├── Searches for: header, display, pills, info components
├── Identifies patterns: existing pill styles, color conventions
├── Locates exact files:
│   ├── src/components/AppHeader.vue
│   ├── src/styles/pills.css
│   └── src/utils/formatters.ts
└── Outputs: scout-header-report.md with:
    ├── File locations
    ├── Line numbers for modifications
    ├── Existing patterns to follow
    └── Recommended approach
```

**Phase 2: Builder**

```text
Builder Agent:
├── Reads scout-header-report.md
├── Follows identified patterns
├── Creates gray pill components
├── Applies consistent styling
├── Outputs modified files with exact changes
└── Context: Only 30k tokens (vs. 80k+ without scout)
```

**Orchestrator involvement:**

```text
1. User prompts: "Create gray pills for header"
2. Orchestrator creates Scout
3. Orchestrator SLEEPS (checks every 15s)
4. Scout completes → Orchestrator wakes
5. Orchestrator reads scout output
6. Orchestrator creates Builder with detailed instructions
7. Orchestrator SLEEPS again
8. Builder completes → Orchestrator wakes
9. Orchestrator reports results
10. Orchestrator deletes both agents
```

**Key techniques:**

- **Scout reduces uncertainty** - Builder knows exactly where to work
- **Pattern following** - Scout identifies conventions
- **Orchestrator sleep** - Two phases, minimal orchestrator context
- **Precise targeting** - No wasted reads

**Results:**

- **Scout:** 15k tokens, 20 seconds
- **Builder:** 30k tokens, 35 seconds
- **Orchestrator:** 8k tokens final
- **Total time:** 55 seconds
- **Feature shipped** correctly on first try

**Source:** One Agent to Rule Them All transcript

---

## Case Study 5: PLAN-BUILD-REVIEW-SHIP Task Board

**Pattern:** Structured lifecycle with quality gates

**Problem:** Ensure all changes go through proper review before shipping

**Architecture:**

```text
Task Board Columns:
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│  PLAN   │→ │  BUILD  │→ │ REVIEW  │→ │  SHIP   │
└─────────┘  └─────────┘  └─────────┘  └─────────┘
```

**Example task: "Update HTML titles"**

**Column 1: PLAN**

```text
Planner Agent:
├── Analyzes requirement
├── Identifies affected files:
│   ├── index.html
│   └── src/App.tsx (has <title> in render)
├── Creates implementation plan:
│   1. Update index.html <title>
│   2. Update App.tsx header component
│   3. Test both pages load correctly
└── Moves task to BUILD column
```

**Column 2: BUILD**

```text
Builder Agent:
├── Reads plan from PLAN column
├── Implements changes:
│   ├── index.html: "Plan Build Review Ship"
│   └── App.tsx: header="Plan Build Review Ship"
├── Runs tests: All passing ✅
└── Moves task to REVIEW column
```

**Column 3: REVIEW**

```text
Reviewer Agent:
├── Reads plan and implementation
├── Checks:
│   ├── Plan followed? ✅
│   ├── Tests passing? ✅
│   ├── Code quality? ✅
│   └── No security issues? ✅
├── Approves changes
└── Moves task to SHIP column
```

**Column 4: SHIP**

```text
Shipper Agent:
├── Creates git commit
├── Pushes to remote
├── Updates deployment
└── Marks task complete
```

**Orchestrator's role:**

```text
- NOT micromanaging each step
- Responding to user commands like "Move task to next phase"
- Tracking task state in database
- Providing UI showing current phase
- Can intervene if phase fails (e.g., tests fail in BUILD)
```

**UI representation:**

```text
Task: Update Titles
├── Status: REVIEW
├── Assigned: reviewer-agent-003
├── History:
│   ├── PLAN: planner-001 (completed 2m ago)
│   ├── BUILD: builder-002 (completed 1m ago)
│   └── REVIEW: reviewer-003 (in progress)
└── Files modified: 2
```

**Key techniques:**

- **Clear phases** - No ambiguity about current state
- **Quality gates** - Can't skip to SHIP without REVIEW
- **Agent specialization** - Each agent expert in its phase
- **Failure isolation** - If BUILD fails, PLAN preserved

**Results:**

- **Zero shipping untested code** (REVIEW gate catches issues)
- **Clear audit trail** (who did what in which phase)
- **Parallel tasks** (multiple agents in different columns)
- **Single interface** (user sees all tasks across all phases)

**Source:** Custom Agents transcript

---

## Case Study 6: Meta-Agent System

**Pattern:** Agents building agents

**Problem:** Need new specialized agent but don't want to hand-write configuration

**Solution:** Meta-agent that builds other agents

**Meta-agent prompt:**

```markdown
# meta-agent.md

You are a meta-agent that builds new sub-agents from user descriptions.

When user says "build a new sub-agent":
1. Ask what the agent should do
2. Fetch Claude Code sub-agent documentation
3. Design system prompt for new agent
4. Create agent configuration file
5. Test agent with sample prompts
6. Report usage examples

Output: .claude/agents/<agent-name>.md with complete configuration
```

**Example: Building TTS summary agent**

**User:** "Build agent that summarizes what my code does using text-to-speech"

**Meta-agent process:**

```text
Step 1: Understand requirements
├── Parse: "summarize code" + "text-to-speech"
├── Infer: Needs code reading + TTS API access
└── Clarify: Voice provider? (user chooses 11Labs)

Step 2: Fetch documentation
├── Reads Claude Code sub-agent docs
├── Reads 11Labs API docs
└── Understands agent configuration format

Step 3: Design system prompt
├── Purpose: Concise code summaries via voice
├── Tools needed: read files, 11Labs TTS
├── Response format: Audio file output
└── Trigger: "use TTS summary"

Step 4: Create configuration
Writes .claude/agents/tts-summary.md:
---
name: tts-summary
description: Concisely summarizes code with text-to-speech. Trigger: "TTS summary"
---
Purpose: Review user's code and provide 1-sentence summary via 11Labs voice
[... full system prompt ...]

Step 5: Test
├── Runs test prompt: "TTS summary for hooks.py"
├── Agent reads file, generates summary
├── Outputs audio with summary
└── Validates: Works correctly ✅

Step 6: Report
├── Explains how to use new agent
├── Shows example prompts
└── Notes: Can adjust voice, length, etc.
```

**Result:** Fully functional TTS summary agent created from natural language description

**Recursion depth:**

```text
Level 0: Human user
  └→ Level 1: Meta-agent (builds agents)
      └→ Level 2: TTS summary agent (built by meta-agent)
          └→ Level 3: Sub-agents (if TTS agent spawns any)
```

**Key techniques:**

- **Documentation fetching** - Meta-agent reads official docs
- **Template following** - Follows agent configuration patterns
- **Validation loop** - Tests before declaring success
- **Recursive creation** - Agents can build agents

**Challenges:**

- **Dependency coupling** - New agent depends on meta-agent's understanding
- **Debugging difficulty** - If generated agent fails, hard to trace
- **Version drift** - Meta-agent's docs knowledge may become outdated

**Results:**

- **New agent in ~2 minutes** vs. 15+ minutes manually
- **Follows best practices** automatically
- **Tested before delivery**
- **Documented usage**

**Source:** Sub-Agents transcript

---

## Case Study 7: Observability Dashboard

**Pattern:** Real-time multi-agent monitoring

**Problem:** Running 5-10 agents simultaneously. Can't see what they're doing.

**Solution:** Centralized observability system

**Architecture:**

```text
┌──────────────────── Multiple Agents ────────────────────┐
│  Agent 1    Agent 2    Agent 3    Agent 4    Agent 5    │
│    ↓          ↓          ↓          ↓          ↓        │
│             pre/post-tool-use hooks                      │
│                        ↓                                 │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────── Bun Server ─────────────────────────┐
│  POST /events endpoint                                   │
│         ├→ Store in SQLite (persistence)                 │
│         └→ Broadcast via WebSocket (real-time)           │
└──────────────────────────────────────────────────────────┘
                         ↓
┌──────────────────── Web Client ─────────────────────────┐
│  ┌─────────────────────────────────────────────────┐    │
│  │ Live Activity Pulse (1min/3min/5min windows)    │    │
│  ├─────────────────────────────────────────────────┤    │
│  │ Event Stream (filtered by app/session/type)     │    │
│  ├─────────────────────────────────────────────────┤    │
│  │ Event Details (with AI-generated summaries)     │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────┘
```

**Hook implementation:**

```python
# .claude/hooks/post-tool-use.py
import sys, json, subprocess

def main():
    event = json.load(sys.stdin)

    # Send to observability server (with AI summary)
    subprocess.run([
        "uv", "run",
        ".claude/hooks/utils/send-event.py",
        "my-codebase",          # App name
        "post-tool-use",        # Event type
        "--summarize"           # Generate Haiku summary
    ], input=json.dumps(event), text=True)

if __name__ == "__main__":
    main()
```

**What user sees:**

```text
┌─────────────── Live Activity Pulse ───────────────┐
│ ▂▄▆█▆▄▂▁ Agent A (very active)                    │
│ ▁▁▂▂▃▃▂▂ Agent B (moderate activity)              │
│ ▂▂▂▂▂▂▂▂ Agent C (steady work)                    │
│ ▁▁▁█▁▁▁▁ Agent D (spike, then quiet)              │
└────────────────────────────────────────────────────┘

┌─────────────── Event Stream ──────────────────────┐
│ [Agent A] post-tool-use                            │
│   Summary: "Wrote authentication logic to user.py"│
│   Time: 2s ago                                     │
├────────────────────────────────────────────────────┤
│ [Agent B] sub-agent-stop                           │
│   Summary: "Completed documentation scrape"        │
│   Time: 5s ago                                     │
├────────────────────────────────────────────────────┤
│ [Agent C] notification                             │
│   Summary: "Needs approval for rm command"         │
│   Time: 8s ago                                     │
└────────────────────────────────────────────────────┘
```

**Filtering:**

```text
Filters available:
├── By app (codebase-1, codebase-2, etc.)
├── By agent session ID
├── By event type (pre-tool, post-tool, stop, etc.)
└── By time window (1min, 3min, 5min)
```

**Event summarization:**

```python
# Each event summarized by Haiku ($0.0002 per event)
Event: post-tool-use for Write tool
Input: {file: "auth.py", content: "...500 lines..."}
Output: Success

Summary generated:
"Implemented JWT authentication with refresh tokens in auth.py"

Cost: $0.0002
Human value: Instant understanding without reading 500 lines
```

**Key techniques:**

- **One-way data stream** - Simple, fast, scalable
- **Edge summarization** - AI summaries generated at hook time
- **Dual storage** - SQLite (history) + WebSocket (real-time)
- **Color coding** - Consistent colors per agent session

**Results:**

- **5-10 agents monitored** simultaneously
- **Thousands of events logged** (cost: ~$0.20)
- **Real-time visibility** into all agent work
- **Historical analysis** via SQLite queries

**Business value:**

- **Catch errors fast** (notification events = agent blocked)
- **Optimize workflows** (which tools used most?)
- **Debug issues** (what happened before failure?)
- **Scale confidence** (can observe 10+ agents easily)

**Source:** Multi-Agent Observability transcript

---

## Case Study 8: AFK Agent Device

**Pattern:** Autonomous background work while you're away

**Problem:** Long-running tasks block your terminal. You want to work on something else.

**Solution:** Dedicated device running agent fleet

**Architecture:**

```text
Your Device (interactive):
├── Claude Code session
├── Send job to agent device
└── Monitor status updates

Agent Device (autonomous):
├── Picks up job from queue
├── Executes: Scout → Plan → Build → Ship
├── Reports status every 60s
└── Ships results to git
```

**Workflow:**

```bash
# From your device
/afk-agents \
  --prompt "Build 3 OpenAI SDK agents: basic, with-tools, realtime-voice" \
  --adw "plan-build-ship" \
  --docs "https://openai-agent-sdk.com/docs"

# Job sent to dedicated device
# You continue working on your device
# Background: Agent device executes workflow
```

**Agent device execution:**

```text
[00:00] Job received: Build 3 SDK agents
[00:05] Planner agent created
[00:45] Plan complete: 3 agents specified
[01:00] Builder agent 1 created (basic agent)
[02:30] Builder agent 1 complete: basic-agent.py ✅
[02:35] Builder agent 2 created (with tools)
[04:15] Builder agent 2 complete: agent-with-tools.py ✅
[04:20] Builder agent 3 created (realtime voice)
[07:45] Builder agent 3 partial: needs audio libraries
[08:00] Builder agent 3 complete: realtime-agent.py ⚠️ (partial)
[08:05] Shipper agent created
[08:20] Git commit created
[08:25] Pushed to remote
[08:30] Job complete ✅
```

**Status updates (every 60s):**

```text
Your device shows:

[60s] Status: Planning agents...
[120s] Status: Building agent 1 of 3...
[180s] Status: Building agent 2 of 3...
[240s] Status: Building agent 3 of 3...
[300s] Status: Testing agents...
[360s] Status: Shipping to git...
[420s] Status: Complete ✅

Click to view: results/sdk-agents-20250105/
```

**What you do:**

```text
1. Send job (10 seconds)
2. Go AFK (work on something else)
3. Get notified when complete (7 minutes later)
4. Review results
```

**Key techniques:**

- **Job queue** - Agents pick up work from queue
- **Async status** - Reports back periodically
- **Autonomous execution** - No human in the loop
- **Git integration** - Results automatically committed

**Results:**

- **3 SDK agents built** in 7 minutes
- **You worked on other things** during that time
- **Autonomous end-to-end** - plan + build + test + ship
- **Code review** - Quick glance confirms quality

**Infrastructure required:**

- Dedicated machine (M4 Mac Mini, cloud VM, etc.)
- Agent queue system
- Job scheduler
- Status reporting

**Use cases:**

- Long-running builds
- Overnight work
- Prototyping experiments
- Documentation generation
- Codebase refactors

**Source:** Claude 2.0 transcript

---

## Cross-Cutting Patterns

### Pattern: Context Window as Resource Constraint

**Appears in:**

- Case 1: Sub-agent delegation protects primary
- Case 2: Scout-plan-build reduces planner context
- Case 3: Orchestrator sleeps to protect its context
- Case 8: Fresh agents for each phase (no accumulation)

**Lesson:** Context is precious. Protect it aggressively.

### Pattern: Specialized Agents Over General

**Appears in:**

- Case 3: Frontend/Backend/QA agents vs. one do-everything agent
- Case 4: Scout finds, builder builds (not one agent doing both)
- Case 5: Planner/builder/reviewer/shipper (4 specialists)
- Case 6: Meta-agent only builds, doesn't execute

**Lesson:** "A focused agent is a performant agent."

### Pattern: Observability Enables Scale

**Appears in:**

- Case 3: Orchestrator tracks agent status
- Case 5: Task board shows current phase
- Case 7: Real-time dashboard for all agents
- Case 8: Status updates every 60s

**Lesson:** "If you can't measure it, you can't scale it."

### Pattern: Deletable Temporary Resources

**Appears in:**

- Case 3: All 3 agents deleted after completion
- Case 4: Scout and builder deleted
- Case 5: Each phase agent deleted after task moves
- Case 8: Builder agents deleted after shipping

**Lesson:** "The best agent is a deleted agent."

## Performance Comparisons

### Single Agent vs. Multi-Agent

| Task | Single Agent | Multi-Agent | Speedup |
|------|--------------|-------------|---------|
| Load 10 docs | 150k tokens, 5min | 30k primary, 2min | 2.5x faster, 80% less context |
| SDK migration | Fails (overflow) | 80k max/agent, 30min | Completes vs. fails |
| Codebase summary | 120k tokens, 3min | 32k max/agent, 52s | 3.5x faster |
| UI components | 80k tokens, 2min | 30k max, 55s | 2.2x faster |

### With vs. Without Orchestration

| Metric | Manual (no orchestrator) | With Orchestrator |
|--------|-------------------------|-------------------|
| Commands per task | 8-12 manual prompts | 1 prompt to orchestrator |
| Context management | Manual (forget limits) | Automatic (orchestrator sleeps) |
| Error recovery | Start over | Retry failed phase only |
| Observability | Terminal logs | Real-time dashboard |

## Common Failure Modes

### Failure: Context Explosion

**Scenario:** Case 2 without scouts

- Single agent reads 100+ files
- Context hits 180k tokens
- Agent slows down, makes mistakes
- Eventually fails or times out

**Fix:** Add scout phase to filter files first

### Failure: Orchestrator Watching Everything

**Scenario:** Case 3 with observing orchestrator

- Orchestrator watches all agent work
- Orchestrator context grows to 100k+
- Can't coordinate more than 2-3 agents
- System doesn't scale

**Fix:** Implement orchestrator sleep pattern

### Failure: No Observability

**Scenario:** Case 7 without dashboard

- 5 agents running
- One agent stuck on permission request
- No way to know which agent needs attention
- Entire workflow blocked

**Fix:** Add hooks + observability system

### Failure: Agent Accumulation

**Scenario:** Case 5 not deleting agents

- 20 tasks completed
- 80 agents still running (4 per task)
- System resources exhausted
- New agents can't start

**Fix:** Delete agents after task completion

## Key Takeaways

1. **Parallelization = Sub-agents** - Nothing else runs agents in parallel

2. **Context protection = Specialization** - Focused agents use less context

3. **Orchestration = Scale** - Single interface manages fleet

4. **Observability = Confidence** - Can't scale what you can't see

5. **Deletable = Sustainable** - Free resources for next task

6. **Multi-agent is Level 5** - Requires mastering Levels 1-4 first

## When to Use Multi-Agent Patterns

Use multi-agent when:

- ✅ Task naturally divides into parallel subtasks
- ✅ Single agent context approaching limits
- ✅ Need quality gates between phases
- ✅ Want to work on other things while agents execute
- ✅ Have observability infrastructure

Don't use multi-agent when:

- ❌ Simple one-off task
- ❌ Learning/prototyping phase
- ❌ No way to monitor agents
- ❌ Task requires tight human-in-loop feedback

## Source Attribution

All case studies drawn from field experience documented in 8 source transcripts:

1. Elite Context Engineering - Case 1 (AI docs loader)
2. Claude 2.0 - Case 2 (SDK migration), Case 8 (AFK device)
3. Custom Agents - Case 5 (task board)
4. Sub-Agents - Case 6 (meta-agent)
5. Multi-Agent Observability - Case 7 (dashboard)
6. Hooked - Supporting patterns
7. One Agent to Rule Them All - Case 3 (summarization), Case 4 (UI components)
8. (Transcript 8 name not specified in context)

## Related Documentation

- [Orchestrator Pattern](../patterns/orchestrator-pattern.md) - Multi-agent coordination
- [Hooks for Observability](../patterns/hooks-observability.md) - Monitoring implementation
- [Context Window Protection](../patterns/context-window-protection.md) - Resource management
- [Evolution Path](../workflows/evolution-path.md) - Progression to multi-agent mastery

---

**Remember:** These are real systems in production. Start simple, add complexity only when needed.