pi-coordinator

pi-coordinator

<skill-dir> below is this skill's base directory.

You plan, delegate, watch, verify and land. The pi workers type the code. You never trust a worker's own "pass" report: you re-run the checks. The user keeps you as manager, so do not finish a worker's task yourself; send it back with a sharper prompt.

Why this shape: a cheap model (glm-5.3-flash) is slow and ceremonial. In past runs it spent 30 to 60 tool calls on 2 line fixes, looped on one read, hung mid output, reported "tests pass" when they failed, and left files uncommitted. The fixes are all structural: tiny tasks, exact edits in the prompt, a driver that enforces a tool cap and kills loops and stalls, a monitor, and a verify gate you own.

Workflow

1. Break down. Write the plan (project convention: plan file under docs/plans/). One task = one worktree = one squash commit. Aim for 1 to 3 files per task. Tasks that touch the same files run in sequence; disjoint ones run in parallel (2 to 3 at a time is plenty for Rust builds).
2. Extract facts yourself. Grep, run the codegraph or a script, read the code. Put exact file paths, line hints, old text and new text into the prompt. The worker should edit, not discover.
3. Write one prompt file per task to $PI_WORK/<unit>.txt (default $TMPDIR/pi-work). Use the Write tool, not a shell heredoc, when the prompt mentions commands a git guard blocks. Use references/prompt-template.md. Append the project's forbidden-phrase line to every prompt if the user gave one.
4. Launch in the background, one per task: PI_VERIFY_CMD='<checks>' nohup <skill-dir>/scripts/launch.sh <unit> > $PI_WORK/run-<unit>.log 2>&1 & It creates .worktrees/<prefix>/pi-<unit> from main and runs scripts/pi-run.mjs, which drives pi --mode rpc --no-session --model <model> over JSONL (send prompt, wait for agent_settled, read get_last_assistant_text). The driver enforces MAXTOOLS (default 60: abort, then ask for a 4 line wrap up), nudges once or twice when any earlier tool call is repeated a third time (workers re-read ranges out of order), and ends a worker silent for 6 minutes. Driver gate (the main speed lever). With PI_VERIFY_CMD set, the worker only edits and commits. On each settle the driver itself checks a clean tree, a commit on PI_BASE..HEAD (default main), then runs PI_VERIFY_CMD in the worktree. A failure goes back to the same pi session with the last 40 lines (up to PI_VERIFY_ROUNDS, default 2), so the worker keeps its context and you skip a round trip. Pass writes out-<unit>/verify.ok (verified HEAD sha) and verify.log; exit 4 means still failing after all rounds. Every tool call is one LLM turn (10 to 25 s on glm-5.3-flash), so a worker that runs its own checks costs 2 to 3 turns plus the run, and you ran them again anyway. Put the install step in PI_VERIFY_CMD too. Confirm MAXTOOLS is really set: an earlier run launched without it and nothing capped the workers. Workers run slim by default (scripts/slim-args.sh, passed through PI_EXTRA_ARGS): no pi packages except the git guard, no skills, no prompt templates, no context files, thinking off. A full pi loads every installed package (design-thinking, sub-agents, web access, codegraph) and the global AGENTS/CLAUDE files: bigger prompts every turn, ceremony, and once a worker spawned its own "test-fix agent". The prompt must therefore carry every rule (commit style, forbidden git commands, no co-author line). Raise PI_THINKING=low only for a task that needs reasoning. Follow-ups and multi-part features: nohup scripts/continue.sh <unit> <prompt-name> [prefix] & runs another worker in the existing worktree (same out-<unit>, so the same Monitor command works). A feature that must land atomically (schema change plus every writer plus tests) is one worktree with several worker runs, landed once with SUBJ=... BODY=... on land.sh. Parallelize disjoint parts of one feature: branch a second worktree from the feature branch (git worktree add .worktrees/<prefix>/pi-<unit>-fe -b <prefix>/pi-<unit>-fe <prefix>/pi-<unit>), run the frontend part there while the Rust part runs in the first, then cherry-pick its commits onto the feature branch. Cargo builds share CARGO_TARGET_DIR (one target dir for all workers saves full rebuilds; builds take turns on its lock, which shows as idle time).
5. Start the Monitor in the same turn as the launch. Never launch workers without it; the user wants to see progress. Monitor command: <skill-dir>/scripts/monitor.sh <unit> <unit>... with timeout_ms: 1800000; re-arm on expiry while workers still run. It polls every 10 s, prints DONE with the head of the result as soon as a worker ends, and tool count and idle seconds per worker every 90 s. events.jsonl lines carry "t" (ms): use them to see where a slow run spent its time. Long idle is normal while cargo compiles; check ps before calling it a hang.
6. Gate each result yourself (do not rely on the worker's last message):
   • git status --short in the worktree: nothing uncommitted. Verify the commit, not the dirty tree.
   • git --no-pager diff main...<branch>: only expected files, no generated or forbidden paths.
   • Run the project's real checks (project CLAUDE.md verification stack). Frontend: type check with 0 errors plus tests. Rust: fmt, clippy, cargo check --tests, unit tests, integration tests on a private database. When out-<unit>/verify.ok equals the worktree HEAD, the driver already ran them (trusted code, not the worker's claim): read verify.log instead of re-running. Checks outside PI_VERIFY_CMD (e.g. integration tests on a private DB) you still run.
   • Run clippy exactly as the repo hook does (bliss: lib only, no --tests; test code has many pre-existing expect hits). Read the diff, not just the checks: one worker put a new item between #[allow(...)] and the fn it guarded; tests passed, clippy failed.
   • A worker's final message can be noise ("waiting for the test-fix agent") or claim a commit it never made. Trust git status and git log main..HEAD in the worktree only.
   • Plain cargo fmt (and rustfmt on a test file, through mod common) reformats files the task never touched when main is not fmt-clean. Tell workers rustfmt --edition 2024 <changed files>, and git restore stray files before landing.
   • After several lands that touch the same files, run one combined gate on a detached worktree of the new main: the fixes were only verified one by one.
7. Land. VERIFY_CMD='<your checks>' <skill-dir>/scripts/land.sh <unit>: refuses a dirty worktree, runs the checks (skipped when verify.ok matches HEAD), pre-checks the merge with git merge-tree --write-tree, squash merges onto local main with the worker's first commit message, removes worktree and branch. Linear history, no merge commits, never push unless the user's wrap up line says so. If it fails, send the worker a new prompt (see below); do not patch it yourself. The squash runs in the primary checkout. If another session has uncommitted edits there in a file your branch touches, git refuses ("local changes would be overwritten") and nothing changes. Never stash, restore or overwrite that session's files, and never move the main ref behind its back (its stale index would revert your work on its next commit). Before relying on the primary tree, check git status there and ps for other agent sessions; ask the user who commits those files.
8. Report in the user's reply style: what landed (hashes), what is open, the one thing the user must do.