---
name: pi-subagents-workflow
description: Coordinate delegated work with agent_spawn, agent_send, and agent_stop. Use when the user asks for sub-agents, a task would flood your context with verbose output, or it splits into independent parallel parts; also when continuing, messaging, or stopping existing sub-agents.
---

# Sub-agent coordination

These instructions are for the main agent. Assign work from the current request; do not expand the user's authorization. Do small tasks, or tasks that depend on context you already hold, yourself; a sub-agent starts with a fresh context and must rebuild it.

1. **Specify the task.** Write tasks and messages in complete, plain sentences; a sub-agent has a separate context, so shorthand, abbreviations, and words joined without spaces are ambiguous to it. Keep code identifiers, paths, and commands exact. A new task states the goal, necessary context and paths, files it may change, limits or decisions it cannot infer, and how the result will be accepted; give these separate paragraphs when the task is longer than a few lines.
2. **Parallelize independent work.** If a task needs an undecided interface, settle that interface first. Otherwise keep working or wait for results; do not poll or repeatedly ask for completion. Handle communication between sub-agents yourself, using their actual available tools rather than asking them to contact one another.
3. **Keep file changes separate.** Only one agent may change a given file at a time, including the main agent. A checking task is read-only unless edits were explicitly assigned. When a check finds a defect, pass the concrete finding to the agent responsible for that file rather than changing it concurrently.
4. **Continue related work.** Prefer the original sub-agent for questions, revisions, additional tests, or later stages of the same task. Start a new one for independent parallel work, an independent check needing fresh context, or when the existing agent is unsuitable—not merely because its previous turn ended.
5. **Avoid unnecessary messages and stops.** Send only new work, necessary information, corrections, or answers. Do not send thanks, receipts, status-only announcements, or requests to repeat an already-delivered report. Do not routinely stop completed agents; stop for cancellation, incorrect execution that must halt, or an explicit stop request. Report to the user when a result changes the conclusion, risk, or next action, not for each notification.
6. **Check what is missing.** Inspect existing check results and their scope before running more checks. An independent check should examine a risk or boundary the existing checks did not cover. The main agent verifies cross-task integration rather than replaying every sub-agent check. After changes, rerun affected checks; an old notification alone is not a reason to repeat work. Judge findings against the current files, and distinguish a defect in the actual inputs from a hypothetical future compatibility risk.