pi-epic-pipeline

Autonomous BMAD epic pipeline orchestrator for pi. Runs stories through create → dev → review → gate phases automatically, switching models per phase and looping on review findings.

Prerequisites

• pi CLI installed and on your PATH
• Node.js ≥ 20

Installation

Via npm (global CLI)

npm install -g pi-epic-pipeline
pi-epic-pipeline --help

Via pi package manager

pi install npm:pi-epic-pipeline

From git

pi install git:github.com/your-org/pi-epic-pipeline

Local development

git clone https://github.com/your-org/pi-epic-pipeline.git
cd pi-epic-pipeline
npm link
pi-epic-pipeline --verbose

Quick Start

1. Create a sprint status YAML (e.g. _bmad-output/implementation-artifacts/sprint-status.yaml):

   epic-5: in-progress
   5-1-auth: ready-for-dev
   5-2-login: backlog
   5-3-logout: done
   

2. Create a model policy (e.g. .pi/bmad/model-policy.json):

   {
     "tiers": {
       "smart": ["anthropic/claude-opus-4"],
       "fast": ["anthropic/claude-sonnet-4"]
     },
     "presets": {
       "story-prep": { "model": "fast", "thinking": "medium" },
       "story-dev": { "model": "smart", "thinking": "high" },
       "review": { "model": "smart", "thinking": "high" },
       "gate-light": { "model": "fast", "thinking": "low" }
     }
   }
   

3. Run the pipeline:

   pi-epic-pipeline --verbose
   

Usage

pi-epic-pipeline [options]

Options:
  --epic <id>          Target specific epic (auto-detected otherwise)
  --story <key>        Target a single story only
  --config <path>      Load explicit config file
  --cwd <path>         Project working directory (default: .)
  --pi-cwd <path>      Working directory passed to pi --cwd (default: same as --cwd)
  --status-file <path> Sprint status YAML path
  --policy-file <path> Model policy JSON path
  --checkpoint-file <path> Checkpoint file path
  --dry-run            Print plan without executing
  --verbose            Stream full agent output
  --interactive        Pause for confirmation before each phase
  --continue           Resume from last checkpoint

Configuration

Configuration is resolved in this order (later overrides earlier):

1. Built-in defaults
2. .pi/epic-pipeline.json (searched upward from cwd)
3. package.json → "epicPipeline" field
4. Explicit --config <file>
5. CLI flags (--cwd, --status-file, etc.)

Example .pi/epic-pipeline.json

{
  "cwd": "hst-registration",
  "statusFile": "_bmad-output/implementation-artifacts/sprint-status.yaml",
  "policyFile": ".pi/bmad/model-policy.json",
  "checkpointFile": ".pi/bmad/pipeline-checkpoint.json",
  "storyKeyPattern": "^(?:rb)?\\d+-\\d+-",
  "excludeStoryPatterns": ["^epic-", "-retrospective$"],
  "epicExtractor": "^((?:rb)?\\d+)-",
  "phases": {
    "backlog": ["create-story", "dev", "review", "gate"],
    "ready-for-dev": ["dev", "review", "gate"],
    "in-progress": ["dev", "review", "gate"],
    "review": ["review", "gate"]
  },
  "presets": {
    "create-story": "story-prep",
    "dev": "story-dev",
    "review": "review",
    "gate": "gate-light"
  },
  "prompts": {
    "create-story": "bmad-create-story {{story}}",
    "dev": "bmad-dev-story {{story}}",
    "review": "bmad-code-review",
    "gate": "Run a gate check for story {{story}}..."
  },
  "reviewOptions": {
    "maxAutoFixes": 2,
    "fixPreset": "story-dev",
    "blockingPatterns": ["blocking", "critical.*issue", "must\\s+fix"],
    "passPatterns": ["no\\s+blocking", "review\\s+pass"]
  }
}

Prompt Templates

Prompts support these placeholders:

Placeholder	Description
{{story}}	Story key (e.g. 5-1-auth)
{{cwd}}	Absolute path to pi working directory
{{statusFileRel}}	Status file path relative to project root
{{statusFile}}	Absolute status file path
{{policyFileRel}}	Policy file path relative to project root
{{policyFile}}	Absolute policy file path
{{checkpointFileRel}}	Checkpoint file path relative to project root
{{checkpointFile}}	Absolute checkpoint file path

Architecture

The pipeline runs each phase in a fresh pi --mode rpc process to avoid context pollution. Between phases:

• Model switches according to policy preset
• Thinking level adjusts per preset
• Review phase runs an auto-fix loop (switches to dev model, applies fixes, re-reviews)

Phase Flow

for each incomplete story:
  create-story  → story-prep preset
  dev           → story-dev preset
  review        → review preset  (+ fix loop)
  gate          → gate-light preset

Output

Without --verbose:

• Step header with phase, story, model, and thinking level
• Animated spinner with elapsed time
• 5-line output preview after each turn
• Timer summaries for each sub-step

With --verbose:

• All of the above, plus full streamed agent output

Checkpointing

If the pipeline fails or is interrupted, a checkpoint is saved. Resume with:

pi-epic-pipeline --continue

License

MIT