kakaroto-config 1.0.5 → 1.0.6

package/config/commands/feature/04-red.md

@@ -0,0 +1,160 @@
+# Fase 4: RED (Escrever Testes)
+
+> **REGRA:** Testes devem FALHAR. Imports inexistentes OK. NÃO escreva código de produção.
+
+## Responsabilidade
+Escrever testes que FALHAM baseados no contract. Execução AUTÔNOMA.
+
+---
+
+## Passo 1: Carregar Contexto
+
+```
+Read {state.contract}   # Critérios aprovados + mitigações
+Read {state.analysis}   # Mapa: testes existentes, código a reutilizar
+```
+
+Listar factories/mocks disponíveis:
+- test-utils/factories/ → nomes
+- test-utils/mocks/ → nomes
+
+---
+
+## Passo 2: Isolar Contexto (CRUCIAL)
+
+**DESCARTAR da memória:**
+- Código de produção
+- Patterns de implementação
+- Como funções são implementadas
+
+**RETER apenas:**
+- Critérios do contract (O QUE testar)
+- Nomes de factories/mocks (COMO isolar)
+- Mapa de testes existentes (ONDE colocar)
+
+> **Objetivo:** Testar COMPORTAMENTO, não IMPLEMENTAÇÃO.
+
+---
+
+## Passo 3: Escrever Testes
+
+### 3.1 Decisão de Local
+
+| Resultado no Analysis | Ação |
+|----------------------|------|
+| Teste existe para módulo | ESTENDER arquivo existente |
+| Arquivo existe, caso não | ADICIONAR describe/it |
+| Nenhum existe | CRIAR novo arquivo |
+
+### 3.2 Estrutura (via Playbook)
+
+Carregar playbook de testes conforme tipo da feature:
+
+```
+Read ~/.claude/commands/feature/playbooks/{featureType}/red.md
+```
+
+| featureType | Playbook |
+|-------------|----------|
+| api | playbooks/api/red.md |
+| ui | playbooks/ui/red.md |
+| service | playbooks/service/red.md |
+| job | playbooks/job/red.md |
+
+O playbook define:
+- Testes requeridos (Unit/Integration/E2E)
+- Mocks tipicos
+- Test patterns com vitest
+
+### 3.3 Regras
+
+- Imports inexistentes OK (vão falhar - RED)
+- Usar factories de test-utils/factories/
+- Usar mocks de test-utils/mocks/
+- 1 critério do contract → 1+ testes
+- **APENAS Unit e Integration tests** (E2E é validado em 07-validation)
+
+---
+
+## Passo 4: Sufficiency Gate
+
+Usar `mcp__sequential-thinking__sequentialthinking`:
+
+Verificar apenas critérios Unit/Integration (E2E é separado):
+
+| # | Critério (Unit/Integration) | Teste Escrito | Coberto? |
+|---|----------------------------|---------------|----------|
+| 1 | "{critério}" | it('...') | ✓/✗ |
+
+**SE** cobertura < 100%:
+- Identificar critérios faltantes
+- Voltar ao Passo 3
+- Adicionar testes
+
+**SE** cobertura == 100%:
+- Prosseguir
+
+---
+
+## Passo 5: Verificar RED
+
+```bash
+npm test -- --testPathPattern="[feature]" 2>&1 || true
+```
+
+| Resultado | Ação |
+|-----------|------|
+| Todos FALHAM | Correto - prosseguir |
+| Alguns passam | Investigar (já existe implementação?) |
+| Erro de sintaxe | Corrigir teste e re-run |
+
+---
+
+## Passo 6: Commit RED
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+test: add tests for [feature] (RED)
+
+Tests expected to fail - implementation pending.
+Coverage: {N} criteria from contract.
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+SLUG=$(jq -r '.feature' .claude/workflow-state.json 2>/dev/null)
+
+# Pré-condição
+test -f ".claude/contracts/${SLUG}.md" || { echo "❌ Pré: contract não existe"; exit 1; }
+
+# Pós-condição: Commit RED existe
+git log -1 --format="%s" | grep -q "test:.*RED" || { echo "❌ Commit RED não encontrado"; exit 1; }
+
+echo "✅ Gate 04-red passou"
+```
+
+---
+
+## Passo 7: Atualizar Estado
+
+```bash
+jq '
+  .currentPhase = "05-green" |
+  .completedPhases += ["04-red"] |
+  .resumeHint = "Testes RED commitados. Prox: implementar código mínimo" |
+  .lastStep = "Passo 7: Atualizar Estado"
+' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/05-green.md

