# SDD client - Claude Code
Use `.claude/commands/workflow.md` para demandas de agent/card/webhook e `.claude/commands/orchestration.md` para fluxo direto. A skill `.claude/skills/orchestration/SKILL.md` mantém o contrato portável; 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.
- Quando o adapter/editor tiver contagem real de uso, chame `sdd <stage>` ou `sdd artifact save` propagando `SDD_USAGE_INPUT_TOKENS`, `SDD_USAGE_CACHED_INPUT_TOKENS`, `SDD_USAGE_OUTPUT_TOKENS`, `SDD_USAGE_REASONING_OUTPUT_TOKENS` e `SDD_USAGE_TOTAL_TOKENS`; o artefato grava `Tokens source: provider-reported`. Para tempo real de geração, propague `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 grava estimativa local de tokens e tempo local do CLI com source explícito.
- Execução real com escrita no workspace exige adapter autorizado. Codex, Claude Code, opencode, Cursor Agent, Devin, Trae e Antigravity têm adapters diretos; provider desconhecido deve gerar 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,kiro,opencode,trae,antigravity --dry-run`.
- Valide workflows com `sdd workflow validate standard-sdd --json` e `sdd workflow validate loop --json`.
- Execute recipes determinísticas com `sdd workflow run <id> --input "<texto>" --max-iterations N --json`.
- Para demandas vindas de agent, card, bot ou webhook, use `sdd workflow run loop --input "<demanda>" --max-iterations 3 --json`.
- Consulte `docs/SKILLS.md`, `docs/WORKFLOWS.md` e `docs/WORKFLOW.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. Para entrada agentic durável, rode `sdd workflow run loop --input "<demanda>" --max-iterations 3 --json`; para fluxo direto, rode `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).