# 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 oito etapas, com **Refinamento** como etapa opcional, cada uma conduzida por um subagent especializado, com checkpoints humanos nos pontos críticos.
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
- 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`, `/memory` — cada uma delega ao subagent correspondente e aceita um argumento de entrada.
## 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 |
| 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 / QA |
| 8 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`, `bdd-gherkin`, `code-review`, `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.
- 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