@girardelli/architect 2.2.0 → 5.0.0

package/src/agent-generator/templates/core/workflow-fix-bug.ts

@@ -0,0 +1,239 @@
+import { TemplateContext } from '../../types.js';
+
+/**
+ * Generates enterprise-grade fix-bug.md workflow.
+ * 10 steps: diagnosis → localization → root cause → RED test → fix → regression → docs.
+ */
+export function generateFixBugWorkflow(ctx: TemplateContext): string {
+  const { stack, projectName, config, report } = ctx;
+
+  return `---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Workflow completo para correção de bug em ${projectName}'
+---
+
+# 🐛 Workflow: Fix Bug
+
+> **Bugs não se corrigem por tentativa e erro.**
+> Diagnóstico rigoroso → reprodução → root cause → teste RED → fix → regressão.
+
+---
+
+## Pré-requisitos
+
+\`\`\`
+□ Li INDEX.md e PREFLIGHT.md
+□ Li LESSONS-LEARNED.md (se existir) — talvez esse bug já aconteceu
+□ Li ERROR-PATTERNS.md (se existir) — talvez é um padrão conhecido
+□ Estou em uma branch fix/ ou hotfix/ (NUNCA main/develop)
+□ Build e testes passando ANTES da minha alteração
+\`\`\`
+
+---
+
+## Step 1: Diagnóstico Inicial
+
+\`\`\`
+Bug: [descrição clara do problema]
+Reportado por: [quem reportou]
+Ambiente: [produção / staging / dev]
+Severidade: [CRITICAL / HIGH / MEDIUM / LOW]
+
+Comportamento atual: [o que acontece]
+Comportamento esperado: [o que deveria acontecer]
+Como reproduzir:
+  1. [passo 1]
+  2. [passo 2]
+  3. [resultado errado]
+\`\`\`
+
+---
+
+## Step 2: Leitura de Contexto
+
+\`\`\`bash
+# Verificar LESSONS-LEARNED para bugs similares
+grep -i "[termo do bug]" LESSONS-LEARNED.md 2>/dev/null
+
+# Verificar ERROR-PATTERNS
+grep -i "[termo do bug]" ERROR-PATTERNS.md 2>/dev/null
+
+# Verificar regras de negócio relevantes
+grep -i "[domínio do bug]" BUSINESS-RULES.md 2>/dev/null
+
+# Histórico de commits na área afetada
+git log --oneline -20 -- [arquivo ou diretório afetado]
+\`\`\`
+
+---
+
+## Step 3: Localização do Problema
+
+\`\`\`bash
+# Buscar no código
+grep -rn "[termo do erro]" --include="*.${stack.primary === 'Python' ? 'py' : stack.primary === 'Dart' ? 'dart' : 'ts'}" src/
+
+# Verificar logs (se disponível)
+# Verificar stack trace
+
+# Mapear o fluxo de dados:
+# Input → [onde entra] → [como transforma] → [onde sai] → Output
+\`\`\`
+
+\`\`\`
+Arquivo(s) suspeito(s): _______________
+Função/método suspeito: _______________
+Linha(s) suspeita(s): _______________
+\`\`\`
+
+---
+
+## Step 4: Root Cause — Identificação da Causa Raiz
+
+\`\`\`
+╔══════════════════════════════════════════════╗
+║  NUNCA corrigir o SINTOMA.                   ║
+║  SEMPRE encontrar a CAUSA RAIZ.              ║
+║                                               ║
+║  Técnica dos 5 Porquês:                      ║
+║  1. Por que o bug acontece? → porque...      ║
+║  2. Por que isso? → porque...                ║
+║  3. Por que isso? → porque...                ║
+║  4. Por que isso? → porque...                ║
+║  5. Por que isso? → CAUSA RAIZ               ║
+╚══════════════════════════════════════════════╝
+\`\`\`
+
+\`\`\`
+Causa raiz: _______________
+Confiança: [ ] Alta (reproduzi) [ ] Média (hipótese forte) [ ] Baixa (preciso investigar mais)
+\`\`\`
+
+> **Se confiança é Baixa → PARAR e investigar mais. Não chutar.**
+
+---
+
+## Step 5: Verificar Testes Existentes
+
+\`\`\`bash
+# Testes que cobrem a área afetada
+grep -rn "[nome da função/classe]" --include="*.test.*" --include="*.spec.*" tests/ src/
+
+# Rodar testes existentes
+${stack.testFramework === 'pytest' ? 'pytest -v -k "[nome do módulo]"' : stack.testFramework === 'flutter_test' ? 'flutter test test/[modulo]_test.dart' : 'npx jest --testPathPattern="[modulo]"'}
+\`\`\`
+
+\`\`\`
+□ Existem testes para a área afetada? [sim/não]
+□ Os testes passam? [sim/não]
+□ Os testes cobrem o cenário do bug? [sim/não — se não, criar no Step 6]
+\`\`\`
+
+---
+
+## Step 6: Criar Teste RED
+
+> **PRIMEIRO criar um teste que FALHA reproduzindo o bug.**
+> Só depois corrigir o código.
+
+\`\`\`
+Teste: [nome descritivo do teste]
+Input: [dados que reproduzem o bug]
+Expected: [resultado correto]
+Actual: [resultado errado — o teste deve FALHAR]
+\`\`\`
+
+\`\`\`bash
+# Rodar e confirmar que FALHA (RED)
+${stack.testFramework === 'pytest' ? 'pytest -v -k "[nome do teste]"' : 'npx jest --testNamePattern="[nome do teste]"'}
+# DEVE FALHAR ❌
+\`\`\`
+
+---
+
+## Step 7: Correção Mínima
+
+\`\`\`
+╔══════════════════════════════════════════════╗
+║  REGRA: Correção MÍNIMA.                     ║
+║                                               ║
+║  ✓ Corrigir APENAS a causa raiz              ║
+║  ✓ Menor quantidade de linhas possível       ║
+║  ✗ NÃO refatorar código adjacente            ║
+║  ✗ NÃO "aproveitar" para melhorar outra coisa║
+║  ✗ NÃO adicionar features junto com o fix    ║
+╚══════════════════════════════════════════════╝
+\`\`\`
+
+Após corrigir:
+\`\`\`bash
+# Rodar o teste do Step 6 — agora deve PASSAR (GREEN)
+${stack.testFramework === 'pytest' ? 'pytest -v -k "[nome do teste]"' : 'npx jest --testNamePattern="[nome do teste]"'}
+# DEVE PASSAR ✅
+\`\`\`
+
+---
+
+## Step 8: Teste de Regressão
+
+\`\`\`bash
+# Rodar TODOS os testes (não só o novo)
+${stack.testFramework === 'pytest' ? 'pytest' : stack.testFramework === 'flutter_test' ? 'flutter test' : 'npm run test'}
+
+# Build completo
+${stack.packageManager === 'npm' ? 'npm run build' : 'make build'}
+
+# Score
+npx @girardelli/architect score .
+\`\`\`
+
+\`\`\`
+□ Teste do bug passa (GREEN) ✓
+□ TODOS os outros testes passam ✓
+□ Build compila ✓
+□ Score não regrediu ✓
+\`\`\`
+
+---
+
+## Step 9: Verificação de Fluxos Existentes
+
+\`\`\`
+□ Verifiquei que features dependentes não foram afetadas
+□ Verifiquei edge cases relacionados
+□ Se o bug era em API → verifiquei clientes da API
+□ Se o bug era em banco → verifiquei migrations e seeds
+\`\`\`
+
+---
+
+## Step 10: Documentação
+
+\`\`\`
+□ Atualizar LESSONS-LEARNED.md:
+  - O que aconteceu
+  - Causa raiz
+  - Como foi corrigido
+  - Como prevenir no futuro
+
+□ Atualizar ERROR-PATTERNS.md (se é um padrão novo):
+  - Padrão do erro
+  - Sintomas
+  - Solução
+
+□ Commit com mensagem semântica:
+  fix: [descrição clara do que foi corrigido]
+
+□ PR criado com:
+  - Descrição do bug
+  - Causa raiz
+  - Solução aplicada
+  - Testes adicionados
+\`\`\`
+
+---
+
+**Gerado por Architect v3.1 · Score: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}

package/src/agent-generator/templates/core/workflow-new-feature.ts

@@ -0,0 +1,323 @@
+import { TemplateContext } from '../../types.js';
+
+/**
+ * Generates enterprise-grade new-feature.md workflow.
+ * 10 steps with approval gates, mockup-first, backend-first order,
+ * integration doc, coverage gate, user story/task templates.
+ */
+export function generateNewFeatureWorkflow(ctx: TemplateContext): string {
+  const { stack, projectName, config, report } = ctx;
+
+  return `---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Workflow completo para nova feature em ${projectName}'
+---
+
+# 🚀 Workflow: Nova Feature
+
+> **Este workflow é OBRIGATÓRIO para qualquer nova funcionalidade.**
+> Cada step tem um gate de aprovação. Pular steps é violação do protocolo.
+
+---
+
+## Pré-requisitos
+
+\`\`\`
+□ Li INDEX.md e entendi a estrutura do framework
+□ Li 00-general.md (Regras de Ouro)
+□ Li PREFLIGHT.md e completei TODAS as fases
+□ Li QUALITY-GATES.md e sei quais métricas atender
+□ Estou em uma branch feature/ (NUNCA main/develop)
+\`\`\`
+
+---
+
+## FASE 0: AÇÃO ZERO — Diagnóstico
+
+> **ANTES de qualquer coisa, fazer diagnóstico do estado atual.**
+
+\`\`\`bash
+# Estado do projeto
+git branch --show-current
+git status
+
+# Build e testes ANTES de começar
+${stack.packageManager === 'npm' ? 'npm run build && npm run test' : stack.testFramework === 'pytest' ? 'python -m pytest' : stack.testFramework === 'flutter_test' ? 'flutter test' : 'make test'}
+
+# Score atual
+npx @girardelli/architect score .
+
+# Ler lições aprendidas (se existir)
+cat LESSONS-LEARNED.md 2>/dev/null || echo "Sem lessons learned"
+
+# Regras de negócio (se existir)
+cat BUSINESS-RULES.md 2>/dev/null || echo "Sem business rules"
+\`\`\`
+
+\`\`\`
+□ Build passando ✓
+□ Testes passando ✓
+□ Score anotado: ___/100 (não pode regredir)
+□ Lessons learned lidos
+\`\`\`
+
+---
+
+## FASE 1: Diagnóstico da Feature
+
+\`\`\`
+Quero implementar [NOME DA FEATURE].
+
+Contexto:
+- Quem usa: [usuário / admin / sistema externo / ...]
+- Tem UI: [sim/não]
+- Tem API: [sim/não]
+- Tem banco: [sim/não]
+- Repo: [${ctx.projectName} / monorepo path / ...]
+
+Descrição:
+[2-3 frases do ponto de vista do usuário]
+
+Critérios de aceite:
+- CA1: [critério mensurável]
+- CA2: [critério mensurável]
+- CA3: [critério mensurável]
+\`\`\`
+
+---
+
+## Step 1: MOCKUP ${stack.hasFrontend || stack.hasMobile ? '(OBRIGATÓRIO)' : '(se tem UI)'}
+
+> **Gate 1 — Primeiro artefato. Nada começa sem mockup aprovado (quando tem UI).**
+
+\`\`\`
+╔══════════════════════════════════════════════════════╗
+║  O MOCKUP DEVE CONTER:                               ║
+║                                                       ║
+║  ✓ TODAS as telas/páginas envolvidas                 ║
+║  ✓ Estado: com dados (normal)                        ║
+║  ✓ Estado: vazio (empty state)                       ║
+║  ✓ Estado: carregando (loading)                      ║
+║  ✓ Estado: erro (error state)                        ║
+║  ✓ TODOS os modais / dialogs                         ║
+║  ✓ Mensagens de sucesso                              ║
+║  ✓ Mensagens de erro                                 ║
+║  ✓ Fluxo completo (passo a passo)                    ║
+║  ✓ Padrão visual do sistema (cores, fontes, layout)  ║
+${stack.hasFrontend ? '║  ✓ Responsividade (desktop + mobile se web)          ║\n' : ''}${stack.hasMobile ? '║  ✓ Padrão do app (navegação, header, bottom bar)     ║\n' : ''}║                                                       ║
+║  Formato: HTML interativo ou imagens anotadas        ║
+╚══════════════════════════════════════════════════════╝
+\`\`\`
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 2: User Stories
+
+> **Gate 2 — Histórias de usuário com critérios de aceite mensuráveis.**
+
+Formato:
+
+\`\`\`markdown
+## US-001: [Título]
+
+**Como** [ator],
+**Quero** [ação],
+**Para** [benefício].
+
+### Critérios de Aceite
+- CA1: [critério mensurável]
+- CA2: [critério mensurável]
+
+### Regras de Negócio
+- RN1: [regra]
+
+### Exceções
+- E1: Se [condição], então [comportamento]
+\`\`\`
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 3: Arquitetura (C4)
+
+> **Gate 3 — Visão técnica da implementação.**
+
+Usar template [C4.md](../templates/C4.md):
+
+\`\`\`
+Nível 1 — Contexto: Quem são os atores e sistemas externos?
+Nível 2 — Container: Quais serviços/apps são afetados?
+Nível 3 — Componente: Quais módulos/classes são criados/modificados?
+Nível 4 — Código: Interfaces, DTOs, entidades (se complexo)
+\`\`\`
+
+Se a decisão é significativa → criar ADR (template [ADR.md](../templates/ADR.md))
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 4: Task Breakdown
+
+> **Gate 4 — Lista de tarefas com estimativa.**
+
+Formato:
+
+\`\`\`markdown
+## TASK-001: [Título]
+- **US:** US-001
+- **Camada:** Backend / Frontend / App / Database
+- **Estimativa:** XS / S / M / L / XL
+- **Agente:** [quem executa]
+- **Deps:** [depende de TASK-XXX, se houver]
+\`\`\`
+
+Ordenar por dependência. Backend SEMPRE primeiro.
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 5: BDD (Cenários)
+
+> **Gate 5 — Cenários de comportamento para cada critério de aceite.**
+
+Formato (Gherkin):
+
+\`\`\`gherkin
+Feature: [Nome da Feature]
+
+  Scenario: [cenário happy path]
+    Given [contexto]
+    When [ação do usuário]
+    Then [resultado esperado]
+
+  Scenario: [cenário de erro]
+    Given [contexto]
+    When [ação inválida]
+    Then [mensagem de erro esperada]
+
+  Scenario: [cenário edge case]
+    Given [contexto específico]
+    When [ação]
+    Then [comportamento esperado]
+\`\`\`
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 6: TDD (Casos de Teste)
+
+> **Gate 6 — Casos de teste ANTES do código.**
+
+\`\`\`
+Para cada TASK:
+  1. Listar os testes que serão escritos
+  2. Descrever input → output esperado
+  3. Incluir testes de erro/exceção
+  4. Incluir testes de boundary
+
+Meta: Cobertura ≥ ${config.coverageMinimum}% (INEGOCIÁVEL)
+\`\`\`
+
+**Apresentar ao humano → Aguardar \`/approved\`**
+
+---
+
+## Step 7: Implementação — Backend
+
+> **SOMENTE após TODOS os 6 gates aprovados.**
+
+\`\`\`
+□ Criar/modificar entities e DTOs
+□ Criar/modificar services (lógica de negócio)
+□ Criar/modificar controllers (endpoints)
+□ Criar migrations (se houver alteração de banco)
+□ Escrever testes (RED → GREEN → REFACTOR)
+□ Rodar: build ✓ + tests ✓ + coverage ≥ ${config.coverageMinimum}% ✓
+\`\`\`
+
+---
+
+## Step 8: Documento de Integração
+
+> **OBRIGATÓRIO se tem frontend/app. Gerado APÓS backend completo.**
+
+\`\`\`markdown
+# Documento de Integração: [Feature]
+
+## Endpoints
+
+### [METHOD] /api/v1/[recurso]
+
+**Request:**
+\\\`\\\`\\\`json
+{
+  "campo": "tipo — descrição"
+}
+\\\`\\\`\\\`
+
+**Response (200):**
+\\\`\\\`\\\`json
+{
+  "campo": "tipo — descrição"
+}
+\\\`\\\`\\\`
+
+**Erros:**
+| Código | Mensagem | Quando |
+|--------|----------|--------|
+| 400 | Validation error | Input inválido |
+| 404 | Not found | Recurso inexistente |
+
+## Regras
+- [regra 1]
+- [regra 2]
+\`\`\`
+
+---
+
+## Step 9: Implementação — Frontend / App
+
+> **Baseado no Documento de Integração.**
+
+\`\`\`
+□ Criar/modificar componentes (seguir mockup)
+□ Implementar state management
+□ Integrar com endpoints (conforme doc de integração)
+□ Implementar TODOS os estados (loading, error, empty, data)
+□ Escrever testes (unitários + e2e se aplicável)
+□ Rodar: build ✓ + tests ✓ + coverage ≥ ${config.coverageMinimum}% ✓
+\`\`\`
+
+---
+
+## Step 10: Verificação Final
+
+\`\`\`
+╔════════════════════════════════════════════════╗
+║  CHECKLIST FINAL — TODOS devem ser ✓          ║
+║                                                ║
+║  □ Build compila sem erros                     ║
+║  □ TODOS os testes passam                      ║
+║  □ Cobertura ≥ ${String(config.coverageMinimum).padEnd(3)}%                         ║
+║  □ Score ≥ ${String(config.scoreThreshold).padEnd(3)}/100 (sem regressão)        ║
+║  □ Lint sem errors                             ║
+║  □ Zero anti-patterns CRITICAL novos           ║
+║  □ Todos os critérios de aceite cobertos       ║
+║  □ Documentação atualizada                     ║
+║  □ LESSONS-LEARNED atualizado (se aplicável)   ║
+║  □ PR criado com descrição completa            ║
+╚════════════════════════════════════════════════╝
+\`\`\`
+
+---
+
+**Gerado por Architect v3.1 · Score: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}

package/src/agent-generator/templates/core/workflow-review.ts

@@ -0,0 +1,106 @@
+import { TemplateContext } from '../../types.js';
+
+/**
+ * Generates enterprise-grade review.md workflow.
+ * Structured code review with checklist per dimension.
+ */
+export function generateReviewWorkflow(ctx: TemplateContext): string {
+  const { stack, projectName, config, report } = ctx;
+
+  return `---
+antigravity:
+  trigger: 'on_demand'
+  description: 'Workflow de code review estruturado para ${projectName}'
+---
+
+# 🔍 Workflow: Code Review
+
+> **Code review não é "LGTM".**
+> É uma verificação sistemática em 6 dimensões.
+
+---
+
+## Dimensão 1: Correção Funcional
+
+\`\`\`
+□ O código faz o que a US/task pede?
+□ Todos os critérios de aceite estão cobertos?
+□ Edge cases foram tratados?
+□ Erros são tratados adequadamente?
+□ Regras de negócio estão corretas?
+\`\`\`
+
+## Dimensão 2: Qualidade de Código
+
+\`\`\`
+□ Código legível sem comentários explicativos?
+□ Naming é descritivo e consistente?
+□ Sem duplicação (DRY)?
+□ Funções/métodos com responsabilidade única?
+□ Sem magic numbers (extrair para constantes)?
+□ Tipos corretos (sem \`any\` / \`type: ignore\` injustificado)?
+□ Sem código morto / comentado?
+\`\`\`
+
+## Dimensão 3: Testes
+
+\`\`\`
+□ Testes existem para o novo código?
+□ Cobertura ≥ ${config.coverageMinimum}%?
+□ Testes são significativos (não apenas \`expect(true).toBe(true)\`)?
+□ Happy path coberto?
+□ Error path coberto?
+□ Edge cases cobertos?
+□ Nenhum teste com .skip() injustificado?
+\`\`\`
+
+## Dimensão 4: Segurança
+
+\`\`\`
+□ Sem secrets hardcoded?
+□ Input validado e sanitizado?
+□ SQL injection prevenido (parameterized queries)?
+□ XSS prevenido (output encoding)?
+□ Autenticação/autorização verificada?
+□ Dados sensíveis não logados?
+□ Rate limiting em endpoints novos?
+\`\`\`
+
+## Dimensão 5: Performance
+
+\`\`\`
+□ Sem N+1 queries?
+□ Queries com índice adequado?
+□ Sem loops desnecessários sobre coleções grandes?
+□ Lazy loading onde aplicável?
+□ Sem memory leaks óbvios (subscriptions, listeners)?
+□ Caching considerado onde faz sentido?
+\`\`\`
+
+## Dimensão 6: Arquitetura
+
+\`\`\`
+□ Segue os padrões do projeto (rules/)?
+□ Camada correta (controller ≠ service ≠ entity)?
+□ Sem violações de layer (data layer acessando UI)?
+□ Score não regrediu: architect score ≥ ${config.scoreThreshold}/100
+□ Sem novos anti-patterns CRITICAL?
+□ Imports organizados, sem circulares?
+\`\`\`
+
+---
+
+## Resultado do Review
+
+| Resultado | Ação |
+|-----------|------|
+| ✅ Aprovado | Merge permitido |
+| ⚠️ Aprovado com observações | Merge permitido, fix no próximo PR |
+| ❌ Mudanças necessárias | Bloquear merge até resolver |
+| 🔴 Bloqueado | Issue de segurança ou regressão — resolver imediatamente |
+
+---
+
+**Gerado por Architect v3.1 · Score: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}