pi-delegator

name	pi-delegator
description	Delegate approved coding tasks to Pi subprocesses with free opencode defaults, model setup, live progress, and metrics. Don't use for direct edits, CI, or non-Pi agents.
license	MIT
effort	high
metadata	{"version":"1.0.0","author":"Luong NGUYEN <[e-mail]>"}

Pi Delegator

Use this skill when another AI agent should delegate a clearly scoped task to a separate Pi instance, monitor Pi while it works, and report exact session metrics. The main agent stays the orchestrator: it captures intent, gets user approval, selects a model, runs Pi, and summarizes the result.

Repo Sync Before Edits (mandatory)

If the delegated Pi task may modify a git repository, sync the target repo before starting Pi so the delegated work begins from current code:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty, stash first, sync, then pop. If origin is missing or conflicts occur, stop and ask the user before continuing.

Safety contract

• Never start Pi until the user approves the exact run preview.
• Prefer free opencode-cli models whenever that provider is available.
• Do not hide that a non-free model will be used; ask for explicit approval.
• Do not invent token, cost, or duration metrics. Report only collected values.
• Keep Pi's task prompt clear and bounded; Pi should know what to do, where to work, what tools are allowed, and what output is expected.

Prerequisites

Before any delegation, verify:

which pi
python3 --version

If either command fails, stop and tell the user what to install. Resolve the bundled helper relative to this skill directory, then use it for model discovery, config persistence, execution, event monitoring, and metrics collection:

helper="<absolute-path-to-this-skill>/scripts/pi_delegate.py"

Step 1 — Check models and configure default

Run model discovery first on every skill invocation:

python3 "$helper" models --prefer-free

The helper reads Pi's available models and highlights free opencode-cli models. Configuration is stored in:

~/.pi/agent/skills/pi-delegator/config.json

If no config exists, or the configured model is no longer available:

1. Show the model list or the helper's recommended free default.
2. Ask the user to select a default model and thinking level.
3. Save it with:

python3 "$helper" configure \
  --model "provider/model" \
  --thinking "low"

Default policy: if opencode-cli is available, recommend and use an opencode-cli model unless the user explicitly chooses another provider.

Step 2 — Capture clear input

Build a delegation brief before asking for approval:

• Task: the exact work Pi should perform.
• Target cwd: absolute path where Pi will run.
• Permissions: read-only, edit files, run tests, install deps, or other limits.
• Tools: allowed Pi tools, such as read,bash,edit,write or read-only tools.
• Constraints: files to avoid, coding standards, time limits, expected tests.
• Expected output: summary only, changed files, patch, report path, etc.
• Complexity: simple, medium, or complex.

If any field is unclear, ask a concise clarifying question before continuing.

Step 3 — Select model and thinking

Read references/model-selection.md when choosing a model. In short:

• Simple tasks: free opencode-cli if available, thinking off or minimal.
• Medium tasks: free capable model if available, thinking low or medium.
• Complex/risky tasks: strongest available free model first; if a paid model is recommended, ask the user to approve the paid model explicitly.

Respect user overrides. If the run will use a non-free provider while opencode-cli is available, include that warning in the approval preview.

Step 4 — Approval gate

Show this preview and wait for explicit approval:

◆ Pi Delegation Preview
┄┄┄┄┄┄┄┄┄┄┄┄┄
  Task:       <one sentence>
  Cwd:        <absolute path>
  Model:      <provider/model>
  Thinking:   <off|minimal|low|medium|high|xhigh>
  Tools:      <tool allowlist>
  Permissions:<read-only|can edit|can run tests|...>
  Complexity: <simple|medium|complex>

Run Pi with this task? [y/N]

Default to No. If the user declines, stop without launching Pi.

Step 5 — Run and monitor Pi

After approval, write the delegation prompt to a temporary file and run:

python3 "$helper" run \
  --approved \
  --task-file /tmp/pi-task.md \
  --cwd "<target-cwd>" \
  --model "<provider/model>" \
  --thinking "<level>" \
  --tools "read,bash,edit,write" \
  --approve-project \
  --session-name "pi-delegated-task"

The helper uses Pi RPC mode, streams progress events, and requests final session stats. Read references/event-monitoring.md for the event-to-progress mapping. Use --verbose only when the user asks for raw streaming detail.

Step 6 — Report result and metrics

Return a compact report:

◆ Pi Delegation Complete
┄┄┄┄┄┄┄┄┄┄┄┄┄
  Result:       DONE | FAILED | ABORTED
  Duration:     <seconds>
  Model:        <provider/model>
  Thinking:     <level>
  Tokens:       input <n>, output <n>, cache read <n>, cache write <n>
  Cost:         <amount or not reported>
  Tool calls:   <n>
  Session:      <session file or not persisted>

  Summary:
  <Pi's final answer or concise synthesis>

If Pi changed files, list them from git status --short after the run. Do not claim tests passed unless Pi or the main agent actually ran them.

Error handling

• Missing pi: ask the user to install Pi and stop.
• No models available: ask the user to authenticate Pi or configure providers.
• Configured model unavailable: rerun model selection and update config.
• User declines approval: stop cleanly.
• Pi process fails: show stderr, partial progress, and any collected metrics.
• Metrics unavailable: write not reported instead of guessing.

Step Completion Reports

After each major phase, print a compact status block:

◆ <Phase> ([step N of 6])
┄┄┄┄┄┄┄┄┄┄┄
  Models checked:    ✓ pass
  Free default:      ✓ pass (opencode-cli available)
  User approval:     ✓ approved
  Result:            PASS