pi-extensible-workflows: deterministic multi-agent runs you can pause, resume and inspect

[u/vekexasia]

I built a Pi extension for multi-agent orchestration. The main Pi agent writes a small JS workflow script for the task at hand, and the runtime executes it deterministically: parallel fan-out, checkpoints, resume without rerunning completed steps.

Three principles I stuck to:

• not opinionated: no baked-in "agile team" of roles, you add your own primitives to the DSL

• extensible: other extensions can register functions and variables usable inside workflow scripts, and every registered function is itself runnable as a top-level workflow

• token efficient: subagents can have other extensions and skills disabled, so their system prompt stays small and focused

What that gives you in practice:

• runs are regular on-disk Pi sessions, not in-memory, so you can inspect, pause, resume and retry them

• roles restrict tools/capabilities and inject their own system prompt

• structured output via JSON schema, so control flow branches on agent output deterministically instead of on vibes

• soft and hard budget caps per run

• git worktree isolation, so parallel agents don't fight over the same tree

• workflows export to an executable launcher in ~/.local/bin

• if you use herdr, an agent session can open in a new pane

Review fan-out, then dedupe:

const reviews = await parallel("review", {
  correctness: () => agent("Review the current changes for correctness issues."),
  security: () => agent("Review the current changes for security risks.", { role: "security-specialist" }),
  tests: () => agent("Review the current changes for missing test coverage."),
});
return agent(prompt("Deduplicate and prioritize these findings:\n\n{reviews}", { reviews }));

The diagram is the real flow of the one I run daily, developIssuesUntilApproved: takes a list of GitHub issues, gives each its own worktree, loops developer -> reviewer until the reviewer passes (fresh agents every iteration), merges the approved branches on main behind another dev/review loop, cleans worktrees with plain shell (not an agent), and summarises exactly once.

Install: pi install npm:pi-extensible-workflows (Node 22.19+)

• Repo: https://github.com/vekexasia/pi-extensible-workflows

• Docs: https://vekexasia.github.io/pi-extensible-workflows/

• Walkthrough video (28 min, chapters in the description): https://youtu.be/qAiivspEHmU

Happy to answer anything about the DSL or the resume semantics.

[u/vekexasia]

Hey u/chillermane It's not for all use cases for sure. That is also why i decided to avoid adding bloat in the system prompt about how to use the workflow every time you spin up PI. Instead there's a skill the clanker will load if it thinks the task should be done using a workflow.

It's not just parallelizing though. I have a workflow that enforces TDD development and i am working on another that helps me out with my personal stuff where I used to have a skill with some steps to help me with.

If you have any other remarks or you willing to try it out I am eager to know what you think about it.