# 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 via sdd hook
└── 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; `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, e `cursor` usa Cursor Agent. `gemini` continua aceito como alias legado para `antigravity`. `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`. Se estiver ausente, o doctor mostra `login_command` 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.

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` registra hooks de projeto para:

- Bloquear escrita por agents read-only.
- Impedir comandos destrutivos, merge, push e deploy sem gate.
- Validar `TaskCreated`, `TaskCompleted` e `TeammateIdle` em Agent Teams.
- Validar contratos mínimos de artefatos Markdown com `sdd hook artifact-gate`.
- Notificar quando há input/permissão humana pendente.
- Gravar auditoria em `.sdd/events.jsonl`, `.sdd/subagents.jsonl`, `.sdd/task-gates.jsonl` e `.sdd/notifications.jsonl`.

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.
