pi-flows

A pi-package that adds multi-agent workflow orchestration to pi. Design flows as YAML DAGs, run them with automatic parallel scheduling, and watch everything in a live TUI dashboard — while the main session stays fully interactive.

Overview

Flows are reusable workflow templates that coordinate multiple AI agents through structured inputs and outputs. Each agent runs in an isolated session with scoped tools and filesystem access.

Best practice usage:

• Research → Plan → Implement → Verify cycles
• Code review pipelines with verify/fix loops
• Documentation generation with multi-domain research
• Refactoring with interactive branching

Installation

pi install npm:pi-flows

Or from a local clone:

pi install /path/to/pi-flows

Quick Start

1. Create an agent (.pi/flows/agents/reviewer.md):

   ---
   name: reviewer
   description: Reviews code for quality issues
   model: @coding
   tools: read, grep, find
   inputs:
     - target_path
   ---
   Review the code for: ${{task}}
   Focus on: ${{input.target_path}}

2. Create a flow (.pi/flows/flows/review/flow.yaml):

   name: review
   description: Research then review code
   task_required: true
   task_prompt: "What should I review?"
   
   steps:
     - id: research
       agent: project-context-reader
       task: Investigate the codebase for ${{task}}
   
     - id: review
       agent: reviewer
       blockedBy: [research]
       inputs:
         target_path: "${{result.research.summary}}"
       task: Review based on research findings

3. Run it:

   /review Fix the auth middleware

Commands & Keybindings

| Command | Description | |---------|-------------| | /flows | List and manage flows (run, delete) | | /skill:manage-flows | Load the flow/agent create-and-edit reference skill | | /flows:delete | Delete a flow | | /roles | Assign models to role tiers (@coding, @planning, etc.) | | alt+a | Toggle auto-routing (agents decide fork branches autonomously) | | alt+x | Abort running flow / dismiss flow summary | | alt+o | Inspect agents (enter dashboard/summary navigate mode) | | alt+t | Toggle thinking in the agent-detail overlay |

Keybindings live in the alt+<letter> namespace to avoid colliding with pi's ctrl+<letter> defaults, and are rebindable via ~/.pi/agent/keybindings.json.

Flows also register as slash commands based on directory path: .pi/flows/flows/review/flow.yaml → /review. Each flow is a self-contained directory — its flow.yaml plus any co-located code-node handlers (<id>.ts).

Core Concepts

• Agents — Markdown files with YAML frontmatter (config) and body (system prompt). Run in isolated sessions with scoped tools and file access.
• Flows — YAML files defining a DAG of steps connected via blockedBy. The engine schedules independent steps in parallel, up to max_concurrent.
• Template variables — ${{task}}, ${{result.step-id.summary}}, ${{input.name}} wire data between steps at dispatch time.
• Model roles — @coding, @planning, @research, @compact map to concrete models via /roles. Each agent declares which tier it needs.
• Edit flow — Create and edit flows/agents conversationally in the main session using the flow_agents and flow_write tools. These tools are off by default; enable them per project or globally with flows.editFlow: true in .pi/settings.json. Load /skill:manage-flows for the format reference.

Writing Agents

Agents are .md files in .pi/flows/agents/ (project-local) or a package's agents/ directory.

---
name: backend-dev
description: Implements backend changes
model: @coding
thinking: high
tools: read, write, edit, grep, bash
inputs:
  - research_context
outputs:
  - verdict
access:
  read: ["src/**"]
  write: ["src/main/**"]
  bash:
    deny: ["rm -rf"]
card:
  label: "Backend Dev"
  metric: developer
---
You are a backend developer. Task: ${{task}}
Context: ${{input.research_context}}

Key fields: model (role tier), tools (allowlist — guard blocks everything else), inputs/outputs (typed data flow), access (filesystem sandbox), card (TUI dashboard rendering).

Writing Flows

Step Types

Every step declares an explicit type: (the parser does not infer it). There are five: agent, fork, agent-decision, code, code-decision.

Agent — dispatch a named agent with a task:

- id: impl
  type: agent
  agent: backend-dev
  blockedBy: [research]
  inputs:
    research_context: "${{result.research.summary}}"

Fork — present a choice to the user (or let an agent decide in auto-routing mode):

- id: choose
  type: fork
  question: "Which approach?"
  options: [Quick fix, Full refactor]
  branches:
    Quick fix: quick-step
    Full refactor: refactor-step
  agent: flow-decision    # used when alt+a (AUTO) is active

