sdd-layer 0.25.3

# Uso com programas e agentes

Este guia mostra como usar o SDD Layer nos principais programas de agente/editor. A regra central é simples: cada programa pode oferecer comandos, skills, subagents, MCP ou ACP, mas o contrato canônico continua no CLI `sdd`, no artifact store `docs/<slug>/`, no `traceability-map.yaml` e nos checkpoints humanos.

## Preparação

Instale ou atualize o SDD no projeto alvo:

```bash
cd /caminho/do/projeto
sdd init
sdd doctor
sdd clients doctor
```

Para atualizar superfícies de programas em um projeto já instalado:

```bash
sdd update
sdd clients sync --targets all --dry-run
sdd clients doctor --strict
```

Use `--dry-run` primeiro quando houver mudanças locais nos diretórios `.agents/`, `.claude/`, `.cursor/`, `.devin/`, `.kiro/`, `.opencode/` ou `.trae/`.

## Fluxo recomendado

Para uma demanda nova:

```bash
sdd init "<nome-da-orquestracao>"
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
```

Para o fluxo direto:

```bash
sdd orchestration "<ideia>" --name "<nome-da-orquestracao>"
```

Para preparar contexto antes de execução:

```bash
sdd context build --name "<nome-da-orquestracao>" --stage execution --write
sdd trace summary --orchestration "<nome-da-orquestracao>" --json
```

Antes de avançar para execução, review ou memória:

```bash
sdd eval orchestration --name "<nome-da-orquestracao>" --json
sdd quality report --name "<nome-da-orquestracao>" --json
```

## Mapa rápido

| Programa | Superfície principal | Como iniciar |
|---|---|---|
| Terminal/CLI | `sdd` | `sdd orchestration "<ideia>"` |
| Codex | `AGENTS.md`, `.codex/commands/`, `.codex/agents/`, `.agents/` | use `/agentic-sdd-loop`, peça `/sdd orchestration` ou rode `sdd` no terminal |
| Claude Code | `CLAUDE.md`, `.claude/commands/`, `.claude/skills/` | `/sdd orchestration "<ideia>"` ou `/agentic-sdd-loop "<demanda>"` |
| Cursor | `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/skills/` | use comandos/rules gerados ou rode `sdd` no terminal integrado |
| opencode | `.opencode/commands/`, `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/` | `/agentic-sdd-loop` ou `/orchestration` |
| Devin | `AGENTS.md`, `.devin/config.json`, `.devin/agents/`, `.devin/skills/` | use a skill nativa `agentic-sdd-loop` |
| Kiro | `.kiro/agents/sdd/`, `.kiro/skills/`, `.kiro/steering/`, `.kiro/hooks/`, `.kiro/settings/mcp.json` | selecione `sdd/orchestrator` ou use `/orchestration` |
| Trae | `.trae/commands/`, `.trae/rules/`, `.trae/skills/` | `.trae/commands/agentic-sdd-loop.md` ou `sdd orchestration` |
| Antigravity | `AGENTS.md`, `.agents/rules/`, `.agents/skills/` | Workspace Rule + `sdd workflow run agentic-sdd-loop` |
| Zed/ACP | `sdd acp serve` | `sdd acp config --targets zed --dry-run` |
| MCP clients | `sdd mcp serve` | `sdd mcp config --targets all --root .` |

## Terminal e CLI puro

Use quando não houver editor com agente ou quando quiser execução determinística:

```bash
sdd discover --name "<ciclo>"
sdd risk "<feature>" --name "<ciclo>"
sdd orchestration "<ideia>" --name "<ciclo>"
```

Comandos úteis:

```bash
sdd artifact status "<ciclo>"
sdd trace list --json
sdd trace summary --orchestration "<ciclo>" --json
sdd clients doctor --strict
sdd capabilities doctor --targets all
```

## Codex

Arquivos esperados:

