# Camada de orquestração SDD para agentes de código
Adapta um sistema multiagente Spec-Driven Development (Project Discovery → Memória) para CLI, Codex, Claude Code, opencode, Cursor, Devin, Antigravity e Trae. O fluxo inclui Project Discovery, Risk Classification, as etapas de produto/engenharia, **Refinement** opcional entre Tasks e Execution e **ADR pós-execução** para registrar decisões arquiteturais confirmadas, criadas ou alteradas pela implementação.
O nome canônico do fluxo completo é `orchestration`. `orchestrator` continua aceito apenas como alias legado.
## Instalação
Instale o CLI nativo no repositório da camada:
```
cargo install --path .
```
O binário `sdd` funciona em Windows, Linux e macOS. Para **compilar** no Windows é
preciso um linker C: ou o toolchain MSVC (Visual Studio Build Tools, recomendado) ou,
se usar o toolchain `x86_64-pc-windows-gnu`, um MinGW-w64 com `dlltool`/`gcc` no `PATH`
(ex.: WinLibs). Linux/macOS já trazem o linker pelo `build-essential`/Xcode CLT.
Inicialização recomendada dentro de outro projeto:
```
cd /caminho/do/projeto
sdd init
sdd doctor
sdd clients doctor
sdd init "minha-orquestracao"
```
Durante `sdd init`, se `codegraph` estiver disponível no `PATH` e ainda não houver `.codegraph/`, o CLI executa `codegraph init -i .` em modo best-effort. Sem CodeGraph instalado, a instalação continua normalmente com fallback `git`/`rg`.
Também é possível instalar apontando para outro diretório:
```
sdd init --root /caminho/do/projeto
sdd install /caminho/do/projeto --preset generic
```
Para atualizar um projeto que já tem `.sdd/` instalado com as mudanças mais recentes do pacote:
```
sdd update
sdd clients doctor
```
`sdd upgrade` é alias de `sdd update`. O update mescla `AGENTS.md` e `CLAUDE.md` quando já existem no projeto, inserindo ou atualizando um bloco gerenciado do SDD sem apagar instruções locais; também atualiza as superfícies gerenciadas pelo pacote (`.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.devin/`, `.opencode/`, `.trae/` e `.sdd/`), preserva `sdd.config.yaml` por padrão e mantém artefatos em `docs/<orquestracao>/`. Use `--update-config --preset <preset>` apenas quando quiser regenerar a configuração a partir de um preset.
Presets disponíveis em `.sdd/presets/` no projeto instalado: `generic`, `frontend-react`, `backend-node`, `hono-api`, `python-api`, `rust-api`, `monorepo` e `infra`.
`python-api` é um preset para projetos alvo FastAPI; a camada SDD em si continua usando somente o binário Rust `sdd` para regras determinísticas, hooks e validações locais.
O layout padrão é **compact**: somente os arquivos que as ferramentas precisam descobrir ficam na raiz; o restante vai para `.sdd/`.
```
seu-projeto/
├── AGENTS.md
├── CLAUDE.md
├── sdd.config.yaml
├── .agents/
├── .claude/
├── .codex/
├── .cursor/
├── .devin/
├── .opencode/
├── .trae/
└── .sdd/
├── adapters/
├── clients/
├── docs/
├── presets/
├── schemas/
└── templates/
```
Use `--layout flat` somente para desenvolvimento da própria camada ou instalações legadas que já esperam `schemas/`, `templates/`, `adapters/` e `presets/` na raiz.
Use `--with-ci` para instalar também `tests/` e `.github/workflows/sdd.yml` no projeto alvo. Use `--with-examples` para copiar `examples/`.
Por padrão o installer **não** copia `.claude/skills/orchestration-plugin`, porque os comandos de projeto já cobrem o fluxo e isso evita duplicidade no autocomplete. Use `--with-claude-plugin` apenas quando quiser testar o plugin Claude empacotado dentro do projeto alvo.
Para Claude Code, copie a pasta `.claude/` e o arquivo `CLAUDE.md` para a raiz do seu projeto:
```
seu-projeto/
├── .claude/
│ ├── agents/ # os subagents (um por etapa; refinement é opcional)
│ ├── commands/ # /sdd + etapas + team/automation helpers
│ ├── skills/ # bdd-gherkin, code-review e skills SDD complementares
│ ├── rules/ # princípios, importados pelo CLAUDE.md
│ └── settings.json # permissões, Agent Teams e hooks vazios por padrão
└── CLAUDE.md
```
Para Codex, mantenha `AGENTS.md`, `.codex/agents/`, `.codex/rules/` e `.agents/skills/` na raiz. Arquivos de suporte ficam em `.sdd/`.
Para Cursor, use `AGENTS.md`, `.cursor/model-routing.yaml`, `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/` e `.cursor/skills/`. Para opencode, use `AGENTS.md`, `.opencode/commands/` e `.opencode/agents/`. Para Devin, use `AGENTS.md`, `.devin/config.json`, `.devin/rules/`, `.devin/agents/`, `.devin/skills/`, `.devin/workflows/` e `.agents/skills/`. Para Trae, use `AGENTS.md`, `.trae/commands/`, `.trae/rules/` e `.trae/skills/`. Para Antigravity, use também `.agents/rules/sdd.md`.
Gere ou valide essas superfícies com:
```
sdd clients list
sdd clients sync --targets all
sdd clients doctor
```
Opcionalmente, use `plugins/orchestration/` como plugin Codex repo-local: ele empacota a skill central de orquestração SDD e pode ser publicado num marketplace local quando você quiser distribuí-lo. Use `plugins/design/` quando quiser um plugin Codex repo-local para design minimalista moderno ancorado na stack real do projeto.
Se você editar os arquivos de agente/comando direto no disco, reinicie a sessão do Claude Code para carregá-los (ou crie-os pela interface `/agents`). Rode `/memory` (built-in) para conferir quais instruções foram carregadas e `/agents` para gerenciar os subagents.
## Uso
- **Fluxo completo:** `/sdd orchestration "quero um botão de exportar CSV no relatório"`. O fluxo delega cada etapa ao subagent certo e PARA nos checkpoints (após PRD, após Tech Spec, após Refinement quando houver risco, antes do merge/deploy) para sua aprovação. `/sdd orchestrator` é alias legado.
- **Preparação do projeto:** `/sdd discover` gera Project Discovery; `/sdd risk "<feature>"` classifica risco; `/sdd doctor` valida se a instalação/configuração está pronta.
- **Dry-run:** `/dry-run "<feature>"` simula Project Discovery, risco, PRD, Tech Spec, Tasks e Refinement sem tocar código.
- **Etapa individual:** por exemplo `/prd` (usa a visão mais recente), `/techspec`, `/tasks`, `/refinement` (opcional — condensa o backlog num documento de grooming enxuto), `/execution TASK-003`, `/review` (revisa o diff atual), `/memory`.
- **Agent Teams:** `/team-techspec`, `/team-execution`, `/team-review`.
- **Automations:** `/automation` para planejar acompanhamento de PR, CI, deploy, Jira ou Slack.
Por padrão, cada orquestração deve ter um fallback local em `docs/<slug-da-orquestracao>/`. Esse diretório guarda os artefatos aprovados/registrados e o `traceability-map.yaml` quando Jira/Confluence/etc. ainda não estão configurados por completo.
## Notas de design
Cada subagent roda em seu próprio contexto, com ferramentas no escopo do papel: as etapas de planejamento são read-only para código e só podem gravar o artefato canônico do próprio stage; `execution` tem escrita e bash; `review` tem bash de leitura (diff/test), com os comandos seguros pré-aprovados em `settings.json`. Os modelos seguem a carga cognitiva em `sdd.config.yaml` e nos arquivos de roteamento dos clients: etapas leves usam modelos médios, enquanto `techspec`, `execution` e `review` usam modelos/efforts mais fortes.
As skills carregam sozinhas pela descrição: `bdd-gherkin` para critérios de aceite, `code-review` para merge, `traceability` para links entre artefatos, `checkpoints` para gates humanos, `integrations` para Jira/Confluence/Bitbucket e `memory` para o fechamento do ciclo.
Para uso em qualquer projeto, a camada agora também inclui `project-discovery`, `risk-classifier`, `artifact-schemas`, `test-strategy`, `release-readiness`, `security-privacy`, `data-contracts` e `repo-adapter`.
## Configuração por projeto
Cada projeto deve ter um `sdd.config.yaml`, criado a partir de `.sdd/sdd.config.example.yaml`. Ele declara stack, sistemas, paths, comandos, políticas de qualidade, regras de risco e adapters. Rode:
```
sdd doctor
```
## Providers, segurança e memória
O CLI aceita seleção determinística de provider sem chamar rede por padrão:
```
sdd providers list
sdd providers doctor --json
sdd orchestration --provider claude --model claude-sonnet-4-6 --effort high --dry-run "minha ideia"
sdd prd --provider custom --model local-test --effort medium --name "meu ciclo" "entrada"
```
A precedência é: flags (`--provider`, `--model`, `--effort`, `--offline`), env (`SDD_PROVIDER`, `SDD_MODEL`, `SDD_EFFORT`/`SDD_REASONING_EFFORT`, `SDD_OFFLINE`), modelos declarados nos agents/routings do projeto, `sdd.config.yaml` e defaults embutidos. O override do agent só é aplicado quando o modelo existe no catálogo `models` do provider. Cada provider também declara `auth_methods` seguros: `claude` aceita Claude Code ou API, `codex` aceita Codex CLI ou API, `opencode` usa o CLI/credenciais Go-Zen, `antigravity` usa o Antigravity CLI (`agy`) ou Google AI API, `cursor` usa Cursor Agent, e `rig` é um adapter opcional via `rig-core` para roteamento futuro de providers/tools, mantendo auth nas env vars do provider real. `gemini` continua aceito como alias legado para `antigravity`; `rig-core` continua aceito como alias de `rig`. `providers list` usa detecção rápida de PATH/env; `providers doctor` valida login real com comandos como `agy models`, `cursor agent status`, `claude auth status`, `opencode providers list` ou `codex login status` e env vars como `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` ou `RIG_PROVIDER_API_KEY` para Rig. Se estiver ausente, o doctor mostra `login_command` quando houver, como `agy`, `cursor agent login`, `claude auth login`, `opencode providers login` ou `codex login`. Tokens ficam apenas em variáveis de ambiente; `providers doctor` mostra método, origem e `present: true/false`, mas nunca imprime valores. Logs, artifacts e eventos passam pelo scrubber central antes de registrar comandos ou mensagens que possam conter API keys.
No TUI, a seleção de provider aparece antes da lista de orquestrações. Use `←/→` para modelo inicial e `[`/`]` para effort inicial. Gerar uma etapa ou apertar `r` para regenerar tenta usar o adapter direto do provider e mostra o trace; os adapters diretos atuais cobrem `codex exec`, `claude --print`, `opencode run`, `cursor agent --print` e `agy --prompt`, todos salvando o Markdown via `sdd artifact --root <root> save ...`. Execução real de tasks que edita o workspace permanece restrita ao adapter Codex nesta versão.
O MCP Rust nativo permanece em stdio e expõe tools/resources/prompts read-only. A feature opcional `mcp-rmcp` compila metadata tipada com `rmcp`, e a tool/resource `sdd_runtime_adapters` (`sdd://runtime/adapters`) informa se `rmcp` e `rig-core` estão presentes no binário atual.
A memória incremental é derivada e reconstruível:
```
sdd memory learn --name "meu ciclo"
sdd memory status --json
```
O índice padrão é `.sdd/memory/learnings.jsonl`, com `source_artifact` e `source_hash` apontando para arquivos em `docs/<slug>/`. Ele é cache auditável, não fonte primária.
A Project Intelligence Layer amplia esse contrato com Context Packs por etapa e índices derivados em `.sdd/intelligence/`:
```
sdd intelligence learn --name "meu ciclo"
sdd intelligence learn --all
sdd intelligence status --json
sdd intelligence health --json --fail-on high
sdd context build --name "meu ciclo" --stage execution --write
sdd optimize status --json
```
`sdd context build` monta um pacote auditável para o stage, citando fontes incluídas, excluídas, obsoletas e conflitos. Ele considera automaticamente a orquestração atual, fontes globais e histórico em `docs/*/traceability-map.yaml`, com ranking para priorizar a feature em andamento. `sdd intelligence learn/status/health` ajuda a reconstruir aprendizados, inspecionar obsolescência e verificar sinais objetivos de saúde, sem substituir `docs/<slug>/` nem `traceability-map.yaml` como fonte canônica.
O Optimization Wrapper é opcional e provider-neutral: detecta CodeGraph, RTK e Caveman quando presentes, expõe fallback explícito e injeta um Context Handoff curto em `sdd context build`. Use `sdd optimize compress --kind trace|handoff|memory-derived` para compactar relato operacional sem reescrever PRD, Tech Spec, Tasks, ADR ou Review.
Os contratos de artefato vivem em `.sdd/schemas/artifact-sections.json`, e podem ser validados com:
```
sdd validate-artifact techspec docs/minha-techspec.md
```
O projeto e o artifact store local são criados e atualizados com a CLI:
```
sdd init
sdd init "exportacao-csv"
sdd artifact save "exportacao-csv" prd --file prd.md --state approved
sdd artifact status "exportacao-csv"
```
A documentação completa de operação está em `docs/USAGE.md`, `docs/PROJECT-INTELLIGENCE.md`, `docs/PROJECT-ONBOARDING.md`, `docs/PACKAGING.md`, `docs/ARTIFACTS.md`, `docs/ARTIFACT-STORE.md`, `docs/AUTOMATIONS.md` e `docs/ADAPTERS.md`.
`docs/CLIENTS.md` descreve as superfícies por cliente e o comando `sdd context recommend --write`, que usa os sinais do discovery para sugerir novas skills específicas de tecnologia, rules, seções de `AGENTS.md` e deltas de `CLAUDE.md`.
## Distribuição
- `src/main.rs`: CLI Rust `sdd`, fonte canônica para doctor, CI, artifact store, risco, validação, scaffolds de etapa e hooks.
- `build.rs`: empacota os recursos SDD no binário para `sdd init`, `sdd install` e `sdd update` funcionarem fora do repositório da camada.
- `.sdd/presets/`: configurações iniciais por tipo de projeto.
- `.sdd/adapters/`: mapeia Jira/Confluence/Bitbucket, GitHub, GitLab, Linear/Notion e Markdown-only.
- `.sdd/clients/`: documenta superfícies por cliente geradas por `sdd clients sync`.
- `examples/export-csv-feature/`: exemplo completo de feature.
- `cargo test`: regressão do CLI, artifact store, risk classifier e hooks.
- `.github/workflows/sdd.yml`: workflow de validação.
- `VERSION` e `CHANGELOG.md`: versionamento da camada.
## Agent Teams
`settings.json` habilita `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` e `teammateMode: auto`. Use teams apenas quando houver trabalho independente:
- TechSpec complexa: `architecture-reviewer`, `security-reviewer`, `data-contract-reviewer`, `qa-strategist`.
- Execução paralela: `frontend-implementer`, `backend-implementer`, `test-implementer`, com ownership explícito de arquivos.
- Review não trivial: `security-reviewer`, `performance-reviewer`, `test-reviewer`, `architecture-reviewer`, `data-contract-reviewer`.
O lead sintetiza os pareceres e preserva o checkpoint humano; teammates não aprovam merge, deploy, PRD ou Tech Spec.
## Hooks e plugin
`.claude/settings.json` mantém os eventos de hook declarados, mas vazios por padrão. O objetivo é não interromper loops automáticos com `PreToolUse`, `TaskCreated`, `TaskCompleted` ou gates pós-escrita enquanto o agente está trabalhando. Guardrails determinísticos continuam disponíveis como comandos explícitos de CLI/CI:
- `sdd hook write-guard`
- `sdd hook bash-guard`
- `sdd hook task-gate`
- `sdd hook artifact-gate`
- `sdd hook trace-log`
- `sdd hook subagent-audit`
- `sdd hook notify`
Use esses hooks quando o harness quiser uma checagem deliberada ou um modo estrito. No fluxo automático padrão, checkpoints humanos continuam acontecendo nas etapas de produto/release, não como bloqueio de ferramenta a cada ação do agente.
O diretório `.claude/skills/orchestration-plugin/` empacota a mesma política como plugin de projeto do Claude Code. Ele é útil para desenvolver/distribuir o plugin, mas em projetos instalados via `sdd install` o caminho canônico é usar `/sdd ...`.
O diretório `plugins/orchestration/` empacota a política como plugin Codex validado, sem hooks no manifest porque hooks ainda não são aceitos pelo validador de plugin Codex usado neste scaffold. O diretório `plugins/design/` adiciona uma skill e comandos Codex para brief e review de design minimalista moderno, mantendo o handoff preso à tecnologia descoberta no projeto.
## Automations
Use esta ordem de preferência:
1. Channels/webhooks quando CI, Jira, Slack, Bitbucket ou deploy puderem empurrar eventos.
2. Scheduled tasks (`/loop` ou CronCreate) para polling temporário de PR/CI/deploy.
3. Hooks para regras locais determinísticas antes/depois de tool use, subagents e Agent Teams.
Scheduled tasks são de sessão; para automação durável, mova o evento para CI, rotina externa ou orquestrador durável.
## Validação da camada
Rode:
```
cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release
sdd ci
```
Esses comandos validam formatação, lint, testes Rust unitários/de integração, JSONs, schemas, hooks, doctor e smoke checks do CLI.