# pi-continuous-orchestration

A [Pi](https://pi.dev) extension that keeps a main agent working toward a
high-level goal until the work is verifiably done, using durable Markdown memory
and an independent adversarial verifier.

## Install

Node `>=22.19.0` is required. Three commands from a clean machine:

```bash
# 1. Install the pi coding agent
npm install -g @earendil-works/pi-coding-agent

# 2. Give pi a model to talk to (any one provider key)
export ANTHROPIC_API_KEY=sk-...

# 3. Install this extension
pi install npm:pi-continuous-orchestration
```

Any provider pi supports works — `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`,
`OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY` and others. Run
`pi --help` for the full list.

That is the complete setup. The package bundles the tested `pi-subagents`
runtime, its built-in agents, skills, and prompts, so there is no second package
to install.

## Use it

```bash
cd your-project
pi
```

Type your goal as an ordinary prompt, the way you would ask for any task:

> Add rate limiting to the public API, with tests, and make sure the existing
> suite still passes.

The main agent stays your single point of contact for the whole run. It works,
gets reviewed, and keeps going until the goal is met — you do not need to prompt
it again between passes. Type a message at any time to interrupt, ask something,
or change direction.

Give it a goal with a checkable finish line. "Make sure the test suite passes"
gives the verifier something to confirm; "improve the code" does not.

To try it for one run without installing:

```bash
pi -e npm:pi-continuous-orchestration
```

To pick a specific model:

```bash
pi --model deepseek/deepseek-v4-flash
```

## How it works

The main agent gets a static autonomous-work instruction and four durable files
under `.pi/meta/` in your working directory:

| File | Purpose |
| --- | --- |
| `GOAL.md` | The durable goal, constraints, and evidence required to call it done |
| `LEDGER.md` | Working memory: decisions, evidence, failed approaches, blockers |
| `STATUS.md` | A short human-readable snapshot of results and remaining gaps |
| `ROADMAP.md` | Milestones, ordering, dependencies, and coverage |

These are plain Markdown you can read or edit at any time. No database. The
agent may add its own notes in the same directory.

When the agent finishes a work pass, one of two things happens:

- **Known work is pending** (a subagent or background command): a fallback wake
  fires after five minutes so a stalled wait gets inspected.
- **Nothing is pending**: an independent verifier reviews the goal, the notes,
  and the actual workspace evidence, running tests and live checks as needed.

If the verifier finds gaps, they come back to the main agent as an ordinary user
follow-up. The agent is never told a reviewer exists, so it treats the feedback
as direction rather than as a grade. When the goal is genuinely met, the run
settles and reports completion.

Interrupt at any time by typing a message. That cancels any in-flight review,
answers you, and resumes the work.

## Configuration

Optional, at
`~/.pi/agent/extensions/continuous-orchestration/config.json`:

```json
{
  "enabled": true,
  "idleWakeMs": 300000,
  "freshAdversaryEachReview": false,
  "delegationAckTimeoutMs": 10000,
  "adversaryAgent": "orchestration-adversary"
}
```

| Key | Default | Meaning |
| --- | --- | --- |
| `enabled` | `true` | Set `false` to keep the package installed but inactive |
| `idleWakeMs` | `300000` | Fallback wake interval while known work is pending |
| `freshAdversaryEachReview` | `false` | Always send the full review task instead of the incremental follow-up |
| `adversaryAgent` | `orchestration-adversary` | Agent name used for verification |
| `delegationAckTimeoutMs` | `10000` | How long to wait for `pi-subagents` to accept a review request before reporting verification unavailable |

## Status line

During a run pi's footer shows total elapsed time since your prompt, `Main`
while the agent works, and review progress (turns, tools, tokens, current tool)
while verification runs. Those statistics stay in the UI; the agent only
receives substantive instructions.

## Known limitation

The public pi-subagents delegation protocol cannot resume a prior child session,
so each review starts a fresh reviewer process. After the first review the
reviewer receives an incremental task that points it at the current notes and
changed evidence rather than a full re-review, but it does not carry in-session
memory across reviews.

## License

MIT