# Clientes SDD
`orchestration` é o nome canônico do fluxo completo. `orchestrator` continua disponível apenas como alias legado para não quebrar projetos existentes.
## Comandos
```bash
sdd clients list
sdd clients doctor
sdd clients sync --targets all
sdd orchestration "<ideia>"
```
## Provider selection
Todas as superfícies devem delegar para o CLI quando precisarem de provider/model/effort:
```bash
sdd orchestration --provider codex --model gpt-5.5 --effort xhigh "<ideia>"
sdd providers doctor --json
```
A precedência é flags, env (`SDD_PROVIDER`, `SDD_MODEL`, `SDD_EFFORT`, `SDD_OFFLINE`), `sdd.config.yaml` e defaults. `sdd providers doctor --json` identifica métodos seguros de autenticação, modelos disponíveis, efforts, roteamento por etapa, budget de tokens, limites declarados em `usage_limits`, janela de contexto e pricing por modelo quando configurados. Métodos com `check_command` diferenciam CLI instalado de sessão válida e expõem `login_command` quando faltar autenticação, sem revelar tokens. Clientes não devem copiar tokens para prompt, Markdown, traceability ou memory; use apenas nomes de env vars (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc.) e deixe o CLI redigir eventos. Consumo exibido no TUI vem de eventos incrementais do adapter: real quando o provider reporta `usage` e estimado localmente quando não há telemetria. Custo depende de `models[].pricing`; sem isso, o TUI informa que preço não está configurado. Adapters novos devem emitir `Trace`, `Context`, `Usage` e `Finished` para manter a experiência de coding agent consistente.
Adapters diretos no TUI cobrem `codex exec --json`, `claude --print`, `opencode run`, `cursor agent --print`, `devin --print`, `trae-cli run` em diretório temporário e `agy --prompt` para geração/regeneração de artefatos. Execução real de tasks que edita o workspace continua limitada ao adapter Codex nesta versão; demais clients devem falhar explicitamente antes de mutar arquivos quando não houver adapter de escrita autorizado.
## Proveniência
Eventos de geração e execução precisam registrar o agent real usado pelo harness. Valores canônicos atuais: `codex`, `claude-code`, `opencode`, `cursor-agent`, `devin`, `trae-agent`, `antigravity`, `sdd-harness` e `unsupported-workspace-execution`.
Para modelo, o contrato separa:
- `selected_model`: modelo resolvido pelo SDD e enviado ao adapter.
- `observed_model`: modelo reportado pelo provider/CLI em metadata estruturada.
- `confidence: "unreported"`: provider sem metadata confiável; não inferir modelo observado a partir da configuração.
Veja `docs/QUALITY-OBSERVABILITY.md` para logs, checks de qualidade e matriz completa de adapters.
## Skills e workflows portáveis
O catálogo de skills e a DSL de workflows são contratos compartilhados por todos os clients.
| Recurso | Fonte canônica | CLI |
|---|---|---|
| Catálogo de skills | `templates/skill-catalog.yaml` | `sdd skills list|doctor|sync|recommend|validate` |
| Skills independentes | `.agents/skills/<id>/SKILL.md` | `sdd skills validate <path>` |
| Mirrors de plugin | `plugins/orchestration/skills/<id>/SKILL.md` | `sdd skills doctor --strict` |
| Workflows embutidos | `templates/workflows/*.yaml` | `sdd workflow list|validate|run|status` |
| Relatórios de workflow | `.sdd/workflows/<id>.json` | `sdd workflow status <id> --json` |
Targets de sync de skills:
| Target | Diretório |
|---|---|
| Codex e Antigravity | `.agents/skills/` |
| Claude Code | `.claude/skills/` |
| Cursor | `.cursor/skills/` |
| Devin | `.devin/skills/` |
| opencode | `.opencode/skills/` |
| Trae | `.trae/skills/` |
`standard-sdd` pode ser usado como workflow determinístico de planejamento até gate PRD; `deep-execution-review`, `discovery-skill-hardening` e `bugfix-diagnostic-loop` cobrem loops operacionais. Nenhum workflow pode autoaprovar checkpoint humano.
Referências completas: `docs/SKILLS.md` e `docs/WORKFLOWS.md`.
## Superfícies suportadas
| Cliente | Superfície ativa | Observação |
|---|---|---|
| CLI | `sdd orchestration` | Harness determinístico para todos os produtos. |
| Codex | `AGENTS.md`, `.codex/agents/`, `.codex/sdd-model-routing.toml`, `.agents/skills/orchestration/SKILL.md` | Plugin Codex usa `/sdd orchestration`. |
| Claude Code | `CLAUDE.md`, `.claude/model-routing.yaml`, `.claude/skills/orchestration/SKILL.md`, `.claude/commands/orchestration.md` | `orchestrator` e wrapper legado. |
| opencode | `AGENTS.md`, `.opencode/model-routing.yaml`, `.opencode/commands/`, `.opencode/agents/` | `/orchestration` chama `sdd orchestration`. |
| Cursor | `AGENTS.md`, `.cursor/model-routing.yaml`, `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/skills/` | Rules, slash commands, subagent e skill nativos reforçam o fluxo SDD. |
| Devin | `AGENTS.md`, `.devin/config.json`, `.devin/rules/`, `.devin/agents/`, `.devin/skills/`, `.devin/workflows/`, `.agents/skills/orchestration/SKILL.md` | Configura import, regra local, custom subagent, skills e workflows por etapa. |
| Antigravity | `AGENTS.md`, `.agents/rules/sdd.md`, `.agents/skills/orchestration/SKILL.md` | Workspace Rule + skills compartilhadas. |
| Trae | `AGENTS.md`, `.trae/commands/`, `.trae/rules/`, `.trae/skills/orchestration/SKILL.md` | Superfície nativa reforça `sdd init` e persistência em `docs/<slug>/`. |
## Discovery e contexto incremental
Depois de `sdd discover`, o artefato `00-project-discovery.md` inclui `Recomendações de skills e regras`. Essa seção deve orientar:
- novas skills em `.agents/skills/<nome>/SKILL.md`;
- espelho Claude em `.claude/skills/<nome>/SKILL.md` quando a invocação direta for útil;
- rules Cursor em `.cursor/rules/<nome>.mdc`, commands em `.cursor/commands/<nome>.md`, subagents em `.cursor/agents/<nome>.md` e skills em `.cursor/skills/<nome>/SKILL.md`;
- rules/skills/subagents/workflows Devin em `.devin/rules/`, `.devin/skills/`, `.devin/agents/` e `.devin/workflows/`;
- rules Antigravity em `.agents/rules/<nome>.md`;
- seções curtas em `AGENTS.md`;
- deltas específicos em `CLAUDE.md`.
Use:
```bash
sdd context recommend
sdd context materialize --name "<orquestracao>"
sdd context materialize --name "<orquestracao>" --json
sdd context materialize --name "<orquestracao>" --write
```
`context recommend` continua cuidando das recomendações determinísticas por tecnologia. `context materialize` revisa boundaries por trecho, imprime o plano por padrão e só aplica blocos gerenciados `sdd-context` com `--write`, preservando conteúdo humano fora dos marcadores.
Com `--name "<orquestracao>"`, o plano contextual é salvo em `docs/<slug>/00-context-recommendations.md` quando aplicado. `AGENTS.md` é a superfície portátil principal; `CLAUDE.md` recebe apenas diferenças específicas de Claude Code; `AGENTS.md` locais aparecem somente em diretórios com boundary claro.