# SDD client - Claude Code
Use `.claude/skills/orchestration/SKILL.md` ou `.claude/commands/orchestration.md`; comandos antigos em `.claude/commands/orchestrator.md` devem delegar ao canônico.
## Nome canônico
- Use `orchestration` para comandos e skills.
- Trate `orchestrator` como alias legado e apenas como papel humano.
## Resolução do CLI
- Faça uma checagem curta com `command -v sdd`. Se retornar um path, use `sdd ...`.
- Se `sdd` não estiver no `PATH` e o projeto atual for o checkout fonte `sdd-layer` (`Cargo.toml` com `name = "sdd-layer"` e bin `sdd`), use `cargo run --bin sdd -- ...` a partir da raiz.
- Em shells de editor, confirme `echo "$PATH"`; se faltar `$HOME/.cargo/bin`, configure `export PATH="$HOME/.cargo/bin:$PATH"` no ambiente do cliente.
- Não procure entrypoints alternativos antes desse preflight; se ambos falharem, reporte instalação/PATH ausente e o comando exato a reexecutar após instalar o binário ou ajustar o PATH.
## Provider e login
- Rode `sdd providers doctor` para validar provider/modelo/credenciais antes de iniciar.
- Quando um método estiver deslogado, use o `login_command` exibido, por exemplo `agy`, `codex login`, `claude auth login`, `devin auth login`, `trae-cli show-config`, `opencode providers login` ou `cursor agent login`.
- Nunca copie tokens para prompts ou artefatos; use nomes de env vars e deixe o CLI redigir eventos.
## Avaliação e observabilidade
- Rode `sdd eval stage --name "<ciclo>" --stage <stage> --json`, `sdd eval orchestration --name "<ciclo>" --json` e `sdd quality report --name "<ciclo>" --json` antes de avançar execução, review ou memória.
- Use `sdd trace summary --orchestration "<ciclo>" --json` para auditar eventos e evidências.
- Eventos registram `agent`, `selected_model`, `observed_model` quando o provider reporta metadata confiável e `confidence`.
- Não trate `selected_model` como modelo observado. Quando o provider só retorna texto, deixe `observed_model` não reportado.
- Execução real com escrita no workspace exige adapter autorizado; nesta versão, apenas Codex tem `WorkspaceExecutionAdapter`. Outros clients devem gerar artefatos/handoff ou falhar antes de mutar arquivos.
## Atualização de pacote
- Em projeto já instalado, rode `sdd update` para refletir mudanças do pacote.
- `sdd upgrade` é alias de `sdd update`.
- O update preserva `sdd.config.yaml`, `docs/<orquestracao>/` e arquivos extras de skills/rules locais por padrão.
## Skills e workflows
- Valide o catálogo híbrido com `sdd skills doctor --strict`.
- Revise sync sem escrever com `sdd skills sync --targets codex,claude,cursor,devin,opencode,trae,antigravity --dry-run`.
- Valide workflows com `sdd workflow validate standard-sdd --json`.
- Execute recipes determinísticas com `sdd workflow run <id> --input "<texto>" --max-iterations N --json`.
- Consulte `docs/SKILLS.md` e `docs/WORKFLOWS.md`.
## Fluxo mínimo
1. Defina um `<ciclo>` estável para a orquestração.
2. Rode `sdd init "<ciclo>"` antes de criar artefatos de etapa; isso cria `docs/<slug-do-ciclo>/` e `traceability-map.yaml`.
3. `sdd discover --name "<ciclo>"`
4. `sdd risk "<feature>" --name "<ciclo>"`
5. `sdd orchestration "<ideia>" --name "<ciclo>"`
6. Salvar cada etapa em `docs/<slug-do-ciclo>/` com `sdd artifact save` (`recorded` para etapas informativas, `approved` só depois de checkpoint humano).