Pi Crew

Pi Crew

Delegate bounded work to subagents; responsibility for scope, verification, and the final answer stays with you.

Choose the Workflow

• To create a custom agent, read Create a Custom Agent and follow it for role design, frontmatter, body instructions, and verification. Resolve the path relative to this skill directory. Creating a definition does not require spawning it.
• To delegate work to an existing agent, follow the orchestration workflow below.

Select

Call crew_list and select each resolved agent by its role description. Every subagent supports follow-up turns. Use crew_status only when you need a snapshot of your open subagent sessions; never poll it for completion because results arrive automatically.

An inline <pi-crew subagent="name" /> reference records the subagent the user selected with @crew:name; mention names use only ASCII letters, digits, and hyphens. It is not an unconditional instruction to spawn. Use the surrounding sentence's intent to decide whether delegation is requested.

Use multiple subagents whenever the work has independent parts: separate scopes, distinct deliverables, or complementary review angles. Give every spawn a separate goal and avoid duplicate ownership.

Do not build generic handoff pipelines merely because several roles are available. A subagent should perform its own bounded investigation unless separate discovery, decision analysis, or planning is independently valuable to the user's request.

Do not use an agent whose stated purpose does not match the requested deliverable.

Delegate

• Delegate for useful independent work such as broad discovery, focused planning or review, bounded implementation, and verification. Skip tiny tasks where delegation adds no value; resolve unclear scope or blocking decisions first.
• Gather only enough context to write the assignment; leave delegated investigation to the subagent.
• Read-only reviewers may inspect the same scope for distinct concerns; serialize work that may edit the same files.

Size and split

One task is one deliverable the subagent can finish and verify on its own, and that you can check in a single pass. Judge size by scope and difficulty, not by item count: a hard five-step task may need splitting, a simple twelve-step task may not.

• Split when parts have different deliverables or different verification, or when you would need several follow-up rounds to steer one agent through them.
• Run parts in parallel when they touch disjoint files and neither needs the other's result.
• Run parts in sequence when one depends on another's outcome. Write the next task after the result arrives and carry the confirmed findings into its context; do not pre-write it on assumptions.
• Keep parts together when they edit the same files or one change is meaningless without the other.
• Signs a task is too big: the goal joins unrelated outcomes with "and"; instructions mix discovery, implementation, documentation, and verification of separate things; you expect to correct course mid-way.

Two modes

Decide first whether you are starting a subagent or continuing one; the message you write is different in each case.

• crew_spawn: the subagent starts empty. It sees only the task, the repository, and its own definition. Write a complete ticket for someone who joined today.
• crew_respond: the subagent remembers its own task, findings, and last answer. Do not restate them. Write only what it could not see since its last turn: a user decision, files you or another agent changed, a rejection or correction, and what it must not touch now. Name those items; do not point at "the changes above" or anything else from your own conversation.
• Same deliverable, needs correction → crew_respond while the agent is completed or needs_input. New scope or a different deliverable → crew_spawn with a new task.
• If new information arrives while the subagent is running, keep it until the result arrives, then send it with crew_respond if still relevant. Do not poll for completion.