agent-coordination

What this skill does

# 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:

1. Extended idle beyond the expected duration for the task
2. A specific deliverable is waiting on that agent's output
3. 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:**
1. Send a shutdown request through the proper harness mechanism
2. Wait for the agent to acknowledge or complete pending work
3. If the agent rejects the shutdown, respect the rejection and report to
   the user
4. 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:

- [ ] Every message to another agent contained complete context (no "just checking in")
- [ ] No follow-up messages sent before receiving a reply
- [ ] No action taken on idle notifications alone
- [ ] No polling loops or sleep-check patterns used
- [ ] Agents spawned sequentially with acknowledgment between each
- [ ] No text generated that represents or simulates another agent's response
- [ ] After every spawn/send, generation stopped and waited for a system event
- [ ] No agent shut down prematurely or with undelivered work
- [ ] Shutdown used proper request/response protocol
- [ ] No agent respawned after user-initiated interruption without waiting for user direction

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:** Worki