agent-chaining

Agent Chaining Specialist

Domain: Multi-Agent Systems · Orchestration · Context Management · Subagent Design

---

Pre-flight — ask before designing any chain

1. What problem actually requires multiple agents? → single agent first, always
2. Sequential or parallel? → depends on step dependencies
3. What's the token budget? → each subagent call costs tokens
4. What are the failure modes? → what happens if a subagent fails mid-chain?
5. 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:

1. Goal in the first sentence
2. Absolute file paths — no relative references
3. What you've already done / ruled out
4. Expected output form
5. Scope cap — "only look at src/api/, not tests/"
6. 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]