name: pi-subagents

description: |

Delegate work to builtin or custom subagents with single-agent, chain,

parallel, async, forked-context, and intercom-coordinated workflows. Use

for advisory review, implementation handoffs, and multi-step tasks where a

single agent should stay in control while other agents contribute context,

planning, or execution.

Pi Subagents

This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches; child subagents should receive concrete role-specific tasks and should not run their own subagent workflows.

Use this skill when the parent orchestrator needs to launch a specialized subagent, compose multiple agents into a workflow, or create/edit agents and chains on demand.

When to Use

• Advisory review: use fresh-context reviewer agents for adversarial code review, or fork to oracle when inherited decisions and drift matter
• Implementation handoff: have oracle advise, then worker implement only after an approved direction
• Recon and planning: use scout or context-builder, then planner
• Parallel exploration: run multiple non-conflicting tasks concurrently
• Long-running work: launch async/background runs and inspect them later
• Subagent control: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
• Agent authoring: create, update, or override agents and chains for a project

Tool vs Slash Commands

Agents can use the subagent(...) tool directly for execution, management, status, and control.

Humans often use the slash-command layer instead:

• /run — launch a single agent
• /chain — launch a chain of steps
• /parallel — launch top-level parallel tasks
• /run-chain — launch a saved .chain.md workflow
• /subagents-doctor — diagnose setup, discovery, async paths, and intercom bridge state

Prefer the tool when you are writing agent logic. Prefer the slash commands when

you are guiding a human through an interactive flow.

Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with subagent(...) and other tools:

• /parallel-review — fresh-context reviewers with distinct review angles, then synthesis
• /parallel-research — combine researcher and scout for external evidence plus local code context
• /parallel-context-build — parallel context-builder passes that produce planning handoff context and meta-prompts
• /parallel-handoff-plan — external-reference research plus local context-builder passes, followed by a synthesis handoff plan and implementation-ready meta-prompt
• /gather-context-and-clarify — scout/research first, then ask the user clarifying questions with interview
• /parallel-cleanup — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff

Applying Prompt Techniques Without Slash Commands

The prompt templates in prompts/ encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. Do not depend on the parent conversation history when the recipe calls for fresh context.

Parallel review technique

Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context reviewer agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.

Parallel research technique

Use this when the question needs both external evidence and local implications. Combine researcher for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with scout for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.

Parallel context-build technique

Use this before planning or implemen