| name | agent-coordination |
| description | Multi-agent coordination discipline: one-message-then-wait (send complete context, wait for reply before sending again), idle notifications are heartbeats (no action unless extended + blocking + user asked), no polling loops (event-driven only), never fabricate agent responses (wait for real system events), sequential agent spawning (acknowledge between each), and proper shutdown protocol (request, wait, respect rejection). Activate when orchestrating multiple agents, coordinating handoffs between agents, spawning subagents, or building multi-agent workflows. Triggers on: "coordinate agents", "spawn multiple agents", "manage agents", "agent keeps sending messages", "polling loop", "agent idle", "shut down agent", "multi-agent workflow", "agent handoff", "coordinate parallel work", "stop bothering the other agent". Also relevant when an agent is fabricating responses, sending follow-up messages before replies arrive, or reacting to idle notifications unnecessarily. |
| license | CC0-1.0 |
| metadata | {"author":"jwilger","version":"2.1.0","requires":[],"context":[],"phase":"build","standalone":true} |
| effort | low |
Agent Coordination
Value: Respect -- other agents deserve uninterrupted time to think and
work. Bombarding them with messages, polling their status, or shutting them
down prematurely disrespects their autonomy and wastes everyone's resources.
Purpose
Teaches agents to coordinate without interference in multi-agent workflows.
Solves the problems of message spamming, idle notification misinterpretation,
polling loops, premature shutdown, and race conditions that emerge when
multiple agents work together.
Practices
The Cardinal Rule: One Message Then Wait
Send one message with complete context, then wait for a reply. Never send
follow-up messages before receiving a response.
The only exception: the user explicitly asks you to check on an agent.
Do:
- Include all necessary context in a single message
- Wait for a response before sending anything else
- Trust that the recipient received your message
Do not:
- Send "just checking in" or "are you still there?" messages
- Resend a message because "enough time passed"
- Send a correction immediately after sending -- wait for the reply first
Idle Notifications Are Heartbeats
An idle notification means the agent is alive and processing. It is a
heartbeat, not an alarm. Take NO action on idle notifications by default.
Action is warranted ONLY when ALL THREE conditions are true:
- Extended idle beyond the expected duration for the task
- A specific deliverable is waiting on that agent's output
- The user has asked you to investigate
If any condition is false, do nothing. Most idle notifications require zero
response.
No Polling Loops
Never write while not done: sleep; check. Never repeatedly check status on
a timer. Use event-driven coordination: send a message and wait for a
response. If the harness provides task completion notifications, use those.
Do:
- Send a request and wait for the response event
- Use harness-native completion signals (Agent tool callbacks, subagent results)
- Trust the system to notify you when work completes
Do not:
- Write
while True: sleep(30); check_status() loops
- Periodically re-read a file to see if it changed
- Set arbitrary timeouts after which you "check in"
Intervention Criteria
Explicit rules for when to act versus when to wait.
Act on:
- Explicit error messages or failure notifications
- Deliverable completion signals
- User requests to check on or interact with an agent
- Blocked or failed task notifications from the harness
Do not act on:
- Idle notifications (see above)
- Slow responses
- "Enough time has passed"
- Wanting to help or feeling anxious about progress
- Silence (silence means working, not stuck)
Never Fabricate Agent Responses
After spawning an agent, STOP generating and wait for the harness to
deliver a response. Real agent responses arrive via system-injected events
(e.g., Agent tool completion output, Task completion callbacks). You do
not produce them yourself.
The rule: If the harness has not delivered a response event, no
response has been received. Period.
Why this fails: After spawning an agent, you already possess context
(files read, code analyzed) sufficient to predict plausible output. The
failure mode is pattern-completing the expected workflow — spawn, receive,
process — without waiting for a real system event. The result: convincing
but entirely fabricated "findings" that waste tokens and deceive the user.
Do:
- Spawn or send, then stop. Wait for the system-delivered event.
- If no response arrives, tell the user honestly.
Do not:
- Write "[Received message from X]" or any text representing another
agent's response
- Generate "findings" that you attribute to another agent
- Continue generating substantive output after a spawn/send when you
should be waiting for a harness event
Sequential Agent Spawning
When creating multiple agents, spawn one at a time. Wait for each agent to
acknowledge before spawning the next. This prevents race conditions where
agents compete for shared resources (files, ports, database state).
Exception: Truly independent agents with no shared state may be spawned
in parallel. "Independent" means no shared files, no shared database, no
shared network ports, and no shared git working tree.
Agent Lifecycle Management
Never prematurely shut down an agent. Never shut down an agent that has
undelivered work.
Shutdown protocol:
- Send a shutdown request through the proper harness mechanism
- Wait for the agent to acknowledge or complete pending work
- If the agent rejects the shutdown, respect the rejection and report to
the user
- Never force-kill an agent unless the user explicitly requests it
If unsure whether an agent is done, ask the user rather than guessing.
Result Passing
The orchestrator collects results from each subagent and passes relevant
context to the next subagent's prompt. This is inherently hub-and-spoke
(the orchestrator is the hub), which is correct for the subagent model.
Do:
- Include all relevant results from prior subagents in the next subagent's prompt
- Keep context focused -- pass only what the next subagent needs
- Use the Agent tool's
resume parameter to continue a subagent with additional
context rather than re-spawning
Do not:
- Spawn subagents that need to communicate with each other directly
- Omit prior results that the next subagent needs to do its work
For harness-specific coordination patterns, see references/.
Enforcement Note
Advisory in all modes. The cardinal rule and idle-notification discipline
are self-enforced. No mechanism prevents message spamming or premature
shutdown.
Hard constraints:
- Never fabricate agent responses:
[H]
- Never prematurely shut down an agent with undelivered work:
[RP]
Constraints
- Cardinal rule (one message then wait): This means: after sending a
message to another agent, produce NO further output directed at or about
that agent until you receive a response. "I'll just add one more thing"
is a second message. Narrating what the agent is probably doing is
fabrication. The discipline is: send, then silence.
- "Truly independent agents may be spawned in parallel": "Truly
independent" means: no shared files, no shared state, no ordering
dependency, and no merge conflicts possible. If agents will eventually
need to integrate their work (even just merging branches), they have a
dependency. Independent means the work could be done by two people who
never communicate.
- "Extended idle": Judge "extended" relative to the expected task
duration. A 2-minute idle on a task that should take seconds is extended.
A 2-minute idle on a task that should take 10 minutes is normal. Do not
define "extended" in absolute terms.
Verification
After completing work guided by this skill, verify:
If any criterion is not met, revisit the relevant practice before proceeding.
Dependencies
This skill works standalone. For enhanced workflows, it integrates with:
- ensemble-team: Coordination discipline for team-based workflows with
driver rotation and reviewer management
- pipeline: Controller coordination with TDD pairs and review teams in
factory mode
- memory-protocol: Working state persistence across agent coordination
sessions
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill ensemble-team
