---
name: orchestration
description: Execute or review the full SDD flow across any provider/model and client, including CLI, Codex, Claude Code, opencode, Cursor, Devin, Antigravity and Trae. Use when the user asks for SDD, orchestration, orchestrator, discover, PRD, Tech Spec, tasks, execution, ADR, review or memory.
---

# SDD Orchestration

Use `orchestration` as the canonical command and skill name. Treat `orchestrator` as a legacy alias only.

## Canonical CLI

```bash
sdd orchestration "$ARGUMENTS"
```

## CLI Resolution

Resolve the CLI once before inspecting repository internals or searching for alternate entrypoints:

1. If `command -v sdd` succeeds, run `sdd ...`.
2. If `sdd` is not in `PATH` and the current checkout is the `sdd-layer` source repo (`Cargo.toml` declares package `sdd-layer` and bin `sdd`), run `cargo run --bin sdd -- ...` from the repo root.
3. If both paths fail, report that the SDD CLI is unavailable and include the exact command the harness should retry after installing the binary or adding `$HOME/.cargo/bin` to `PATH`.

Editor and agent shells may not inherit the user's interactive shell `PATH`; do not spend time searching for another CLI implementation before this preflight.

The CLI is the deterministic harness for state, risk, artifact store, validation and hooks. Agent/editor surfaces must call the CLI instead of duplicating logic in prompt text.

## Provider Compatibility

The SDD contract must be provider-neutral. OpenAI-compatible, Anthropic, Google, local CLI, offline and future providers should all be able to consume the same Markdown skills and produce the same artifacts. Treat tool calling, browser access, screenshots, MCP and subagents as optional client capabilities with fallbacks.

## Design And Diagrams

Always trigger the design subflow when the feature involves UI, UX, CLI/TUI, design system, journey, navigation, screen, form, dashboard, visual state or interface copy.

- PRD: use `design-interview` and `experience-design`.
- Tech Spec: use `information-architecture`, `design-tokens` and `artifact-diagrams`.
- Tasks or Refinement: use `design-to-tasks`.
- Execution: use `frontend-design` or the stack-appropriate experience handoff.
- Review, checkpoint or merge: use `visual-review` with visual evidence or a documented fallback.

Use `artifact-diagrams` in planning when flow, architecture, states, contracts or dependencies are clearer visually. Every materialized PRD and Tech Spec must include `## Diagramas`: add useful Mermaid/Excalidraw references, or write `Não aplicável` with a short reason when a diagram would be noise. Keep Mermaid in Markdown for versioned artifacts and save Excalidraw canvases in `docs/<orchestration-slug>/assets/` when planning needs editable collaboration.

## Task Agent Prompts

Tasks must include `## Prompts Agent` with one standalone prompt per task. Each prompt must be precise enough for any LLM/client to execute without conversation memory.

Each prompt must include:

- Task ID and title using the executable format `T-01` or `TSK-01`.
- Origin artifacts: PRD, Tech Spec, Tasks, diagrams and relevant assets.
- Verifiable objective.
- In scope and out of scope.
- Probable files and ownership boundaries.
- Business rules, technical contracts, states, data constraints and design references needed to execute.
- Implementation steps or investigation sequence.
- Validation commands/checks or instructions to discover them in the repo.
- Definition of Done and expected final report.

Do not require a specific provider, model, browser, MCP, subagent or tool-calling capability inside the prompt. Express optional capabilities with fallbacks.

## Flow

0. Project Discovery: stack, commands, paths, CI, risks and adapters.
0. Risk Classification: rigor, Refinement, Agent Teams, checkpoints and evidence.
1. Idea: product discovery.
2. PRD: requirements, rules and acceptance criteria. Checkpoint.
3. Tech Spec: codebase-grounded architecture. Checkpoint.
4. Tasks: atomic backlog with Gherkin.
5. Refinement: optional but formal grooming; record when skipped.
6. Execution: one task at a time, after reading the execution Context Pack and code-intelligence handoff.
6a. ADR: create or update Architecture Decision Records from execution evidence.
7. Review: diff, tests, security and acceptance criteria. Checkpoint.
8. Memory: compact decisions, links and learnings.

