spec-driven

Use para uma SABATINA — entrevista implacável que transforma intenção difusa em entendimento compartilhado antes de construir. Caminha pela árvore de decisão UMA pergunta por vez, resolvendo dependências entre escolhas, sempre com uma resposta recomendada; explora o codebase/docs em vez de perguntar quando a resposta já existe. Ideal no gate da spec (AC testáveis / Definition of Ready) e do design (decisão difícil de reverter). Produz um resumo de entendimento que alimenta product.md/design.md/spec.md. Chamada por /nova-feature, /kickoff, /roadmap e /validar, ou acione direto com /clarificar.

Use ao iniciar OU dar continuidade a um projeto com o boilerplate SDD. Primeiro descobre o modo — greenfield (começando do zero) ou brownfield (já rodando) — e roteia. Greenfield conduz uma entrevista Lean Inception (visão, personas, MVP). Brownfield mapeia o estado atual (as-is), identifica gaps vs o padrão SDD e captura decisões históricas. Os dois caminhos passam pelo kickoff técnico nos 5 eixos (tech stack, arquitetura, infra, qualidade, observabilidade), propõem a camada agêntica do projeto (rules, subagents, skills, workflows/CI) e convergem num roadmap incremental, gerando a "constituição" do projeto. As integrações com ferramentas do time (Jira, Confluence, MCPs) são uma skill separada (/integracoes) — rode antes para insumos read-first, ou depois. Acione com /kickoff.

Use para abrir uma nova feature no padrão SDD. Decide o tier (trivial/pequeno/arquitetural), cria specs/NNNN-<nome>/ com os templates certos, conduz o preenchimento de cima pra baixo pelos gates (product → design → domain → spec → tasks) e, quando há MCP conectado, importa a story do Jira no início e cria as issues na quebra de tasks. Acione com /nova-feature.

Use para construir ou atualizar docs/product/roadmap.md em horizontes Now/Next/Later, com valor, esforço, dono e dependências, priorizando quick wins de baixo risco. No brownfield inclui a adoção incremental do SDD. Pensado para revisar com o time a cada ciclo. É chamada pelo /kickoff e também roda sozinha periodicamente. Acione com /roadmap.

Use APÓS implementar uma feature para validá-la (UAT) — roda os gates de docs/engineering/TESTING.md, mapeia cada AC-N ao seu teste e aponta ACs sem cobertura, resolve SPEC_DEVIATION pendente, checa o Definition of Done e atualiza docs/STATE.md. Acione com /validar.

Use para acompanhar métricas de entrega/fluxo — Lead Time (tempo até produção) e Throughput (itens concluídos por ciclo) — a maturidade de Continuous Delivery vs Continuous Deployment, e a qualidade de código (cobertura e análise estática) como tendência rastreável. Lê git/Jira/CI e os artefatos de qualidade quando há MCP conectado e atualiza docs/engineering/metrics.md. Acione com /metricas.

Use para criar ou ajustar a pipeline de CI/CD que materializa os gates SDD — lint, análise estática (type-check/complexidade/SAST), testes (unidade/integração/aceite) e cobertura a partir de docs/engineering/TESTING.md, com cobertura e análise estática publicadas como artefatos, mais a regra "falha PR sem spec aprovada". Detecta GitHub Actions / GitLab CI / outro. Gera o arquivo só com aprovação. Acione com /setup-ci.

Use para levantar as ferramentas do time (Jira, Confluence, Notion, GitHub, cloud, observabilidade), conectar os MCPs com segurança, puxar insumos de leitura e definir os fluxos de escrita (repo → ferramenta). Gera docs/engineering/integrations.md e, se aprovado, .mcp.json, e registra os MCPs validados no roteamento (bloco "Ferramentas conectadas (MCP)" do CLAUDE.md + skills tools-aware). Rode ANTES do /kickoff para alimentar os artefatos com dado real (read-first), ou DEPOIS, quando o ferramental ficar conhecido. Re-executável. Acione com /integracoes.

Use para revisar um PR/MR no padrão SDD — verifica conformidade de processo: spec aprovada para a mudança, cada AC-N com teste verde, nenhum SPEC_DEVIATION aberto, ADRs para decisões irreversíveis, glossário/context-map atualizados e DoD cumprido. Posta o resultado como comentário no PR/MR via GitHub/GitLab MCP (se conectado). Complementa o /code-review do harness (que caça bugs). Acione com /revisar-pr.

Use para auditar a conformidade da esteira SDD — roda o validador estrutural (frontmatter, links, specs) e checa o que exige julgamento (rastreabilidade AC→teste→commit, DoD, specs órfãs, docs vivas atualizadas). Reporta violações com o arquivo. Acione com /auditar.

Use no discovery para desenhar a arquitetura de ALTO NÍVEL em Mermaid — diagrama de contexto (C4 L1), containers (C4 L2) e o mapa de bounded contexts (DDD). Lê vision, context-map, design e assessment, e gera/atualiza docs/architecture/diagrams.md. Mantém alto nível, sem detalhe de implementação. Acione com /diagramar.

Use para avaliar a fidelidade da implementação à spec — roda o eval que checa se cada AC-N é coberto por task e referenciado em teste, conta SPEC_DEVIATION e reporta um score por feature. Acione com /evals.

Use para propor e gerar a camada agêntica do projeto — rules (CLAUDE.md, settings.json), subagents (.claude/agents), skills (.claude/skills) e workflows/CI — afinados ao stack, ferramentas, processo e domínio. Propõe com justificativa e gera só o aprovado. É chamada pelo /kickoff e também roda sozinha ao evoluir o projeto ou ao chegar novas ferramentas. Acione com /camada-agentica.

Use ao PAUSAR/encerrar uma sessão de trabalho (grava o estado atual em docs/STATE.md para retomar depois) ou ao RETOMAR (lê docs/STATE.md e a spec ativa e recompõe o contexto, propondo o próximo passo). Mantém a continuidade entre sessões de humanos e agentes. Acione com /handoff.

Use para mapear um codebase existente (brownfield) e produzir docs/architecture/assessment.md — stack, arquitetura, bounded contexts implícitos, maturidade nos 5 eixos, dívidas/riscos e decisões históricas a virar ADR retroativo. Re-execução atualiza o assessment. É chamada pelo /kickoff no modo brownfield, e também roda sozinha quando o codebase mudar ou para analisar um repo. Acione com /mapear.