pi-adaptive-orchestrator

pi-adaptive-orchestrator is a human-approved Pi workflow for planning, delegating, reviewing, and handing off coding work without letting the coordinator edit the project itself.

It starts every run on Sol medium, asks Sol to assess the task, and then routes the planning effort, worker agents, reviewers, and final review through a small tested policy:

Complexity	Planner / final review	Worker	Reviewer
Easy	Sol medium	Luna high	Luna high
Medium	Sol high	Terra medium	Terra high
Complex	Sol xhigh	Terra xhigh	Terra xhigh

Pi calls the requested “extra high” effort level xhigh. The planner records a rationale for every route. The coordinator cannot use Pi edit or write; one serialized worker owns project edits at a time.

Requirements

• Pi 0.80.x (>=0.80.6 <0.81.0)
• pi-subagents 0.34.x
• Access to the configured Sol, Luna, and Terra model ids

The package defaults to Pi's authenticated Codex model family:

openai-codex/gpt-5.6-sol
openai-codex/gpt-5.6-luna
openai-codex/gpt-5.6-terra

If your Pi session uses a different configured provider, override all three model ids in the trusted project config below.

Install

Trusted clones of this repository load the package from the project-local .pi/settings.json entry. Start a new Pi session from the repository after trusting the project.

pi-subagents must be installed as a Pi package (not merely an npm dependency) so its RPC bridge and async lifecycle extension are loaded. For another trusted workspace, install the local source while developing:

pi install ./path/to/asha/pi-packages/pi-adaptive-orchestrator

After a public npm release is available, install the package and its required bridge together:

pi install npm:pi-subagents@0.34.0
pi install npm:pi-adaptive-orchestrator@0.1.0

Installation does not grant access to models the user is not authenticated to use.

Use

/orchestrate add an idempotent retry contract to the import worker

The command changes the parent session to Sol medium and sends the task to the coordinator. Sol must classify complexity, call orchestration_route, and create a detailed plan. The extension persists the plan checkpoint and stops.

Review the plan, then explicitly continue:

/orchestrate approve

The coordinator then:

1. routes and starts each child through orchestration_delegate, which passes its exact model to pi-subagents;
2. serializes all delegates by default, including active-worktree writers;
3. runs one independent review → fix-worker → re-review loop when a fix is needed;
4. routes the parent to Sol final-review effort; and
5. calls orchestration_handoff with the evidence for a human decision.

Commands:

/orchestrate status
/orchestrate approve
/orchestrate cancel

The workflow never deploys, merges, or treats its own handoff as human approval.

Configuration

An optional trusted project config at .pi/adaptive-orchestrator.json can override only the three provider-qualified model ids:

{
  "models": {
    "sol": "openai-codex/gpt-5.6-sol",
    "luna": "openai-codex/gpt-5.6-luna",
    "terra": "openai-codex/gpt-5.6-terra"
  }
}

Unknown aliases, bare model names, malformed JSON, unavailable models, or unavailable credentials fail visibly before a run starts. Do not put API keys or secrets in this file.

Operational constraints

• The package invokes the installed pi-subagents RPC bridge for child execution and consumes its completion events for tracked status/progress. It disables pi-subagents’ nested acceptance gate because this workflow enforces its own independent reviewer and required re-review after a fix; this also permits valid read-only/no-diff worker slices.
• orchestration_delegate is the only child-launch path while a run is active. Every logical slice needs a stable workId; a failed or paused child can be retried only with the same workId and retry: true. It supplies the routed model, uses fresh child context, and gives children an explicit no-nesting contract.
• The extension blocks every coordinator tool except read-only inspection and its own orchestration tools while a run is active. A human approval gate therefore cannot be bypassed with bash, direct subagent, edit, or write calls.
• The extension allows one active delegate at a time. This intentionally favors a strong active-worktree writer guarantee over parallel implementation; use a separate workflow for deliberately isolated worktree fanout.
• xhigh is the maximum Pi thinking level; routing never invents an unsupported “extra high” value.
• Run /orchestrate cancel before starting another task if a plan is no longer wanted.

Development

cd pi-packages/pi-adaptive-orchestrator
npm test
npm run check
npm pack --dry-run