package/config/commands/feature/05-green.md

@@ -0,0 +1,179 @@
+# Fase 5: GREEN (Implementar)
+
+> **REGRA:** Código MÍNIMO para testes passarem. Sem validações extras, abstrações ou otimizações.
+
+## Responsabilidade
+Implementar código MÍNIMO para testes passarem. Execução AUTÔNOMA.
+
+---
+
+## Passo 1: Carregar Contexto
+
+```bash
+# Testes que falharam
+git diff HEAD~1 --name-only | grep "\.test\.ts$"
+```
+
+```
+Read {state.analysis}   # Código existente a reutilizar
+Read {state.contract}   # Mitigações acordadas
+```
+
+---
+
+## Passo 2: Planejar Tarefas
+
+### 2.1 Mapear Testes → Código
+
+| Teste | Código Necessário | Reutiliza? | Arquivo |
+|-------|-------------------|------------|---------|
+| it('A') | função X | helper.ts:20 | ESTENDER |
+| it('B') | função Y | - | CRIAR |
+| it('C') | função Z | utils.ts | REUTILIZAR |
+
+### 2.2 Incluir Mitigações
+
+Do contract, seção "Cenários Excluídos":
+
+| Mitigação | Implementação | Arquivo |
+|-----------|---------------|---------|
+| try/catch para API | wrap em try/catch + log | handler.ts |
+| Schema validation | zod schema | types.ts |
+
+### 2.3 Ordenar
+
+1. Dependências primeiro (tipos, utils)
+2. Funções principais
+3. Mitigações
+
+---
+
+## Passo 3: Implementar (Loop por Teste)
+
+Para cada teste falhando:
+
+```
+┌─────────────────────────────────────────┐
+│  1. TodoWrite: marcar in_progress       │
+│  2. Implementar código MÍNIMO           │
+│  3. tsc --noEmit                        │
+│  4. npm test -- --testPathPattern="X"   │
+│  5. SE passou → TodoWrite: completed    │
+│     SE falhou → corrigir (max 3x)       │
+│  6. Próximo teste                       │
+└─────────────────────────────────────────┘
+```
+
+### O que é "Código Mínimo"?
+
+**FAZER:**
+- Exatamente o que teste espera
+- Estruturas simples e elegantes
+- Reutilizar código existente
+
+**NÃO FAZER:**
+- Validações além do testado
+- Abstrações "por precaução"
+- Otimizações prematuras
+- Refactoring (fase 6)
+
+---
+
+## Passo 4: Validar GREEN
+
+### 4.1 Testes
+
+```bash
+npm test
+```
+
+### 4.2 TypeScript
+
+```bash
+npx tsc --noEmit
+```
+
+### 4.3 Mitigações
+
+Checklist do contract:
+- [ ] Todas mitigações implementadas?
+- [ ] Logging para cenários não testados?
+- [ ] Schemas validam inputs de risco?
+
+### 4.4 Loop de Correção
+
+```
+while (falhas AND tentativas < 3):
+    Identificar erro
+    Corrigir CÓDIGO (não teste)
+    Re-run
+    tentativas++
+
+if ainda falha:
+    PARAR e reportar ao user
+```
+
+---
+
+## Passo 5: Commit GREEN
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+feat: implement [feature]
+
+- All tests passing
+- Mitigations implemented
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+# Testes passam
+npm test || { echo "❌ Testes falhando"; exit 1; }
+
+# TypeScript compila
+npx tsc --noEmit || { echo "❌ TypeScript não compila"; exit 1; }
+
+echo "✅ Gate 05-green passou"
+```
+
+---
+
+## Output
+
+```markdown
+## GREEN Phase - Completo
+
+**Testes:** X/X passando
+
+**Arquivos modificados:**
+- [lista]
+
+**Mitigações implementadas:**
+- [lista]
+```
+
+---
+
+## Passo 6: Atualizar Estado
+
+```bash
+jq '
+  .currentPhase = "06-quality" |
+  .completedPhases += ["05-green"] |
+  .resumeHint = "GREEN completo. Prox: quality gate (refactoring)" |
+  .lastStep = "Passo 6: Atualizar Estado"
+' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/06-quality.md

package/config/commands/feature/06-quality.md