Agent Decision — an agent calls finish({ branch }) to route; a branch pointing at an earlier step is a loop (bounded by max_iterations):

- id: verify-loop
  type: agent-decision
  agent: flow-decision
  task: "Check iteration ${{loop.verify-loop.iteration}}/${{loop.verify-loop.max}}"
  branches:
    fix: fixer        # backward target → loops
    done: done        # forward target → exits
  max_iterations: 3   # required when a branch points backward

Code — run a deterministic TypeScript handler as a node (no LLM):

- id: validate
  type: code
  inputs:
    invoice: "${{result.extract.canonical}}"
  outputs:
    - name: valid
  blockedBy: [extract]

Code Decision — a code node that routes on a returned branch (≥2 branches):

- id: route
  type: code-decision
  inputs:
    valid: "${{result.validate.valid}}"
  branches:
    approve: finalize
    reject: notify

Input Wiring

Steps pass data through inputs + template variables:

- id: researcher
  agent: researcher
  task: Investigate ${{task}}

- id: developer
  agent: developer
  blockedBy: [researcher]
  inputs:
    context: "${{result.researcher.summary}}"
    spec_path: specs/api-spec.md    # pass a path; the agent reads it via its `read` tool

The agent's prompt references inputs as ${{input.context}}. Typed outputs declared in agent frontmatter (outputs:) are accessible as ${{result.step-id.outputName}} and are delivered to code-node handlers as their real JSON type when wired as a whole-value reference. File-backed data is passed as a path and read at runtime (give the consuming agent the read tool) — there is no file:// content injection.

TUI Dashboard

When flows run, a live dashboard appears with agent cards in a grid layout. Each card shows status, elapsed time, and domain-specific metrics (files modified, tests passed, etc.). Navigate with arrow keys, expand agent detail views, and see the full flow summary after completion.

Card types (card.metric): developer, researcher, tester, verifier, writer, default — or register custom renderers via flow:register-card.

Integration with pi-agent-dashboard

pi-flows is the engine. The browser dashboard rendering of flow events lives in pi-agent-dashboard as a separate workspace plugin (packages/flows-plugin/). The two repos are intentionally split: pi-flows emits flow:* events; the dashboard reacts to them.

See docs/dashboard-integration.md for the architecture diagram, the wire-protocol bridge, and how to add new flow events end-to-end.

Built-in Agents

| Agent | Role | Description | |-------|------|-------------| | flow-decision | Router | Makes branch/loop decisions for fork and loop steps | | project-context-reader | Researcher | Reads and summarizes project structure |

Developer Docs

Detailed documentation in the docs/ folder:

• Flows Reference — Complete step type reference with syntax and examples
• Agents Reference — Agent frontmatter schema, model tiers, card types
• Flow Authoring — Full format reference for agent and flow files
• Architecture — Internal design: DAG execution, agent isolation, sub-extensions
• Events API — Register custom cards, tools, and listen to flow events
• Public API — Core TypeScript types and functions for programmatic use
• Skills & Extensions — Skill bundles and extension registration
• Tools Reference — Built-in tools available to agents
• Creating Packages — Build domain packages with custom agents and flows
• Extending pi-flows — Advanced customization
• Dashboard Integration — How pi-flows and pi-agent-dashboard connect

Releasing

Releases are automated via .github/workflows/publish.yml. Two paths:

Workflow dispatch (recommended). Open the GitHub Actions UI, run the Release workflow, type the version (e.g. 0.2.2). The workflow bumps package.json, dates the matching ## [Unreleased] (or undated ## [X.Y.Z]) section in CHANGELOG.md to ## [vX.Y.Z] - <today>, commits, tags, pushes, then publishes to npm with provenance via npm Trusted Publishing, and drafts a GitHub Release with the CHANGELOG body.

Tag push. Locally bump the version + CHANGELOG yourself, commit, tag vX.Y.Z, and git push --follow-tags. The same publish + release jobs fire.

Before the first release run, ensure:

1. The npm package @blackbelt-technology/pi-flows has a Trusted Publisher configured pointing at this repo + publish.yml + the npm-publish environment.
2. A GitHub repository environment named npm-publish exists (Settings → Environments). Add a required-reviewer rule there if you want a manual gate before every publish.

Prep your CHANGELOG entry under ## [Unreleased] before triggering the workflow — the heading-dating step rewrites it in place.

See docs/releasing.md for the operator runbook.

License

MIT