# Clientes SDD

`orchestration` e o nome canônico do fluxo completo. `orchestrator` continua disponível apenas como alias legado para não quebrar projetos existentes.

Guia prático por programa/editor: [`docs/PROGRAMAS.md`](PROGRAMAS.md). Use este arquivo para entender as superfícies geradas; use o guia de programas para copiar comandos e configurar Codex, Claude Code, Cursor, opencode, Devin, Trae, Antigravity, Zed/ACP e MCP.

## Comandos

```bash
sdd clients list
sdd clients doctor
sdd clients sync --targets all
sdd orchestration "<ideia>"
sdd diagram doctor --name "<ciclo>"
sdd diagram attach --name "<ciclo>" --stage idea|prd|techspec --file <arquivo.html|svg|excalidraw> --title "<título>" --source "<origem>"
sdd workflow run agentic-sdd-loop --input "<demanda>" --json
sdd acp serve --root .
sdd acp doctor --root . --json
```

## 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. Quando um adapter/editor tiver contagem real de uso, deve chamar `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. 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`, `claude --print`, `opencode run`, `cursor agent --print`, `devin --print`, `trae-cli run` e `agy --prompt` para geração/regeneração de artefatos. Execução real de tasks que edita o workspace usa os adapters explícitos de Codex, Claude Code, opencode, Cursor Agent, Devin, Trae e Antigravity; provider desconhecido deve gerar handoff ou falhar antes de executar o client.

## Superficies suportadas

| Cliente | Superficie ativa | Observação |
|---|---|---|
| CLI | `sdd orchestration` | Harness determinístico para todos os produtos. |
| Codex | `AGENTS.md`, `.codex/agents/`, `.codex/sdd-model-routing.toml`, `.agents/agents/sdd-orchestrator/AGENT.md`, `.agents/skills/orchestration/SKILL.md`, `.agents/skills/<stage>/SKILL.md` | Plugin Codex usa `/sdd orchestration`; ACP expõe `sdd-orchestrator`; stage skills cobrem `idea`, `prd`, `techspec`, `tasks`, `execution`, `review`, `memory` e demais etapas. |
| Claude Code | `CLAUDE.md`, `.claude/model-routing.yaml`, `.claude/skills/orchestration/SKILL.md`, `.claude/skills/<stage>/SKILL.md`, `.claude/commands/orchestration.md`, `.claude/commands/agentic-sdd-loop.md`, `.claude/commands/diagram.md` | `agentic-sdd-loop` inicia o recipe durável; `/diagram` gera/anexa companions visuais; commands continuam como fallback quando a skill da etapa não carregar. |
| opencode | `AGENTS.md`, `.opencode/model-routing.yaml`, `.opencode/commands/`, `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/` | `/agentic-sdd-loop` chama `sdd workflow run agentic-sdd-loop`; `/orchestration` chama `sdd orchestration`; stage skills vivem em `.opencode/skills/<stage>/SKILL.md` e comandos propagam `SDD_PROVIDER=opencode`. |
| Cursor | `AGENTS.md`, `.cursor/model-routing.yaml`, `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/skills/` | Rules, slash commands, subagent e skill nativos reforcam o fluxo SDD; `.cursor/commands/diagram.md` delega para o contrato de diagramas. |
| Devin | `AGENTS.md`, `.devin/config.json`, `.devin/rules/`, `.devin/agents/`, `.devin/skills/`, `.devin/workflows/`, `.agents/agents/sdd-orchestrator/AGENT.md`, `.agents/skills/orchestration/SKILL.md` | `.devin/workflows/agentic-sdd-loop.md` é o playbook de entrada; `.devin/workflows/<stage>.md` e `.devin/skills/<stage>/SKILL.md` cobrem fallback e skill por etapa. |
| Antigravity | `AGENTS.md`, `.agents/agents/sdd-orchestrator/AGENT.md`, `.agents/rules/sdd.md`, `.agents/skills/orchestration/SKILL.md`, `.agents/skills/<stage>/SKILL.md` | Workspace Rule + skills compartilhadas descrevem o loop e seus gates. |
| Trae | `AGENTS.md`, `.trae/commands/`, `.trae/rules/`, `.trae/skills/orchestration/SKILL.md`, `.trae/skills/<stage>/SKILL.md` | `.trae/commands/agentic-sdd-loop.md` inicia o recipe; stage skills e commands por etapa usam o CLI como harness determinístico. |