@@ -0,0 +1,109 @@
+# Fase 6: Quality
+
+## Responsabilidade
+REFACTOR do ciclo TDD + Quality Gate.
+
+---
+
+## Passo 1: Refactoring Agents
+
+### 1.1 Code Simplifier
+```javascript
+Task({
+  subagent_type: "code-simplifier",
+  prompt: `Verificar reuso (DRY). Detectar duplicacoes. Simplificar.
+
+REGRA PARA .test.ts - FACTORIES:
+- SE objetos inline representando entidades
+- E factory existe em test-utils/factories/
+- ENTAO substituir por factory
+- Validar com npm test
+- Reverter se falhar`,
+  description: "Simplify and DRY check"
+})
+```
+
+### 1.2 Code Reviewer
+```javascript
+Task({
+  subagent_type: "code-reviewer",
+  prompt: "Review final. Verificar qualidade, seguranca, patterns. Corrigir issues.",
+  description: "Final code review"
+})
+```
+
+---
+
+## Passo 2: Verificar Testes Pos-Refactoring
+
+```bash
+npm test 2>&1
+```
+
+| Resultado | Acao |
+|-----------|------|
+| Todos passam | Pular para Passo 3 (Final Gate) |
+| Algum falhou | Executar Recovery |
+
+### Recovery (SE FAIL)
+
+1. Identificar causa
+2. Verificar diff do agent
+3. Decidir: reverter ou corrigir
+4. Re-run
+5. Max 2 tentativas
+
+---
+
+## Passo 3: Final Gate
+
+```bash
+npm test && npx tsc --noEmit && npm run build
+```
+
+### Self-Healing Loop
+
+```
+tentativas = 0
+while (gate falhando AND tentativas < 2):
+    1. Identificar erro
+    2. Analisar causa
+    3. Corrigir
+    4. Re-run
+    tentativas++
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+# Testes passam
+npm test || { echo "❌ Testes falhando"; exit 1; }
+
+# TypeScript compila
+npx tsc --noEmit || { echo "❌ TypeScript não compila"; exit 1; }
+
+# Build funciona
+npm run build || { echo "❌ Build falhou"; exit 1; }
+
+echo "✅ Gate 06-quality passou"
+```
+
+---
+
+## Passo 4: Atualizar Estado
+
+```bash
+jq '
+  .currentPhase = "07-validation" |
+  .completedPhases += ["06-quality"] |
+  .resumeHint = "Quality completo. Prox: E2E validation" |
+  .lastStep = "Passo 4: Atualizar Estado"
+' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/07-validation.md

package/config/commands/feature/07-validation.md

@@ -0,0 +1,168 @@
+# Fase 7: Validation
+
+## Responsabilidade
+E2E Validation - verificar que feature funciona no mundo real.
+
+---
+
+## Passo 1: Pre-flight Check (BLOCKING)
+
+```bash
+# Ler contract path do state
+CONTRACT=$(jq -r '.contract' .claude/workflow-state.json)
+
+# Verificar que contract existe e tem E2E spec
+if [ ! -f "$CONTRACT" ]; then
+  echo "❌ GATE BLOQUEADO: Contract não encontrado em $CONTRACT"
+  echo "Execute fase 03-strategy para criar contract"
+  exit 1
+fi
+
+if ! grep -q "## E2E Validation" "$CONTRACT"; then
+  echo "❌ GATE BLOQUEADO: E2E Validation spec não encontrada no contract"
+  exit 1
+fi
+```
+
+---
+
+## Passo 2: Carregar Playbooks
+
+```javascript
+// Carregar base E2E concepts
+Read("~/.claude/commands/feature/playbooks/_e2e-base.md")
+
+// Carregar E2E template especifico do tipo
+Read("~/.claude/commands/feature/playbooks/{featureType}/e2e.md")
+
+// Carregar contract com spec
+Read({state.contract})  // path do workflow-state.json
+// Extrair: e2e_type, e2e_spec
+```
+
+---
+
+## Passo 3: Executar E2E por Tipo
+
+### SE auto:
+1. Rodar script/Playwright conforme spec
+   ```bash
+   {comando do spec}
+   ```
+2. Reportar resultado
+
+### SE semi-auto:
+1. Disparar trigger (API call conforme spec)
+2. Poll resultado (max 10x, interval 5s)
+   ```javascript
+   for (let i = 0; i < 10; i++) {
+     const result = await checkCondition();
+     if (result.success) break;
+     await sleep(5000);
+   }
+   ```
+3. Verificar criterio de sucesso
+4. Reportar: "E2E Semi-auto: PASSOU" ou "FALHOU: {motivo}"
+
+### SE hybrid:
+1. Solicitar acao do user:
+   ```javascript
+   AskUserQuestion({
+     questions: [{
+       question: "{acao_do_spec}. Responda quando terminar.",
+       header: "Acao Manual",
+       options: [
+         { label: "Feito", description: "Executei a acao" },
+         { label: "Nao consigo", description: "Problema ao executar" }
+       ],
+       multiSelect: false
+     }]
+   })
+   ```
+2. User responde "Feito"
+3. Claude executa verificacoes do spec
+4. Reportar: "E2E Hybrid: PASSOU" ou "FALHOU: {motivo}"
+
+---
+
+## Passo 4: Self-Healing Loop (SE FALHOU)
+
+### 4.1 Classificar Falha
+
+| Tipo | Exemplos | Acao |
+|------|----------|------|
+| CORRIGIVEL | Bug no código, timeout config, query errada | Corrigir automaticamente |
+| EXTERNO | Rede, serviço offline, credenciais | Reportar e parar |
+
+### 4.2 Loop Automatico (max 2 tentativas)
+
+```
+while (falhando AND tentativas < 2 AND tipo == CORRIGIVEL):
+    1. Analisar causa
+    2. Corrigir código/config/spec
+    3. Re-run E2E
+    tentativas++
+```
+
+### 4.3 Escape Hatch (SE ainda falha)
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "E2E falhou após self-healing. O que fazer?",
+    header: "E2E Failed",
+    options: [
+      { label: "Debugar", description: "Executar /debug workflow" },
+      { label: "Continuar", description: "Marcar FAILED e prosseguir" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+---
+
+## Passo 5: Atualizar Contract
+
+```javascript
+// Atualizar contract (path do state.contract)
+// Mudar E2E Status: PENDING → PASSED | FAILED
+Edit({
+  file_path: {state.contract},
+  old_string: "**Status:** PENDING",
+  new_string: "**Status:** {PASSED | FAILED}"
+})
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+# E2E deve ter sido executado
+CONTRACT=$(jq -r '.contract' .claude/workflow-state.json)
+if ! grep -q "Status:.*PASSED\|Status:.*FAILED" "$CONTRACT" 2>/dev/null; then
+  echo "❌ GATE BLOQUEADO: E2E Validation não executada"
+  exit 1
+fi
+
+echo "✅ Gate 07-validation passou"
+```
+
+---
+
+## Passo 6: Atualizar Estado
+
+```bash
+jq '
+  .currentPhase = "08-delivery" |
+  .completedPhases += ["07-validation"] |
+  .resumeHint = "E2E validado. Prox: commit e push" |
+  .lastStep = "Passo 6: Atualizar Estado"
+' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/08-delivery.md

