stageflow

KO | EN

gitlite — search

#redis #list #ai-agent #anthropic #docker #tensorflow #php #tailwindcss #android #claude

(★ 9)

Configurable, typed multi-stage agent workflows for Pi — local console, human gates, MCP, and CI.

File Explorer

ZIP Download

- - archify-pr-diagrams.yml
  - ci.yml
  - docs.yml
  - publish.yml
  - release.yml
  - repair-github-release-notes.yml
- - stageflow-architecture.svg
  - stageflow-icon.svg
  - stageflow-og.svg
- - stage-run-log-panel.md
- _config.yml
- architecture.md
- ci.md
- cli-reference.md
- envelopes.md
- hitl.md
- mcp.md
- operator-console.md
- providers.md
- quickstart.md
- README.md
- skills-suite.md
- verified-stage-execution.md
- yaml-catalog.md
- - archify-on-pr.pipeline.yaml
  - archify-on-pr.task.yaml
  - author-diagrams.yaml
  - detect-changes.yaml
  - README.md
- - check.yaml
  - ci-demo.pipeline.yaml
  - README.md
  - validate.sh
- - branch-a.yaml
  - branch-b.yaml
  - decide.yaml
  - fork-demo.pipeline.yaml
  - fork-demo.task.yaml
  - README.md
- - context7-mcp.pipeline.yaml
  - context7-mcp.task.yaml
  - fetch-docs.yaml
  - README.md
  - resolve-library.yaml
  - write-brief.yaml
- - .gitignore
  - address-feedback.yaml
  - align.yaml
  - decompose.yaml
  - default-model-hierarchy.task.yaml
  - feature-loop.pipeline.yaml
  - feature-loop.task.yaml
  - implement.yaml
  - plan.yaml
  - publish.yaml
  - README.md
  - review.yaml
  - verify.yaml
- - continue-only.task.yaml
  - exhaust-require-continue.task.yaml
  - exhaust-wait-human.task.yaml
  - feedback-loop-wait-human.pipeline.yaml
  - feedback-loop.pipeline.yaml
  - feedback-loop.task.yaml
  - implement.yaml
  - plan.yaml
  - README.md
  - review.yaml
  - send-back-once.task.yaml
  - submit.yaml
  - VERIFY.md
- - .gitignore
  - clarify.yaml
  - generic-fan-in-accepted.pipeline.yaml
  - generic-fan-in-accepted.task.yaml
  - generic-fan-in.pipeline.yaml
  - generic-fan-in.task.yaml
  - README.md
  - research.yaml
  - synthesize.yaml
  - validation.yaml
- - .gitignore
  - draft-release-notes.yaml
  - github-release.pipeline.yaml
  - github-release.task.yaml
  - publish-github-release.yaml
  - README.md
- - .gitignore
  - hello.pipeline.yaml
  - my-task.task.yaml
  - README.md
  - research.yaml
- - oss-address-review-feedback.yaml
  - oss-approve-contribution.yaml
  - oss-approve-plan.yaml
  - oss-explain-fix.yaml
  - oss-explain-issue.yaml
  - oss-implement-source-fix.yaml
  - oss-investigate-area.yaml
  - oss-issue-contribution.pipeline.yaml
  - oss-issue-intake.yaml
  - oss-plan-investigation.yaml
  - oss-plan-review.yaml
  - oss-reproduce-issue.yaml
  - oss-review-change.yaml
  - oss-verify-fix.yaml
  - oss-write-regression-test.yaml
  - pi-7629.task.yaml
  - pi-8919.task.yaml
  - pydantic-ai-7971.task.yaml
  - README.md
- - implement-fix.yaml
  - oss-quick-fix.pipeline.yaml
  - ship-fix.yaml
  - understand-issue.yaml
  - verify-fix.yaml
- - .gitignore
  - plan-review-followup.yaml
  - plan-review.pipeline.yaml
  - plan-review.task.yaml
  - plan-review.yaml
  - README.md
