pi-workflow

Workflow orchestration for Pi.

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 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 runs, add --thinking low; defaults remain conservative pending holdout evidence. 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.

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.