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

TUI.mp4 TUI Live tree, cost, and the workflow script while a run is in progress.	Herdr.mp4 Herdr Inspect a live workflow agent in its own pane.
Trajectory.mp4 Trajectory Gantt of model and tool events, plus steer/stop on a running subagent. Open sample run report	Configuring.mp4 Configuring Model aliases, skills, and extension settings.
Roles.mp4 Roles Markdown roles for tools, model, and policy.	Reusable.mp4 Reusable workflows Register a callable defineWorkflowFunction and mix shell gates with agents.

Install

pi install npm:@marcoscale98/pi-extensible-workflows@fork

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. The starter, Subagents, and Trajectory can each be disabled with Pi package filters.

Companion packages

• @marcoscale98/piewf-herdr (pi install npm:@marcoscale98/piewf-herdr@fork): workflow-agent sessions in Herdr panes.
• @marcoscale98/piewf-cli (npm install --global @marcoscale98/piewf-cli@fork): piewf for doctor, inspection, headless runs, export, and bundles.
• @piewf/pi-ext-roles (npm install -g @piewf/pi-ext-roles): pi-role <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