sdd-agentic-flow

Versão prática em português. Leia o README principal em inglês para a referência técnica completa.

sdd-agentic-flow é um Spec-Driven Agentic Workflow Harness local-first e zero-dependência para agentes de código.

Seu agente pode entregar um diff e ainda deixar dúvida se cumpriu a intenção. Este toolkit mantém a especificação, a evidência e a revisão humana no mesmo fluxo.

O que é o sdd-agentic-flow?

O sdd-agentic-flow é um Agentic Workflow Harness: um plano de controle de engenharia nativo do repositório que transforma desenvolvimento orientado a especificações em workflows limitados e verificáveis para coding agents.

Não é só um pacote de Agent Skills. As skills são a camada pública de capacidade; o host de agentes de código é dono da execução em runtime. Em volta delas: metodologia, contratos de artefato, baselines, modelo de evidência, configuração, CLI e lifecycle.

O objetivo é engenharia assistida por agentes, estruturada, rastreável e verificável. O modo autonomous assume a entrega local dentro da autoridade delegada; humanos mantêm autoridade nas fronteiras de segurança, ações externas, irreversíveis e release.

O agente faz o trabalho. A especificação define o que deve ser verdadeiro. Sensores fornecem evidência. O modo autonomous resolve o trabalho ordinário e escala apenas na fronteira de autoridade.

Fontes que informam este desenho — com papéis epistêmicos, não como specs — estão em inspirations.

Specs estruturadas, limites claros e governança humana:

• Camada de capacidade: skills Markdown com contrato de capacidade sobre baselines TLC e TDD condensados.
• Dimensionamento adaptativo: perfis de feature com contexto de projeto auto-descoberto opcional.
• Zero footprint por padrão: instalação user-local; .sdd-agentic-flow/config.yml só quando você cria.
• Humano no loop: o toolkit estrutura o trabalho do agente; você mantém a autoridade final de revisão.
• Agnóstico de linguagem: a CLI roda em Node.js >= 22; seu projeto não precisa ser Node.

Para times que usam coding agents, essa divisão mantém o trabalho de engenharia revisável: humanos definem a intenção e verificam os resultados; agentes executam dentro do harness. O projeto não afirma ganhos de tokens ou velocidade sem dados medidos.

Instale e rode com npx sdd-agentic-flow: início rápido, guia de uso das skills, jornada do desenvolvedor e arquitetura.

O problema

Você delega uma tarefa. O agente pula para o código, mistura limites e marca trabalho como concluído sem prova executável. O tempo de revisão vai reconstruir a intenção a partir do diff — não validar o comportamento.

| Falha comum | Resposta local | | --- | --- | | Implementação começa antes de entender os requisitos | saf-create-spec e saf-create-prompts | | A tarefa é grande demais para uma mudança controlada | saf-implement ou saf-implement-multi | | Saída aceita sem evidência | saf-check-task e saf-validate | | PR perde rastreabilidade com a feature | saf-create-pr, saf-review-pr e saf-fix-pr |

Veja por que o toolkit existe. Para o modelo mental do plano de controle, leia sdd-agentic-flow model e engineering model.

Além dos prompts

A maioria das ferramentas para agentes para em prompts melhores. O sdd-agentic-flow explicita a fronteira de engenharia:

| Aspecto | Papel em uma linha | | --- | --- | | Prompt | Instruções por skill | | Context | Specs + contexto de projeto + config | | Harness | Modos, contratos, safety, evidência | | Execução do host | Loops, sessões e workers escolhidos pelo host |

SDD define o que é “pronto” antes da implementação. SAF define restrições e transições admissíveis; o host executa. Evidence Graph é uma projeção de rastreabilidade somente-leitura, não um grafo de execução. Veja o engineering model.

A solução

Escreva a spec primeiro. A spec é o contrato entre você e o agente: comportamento, escopo e critérios de aceite ficam em .specs/features/ antes de alterar código de produção.

Você delega um resultado limitado; o toolkit mantém os contratos de workflow e os gates de evidência. Manual, supervised e autonomous definem quanto da progressão fica com o agente. Cada fase tem uma skill Markdown, defaults de segurança locais e artefatos de evidência que você inspeciona. Leia a metodologia SDD (em inglês) para o panorama completo.

O que muda para você

| Resultado | Como o toolkit entrega | | --- | --- | | Limites de tarefa | Specs, prompts de tarefa e saf-check-task por fatia | | Rastreabilidade | Spec → prompt → código → pacote de PR em uma cadeia | | Evidência antes de concluir | TDD baseline, check reports, validation reports | | Entrada mais clara para o agente | Specs escritas e .sdd-agentic-flow/config.yml em vez de repetir contexto no chat | | Trabalho assíncrono | Artefatos versionados em .specs/ e .sdd-agentic-flow/ | | Setup reversível | uninstall --plan, escopo de instalação explícito, modelo de confiança |

[!NOTE] Benchmark de token economics: planejado para release futura (ROADMAP.md). Este README não cita multiplicadores de token ou velocidade sem dados medidos.

Início rápido

Requer Node.js >= 22 só para a CLI. Seu projeto não precisa ser Node.js. Veja compatibilidade de ambiente.

npx sdd-agentic-flow

Esse é o ponto de entrada humano canônico: ele encaminha primeiro uso, setup existente, setup parcial e recuperação. A CLI recomenda o lifecycle install → init → doctor; configuração é opcional. Ela é um plano de controle para setup, inspeção e manutenção — não invoca skills. Veja O que é SDD? e a referência de comandos.