- `AGENTS.md`
- `.codex/config.toml`
- `.codex/agents/`
- `.codex/commands/agentic-sdd-loop.md`
- `.agents/agents/sdd-orchestrator/AGENT.md`
- `.agents/skills/orchestration/SKILL.md`
- `.agents/skills/<stage>/SKILL.md`

Uso recomendado:

```bash
sdd clients sync --targets codex --dry-run
sdd clients doctor
```

No Codex, peça para usar o fluxo SDD canônico:

```text
/agentic-sdd-loop "demanda vinda de card, bot, webhook ou texto livre"
/sdd orchestration "implementar exportação CSV no relatório"
```

Fallback em qualquer sessão Codex:

```bash
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
sdd orchestration "implementar exportação CSV no relatório"
```

## Claude Code

Arquivos esperados:

- `CLAUDE.md`
- `.claude/settings.json`
- `.claude/commands/orchestration.md`
- `.claude/commands/agentic-sdd-loop.md`
- `.claude/skills/orchestration/SKILL.md`
- `.claude/skills/<stage>/SKILL.md`

Uso recomendado:

```text
/agentic-sdd-loop "minha demanda"
/sdd orchestration "minha ideia"
/prd
/techspec
/tasks
/execution T-01
/review
/memory
```

Depois de editar arquivos em `.claude/`, reinicie a sessão do Claude Code para recarregar comandos, skills e permissões.

## Cursor

Arquivos esperados:

- `.cursor/model-routing.yaml`
- `.cursor/rules/sdd.mdc`
- `.cursor/rules/codegraph.mdc`
- `.cursor/commands/`
- `.cursor/agents/sdd-orchestrator.md`
- `.cursor/skills/orchestration/SKILL.md`
- `.cursor/skills/<stage>/SKILL.md`

Uso recomendado:

```bash
sdd clients sync --targets cursor --dry-run
sdd mcp config --targets cursor --root .
```

No Cursor, use as rules/commands geradas quando estiverem disponíveis. Se o comando nativo não aparecer, use o terminal integrado:

```bash
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
```

## opencode

Arquivos esperados:

- `.opencode/model-routing.yaml`
- `.opencode/commands/orchestration.md`
- `.opencode/commands/agentic-sdd-loop.md`
- `.opencode/agents/sdd-orchestrator.md`
- `.opencode/skills/`
- `.opencode/skills/<stage>/SKILL.md`
- `.opencode/plugins/`

Uso recomendado:

```text
/agentic-sdd-loop <demanda>
/orchestration <ideia>
/verify-changes
/team-review
/team-execution
/security-audit
/test-design
/fast-lane
```

Os plugins opencode são guardrails opt-in. Eles ajudam a bloquear secrets, sugerir verificação e lembrar paralelização segura, mas não substituem `sdd ci`, `sdd eval` ou checkpoints humanos.

## Devin

Arquivos esperados:

- `.devin/config.json`
- `.devin/agents/sdd-orchestrator/AGENT.md`
- `.devin/skills/agentic-sdd-loop/SKILL.md`
- `.devin/skills/orchestration/SKILL.md`
- `.devin/skills/<stage>/SKILL.md`
- `.agents/agents/sdd-orchestrator/AGENT.md`

Uso recomendado:

1. Abra uma sessão Devin no projeto.
2. Invoque a skill `agentic-sdd-loop` ou aponte para `.devin/skills/agentic-sdd-loop/SKILL.md`.
3. Passe a demanda e peça para persistir artefatos em `docs/<slug>/`.
4. Exija parada em checkpoints humanos antes de execução, merge ou deploy.

`AGENTS.md` é a regra canônica. `.devin/rules/` e `.devin/workflows/` não são superfícies nativas do Devin CLI. O arquivo `.devin/config.json` mantém imports Claude/Cursor/Windsurf desativados para não duplicar agents e skills instalados pelo SDD.

Fallback:

```bash
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
```

## Kiro

Arquivos esperados:

