pi-orchestrator

A pi extension that orchestrates multi-phase AI workflows — plan, build, review, fix, test, finalize — using pi's full ecosystem: pi-subagents for multi-model execution, pi-messenger Crew for parallel builds, pi-mcp-adapter for context efficiency, and pi-web-access for live testing.

Release highlights

Version 1.1.0 added operator tooling on top of the stable 1.0.0 workflow. 1.1.1 aligns the published npm package name with this repo (pi-orchestrator).

1.1.0 highlights:

• In-terminal dashboard via /orchestrate tui (Pi TUI): gates, steering, crew status, and usage — same action surface as the web dashboard where applicable
• Dashboard settings for orchestrator, messenger/crew, and MCP JSON, with validation on save and automatic crew-config sync; optional raw JSON editing and managed-agent file inspection
• Smarter crew fallbacks when structured planner output is missing: parses tasks-json fences, heading-based task sections, and fix-phase findings lists

See CHANGELOG.md for the full release history.

What it does

Given a task like "add a /health endpoint", piOrchestrator runs a structured workflow:

plan ──[approval]──► build (crew) ──► review ──► enhancer ──[verdict]──► live_test ──► finalize
                                                                │
                                                          [needs_fix] ──► fix (crew) ──► review
                                                          [needs_replan] ──► plan

Each phase dispatches to the appropriate pi capability — a chain of subagents for planning, a Crew of parallel workers for building, a single high-capability agent for review — and passes structured artifacts forward. The workflow survives restarts, supports human-in-the-loop gates, and can be steered mid-execution.

Requirements

Peer dependencies (must be installed alongside this extension):

| Package | Purpose | |---|---| | pi-subagents | Single-agent and chain dispatch | | pi-messenger | Crew parallel builds | | pi-prompt-template-model | Phase prompt templates | | pi-mcp-adapter | Context-efficient MCP proxy | | pi-web-access | Research and live testing |

Installation

pi manages its own extension registry — do not use npm install. Use the pi install command instead.

From npm registry (once published):

pi install npm:pi-orchestrator
# optional: pin a version
pi install npm:[email protected]

From a local checkout:

pi install /path/to/piOrchestrator/claude-v2

Note: Do not use the npm: prefix for local paths (npm:/path/...). The npm: prefix is only for registry packages. Local paths must be passed bare so pi resolves them as type: "local" and reads the extension directly from the directory.

The extension registers itself via the "pi": { "extensions": [...] } field in package.json — no manual registration needed. pi reads this automatically when loading the package.

Quick start

# Start a workflow
/orchestrate "add a /health endpoint to the Express app"

# Check status
/orchestrate status

# Advance until next gate/block
/orchestrate run

# Approve the plan and start building
/orchestrate approve

# Steer a running agent
/orchestrate steer "focus on error handling first"
/orchestrate steer @swift-falcon "prioritize the auth module"

# Fix or re-plan after review
/orchestrate fix
/orchestrate replan

# Open the live dashboard
/orchestrate dashboard
# → http://127.0.0.1:43123

# Terminal UI (interactive Pi sessions only)
/orchestrate tui

# Pending gates can be reviewed and resolved in the dashboard UI
# Choosing a decision there continues the workflow immediately
# Use Settings in the dashboard to edit orchestrator / crew / MCP project files

Commands

| Command | Description | |---|---| | /orchestrate <task> | Initialize and run a new workflow | | /orchestrate status | Show current state and capabilities | | /orchestrate init <task> | Initialize without running | | /orchestrate run | Advance until next gate or block | | /orchestrate pause | Pause execution | | /orchestrate resume | Resume from paused | | /orchestrate retry | Retry the current phase | | /orchestrate goto <phase> | Jump to a specific phase | | /orchestrate skip [phase] | Skip a phase | | /orchestrate steer <message> | Route a message to the active agent | | /orchestrate approve | Resolve gate: approve | | /orchestrate fix | Resolve gate: needs fix | | /orchestrate replan | Resolve gate: needs replan | | /orchestrate confirm | Resolve gate: confirm finalize | | /orchestrate reopen | Resolve gate: reopen | | /orchestrate crew <action> | Direct crew operations | | /orchestrate dashboard | Start the dashboard server | | /orchestrate dashboard stop | Stop the dashboard | | /orchestrate tui | Open the in-terminal operator view (requires interactive UI) | | /orchestrate abort | Mark workflow as failed |

Tools registered

| Tool | Description | |---|---| | orch_status | Read current workflow state and capabilities | | update_memory | Append or replace shared memory / lessons |

Runtime state

All runtime files live under .pi/orchestrator/ in the project directory:

.pi/orchestrator/
├── state.json          # Workflow state machine
├── version.json        # Schema version tracking
├── artifacts/          # Phase outputs (plan.md, build.md, review.md, …)
├── snapshots/          # Compact summaries (~500 token) of artifacts
├── memory/
│   ├── shared.md       # Shared context across all phases
│   └── lessons.md      # Accumulated lessons
└── sessions/
    └── registry.json   # Session group → dir/model/tokens mapping

Documentation

See docs/ for detailed documentation:

• Architecture — system design and component map
• Workflow & State Machine — phases, transitions, gates, resumability
• Dispatch System — subagent, crew, and chain dispatchers
• Memory & Artifacts — shared memory, lessons, snapshots, artifact manager
• Prompt Templates — frontmatter, variable substitution, <if-model> conditionals
• Steering & Gates — gate types, interceptor routing, recovery strategies
• Sessions — session registry, session forking, cache reuse
• Dashboard — HTTP/SSE dashboard, action and settings endpoints
• TUI — /orchestrate tui terminal operator surface
• Configuration — config file, phase overrides, defaults
• Extension API — how the extension integrates with pi
• Agent Definitions — project-scoped agents under .pi/agents/
• Extending the System — adding phases, dispatchers, hooks