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 Recommended: pull the published image. Node install and sf init are the other path
YAML catalog Author dialect io / verify / on_verify_fail and wiring route / entry / type: loop / Clone Chain (upgrading older catalogs)
CLI reference sf init, sf run, sf run-stage, sf validate, sf eval, 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
Hosted runtime Public library contract for embedding one inline pipeline run
Envelopes Stage handoff contract (emit_stage_envelope, artifacts)
Verified Stage Execution After-phase verify, evidence, and on_verify_fail repair / manual recovery
Human-in-the-loop Gate kinds, operator replies, --skip-gates, exit code 2
Agents Project-owned agents (agents/*.agent.yaml): overview and where the pieces live
Agent definition Every field of an agent file, defaults and limits, reserved ids, revisions, validation issues
Agent runtime Turns, tool grants, ask-first approvals, guardrails, sub-agents, limits, restart behaviour
Agent observability Spans, capture modes, redaction, OTLP export, groundedness evals
Agent API REST routes, CLI and MCP tools for agents, webhooks and the public chat API
Set up your first agent Create, test and enable an agent
Agent channel guides Email (AgentMail), iMessage, Slack, Telegram, schedules, web chat
MCP servers Add MCP servers, secrets and OAuth from Settings or .mcp.json; use them from agents and stages
Glossary Agent, agent session, pipeline run, connection, Project MCP and other terms
Workshop Author Chat-draft a pipeline at #/workshop, save it into the catalog, and run it
Evals Check a stage or an agent against a dataset: eval files, datasets, graders (schema, field, reference, rubric, code, and for agents tool_calls, conversation_check, goal_reached), repeats and honest statistics, compare, sorting failures into buckets, cost limits, the engine, error codes, Evals for agents (scenarios, tool and approval policy, eval sessions), privacy, what is not built
Browser sessions Stage browser field, saved logins (profiles), login check and human login pattern, queueing, teardown, headed vs headless, live view and watch-the-agent for Hosts with no screen, container browser host (development), Host config keys, what is not built
Browser sessions internals For contributors: module map, lifecycle, file layout, env contract, invariants, seams, extension recipes, test and debug guide for browser sessions
Providers Pi model auth — pi_home vs sf_owned
Email accounts IMAP accounts for email triggers
Communication channels connecting AgentMail, Slack, Telegram, iMessage and WhatsApp, linking a connection to a stage, connections.yaml and secret handling, run-start checks, the Connections page API, and troubleshooting

Operating Stageflow

Doc What you'll learn
Data directory Durable root layout, keep vs disposable, image user, version support
Docker and self-hosting Local Compose try (.env.example, control token, providers), pull/run, Compose stage sandbox, browser image recipes (Dockerfile.browser, Dockerfile.browser-sandbox) and container browser host config, backup/restore, provenance, hardened egress (docs-only)
Operator console Navigation, command palette, keyboard shortcuts and routes
Console: Overview Control center: what needs you, what is running, system health, run trends
Console: Inbox Gates and agent approvals waiting on you, desktop notifications
Console: Pipeline runs Run list, Start a run, run detail (Timeline, Graph, List; Transcript, Events, Envelope, Artifacts)
Console: Pipelines, tasks and catalog Pipeline editor, Tasks, Catalog, Triggers, Workshop
Console: Evals Evals list, New eval wizard (stage or agent), Datasets and scenarios, Run dialog and live progress, run switcher, results, suggested failure sorting, case drawer and conversation transcript, Compare, Edit eval
Console: Agents Directory, create and edit, sessions, run inspector
Console: Connections Channels, email accounts, tool servers
Console: Settings Providers (connect, replace key, disconnect), Concurrency, MCP server, Project MCP, Notifications
Environment variables Every STAGEFLOW_* variable the Host reads
Migrating stage environments Move stages to declared secrets and the curated stage environment
Triggers readiness Checklist: which trigger kinds and console options the Host runs today vs manual-only
MCP Streamable HTTP tools when sf ui or sf mcp is running, including standalone run_stage and the eval tools
A2A Publish pipelines for other agents to invoke over JSON-RPC, plus the wildcard-access run_stage operation
CI / headless --json, exit codes, sf eval run in CI, GitHub Actions, PR diagram dogfood

Archify on PR — pull-request diagram automation dogfooding Stageflow in GitHub Actions: unused-path 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 join skip vs fail (two named parents into one child, inspect keyed envelopes) and a runnable tour of deterministic route if (operators, composition, skip, join fire and miss), see YAML catalog — Generic fan-in and examples/route-if-tour/. For a short spine of every verify check type (artifact, command, checklist, payload_schema, gate, checkout_changes), see examples/verify-tour/. For emit soft-reject, automatic repair, manual recover, and ordinary Retry, see examples/retry-tour/.

For source-owned feedback loops (continue / send_back), see examples/feedback-loop/ and YAML catalog — Feedback loops. For MCP-host HITL (answer_gate) plus exhausted-loop decide_feedback_loop, see examples/mcp-hitl-tour/. For stage agents consuming project MCP servers, see YAML catalog — Stage MCP, examples/stage-mcp/, examples/playwright-mcp/, and examples/context7-mcp/.

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). Clone Chain shapes live under the fixtures above; there is no examples/ Clone Chain walkthrough.

See also