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:

• Write a human JD — What would you want this person to do? What qualities? What indicates success?

• Identify handoff points — Where would a human need to check in or escalate?

• Define the onboarding — What handbook would you give a new hire?

• 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/project-manager/ ├── SKILL.md # Entry point, routes to chapters └── references/ ├── 01-foundation.md # Who we are, tools, escalation, standards ├── 02-daily-ops.md # Data gathering procedures ├── 03-dashboards.md # Structure, quality checks └── 04-onboarding.md # New client setup

Chapter Structure:

Chapter Contents

Foundation Team, tools, data sources, escalation rules, quality standards

Domain chapters Specific procedures for each responsibility area

Reading Pattern:

Sub-agent reads:

1. Foundation chapter (always)
2. Relevant domain chapter(s) (based on task)

Context Budget Strategies

Strategy When to Use

Shared folder 5+ sub-agents, inter-agent dependencies

Context proxy Research agents returning verbose results

Manifest files Orchestrator needs status, not details

Chunked execution Serial phases when parallel overwhelms

Architecture Decision Tree

How many sub-agents? ├── 1-3 → Direct orchestration (return reports to main) ├── 4-10 → Shared folder pattern └── 10+ → Phased execution with manifest

Do teammates need direct communication? ├── No → Sub-agents (Task tool) — report results back only └── Yes → Agent Teams — shared task list, inter-agent messaging ├── See agent-teams skill for full guide └── Best for: parallel review, competing hypotheses, multi-module features

Do sub-agents need each other's output? ├── No → Parallel execution, merge results └── Yes → Shared folder, dependency ordering

Is orchestrator context a concern? ├── No → Return full reports └── Yes → Status-only returns + file paths

Anti-Patterns

Pattern Problem Fix

Slash commands as orchestration Context exhaustion before work starts Move to sub-agents

Orchestrator relays all context Bottleneck, signal loss Shared folder

One skill per micro-task Fragile, hard to maintain Handbook chapters

Sub-agents return full reports Context overflow at 10+ agents Path-only returns

Iteration Path

Most multi-agent systems evolve through:

• Slash commands — Quick start, context limits emerge

• Orchestrator + sub-agents — Solves context, creates relay bottleneck

• Shared folder — Solves relay, reveals skill fragmentation

• Handbook consolidation — Unified knowledge, maintainable

Skip earlier stages when building new systems.

Agent Teams

When workers need to communicate directly with each other — not just report back to an orchestrator — use Agent Teams instead of sub-agents. Agent Teams provide shared task lists, inter-agent messaging, and independent context windows.

Key differences from sub-agent patterns above:

• Teammates message each other directly (not just back to caller)

• Shared task list with self-claiming and dependency auto-unblock

• Each teammate is a full Claude Code session with own context

When to upgrade from sub-agents to Agent Teams:

• Sub-agents need to share findings mid-task

• You need adversarial debate or competing hypotheses

• 3+ workers need self-organizing coordination

For full setup, operations reference, and orchestration patterns, apply the agent-teams skill.