sdd-agentic-flow

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

sdd-agentic-flow é um toolkit local-first e zero-dependência de Spec Driven Development para fluxos com agentes de código. Ele traz skills Markdown com contrato de capacidades, baselines condensadas de TLC e TDD, dimensionamento adaptativo por perfil de feature, e contexto de projeto opcionalmente auto-descoberto. A instalação de skills é explícita e, por padrão, user-local — sem nenhum arquivo no projeto; a configuração (.sdd/config.yml) é sempre explícita e fica no projeto. A decisão final é sempre das pessoas. Veja a arquitetura.

Por que confiar?

O código é inspecionável, a CLI tem zero dependências runtime, não usa telemetria, postinstall ou rede externa por padrão, e não faz commit, push, merge, deploy ou publish automaticamente. Use doctor e doctor --smoke para validação local.

Por padrão, install usa o escopo user: escreve apenas nos diretórios globais de skills de cada agente suportado (Codex CLI, Cursor, Claude Code, VS Code + GitHub Copilot) e não cria nenhum arquivo no projeto. Use --scope project para o comportamento anterior (grava em .agents/skills/ dentro do projeto). Veja installation-scope.md.

Início rápido

npx sdd-agentic-flow init
npx sdd-agentic-flow install core
npx sdd-agentic-flow doctor

Veja installation.md (em inglês) para o guia completo de instalação.

Use init --interactive para escolher as opções iniciais, incluindo o perfil de feature (small_fix, medium_feature, large_feature, epic). Packs disponíveis: core, planning, execution, pr, multi-worktree, full, local-files e github. O init também auto-descobre .sdd/context/project-context.md; rode discover [--force] para atualizar, ou context status/context refresh para ver a proveniência gravada (quando/de qual revisão foi gerado) e atualizá-la sem precisar lembrar da flag.

Para escolher o perfil de idioma diretamente:

npx sdd-agentic-flow init --language en-US
npx sdd-agentic-flow init --language pt-BR

Veja os perfis de idioma para conhecer o contrato.

Modos e desinstalação

Os modos documentados são plan, guided, apply, review e full; todos preservam limites locais e não publicam ou enviam alterações por padrão. Veja execution modes.

npx sdd-agentic-flow uninstall --plan
npx sdd-agentic-flow uninstall --apply

A desinstalação preserva specs, relatórios, snapshots e código-fonte, e remove dos dois escopos por padrão. Use --include-config apenas para remover também .sdd/config.yml, ou --scope/--agent para restringir a remoção.

Fluxo principal

Plan → Prompt → Implement → Check → PR → Review → Fix → Validate

Use sdd-route quando o próximo passo não estiver claro. Ele apenas recomenda uma skill local e não executa ações automaticamente. Veja o modelo de invocação, por que o toolkit existe, e os princípios de design (ambos em inglês).

Perfis de idioma definem a saída humana; o glossário de domínio é opcional e registra termos do produto. O init não cria esse arquivo automaticamente. Veja vocabulário de domínio.

TDD baseline

O sdd-agentic-flow usa o TLC baseline para planejamento e specs e o TDD baseline para implementação. O TDD baseline usa testes focados em comportamento, public seams acordados, ciclos RED → GREEN → REFACTOR e vertical slices. Veja TDD baseline.

Para quem é indicado?

É indicado para times que usam SDD, entregam features em sprints, usam TDD/test-first, precisam de rastreabilidade e delegam tarefas para agentes com revisão. Não é otimizado para scripts descartáveis, agentes sem revisão humana ou pipelines automáticos de release/deploy.

Para o fluxo completo, consulte o guia de uso das skills em português e o guia em inglês.

Veja o catálogo de skills para a versão detalhada — propósito, quando usar/não usar, entradas/saídas, dependências, conflitos, baseline e posição no fluxo de cada uma das 11 skills públicas.

Veja também a matriz de compatibilidade (quais packs instalam quais skills) e os guias de decisão: escolhendo um perfil de feature, adotando em um repositório existente, e baselines condensadas vs. completas.