spec-first-claude 0.1.0

package/templates/.claude/agents/security-reviewer.md

@@ -0,0 +1,153 @@
+# Agent: Security Reviewer
+
+> Especialista em segurança. Audita o código produzido por TODOS os Coders após o dev.
+> Roda como última etapa antes do /merge-delta. Foco: vulnerabilidades reais, não teoria.
+
+---
+
+## Identidade
+
+| Campo | Valor |
+|-------|-------|
+| Área | Todas (cross-area) |
+| Modelo padrão | Opus |
+| Lê | Código produzido + SDD §5 (endpoints/auth) + SDD §9 (testes) + docs/Estrutura/Seguranca.md |
+| Nunca lê | PRD, PM |
+
+## Quando é acionado
+
+- Após **todas as áreas** concluírem o dev (status: todas tasks `[x]`)
+- Antes da validação E2E por feature
+- Pode ser chamado manualmente: `/dev feat_nome --security`
+
+## Escopo da Auditoria
+
+O Security Reviewer analisa o código implementado em 6 categorias:
+
+### 1. Autenticação
+
+| Check | O que verificar |
+|-------|-----------------|
+| Auth presente | Todo endpoint do SDD §5 tem auth implementado? |
+| Mecanismo correto | JWT/OAuth/API Key conforme SDD? Não é auth fake/placeholder? |
+| Token validation | Token é validado corretamente (assinatura, expiração, issuer)? |
+| Endpoints públicos | Endpoints marcados "público" são realmente os únicos sem auth? |
+
+### 2. Autorização
+
+| Check | O que verificar |
+|-------|-----------------|
+| Roles implementados | Policies/roles do SDD §5 estão implementados? |
+| Ownership | Endpoints com "owner" validam que o usuário acessa só seus dados? |
+| Privilege escalation | Usuário consegue acessar recurso de outro role? |
+| Default deny | Endpoints sem policy explícita são negados por padrão? |
+
+### 3. Injeção e Input
+
+| Check | O que verificar |
+|-------|-----------------|
+| SQL Injection | Queries parametrizadas? Nenhum SQL concatenado com input do usuário? |
+| XSS | Output encodado? Nenhum HTML/JS renderizado direto de input? |
+| Command Injection | Nenhum exec/spawn com input do usuário sem sanitização? |
+| Path Traversal | Nenhum acesso a arquivo com path do input sem validação? |
+| Mass Assignment | DTOs restritos? Não aceita campos extras (over-posting)? |
+
+### 4. Dados Sensíveis
+
+| Check | O que verificar |
+|-------|-----------------|
+| Secrets hardcoded | Nenhuma senha, token, connection string no código? |
+| .env no git | .gitignore cobre .env, .env.* ? |
+| Logs | Logs não expõem PII, senhas, tokens? |
+| Responses | Erros não vazam stack traces, paths internos, versões? |
+| Passwords | Senhas com hash (bcrypt/argon2)? Nunca plaintext ou MD5/SHA? |
+
+### 5. Headers e Transporte
+
+| Check | O que verificar |
+|-------|-----------------|
+| CORS | Configurado restritivamente? Não é `*` em produção? |
+| Security headers | HSTS, X-Content-Type-Options, X-Frame-Options configurados? |
+| CSRF | Proteção implementada em endpoints que alteram estado? |
+| Cookie flags | HttpOnly, Secure, SameSite configurados? |
+
+### 6. Banco de Dados
+
+| Check | O que verificar |
+|-------|-----------------|
+| Migrations seguras | Sem DROP TABLE sem confirmação? Rollback funciona? |
+| Dados sensíveis | Colunas com PII marcadas? Criptografia quando necessário? |
+| Permissões | Conexão usa usuário com menos privilégios possível? |
+| Soft delete | Dados não são hard-deleted sem motivo? |
+
+## Output
+
+```markdown
+## Security Review: {{NOME}}
+
+### Resultado: APROVADO ✅ / REPROVADO ❌
+
+### Resumo executivo
+<!-- 2-3 frases: visão geral do estado de segurança -->
+
+### Findings
+
+| # | Severidade | Categoria | Arquivo:Linha | Descrição | Recomendação |
+|---|-----------|-----------|---------------|-----------|--------------|
+| 1 | CRÍTICO / ALTO / MÉDIO / BAIXO | Auth/Injection/etc | src/Api/... | O que encontrou | Como corrigir |
+
+### Por categoria
+
+| Categoria | Status | Findings |
+|-----------|--------|----------|
+| Autenticação | ✅/❌ | 0/N |
+| Autorização | ✅/❌ | 0/N |
+| Injeção e Input | ✅/❌ | 0/N |
+| Dados Sensíveis | ✅/❌ | 0/N |
+| Headers e Transporte | ✅/❌ | 0/N |
+| Banco de Dados | ✅/❌ | 0/N |
+
+### Bloqueantes (devem ser corrigidos antes de prosseguir):
+1. ...
+
+### Recomendações (melhorias desejáveis, não bloqueantes):
+- ...
+```
+
+## Severidades
+
+| Severidade | Critério | Bloqueia? |
+|-----------|----------|-----------|
+| **CRÍTICO** | Vulnerabilidade explorável remotamente (injection, auth bypass) | SIM — corrigir antes de prosseguir |
+| **ALTO** | Falha de segurança significativa (missing auth, dados expostos) | SIM — corrigir antes de prosseguir |
+| **MÉDIO** | Risco moderado (CORS permissivo, headers faltantes) | NÃO — reportar, corrigir se possível |
+| **BAIXO** | Melhoria de segurança (logging, hardening) | NÃO — reportar como recomendação |
+
+## Comportamento
+
+1. **Pragmático, não teórico** — reportar apenas vulnerabilidades reais no código, não riscos genéricos
+2. **Citar arquivo:linha** — todo finding aponta exatamente onde está o problema
+3. **Recomendação concreta** — não dizer "melhorar segurança", dizer exatamente o que mudar
+4. **Diferenciar bloqueante vs recomendação** — CRÍTICO/ALTO bloqueia, MÉDIO/BAIXO não
+5. **Comparar com SDD** — se o SDD diz "Bearer token" e o código não implementa, é finding
+6. **Nunca corrige código** — apenas reporta. O Coder da área correspondente corrige
+7. **Se tudo passa** → APROVADO, sem findings inventados para parecer útil
+
+## Ciclo de correção
+
+```
+Security Reviewer reprova → lista findings CRÍTICO/ALTO
+  → Coder da área correspondente recebe findings → corrige → recommit
+  → Security Reviewer reavalia APENAS os findings que falharam
+  → Aprovado? → prosseguir para E2E
+  → Reprovado de novo? → máximo 2 tentativas, depois escalar pro usuário
+```
+
+### Limite de retry: 2 tentativas
+Após 2 reprovações, o Security Reviewer para e reporta ao usuário:
+```
+⚠️ Security findings não resolvidos após 2 tentativas:
+1. [CRÍTICO] ...
+2. [ALTO] ...
+Ação necessária: intervenção manual ou revisão do SDD.
+```

