| name | pi-delegate |
| description | Use when delegating simple research, review, mapping, verification, or planning tasks to multiple Pi coding agents without edits, worktrees, dispatch JSON, or merges. |
Pi Delegate
Use this skill for lightweight Pi delegation where the parent agent remains the coordinator and synthesizer.
Default Rules
- Use direct
pi CLI calls, not pi-dispatch.
- Keep Pi agents read-only unless the user explicitly asks for implementation.
- Prefer
--tools read,grep,find,ls --no-session.
- Give each Pi agent a narrow, self-contained prompt.
- Require concise findings with concrete file paths and uncertainties.
- The parent agent cross-checks important claims locally before reporting.
- Do not create dispatch JSON.
- Do not create git worktrees.
- Do not merge, commit, or revert changes.
When To Use
Use pi-delegate for:
- architecture research
- codebase mapping
- bug or risk investigation
- test-gap review
- security/privacy review
- implementation planning
- independent critique of a proposal
Use pi-dispatch instead when Pi agents need to edit files, run dependent waves, isolate work in worktrees, retry with model routing, or merge results.
Pattern
Launch 2-5 parallel Pi agents with disjoint research slices:
pi --tools read,grep,find,ls --no-session -p "You are Pi researcher A. Work read-only in <repo>. Research <slice>. Do not edit or write files. Return concise findings with exact file paths, risks, and uncertainties."
Common slices:
- top-level structure, build system, entry points
- domain flow and key services
- state, persistence, events, and boundaries
- tests, mocks, CI, security, and quality risks
- focused risk area named by the user
Preflight
Before delegation, quickly check:
command -v pi && pi --version
git status --short
If the repo is dirty, pi-delegate is still safe for read-only research. Mention the dirty state if it affects interpretation. If the user wants implementation and the repo is dirty, ask or switch to direct scoped edits; use pi-dispatch only after the user accepts checkpoint/worktree behavior.
Baseline Tasks
For build/test questions, Pi agents should identify likely commands, but the parent agent runs the real baseline locally. Prefer the repository's actual build system over generic instructions in ambient agent files.
Good delegate prompt:
pi --tools read,grep,find,ls --no-session -p "Work read-only. Identify exact build/test commands, schemes, targets, excluded tests, and uncertainties. Do not run commands."
Then the parent runs the chosen command and records the exit code plus the short success/failure summary.
Timeouts
Pi print-mode can be quiet until completion. Use the surrounding tool timeout when available. If using shell directly, wrap long investigations with a local timeout such as:
timeout 180 pi --tools read,grep,find,ls --no-session -p "<prompt>"
On macOS without GNU timeout, omit the wrapper unless gtimeout is installed. Treat a timeout as a partial result and continue with other agents' reports.
Output Shape
Ask Pi agents for this structure when the task has risk:
Findings:
- <claim> - <file path> - confidence: high|medium|low
Risks:
- <risk> - impact - uncertainty
Next action:
- <smallest useful step>
Synthesis
After all Pi agents return:
- Compare reports for agreement and contradictions.
- Verify high-impact claims with local reads or searches.
- Report the synthesis first, then notable per-agent findings if useful.
- Recommend the next smallest useful action.
Use this compact table for complex syntheses:
| Claim | Source | Confidence | Verified |
|---|---|---:|---|
| ... | path:line or agent | high/medium/low | yes/no |
Escalate to pi-dispatch only after synthesis identifies a complex implementation with separable write scopes or dependency waves.
Safety Gate
If the user asks for implementation during a pi-delegate workflow, stop and choose one of:
- implement directly for small scoped edits
- switch to
pi-dispatch for complex parallel implementation
- ask before proceeding if the git worktree is dirty and dispatch would checkpoint or merge
