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.

Guia prático por programa/editor: docs/PROGRAMAS.md. Ele cobre Terminal/CLI, Codex, Claude Code, Cursor, opencode, Devin, Trae, Antigravity, Zed/ACP e MCP.

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/, .opencode/agents/, .opencode/skills/ e .opencode/plugins/. 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.

Para comandos e exemplos por programa, veja docs/PROGRAMAS.md.

Gere ou valide essas superfícies com:

sdd clients list
sdd clients sync --targets all
sdd clients doctor
sdd clients doctor --strict
sdd skills doctor --strict
sdd workflow list --json

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.

O adapter GitHub cobre Issues, Projects v2, Pull Requests e Actions mantendo docs/<slug>/traceability-map.yaml como fonte local. Use GitHub App como autenticação principal e GITHUB_TOKEN/GH_TOKEN como fallback de desenvolvimento. O receiver HTTP de webhooks do bot é opcional e só inicia com github.webhook.enabled/porta configurada ou SDD_GITHUB_WEBHOOK_PORT, validando X-Hub-Signature-256. Para registrar ponteiros externos sem editar YAML manualmente:

sdd artifact link "minha orquestração" github \
  --url https://github.com/org/repo/issues/42 \
  --kind issue \
  --id GH-42 \
  --stage idea

O catálogo híbrido de skills vive em templates/skill-catalog.yaml e é operado por sdd skills list|doctor|sync|recommend|validate. Skills SDD continuam no pacote de orquestração; skills independentes e stack-specific ficam em .agents/skills/<id>/SKILL.md e podem ser sincronizadas para Claude, Cursor, Devin, opencode, Trae e Antigravity. Veja docs/SKILLS.md.

Workflows dinâmicos vivem em templates/workflows/*.yaml e são operados por sdd workflow list|validate|run|status. Eles permitem loops determinísticos com orçamento de iteração, evidências, retries e checkpoints humanos sem depender de LangGraph/Rig/Agno/Flue. O módulo agentic-sdd-loop é o recipe de entrada para agents: resolve a demanda, roda o planejamento durável até o primeiro gate e deixa handoff para execução/review/memory supervisionadas. Veja docs/WORKFLOWS.md e docs/AGENTIC-SDD-LOOP.md.

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, devin usa Devin CLI, trae usa Trae Agent CLI mais env vars do provider real, 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; devin-cli, trae-cli e trae-agent continuam aceitos como aliases; 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, devin auth status, trae-cli show-config, 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, devin auth login, trae-cli show-config, 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, devin --print, trae-cli run isolado 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; providers sem escrita explícita falham antes de mutar o workspace.

Os eventos persistidos registram agent como o client/adapter invocado (codex, claude-code, cursor-agent, opencode, devin, trae-agent ou antigravity) e diferenciam selected_model de observed_model: o primeiro vem da resolução SDD/configuração, o segundo só aparece quando o adapter reporta metadata real. Quando o provider não expõe essa informação, o registro fica confidence: "unreported" em vez de tratar o modelo selecionado como fato observado.

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. O MCP também expõe sdd_project_status, sdd_search, sdd_optimize_status, sdd_context_handoff, sdd_context_bundle, sdd_capabilities_status e sdd_agents_manifest para consultas de status, busca, contexto, handoff e agents. Para agentes com MCP, sdd_context_bundle é a superfície principal de leitura antes de gerar ou executar: ele agrega artifact store, Context Pack, trace summary, capabilities, runtime adapters, busca local e recomendações de CodeGraph, mas continua derivado dos artefatos canônicos em docs/<slug>/ e traceability-map.yaml.

O ACP v1 fica disponível como superfície de sessão para editors/clients que falam Agent Client Protocol:

sdd acp serve --root .
sdd acp doctor --root . --json
sdd acp config --targets zed,all --dry-run

O agente ACP inicial é sdd-orchestrator. Sessões são cache em .sdd/acp/sessions/<session_id>.json; artifacts, checkpoints, traceability e validações continuam canônicos no CLI/Markdown.

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 context materialize --name "meu ciclo"
sdd context materialize --name "meu ciclo" --write
sdd context materialize --name "meu ciclo" --local-agents --max-boundaries 3 --write
sdd optimize status --json
sdd diagram doctor --name "meu ciclo"
sdd diagram attach --name "meu ciclo" --stage prd --file docs/meu-ciclo/assets/diagrams/jornada.html --title "Jornada principal" --source "02-prd.md"
sdd skills doctor --strict
sdd skills sync --targets codex,claude,cursor,devin,opencode,trae,antigravity --dry-run
sdd workflow list --json
sdd workflow validate standard-sdd --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.

sdd context materialize detecta perfis de contexto reais do projeto, propõe regras operacionais por trecho e, por padrão, mostra plano/diff sem tocar arquivos. Com --write, ele atualiza apenas blocos gerenciados sdd-context em AGENTS.md, CLAUDE.md e salva docs/<slug>/00-context-recommendations.md; AGENTS.md locais só são planejados/criados com --local-agents ou quando context_materialization.local_agents: true já estiver configurado.

sdd diagram checa a skill diagram-design, paths de assets e anexa companions HTML/SVG/Excalidraw em docs/<slug>/assets/diagrams/ sem substituir Mermaid no Markdown. sdd skills valida e sincroniza templates/skill-catalog.yaml, incluindo bundles de skill como diagram-design; sdd workflow lista, valida e executa handoffs determinísticos de workflows sem aprovar gates humanos. O workflow embutido standard-sdd equivale ao caminho de planejamento até o primeiro gate; deep-execution-review, discovery-skill-hardening e bugfix-diagnostic-loop cobrem loops de execução, hardening e bugfix.

Eficácia mensurável e avaliação

A camada não promete sucesso absoluto do modelo; ela mede e bloqueia avanço quando o contrato local falha. Use os gates determinísticos antes de avançar execução, review ou memória:

sdd eval stage --name "meu ciclo" --stage techspec --json
sdd eval orchestration --name "meu ciclo" --json
sdd quality report --name "meu ciclo" --json

As avaliações validam seções obrigatórias, rastreabilidade, diagramas, Prompts Agent, estado do traceability-map.yaml e freshness de Context Packs em etapas críticas. Cada execução registra evidência em .sdd/evaluations.jsonl; o motor autônomo usa esse mesmo contrato para bloquear etapas com achados críticos.

Para demandas já aprovadas até Refinement, o motor pode materializar o pós-planejamento sem aprovar release automaticamente:

sdd auto run --real --through review
sdd auto run --real --through memory

--through só atua quando a demanda está em ready_for_exec; PRD, Tech Spec e Refinement continuam exigindo aprovação humana explícita.

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/PROGRAMAS.md, docs/IMPLEMENTACOES-RECENTES.md, docs/SKILLS.md, docs/WORKFLOWS.md, docs/QUALITY-OBSERVABILITY.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, sdd context recommend para recomendações por tecnologia e sdd context materialize para aplicar, de forma revisável e idempotente, blocos sdd-context em AGENTS.md, CLAUDE.md e, por opt-in, arquivos locais por boundary.

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 --all-targets --all-features -- -D warnings
cargo test --locked --all-features
cargo build --release
sdd ci --strict-release
sdd maintenance report

O gate strict/release agrega Rust fmt/clippy/test, sdd health --strict, doctors SDD, bot build/test, docs generate/links/build e checks advisory visíveis. Ferramentas opcionais ausentes aparecem como skipped; achados de advisory aparecem como warn, sem bloquear o caminho obrigatório.