package/config/commands/feature/08-delivery.md

@@ -0,0 +1,86 @@
+# Fase 8: Delivery
+
+## Responsabilidade
+Entregar código validado (commit + push + memory sync).
+
+---
+
+## Passo 1: Verificar Estado
+
+```bash
+git status
+git diff --stat
+```
+
+---
+
+## Passo 2: Commit
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+{type}: {descricao concisa em ingles}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Tipos:** feat, fix, refactor, docs, test
+
+---
+
+## Passo 3: Push
+
+```bash
+git push
+```
+
+---
+
+## Passo 4: Memory Sync
+
+```javascript
+Task({
+  subagent_type: "memory-sync",
+  prompt: "Sincronizar knowledge graph. Skip se trivial.",
+  description: "Sync memory graph"
+})
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+# 1. Commit deve existir com formato válido
+git log -1 --format="%s" | grep -qE "^(feat|fix|refactor|test|docs):" || {
+  echo "❌ GATE BLOQUEADO: Commit não criado ou formato inválido"
+  exit 1
+}
+
+# 2. Push deve estar feito (branch remota atualizada)
+git status | grep -q "Your branch is up to date\|nothing to commit" || {
+  echo "⚠️ AVISO: Mudanças locais não pushadas"
+}
+
+echo "✅ Gate 08-delivery passou"
+```
+
+---
+
+## Passo 5: Atualizar Estado
+
+```bash
+jq '
+  .currentPhase = "09-evaluate" |
+  .completedPhases += ["08-delivery"] |
+  .resumeHint = "Feature entregue. Prox: auto-avaliacao do workflow" |
+  .lastStep = "Passo 5: Atualizar Estado"
+' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/09-evaluate.md