pi-spine

Orchestration spine for long-running pi development.

pi-spine is a pi package for parallel, multi-day agent batches on real codebases. It combines Taskplane-style task packets, Babysitter-grade audit history, and pi-conductor-inspired human gates in one pi-native flow — compose, don't merge the best patterns into a single pi-native spine.

pi-spine is	pi-spine is not
A pi extension + CLI (spine) for batch orchestration	A replacement for pi itself
Compatible with Taskplane PROMPT.md / STATUS.md packets	A fork of Taskplane
An append-only orchestration journal for control-plane events	A full Babysitter process-definition engine
Human gates before integrate/merge	A clone of pi-conductor's external control-plane DB (archived upstream)
Worktree-isolated parallel lanes	Cross-harness routing (Cursor, Codex, etc.) in v1

Feature summary

• Taskplane-compatible tasks — PROMPT.md, STATUS.md, dependencies.json
• Dependency waves — topological scheduling with parallel lanes
• Git worktree isolation — one lane per worktree; orch branch for integration
• STATUS-first workers — checkpoint discipline and step-boundary commits
• Cross-model review — reviewer model configurable separately from worker
• Orchestration journal — JSONL event log for debugging and resume context
• Human gates — approve or reject integrate with test/build evidence
• Local dashboard — batch, lane, and gate visibility (SSE)
• create-spine-tasks skill — decompose PRDs into spine-tasks/ packets (local install)

Inspired by

pi-spine builds on ideas from Taskplane, Babysitter, and pi-conductor (archived). For comparisons, trade-offs, and when to use each tool alone, see Why pi-spine?.

Honest limits

pi-spine ships operator-driven batch monitoring, not autonomous supervision.

Out of scope	What to use instead
Supervisor mail — conversational nudges between orchestrator and workers	spine status --diagnose, dashboard diagnosis banner
Autonomous monitor agent — background session polling batch health	CLI + dashboard surfaces; human operator runs suggested commands

Primary monitor surfaces: spine status --diagnose, spine dashboard / /spine-dashboard, and the operator runbook. The .spine/agents/supervisor.md template documents this no-agent reality; the batch engine does not spawn it.

Prerequisites

Dependency	Required
Node.js ≥ 22	Yes
pi coding agent	Yes
Git (worktree support)	Yes

Install

pi install npm:pi-spine
# or: npm install -g pi-spine

For git/path development installs, see local-install.md. After install, spine doctor warns when a stale global spine on PATH does not match your checkout.

Doc	Purpose
bootstrap-checklist.md	First-time consumer setup
operator-runbook.md	Daily operator procedures
cursor-rules-discovery.md	Contributor Cursor rules (contributors)

Quick start

1. Install and init — pi install npm:pi-spine then cd my-project && spine init && spine doctor
2. Plan and preflight — spine preflight && spine plan all (pi: /spine-plan all)
3. Start a batch — spine batch start pending (pi: /spine pending)
4. Monitor — spine status --diagnose (pi: /spine-status)
5. Land on main — spine gate status → spine gate approve → spine integrate (pi: /spine-gate → /spine-integrate)

Full command reference: docs/QUICK-REFERENCE.md.

Commands at a glance

CLI

Command	Purpose
spine init	Create .spine/ config and agent stubs
spine doctor	Validate Node, git, pi, config
spine preflight	Required checks before batch start
spine plan all / pending	Preview dependency waves and lanes
spine batch start pending	Run unfinished tasks in dependency order
spine status --diagnose	Reconciled batch diagnosis + next action
spine batch pause / resume	Stop or continue scheduling
spine gate status / approve	Review evidence; approve integrate
spine integrate	Merge orch branch → main
spine dashboard	Local SSE dashboard (default port 8109)

pi slash commands

Command	Purpose
/spine-plan all	Preview waves and lanes
/spine pending	Start batch for pending tasks
/spine-status	Batch diagnosis + lane health
/spine-gate	Gate inspection and resolution
/spine-integrate	Merge orch branch after gate approval
/spine-dashboard	Start dashboard in background

How it works

preflight → plan waves → batch start (worktree lanes)
    → workers (PROMPT/STATUS, .DONE) → lane merge → orch branch
    → gate approve → integrate → main

Waves serialize dependency groups; lanes parallelize disjoint file scopes within a wave. See EXECUTION-FLOW-DIAGRAMS.md and EXECUTION-FLOW.md for lifecycle detail.

Best-of-N (dev script)

scripts/best-of-n.mjs runs the same prompt through multiple pi models in parallel worktrees — for comparing outputs, not production batches. Git checkout only; not shipped on npm. See docs/QUICK-REFERENCE.md (dev scripts) and scripts/best-of-n.mjs.

Migrating from Taskplane

1. Install pi-spine in the same or a new repo.
2. spine init then spine doctor
3. Migrate config from .pi/taskplane-config.json (spine migrate-from-taskplane).
4. Run /spine-plan all and compare to your last Taskplane plan.

Do not run Taskplane and pi-spine batches on the same repo concurrently. See bootstrap-checklist.md.

Project status

v1.1.0 on npm and pi.dev. API may still evolve in patch releases; see git tags and docs/release/.

CI runs on every push and PR: typecheck, tests, coverage, and CLI smoke checks — see .github/workflows/ci.yml and npm-publish.md.

Documentation

Document	Purpose
docs/PRD.md	Product requirements and implementation contract
docs/QUICK-REFERENCE.md	Operator command reference
docs/EXECUTION-FLOW.md	Batch lifecycle and scheduling
docs/adoption/why-pi-spine.md	Positioning vs Taskplane, Babysitter, pi-conductor (archived)
docs/adoption/operator-runbook.md	Daily operator procedures
docs/adoption/bootstrap-checklist.md	First-time setup

License

MIT (intended).