---
name: orchestration
description: Executar ou revisar o fluxo completo Spec-Driven Development em qualquer client ou provider, com Project Discovery, classificação de risco, contratos de artefato, Agent Teams, automations, checkpoint humano, rastreabilidade, integração Jira/Confluence/Bitbucket/GitHub/GitLab e memória de ciclo.
---

# Orquestração SDD

## Fluxo

0. Project Discovery: stack, comandos, paths, CI, riscos e adapters do projeto.
0. Risk Classification: rigor, Refinement, Agent Teams, checkpoints e evidências.
1. Ideia: visão de produto.
2. PRD: requisitos, regras e critérios iniciais. Checkpoint.
3. Tech Spec: arquitetura ancorada no codebase. Checkpoint.
4. Tasks: backlog atômico com Gherkin.
5. Refinement: grooming enxuto opcional, registrado quando dispensado.
6. Execution: uma task por vez, depois de ler o Context Pack de execution e o handoff de code intelligence.
6a. ADR: crie ou atualize Architecture Decision Records a partir das evidências de execução.
7. Review: revisão, CI e validação contra critérios. Checkpoint.
8. Memory: compactação de decisões, links e aprendizados.

## Distribuição

- Use `sdd install <projeto>` no repo da camada ou `sdd install <projeto>` em um pacote instalado.
- Use `.sdd/presets/` como ponto de partida de `sdd.config.yaml`.
- Use `.sdd/adapters/` para mapear Atlassian, GitHub, GitLab, Linear/Notion ou Markdown-only.
- Use `/dry-run` antes de liberar Execution em projetos sensíveis.

## Compatibilidade de providers

O fluxo deve funcionar com qualquer provider configurado em `sdd.config.yaml`: OpenAI-compatible, Anthropic, Google, local CLI, offline ou futuro. Provider/modelo não é client/harness. O contrato portátil é Markdown, arquivos, comandos `sdd`, artifact store, validação e evidência. Use `provider-compatibility` quando uma etapa depender de tool calling, browser, MCP, subagent, screenshots ou contexto longo.

## Contrato runtime-agnostic

O core SDD governa o contrato SDLC: etapas, artifact store, checkpoints, validação, rastreabilidade, registry de providers e comportamento determinístico do CLI. Rig, Flue, LangGraph, Agno e runtimes futuros são engines/adapters opcionais para execução, roteamento, tools ou composição; eles não substituem `.agents` como contrato canônico, `docs/<slug-da-orquestracao>/traceability-map.yaml` como fonte local de verdade nem MCP/trace como observabilidade read-only. Quando um runtime adapter estiver ausente, continue com Markdown, comandos `sdd`, artifact store local e validações determinísticas.

## Qualidade e observabilidade

Antes de avançar execução autônoma, review ou memória, rode:

```bash
sdd eval stage --name "<orquestracao>" --stage <stage> --json
sdd eval orchestration --name "<orquestracao>" --json
sdd quality report --name "<orquestracao>" --json
sdd trace summary --orchestration "<orquestracao>" --json
```

As avaliações validam seções obrigatórias, rastreabilidade, diagramas, `Prompts Agent`, freshness de Context Packs e estado do `traceability-map.yaml`. Achado crítico bloqueia avanço automático. `sdd quality report` registra ferramentas opcionais e fallbacks em `.sdd/evaluations.jsonl`.

Para pós-planejamento autônomo, use apenas depois dos gates humanos exigidos:

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

`--through` nunca aprova merge, release ou deploy.

Eventos devem preservar `agent`, `selected_model`, `observed_model` quando o provider/CLI reporta metadata confiável e `confidence`. Não inferir `observed_model` a partir da configuração; se o provider só retorna texto, deixe o modelo observado como não reportado.

Quando um adapter/editor tiver contagem real de uso, chame `sdd <stage>` ou `sdd artifact save` propagando `SDD_USAGE_INPUT_TOKENS`, `SDD_USAGE_CACHED_INPUT_TOKENS`, `SDD_USAGE_OUTPUT_TOKENS`, `SDD_USAGE_REASONING_OUTPUT_TOKENS` e `SDD_USAGE_TOTAL_TOKENS`; os artefatos gravam `Tokens source: provider-reported`. Para tempo real de geração, propague `SDD_GENERATION_STARTED_AT`, `SDD_GENERATION_EXECUTION_STARTED_AT`, `SDD_GENERATION_FINISHED_AT`, `SDD_GENERATION_DURATION_MS`, `SDD_GENERATION_REASONING_DURATION_MS` e `SDD_GENERATION_EXECUTION_DURATION_MS`; os artefatos gravam `Tempo source: provider-reported`. Sem esses envs, o CLI grava estimativa local de tokens e tempo local do CLI com source explícito.

