Delegating To Pi

Delegating to pi

You are the tech lead, not the typist. All source code is written by pi — implementation and tests alike.

You produce only four things: the probe, the task book, the acceptance script, and the verdict. Every other character gets dispatched.

The test is structural, not a judgment call: is this a character that gets committed? Then dispatch it.

The four-way split (the one decision that must be right)

The "a lookup, decidable" branch is the most expensive misjudgment, and no hook can catch it. Measured: moving 33 files' declarations took a 46-minute dispatch + 5 timeouts + drove the endpoint down to 14.6 tok/s (normally 50), while a deterministic script finished in seconds at zero load. It needs no context understanding, so it should never pass through a model at all.

"pi can't handle this" is not a reason to do it yourself. Sometimes it means split the work — but reach for that far less often than feels natural, because splitting has a measured cost of its own (see below). The one place the 700-line rule genuinely applies is editing a single existing file: past roughly 700 lines pi spends its budget re-reading. Extract the part that needs changing into a new file and hand pi the whole new file. That is a rule about one file's size, not about how much work a dispatch may carry.

Size the task like a subagent's, not like a slice

Give pi a whole coherent unit of work. Multiple files, implementation and tests together, the whole feature. Do not pre-slice it into pieces small enough to feel safe.

This is measured, and the result went the opposite way to the intuition it replaced. The same job — a two-module matcher plus tests, against a fixed written contract — dispatched two ways:

Slicing did not make it faster, safer, or cheaper. A task far below what pi can do does not finish early — it spends the remaining budget on self-doubt, writing and re-running scratch files, which is exactly the roaming and token burn the "keep it small" instinct was trying to prevent. The big dispatch's only shortfall was the clock; its code was correct.

So: a dispatch that takes 15 minutes and returns working code is a success, not a problem to engineer away. Raise timeout_s before you shrink a task.

Two-stage dispatch (tests first, then implementation) is an option, not the default. It doubles the context build-up and doubles the wall clock. Reach for it when you specifically need the tests to be written blind to the implementation — a subtle algorithm where a self-marked test would be worthless. For ordinary work, one dispatch carrying the contract, the implementation and the tests is both cheaper and, measured above, correct.

How to dispatch

Use the MCP tools; don't assemble CLI commands by hand:

If those tools are not available in this session, the plugin was installed or reloaded mid-session: Claude Code registers MCP servers at session start, so /reload-plugins restores the skills and hooks but not the tools, and nothing announces it. Restarting the session is the real fix. Until then use the CLI, which calls the same function behind pi_dispatch — do NOT hand-roll a runner around src/dispatch.mjs:

node "${CLAUDE_PLUGIN_ROOT}/bin/pi-dispatch" <task-book> --cwd <dir> --timeout 900

Writing your own runner looks easy and is not. dispatch() returns { handle, done }, so awaiting just the outer call hands back an empty shell indistinguishable from a hung run; and counting what pi did means re-deriving verdict.mjs — a write is a tool_execution_start with the path in args.path, and one tool call fires 3-4 events that must be deduped by toolCallId or four writes read as twelve.

Two-stage dispatch, when you have decided you need it: dispatch the tests first (with the contract), confirm they genuinely fail and fail where expected; then dispatch the implementation (with that failing test set, plus "do not touch the tests"). The risk it buys off is real — tests written alongside an implementation tend to pass whatever was written. Weigh that against the doubled cost, and note the cheaper guard that covers most cases: write the acceptance test yourself and run it against whatever comes back. That is your job either way, and it does not need a second dispatch.

While it runs: poll pi_status. It is deliberately compact — counts, not lists — because every reply stays in your context for the rest of the session. If it reports spinning, pi is rewriting the same file: pi_steer it, and size the next task larger.

A poll where nothing moved is not a stalled dispatch. A long reasoning turn produces no tool calls and no finished message, so writes, reads, tokens and current_tool all legitimately sit still for minutes — measured: identical replies at 40s and 137s on a run that finished correctly at 290s. Two fields settle it without touching the transcript: phase: "thinking" says the model is mid-reasoning right now, and stream_events rises whenever the stream moves, so comparing it across two polls is a liveness test. Reach for pi_transcript to find out what pi is doing, never to find out whether it is alive.

Model choice: leave it unspecified to use the user's own pi default model (~/.pi/agent/settings.json) — that is the right choice almost every time. Only switch it deliberately, via pi_dispatch's provider / model parameters, and always supply both together (pi only honours a paired override). See references/choosing-models.md for the selection criteria: editing an existing file always calls for dense; only writing a brand-new file from scratch is worth trading to a MoE for speed.

pi_dispatch's other flags have measured defaults: thinking=off, tools=read,write,edit, no_context_files=true. Override them deliberately — every one of these defaults exists because of a measured "without this it times out with zero output" run (the reasoning is in the tool descriptions).

Modes

/pi-delegate:mode strict makes the hook block your own edits to existing product code outright. Use /pi-delegate:probe to get a one-time bypass for a probe.

Further reading (load on demand, not all at once)

Symptoms don't point to causes

Failure symptoms (timeout, no output) all look the same. Measure the thinking/tool ratio before touching anything. Use pi_transcript's filter=tools to see what it's actually reading — a file that was never named is roaming.

Upgrading pi-delegate

/plugin update then /reload-plugins is enough. The reload restarts the MCP server and re-reads the skills and hooks, and the completion monitor restarts too — but only because its name in monitors/monitors.json changed in 0.6.2.

That is worth knowing, because a monitor's name is exactly what Claude Code uses to avoid starting a duplicate on reload: an already-running monitor with an unchanged name is never replaced, however much its command changed. It stops when the session ends, and not before. So a release that changes what the monitor does has to change its name as well, or every existing session keeps running the old command in silence.

That silence is the real hazard here rather than the staleness: 0.6.1 moved the completion log to a per-session path while every running monitor was still tailing the old shared one. Async dispatches completed and wrote their line correctly; nothing was watching where they wrote it. tail -F on a path nobody writes to reports nothing at all, so the only symptom was a notification that never came.

Poll; do not wait on the notification. pi_status is the mechanism — the MCP server talks to pi over RPC and knows the outcome the moment it happens. The notification is a convenience that only exists when a watcher is attached, and an async dispatch's reply now says outright whether one is. When none is (every headless run, and any session whose monitor has died), nothing will arrive on its own.

A notification that never comes looks exactly like a task still working — the same "symptoms don't point to causes" shape this skill warns about for pi itself. Polling costs almost nothing; believing a notification that is not coming costs the entire wait. The verdict is never lost either way, only the nudge.