Orchestrator (Pi Workflows)

Turn a multi-agent mission into one deterministic workflow run. The workflow owns scheduling and persistence; the parent Pi session owns routing, approval boundaries, and final judgment.

Use this only when the pi-extensible-workflows extension is installed and its workflow tools are available. For ordinary single-agent work, invoke the matching project skill directly.

Non-Negotiables

1. Inventory the actual available skills before routing. Use ask-matt as the map when present, but never launch it as a worker.
2. Give each agent one primary skill and copy its concrete workflow, constraints, inputs, and done criteria into the prompt.
3. Model dependencies structurally. Put only independent jobs in the same parallel() block; await their results before dependent work.
4. Keep operation names and object keys stable. Persisted retry and resume depend on those structural keys.
5. Use prompt() when inserting agent results into another prompt. Await bare agent results before interpolation or serialization.
6. Treat agent output as a claim. A separate verification or synthesis step must inspect artifacts and evidence before the mission passes.
7. Use named withWorktree() scopes for modifying agents. Never let independent writers share a worktree or edit the launch checkout concurrently.
8. Use shell() mainly for bounded verification. External side effects are not guaranteed exactly once if the host fails before journaling.
9. Set a budget when fan-out is open-ended or expensive. Do not bypass exhaustion by retrying ordinary agent calls.
10. Use the exact recovery action for the persisted state: workflow_retry for failed, workflow_resume for budget_exhausted, and neither for completed or stopped runs.
11. When Pi delegates execution to Herdr, use two sequential Pi agents: one planner and one Herdr orchestrator. Herdr owns the worker fan-out; Pi must not duplicate it.