# Adapters
Adapters traduzem a pipeline SDD para ferramentas específicas sem mudar o fluxo. O contrato separa integração externa, geração de artefatos e execução com escrita no workspace.
## Regra
O fluxo permanece igual. O adapter só define:
- dono do conteúdo;
- dono do estado;
- identificador canônico;
- evento de entrada;
- evento de saída;
- fallback;
- observabilidade.
Provider não é client, e client não é automaticamente adapter de escrita. Um provider pode gerar Markdown válido sem ter permissão para alterar o workspace.
Workflows dinâmicos (`sdd workflow`) também não são runtime adapters externos. Eles são recipes determinísticas em YAML que podem acionar stages, skills, evals, comandos e checkpoints usando o contrato local. LangGraph, Rig, Agno, Flue ou runtimes futuros devem entrar como adapters do mesmo contrato, nunca como substitutos de artifact store, checkpoints e rastreabilidade.
## Tipos de adapter
| Integração externa | mapear artefatos, estados e eventos para Jira, Confluence, GitHub, GitLab, Linear, Notion ou Markdown-only | arquivos `.sdd/adapters/*.yaml` |
| `ArtifactGenerationAdapter` | gerar ou regenerar PRD, Tech Spec, Tasks, Review, Memory e handoffs headless | Codex, Claude Code, opencode, Cursor, Devin, Trae, Antigravity |
| `WorkspaceExecutionAdapter` | executar tasks com escrita real no workspace | Codex nesta versão |
| Workflow DSL | encadear nodes, loops, retries, evidências e gates sem runtime externo | `templates/workflows/*.yaml` |
Adapters de geração podem escrever apenas arquivos temporários controlados pelo harness e persistir o artefato final via `sdd artifact save`. Adapters de execução com escrita precisam declarar autorização explícita e registrar evidências, tentativas, testes e erros em trace.
## Adapters disponíveis
### Integrações externas
| Atlassian | `.sdd/adapters/atlassian.yaml` | Jira, Confluence, Bitbucket, Pipelines, Slack |
| GitHub | `.sdd/adapters/github.yaml` | GitHub Issues, PRs, Actions, Markdown |
| GitLab | `.sdd/adapters/gitlab.yaml` | GitLab Issues, MRs, CI |
| Linear + Notion | `.sdd/adapters/linear-notion.yaml` | Linear para estado, Notion para docs |
| Markdown-only | `.sdd/adapters/markdown-only.yaml` | Repos simples sem suite de produto |
Mesmo com adapters externos, mantenha `docs/<slug-da-orquestracao>/` como fallback mínimo quando `artifact_store.enabled=true`.
### Geração e execução por client
| Codex | `codex exec --json` | permitida | adapter inicial de workspace |
| Claude Code | `claude --print` | bloqueada sem adapter explícito | geração/headless e handoff |
| opencode | `opencode run` | bloqueada sem adapter explícito | geração/headless e handoff |
| Cursor Agent | `cursor agent --print` | bloqueada sem adapter explícito | geração/headless e handoff |
| Devin | `devin --print` | bloqueada sem adapter explícito | geração/headless e handoff |
| Trae Agent | `trae-cli run` isolado | bloqueada sem adapter explícito | usa diretório temporário para não mutar workspace |
| Antigravity | `agy --prompt` | bloqueada sem adapter explícito | geração/headless e handoff |
Quando um provider sem escrita tenta execução real, o resultado correto é falha explícita `unsupported-workspace-execution` antes de qualquer mutação.
## Como escolher
Configure em `sdd.config.yaml`:
```yaml
systems:
work_tracker: github-issues
docs: markdown
repo: github
ci: github-actions
chat: none
```
Depois use `/sdd discover` para confirmar se o adapter reflete a realidade do projeto.
## Matriz esperada
Ao planejar uma integração, entregue:
Não use comentário livre como estado. Não duplique PRD/Tech Spec entre sistemas. Grave ponteiros canônicos e mantenha o arquivo local quando a integração externa ainda não estiver confiável.
## Arquivos de adapter
Cada arquivo em `.sdd/adapters/*.yaml` tem:
- `artifacts`: dono de conteúdo, dono de estado e ID canônico por etapa.
- `events`: eventos que acordam a próxima etapa.
- `fallbacks`: caminho quando a ferramenta não emite evento confiável.
Durante `/sdd discover`, confira se o adapter selecionado em `sdd.config.yaml` bate com a realidade do projeto.
## Observabilidade obrigatória
Todo adapter deve registrar:
- `agent`: client/adapter efetivamente invocado;
- `selected_model`: modelo resolvido e enviado ao adapter;
- `observed_model`: modelo reportado pelo provider/CLI quando existir metadata confiável;
- `confidence`: `observed`, `estimated` ou `unreported`, conforme evidência;
- custo/usage quando o provider reportar ou quando houver estimativa declarada;
- contexto usado, comando executado, resultado e erro redigido;
- ponteiro para artefato salvo, run id e stage.
Não inferir `observed_model` a partir de config. Se o CLI só retorna texto, preserve `selected_model` e registre o observado como não reportado.
## Workflows como contrato de adapter futuro
Um runtime externo que execute workflows deve respeitar a DSL v1:
- validar `version`, `id`, `nodes`, `edges` e `max_iterations`;
- rejeitar action desconhecida, node intermediário sem destino, loop sem limite e checkpoint que tente autoaprovar;
- persistir evidências em `.sdd/workflows/<id>.json` ou evento equivalente;
- usar `docs/<slug>/traceability-map.yaml` como fonte local de verdade;
- delegar aprovação humana para comandos explícitos como `sdd demand approve|reject`.
Enquanto um adapter externo não existir, `sdd workflow run` é o runner canônico.