Appearance
A metaagent routes, delegates, and synthesizes — never executes — in one of two canonical shapes ( hierarchy or pipeline), both capped at depth-2.
Guide
How to build metaagents
Start here
Two canonical shapes. Pick the one that fits the work.
Hierarchydomains span
Orchestrator / Lead / Worker
Agents split by domain. Leads delegate; workers execute.
User
↓
Orchestrator
↓
Team Lead
↓
Worker
Context propagates via env vars to every subprocess. Use when the work is wide — parallel domains under one synthesis.
Pipelinephases chain
ADW Script
Python script chains phase-prompts sequentially. Same depth-2, different mechanism.
plan
→
build
→
test
→
review
Each phase is its own agent call. Use when the work is deep — sequential SDLC stages that must run in order.
Both shapes respect depth-2. Neither is the "right" one — pick by whether the work is parallel-across-domains or sequential-across-phases.
The reading path
Seven nodes. Read in this order.
01
Delegation Has a Sweet Spot
Depth-2 is the observed optimum. Depth-1 hits single-agent ceilings; depth-3+ bleeds coordination cost.
The sizing rule — teaches you how tall the tree can be.
sizing
02
Domain Locking Scales Multi-Agent Safety
Per-file permissions are what let N agents share a codebase without stepping on each other.
Prompt-level "please stay in your lane" does not hold under pressure.
safety
03
One Agent One Prompt One Purpose
Every agent the orchestrator spawns must have a single focused job.
Generalists underperform — context gets split across too many concerns.
discipline
04
Agent Delegation Hierarchy
The canonical org-chart: User → Orchestrator → Team Lead → Worker.
Leads delegate; workers execute. Context propagates through env vars.
shape A
05
Agent
The atomic unit. One role, one prompt, one artifact.
Every node in the hierarchy is an instance of this primitive.
atom
06
ADW Script
A Python script that chains phase-prompts — the pipeline alternative.
Same depth-2 discipline, different mechanism. Good for plan → build → test → review.
shape B
07
Trigger
The out-loop entry point. Crons, webhooks, file-watchers.
Without a Trigger, every metaagent runs only when a human invokes it.
entry
Read top-to-bottom. Each node assumes the ones above it — skipping forward means hitting concepts that don't land yet.
The depth rule
Depth-2 is the sweet spot. Do not go deeper.
d1
Ceilinged
User
→
Agent
Single-agent ceiling. No delegation — you hit context and role limits fast.
d2
✓ Sweet spot
User
→
Orch
→
Worker
One level of indirection. Route and synthesize without compounding loss.
d3+
Bleeds
User
→
Orch
→
Lead
→
…
Latency bleeds. Context is lost at every hop — coordination cost without quality gain.
If you find yourself wanting depth-3, split the orchestrator into two peers instead. Width scales; depth doesn't.
Where to go next
Two sibling guides. Both compose with this one.
runtime
how-to-metaprompt
Runtime prompt composition. What makes many specialized agents feasible within the hierarchy — skills resolve, variables interpolate, roles diverge at boot.
composition
how-to-build-metaskills
Meta-behavior pairs with meta-agents. Skills that compose plug into agents that compose. Same shape, different layer.
Metaagents answer who does the work. Metaprompts answer how each role gets wired. Metaskills answer which rules compose in.
The discipline
A metaagent's job is to route, delegate, and synthesize — not to execute.
Pick hierarchy when domains span, pipeline when phases chain. Cap at depth-2. Lock domains by file permission, not by please-stay-in-your-lane. Every spawned agent is one role, one prompt, one artifact.