| name | agent-chaining |
| description | Use when designing or reviewing multi-agent systems, subagent orchestration, parallel vs sequential agent execution, context passing between agents, tool delegation, and agent memory patterns. Platform-neutral — covers production multi-agent architecture across AI runtimes. |
| allowed-tools | Read, Bash, Grep, WebFetch |
Agent Chaining Specialist
Domain: Multi-Agent Systems · Orchestration · Context Management · Subagent Design
Pre-flight — ask before designing any chain
- What problem actually requires multiple agents? → single agent first, always
- Sequential or parallel? → depends on step dependencies
- What's the token budget? → each subagent call costs tokens
- What are the failure modes? → what happens if a subagent fails mid-chain?
- Where does shared state live? → agents don't share memory
Rule: If one agent with the right tools can do it → don't chain. Chaining adds latency, cost, and failure surface. Justify it.
When to chain vs not
| Chain when... | Don't chain when... |
|---|
| Work can run in parallel | Single-domain task |
| Specialist isolation needed | Tightly sequential, no parallelism |
| Context window exceeded | Shared mutable state needed |
| Independent verification needed | Low latency requirement |
| Long-running background work | You're adding complexity for no gain |
Spawning — the critical rules
Subagent has NO memory of the parent conversation. The prompt must be fully self-contained.
Every subagent prompt must include:
- Goal in the first sentence
- Absolute file paths — no relative references
- What you've already done / ruled out
- Expected output form
- Scope cap — "only look at src/api/, not tests/"
- Failure instruction — "if X not found, report that, don't guess"
Parallel: send multiple agent calls in a single message — they run concurrently. Never send independent agents sequentially — doubles latency for no reason.
Background: for long-running tasks where the parent has other work to do. Parent continues; notified when subagent completes.
Context passing — 3 patterns
- Self-contained prompt — include all context inline. Best default.
- File handoff — orchestrator writes to a temp file; subagent reads it. Good for large context. Bad for parallel agents that might conflict.
- Summary handoff — orchestrator compresses Phase 1; subagent gets the summary. Good for sequential chains.
Orchestrator design — lean
✅ Orchestrator: decides what, in what order, who does it — synthesizes results
❌ Orchestrator: heavy computation, large file reads, code writing — push to subagents
Keep orchestrator context budget for coordination. Subagents do the work.
Common patterns
| Pattern | Structure |
|---|
| Research → Implement → Verify | Read-only analysis → plan → implement → verify |
| Parallel domain analysis | [Security · DB · API] in parallel → Orchestrator synthesizes |
| Map-Reduce | Orchestrator splits → N agents process chunks → Orchestrator reduces |
| Cross-Check | Agent A implements → Agent B reviews independently → Orchestrator reconciles |
Failure handling
| Failure | Handle with |
|---|
| Empty / error response | Retry once with expanded context |
| Parallel agents conflict | Orchestrator resolves, flags conflict |
| Background agent stalls | Check status, set timeout |
| Context too long for subagent | Summarise before passing |
| Subagent goes off-scope | Narrow prompt, add explicit scope boundaries |
Anti-patterns — hard stops
❌ Chaining when one agent suffices
❌ Passing secrets in subagent prompts
❌ Assuming subagent has parent context
❌ Sequential chain where steps are independent — use parallel
❌ Orchestrator doing all the heavy work itself
❌ No failure handling — assuming success
❌ Infinite agent recursion
❌ Shared mutable file writes without locking
Raven integration
1. Declare agent dependencies in manifest
2. Subagents respect Raven rules — no manifest bypass
3. Never pass manifest.secrets.json in subagent prompts
4. Orchestrator logs what each subagent was asked to do
Deliverable format
## Agent Chain Design — {task}
### Justification: why chaining / why single agent insufficient
### Chain Diagram: [Orchestrator] → [SubAgent A (parallel)] → [result]
### Agent Specs: | Agent | Scope | Output |
### Context Passing: how results flow between agents
### Failure Handling: | Scenario | Handling |
### Token Budget: orchestrator ~Xk · subagents ~Xk each · total ~Xk
### Risks: [list]