Para automação ou uso avançado, use comandos explícitos como npx sdd-agentic-flow install, npx sdd-agentic-flow init e npx sdd-agentic-flow doctor. A política padrão efetiva é apply + supervised; use config policy somente quando um override explícito for necessário. Autonomous não significa autoridade ilimitada. Commit, push, merge, tag, publish, deploy e outras ações externas ou irreversíveis continuam fora da delegação. A CLI não executa skills.

Depois, invoque saf-route ou abra o guia de uso das skills. Copie uma receita de prompts ao delegar a um agente.

Em um terminal real, npx sdd-agentic-flow guia a configuração de compartilhamento, hosts de agentes, workflow, idioma e profundidade do processo (com Supervisionado recomendado ao pressionar Enter). Para automação, use init e comandos config explícitos. Veja início rápido.

Ao escolher pt-BR, a saída humana da CLI — prompts, planos, doctor, menu e learn-sdd — passa a usar português brasileiro. Commands, paths, statuses, IDs e JSON permanecem em inglês canônico para continuar copiáveis e estáveis.

Como funciona

Canonical workflow path: Plan → Prompt → Implement → Check → PR → Review → Fix → Validate

flowchart TD
  route[saf-route] --> brainstorm[saf-brainstorm]
  brainstorm -->|converged| specs[saf-create-spec]
  route --> specs
  specs -.->|on demand| explain[saf-explain]
  specs --> prompts[saf-create-prompts]
  prompts --> implement[saf-implement]
  prompts -->|dependent tasks| implementmulti[saf-implement-multi]
  implementmulti -->|delegates per task| implement
  implement --> check[saf-check-task]
  check --> pr[saf-create-pr]
  pr --> review[saf-review-pr]
  review -->|findings accepted| fix[saf-fix-pr]
  fix --> review
  review -->|ready| validate[saf-validate]

Use saf-route quando o próximo passo não estiver claro. Ele recomenda uma skill e aponta para o SKILL.md selecionado; não invoca skills nem altera arquivos.

Exemplos de workflow

Esses walkthroughs ilustram formatos de artefatos e o comportamento esperado da CLI. Não são evidência de execução de agentes. As jornadas executáveis da CLI estão em scripts/cli-exhaustive.ts e scripts/cli-certification.ts.

| Fluxo | O que ilustra | Walkthrough | | --- | --- | --- | | Greenfield | Source item até validação | task-management | | Código existente | Specs a partir de código sem docs | existing-code mode | | Project context | Ciclo context refresh / context status | project-context lifecycle | | Loop de PR | Create → review → fix → review | pr-flow | | Autonomia AUTO-001 | Idea → spec com config autônoma | autonomy-idea-to-spec | | Autonomia AUTO-002 | Cadeia spec → validate | autonomy-spec-to-validate | | Autonomia AUTO-003 | Guardrail pause → resume | autonomy-guardrail-pause-resume | | Autonomia AUTO-004 | Human override (guardrail 3) | autonomy-human-override | | Autonomia AUTO-005 | Budget exhaustion (guardrail 6) | autonomy-budget-exhaustion |

O exemplo task-management mostra uma feature de ponta a ponta. As fixtures de autonomia ilustram estados de continuidade e reparo; somente checks executados fornecem evidência de um comportamento específico.

TDD baseline

O toolkit usa um baseline TLC para planejamento e um baseline TDD para implementação. O contrato exigido é evidência comportamental adequada na costura contratual (campo Public seam), com resultados atuais gravados. Test-first é recomendado quando afia a spec. O ritual completo RED → GREEN → REFACTOR é opcional e não é prova do harness. Um sensor que passa é evidência, não veredito de correção. Self-report is not evidence. Specs are living control artifacts; rigor follows uncertainty and risk. Detalhe canônico: TDD baseline e baselines.

Saiba mais

| Tópico | Doc | | --- | --- | | Modelo de engenharia e identidade do produto | docs/engineering-model.md | | Jornada ilustrativa do desenvolvedor | docs/developer-journey.md | | Metodologia SDD | docs/sdd-methodology.md | | Arquitetura | docs/architecture.md | | As 12 skills | docs/skills-catalog.md | | Setup por agente | Codex, Cursor, Claude Code, VS Code + Copilot | | Política de idioma | docs/i18n.md | | Contribuir | CONTRIBUTING.md |

Para quem é indicado?

Você se encaixa se adota Spec-Driven Development, entrega em sprint com gates de revisão, fatia specs e tarefas como tech lead, delega fatias rastreáveis a agentes, exige evidência comportamental (TDD e test-first continuam estratégias válidas) ou coordena trabalho multi-agente ou multi-task com controle humano.

Não é otimizado para

Scripts descartáveis, agentes sem revisão humana, pipelines automáticos de release/deploy, ou fluxos que rejeitam specs, limites de tarefa e checkpoints de validação.

A referência completa de comandos, bundle oficial, modos de execução, níveis de autonomia, mapa de skills, vocabulário de domínio e limites de segurança está no README em inglês (seção colapsável Technical reference).

Resumo de confiança: código inspecionável, zero dependências npm externas em runtime, sem telemetria ou rede por padrão. As bibliotecas de build usadas pela UI rica do terminal são incorporadas ao artefato publicado. As exceções de rede são doctor --check-updates, upgrade e a pergunta opcional do welcome interativo. O toolkit não faz commit, push, merge, deploy ou publish automaticamente. Por padrão, install --scope user não cria arquivos no projeto. Veja modelo de confiança e escopo de instalação.

Desinstalação:

npx sdd-agentic-flow uninstall --plan
npx sdd-agentic-flow uninstall --yes

Veja desinstalação e a política de compatibilidade.