- - .gitignore
  - playwright-mcp.pipeline.yaml
  - playwright-mcp.task.yaml
  - README.md
  - screenshot.yaml
- - README.md
  - retry-tour.pipeline.yaml
  - retry-tour.task.yaml
- - README.md
  - route-if-tour.pipeline.yaml
  - route-if-tour.task.yaml
- - 01-core-routing.pipeline.yaml
  - 02-on-gating.pipeline.yaml
  - 03-two-entry-points.pipeline.yaml
  - 04-entry-false-equivalent-to-omitted.pipeline.yaml
  - 05-fork-choice.pipeline.yaml
  - 06-fan-out-fan-in.pipeline.yaml
  - 07-loop-human-decision.pipeline.yaml
  - 08-skip-fallback-and-multi-on-gate.pipeline.yaml
  - 09-multi-loop-targets.pipeline.yaml
  - 10-uses-dialect-fork.pipeline.yaml
  - 11-sequential-io-handoff.pipeline.yaml
  - 12-complex-io-schemas.pipeline.yaml
  - 13-ref-io-handoff.pipeline.yaml
  - 14-if-eq-gating.pipeline.yaml
  - 15-if-all-gated.pipeline.yaml
  - 16-if-composition.pipeline.yaml
  - 17-if-join.pipeline.yaml
  - README.md
  - smoke-test.task.yaml
- - feat-address-feedback.yaml
  - feat-implement.yaml
  - feat-plan.yaml
  - feat-review.yaml
  - feat-ship.yaml
  - README.md
  - ship-feature.pipeline.yaml
  - ship-feature.task.yaml
- - .gitignore
  - echo-mcp.mjs
  - README.md
  - stage-mcp-dead.pipeline.yaml
  - stage-mcp-dead.task.yaml
  - stage-mcp-missing-var.pipeline.yaml
  - stage-mcp-missing-var.task.yaml
  - stage-mcp.pipeline.yaml
  - stage-mcp.task.yaml
  - use-echo.yaml
- - README.md
  - verify-tour.pipeline.yaml
  - verify-tour.task.yaml
- README.md
- copy-ui-dist.ts
- deliver-diagrams.sh
- install-archify-skill.sh
- list-login-capable-providers.ts
- migrate-attempt-layout.ts
- prepare-ci-context.sh
- release-range.mjs
- validate-detect-envelope.mjs
- validate-examples.ts
- verify-pack.ts
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- install-suite.sh
- - activity.ts
  - activityObserver.ts
  - agentBackend.ts
  - claudeActivity.ts
  - claudeAdapter.ts
  - claudeSession.ts
  - claudeTools.ts
  - cursorProvider.ts
  - fakeAgent.ts
  - oauthSessionManager.ts
  - piAdapter.ts
  - piIsolatedMcp.ts
  - piIsolatedMcpProbe.ts
  - port.ts
  - providerAuth.ts
  - providerSupport.ts
  - resolveAgentPort.ts
- - displayCatalogPath.ts
- - artifactCommand.ts
  - ciIdentity.ts
  - envelopeCommand.ts
  - exportRunCommand.ts
  - handoffFormat.ts
  - initCommand.ts
  - initTemplates.ts
  - migrateYamlCommand.ts
  - operatorCatalog.ts
  - providersCommand.ts
  - runCommand.ts
  - runOutput.ts
  - runsCommand.ts
  - skillsCommand.ts
  - terminalAuthInteraction.ts
  - terminalSecret.ts
  - validateCommand.ts
  - validateOutput.ts
