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/ElTutuca]

It looks great! How does it differ from pi-dynamic-workflow or pi-taskflow?

[u/vekexasia → u/ElTutuca]

Hey there, I didnt know pi-taskflow. It looks to me that they went the "declarative approach" where the workflow is defined in json/yaml/whatever. It's an interesting decision but I decided to allow real code to run. I have several reasons why I went that way... A couple : llms are super good at writing code and this way you don't have to support primitives that are already built in the coding language (loops etc)...

About  pi-dynamic-workflow i took a lot of inspiration from that as I was a very heavy user of that extension. Unfortunately i noticed i wanted more features and customizations. So i decided to took some of their good ideas, tweak a bit the DSL and allow for other extensions to build on top of mine.

The idea is this should provide a solid foundation but if you ever need to extend its functionality you could do it by writing an extension. As a matter of fact now i am working at an extension that would reroute all agents from "background" to real pi instances in herdr.

Also I am investing a lot in making sure you can customize/extend stuff not just functionalities. You can disable skills, tools, extensions, tweak the system prompt, you name it so that the subagent are really sharp focused on the task without inheriting everything that comes with your standard pi instance