# SDD Clients
Este diretório documenta as superfícies nativas geradas por `sdd clients sync`.
Para uso operacional por programa/editor, veja [`docs/PROGRAMAS.md`](../docs/PROGRAMAS.md).
## Targets
- `cli`: harness determinístico `sdd`.
- `codex`: `AGENTS.md`, `.codex/config.toml`, `.codex/agents/`, `.agents/agents/` e `.agents/skills/`.
- `claude-code`: `.claude/commands/`, `.claude/agents/` e `.claude/skills/`.
- `cursor`: `.cursor/model-routing.yaml`, `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/` e `.cursor/skills/`.
- `opencode`: `.opencode/commands/`, `.opencode/agents/`, `.opencode/skills/` e `.opencode/plugins/`.
- `devin`: `.devin/config.json`, `.devin/agents/`, `.devin/skills/`, `AGENTS.md`, `.agents/agents/` e `.agents/skills/`; rules/workflows vivem em `AGENTS.md` e skills nativas, não em `.devin/rules/` ou `.devin/workflows/`.
- `kiro`: `AGENTS.md`, `.kiro/agents/sdd/`, `.kiro/skills/`, `.kiro/steering/`, `.kiro/hooks/`, `.kiro/settings/mcp.json` e o Power opcional em `.sdd/clients/kiro-power/`.
- `antigravity`: `.agents/agents/`, `.agents/rules/` e `.agents/skills/`.
- `trae`: `.trae/commands/`, `.trae/rules/` e `.trae/skills/`.
Use `sdd clients doctor` para validar cobertura e `sdd clients sync --targets all` para gerar ou atualizar as superfícies no projeto instalado. Use `sdd diagram doctor --name "<ciclo>"` e `sdd diagram attach --name "<ciclo>" --stage idea|prd|techspec --file <arquivo.html|svg|excalidraw> --title "<título>" --source "<origem>"` para validar e anexar companions em `docs/<slug>/assets/diagrams/`.
Targets com suporte a skills recebem stage skills para `discover`, `risk`, `idea`, `prd`, `techspec`, `tasks`, `refinement`, `execution`, `adr`, `review` e `memory`: `.agents/skills/<stage>/SKILL.md` para Codex/Antigravity, `.claude/skills/<stage>/SKILL.md`, `.cursor/skills/<stage>/SKILL.md`, `.opencode/skills/<stage>/SKILL.md`, `.devin/skills/<stage>/SKILL.md`, `.kiro/skills/<stage>/SKILL.md` e `.trae/skills/<stage>/SKILL.md`. Quando a superfície não carregar skill/subagent, o command equivalente deve delegar ao CLI `sdd` e preservar artifact store, traceability e checkpoints.
## Contrato runtime-agnostic
O core SDD é dono do contrato SDLC: etapas, artifact store, checkpoints, validação, rastreabilidade, registry de providers e comportamento determinístico do CLI. Runtimes como Rig, Flue, LangGraph, Agno ou frameworks futuros são engines/adapters opcionais para execução, roteamento, tools ou composição; eles não substituem `.agents` como contrato canônico nem `docs/<slug>/traceability-map.yaml` como fonte local de verdade.
Quando um runtime adapter estiver ausente, o fallback obrigatório é continuar com Markdown, comandos `sdd`, artifact store local e validações determinísticas. MCP e trace expõem observabilidade derivada/read-only; não aprovam checkpoints nem gravam estado canônico.
## MCP e traces
- `sdd mcp serve --root .`: expõe artifacts, context packs, context bundles, handoffs, readiness summary, traces, capability catalog, manifesto de agents e doctor de clients via MCP stdio read-only.
- `sdd mcp config --targets all --root .`: gera `.mcp.json`, `.cursor/mcp.json`, `.kiro/settings/mcp.json`, regra CodeGraph do Cursor e faz merge das permissões MCP no Claude.
- `sdd_context_bundle`: leitura principal para clients MCP antes de gerar/executar; agrega Context Pack, artifact status, busca local, trace summary, capabilities, runtime adapters e recomendações de CodeGraph.
- `sdd_readiness_summary`: veredito de cockpit `ready | warn | blocked` com MCP doctor, health, auto/workflow status, freshness do cache, capabilities, quality report e próximos comandos recomendados.
- `sdd acp serve --root .`: expõe o agente `sdd-orchestrator` via Agent Client Protocol v1 por stdio.
- `sdd acp doctor --root . --json`: valida a superfície ACP e o manifesto canônico.
- `sdd trace list --json`: lista eventos normalizados de `.sdd/*.jsonl`.
- `sdd trace show <run_id> --json`: mostra árvore de execução por `run_id`/`parent_run_id`.
- `sdd trace summary --orchestration "<nome>" --json`: resume status, tipos de evento, stages e raízes.
- `sdd trace doctor`: valida parse dos arquivos `.sdd/events.jsonl`, `.sdd/subagents.jsonl`, `.sdd/task-gates.jsonl` e `.sdd/runs.jsonl`.
O MCP não substitui o contrato local: a trilha canônica continua nos JSONL redigidos em `.sdd/`. O ACP também é superfície derivada; suas sessões ficam em `.sdd/acp/sessions/` e não substituem artifacts em `docs/<slug>/`.
## Capabilities
`templates/capability-catalog.yaml` é o contrato v2 para recursos portáveis. Ele descreve cada capability, sua fonte canônica, adapters por client, fallback provider-neutral e validações semânticas.
A capability `stage-skills` valida a matriz de skills por etapa em todos os targets compatíveis e detecta drift contra o gerador Rust. Ela complementa `orchestration-skill`: a primeira cobre entrada ou retomada de uma etapa isolada; a segunda cobre o fluxo SDD completo.
- `sdd capabilities list`: lista capabilities e adapters.
- `sdd capabilities doctor --targets all`: valida fonte canônica, cobertura por target, drift gerado e checks semânticos.
- `sdd capabilities sync --targets all`: regenera surfaces conhecidas e copia adapters declarados no catálogo.
- `sdd capabilities recommend --root . --write`: materializa recomendações de skills/rules/MCP/hooks para o projeto atual.
- `sdd clients doctor --strict`: executa `clients doctor` e também `capabilities doctor`.
## Resource adoption map
- Codex: `.agents/skills`, `.codex/config.toml`, plugins, hooks, MCP, automations e worktrees.
- Claude Code: skills, commands compatíveis, subagents, hooks, MCP e settings.
- OpenCode: commands, agents/subagents, skills compatíveis com `.agents`, MCP, plugins e permissions.
- Cursor: rules, skills, subagents, MCP, hooks, CLI/cloud agent.
- Devin: `AGENTS.md`, Knowledge, Playbooks, API/schedules e workflows.
- Trae/Antigravity: rules, skills e commands como adapters portáveis.