pi-baton0.8.6

Pi-native workflow baton runner with per-step model switching and isolated step context.

GitHub Actions Published 19 days ago MIT ~685 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

Pi Baton

Run YAML-defined review loops in Pi with per-step model switching and isolated step context.

What this is

Pi Baton is a Pi-native workflow baton runner. Define implement → review → fix loops in YAML, and let Pi Baton execute them with automatic baton handoff between isolated subagent steps.

Features

Per-step model switching — fast model for implement, strong model for review
Isolated step context — no shared conversation pollution between steps
Structured review contract — accept/reject with mandatory findings or acceptance notes
Live progress widget — see which step is running, its agent, and judgment in real time

Install

Install the published npm package with Pi:

pi install npm:pi-baton

Pin a specific version when you want reproducible installs:

pi install npm:pi-baton@0.9.1

Install into the current project instead of your user Pi settings:

pi install npm:pi-baton -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-baton

Try it without permanently installing:

pi -e npm:pi-baton

Quick start

Try this package locally from a clone of this repository:

pi -e .

Then run:

/baton:new        create a workflow scaffold
/baton:start      choose workflow + task brief → idle run
/baton:run        execute run to terminal state (with live widget)
/baton:status     show the active run summary, or the most recent finished run
/baton:history    list recent completed or failed runs from persisted history
/baton:inspect    choose a terminal run and inspect its structured step summaries

Use /baton:status for the active run or the single most recent finished run. Use /baton:history to find a recent completed or failed run and its run directory; use /baton:inspect to choose one of those runs and read its bounded structured step summaries and review decision. /baton:inspect never opens raw output.

Builtin workflows work out of the box — no agent setup required:

Default Review Loop (implement → review → fix)
Two-Stage Review Gauntlet (draft → technical_review → editorial_review, with rejects routed through fix)

Prerequisites

Pi Baton ships builtin worker and reviewer subagents under agents/. They work with your current Pi model.

To override with custom agents, place .md files under:

.pi/agents/worker.md
.pi/agents/reviewer.md

Discovery order: project .pi/agents/ → user ~/.pi/agent/agents/ → pi-baton builtin.

Workflow authoring

See docs/workflows.md for an end-to-end walkthrough: step kinds, transitions, the review contract, iteration_cap, model overrides, and agent discovery order.

/baton:new

Pick a name and a scaffold from default-review-loop is written to .pi/baton/workflows/ and opened in editor. The scaffold includes <your-fast-model> / <your-strong-model> placeholders for step-level model overrides.

The shipped workflows/ directory also includes two-stage-review-gauntlet.yaml, a second builtin graph that demonstrates chaining two review gates before completion.

Workflow YAML reference

name: My Review Loop
iteration_cap: 5
steps:
  implement:
    agent: worker
    model: openai/gpt-5.4        # optional: fast model
    prompt: work prompt
    next: review
  review:
    agent: reviewer
    model: anthropic/claude-opus-4-5  # optional: strong model
    prompt: review prompt
    on_accept: _complete         # or a step name
    on_reject: fix
  fix:
    agent: worker
    model: openai/gpt-5.4
    prompt: fix prompt
    next: review

on_accept: _complete ends the run.
iteration_cap prevents infinite review loops — the run fails at the cap.
Review agents must return accept/reject with findings or acceptance notes.

Package contents

Path	Purpose
`extensions/`	Slash-command entrypoints (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`, `/baton:history`, `/baton:inspect`)
`lib/`	Workflow parser, run engine, subagent runner, review contract, UI widget
`agents/`	Builtin `worker` and `reviewer` subagent definitions
`workflows/`	Builtin workflows (`default-review-loop.yaml`, `two-stage-review-gauntlet.yaml`)
`assets/`	README / package branding assets
`docs/`	Workflow authoring guide, release and maintainer documentation

Development

npm install
npm run ci

Release

This package uses npm Trusted Publishing with GitHub Actions OIDC — no NPM_TOKEN is required.

npm version patch
git push

On main, version bumps trigger auto-release and publish workflows. See docs/release.md for setup details.

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

License

MIT