Quick start

This guide walks through a minimal Stageflow project: one pipeline, one stage, one task. The example is domain-neutral — you define what each stage does via system_prompt and YAML; Stageflow does not ship built-in stage types.

Prerequisites

npm i -g stageflow

1. Scaffold the catalog

In an empty project directory (preferably a git repo), run:

sf init

This creates:

File Purpose
stageflow.yaml Manifest — declares which directories to browse and validate
pipelines/hello.pipeline.yaml Single inline stage pipeline
tasks/hello.task.yaml Task file

Manual alternative — same shape without sf init:

stageflow.yaml

version: 1
catalog:
  pipelines:
    - pipelines
  tasks:
    - tasks
  patterns:
    pipeline: "*.pipeline.yaml"
    task: "*.task.yaml"

pipelines/hello.pipeline.yaml

id: hello
stages:
  - id: hello
    system_prompt: Say hello and emit a success envelope.
    model: anthropic/claude-sonnet-4-5

tasks/hello.task.yaml

id: hello
goal: Run the hello pipeline scaffold.

Stages are object entries with inline bodies or uses: paths — not bare string ids. See YAML catalog for the full schema.

2. Validate the catalog

sf validate --strict

With no flags, sf validate checks all pipelines and tasks declared in stageflow.yaml (manifest-all), plus the stages those pipelines reference. --strict promotes manifest warnings (missing manifest, empty catalog) to errors.

It does not prove provider auth or checkout paths.

3. Connect a provider

Either open the operator console:

sf ui

Go to Settings → Providers and connect a model, or use the CLI:

sf providers list
sf providers login anthropic --type api_key --api-key-env ANTHROPIC_API_KEY

See Providers for pi_home vs sf_owned credential storage.

4. Run the pipeline

sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml

--pipeline and --task require filesystem paths — there is no bare-id fallback.

Each stage runs in a fresh Pi session. When the stage agent finishes, it must call emit_stage_envelope once (see Envelopes). On success the pipeline completes and run state is stored under <git-root>/.stageflow/ regardless of which subdirectory you run from.

5. Operate via the console

With sf ui running (default http://127.0.0.1:3847):

If a stage calls ask_operator, the run pauses until you reply in the console. See Human-in-the-loop.

For MCP without the console, use sf mcp — see MCP.

Multi-stage pipelines

Add more stage entries to the pipeline. Use uses: for external stage files or inline system_prompt / model. Order with explicit needs:

id: linear
stages:
  - id: clarify
    uses: ../stages/clarify.yaml
  - id: design-doc
    uses: ../stages/design-doc.yaml
    needs: clarify

Canonical example: tests/fixtures/pipelines/linear-explicit.pipeline.yaml.

Parallel fan-out uses the same needs field — see tests/fixtures/pipelines/parallel-after-clarify.pipeline.yaml and YAML catalog. For conditional routing (the deciding stage chooses one or more branches at runtime), see Fork pipelines in the YAML catalog. Clonable fan-out clones one successor N times at completion — see Clonable successors.

Headless / CI

sf validate --strict --json
sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml --json

Exit codes: 0 success, 1 failure, 2 waiting on HITL. Details in CI / headless.

See also