---
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. Before spawning, decide what you will do yourself, and do not do the same work as a sub-agent. Handle communication between sub-agents yourself, using their actual available tools rather than asking them to contact one another. While background work runs, continue only with independent work. If nothing else can be done, end your current reply normally. Ending your reply leaves background agents running; their completion notifications automatically start a new model request when the parent is idle. Results cannot enter a model request that is already generating, so do not keep that request open or spend thinking waiting for them. Do not poll, sleep to wait, or repeatedly ask for completion. A normal reply ending is different from an abort: after an abort, results are saved without automatically restarting the parent.
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.
7. **Run long work in milestones.** For work expected to span several hours or sessions, give each sub-agent round a task it can finish in about 45 minutes, with a concrete acceptance command that preferably runs the whole flow end to end. Accept a milestone by that command's result and the key diff; do not review every component or negotiate field names with sub-agents. At the end of each milestone, write a short handoff file: current state, open problems, next milestone. Proactively tell the user and suggest continuing from the handoff in a new main session rather than carrying the whole history forward.