- `.kiro/agents/sdd/orchestrator.md` e especialistas por etapa/review.
- `.kiro/skills/` com `sdd`, `orchestration`, `agentic-sdd-loop`, etapas e skills do catálogo.
- `.kiro/steering/` com inclusão `always` das regras canônicas `.codex/rules/`.
- `.kiro/hooks/sdd-guardrails.json` no schema agregado `v1`.
- `.kiro/settings/mcp.json` com SDD e CodeGraph, ambos relativos ao workspace.
- `.sdd/clients/kiro-power/` como Power opcional importável.

Uso recomendado:

1. Confie no workspace quando o Kiro solicitar e selecione o custom agent `sdd/orchestrator`.
2. Use `/orchestration`, `/agentic-sdd-loop` ou uma skill de etapa.
3. Mantenha artefatos SDD em `docs/<slug>/`; `.kiro/specs/` pertence ao lifecycle nativo de specs do Kiro e não é o store canônico do SDD.
4. Use o Power somente para distribuição opcional. `sdd install` continua sendo a instalação completa.

Diagnóstico:

```bash
sdd clients sync --targets kiro --dry-run
sdd skills sync --targets kiro --dry-run
sdd clients doctor --strict
sdd capabilities doctor --targets kiro
```

Referência oficial: [custom agents](https://kiro.dev/docs/custom-agents/), [hooks](https://kiro.dev/docs/hooks/), [Powers](https://kiro.dev/docs/powers/), [skills](https://kiro.dev/docs/skills/), [steering](https://kiro.dev/docs/steering/) e [MCP](https://kiro.dev/docs/mcp/configuration/).

## Trae

Arquivos esperados:

- `.trae/commands/agentic-sdd-loop.md`
- `.trae/commands/orchestration.md`
- `.trae/rules/`
- `.trae/skills/orchestration/SKILL.md`
- `.trae/skills/<stage>/SKILL.md`

Uso recomendado:

```text
agentic-sdd-loop <demanda>
orchestration <ideia>
```

Quando a superfície nativa não estiver carregada, use o terminal:

```bash
sdd orchestration "<ideia>"
```

As stage skills cobrem `discover`, `risk`, `idea`, `prd`, `techspec`, `tasks`, `refinement`, `execution`, `adr`, `review` e `memory`. Se uma skill ou subagent não carregar no programa, use o command correspondente ou rode `sdd <stage> "$ARGUMENTS"` no terminal, mantendo artifact store, traceability-map e checkpoints.

## Antigravity

Arquivos esperados:

- `AGENTS.md`
- `.agents/rules/sdd.md`
- `.agents/agents/sdd-orchestrator/AGENT.md`
- `.agents/skills/orchestration/SKILL.md`
- `.agents/skills/<stage>/SKILL.md`

Uso recomendado:

```bash
sdd clients sync --targets antigravity --dry-run
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
```

Antigravity usa `.agents` como contrato compartilhado. Não duplique regras específicas se a mesma orientação já estiver em `AGENTS.md` ou `.agents/rules/sdd.md`.

## Zed e clientes ACP

ACP expõe o agente principal `sdd-orchestrator` por stdio.

Diagnóstico:

```bash
sdd acp doctor --root . --json
```

Configuração Zed:

```bash
sdd acp config --targets zed --dry-run
sdd acp config --targets zed
```

Configuração manual para qualquer cliente ACP:

```bash
sdd acp serve --root /caminho/do/projeto
```

Comportamento esperado:

- `initialize` retorna `protocolVersion: 1` e `agentInfo: sdd-layer`;
- `session/new` exige `cwd` absoluto;
- `session/prompt` aceita texto e `ResourceLink`;
- `session/load` reenvia transcript redigido;
- `session/prompt` transmite plano, chunks, uso e tool updates incrementalmente;
- `session/request_permission` é obrigatório antes de escrita, tool mutável ou checkpoint;
- `session/cancel` propaga cancelamento cooperativo ao turno;
- `session/list` e `session/delete` operam o cache derivado;
- sessões usam `.sdd/acp/sessions/<id>/meta.json` e `events.jsonl`, não a fonte canônica.

Nunca coloque tokens em prompts. Quando o cliente enviar `mcpServers`, o SDD redige valores sensíveis antes de persistir a sessão.

## MCP

MCP é read-only e derivado. Use como superfície principal de leitura para contexto operacional, traces, capabilities, manifesto de agents e handoff. A fonte canônica de decisão continua em `docs/<slug>/` e `traceability-map.yaml`.

Gerar configs locais:

```bash
sdd mcp config --targets all --root .
```

Servir manualmente:

```bash
sdd mcp serve --root .
```

Tools principais:

- `sdd_trace_list`
- `sdd_trace_show`
- `sdd_trace_summary`
- `sdd_artifact_status`
- `sdd_context_build`
- `sdd_context_bundle`
- `sdd_context_handoff`
- `sdd_clients_doctor`
- `sdd_project_status`
- `sdd_readiness_summary`
- `sdd_search`
- `sdd_capabilities_status`
- `sdd_agents_manifest`
- `sdd_optimize_status`
- `sdd_runtime_adapters`

Resources principais:

- `sdd://optimization/status`
- `sdd://capabilities/catalog`
- `sdd://agents/{agent_id}`
- `sdd://runtime/adapters`
- `sdd://artifact/{orchestration}/{stage}`
- `sdd://context/{orchestration}/{stage}`
- `sdd://context-bundle/{orchestration}/{stage}`
- `sdd://handoff/{orchestration}/{stage}`
- `sdd://trace/{run_id}`
- `sdd://auto/status`
- `sdd://workflow/{id}/status`
- `sdd://quality/{slug}`

Antes de gerar ou executar em um client MCP, prefira `sdd_context_bundle` para obter artifact status, Context Pack, trace summary, capabilities, runtime adapters, busca local e recomendações de chamadas CodeGraph. Depois use CodeGraph para mapa estrutural de código, callers/callees, impacto e fonte de símbolos.

Envie `profile: "compact"` por padrão. Use `standard` quando precisar do handoff e de trechos de contexto; `full` deve ser explícito. Respostas perfiladas incluem `schema_version`, `profile`, `truncated`, `next_cursor` e links para resources. Chamadas sem `profile` mantêm a resposta legada nesta versão minor.

MCP não aprova checkpoints, não escreve código e não substitui `docs/<slug>/traceability-map.yaml`.

## Segurança

- Tokens ficam em variáveis de ambiente, nunca em prompt ou Markdown.
- Use `sdd providers doctor --json` para diagnosticar login sem imprimir segredo.
- ACP redige valores sensíveis de `mcpServers` antes de gravar sessão.
- MCP é read-only.
- Escrita de código só deve acontecer quando o fluxo estiver pronto para execução e com adapter autorizado.

## Troubleshooting

| Sintoma | Ação |
|---|---|
| `sdd` não encontrado | Instale com `cargo install --path .` ou ajuste `PATH` para incluir `$HOME/.cargo/bin`. |
| Comando do editor não aparece | Rode `sdd clients sync --targets <programa> --dry-run`, aplique se fizer sentido e reinicie o programa. |
| MCP não conecta | Rode `sdd mcp config --targets all --root .` e confira paths absolutos em `.mcp.json` ou `.cursor/mcp.json`. |
| ACP não conecta | Rode `sdd acp doctor --root . --json` e teste `sdd acp serve --root .` no terminal. |
| `clients doctor --strict` falha por drift | Gere as superfícies com `sdd clients sync --targets all --dry-run`; revise antes de aplicar. |
| Provider deslogado | Rode `sdd providers doctor --json` e use o `login_command` indicado. |
| Artefato não encontrado | Rode `sdd init "<ciclo>"` e confira `docs/<slug>/traceability-map.yaml`. |
| Artifact Store divergente | Rode `sdd artifact doctor "<ciclo>"` e depois `sdd artifact repair "<ciclo>" --dry-run`; aplique somente com `--apply`. |