- - browseCatalog.ts
  - cloneChain.ts
  - createPipeline.ts
  - createStage.ts
  - legacyYaml.ts
  - listConfig.ts
  - listExtensions.ts
  - listModelsFromManifest.ts
  - listSkills.ts
  - loadOutcome.ts
  - loadPipeline.ts
  - loadStage.ts
  - loadStageflowManifest.ts
  - loadTask.ts
  - materializeStageModels.ts
  - mergePipelineIncludes.ts
  - migrateYaml.ts
  - modelField.ts
  - normalizePipelineStageEntry.ts
  - parseCompletionContract.ts
  - parsePreEmitChecks.ts
  - pipelineNeeds.ts
  - pipelineRoute.ts
  - pipelineStageKeys.ts
  - printTargetYaml.ts
  - readYamlObject.ts
  - resolveCatalogContext.ts
  - resolveForkEmitContext.ts
  - resolveModel.ts
  - resolvePipelineDag.ts
  - resolveStageMcpServers.ts
  - routeIf.ts
  - scanCatalogPaths.ts
  - validateCatalog.ts
  - validateCompletionContract.ts
  - yamlDialect.ts
- - check.ts
  - feedbackLoop.ts
  - forkChoice.ts
  - payloadSchema.ts
  - preEmitChecks.ts
- - qaTrail.ts
- - catalogTools.ts
  - controlTools.ts
  - deps.ts
  - projectRun.ts
  - readArtifact.ts
  - resources.ts
  - server.ts
  - toolResults.ts
  - tools.ts
  - waitingGates.ts
  - waitRun.ts
- - findProjectRoot.ts
  - globalHome.ts
  - resolveProjectContext.ts
  - resolveStageflowContext.ts
- - projectRun.ts
- - feedbackLoopContext.ts
  - priorEnvelope.ts
- - createStore.ts
  - normalizeCatalogPath.ts
  - paths.ts
  - pipelineDagSnapshot.ts
  - port.ts
  - runProjection.ts
  - stageExecution.ts
  - stageInstanceId.ts
  - stageSnapshot.ts
  - syntheticStageSnapshot.ts
  - trackProjection.ts
  - verificationHistory.ts
  - workspaceLayout.ts
- - answerResume.ts
  - cloneSchedule.ts
  - completionCheckoutBaseline.ts
  - completionCheckRunner.ts
  - credentialBinding.ts
  - dagTraversal.ts
  - envelopeRouting.ts
  - feedbackLoopCoordinator.ts
  - feedbackLoopDecision.ts
  - feedbackLoopRoute.ts
  - feedbackLoopSchedule.ts
  - forkGeneration.ts
  - gitCheckoutCapability.ts
  - joinReadiness.ts
  - manualRecoveryState.ts
  - pipelineRunner.ts
  - pipelineScheduler.ts
  - pipelineValidationError.ts
  - reloadRunCatalog.ts
  - replayLifecycle.ts
  - resumeReconstruct.ts
  - routeIfEval.ts
  - runChangeBus.ts
  - runManager.ts
  - runRetryCoordinator.ts
  - settingsFile.ts
  - stageAttemptBootstrap.ts
  - stageAttemptContext.ts
  - stageConcurrency.ts
  - stageHitl.ts
  - stageProcessLauncher.ts
  - stageRecovery.ts
  - stageRoots.ts
  - stageRunner.ts
  - stageWorker.ts
  - stageWorkerProtocol.ts
  - taskInput.ts
  - verifiedStageExecution.ts
- - bootstrap.ts
  - createHttpHost.ts
  - http.ts
  - mcpHost.ts
  - operatorResults.ts
  - projectMcpRoutes.ts
  - providerRoutes.ts
- - askOperator.ts
  - emitStageEnvelope.ts
  - writeStageArtifact.ts
- - completion.ts
  - envelope.ts
  - forkChoice.ts
  - pipeline.ts
  - preEmitCheck.ts
  - stage.ts
  - stageflowManifest.ts
  - task.ts
  - usage.ts
- cli.ts
- index.ts
- package-meta.ts
- - mockStageWorker.mjs
- - fixturePaths.ts
  - plantDiskEraRun.ts
  - projectContext.ts
  - seedDiamondRun.ts
