pi-workflow 是一个为 Pi 设计的工作流编排工具，让 Pi 能执行多步骤、可复用的工作流，而不是只有单轮对话。用自然语言就能触发，不用每次手写提示词。

四种工作流直接用：

• deep-research 做深度研究
• deep-review 审代码
• spec-review 查规格
• impact-review 评估影响。

工作流定义成 JSON 阶段图，支持 single、foreach、reduce、loop、dag、dynamic 六种模式。

https://github.com/AgwaB/pi-workflow…

AgwaB/pi-workflow

Source: https://github.com/AgwaB/pi-workflow

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 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.

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.

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.