# 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, Kiro, Antigravity e Trae. O fluxo inclui Project Discovery, Risk Classification, as etapas de produto/engenharia, **Refinement** opcional entre Tasks e Execution, **QA** entre Review e Memory pra validação funcional, e **ADR** como utilitário sem posição fixa — chamado sempre que uma decisão arquitetural real precisar ser travada (obrigatório uma vez logo após a Idea, antes do PRD).
O nome canônico do fluxo completo é `orchestration`. `orchestrator` continua aceito apenas como alias legado.
Guia prático por programa/editor: [`docs/PROGRAMAS.md`](docs/PROGRAMAS.md). Ele cobre Terminal/CLI, Codex, Claude Code, Cursor, opencode, Devin, Kiro, 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/`, `.kiro/`, `.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/
├── .kiro/
├── .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` nem bundles Codex repo-locais em `plugins/`, porque os comandos e skills 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 CLI, use `AGENTS.md`, `.devin/config.json`, `.devin/agents/`, `.devin/skills/` e `.agents/skills/`; `.devin/rules/` e `.devin/workflows/` não são superfícies nativas. Para Kiro, use `AGENTS.md`, `.kiro/agents/sdd/`, `.kiro/skills/`, `.kiro/steering/`, `.kiro/hooks/` e `.kiro/settings/mcp.json`; o Power em `.sdd/clients/kiro-power/` é opcional. 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`](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
```
O bundle de orquestração distribuído vive em `.agents/skills/orchestration-plugin/`, com mirror compatível em `.claude/skills/orchestration-plugin/`. Use `plugins/design/` quando quiser um plugin Codex repo-local para design minimalista moderno ancorado na stack real do projeto. Esses bundles não são materializados em projetos consumidores por `sdd install`/`sdd update` padrão.
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:
```bash
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, Kiro, 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, adapters e as preferências de orquestração: `orchestration.isolation` (`local` default, `worktree` ou `cloud` reservado/sem integração — sem pergunta obrigatória a cada orquestração; `--worktree yes|no` só como override pontual) e `orchestration.artifacts` (`local` default em `docs/<slug>/`, ou `cloud` para providers integrados como Jira/Confluence/GitHub com o Markdown local como espelho). Rode:
```
sdd doctor # agrega doctor, clients, skills, capabilities, providers e health
sdd doctor --fix # aplica correções seguras da allowlist (pm2, mirrors, MCP)
sdd doctor --strict # gate de CI: apenas reporta, exit != 0 se houver problemas
```
## 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, estritamente read-only, e negocia o contrato `2025-11-25`. Tools perfiladas retornam `structuredContent` tipado e o mesmo JSON em `TextContent` para clientes legados. Use `profile=compact` (até 16 KB) para status/handoff, `profile=standard` (até 64 KB) para geração e `profile=full` somente sob demanda; omitir `profile` preserva o comportamento legado nesta versão minor. Buscas, traces e resources usam cursor, e detalhes volumosos ficam em links `sdd://...` anotados com audiência, prioridade e `lastModified`. A feature opcional `mcp-rmcp` ainda fornece apenas metadata tipada; a migração do transporte ativo para o SDK permanece pendente e o servidor manual é o fallback explícito.
O Artifact Store é resolvido por um locator único que inclui worktrees. Saves usam lock, `--if-match`, SHA-256, revisão, journal e rename atômico; aprovação sempre valida o schema, inclusive com `--force`. Diagnóstico e recuperação são explícitos:
```bash
sdd artifact doctor "meu ciclo"
sdd artifact history "meu ciclo" prd
sdd artifact repair "meu ciclo" --dry-run
sdd artifact repair "meu ciclo" --apply
```
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`. Cada sessão derivada usa `.sdd/acp/sessions/<session_id>/meta.json` atômico e `events.jsonl` append-only/redigido, com replay em `session/load`, listagem e remoção. Turnos emitem plano, chunks, uso e atualização de tool call; operações mutáveis e checkpoints exigem `session/request_permission`. 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 repair --all --json
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,kiro,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/repair` ajuda a reconstruir aprendizados, inspecionar obsolescência, verificar sinais objetivos de saúde e fechar memória operacional ausente/obsoleta, 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 `.agents/skills/orchestration-plugin/` empacota a política como plugin Codex validado e `.claude/skills/orchestration-plugin/` preserva o mirror compatível. 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.