- agent.activity.test.ts
- agent.askOperator.wiring.test.ts
- agent.claudeActivity.test.ts
- agent.claudeAdapter.test.ts
- agent.claudeSession.test.ts
- agent.claudeTools.schemaParity.test.ts
- agent.cursorProvider.test.ts
- agent.piAdapter.hitlWait.test.ts
- agent.piAdapter.mcp.isolation.test.ts
- agent.piAdapter.prompt.test.ts
- agent.piAdapter.session.test.ts
- agent.piAdapter.skill.test.ts
- agent.piAdapter.test.ts
- agent.piIsolatedMcp.test.ts
- agent.port.contract.test.ts
- agent.providerAuth.oauthSession.test.ts
- agent.providerAuth.test.ts
- agent.resolveAgentPort.test.ts
- agent.stageHandle.test.ts
- choiceEmission.test.ts
- cli.artifact.test.ts
- cli.ciIdentity.test.ts
- cli.envelope.test.ts
- cli.exportRun.test.ts
- cli.init.test.ts
- cli.migrateYaml.test.ts
- cli.operatorCatalog.test.ts
- cli.providers.oauth.test.ts
- cli.providers.test.ts
- cli.run.json.test.ts
- cli.run.skipGates.test.ts
- cli.run.validationGate.test.ts
- cli.run.waiting.test.ts
- cli.runs.answer.test.ts
- cli.runs.feedbackDecide.test.ts
- cli.runs.mutate.test.ts
- cli.runs.test.ts
- cli.skills.test.ts
- cli.usage.test.ts
- cli.validate.test.ts
- cli.version.test.ts
- completion.contract.test.ts
- config.cloneChain.cap.test.ts
- config.cloneChain.detect.test.ts
- config.cloneChain.illegal.test.ts
- config.cloneChain.load.test.ts
- config.cloneChain.loop.test.ts
- config.createPipeline.test.ts
- config.createStage.test.ts
- config.feedbackLoop.test.ts
- config.forkContext.test.ts
- config.legacyCloneRejected.test.ts
- config.legacyFieldsRejected.test.ts
- config.legacyYaml.test.ts
- config.listConfig.test.ts
- config.listExtensions.test.ts
- config.listModelsFromManifest.test.ts
- config.listSkills.test.ts
- config.load.test.ts
- config.loadPipelineModel.test.ts
- config.loadPipelineOwned.test.ts
- config.loadStageflowManifest.test.ts
- config.loadStageInline.test.ts
- config.loadStageMcp.test.ts
- config.loadTask.test.ts
- config.loadValidation.test.ts
- config.mergePipelineIncludes.test.ts
- config.normalizePipelineStageEntry.test.ts
- config.pipelineDag.test.ts
- config.pipelineRoute.test.ts
- config.pipelineRouteLoop.test.ts
- config.pipelineRouteSelect.test.ts
- config.resolveCatalogContext.test.ts
- config.resolveModel.test.ts
- config.resolvePipelinePath.test.ts
- config.resolveStageMcpServers.test.ts
- config.routeIf.test.ts
- config.scanCatalogPaths.test.ts
- config.targetDialect.fixtures.test.ts
- config.validateCatalog.test.ts
- config.yamlDialect.test.ts
- displayCatalogPath.test.ts
- docs.fixtures.test.ts
- envelope.check.test.ts
- envelope.feedbackLoop.test.ts
- envelope.forkChoice.test.ts
- envelope.payloadSchema.test.ts
- hitl.qaTrail.append.test.ts
- hitl.qaTrail.derive.test.ts
- hitl.qaTrail.types.test.ts
- installSkillsSuite.test.ts
- mcp.readArtifact.test.ts
- mcp.server.sessionInit.test.ts
- mcp.tier3.test.ts
- mcp.tools.test.ts
- mcp.waitingGates.test.ts
- mcp.waitRun.test.ts
- package.identity.test.ts
- packaging.build.test.ts
- packaging.manifest.test.ts
- packaging.verifyPack.test.ts
- pipelineScheduler.forkSkip.test.ts
- project.findProjectRoot.test.ts
- project.resolveProjectContext.test.ts
- project.resolveStageflowContext.test.ts
- projection.feedbackLoop.test.ts
- providerAuth.discovery.test.ts
- release-range.test.ts
- runChangeBus.test.ts
- runManager.inline-task.test.ts
- runstore.adapter.contract.test.ts
- runstore.catalog.test.ts
- runstore.dagSnapshot.test.ts
- runstore.feedbackLoop.test.ts
- runstore.layout.test.ts
- runstore.locators.test.ts
- runstore.normalizeCatalogPath.test.ts
- runstore.projection.test.ts
- runstore.sqlite.test.ts
- runstore.stageExecution.derivePatch.test.ts
- runstore.stageExecutions.test.ts
- runstore.stageInstanceId.test.ts
- runstore.storeRoot.test.ts
- runstore.trackProjection.test.ts
- runstore.verificationHistory.test.ts
- runstore.workspaceLayout.test.ts
- runtime.automaticRepair.test.ts
- runtime.capacity.test.ts
- runtime.cloneChain.cap.test.ts
- runtime.cloneChain.loop.test.ts
- runtime.cloneChain.multiple.test.ts
- runtime.cloneChain.parallel.test.ts
- runtime.cloneChain.run.test.ts
- runtime.cloneChain.sequential.test.ts
- runtime.cloneSchedule.mint.test.ts
- runtime.completionCheckoutBaseline.test.ts
- runtime.completionCheckRunner.test.ts
- runtime.credentialBinding.test.ts
- runtime.envelopeRouting.test.ts
- runtime.feedbackLoop.retry.test.ts
- runtime.feedbackLoop.test.ts
- runtime.feedbackLoop.waitForHuman.test.ts
- runtime.forkRouting.test.ts
- runtime.genericFanIn.retry.test.ts
- runtime.genericFanIn.schedule.test.ts
- runtime.gitCheckoutCapability.test.ts
- runtime.hitl.hold.test.ts
- runtime.hitl.multiWait.test.ts
- runtime.hitl.planReview.test.ts
- runtime.hitl.processMode.test.ts
- runtime.hitl.qa.test.ts
- runtime.joinReadiness.test.ts
- runtime.loadPipelineForRun.test.ts
- runtime.manualRecovery.test.ts
- runtime.parallel-runs.test.ts
- runtime.pipeline.parallel.test.ts
- runtime.pipeline.test.ts
- runtime.pipeline.validationGate.test.ts
- runtime.pipelineOwned.smoke.test.ts
- runtime.rerun.test.ts
- runtime.routeIfEval.test.ts
- runtime.runLocators.test.ts
- runtime.settingsFile.test.ts
- runtime.skipGates.test.ts
- runtime.stageAttemptBootstrap.test.ts
- runtime.stageProcess.test.ts
- runtime.stageRecovery.test.ts
- runtime.stageRetry.hydrate.test.ts
- runtime.stageRetry.test.ts
- runtime.stageRoots.test.ts
- runtime.stageWorker.test.ts
- runtime.storeResolution.test.ts
- runtime.verifiedStageExecution.test.ts
- server.createHttpHost.test.ts
- server.http.test.ts
- server.operatorResults.test.ts
- server.uiDist.test.ts
- skills.authorDialect.test.ts
- skills.authorExamples.test.ts
- skills.sessionCapture.exampleValidates.test.ts
- skills.sessionCapture.locateTranscript.test.ts
- skills.sessionCapture.manifest.test.ts
- skills.sessionCapture.providerGate.test.ts
- skills.sessionCapture.resolveCatalogId.test.ts
- skills.stageflowRun.manifest.test.ts
- skillsSuitePackaging.test.ts
- surface.catalogParity.test.ts
- tools.askOperator.fixtures.test.ts
- tools.askOperator.schema.test.ts
- tools.askOperator.test.ts
- tools.emitStageEnvelope.preEmitChecks.test.ts
- tools.writeStageArtifact.test.ts
- - stageflow-icon.svg
- - api.projectMcp.test.ts
  - api.providers.test.ts
  - api.ts
  - App.tsx
  - brandCopy.test.ts
  - catalogJoin.test.ts
  - catalogJoin.ts
  - console.css
  - main.tsx
  - mcpConnect.test.ts
  - mcpConnect.ts
  - ReplyZone.tsx
  - routes.test.ts
  - routes.ts
  - StatusLabel.tsx
  - themePreference.test.ts
  - themePreference.ts
  - toast.ts
  - useWaitingNotifications.test.ts
  - useWaitingNotifications.ts
  - vite-env.d.ts
