pi-workflows

A configurable pi extension for defining and running named multi-phase workflows with tool control, subworkflow nesting, and state persistence.

Features

• Named workflows — Define any number of workflows as standalone directories with a workflow.yaml file, each invoked by a unique slash command.
• Configurable phases — Each phase specifies its own instructions, emoji, and available subagent profiles.
• Per-phase tool control — Restrict tools per phase using a blacklist (block specific tools) or whitelist (allow only specific tools).
• Subworkflow nesting — Compose workflows by referencing other workflows as phases, with cycle detection and breadcrumb navigation.
• State persistence — Workflow state survives session restarts via pi.appendEntry.
• Auto-continue enforcement — The agent cannot finish until the workflow reaches DONE; a configurable reminder is injected on premature agent_end.
• Template variables — Use {workflowName}, {phaseName}, {taskDescription}, and more in messages and instructions.
• Slash commands — Start workflows with /workflow, cancel with /cancel-workflow, and inspect progress with the workflow_step tool.

Installation

pi install git:github.com/harms-haus/pi-workflows

Quick Start

1. Create a workflow directory under .pi/workflows/ in your project (or ~/.pi/agent/workflows/ globally):

mkdir -p .pi/workflows/my-workflow

2. Write workflow.yaml with two phases referencing markdown files:

name: My Workflow
commandName: my-workflow
initialMessage: 'Starting {workflowName} for: "{description}"'
phases:
  - gather.md
  - execute.md

Create the phase files alongside workflow.yaml:

## <!-- gather.md -->

id: gather
name: Gather
emoji: "🔍"

---

Research the task and summarize findings.

## <!-- execute.md -->

id: execute
name: Execute
emoji: "🔨"
tools:
whitelist: - edit - write - workflow_step

---

Implement the solution based on gathered research.

See docs/configuration-reference.md for the full schema.

3. Run the workflow in your pi session:

/workflow my-workflow add user authentication

Usage

Commands

| Command | Description | | --------------------------------------- | ----------------------------------------------------------- | | /workflow {commandName} {description} | Start a workflow | | /cancel-workflow | Cancel the active workflow (bypasses the not-done reminder) |

workflow_step Tool

| Action | Description | | -------- | ----------------------------------------------------------------------- | | status | Show current workflow state, phase instructions, and available profiles | | next | Advance to the next phase (or DONE if on the last phase) | | cancel | Cancel the active workflow (requires two calls to confirm) | | loop | Restart the current scope from phase 0 (if the workflow is loopable) |

For complete examples, see docs/examples.md.

Documentation

| Document | Description | | ---------------------------------------------------------- | -------------------------------------------------------- | | Configuration Reference | Full schema for workflow.yaml and phase markdown files | | Template Variables | All available {variables} and where they can be used | | Subworkflows | Composing workflows from other workflows | | Examples | Complete workflow definitions and usage patterns | | Architecture | Extension structure, hooks, and data flow | | Hook Lifecycle | How hooks intercept agent turns and tool calls | | State Management | How workflow state is tracked and persisted | | Testing | Running and writing tests for the extension | | Contributing | Development setup and contribution guidelines |

License

MIT