Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 20 additions & 7 deletions context/agents/delegation-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,21 +276,34 @@ Use session resumption when:

---

## Scaling with Multiple Instances
## Wave Discipline: Batch Everything Independent

For large codebases or complex investigations, dispatch MULTIPLE instances of the same agent with different scopes:
**Every delegate call in one turn runs concurrently. Every delegate call in a separate turn
runs sequentially, and you block on the previous one first.**

Plan your full delegation set before dispatching any of it. Emit every independently
resolvable delegation in a single turn — different agents, same agent with different
scopes, or both.

```python
# Parallel dispatch - independent surveys
# One turn, three concurrent agents - different specialists
delegate(agent="foundation:explorer", instruction="Survey auth/", context_depth="none")
delegate(agent="python-dev:code-intel", instruction="Trace authenticate() callers")
delegate(agent="foundation:git-ops", instruction="Summarize recent auth/ commits")

# One turn, three concurrent instances - same agent, split scope
delegate(agent="foundation:explorer", instruction="Survey auth/", context_depth="none")
delegate(agent="foundation:explorer", instruction="Survey api/", context_depth="none")
delegate(agent="foundation:explorer", instruction="Survey models/", context_depth="none")
```

**When to scale:**
- Large codebase with distinct areas
- Multiple independent questions to answer
- Time-sensitive investigations where parallelism helps
**Only a delegation that consumes another delegation's output belongs in a later turn.**
Everything else goes now. Before you dispatch a second wave, ask whether it could have
gone out with the first — if it could have, batch what remains rather than repeating the
mistake.

**When to scale out:** large codebase with distinct areas; multiple independent questions;
any investigation where you would otherwise wait on one agent before starting the next.

---

Expand Down
33 changes: 25 additions & 8 deletions context/agents/multi-agent-patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,39 @@ This context provides patterns for orchestrating multiple agents effectively.

---

## Parallel Agent Dispatch
## Plan the Whole Set, Then Dispatch

**CRITICAL**: For non-trivial investigations or tasks, use MULTIPLE agents to get richer results. Different agents have different tools, perspectives, and context that complement each other.
**Delegations emitted in ONE turn run concurrently. Delegations split across turns run
sequentially — and you sit idle through each one.**

When investigating or analyzing, dispatch multiple agents IN PARALLEL in a single message:
Before your first delegate call, write down every delegation the task needs. Then emit,
in a single turn, every one of them that does not consume another delegation's output.

```python
# ONE turn - all three run at once, total time = the slowest one
delegate(agent="foundation:explorer", instruction="Survey the authentication module structure")
delegate(agent="python-dev:code-intel", instruction="Trace the call hierarchy of authenticate()")
delegate(agent="foundation:zen-architect", instruction="Review auth module for design patterns")
delegate(agent="foundation:git-ops", instruction="Summarize recent commits touching auth/")
```

**Why parallel matters:**
- Each agent brings different tools (LSP vs grep vs design analysis)
- Deterministic tools (LSP) find actual code paths; text search finds references and docs
- TOGETHER they reveal: actual behavior + dead code + documentation gaps + design issues
**Two reasons this matters, and the second is the one usually missed:**

1. **Richer results** — each agent brings different tools and perspective; together they
reveal actual behavior + dead code + documentation gaps + design issues.
2. **Wall-clock** — a task delegated in three sequential waves takes roughly the sum of
those waves. The same agents batched into one wave take the length of the longest.
Sequential waves of independent work are pure waste.

### The Independence Test

Before dispatching a wave, ask: **would I write any of these instructions differently if I
had the others' results first?**

- **No** → they are independent. They belong in the SAME turn. Emit them now.
- **Yes** → only the ones that consume a result wait. Everything else still goes now.

And before dispatching wave N+1, ask: **could this have gone out with wave N?** If yes, you
already paid for the mistake — batch the remainder.

---

Expand Down
15 changes: 14 additions & 1 deletion modules/tool-delegate/amplifier_module_tool_delegate/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -257,8 +257,21 @@ def description(self) -> str:
# Add usage notes
base_description += """

BATCH YOUR DELEGATIONS. Every delegate call you emit in a single turn runs
CONCURRENTLY. Delegations you split across separate turns run SEQUENTIALLY, and
you block on each one before planning the next.

Before emitting any delegate call, enumerate every delegation this task needs.
Emit ALL of them that do not consume another delegation's output in THIS turn.
Only a delegation that literally needs a prior result as input belongs in a
later turn.

- Two independent delegations in one turn: finishes in the time of the slower one
- The same two split across two turns: takes the sum, plus your own planning turn
- "I'll see what the first one says first" is the failure mode - if you would not
change the second instruction based on the first result, it was independent

Agent usage notes:
- Launch multiple agents concurrently when tasks are independent
- When an agent completes, it returns a single message back to you
- Each agent invocation is stateless - provide complete context in your instruction
- DEFAULT TO DELEGATION - only do simple single-step work yourself"""
Expand Down
Loading