- AGENTS.md
- index.html
- package.json
- tsconfig.json
- vite.config.ts
- vitest.config.ts
.gitignore
.mcp.json
AGENTS.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
install.sh
LICENSE
package-lock.json
package.json
README.md
SECURITY.md
stageflow.yaml
SUPPORT.md
tsconfig.json
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Open-source runtime for **configurable multi-stage agent workflows** with typed handoffs, DAG execution, human gates, MCP, CI, and a local operator console.

[![npm version](https://img.shields.io/npm/v/stageflow)](https://www.npmjs.com/package/stageflow)
[![npm downloads](https://img.shields.io/npm/dm/stageflow)](https://www.npmjs.com/package/stageflow)
![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)
[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/tejasghutukade/stageflow/main/LICENSE)
[![GitHub issues](https://img.shields.io/github/issues/tejasghutukade/stageflow)](https://github.com/tejasghutukade/stageflow/issues)
[![CI](https://img.shields.io/github/actions/workflow/status/tejasghutukade/stageflow/ci.yml?branch=main)](https://github.com/tejasghutukade/stageflow/actions/workflows/ci.yml)

Author pipeline-owned YAML in your project. Stageflow schedules each stage in a fresh agent session, moves context through explicit envelopes and artifacts, and persists run state under `.stageflow/`. [Pi](https://github.com/badlogic/pi-mono) is the current agent execution backend. Bins: **`sf`** and **`stageflow`**.

## Why Stageflow?

Multi-step agent work breaks down when every handoff is ad hoc — a shell script here, a chat transcript there, no shared contract between steps. You end up re-explaining context, losing artifacts, and unable to run the same flow locally and in CI.

Stageflow treats **stages as the unit of composition**. You author pipeline-owned YAML — `*.pipeline.yaml`, `*.task.yaml`, optional `stageflow.yaml` manifest — and define whatever workflow fits your domain: release automation, research pipelines, content review, SDLC, ops runbooks, or something entirely custom. Each stage runs in a **fresh Pi session**, emits a typed **envelope** for the next stage, and can pause on **human-in-the-loop (HITL)** gates when you need an operator in the loop.

The same pipeline runs three ways without rewriting anything:

- **Locally** — `sf ui` for triage, provider setup, and gate replies
- **Headless / CI** — `sf validate` and `sf run --json` with predictable exit codes
- **Via MCP** — Streamable HTTP tools when `sf ui` or `sf mcp` is running

**Stageflow is not an SDLC tool.** Software delivery is a popular pattern in fixtures and dogfood flows, but stages are user-authored and domain-agnostic. If you can express a multi-step workflow in YAML, Stageflow can run it on Pi.

## Features

- **Pipeline-owned YAML** — `*.pipeline.yaml` with inline stages or `uses:` refs; separate `*.task.yaml` files; optional repo-root `stageflow.yaml` manifest
- **Path-based CLI** — `--pipeline` and `--task` take filesystem paths (no bare-id lookup)
- **Pi-native** — runs on `@earendil-works/pi-coding-agent`; reuse an existing Pi login (`pi_home`) or store credentials in `~/.stageflow/agent/auth.json` (`sf_owned`)
- **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
- **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
- **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
- **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
- **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
- **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
- **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
- **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`

## Architecture at a glance

![Stageflow architecture: pipeline definitions and operator interfaces drive the orchestration runtime, which coordinates agent execution and persisted state](https://raw.githubusercontent.com/tejasghutukade/stageflow/main/docs/img/stageflow-architecture.svg)

The scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out/join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind `AgentPort`; Pi supplies the current coding-agent session, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI.

See [Architecture](docs/architecture.md) for component boundaries, execution flow, persistence, recovery behavior, and the tradeoffs behind fresh sessions and explicit handoffs.

## Installation

Requires **Node.js ≥ 20**.

**Quick install (macOS / Linux):**

```bash
curl -fsSL https://raw.githubusercontent.com/tejasghutukade/stageflow/main/install.sh | bash
```

**npm:**

```bash
npm i -g stageflow
# or
npx stageflow
# or, from a packed tarball
npm i -g ./stageflow-*.tgz
```

`better-sqlite3` ships prebuilds for common platforms. `--ignore-scripts` is fine when a prebuild exists. Benign `node-gyp` warnings during install can be ignored if `require("better-sqlite3")` works.

**Harness skills** (Cursor, Claude Code, Codex, Pi, OpenCode) — from a consumer project:

```bash
npx skills add tejasghutukade/stageflow
```

Then ask the agent to set up Stageflow. Details: [docs/skills-suite.md](docs/skills-suite.md).

## Quick start

In a project directory (preferably a git repo):

```bash
sf init
```

This scaffolds `stageflow.yaml`, `pipelines/hello.pipeline.yaml` (inline stage), and `tasks/hello.task.yaml`.

Run (after connecting a provider — see below):

```bash
sf ui                          # operator console at http://127.0.0.1:3847
sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
```

Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)

## Connect a model provider

Each stage sets a **`model`** id in YAML (e.g. `anthropic/claude-sonnet-4-5`). The matching provider must be authenticated before runs succeed — `sf validate` does not check auth.

**Operator console** (easiest for local setup):

```bash
sf ui
```

Open **Settings → Providers** (or **Connect** from the rail when nothing is configured) and sign in with API key or OAuth.

**CLI** (works headless and in CI):

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

Use `sf providers list` to see provider ids and supported auth types (`api_key`, `oauth`).

**Credential storage:** reuse Pi's shared auth file (`pi_home`) or keep credentials in Stageflow's global store (`sf_owned`):

```bash
sf providers detect
sf providers source set pi_home    # or sf_owned
```

Pi is Stageflow's current agent execution backend. Stageflow owns the workflow layer around it, and you do not need Pi CLI `/login` as a prerequisite when providers are configured through the console or `sf providers`.

Full reference: [docs/providers.md](docs/providers.md)

## Operator console

Start the console with `sf ui` (default `http://127.0.0.1:3847`).

- **Runs** — active and recent pipeline runs, capacity, and status at a glance
- **Run detail** — spatial stage map; select a stage for the gated workspace (logs, files, envelopes, HITL). Created runs show **not started** with a **Start run** action until history exists
- **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
- **Pipelines** — browse manifest-declared pipeline definitions
- **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)

Brand assets live under `docs/img/` (`stageflow-og.svg`, `stageflow-icon.svg`).

## Headless / CI

The guest actor is the CLI (`sf` / `stageflow`). `sf ui` and MCP are not required in the job.

```bash
sf validate --strict --json
```

Validate exits `0` or `1` only (no waiting / `2`). With no flags, `sf validate` checks pipelines and tasks in the manifest (plus stages). `--pipeline` validates that pipeline and its stages only; `--task` validates that task file. It never proves provider auth or checkout paths.

```bash
sf providers login <providerId> --api-key-env <VAR>
```

If the provider also supports OAuth, pass `--type api_key`.

```bash
sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml --json
```

The process exits `0` when the Run succeeded, `1` when it failed (including a busy start), and `2` when waiting. `sf run --json` prints one stdout document. `ok` is true only for `succeeded`. Busy has no `runId`.

| outcome | ok | runId | exit |
|---|---|---|---|
| `succeeded` | true | present | `0` |
| `failed` | false | present after start; omit when start never created a run | `1` |
| `waiting` | false | present | `2` |
| `busy` | false | omit | `1` |

On a mixed Pipeline, default wait parks the Run (exit `2`). `--skip-gates` fails the Stage (exit `1`). A Pipeline with no HITL does not need the flag.

Post-run extraction (dogfooded in [Archify PR diagrams](examples/archify-on-pr/)):

```bash
sf run ... --json --include stages > sf-run.json
sf envelope get --from sf-run.json --stage author-diagrams --format handoff --json
sf skills install --from-zip <url> --skill-name archify
```

See [docs/ci.md](docs/ci.md) for the full CI recipe and [`.github/actions/sf-run`](.github/actions/sf-run) composite action.

## State

Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository (SQLite + per-run workspaces under `.stageflow/runs/`). Global config and `sf_owned` auth live under **`~/.stageflow/`**. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.

## MCP

Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.

HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).

Stages use project `.mcp.json` plus stage `mcp` names. See [YAML catalog — Stage MCP](docs/yaml-catalog.md#stage-mcp).

## Stageflow vs Conductor

Both projects address multi-step agent workflows. They differ in orchestration model and runtime.

| | **Stageflow** | **Conductor** |
|---|---------------|---------------|
| **Model** | Configurable **stages** on Pi; pipeline-owned YAML (any domain) | Multi-**agent** workflow graph |
| **Orchestration** | Pipeline DAG + stage worker | Jinja routing, no LLM in router |
| **Unit of work** | Task → Pipeline → Stage attempts | Workflow → Agents |
| **Handoff** | Typed **envelope** + artifacts | Agent output → context |
| **Human gates** | Console + MCP + harness native question UI | Dashboard + TUI fleet |
| **Runtime** | Node.js, Pi coding agent | Python, Copilot/Claude SDKs |
| **Best for** | Personal/team **multi-stage Pi workflows** you define (releases, research, SDLC, …) | Enterprise multi-agent workflows |

If you want deterministic YAML routing across many agents, look at [Conductor](https://github.com/microsoft/conductor). If you want stage-bound Pi runs with reviewable envelopes and an operator console for **workflows you author**, use Stageflow.

## Examples

| Example | Description |
|---------|-------------|
| **[archify-on-pr](examples/archify-on-pr/)** | **Featured** — PR diagram automation: conditional fork, skill binding, envelope handoff, GHA deliver |
| [hello-world](examples/hello-world/) | Single stage, domain-neutral |
| [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
| [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
| [stage-mcp](examples/stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture |
| [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
| [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |
| [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
| [ci-validate](examples/ci-validate/) | Strict validate in CI |

Index: [examples/README.md](examples/README.md)

## Documentation

Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.io/stageflow/)** (GitHub Pages — live after merge to `main` and Pages enabled). Source in [`docs/`](docs/).

| Doc | Description |
|-----|-------------|
| [docs/README.md](docs/README.md) | Documentation index |
| [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
| [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
| [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
| [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
| [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
| [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
| [docs/mcp.md](docs/mcp.md) | MCP tool reference |
| [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
| [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
| [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |

## Develop from source

```bash
git clone https://github.com/tejasghutukade/stageflow.git
cd stageflow
npm i
npm run build && npm run ui:build   # ui:build builds the UI and copies assets into dist/ui
sf ui
```

Run tests: `npm test` and `npm run ui:test`. Typecheck: `npm run typecheck`.

## License

MIT © Tejas G

**Support:** [GitHub Issues](https://github.com/tejasghutukade/stageflow/issues) · [SUPPORT.md](SUPPORT.md)

**Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)

stageflow

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README