Stageflow documentation

Stageflow is an open-source runtime for configurable multi-stage agent workflows. You author pipeline-owned YAML — *.pipeline.yaml, separate *.task.yaml files, optional repo-root stageflow.yaml manifest — and Stageflow schedules fresh agent sessions with explicit envelopes and artifacts between stages. Pi is the current agent execution backend.

Stages are author-defined and domain-agnostic. Release automation, research flows, content review, SDLC, and ops runbooks are all valid patterns; nothing in Stageflow hard-codes a domain.

Getting started

Doc What you'll learn
Quick start Install, sf init, path-based run
YAML catalog Pipeline, stage, and task file schema
CLI reference sf init, sf run, sf validate, sf envelope, sf ui, sf mcp, sf providers
Harness skills suite npx skills add tejasghutukade/stageflow — router + five job skills for Cursor, Claude Code, Codex, Pi, and OpenCode

Core concepts

Doc What you'll learn
Architecture Runtime boundaries, execution flow, persistence, recovery, and design tradeoffs
Envelopes Stage handoff contract (emit_stage_envelope, artifacts)
Verified Stage Execution Completion checks, evidence, and repair policy
Human-in-the-loop Gate kinds, operator replies, --skip-gates, exit code 2
Providers Pi model auth — pi_home vs sf_owned

Operating Stageflow

Doc What you'll learn
Operator console Spatial stage map, gated workspace, navigation, settings
MCP Streamable HTTP tools when sf ui or sf mcp is running
CI / headless --json, exit codes, GitHub Actions, PR diagram dogfood

Archify on PR — pull-request diagram automation dogfooding Stageflow in GitHub Actions: conditional fork skip, pipeline skill binding, sf envelope get --format handoff, and deterministic Archify deliver outside the agent. See CI: PR diagrams (Archify) and examples/archify-on-pr/README.md.

For clonable fan-out (clone one successor N times at completion), see examples/clonable-fanout/ and YAML catalog — Clonable successors. For a diamond join (two named parents into one child, inspect keyed envelopes), see examples/generic-fan-in/ and YAML catalog — Generic fan-in.

For source-owned feedback loops (continue / send_back), see examples/feedback-loop/ and YAML catalog — Feedback loops.

Canonical YAML examples

Test fixtures under tests/fixtures/ are the source of truth for valid catalog shapes:

Runnable walkthroughs live in examples/ (see examples/README.md).

See also