## Diagramas e prompts agent

Todo PRD e toda Tech Spec materializada deve incluir `## Diagramas`; IDEA pode incluir quando o visual melhorar entendimento. Use Mermaid no Markdown para o resumo versionável e referencie Excalidraw em `docs/<slug-da-orquestracao>/assets/` quando houver canvas editável. Use `diagram-design` apenas como companion HTML/SVG em `docs/<slug-da-orquestracao>/assets/diagrams/`, anexado com `sdd diagram attach`. Se diagrama não agregar clareza, mantenha a seção com `Não aplicável` e uma justificativa curta.

Toda etapa Tasks deve incluir `## Prompts Agent` com um prompt standalone por task. Cada prompt precisa funcionar para qualquer LLM/client sem depender da conversa anterior e deve conter ID/título executável (`T-01` ou `TSK-01`), artefatos de origem, objetivo verificável, escopo e fora de escopo, arquivos prováveis, regras/contratos/estados/dados/design relevantes, sequência de execução, validação, DoD e formato do relatório final.

## Artifact store local

Toda orquestração deve ter um fallback local em `docs/<slug-da-orquestracao>/`, inicializado com:

```bash
sdd init "<nome-da-orquestracao>"
```

Quando Jira, Confluence, Git provider ou outro sistema externo não estiverem configurados por completo, esse diretório é a fonte canônica dos artefatos. Salve etapas informativas como `recorded`; salve PRD, Tech Spec, Refinement e Review como `approved` somente depois do checkpoint humano.

## Agent Teams

Use o caminho solo por padrão. Use Agent Teams quando a etapa ganha com paralelismo real:

- TechSpec: `architecture-reviewer`, `security-reviewer`, `data-contract-reviewer`, `qa-strategist`.
- Tasks: decomposição por domínio quando houver independência clara.
- Execution: `frontend-implementer`, `backend-implementer`, `test-implementer`, somente com ownership explícito de arquivos.
- Review: `security-reviewer`, `performance-reviewer`, `test-reviewer`, `architecture-reviewer`, `data-contract-reviewer`.

O lead sintetiza os resultados. Teammates não aprovam checkpoints humanos.

## Automations

- Hooks: bloqueiam comandos perigosos, impedem conclusão sem evidência, auditam subagents/teams e notificam quando há input humano.
- Channels/webhooks: trazem eventos externos como CI, PR, Jira, Slack e deploy para a sessão.
- Scheduled tasks: acompanham temporariamente PR/CI/deploy quando não há evento push.
- Critério: evento push primeiro, polling só quando necessário.

## Regras

