stageflow

Stageflow is an open-source runtime for configurable multi-stage agent workflows. Pipelines are authored as project-owned YAML (`*.pipeline.yaml`, `*.task.yaml`, optional `stageflow.yaml` manifest), and each stage runs in a fresh agent session, passing context forward through typed envelopes and artifacts. Pi is the current agent execution backend. The package installs the `sf` and `stageflow` binaries and requires Node.js 20 or newer. The project positions stages, not agents, as the unit of composition. A scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out and join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind an `AgentPort` abstraction, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI. Run state is persisted in SQLite under `<git-root>/.stageflow/`, with per-run workspaces under `.stageflow/runs/`; global config and credentials live under `~/.stageflow/`. Notable capabilities described in the README include typed envelope handoffs via `write_stage_artifact` and `emit_stage_envelope`, verified stage execution with after-phase `verify` checks and `on_verify_fail` repair or manual recovery, and human-in-the-loop gates where CI exits with code 2 while a run is waiting. A local operator console at `http://127.0.0.1:3847` supports triage of runs, provider connection, gate replies, and transcript inspection. An MCP endpoint is exposed over Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running, with HITL-aware tools such as `wait_run`, `answer_gate`, `list_waiting`, and `decide_feedback_loop`. Headless and CI usage is supported through `sf validate --strict --json` and `sf run --json`, with documented exit codes: 0 for succeeded, 1 for failed or busy, and 2 for waiting. Provider authentication can be configured through the console or `sf providers` commands, with credentials stored either in Pi's shared auth file (`pi_home`) or Stageflow's own store (`sf_owned`). The README explicitly notes that Stageflow is not an SDLC tool; software delivery is a common example pattern, but stages are user-authored and domain-agnostic. The repository includes a comparison with Microsoft Conductor, framing Stageflow as stage-bound Pi runs with reviewable envelopes and an operator console for workflows the user authors, versus Conductor's deterministic YAML routing across many agents. Example pipelines cover hello-world, plan-review with an operator gate, conditional fork routing, stage MCP, Playwright MCP, Context7 MCP, GitHub release drafting, an MCP-first HITL tour, and CI validation. Documentation covers architecture, quickstart, YAML schema, CLI reference, envelopes, HITL, CI, MCP, providers, and the operator console. The project is MIT licensed.