## Rules

- Do not skip required stages.
- Do not skip Refinement when risk is medium, high or critical.
- Stop for explicit human decisions at checkpoints.
- Before creating stage artifacts, initialize the local artifact store with `sdd init "<orchestration-name>"`.
- Use `docs/<orchestration-slug>/` and `traceability-map.yaml` as the local source of truth when external integrations are absent or partial.
- Use `sdd artifact save` for every approved or recorded artifact, with `approved` only after the human checkpoint.
- Validate materialized Markdown with `sdd validate-artifact`.
- When generating PT-BR artifacts or human-facing content, preserve accents and diacritics. Use ASCII-only text only for slugs, paths, branches, code identifiers, commands, schemas, API fields or literal external contracts.
- Use `provider-compatibility` when a workflow must run across all providers/models.
- Use `artifact-diagrams` in planning with Mermaid and Excalidraw when the visual map improves shared understanding.
- After Execution, run `sdd adr` when a technical or architectural decision was made or changed.
- Keep traceability from idea to code, tests and memory.
- After `/discover`, use the generated recommendations to propose technology-specific skills, rules, `AGENTS.md` sections and `CLAUDE.md` deltas.
- Before `/execution`, generate or read `sdd context build --name "<orchestration>" --stage execution --write`; use `code-intelligence` when CodeGraph/Lexa are available, otherwise use `rg --files`, `rg` and focused reads.
- During `/execution`, use `execution-discipline`: tracer bullet vertical slices, failing tests when a seam exists, reproducible diagnosis loops for bugs/performance and fresh verification evidence.

## Formato de saída por etapa

Use o mesmo contrato de saída dos subagents `.codex/agents` e `.claude/agents` em qualquer cliente:

- `idea`: visão geral da ideia, problema, público-alvo, proposta de valor, jornada principal, MVP, fora do MVP, hipóteses, riscos e perguntas em aberto.
- `prd`: resumo executivo, contexto, objetivos, não objetivos, personas, casos de uso, fluxos, requisitos funcionais e não funcionais, regras de negócio, estados, critérios de aceite, métricas, riscos, dependências, escopo do MVP e `Diagramas` com Mermaid/Excalidraw ou justificativa de `Não aplicável`.
- `techspec`: visão técnica, arquitetura, stack, estrutura de pastas, modelagem de dados, contratos de API, fluxos técnicos, estados/eventos, autenticação/autorização, validação, erros, observabilidade, segurança, performance, testes, riscos, decisões arquiteturais, plano de implementação e `Diagramas` técnicos com Mermaid/Excalidraw ou justificativa de `Não aplicável`.
- `tasks`: épicos, histórias técnicas, tarefas atômicas em formato executável (`T-01` ou `TSK-01`), ordem sugerida, dependências, critérios de aceite em Gherkin, DoD, estratégia de testes, arquivos prováveis e `Prompts Agent` standalone por tarefa.
- `refinement`: documento único e enxuto com `Resumo`, `Solução proposta`, `Pontos de observação`, `Checklist macro`, `Subtasks` com estimativas em múltiplos de 0.5h, `Definition of Done` e `Flags, Remote Configs e Configurações`.
- `execution`: resumo do implementado, arquivos criados/alterados, decisões técnicas, como testar, impactos e pendências.
- `adr`: rastreabilidade, status, contexto, problema, decisão, alternativas, consequências, impactos/riscos, plano de adoção, plano de reversão, evidências e histórico de revisão.
- `review`: veredito `Aprovado | Aprovado com ressalvas | Reprovado`, pontos positivos, problemas, severidade, sugestões, testes recomendados e checklist de qualidade.
- `memory`: estado atual, funcionalidades implementadas, arquitetura atual, decisões, padrões, comandos úteis, variáveis de ambiente, testes, pendências, próximos passos e contexto resumido.

Todo artefato materializado deve ter `Rastreabilidade`, apontar para o artefato anterior e ser salvo em `docs/<slug-da-orquestracao>/` com `sdd artifact save`. Use `recorded` para etapas informativas e `approved` somente depois de checkpoint humano.
