# pi-workflow turns a saved stage graph into a run you can stop and resume > A Pi extension that runs named multi-step workflows across subagents, with three slash commands that differ in what they guarantee, execution profiles captured at run start, and run state rebuilt from .pi/workflows after a session reload. **AgwaB/pi-workflow** — Workflow orchestration for Pi - Repository: https://github.com/AgwaB/pi-workflow - Stars: 363 · Forks: 13 - Language: JavaScript - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/agwab-pi-workflow ## A saved stage graph, run by subagents, recorded as a run pi-workflow is an extension for the Pi coding agent that runs named, repeatable multi-step workflows, of which the bundled set covers research, deep review, spec conformance checks and impact review, plus whatever your project adds. A workflow is defined as a deterministic stage graph for taking one natural-language task through a reusable process, and the definition itself is JSON beginning with a schema version. The execution model is built on `@agwab/pi-subagent`: pi-workflow coordinates subagent workers across stages, passes results from one stage to the next, and records the run so it can be inspected, stopped or resumed. That last property is the one that changes how you use it. Runs are not a fire-and-forget invocation, and the state lives under `.pi/workflows` in the project, which is what lets an `Active workflows` widget rebuild itself after a session reload. Underneath, the code is organised in three parts. The workflow is the graph and the run lifecycle, deciding what stages exist and how outputs move forward. Tasks are the agent-backed units, with focused prompts, dynamic fan-out, fan-in synthesis and bounded loops. Support is the deterministic local layer: helper code, validation, normalization, artifacts and resume-friendly state. ## Three commands, three different guarantees The slash commands are easy to confuse and deliberately not interchangeable. Written out, the three forms are: ```text /workflow run deep-research "Research this repository and summarize the architecture tradeoffs." /workflow dynamic "Research this repository and summarize the architecture tradeoffs." /workflow auto "Review the current diff for reliability and test coverage." ``` `run` always starts the named workflow, whatever it finds. `dynamic` always starts the direct dynamic runtime, which plans, fans out and synthesises without a saved definition. `auto` starts nothing on its own: it compares the dynamic runtime against the discoverable named workflows and returns a recommendation, and it explicitly does not offer a choice from the current conversation. Where `auto` runs changes what you get. In the TUI it requires a candidate choice plus a separate final confirmation before anything starts. In print, RPC or headless mode it only prints the recommendation and the follow-up commands, which is the behaviour a script can act on and a person cannot confirm from. Launching is cancellable while the initial scheduling pass validates and completes, and the command returns as soon as one backend task is actually running, leaving the widget and a compact footer to track the rest. ## Profiles are captured at run start, so a run cannot drift Execution profiles decide which model and thinking level each stage uses, and `/workflow profile` in the TUI previews and privately saves one of Codex, Codex High, Claude, Mixed, or a per-stage custom setup. Asked without a workflow argument, the picker shows each workflow's saved profile rather than the path to it, with coloured columns for stage, role, model and thinking level. The design decision worth noting is when the values are read. The preference belongs to the workflow definition and is reused across projects, but every launch, interactive, headless, auto-confirmed or `workflow_run`, captures the effective values at run start. A long run therefore cannot have its backend swapped underneath it halfway through because someone changed a setting in another project. Two consequences follow. A workflow can declare its own custom-named `executionProfiles` with a `defaultExecutionProfile`, and an explicit `/workflow run --profile ` wins over a saved user profile. And a missing model capability or a stale workflow definition block produces an explanation rather than a silent substitution, so a run either starts with the profile you meant or tells you why it cannot. ## Two bundled skills that advise and deliberately do nothing Installing the package brings two skills with it, and both are constrained in ways that are easier to respect once you know they are deliberate. `execution-router` answers a routing question: should this be handled directly, by a targeted verifier or subagent, by an existing workflow, or by a request to author a new one. It is advisory and does not launch, validate, author or redirect a workflow. In practice that means the suggestion arrives as text and you still type the command, which is the correct shape for something that decides how much compute you are about to spend. `workflow-guide` creates, adapts and reviews definitions, and it ships validated scaffold bundles for common graph shapes so a new workflow starts from a structure that has already been checked. Its `fixed-inventory` scaffold is the interesting one: when the caller already knows which documents matter, the scaffold binds them with static code instead of spending a model stage restating known file paths. That is a small design with a large effect on cost, and the boundary it operates under, editorial only, is documented in the usage reference rather than in the README. ## Install is one command, on a Node floor that excludes native Windows Installation goes through Pi's own package command: ```bash pi install npm:@agwab/pi-workflow ``` Reloading Pi afterwards registers three things: the `/workflow` extension, the bundled `workflow-guide` skill and the bundled `execution-router` skill. Updating later uses the matching verb: ```bash pi update npm:@agwab/pi-workflow ``` The requirement is Node.js 22.19.0 or newer on macOS or Linux, and native Windows is not supported, with WSL2 named as the route. A 22.19 floor is not a formality for an agent extension that spawns subagents concurrently. One packaging detail to know before you automate an install. The published file list carries `src` alongside `dist`, and the exports map sends `./extension` to `./src/extension.ts` while the package entry point is `./dist/index.js`, with the `pi-workflow` binary pointing at `src/cli.mjs`. So consumers get compiled JavaScript for the main entry and TypeScript source for the extension, which is a deliberate choice for a package meant to be read as well as run. ## The release gate is five chained scripts, and tests use node --test The package scripts describe how this project treats a release as done. The `validate` script is the gate, and it chains five checks in order: ```bash npm run check:scripts && npm run check:release-workflow && npm run check:public-surface && npm run typecheck && npm run test:unit ``` Three of those are release-specific rather than ordinary linting: a scripts check, a publish-workflow check, and a public-surface check that guards what the package exports. The last is the interesting one for anyone depending on it, since a change to the exported surface is exactly the kind of edit that passes every test and breaks a consumer. Unit tests run on Node's built-in runner rather than a framework: ```bash node --test test/unit/*.test.mjs ``` The test step compiles twice on purpose, once into `dist` and once into a temporary directory, so the suite exercises built output rather than only source. Alongside `test/` there are `tools/` for those release checks, `agents/`, `skills/` and `workflows/` directories that ship in the package, and `docs/usage.md` as the only documentation file included in the tarball. The licence is MIT, the repository is not archived, and releases moved v0.14.0 on 2026-09-17, v0.14.1 on 2026-09-20 and v0.15.0 on 2026-09-29. ## Conclusion pi-workflow suits a team that repeats the same review or research routine and wants the fan-out written down as a graph instead of retyped as a prompt, and it suits anyone who needs a run to survive a session reload. It does not suit a single ad-hoc task, since authoring a definition costs more than typing the request once, and the advisory skills deliberately refuse to launch anything. Verify first that Node 22.19.0 or newer is available on your platform, that WSL2 is acceptable if you are on Windows, and that the profile your workflow names exists on the model you plan to point it at, since a missing capability blocks the run rather than degrading it. ## FAQ ### How do I install pi-workflow? Run `pi install npm:@agwab/pi-workflow` and reload Pi. That registers the `/workflow` extension plus the bundled `workflow-guide` and `execution-router` skills. Updating later is `pi update npm:@agwab/pi-workflow`, and Node.js 22.19.0 or newer is required on macOS or Linux, with WSL2 for Windows. ### What is the difference between /workflow run, dynamic and auto? `run` always starts the named workflow and `dynamic` always starts the direct dynamic runtime. `auto` starts nothing itself: it compares the dynamic runtime with the discoverable named workflows and returns a recommendation, requiring a candidate choice and a separate confirmation in the TUI, and printing only the recommendation in headless mode. ### What are execution profiles in pi-workflow? They set the model and thinking level per stage, saved privately with `/workflow profile` as Codex, Codex High, Claude, Mixed or a custom setup. The saved preference is reused across projects, and every launch captures its effective values at run start, so a run cannot change backend mid-flight. ### Can I resume a pi-workflow run after restarting Pi? Runs are recorded and state lives under `.pi/workflows`, which is what lets the `Active workflows` widget rebuild itself after a session reload. The widget hides launch and preparation states and stale running records with no running task, and `/workflow` opens the full board. ### What does the execution-router skill do in pi-workflow? It advises whether a task should be handled directly, by a targeted verifier or subagent, by an existing workflow, or by authoring a new one. It is advisory and does not launch, validate, author or redirect a workflow, so you still issue the command yourself. ## Sources - [AgwaB/pi-workflow on GitHub](https://github.com/AgwaB/pi-workflow) - [Issues](https://github.com/AgwaB/pi-workflow/issues) - [License: MIT](https://github.com/AgwaB/pi-workflow/blob/main/LICENSE) - [README](https://github.com/AgwaB/pi-workflow/blob/main/README.md) - [Releases](https://github.com/AgwaB/pi-workflow/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agwab-pi-workflow