sdd-agentic-flow

Agentes de código podem começar a escrever antes de entender o pedido, sair do escopo da tarefa e declarar o trabalho pronto sem prova executável. Quem revisa precisa reconstruir a intenção a partir do diff antes de conseguir verificar o comportamento.

Eu queria uma forma de delegar trabalho a agentes mantendo a intenção registrada, o escopo delimitado e as evidências inspecionáveis, sem abrir mão das decisões que devem ficar com uma pessoa.

A especificação vem primeiro e fica no repositório. Doze skills em Markdown cobrem o caminho do planejamento ao prompt, implementação, checagem da tarefa, pull request, revisão, correção e validação. Cada fase gera artefatos que quem revisa pode abrir.

Uma CLI pequena funciona como plano de controle: instala o pacote de skills, inicializa o workspace e diagnostica a configuração. Ela nunca executa skills. Quem executa o trabalho é o host do agente (Codex, Cursor, Claude Code ou VS Code com Copilot).

As skills são a camada de capacidade e o host controla a execução. Isso mantém o toolkit portável entre agentes. O custo é não poder impor comportamento em tempo de execução, então ele depende de contratos, gates e evidências.

Nenhuma dependência npm em tempo de execução, instalação local do usuário por padrão e configuração só quando você a cria. A superfície de confiança fica pequena e a instalação é reversível com um plano de desinstalação.

A autonomia tem limites explícitos. Os modos manual, supervisionado e autônomo definem quanto do avanço fica com o agente, mas commit, push, merge, publicação e deploy ficam sempre com uma pessoa.

As afirmações são medidas. O projeto não cita ganhos de tokens ou velocidade sem dados, e o parser de contratos rejeita chaves desconhecidas e recursos executáveis de YAML.

Testes unitários cobrem os módulos da CLI, e jornadas automatizadas exercitam install, init, doctor, upgrade e uninstall de ponta a ponta. Exemplos de referência documentam os artefatos de cada fluxo e são apresentados como ilustração, não como evidência do comportamento dos agentes.