agent-chaining

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```markdown

From giggsoinc/raven, MIT.

More from giggsoinc/raven