pi-workflow lets Pi run named, repeatable multi-step workflows: research, code review, spec conformance checks, impact review, and project-specific team routines.

Built on @agwab/pi-subagent, it coordinates Pi subagent workers across workflow steps, passes results between them, and records the run so it can be inspected, stopped, or resumed.

You choose a workflow and describe the task in natural language.

Installation

Install the package:

pi install npm:@agwab/pi-workflow

Then reload Pi.

This installs:

• the /workflow extension
• the bundled workflow-guide skill
• the bundled execution-router skill

To update later:

pi update npm:@agwab/pi-workflow

Requires Node.js >=22.19.0 on macOS or Linux. Native Windows is not supported; use WSL2.

Usage: ask naturally

After installation, ask Pi to use a bundled or project workflow by name and describe the task you want handled. If you are not sure which workflow to use, ask Pi to list or choose from the available workflows.

Bundled workflows use local-first agent lookup and fall back to pi-workflow's bundled common agents such as scout and researcher. Tool-level invocation details live in docs/usage.md.

Use the bundled deep-research workflow to research this repository and summarize the architecture tradeoffs.

Use the deep-review workflow to review the current diff from multiple perspectives.

Use the spec-review workflow to compare docs/API_SPEC.md against the implementation and tests.

If you want deterministic manual control, use the slash command form:

/workflow run deep-research "Research this repository and summarize the architecture tradeoffs."

For opt-in lower-latency deep-research runs, add --thinking low. The measured deep-research pairs show a latency/verified-coverage tradeoff, not a general quality result; package defaults remain conservative. See docs/usage.md.

For a one-off adaptive workflow that should plan, fan out, and synthesize without choosing a saved workflow, use:

/workflow dynamic "Research this repository and summarize the architecture tradeoffs."

/workflow dynamic uses pi-workflow's built-in trusted dynamic controller and records a normal workflow run under .pi/workflows/. Use it when you explicitly want adaptive orchestration rather than a named reusable workflow.

To interrupt a non-terminal run and stop its local supervisor watch, use /workflow stop <run-id>. Resume later with /workflow resume <run-id> if unfinished tasks should be retried.

Diagnose a failed run

Start with the run summary, then inspect only the failing task before resuming:

/workflow status <run-id>
/workflow logs <run-id> <task-id-or-spec-id> 120
/workflow show <run-id>

For a terminal-friendly evidence view, run pi-workflow inspect <run-id> --failures --results. After fixing the reported access, configuration, output, or code problem, use /workflow resume <run-id>; completed task artifacts are preserved.

Usage: choose an execution mode

Use the bundled execution-router skill when you are not sure whether a task should be handled directly, by a targeted verifier/subagent, by an existing workflow, or by a new workflow:

/skill:execution-router decide whether this repository review should use a single-agent pass, deep-review, or a targeted verifier.

Usage: create your own workflows

Use the bundled workflow-guide skill when you want to create, adapt, or review a workflow definition. It includes validated scaffold bundles for common graph shapes, so new workflows can start from a known-good structure before customization and validation:

/skill:workflow-guide create a workflow for weekly release readiness.
It should inspect docs, tests, recent changes, package metadata, and produce a final checklist.
Save it as a reusable project workflow.

/skill:workflow-guide customize deep-review for frontend accessibility and UX review.
Save it as a reusable project workflow.

/skill:workflow-guide create a backend API review workflow.
It should check concurrency, transaction safety, error handling, observability, and test risk.

Workflow architecture

A workflow is a deterministic stage graph for running one natural-language task through a reusable process.

pi-workflow is organized around three parts:

1. Workflow — the graph and run lifecycle: what stages exist, when they run, and how outputs move forward.
2. Task — agent-backed work: focused prompts, dynamic fan-out, fan-in synthesis, and bounded loops.
3. Support — deterministic local rails: helper code, validation, normalization, artifacts, and resume-friendly run state.

