pi-workflow: named stage graphs for Pi subagents
Workflow orchestration for Pi
At a glance
- What is it?
- AgwaB/pi-workflow turns a natural-language task into a reusable stage graph that Pi executes across subagent workers, with run state written to .pi/workflows. It is worth adopting if your team repeats the same multi-step review or research pass, and the wrong tool if you want a general-purpose agent framework.
- Who is it for?
- Adopt pi-workflow if your team already runs Pi and keeps repeating the same multi-step pass (deep review, spec conformance, release readiness) and you want that process written down as a JSON stage graph instead of retyped prompts. Do not adopt it if you are not on Pi, if you need native Windows support, or if you want a general agent framework rather than a process runner bolted onto one.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 9 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The repeated-prompt problem pi-workflow is aimed at
Most teams that use an agent CLI end up with a handful of prompts they type over and over: review this diff, check the spec against the implementation, summarise the architecture. The prompt text drifts, the order of steps drifts, and nothing about the run is recorded in a form you can inspect afterwards. pi-workflow targets exactly that. The README describes it as letting Pi "run named, repeatable multi-step workflows: research, code review, spec conformance checks, impact review, and project-specific team routines." The unit of reuse is a named workflow, not a saved prompt. The audience is a team already inside Pi, on macOS or Linux, that wants its review process expressed as a graph rather than as a paragraph of instructions retyped each time. It is not aimed at someone looking for an agent runtime to build on. It sits on top of @agwab/pi-subagent and coordinates workers that Pi already provides.
Stage graph, task, support: the three-part split
The README divides the project into three parts. A workflow is the graph and run lifecycle: which stages exist, when they run, how outputs move forward. A task is agent-backed work: focused prompts, dynamic fan-out, fan-in synthesis, bounded loops. Support is the deterministic local layer: helper code, validation, normalisation, artifacts, and resume-friendly run state. The split matters because it tells you where your own code goes. If you need a parsing step that must not be left to a model, it belongs in support as a helper module, not in a prompt. The graph itself is a JSON object with a schemaVersion, a defaults block (agent, readOnly, tools), and an artifactGraph containing stages. In the README example, a plan stage prompts for machine-readable JSON in a control block with an items array, an inspect stage of type foreach reads that array via a from source and path, a prepare stage runs a helper at ./helpers/prepare.mjs with sourcePolicy partial, and a report stage of type reduce takes plan and prepare as inputs for a synthesis prompt. Data flows forward through named artifacts, and the reduce stage is the only point where multiple upstream artifacts are merged.
The five stage patterns and what each one constrains
The README lists five patterns. single maps one prompt to one subagent. foreach takes a JSON array out of an upstream control artifact and spawns one subagent per item, which is how dynamic fan-out happens without you naming the items in advance. reduce takes upstream workflow artifacts into one synthesis subagent. loop repeats child stages until a deterministic stop condition, so the termination logic is not a model judgement. dag is a nested graph container whose child stages are lowered to namespaced tasks. The design choice worth noting is that fan-out is driven by a control artifact rather than by the orchestrator reasoning about how many workers to start. That makes the width of a run inspectable before it executes, and it means a malformed control artifact is a real failure point rather than something the model can paper over. It also means the plan stage has to be written to emit parseable JSON, which the README example states explicitly in the prompt text.
Installing it and the commands you actually type
Installation is two commands. The README gives pi install npm:@agwab/pi-workflow, then a Pi reload. That installs the /workflow extension plus two bundled skills, workflow-guide and execution-router. Updates use pi update npm:@agwab/pi-workflow. The runtime requirement is Node.js >=22.19.0 on macOS or Linux, and the README states plainly that native Windows is not supported and WSL2 should be used instead. There are two invocation styles. Natural language works: ask Pi to use a bundled or project workflow by name and describe the task, for example "Use the spec-review workflow to compare docs/API_SPEC.md against the implementation and tests." For deterministic control there is the slash form, /workflow run deep-research "Research this repository and summarize the architecture tradeoffs." A third form, /workflow dynamic, skips saved workflows entirely and plans, fans out and synthesises in one pass. Execution profiles are opt-in: a workflow may declare executionProfiles and a defaultExecutionProfile, selected with /workflow run --profile <name>. The README is explicit that low, medium and high are conventions rather than reserved names, and that the system does not infer a profile called medium.
Run state, the active-workflows widget, and what resume depends on
Interactive slash-command launches use Pi's cancellable foreground loader while routing, validating and completing the initial scheduling pass. Once at least one backend task is running, the command returns and Pi shows an Active workflows widget below the editor plus a footer status. The README says the widget excludes launch and preparation states and stale running records with no running task, tracks top-level run progress, and survives session reload by rebuilding from .pi/workflows. That last detail is the load-bearing one. Run state lives in a directory in your project, and the widget is a view reconstructed from it rather than in-memory state. If you move or clean .pi/workflows, you are removing the record the resume path reads. The README also mentions recording the run so it can be "inspected, stopped, or resumed," which is the whole argument for keeping the state on disk. Treat that directory as part of your working tree hygiene, the same way you would treat a lockfile.
Where pi-workflow is the wrong tool
The clearest boundary is platform. Native Windows is not supported, and the README directs you to WSL2. If your engineers work on Windows without WSL, this project is not for you, and that is a stated constraint rather than a bug you can work around. The second boundary is dependency. pi-workflow is built on @agwab/pi-subagent and installed through Pi, so it is not usable outside that ecosystem. If you are evaluating agent frameworks in general, this is a process layer for one specific host. The third is the bundled agent fallback. Bundled workflows use local-first agent lookup and fall back to pi-workflow's bundled common agents such as scout and researcher. In an environment where those lookups resolve differently than expected, a workflow you did not write may not behave the way the README implies. The fourth is that a stage graph is a commitment. If your review process genuinely changes shape every week, writing a graph for it costs more than typing the prompt, and /workflow dynamic exists precisely because saved workflows are not always the right answer.
How this differs from hand-rolled subagent prompting
The obvious alternative is calling Pi subagents directly and letting the model decide the sequence, which is what people do before they reach for an orchestrator. The difference is where the control flow lives. With direct prompting, the model decides how many workers to spawn and when to stop, and the run leaves no structured record. With pi-workflow, the graph decides: foreach reads a JSON array from a named artifact, loop repeats until a deterministic stop condition, reduce merges named upstream artifacts. The README frames the workflow as "a deterministic stage graph for running one natural-language task through a reusable process." That is the trade in one line. You give up the model's freedom to restructure the run mid-flight and you get a process you can name, save as a project workflow, inspect on the board, and resume. The bundled execution-router skill exists for the case where you have not decided which side of that trade you want, and the README offers it as the way to decide whether a task should go direct, to a targeted verifier, to an existing workflow, or to a new one.
Maintenance cost, version cadence and the MIT licence
The release history shows v0.13.6, v0.13.7 and v0.13.8 within three days in September 2026, and the repository was last pushed the same day as the newest release. A cadence that tight on a 0.x line means you should expect to run pi update npm:@agwab/pi-workflow regularly rather than pinning once and forgetting. It also means workflow definitions you write against schemaVersion 1 are the thing to re-check after an upgrade, since that field exists to signal format changes. The licence is MIT, which permits commercial use and modification, but this is not legal advice and you should read the licence text yourself before relying on it in a product. One practical cost the README does not address: because workflows can be saved as project workflows, they become shared artifacts, and a saved workflow that depends on a helper under ./helpers/ is only as portable as that helper. Nothing in the supplied material describes a migration path for workflow definitions across schema versions.
Editorial conclusion
Adopt pi-workflow if your team already runs Pi and keeps repeating the same multi-step pass (deep review, spec conformance, release readiness) and you want that process written down as a JSON stage graph instead of retyped prompts. Do not adopt it if you are not on Pi, if you need native Windows support, or if you want a general agent framework rather than a process runner bolted onto one. Before committing, verify three things against your own setup: that Node.js is at least 22.19.0, that your Pi install resolves the bundled scout and researcher agents or that you have local equivalents, and that a /workflow run deep-research invocation survives a session reload by rebuilding its widget from .pi/workflows. If the third check fails on your machine, the resume story is the part of this project you cannot rely on.
Community notes