Pi Workflow OS — Productivity skill for Claude Code

pi-workflow-os

XState-backed workflow orchestration for [Pi](https://github.com/earendil-works/pi).

This is our own take on dynamic multi-agent workflows: small deterministic JavaScript workflows fan out to isolated Pi subagents, while an explicit XState runtime tracks lifecycle, events, cancellation, progress projection, and future persistence seams.

Credit / inspiration

Inspired by Michael Livshits' [`pi-dynamic-workflows`](https://github.com/Michaelliv/pi-dynamic-workflows) and Anthropic's dynamic workflow pattern for Claude Code.

This package intentionally keeps the best user-facing bit from that prototype, the simple JavaScript workflow DSL, but changes the runtime spine:

• XState owns workflow lifecycle.
• Workflow events are the durable source of truth.
• Snapshots are projections from events.
• Agent failures are typed internally instead of disappearing into anonymous state.
• Model/isolation options are named as hints until enforcement exists.

Install

pi install npm:pi-workflow-os

Then reload Pi:

/reload

When to use Workflow OS

Workflow OS is most useful when a task needs a custom harness instead of one long agent context:

• many independent items that can fan out and synthesize
• adversarial verification, claim checking, or rubric review
• open-ended loops with explicit stop conditions
• ranking/tournament/exploration work
• untrusted triage where readers must be quarantined from privileged actors
• code migrations/refactors that should use isolated worktrees

Use `workflow_suggest` when unsure. It returns whether `workflow_os` is warranted plus recommended patterns, agent profiles, budget, and concurrency.

{
  "task": "Rank 80 resumes and double-check the top ten",
  "itemCount": 80,
  "requiresVerification": true
}

See `docs/pattern-catalog.md` and `examples/workflows/` for starter templates.

Workflow shape

export const meta = {
  name: 'inspect_project',
  description: 'Inspect a r