# Guia de uso — Pipeline SDD completo
Este guia descreve como usar a camada de orquestração SDD em qualquer projeto, do onboarding inicial até memória final.
Para comandos específicos de Codex, Claude Code, Cursor, opencode, Devin, Trae, Antigravity, Zed/ACP e MCP, veja [`docs/PROGRAMAS.md`](PROGRAMAS.md).
## 1. Instalar em um projeto
Modo recomendado:
```bash
cd /caminho/do/projeto
sdd init
```
Por padrão, `sdd init` detecta o root do projeto, escolhe um preset (`frontend-react`, `backend-node`, `hono-api`, `python-api`, `rust-api`, `monorepo`, `infra` ou `generic`) e usa layout compacto: arquivos operacionais ficam em `.sdd/`, e a raiz recebe apenas `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.opencode/` e `sdd.config.yaml`.
Se `optimization.codegraph.auto_index` estiver ativo, `sdd init` também tenta executar `codegraph init -i .` no root do projeto quando o binário existir no `PATH` e `.codegraph/` ainda não existir. A indexação é best-effort: falha ou ausência do CodeGraph não bloqueia a instalação.
Para inicializar outro diretório a partir de qualquer pasta:
```bash
sdd init --root /caminho/do/projeto
```
Para forçar um preset específico:
```bash
sdd init --root /caminho/do/projeto --preset frontend-react
```
Para simular sem escrever:
```bash
sdd init --root /caminho/do/projeto --preset frontend-react --dry-run
```
`--dry-run` apenas mostra as ações; nenhum arquivo é criado.
Para instalar também o workflow de validação:
```bash
sdd init --root /caminho/do/projeto --preset backend-node --with-ci
```
Por padrão o installer não copia o plugin Claude embutido (`.claude/skills/orchestration-plugin`), para evitar comandos duplicados. Use `--with-claude-plugin` apenas para desenvolver ou testar o plugin em um projeto alvo.
Para copiar o exemplo completo:
```bash
sdd install /caminho/do/projeto --with-examples
```
Para atualizar um projeto que já tem `.sdd/` instalado:
```bash
cd /caminho/do/projeto
sdd update
sdd clients doctor
```
`sdd upgrade` é alias de `sdd update`. Por padrão, o update mescla `AGENTS.md` e `CLAUDE.md` existentes com um bloco gerenciado do SDD, atualiza arquivos gerenciados pelo pacote e preserva `sdd.config.yaml`, artefatos em `docs/<orquestracao>/` e arquivos extras criados pelo projeto dentro dos diretórios de agents/rules. Use `sdd update --update-config --preset <preset>` somente quando quiser regenerar `sdd.config.yaml`.
Presets disponíveis:
- `generic`
- `frontend-react`
- `backend-node`
- `hono-api`
- `python-api`
- `rust-api`
- `monorepo`
- `infra`
Copie para a raiz do projeto:
- `AGENTS.md`
- `CLAUDE.md`
- `.claude/`
- `.codex/`
- `.agents/`
- `.sdd/`
- `sdd.config.yaml`
Depois crie o arquivo de configuração do projeto:
```bash
# Linux / macOS
cp .sdd/sdd.config.example.yaml sdd.config.yaml
```
```powershell
# Windows (PowerShell)
Copy-Item .sdd/sdd.config.example.yaml sdd.config.yaml
```
Edite `sdd.config.yaml` com stack, sistemas, paths e comandos reais do projeto.
## 2. Rodar o doctor
Antes de usar a pipeline:
```bash
sdd doctor
sdd clients doctor
```
O doctor valida se os arquivos essenciais existem e se `sdd.config.yaml` tem as chaves mínimas.
## 2.1. Configurar providers
O bloco `providers` em `sdd.config.yaml` define defaults e registry offline. A ordem de precedência é:
1. Flags: `--provider`, `--model`, `--effort`, `--offline`.
2. Env: `SDD_PROVIDER`, `SDD_MODEL`, `SDD_EFFORT`/`SDD_REASONING_EFFORT`, `SDD_OFFLINE`.
3. Config: `providers.default`, `providers.model`, `providers.effort`, `providers.offline`.
4. Defaults embutidos: `codex`, `claude`, `antigravity`, `opencode` e `cursor`.
Comandos úteis:
```bash
sdd providers list
sdd providers doctor --json
sdd orchestration --provider claude --model claude-sonnet-4-6 --effort high --dry-run "x"
sdd prd --provider custom --model local-test --effort medium --name "ciclo" "entrada"
```
Cada provider pode declarar `models`, `efforts`, `model`, `effort`, `stage_models` e `stage_efforts`. A seleção inicial define o fallback do workflow; quando uma etapa tem override em `.codex/agents`, `.claude/agents`, `.cursor/model-routing.yaml` ou `.opencode/model-routing.yaml`, o CLI considera esse modelo primeiro, mas só aplica se ele existir em `models` daquele provider. Os defaults atuais usam Codex `gpt-5.4`/`gpt-5.5`; Claude `claude-haiku-4-5`, `claude-sonnet-4-6` e `claude-opus-4-8`; Antigravity CLI (`agy`) com `gemini-3.5-flash`, `gemini-3.1-pro` e a opção manual `claude-opus-4.6`; Cursor com `composer-2.5-fast`, `composer-2.5`, `sonnet-4.6` e `haiku`; e opencode Go/Zen com IDs reais como `opencode-go/deepseek-v4-pro`, `opencode-go/kimi-k2.7`, `opencode-go/qwen3.7-plus` e `opencode/minimax-m3-free`, sempre com `medium`, `high` ou `xhigh`.
`providers list` mostra catálogo/modelos com detecção rápida de PATH/env, sem rodar checks de sessão que podem demorar. `providers doctor` mostra métodos em `auth_methods`, como API key por env var, CLI local no `PATH` e checks de sessão quando configurados. O CLI valida `agy models`, `codex login status`, `claude auth status`, `opencode providers list` e `cursor agent status`; quando o método falta, a saída inclui `login_command`, por exemplo `agy`, `codex login`, `claude auth login`, `opencode providers login` ou `cursor agent login`. Valores como API keys, tokens e passwords não devem aparecer em stdout, stderr, artifacts, memory, review ou `.sdd/events.jsonl`.
Na TUI, a tela inicial de provider mostra modelo, effort, budget de tokens, limites declarados e métodos de autenticação detectados. Use `←/→` para escolher o modelo inicial e `[`/`]` para escolher o effort inicial. O campo `providers.registry.<id>.usage_limits` pode declarar janelas como `weekly` ou `monthly`, unidade (`hours`, `tokens`, `requests`, `credits`), limite, saldo restante, reset e fonte; quando o provider/adapter não expõe quota real, o TUI mostra esse limite como informado/manual em vez de inventar saldo. Cada item de `models` também pode declarar `context_window_tokens` e `pricing` (`currency`, `input_per_million`, `cached_input_per_million`, `output_per_million`); com isso, o TUI calcula custo por geração quando existe usage real ou estimado. Sem `pricing`, a tela mostra `preço não configurado no modelo`.
Artefatos Markdown e HTML gravam telemetria em `## Rastreabilidade`: `Tokens source: provider-reported` quando o adapter/editor chamar `sdd <stage>` ou `sdd artifact save` com `SDD_USAGE_INPUT_TOKENS`, `SDD_USAGE_CACHED_INPUT_TOKENS`, `SDD_USAGE_OUTPUT_TOKENS`, `SDD_USAGE_REASONING_OUTPUT_TOKENS` e `SDD_USAGE_TOTAL_TOKENS`; `Tokens source: estimated` quando o CLI precisar estimar localmente. Para tempo real de geração, use `SDD_GENERATION_STARTED_AT`, `SDD_GENERATION_EXECUTION_STARTED_AT`, `SDD_GENERATION_FINISHED_AT`, `SDD_GENERATION_DURATION_MS`, `SDD_GENERATION_REASONING_DURATION_MS` e `SDD_GENERATION_EXECUTION_DURATION_MS`; o artefato grava `Tempo source: provider-reported`. Sem esses envs, o CLI registra apenas o tempo local da renderização determinística. Esses campos são contagens e timestamps de uso, não credenciais.
Ao gerar ou apertar `r` para regenerar um artefato, o runner emite eventos incrementais para o TUI: `Trace` para a timeline do agente, `Context` para prompt/artefatos/janela de contexto, `Usage` para input/cache/output/reasoning/total e `Finished` para persistência do artefato. Os adapters diretos atuais usam `codex exec --json`, `claude --print`, `opencode run`, `cursor agent --print`, `devin --print`, `trae-cli run` e `agy --prompt`; todos gravam a resposta final em um arquivo temporário e persistem o draft pelo comando determinístico `sdd artifact --root <root> save ...`. Em Execution, os mesmos clients têm modo workspace-write explícito; provider sem adapter direto continua caindo no harness determinístico ou falha antes de executar o client, com fallback registrado na timeline.
O bloco `runtime.node_effect_bridge.enabled` controla o spike Node+Effect.ts. Com `enabled: false`, `sdd doctor` e `sdd orchestration --dry-run` não exigem `node`, `pnpm` ou Effect.ts.
## 2.2. Inicializar artifact store local
Antes de iniciar uma feature, defina um nome curto para a orquestração e crie o diretório local:
```bash
sdd init "exportacao csv relatorio vendas"
```
O diretório `docs/<slug-da-orquestracao>/` guarda os artefatos aprovados/registrados quando Jira, Confluence ou outro sistema externo ainda não estão configurados por completo.
## 2.3. Diagramas e companions visuais
PRD e Tech Spec materializados devem manter `## Diagramas` com Mermaid, `.excalidraw`, `Não aplicável` com justificativa curta ou referência validada a `assets/diagrams/*.html|*.svg`. IDEA recebe a seção no scaffold quando útil, mas continua válida sem ela.
Use Mermaid/Excalidraw como contrato versionável. Quando um visual editorial for pedido ou `diagrams.visual` permitir, gere o companion com `diagram-design`, salve em `docs/<slug-da-orquestracao>/assets/diagrams/` e anexe:
```bash
sdd diagram doctor --name "exportacao csv relatorio vendas"
sdd diagram attach --name "exportacao csv relatorio vendas" --stage prd --file caminho/visual.html --title "Jornada principal" --source "02-prd.md"
```
Configuração recomendada em `sdd.config.yaml`:
```yaml
diagrams:
auto_markdown: true
visual: explicit # explicit | always | never
visual_stage_allowlist:
- idea
- prd
- techspec
```
## 2.4. Memória derivada
Depois de PRD/Tech Spec/Review registrados, gere o índice local:
```bash
sdd memory learn --name "exportacao csv relatorio vendas"
sdd memory status --json
```
O arquivo `.sdd/memory/learnings.jsonl` é derivado de `docs/<slug>/`, contém `source_artifact` e `source_hash`, e pode ser removido/reconstruído. A fonte primária continua sendo o artifact store.
## 2.5. Project Intelligence Layer
A Project Intelligence Layer usa artefatos canônicos, rastreabilidade, ADRs, reviews, memórias e rules para montar contexto auditável antes de cada etapa SDD. Ela não substitui `docs/<slug-da-orquestracao>/` nem `traceability-map.yaml`; índices em `.sdd/intelligence/` são derivados e reconstruíveis.
Comandos principais:
```bash
sdd intelligence learn --name "exportacao csv relatorio vendas"
sdd intelligence learn --all
sdd intelligence repair --all --json
sdd intelligence status --json
sdd intelligence health --json --fail-on high
sdd context build --name "exportacao csv relatorio vendas" --stage execution --write
sdd context build --name "exportacao csv relatorio vendas" --stage execution --task T-04 --write
sdd optimize status --json
```
`sdd intelligence learn` indexa aprendizados derivados com ponteiro e hash da fonte; `--all` reconstrói os derivados de todos os artifact stores rastreáveis em `docs/*/traceability-map.yaml`. `repair` gera `08-memory.md` operacional quando faltar e reindexa hashes obsoletos, fechando sinais `missing-memory` e `stale-learning` apontados por health. `status` inspeciona índices, obsolescência e conflitos. `health` mostra sinais objetivos de saúde do fluxo e pode falhar checkpoints/CI com `--fail-on`. `sdd context build` gera um Context Pack por stage com manifesto de fontes incluídas, excluídas, obsoletas, conflitos e validações sugeridas, considerando automaticamente histórico local ranqueado.
O Optimization Wrapper envolve CodeGraph, RTK e Caveman como aceleradores opcionais. `sdd optimize status --json` mostra disponibilidade, versão, índice, capacidades e fallback; `sdd context build` usa esse status para montar um Context Handoff com objetivo, task atual, artefatos base, arquivos prováveis, testes sugeridos e paths fora de escopo por padrão. Em clients MCP, use `sdd_context_bundle` ou `sdd://context-bundle/{orchestration}/{stage}` como primeira leitura: o bundle junta Context Pack, handoff, artifact status, busca local, traces, capabilities, runtime adapters e chamadas recomendadas de CodeGraph. Quando CodeGraph não estiver indexado, o fallback esperado é `git diff/status`, manifests e `rg` delimitado. RTK deve ser preferido para comandos longos/ruidosos, e `sdd optimize compress --kind trace|handoff|memory-derived` compacta apenas timeline, comandos, evidências e pendências operacionais.
Veja `docs/PROJECT-INTELLIGENCE.md` para operação detalhada, redaction e regras de provider-neutralidade.
## 3. Fazer Project Discovery
Em projetos brownfield, rode discovery antes da primeira feature:
```text
/sdd discover
```
Saída esperada:
- stack real;
- paths de código, testes, docs e migrations;
- comandos verificados;
- padrões de arquitetura e teste;
- riscos do projeto;
- regras de quando usar Refinement, Agent Teams e checkpoints extras.
Registre o resultado em um documento baseado em `.sdd/templates/project-discovery.md`.
O discovery também inclui `Recomendações de skills e regras`. Use essa seção, ou rode `sdd context recommend --write`, para planejar novas skills específicas da tecnologia do projeto, rules por cliente e atualizações curtas em `AGENTS.md`/`CLAUDE.md`.
Se fizer parte de uma orquestração, salve como `recorded`:
```bash
sdd artifact save "exportacao csv relatorio vendas" project-discovery --file project-discovery.md --state recorded
```
## 4. Classificar risco da feature
Antes de iniciar a feature:
```text
/sdd risk "implementar login SSO com alteração de permissões"
```
Ou diretamente pelo CLI:
```bash
sdd risk "implementar login SSO com alteração de permissões"
```
Use o resultado para decidir:
- se Refinement é obrigatório;
- se Agent Team é necessário;
- se deploy precisa de checkpoint explícito;
- quais reviewers especialistas entram no Review.
## 5. Rodar o fluxo completo
```text
/sdd orchestration "quero exportar CSV no relatório de vendas"
```
O fluxo executa:
1. Idea
2. PRD
3. Tech Spec
4. Tasks
5. Refinement, quando necessário
6. Execution
7. Review
8. Memory
O orquestrador deve parar nos checkpoints e pedir uma decisão explícita: `aprovar`, `pedir ajustes` ou `rejeitar`.
Após cada aprovação, o orquestrador deve salvar o artefato aprovado em `docs/<slug-da-orquestracao>/` e citar o caminho salvo antes de avançar.
## 5.1. Rodar o Agentic SDD Loop
Quando a demanda vier de texto livre, agent externo, card, issue, webhook ou bot, prefira o loop agentic como porta de entrada:
```bash
sdd workflow validate agentic-sdd-loop --json
sdd workflow run agentic-sdd-loop --input "quero exportar CSV no relatório de vendas" --max-iterations 3 --json
sdd workflow status agentic-sdd-loop --json
```
O loop resolve a entrada, roda o planejamento SDD interno até o primeiro checkpoint humano e persiste evidência em dois relatórios:
- `.sdd/workflows/agentic-sdd-loop.json`: envelope agentic, nodes executados, checkpoint e status do loop externo.
- `.sdd/workflows/standard-sdd.json`: planejamento SDD interno, artefatos produzidos, demandas pausadas e prontidão para execução.
Depois de revisar o PRD, registre a decisão humana e continue pelo motor supervisionado:
```bash
sdd demand approve <id> --gate prd --by "<pessoa>"
sdd auto run --real
sdd auto run --real --through review
sdd auto run --real --through memory
sdd auto run --real --unattended
```
Use `--real` apenas quando o provider/adapter estiver configurado e autorizado. Sem adapter real, mantenha o loop como contrato determinístico, materialize os artefatos em `docs/<slug-da-orquestracao>/` e atualize o `traceability-map.yaml`.
Use `--unattended` quando a intenção for rodar sem gate humano até a memória. Ele autoaceita PRD, Tech Spec e Refinement com `channel: automation`, registra eventos `gate_auto_accept` e usa `--through memory` como padrão quando `--through` não é informado.
Para agents, as melhores práticas são:
- preservar a demanda original em `--input`;
- consultar `sdd health --json` para uma visão read-only de manutenção e drift antes de rodadas longas;
- usar `sdd context build --name "<ciclo>" --stage execution --json --metadata-only` antes do Context Pack completo quando a intenção for escolher arquivos/testes com baixo consumo de tokens;
- rodar `sdd workflow status agentic-sdd-loop --json` antes de retomar;
- nunca autoaprovar PRD, Tech Spec, Refinement, Review, merge, release ou deploy;
- usar os comandos gerados do client quando existirem, como `.codex/commands/agentic-sdd-loop.md`, `.claude/commands/agentic-sdd-loop.md`, `.devin/workflows/agentic-sdd-loop.md`, `.opencode/commands/agentic-sdd-loop.md` e `.trae/commands/agentic-sdd-loop.md`;
- manter artifact store, checkpoints e traces locais como fonte operacional, mesmo quando houver links externos para Jira, Linear, GitHub, GitLab, Slack ou webhooks.
Veja o guia completo em `docs/AGENTIC-SDD-LOOP.md`.
## 5.2. Rodar dry-run
Antes de liberar escrita em projetos sensíveis:
```text
/dry-run "adicionar exportação CSV no relatório"
```
O dry-run produz Discovery, Risk, PRD, Tech Spec, Tasks e Refinement quando necessário, mas não executa código.
## 6. Usar etapas individuais
Use quando já houver artefato anterior ou quando quiser retomar uma etapa:
```text
/prd <ideia>
/techspec <prd>
/tasks <tech spec>
/refinement <backlog>
/execution <task>
/review <PR ou diff>
/memory <feature concluída>
```
## 7. Usar Agent Teams
O caminho padrão é um subagent por etapa. Use Agent Teams só quando houver trabalho paralelo real:
```text
/team-techspec <PRD complexo>
/team-execution <tasks independentes com ownership separado>
/team-review <PR não trivial>
```
Regra: teammates produzem pareceres; o agente lead sintetiza. Nenhum teammate substitui checkpoint humano.
## 8. Validar artefatos
Os contratos mínimos vivem em `.sdd/schemas/artifact-sections.json`.
Exemplo:
```bash
sdd validate-artifact techspec docs/minha-techspec.md
```
Um artefato só deve avançar se tiver as seções obrigatórias, principalmente `Rastreabilidade`.
Depois de validado e aprovado, salve:
```bash
sdd artifact save "exportacao csv relatorio vendas" techspec --file techspec.md --state approved
```
## 9. Rastreabilidade
Use `.sdd/templates/traceability-map.yaml` como mapa canônico da feature. Ele liga:
- Project Discovery;
- Risk Classification;
- ideia;
- PRD;
- Tech Spec;
- Tasks;
- Refinement;
- Execution: branch, commits e PR;
- ADR;
- CI;
- review;
- memory.
Não copie documentos inteiros entre sistemas. Grave o link canônico e o estado.
Quando não houver sistema externo confiável, use `docs/<slug-da-orquestracao>/traceability-map.yaml` como mapa canônico local.
## 10. Checkpoints
Use `.sdd/templates/checkpoint.md` em qualquer gate humano.
Gates obrigatórios:
- PRD aprovado;
- Tech Spec aprovada;
- Merge aprovado;
- Deploy aprovado quando houver produção, infra, migration ou feature flag.
Refinement vira gate quando houver risco médio ou alto.
## 11. Review e release
Antes de merge:
- CI ou testes locais relevantes precisam estar verdes;
- review precisa apontar para critérios de aceite;
- achados precisam ter severidade;
- PR precisa apontar para task/spec;
- riscos pendentes precisam estar explícitos.
Antes de deploy:
- evidência de CI;
- plano de rollback;
- feature flags ou rollout quando aplicável;
- aprovação humana.
## 12. ADR pós-execução
Depois de concluir Execution, registre decisões arquiteturais relevantes:
```text
/adr
```
Salve a ADR em `docs/<slug-da-orquestracao>/06-adr.md`. Ela deve apontar para execução, Tech Spec, Tasks, PR/commits, testes e ADRs anteriores quando houver.
## 13. Memory
Ao final, rode:
```text
/memory
```
A memória deve compactar decisões, links, padrões úteis, testes e pendências. Não deve duplicar PRD, Tech Spec ou logs extensos.
Salve a memória em `docs/<slug-da-orquestracao>/08-memory.md` e cite os links externos e ADRs quando existirem.
## 14. Automations e hooks
Use esta ordem:
1. Webhooks/Channels para eventos reais de Jira, CI, PR, Slack e deploy.
2. Scheduled tasks para polling temporário.
3. Hooks locais para guardrails determinísticos.
Hooks atuais:
- bloqueiam escrita por agents read-only;
- bloqueiam comandos destrutivos, merge, push e deploy sem gate;
- validam eventos de Agent Teams;
- registram auditoria em `.sdd/*.jsonl`;
- notificam quando há input humano pendente.
## 15. Adapters e presets
Adapters ficam em `.sdd/adapters/` e presets em `.sdd/presets/`. Use adapters para trocar ferramenta sem mudar o fluxo:
- Atlassian: Jira, Confluence, Bitbucket.
- GitHub: Issues, PRs, Actions.
- GitLab: Issues, MRs, CI.
- Linear/Notion.
- Markdown-only.
Veja `docs/ADAPTERS.md`.
## 15. Artifact store local
Referência completa: `docs/ARTIFACT-STORE.md`.
Comandos principais:
```bash
sdd init "<nome-da-orquestracao>"
sdd artifact save "<nome-da-orquestracao>" prd --file prd.md --state approved
sdd artifact status "<nome-da-orquestracao>"
```
## 16. Validação contínua
Rode localmente:
```bash
sdd ci --strict-release
sdd maintenance report
```
O mesmo contrato do gate é usado em `.github/workflows/sdd-layer.yml`. O modo strict/release sempre usa `sdd health --strict`; ao incluir `--name "<slug>"`, o gate também escopa os sinais de qualidade/health da orquestração e inclui validações como `sdd diagram doctor --name`.
## 17. Critério de pronto do fluxo
Uma feature está pronta quando:
- todos os artefatos têm rastreabilidade;
- checkpoints obrigatórios foram aprovados;
- tasks têm critérios de aceite;
- código aponta para task/PR;
- testes/CI têm evidência;
- review tem veredito;
- deploy, quando houver, foi aprovado;
- memory foi registrada.