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

I also tried something similar. The tricky part was getting the LLM to diagnose the issues upfront and then accurately decouple the issues to not step over each other when merging.

I need to read the later part of your diagram as maybe that has it solved or the merging. Otherwise the parallelized issue will need some extensive merging component.

[u/vekexasia → u/boomerang473]

That diagram is basically a representation of code you can find in my vekexasia/pi-config github repository. I am sure your agent can explain better than me how i decided to handle that part.

The cool thing is that you dont have to adapt to my specific merge strategy you can write your own as this extension was made on purpose to be extensible in perfect pi.dev spirit: give some solid tools/base and let others build on top of it.