multi-agent-architecture

# Multi-Agent Architecture

Design principles for orchestrating many sub-agents without context overflow.

## Core Philosophy

Treat agent design like human hiring: write a job description first, then translate to architecture. The framing shapes every decision.

## The Job Description Method

Before writing any agent code:

1. **Write a human JD** — What would you want this person to do? What qualities? What indicates success?
2. **Identify handoff points** — Where would a human need to check in or escalate?
3. **Define the onboarding** — What handbook would you give a new hire?
4. **Translate to agents** — Each JD section becomes architecture

| JD Section | Architecture Element |
|------------|---------------------|
| Responsibilities | Agent workflows |
| Required skills | Tool permissions |
| Success indicators | Output schemas |
| Escalation criteria | Error handling |
| Onboarding materials | Skills/handbook |

## The Shared Folder Pattern

**Problem:** Orchestrator context overwhelmed when 10+ sub-agents return detailed reports simultaneously.

**Solution:** Sub-agents write to temp folder → downstream agents read directly.

```
.claude/workspace/
├── phase-1/
│   ├── gmail-analysis.md
│   ├── calendar-analysis.md
│   └── drive-inventory.md
├── phase-2/
│   ├── client-summary.md
│   └── action-items.md
└── manifest.yml
```

**Workflow:**

```
1. Orchestrator spawns sub-agents
2. Each sub-agent:
   - Does work
   - Writes report to .claude/workspace/{phase}/{name}.md
   - Returns only: { status: "complete", path: "..." }
3. Downstream agents read prior phase outputs directly
4. Orchestrator reads manifest, not full reports
```

**Benefits:**
- Orchestrator context stays minimal
- Sub-agents get full upstream context
- No signal loss from summarization relay

## The Handbook Pattern

**Problem:** Many narrow skills create fragility and maintenance burden.

**Solution:** One handbook organized by chapters, read foundation + relevant sections.

```
skills/projec