## Paridade de Stage Skills

Todo client com suporte a skills recebe `SKILL.md` para `discover`, `risk`, `idea`, `prd`, `techspec`, `tasks`, `refinement`, `execution`, `adr`, `review` e `memory`. As skills instruem a usar `sdd <stage>`, preservar `docs/<slug-da-orquestracao>/`, atualizar `traceability-map.yaml` via artifact store e respeitar checkpoints humanos quando a etapa exigir aprovação.

Os commands por etapa permanecem como fallback explícito: se a skill/subagent não existir ou não carregar na sessão, o command manda seguir o adapter e delegar estado, persistência e validação ao CLI `sdd`. `sdd clients doctor --strict`, `sdd capabilities doctor --targets all` e `sdd skills doctor --strict` validam essa cobertura.

## Agentic SDD Loop

O módulo `agentic-sdd-loop` padroniza o começo de uma demanda para todos os agents. Ele não troca o fluxo SDD por uma automação sem freios; ele chama o planning loop durável, grava status em `.sdd/workflows/`, respeita o checkpoint de PRD e deixa a execução/review/memory como pós-planejamento supervisionado.

Superfícies gerenciadas:

- `.agents/skills/orchestration/SKILL.md` para Codex/Antigravity e skills compartilhadas;
- `.claude/commands/agentic-sdd-loop.md` para Claude Code;
- `.devin/workflows/agentic-sdd-loop.md` para Devin;
- `.opencode/commands/agentic-sdd-loop.md` para opencode;
- `.trae/commands/agentic-sdd-loop.md` para Trae.

Documentação operacional: `docs/AGENTIC-SDD-LOOP.md`.

## Diagramas

As superfícies gerenciadas expõem `/diagram` ou workflow equivalente para contexto livre, `attach` e `doctor`. O comando deve delegar para `artifact-diagrams` e para o CLI determinístico: Mermaid/Excalidraw permanece no Markdown; `diagram-design` entra apenas como companion HTML/SVG em `docs/<slug>/assets/diagrams/`.

## ACP Agents

`sdd acp serve --root .` expõe o Agent Client Protocol v1 por stdio. No v1 existe uma sessão ACP para o agente principal `sdd-orchestrator`; subagents continuam como papéis internos do fluxo SDD e aparecem no manifesto, mas não viram sessões ACP separadas.

Contrato canônico:

- `.agents/agents/sdd-orchestrator/AGENT.md` é a superfície instalada;
- `templates/client-agents/sdd-orchestrator.md` é o template fonte do pacote;
- MCP permanece read-only e derivado, com `sdd_context_bundle`, `sdd_agents_manifest`, `sdd://context-bundle/{orchestration}/{stage}` e `sdd://agents/sdd-orchestrator`;
- sessões ACP são cache em `.sdd/acp/sessions/<session_id>.json`;
- escrita de código continua bloqueada até o estado SDD estar pronto para execução e checkpoints humanos continuarem respeitados.

## Ergonomia OpenCode

A superfície OpenCode incorpora padrões úteis do `opencode-workflow` sem trocar o contrato SDD:

- `/verify-changes` roda gates fail-fast com `sdd ci`, `sdd eval orchestration`, `sdd quality report` e handoff para review.
- `/team-review` e `/team-execution` tornam review adversarial e paralelização explícitos, com fallback sequencial quando subagents não estiverem disponíveis.
- `/security-audit` e `/test-design` são wrappers finos para as skills `security-privacy` e `test-strategy`.
- `/fast-lane` substitui a ideia de `/rapid` por uma rota de baixo risco que exige `sdd risk`, artifact store e verificação.
- `.opencode/skills/` materializa `code-review`, `security-privacy`, `test-strategy`, `architecture-deepening`, `execution-discipline` e `release-readiness` a partir das fontes SDD.
- `.opencode/plugins/` traz guardrails opt-in para bloquear secrets, sugerir verificação e educar paralelização sem rodar auto-format automático.

## 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 invocacao direta for util;
- 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 --write
```

Com `--name "<orquestracao>"`, a recomendação e salva em `docs/<slug>/00-context-recommendations.md`.
