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.