# AGENTS.md — Camada de orquestração SDLC (Spec-Driven)
Este projeto opera como um sistema multiagente de engenharia de software: leva uma feature da **Ideia à Produção** em nove etapas, com **Refinamento** como etapa opcional, cada uma conduzida por um subagent especializado, com checkpoints humanos nos pontos críticos. ADR não é etapa fixa: é gerado sempre antes do PRD (primeiro ADR da orquestração, obrigatório) e antes do Tech Spec quando houver decisão técnica, além de outras vezes que fizerem sentido ao longo do fluxo.
O SDD é runtime-agnostic: o core governa o contrato SDLC (etapas, artifact store, checkpoints, validação, rastreabilidade, providers e CLI determinístico). Rig, Flue, LangGraph, Agno e runtimes futuros são engines/adapters opcionais; quando ausentes, o fluxo continua por Markdown, comandos `sdd`, artifact store local e validações determinísticas.
## Como invocar
- Decisão de isolamento: config-driven via `orchestration.isolation` no `sdd.config.yaml` — `local` (default; checkout normal no branch da orquestração), `worktree` (cópias isoladas em `.worktree/<key>/`) ou `cloud` (reservado, ainda sem integração; o `next` falha orientando o ajuste). Não pergunte a cada orquestração: inicie o loop com `sdd orchestration next "<entrada>"` e use `--worktree yes|no` apenas como override pontual quando o usuário pedir explicitamente.
- Destino dos artefatos: `orchestration.artifacts` no `sdd.config.yaml` — `local` (default; `docs/<slug>/`) ou `cloud` (providers integrados — Jira/Confluence/GitHub — conforme `systems:` e `adapters.canonical_artifacts`; exige provider configurado e mantém o Markdown local como espelho/fallback).
- Preparação: `/sdd discover` para Project Discovery, `/sdd risk "<feature>"` para classificar risco, `/sdd doctor` para validar instalação/configuração e `/dry-run "<feature>"` para simular sem tocar código.
- Fluxo completo: `/sdd orchestrator "<sua ideia>"` — roda Project Discovery/Risk Classification quando necessário e depois as etapas em ordem, parando nos checkpoints (PRD, Tech Spec, Refinement quando houver risco, merge/deploy) para sua aprovação.
- Etapas individuais: `/idea`, `/prd`, `/techspec`, `/tasks`, `/refinement` (opcional), `/execution`, `/review`, `/qa`, `/memory` — cada uma delega ao subagent correspondente e aceita um argumento de entrada. `/adr` roda sempre que uma decisão precisar ser travada (obrigatório antes do PRD).
## Fluxo
`Discovery → Risk → Idea → ADR-01 → PRD → ADR-02 (se necessário) → Tech Spec → Tasks → Refinement (se necessário) → Execution → Review → QA → Memory`. ADR-01 é obrigatório logo após a Idea, antes do rascunho do PRD. ADR-02 (e seguintes) são gerados sempre que Tech Spec, Tasks ou Execution travarem uma decisão não óbvia com trade-off real — não são etapa fixa numerada, são chamados sob demanda, sequenciais (`adr-001`, `adr-002`...) em `docs/<slug>/adrs/`.
## Etapas e papéis
| Etapa | Comando | Subagent | Papel |
| ----------------------- | --------------- | -------------------- | ------------------------------ |
| 0 Discovery | `/sdd discover` | `project-discovery` | Project Onboarding |
| 0 Risk | `/sdd risk` | `risk-classifier` | Risk Calibration |
| 1 Ideia | `/idea` | `idea` | Product Discovery |
| — ADR (sob demanda) | `/adr` | `adr` | Architecture Decision Record |
| 2 PRD | `/prd` | `prd` | Product Requirements |
| 3 Tech Spec | `/techspec` | `techspec` | Software Architect |
| 4 Tasks | `/tasks` | `tasks` | Delivery Planner |
| 5 Refinement (opcional) | `/refinement` | `refinement` | Tech Lead / Grooming |
| 6 Execução | `/execution` | `execution` | Senior Engineer |
| 7 Review | `/review` | `review` | Principal Engineer |
| 8 QA | `/qa` | `qa` | QA Engineer |
| 9 Memória | `/memory` | `memory` | Knowledge Manager |
As skills `output-quality`, `provider-compatibility`, `artifact-diagrams`, `experience-design`, `design-flow`, `design-interview`, `information-architecture`, `design-tokens`, `design-to-tasks`, `frontend-design`, `visual-review`, `design-extraction`, `impeccable-design`, `bdd-gherkin`, `code-review`, `systematic-debugging`, `subagent-orchestration`, `reflexion-loop`, `project-discovery`, `risk-classifier`, `artifact-schemas`, `test-strategy`, `release-readiness`, `security-privacy`, `data-contracts`, `repo-adapter`, `traceability`, `checkpoints`, `integrations` e `memory` são carregadas automaticamente quando relevantes.
## Configuração por projeto
- Crie `sdd.config.yaml` a partir de `.sdd/sdd.config.example.yaml` em projetos instalados.
- Use `sdd init` sem argumento para detectar o projeto atual, escolher preset e instalar/organizar a camada SDD.
- Rode `sdd doctor` antes do primeiro uso em projetos instalados. O `sdd doctor` agrega todos os doctors (`doctor`, `clients`, `skills`, `capabilities`, `providers` e `health`) em um único relatório; `--fix` aplica correções seguras da allowlist (pm2 opcional, sync de mirrors, regen de MCP), `--fix --dry-run` exibe o plano sem aplicar, `--strict` é gate de CI (apenas reporta, exit != 0 se houver problemas).
- Use `sdd validate-artifact <tipo> <arquivo.md>` para validar artefatos materializados em Markdown.
- Use `.sdd/templates/traceability-map.yaml` como mapa canônico de feature.
- Use `sdd init "<nome-da-orquestracao>"` para criar `docs/<slug-da-orquestracao>/`; salve cada artefato aprovado nesse diretório quando Jira/Confluence/etc. não estiverem configurados por completo.
- Use `sdd install <projeto>` no repositório da camada para plugar em outros projetos.
- Use `.sdd/adapters/` para trocar Jira/Confluence/Bitbucket por GitHub, GitLab, Linear/Notion ou Markdown-only.
- Em layout flat/legado, continue usando `sdd`; o binário Rust é o harness determinístico.
## Agent Teams e automações
- Caminho padrão: um subagent por etapa.
- Caminho paralelo: use Agent Teams em Tech Spec complexa, Tasks cross-layer, Execução de tasks independentes e Review multidimensional.
- Teammates auxiliares: `architecture-reviewer`, `security-reviewer`, `performance-reviewer`, `test-reviewer`, `data-contract-reviewer`, `qa-strategist`, `frontend-implementer`, `backend-implementer`, `test-implementer`.
- Automations: hooks fazem guardrails e auditoria local; Channels/webhooks trazem eventos externos; scheduled tasks acompanham PR/CI/deploy quando não há evento push.
## MCP e observabilidade
- Use `sdd mcp serve --root .` para expor artifacts, contexto, traces, `clients doctor` e adapters runtime (`sdd_runtime_adapters`) como MCP read-only.
- Use `.mcp.json` e `.cursor/mcp.json` para conectar os servidores `sdd` e `codegraph`.
- Traces continuam tendo fonte canônica local em `.sdd/events.jsonl`, `.sdd/subagents.jsonl`, `.sdd/task-gates.jsonl` e `.sdd/runs.jsonl`; MCP apenas consulta e apresenta esses dados.
- MCP/trace não substituem `docs/<slug>/traceability-map.yaml` nem aprovam checkpoints; são observabilidade derivada com fallback por CLI.
- Use `sdd trace list|show|summary|doctor` para auditoria fora do client MCP.
## Regras sempre ativas
@.codex/rules/00-sdd-principles.md
@.codex/rules/10-traceability.md
@.codex/rules/20-output-conventions.md