# 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:

```text
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:

```bash
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:

```bash
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

```text
/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:

```text
/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:

```text
/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:

```json
{
  "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

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