pi-extensible-workflows

Deterministic, resumable multi-agent workflow orchestration for Pi.

Documentation | Developer guide | Subagents | Herdr | Roles | Extension authoring

Requires Node.js 22.19 or newer. This is trusted Pi host code with the same filesystem and process access as Pi. Install only code you trust.

See it

Install

pi install npm:pi-extensible-workflows

For source installation and local development, see the installation guide.

Quick start

Ask Pi to run a workflow. The main agent writes the script for the current task.

const reports = await parallel("review", {
  api: () => agent("Review the API."),
  tests: () => agent("Review the tests."),
});
return agent(prompt("Summarize these reports:\n\n{reports}", { reports }));

Runs are backgrounded by default; set foreground: true to wait for the final value. Use pipeline() for staged work, withWorktree() for isolation, checkpoint() for approval, and agent.create({ name }) with handle.send() when one agent must keep its transcript across turns.

The optional roles extension can also start a plain Pi session with a role, without a workflow:

npm install -g @piewf/pi-ext-roles
pi-role reviewer                 # Pi with the reviewer role's model, tools, skills, and prompt
pi-role scout -p "Where is the retry logic?"

See the optional roles integration.

Included capabilities

The single core installation provides workflows, the reviewLoop starter for developer-and-reviewer implementation cycles, durable standalone subagent tools (subagents_run, subagents_inspect, subagents_steer, subagents_stop, and subagents_retry). Ready-made slash commands launch them: /scout, /parallel-scout, /oracle, /council, /review, /parallel-review, /review-loop, and /deep-research. With the optional roles extension enabled, roles and aliases are overridable; reviewLoop is not. In Pi's TUI, /agents opens a full-screen view of every agent of the session with its full transcript and actions, /workflow the same view on the session's workflow runs, and /subagents on the session's subagents (needs only the subagents extension). /workflow opens its picker, with Model aliases and Close, when there is no run, and outside the TUI; /agents needs the TUI. The starter, Subagents, and Trajectory can each be disabled with Pi package filters.

Companion packages

• @piewf/herdr (pi install npm:@piewf/herdr): workflow-agent sessions in Herdr panes.
• @piewf/cli (npm install -g @piewf/cli): piewf for doctor, inspection, headless runs, export, and bundles.
• @piewf/pi-ext-roles (npm install -g @piewf/pi-ext-roles): pi-role to start native Pi with role defaults. Install and enable this optional Pi extension explicitly to interpret workflow or subagent role options. Core and CLI work without it.

Development

npm ci
npm run check

Start with AGENTS.md for the code map and completion rules. See the verification guide for focused tests, package checks, and checks that need external services. Release approvals and publishing stay in RELEASING.md.

License

MIT