# 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`, `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.

## 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.

## 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).
