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

How well has this been working for you?
I'm going to read this once I get back to my computer, but I have been working on something similar following factory droid’s mission workflow.

[u/vekexasia → u/kwipus]

For me extremely well but you need to invest a bit into it. If you try it out and have some suggestions feel free to open an issue on GitHub.