diff --git a/context/agents/delegation-instructions.md b/context/agents/delegation-instructions.md index fce620a8..5b8d0f0b 100644 --- a/context/agents/delegation-instructions.md +++ b/context/agents/delegation-instructions.md @@ -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. --- diff --git a/context/agents/multi-agent-patterns.md b/context/agents/multi-agent-patterns.md index 8aee3336..fbbd6f90 100644 --- a/context/agents/multi-agent-patterns.md +++ b/context/agents/multi-agent-patterns.md @@ -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. --- diff --git a/modules/tool-delegate/amplifier_module_tool_delegate/__init__.py b/modules/tool-delegate/amplifier_module_tool_delegate/__init__.py index 7312b97b..3f594501 100644 --- a/modules/tool-delegate/amplifier_module_tool_delegate/__init__.py +++ b/modules/tool-delegate/amplifier_module_tool_delegate/__init__.py @@ -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"""