stageflow

Stageflow é um runtime de código aberto para fluxos de trabalho de agentes multiestágio configuráveis. Pipelines são criados como YAML de propriedade do projeto (`*.pipeline.yaml`, `*.task.yaml`, manifesto opcional `stageflow.yaml`), e cada estágio é executado em uma nova sessão de agente, passando contexto adiante por meio de envelopes e artefatos tipados. Pi é o backend de execução de agente atual. O pacote instala os binários `sf` e `stageflow` e requer Node.js 20 ou mais recente. O projeto posiciona estágios, não agentes, como a unidade de composição. Um agendador é dono da semântica de orquestração: prontidão DAG, paralelismo limitado, fan-out e join, roteamento condicional, novas tentativas, ramos ignorados e gates humanos retomáveis. A execução do agente fica atrás de uma abstração `AgentPort`, enquanto o Stageflow é dono do estado do pipeline, workspaces de estágio, validação de handoff e as interfaces usadas pela CLI, console, MCP e CI. O estado da execução é persistido em SQLite sob `<git-root>/.stageflow/`, com workspaces por execução sob `.stageflow/runs/`; configuração global e credenciais ficam em `~/.stageflow/`. Capacidades notáveis descritas no README incluem handoffs de envelope tipado via `write_stage_artifact` e `emit_stage_envelope`, execução de estágio verificada com checagens `verify` após a fase e reparo `on_verify_fail` ou recuperação manual, e gates humanos no loop onde o CI sai com código 2 enquanto uma execução está aguardando. Um console de operador local em `http://127.0.0.1:3847` suporta triagem de execuções, conexão de provedor, respostas de gate e inspeção de transcrições. Um endpoint MCP é exposto via Streamable HTTP em `/mcp` quando `sf ui` ou `sf mcp` está em execução, com ferramentas cientes de HITL como `wait_run`, `answer_gate`, `list_waiting` e `decide_feedback_loop`. Uso headless e CI é suportado via `sf validate --strict --json` e `sf run --json`, com códigos de saída documentados: 0 para sucesso, 1 para falha ou ocupado e 2 para aguardando. A autenticação do provedor pode ser configurada através do console ou comandos `sf providers`, com credenciais armazenadas no arquivo de autenticação compartilhado do Pi (`pi_home`) ou no próprio armazenamento do Stageflow (`sf_owned`). O README observa explicitamente que o Stageflow não é uma ferramenta de SDLC; entrega de software é um padrão de exemplo comum, mas os estágios são criados pelo usuário e agnósticos de domínio. O repositório inclui uma comparação com o Microsoft Conductor, enquadrando o Stageflow como execuções Pi vinculadas a estágios com envelopes revisáveis e um console de operador para fluxos de trabalho que o usuário cria, versus o roteamento YAML determinístico do Conductor entre muitos agentes. Pipelines de exemplo cobrem hello-world, plan-review com um gate de operador, roteamento condicional de fork, MCP de estágio, MCP Playwright, MCP Context7, rascunho de release do GitHub, um tour HITL primeiro-MCP e validação de CI. A documentação cobre arquitetura, quickstart, esquema YAML, referência CLI, envelopes, HITL, CI, MCP, provedores e o console de operador. O projeto é licenciado sob MIT.