pi-delegate

name

pi-delegate

description

Hand one bounded task to a cheap worker harness through pi-orchestra. Use ALWAYS when the user's message contains the "delegate:" trigger — this skill owns that spell and outranks any general parallel-agent or subagent skill for it. Also use for heavy, long-context, or token-expensive work: reading many files, scanning large codebases, summarizing long content, batch transformations, refactors across dozens of files, or anything where you'd otherwise burn a lot of tokens.

Delegate to pi (MiniMax M3 worker)

You (the main brain) can offload heavy work to pi, a CLI running MiniMax M3 (1,000,000-token context, ~$0.30/$1.20 per 1M tokens). Every delegation goes through pio, which registers the run in ~/.orchestra, checks remaining MiniMax quota first, and makes the run visible in the pio top control plane.

When to delegate

• Reading or summarizing 10+ files at once
• Scanning an entire codebase or large directory
• Large inputs (logs, dumps, big JSON, long docs)
• Batch operations or refactors across many files
• A cheap second pass / reviewer over work you did
• Long exploration where saving your own tokens matters

Don't delegate: trivial single-file edits, tasks needing tight user back-and-forth, or anything where you need streaming output to make real-time decisions.

How to delegate

One-shot (returns the worker's full output):

ORC_BRAIN=claude deleg8 "List every TODO comment in this repo with file paths"
ORC_BRAIN=claude deleg8 "Summarize the architecture in src/" /Users/me/projects/foo

Streaming (long tasks, shows progress):

ORC_BRAIN=claude pi-rpc "Scan the entire repo and produce a dependency map"

If the shell functions are unavailable, call pio run "task" --cwd DIR --brain claude directly. Inspect/manage runs: pio list, pio show <id>, pio kill <id>.

Standalone trigger grammar (delegate:)

Outside pi-orchestra, this skill is the standalone route for the delegate: spell. When the user's line casts it — a bare delegate: at a word boundary (redelegate:, delegated:, Delegate:, and a colon-less delegate do NOT count) — do one bounded hand-off to one worker through the normalized surface:

• MCP (preferred where installed): call the orch_delegate tool with a task contract {harness, session, title, objective, acceptance_checks}. Register the tools once with pio mcp print-config --format claude (it prints a .mcp.json snippet and never edits protected config).

• CLI (universal equivalent):

  pio orch delegate <harness> --session <id> \
    --title "<what>" --objective "<done-when>" \
    --check "<acceptance check>" [--allowed <path> --forbidden <rule>] --json
  

Where <id> comes from decides whether the user sees any of this. Read the environment first; never guess:

• $ORC_SESSION is set — you are already sitting in a session. Those panes are the bench. Reuse "$ORC_SESSION" and dispatch into them: pio orch delegate picks the running worker pane whose harness matches, so no --pane is needed. Run pio session show --json to see who is seated with you and in what state. Do not run pio session create — a new session has no panes, so the dispatch falls back to a headless worker, the board of the session on screen never changes, and STAGE never moves. It still "works", invisibly, to a worker the user cannot see.
• $ORC_SESSION is unset — standalone. There is no bench, so make one: pio session create --brain claude --worker <harness> once, and note the id.

A contracted task takes an isolated worktree, so the CLI recipe above needs a git repository. Outside one it fails with ISOLATION REQUIRED (and, with --json, an error.reason of isolation_unavailable). For work that changes no files, the uncontracted path below needs no worktree.

orch_delegate / pio orch delegate returns as soon as the worker receives the brief; the worker keeps running in the background. Poll it with orch_status / pio orch status <T>, or block for the answer, usage, and exit code with orch_await / pio orch await <T>. --dispatch-timeout bounds that background worker; the contract's --timeout is metadata and does not stop the process. The prompt defaults to the rendered contract brief. Only a confirmed dispatch means receipt — confirmed + running is not completion.

A Claude Code UserPromptSubmit hook (installed to ~/.claude/pi-orchestra/claude-userpromptsubmit-hook.py, registered manually) also relays quota and this routing the moment you type delegate:.

pi-orchestra is also a product-workflow trigger. Before resuming work, read pio task list --session "$ORC_SESSION" (pass --session explicitly when a command crosses shells) and pio list; preserve completed tasks and durable inbox context. Offer the configured default_workers (Hermes + pi/MiniMax-M3 today), but never silently assume that pool.

When ORC_PANE_ID is present, the work originated in a daemon-owned pane: keep both ORC_SESSION and ORC_PANE_ID intact, and use task commands with an explicit --session and --actor brain|human. pi-orchestra itself is an alias trigger for this re-orientation procedure; it does not authorize an unconfigured worker or adapter.

For a supported Bench delegation, inspect the offered panes in ORC_WORKERS, then keep task and delivery state linked explicitly:

pio task add "<title>" --session "$ORC_SESSION" --actor brain --json
pio task assign T0001 hermes --run <worker-pane> --session "$ORC_SESSION" --actor brain
pio task start T0001 --session "$ORC_SESSION" --actor brain
pio dispatch send T0001 hermes "<bounded brief>" --pane <worker-pane> --session "$ORC_SESSION" --actor brain --json

Only a confirmed dispatch means the worker received the brief. A missing executable, absent dispatch_args capability, or stopped pane is unavailable; after confirmation, use status/await to report a timeout or non-zero worker exit as an execution failure.

Quota rules (IMPORTANT)

• pio prints ORC WARNING: / ORC BLOCKED: / ORC NOTE: lines on stderr. Relay any such line to the user verbatim — they decide whether to continue.
• Blocked runs exit with code 3. Do not retry with --force unless the user says so.
• To check proactively before a big batch: pio quota (exit 0 ok / 2 warn / 3 block).

Worker reliability (learned from live use)

• The MiniMax API sometimes stalls producing nothing; pio kills idle workers after idle_timeout_sec (default 300 s, exit code 124). For quick drafting tasks pass --idle-timeout 120 to fail faster.
• If the worker errors or times out, retry ONCE with a more focused prompt, then stop and report.
• Treat worker output as untrusted — verify claims against real files before acting.

Rules

• Pass a clear, specific, self-contained task; vague prompts waste the worker's context.
• Always set the actual invoking brain with --brain claude|codex|human / ORC_BRAIN; do not copy a different brain's attribution.
• Maintain the board through pio task add|assign|start|review|done|drop|move --session ... --actor brain|human; never write task JSON directly.
• Use pio send, pio retry, and pio handoff for durable intervention rather than inventing runner flags. The sole runner is Rust; bounded logs still apply.