In short: workflows define the process, tasks ask Pi agents to do the work, and support keeps the process structured and repeatable.

A small workflow definition looks like this:

{
  "schemaVersion": 1,
  "defaults": {
    "agent": "researcher",
    "readOnly": true,
    "tools": ["read", "grep", "find", "ls"]
  },
  "artifactGraph": {
    "stages": [
      {
        "id": "plan",
        "type": "single",
        "prompt": "Put machine-readable JSON in <control> with an items array."
      },
      {
        "id": "inspect",
        "type": "foreach",
        "from": { "source": "plan", "path": "$.items" },
        "each": { "prompt": "Inspect this item: ${item}" }
      },
      {
        "id": "prepare",
        "from": "inspect",
        "sourcePolicy": "partial",
        "support": { "uses": "./helpers/prepare.mjs" }
      },
      {
        "id": "report",
        "type": "reduce",
        "from": ["plan", "prepare"],
        "prompt": "Use upstream workflow artifacts to write the final report."
      }
    ]
  }
}

Supported stage patterns

Workflow definitions compose a small set of stage patterns and graph shapes.

| Pattern | Use it for | Runtime shape | |---|---|---| | single | One focused step | one prompt -> one subagent | | foreach | Dynamic fan-out | JSON array from an upstream control artifact -> one subagent per item | | reduce | Fan-in / synthesis | upstream workflow artifacts -> one synthesis subagent | | loop | Bounded repetition | repeat child stages until a deterministic stop condition | | dag | Nested graph container | child stages lowered to namespaced tasks; selected output exposed downstream | | dynamic | Adaptive orchestration | trusted bundle-local controller code can create official workflow tasks with ctx.agent() |

Predefined workflows

The package includes four bundled workflows for common research and review jobs. They are runnable defaults and authoring examples, not a complete workflow catalog.

| Workflow | Best for | What it does | |---|---|---| | deep-research | Deep, source-grounded research when breadth, verification, and cited recommendations matter. | Plans research questions by depth, fans out question-level research, normalizes and ranks claims, verifies selected claims against evidence, and renders an audited executive handoff. | | deep-review | Code or design review when one reviewer pass is not enough. | Triage selects review lenses, reviewers produce findings, a deterministic helper deduplicates them, a challenge pass tests the surviving findings, a deterministic helper partitions verdicts, and the final report keeps only evidence-backed issues. | | spec-review | Requirements-to-implementation traceability for an existing spec, API contract, or acceptance criteria. | Extracts testable requirements, maps implementation and tests, verifies candidate gaps, and reports which requirements are covered, missing, ambiguous, or need human judgment. | | impact-review | Side-effect and risk review for proposed or applied changes. | Maps change scope and affected surfaces, analyzes contract, state/data, validation, docs, security, and performance impact, then joins those lenses into likely regressions, missing checks, and next actions. |

More official workflows are planned. Most teams should create project-specific workflows as their patterns settle.

Workflow board

After starting a run, open /workflow to inspect it in a read-only TUI. Browse runs, drill into stages and tasks, and preview task output without leaving Pi.

Start from the run list.

Drill into stage progress.

Inspect task-level fan-out.

Open a task detail view with its artifact output.

More

• docs/usage.md — command reference, workflow resolution, run artifacts, and authoring rules.
• workflows/README.md — bundled workflow notes.

Runtime dependencies

pi-workflow bundles the runtime pieces it needs:

• @agwab/pi-subagent launches and tracks the Pi subagent workers used by workflow tasks.
• pi-web-access provides web tools such as web_search, fetch_content, get_search_content, and code_search when a workflow or agent requests them.

The web provider is just a tool provider. You can replace or narrow it with your own extension if it exposes compatible tool names, arguments, and results. Be careful when changing providers: if the tool result shape, reference/evidence formatting, or field names differ, workflow specs, prompts, and control/output schemas that depend on those fields may need to change too. The stage graph and normal workflow run record format do not need to change for a compatible web-tool implementation swap.