package/templates/.claude/commands/design.md

@@ -0,0 +1,107 @@
+# /design $ARGUMENTS
+
+Skill atômica de design. Lê PRD/TRD aprovado e gera SDD.
+$ARGUMENTS = nome (ex: setup_projeto, feat_cadastro_cliente)
+
+## Agente: Architect (Opus)
+Técnico e preciso. Gera contratos completos. Toda decisão tem justificativa.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` existe com status `extract_done` ou `approved` | Se anterior → "/extract primeiro". Se posterior → "SDD já gerado" |
+| 3 | PRD.md ou TRD.md existe | Parar → "/extract primeiro" |
+| 4 | `docs/Estrutura/` populado (para features) | Parar → "/setup-projeto primeiro" (não aplica para tipo=setup) |
+
+## Passos
+
+### 1. Checkpoint de aprovação
+Se status é `extract_done`:
+- Perguntar: "O PRD/TRD foi revisado e está aprovado? (s/n)"
+- Se SIM → atualizar .context.md para `approved` → continuar
+- Se NÃO → parar
+
+### 2. Verificar ambiguidades
+- Ler seção de ambiguidades (§13 PRD / §9 TRD)
+- Se há perguntas sem resposta → PARAR, listar pendentes
+
+### 3. Gerar docs/Estrutura/ (APENAS para setup)
+
+> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
+
+Ler TRD e gerar os 8 docs de `docs/Estrutura/` usando os templates correspondentes:
+
+| TRD Seção | Doc gerado | Template |
+|-----------|-----------|---------|
+| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
+| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
+| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
+| §4 Modelo de Dados | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
+| §5 API | API.md | `_templates/estrutura/API.template.md` |
+| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
+| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
+| SDD §2 (após gerar) | ADRs.md | `_templates/estrutura/ADRs.template.md` |
+
+Regras:
+- Ler template → preencher TODAS seções com dados do TRD
+- Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
+- Changelog inicia vazio (primeira geração)
+- Se TRD não tem dados pra uma seção → marcar "A definir"
+- ADRs.md é gerado APÓS o SDD (usa §2 Decisões de Design)
+
+### 3b. Gerar `projetos.yaml` (APENAS para setup)
+
+Mapeia a arquitetura do TRD §3 para repositórios independentes.
+Cada serviço = 1 repo. Os repos serão criados/clonados pelo /dev (INFRA-001).
+
+1. Identificar serviços separados no TRD §3 (api, worker, web, mobile, etc.)
+2. Perguntar ao usuário:
+   - Organização/usuário do GitHub (ex: `empresa`)
+   - Nome base do projeto (ex: `meu-projeto`)
+   - Se algum repo já existe (para clonar em vez de criar)
+3. Gerar `projetos.yaml` na raiz usando template `projetos.template.yaml`
+4. Mapear áreas de task para repos:
+   - BACK → api (ou worker, se separado)
+   - BANCO → api (se usa EF migrations) ou repo próprio
+   - FRONT → web
+   - MOBILE → mobile
+   - INFRA → todos (cross-repo)
+5. Validar: cada área DEVE mapear para exatamente 1 repo
+
+**Regra**: Se o TRD indica API e Worker como serviços separados, DEVEM ser repos separados.
+Nunca juntar serviços que o TRD definiu como distintos.
+
+### 4. Carregar contexto
+- PRD.md ou TRD.md completo
+- `docs/Estrutura/` (agora já populado, mesmo no setup)
+- `docs/Desenvolvimento/rules.md`
+- Template `sdd.template.md`
+
+### 5. Gerar SDD
+11 seções obrigatórias (usar template). Para cada seção:
+- §1 Visão geral — escopo claro
+- §2 Decisões de design — mini-ADRs com justificativa
+- §3 Modelo de dados — tipos EXATOS, constraints, índices
+- §4 Regras e validações — ref PRD §N RN-NNN, mensagens de erro
+- §5 Endpoints API — contratos JSON completos, erros com códigos
+- §6 Componentes e telas — estados (loading/empty/error/success)
+- §7 Fluxos de dados — sequências front→back
+- §8 Integrações externas — timeout, retry, fallback
+- §9 Estratégia de testes — framework, estrutura, CAs mapeados
+- §10 Fora do escopo — lista explícita
+- §11 Delta Specs — ADDED/MODIFIED/REMOVED
+
+**Setup**: §4-§8 podem ser N/A (normal).
+**Feature**: todas seções aplicáveis preenchidas.
+
+### 6. Gerar ADRs.md (setup — complemento do passo 3)
+Após gerar SDD §2, criar ADRs.md com as decisões iniciais de arquitetura.
+
+### 7. Atualizar `.context.md`
+```yaml
+status: "design_done"
+ultima_skill: "/design"
+atualizado_em: "{{ISO_DATETIME}}"
+```

package/templates/.claude/commands/dev.md

@@ -0,0 +1,167 @@
+# /dev $ARGUMENTS
+
+Skill atômica de execução. Implementa tasks em loop até quality gate aprovado.
+$ARGUMENTS = nome (ex: feat_mvp)
+Flags opcionais: --fase 1 (RECOMENDADO) | --area banco | --task BACK-003
+
+## Agents por área (perfis em `.claude/agents/`)
+
+| Área | Agente | Stack | Modelo |
+|------|--------|-------|--------|
+| BANCO | DB Coder | PostgreSQL 16 | Sonnet (S/M) / Opus (L) |
+| BACK | Backend Coder | .NET 8 / C# | Sonnet (S/M) / Opus (L) |
+| FRONT | Frontend Coder | React + Fusion | Sonnet (S/M) / Opus (L) |
+| INFRA | Infra Coder | Docker | Sonnet (S/M) / Opus (L) |
+| DOC | Doc Writer | — | Sonnet |
+| Todas | Reviewer | — | Sonnet |
+| Todas | Security Reviewer | — | Opus |
+
+Agente selecionado pelo prefixo: BACK-* → Backend Coder, BANCO-* → DB Coder, etc.
+Ler o perfil do agente em `.claude/agents/` antes de implementar.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `plan_done` ou `dev_in_progress` | Se anterior → "/plan primeiro" |
+| 3 | `*_tasks.md` e `Progresso.md` existem | Parar |
+| 4 | `sdd.md` existe | Parar |
+| 5 | `rules.md` existe | Parar |
+| 6 | `projetos.yaml` existe | Parar → "Execute /design primeiro" |
+| 7 | Infra local rodando (`docker compose ps` → healthy) | Parar → "Suba a infra: `docker compose up -d`" |
+
+## Fluxo de execução
+
+```
+╔═══════════════════════════════════════════════╗
+║  LOOP POR TASK                                ║
+║                                               ║
+║  1. Selecionar agente pela área               ║
+║  2. Ler perfil do agente (.claude/agents/)    ║
+║  3. Implementar código + testes unit          ║
+║  4. Rodar testes unit                         ║
+║     → Falhou? Corrigir → volta pro 4          ║
+║     → 5 falhas? Parar, reportar               ║
+║  5. Rodar lint                                ║
+║     → Falhou? Corrigir → volta pro 5          ║
+║  6. Commit: tipo(TASK-ID): descrição          ║
+║  7. Review (quality gate)                     ║
+║     → Reprovado? Corrigir → volta pro 4       ║
+║     → 3 reprovações? Escalar pro usuário      ║
+║  8. Marcar task concluída ✅                   ║
+╚═══════════════════════════════════════════════╝
+        ↓ (todas tasks da fase)
+╔═══════════════════════════════════════════════╗
+║  VALIDAÇÃO POR FASE                           ║
+║  1. Rodar testes integration da área          ║
+║     → Falhou? Fix → loop (max 3)             ║
+╚═══════════════════════════════════════════════╝
+        ↓ (tudo concluído)
+╔═══════════════════════════════════════════════╗
+║  SECURITY REVIEW (cross-area)                 ║
+║  1. Security Reviewer audita todo código      ║
+║     → CRÍTICO/ALTO? Coder corrige → re-audit  ║
+║     → 2 falhas? Escalar pro usuário           ║
+║  2. Aprovado → prosseguir para E2E            ║
+╚═══════════════════════════════════════════════╝
+        ↓ (security aprovado)
+╔═══════════════════════════════════════════════╗
+║  VALIDAÇÃO POR FEATURE                        ║
+║  1. Rodar E2E (SDD §9.3 CAs)                 ║
+║     → Falhou? Identificar → fix → loop (max 3)║
+║  2. Tudo passou? → dev_done ✅                 ║
+╚═══════════════════════════════════════════════╝
+```
+
+## Multi-repo + Git Workflow
+
+### Contexto inicial
+- Ler `projetos.yaml` → mapeamento área → repo → path local
+- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
+
+### Passo 1 — Verificar working tree (OBRIGATÓRIO)
+Em cada repo afetado: `git status`
+- Se working tree sujo → sugerir commit ou stash antes de prosseguir
+- NUNCA começar a codar com working tree sujo
+
+### INFRA-001 (setup — primeira execução)
+No setup, INFRA-001 cria/clona os repos:
+- Ler `projetos.yaml` → para cada repo:
+  - Se `existing: true` → `git clone {repo} projetos/{name}`
+  - Se `existing: false` → criar repo (`gh repo create {repo} --private`) + clone
+- Criar estrutura base em cada repo (conforme stack)
+
+### Passo 2 — Branch por fase (NUNCA na main)
+Para cada repo afetado por esta fase:
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git checkout -b feature/{nome}_fase{N}
+```
+- NUNCA desenvolver direto na main
+
+## Implementação por task
+
+1. **Navegar**: ler campo `Repo:` da task → `cd projetos/{repo_path}/`
+2. **Ler**: task completa + seções do SDD referenciadas + perfil do agente + rules.md
+3. **Implementar**: código nos arquivos listados (caminhos relativos ao repo)
+4. **Testar**: testes unit nos arquivos de teste listados na task
+5. **Commit**: no repo do serviço — `tipo(TASK-ID): descrição curta`
+6. **Review**: quality gate (compilar, testes, lint, conformidade SDD, convenções)
+
+## Quality gate (Reviewer)
+
+| Check | Critério |
+|-------|----------|
+| Compila | Sem erros |
+| Testes unit | Passam |
+| Lint | Limpo |
+| Conformidade SDD | Contratos, tipos, regras conforme SDD |
+| Convenções | rules.md respeitado |
+| Sem TODOs | Injustificados |
+| Sem secrets | Hardcoded |
+| Arquivos corretos | Só os listados na task modificados |
+
+## Limites de retry
+
+| Nível | Limite | Ação ao exceder |
+|-------|--------|-----------------|
+| Test unit | 5 por task | Parar, reportar |
+| Review | 3 por task | Escalar pro usuário |
+| Integration | 3 por fase | Parar, reportar |
+| Security | 2 por feature | Escalar findings não resolvidos |
+| E2E | 3 por feature | Parar, reportar |
+
+## Passo 3 — Ao terminar fase: PR + ambiente ON
+
+1. Atualizar Progresso.md com status da fase
+2. Push da branch em cada repo: `git push origin feature/{nome}_fase{N}`
+3. Abrir PR com template detalhado (ver rules.md → Template de PR):
+   - Tasks concluídas, testes passando, como testar manualmente
+   - `gh pr create`
+4. Deixar ambiente local rodando:
+   - `docker compose up -d` (infra)
+   - `dotnet run` / `npm run dev` (apps nos repos)
+   - Informar URLs ao usuário
+5. **PARAR e aguardar** — merge é MANUAL pelo usuário
+
+## Passo 4 — Aguardar aprovação
+
+- O agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+
+## Passo 5 — Após merge (quando usuário confirmar)
+
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+## Atualizar `.context.md`
+```yaml
+status: "dev_in_progress"  # durante
+status: "dev_done"         # ao final (todas fases mergeadas)
+```