59 lines
2.9 KiB
Markdown
59 lines
2.9 KiB
Markdown
---
|
|
name: subagents
|
|
description: Delegate isolated work through Pi subagent tools. Use when a workflow needs an independent worker, fresh context, parallel reviewers, or hidden role separation.
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# subagents
|
|
|
|
## 1. Confirm support
|
|
|
|
Prefer tool calls when the current runtime exposes them.
|
|
The supported tool names are `subagent_spawn`, `subagent_batch`, `subagent_list`, `subagent_status`, `subagent_result`, and `subagent_cancel`.
|
|
|
|
If these tools are unavailable, do not pretend that an in-process role switch is a subagent.
|
|
State that Pi subagent tools are unavailable in the current runtime.
|
|
Do not perform the delegated subagent work in-process.
|
|
|
|
Done when the run has a supported subagent tool path.
|
|
|
|
## 2. Prepare a bounded prompt
|
|
|
|
Give each subagent a self-contained prompt.
|
|
Include the role, task, repository path, relevant files or artifacts, constraints, and expected output shape.
|
|
Do not expose private planning state that the workflow is trying to isolate.
|
|
For test-driven development, send one behavior at a time rather than a backlog.
|
|
For review, send one review dimension at a time unless batching independent dimensions.
|
|
|
|
Use `context: "independent"` for a fresh worker by default.
|
|
Use `context: "fork"` only when the child intentionally needs the parent transcript as starting context.
|
|
Choose named agents only when the project has configured them.
|
|
Do not invent named agents as part of the delegation.
|
|
|
|
Done when the prompt is narrow enough that the subagent can complete without sharing hidden state or requiring follow-up orchestration.
|
|
|
|
## 3. Spawn and track workers
|
|
|
|
Use `subagent_spawn` for one worker.
|
|
Use `subagent_batch` when several independent workers can run in parallel.
|
|
Both spawn tools return before the child work is complete.
|
|
Record accepted child ids and per-entry failures.
|
|
Use `subagent_list` or `subagent_status` to track lifecycle when needed.
|
|
Use `subagent_result` to retrieve completion output.
|
|
Use `subagent_cancel` for stale or no-longer-needed workers.
|
|
|
|
Do not claim the delegated work is complete until every required child result is available or a failed child has an explicit disposition.
|
|
Treat `queued`, `starting`, `running`, and `settling` as incomplete states.
|
|
Treat `failed`, `cancelled`, `timed_out`, and `orphaned` as failures unless the caller explicitly accepts the missing result.
|
|
|
|
Done when every required worker result has been collected or every missing result has a stated disposition.
|
|
|
|
## 4. Integrate results
|
|
|
|
Use subagent output as evidence, not as an unquestioned command.
|
|
Preserve which child produced each material finding.
|
|
When subagents disagree, report the disagreement rather than averaging it away.
|
|
When a subagent result changes implementation direction, verify the relevant facts in the parent context before editing code.
|
|
|
|
Done when the parent has integrated child results into the caller workflow with provenance and limitations visible.
|