- Não pule etapas obrigatórias.
- Só dispense Refinement quando a feature for trivial e registre o motivo.
- Não dispense Refinement se o Risk Classification indicar risco médio, alto ou crítico.
- Use `output-quality` quando um artefato precisar de síntese decisão-primeiro, matriz de evidência ou handoff mais claro.
- Gere artefatos em PT-BR com acentuação preservada. Use texto sem acento somente em slugs, paths, branches, identificadores, comandos, schemas, campos de API ou contratos externos literais.
- Use `provider-compatibility` quando a solução precisar funcionar em todos os providers/modelos.
- Use `artifact-diagrams` em planejamento quando fluxo, arquitetura, estados, contratos ou dependências ficarem mais claros visualmente; prefira Mermaid dentro do Markdown e Excalidraw como canvas editável quando o fluxo precisar de colaboração, exploração ou mapa espacial. Use `diagram-design` somente como companion HTML/SVG em `assets/diagrams/`.
- Após Execution, rode `sdd adr` quando uma decisão técnica ou arquitetural tiver sido criada, confirmada ou alterada.
- Rode `sdd eval stage`, `sdd eval orchestration` e `sdd quality report` antes de execução autônoma, review ou memory.
- IDEA pode ter `## Diagramas` quando útil; PRD e Tech Spec precisam ter `## Diagramas` com Mermaid/Excalidraw útil, companion `assets/diagrams/*.html|*.svg` ou justificativa de `Não aplicável`.
- Tasks precisam ter `## Prompts Agent` com prompt standalone por task, provider-neutral e executável por qualquer LLM/client.
- Sempre acione o subfluxo de design quando a feature envolver UI, UX, CLI/TUI, design system, jornada, navegação, tela, formulário, dashboard, estado visual ou copy de interface.
- Em PRD com impacto de experiência, use `design-interview` e `experience-design` para transformar decisões de design em requisitos e critérios.
- Em Tech Spec com impacto de experiência, use `information-architecture`, `design-tokens` e `artifact-diagrams`; salve Mermaid no artefato, Excalidraw em `docs/<slug-da-orquestracao>/assets/` e companions `diagram-design` em `docs/<slug-da-orquestracao>/assets/diagrams/` quando útil ao planejamento.
- Em Tasks ou Refinement com impacto de experiência, use `design-to-tasks` para criar fatias verticais verificáveis.
- Em Execution de UI/UX/CLI/TUI, use `frontend-design` ou o handoff de experiência adequado à stack.
- Em Review, checkpoint ou merge de superfície visual, use `visual-review` com evidência visual ou fallback documentado.
- Antes de Execution, gere ou leia `sdd context build --name "<orquestracao>" --stage execution --write`; use `code-intelligence` quando CodeGraph/Lexa existirem, senão use `rg --files`, `rg` e leitura focada.
- Durante Execution com escrita, use apenas adapter autorizado; provider sem escrita deve falhar explicitamente antes de mutar arquivos.
- Durante Execution, use `execution-discipline`: tracer bullet vertical, teste falhando quando houver seam correto, loop reproduzível para bugs/performance e verificação fresca.
- Use checkpoints humanos como decisão explícita: aprovar, pedir ajustes ou rejeitar.
- Preserve rastreabilidade em todos os artefatos.
- Não duplique conteúdo entre sistemas; grave links canônicos.
- Cite o arquivo local salvo em `docs/<slug-da-orquestracao>/` em cada checkpoint e na memória.
- Valide artefatos materializados com `.sdd/schemas/artifact-sections.json`.
- Review deve validar comportamento, testes, segurança e linhas alteradas.
- Memory deve compactar, não duplicar documentos.
- Agent Teams exigem escopo, ownership, evidências e síntese do lead.

## Skills de apoio

- `output-quality`: composição de artefatos decisão-primeiro.
- `provider-compatibility`: portabilidade entre providers/modelos e clients/harnesses.
- `artifact-diagrams`: Mermaid e Excalidraw para fluxos, arquitetura, estados e planejamento.
- `diagram-design`: companions HTML/SVG editoriais para `docs/<slug-da-orquestracao>/assets/diagrams/`.
- `experience-design`: UX/UI/CLI/TUI, estados, tokens, acessibilidade e handoff.
- `design-flow`: sequência guiada de design dentro do SDD.
- `design-interview`: entrevista e stress-test de decisões.
- `information-architecture`: estrutura, navegação, conteúdo, rotas e fluxos.
- `design-tokens`: sistema visual, dark mode, motion e tokens semânticos.
- `design-to-tasks`: brief/IA em tasks verticais verificáveis.
- `frontend-design`: implementação visual aderente à stack real.
- `visual-review`: QA visual com evidência, responsividade e acessibilidade.
- `bdd-gherkin`: critérios de aceite e comportamento.
- `code-review`: revisão antes de merge.
- `traceability`: links de origem, estado e evidência.
- `project-discovery`: onboarding de repositório.
- `risk-classifier`: decisão de rigor do fluxo.
- `artifact-schemas`: contratos mínimos de artefato.
- `test-strategy`: evidência executável.
- `release-readiness`: merge/deploy.
- `security-privacy`: segurança e dados sensíveis.
- `data-contracts`: APIs, eventos e migrations.
- `repo-adapter`: GitHub/GitLab/Bitbucket/monorepo.
- `checkpoints`: gates humanos.
- `integrations`: Jira, Confluence, Bitbucket, MCP e webhooks.
- `memory`: fechamento do ciclo.
