kakaroto-config 1.0.4 → 1.0.6

package/config/commands/feature/01-understand.md

@@ -0,0 +1,217 @@
+# Fase 1: Understand
+
+## Responsabilidade
+Coletar requisitos com o USER.
+
+---
+
+## Passo 0: Detectar Workflow Existente
+
+```bash
+if [ -f .claude/workflow-state.json ]; then
+  phase=$(jq -r '.currentPhase' .claude/workflow-state.json 2>/dev/null)
+  if [ "$phase" != "COMPLETED" ]; then
+    echo "Workflow existente: $phase"
+    echo "Para continuar: Read arquivo em currentPhaseFile"
+    echo "Para novo: prossiga (state sera sobrescrito)"
+  fi
+fi
+```
+
+---
+
+## Passo 1: Analisar Request
+
+Identificar em $ARGUMENTS:
+- Feature solicitada
+- Termos-chave para busca
+- Area provavel (api/, components/, services/)
+
+---
+
+## Passo 2: Buscar Contexto
+
+### 2.1 Memory (sob demanda)
+```
+mcp__memory__search_nodes({ query: "<termos-da-feature>" })
+```
+
+### 2.2 Codebase
+```
+Grep: termos em <area>/
+Read: arquivos diretamente relacionados
+```
+
+---
+
+## Passo 3: Reflexao (ST)
+
+Usar `mcp__sequential-thinking__sequentialthinking`:
+
+1. **O que descobri** - Sintese do contexto
+2. **O que ainda posso descobrir** - Gaps que consigo preencher
+3. **Qual o MVP?** - Escopo MINIMO que resolve
+4. **O que APENAS o user sabe** - Decisoes de produto
+5. **Perguntas minimas para o user** - So o essencial
+
+`totalThoughts`: 5
+
+---
+
+## Passo 4: Perguntas ao User (AUQ)
+
+Usar `AskUserQuestion` com 2-4 perguntas consolidadas.
+
+**Perguntas tipicas (adaptar):**
+- **Problema**: Qual problema resolve? (Eficiencia/Funcionalidade/UX)
+- **Escopo**: MVP ou feature completa?
+- **Design**: Referencia ou patterns existentes?
+- **Prioridade**: O que e mais importante?
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Qual problema principal esta feature resolve?",
+      header: "Problema",
+      options: [
+        { label: "Eficiencia", description: "Automatizar/acelerar processo" },
+        { label: "Funcionalidade", description: "Adicionar capacidade nova" },
+        { label: "UX", description: "Melhorar experiencia existente" }
+      ],
+      multiSelect: false
+    },
+    // ... outras perguntas
+  ]
+})
+```
+
+---
+
+## Passo 5: Criterios de Aceite (AUQ)
+
+Coletar do user como validar sucesso/falha:
+
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Como voce saberia que esta funcionando?",
+      header: "Validacao",
+      options: [
+        { label: "Output especifico", description: "Retorna X, exibe Y na tela" },
+        { label: "Side effect", description: "Salva no DB, posta na rede social" },
+        { label: "Ausencia de erro", description: "Nao quebra, nao loga erro" }
+      ],
+      multiSelect: true
+    },
+    {
+      question: "O que seria uma falha inaceitavel?",
+      header: "Falha Critica",
+      options: [
+        { label: "Dados corrompidos", description: "Salva errado, perde dados" },
+        { label: "Erro silencioso", description: "Falha sem avisar user" },
+        { label: "Acao duplicada", description: "Posta 2x, cobra 2x" }
+      ],
+      multiSelect: true
+    }
+  ]
+})
+```
+
+---
+
+## Passo 6: Persistir Interview
+
+### 6.1 Gerar slug
+`{primeira-palavra}-{YYYY-MM-DD}.md`
+
+### 6.2 Salvar
+```
+Write .claude/interviews/{slug}.md
+```
+
+### 6.3 Formato
+```markdown
+# Interview: {feature}
+
+## Request (Passo 1)
+- **Feature:** {$ARGUMENTS}
+- **Area:** {api/components/services}
+- **Termos-chave:** {lista}
+
+## Descoberta (Passo 2)
+- **Services:** {lista}
+- **Patterns:** {lista}
+- **Memory:** {entidades relevantes ou "N/A"}
+
+## Reflexao (Passo 3)
+- **Escopo:** {MVP | Completo}
+- **Decisoes Implicitas:**
+  | Decisao | Justificativa |
+  |---------|---------------|
+  | {o que assumiu} | {por que} |
+
+## Perguntas e Respostas (Passo 4)
+| # | Pergunta | Resposta | Impacto |
+|---|----------|----------|---------|
+
+## Criterios de Aceite do User (Passo 5)
+| # | Criterio | Tipo | Verificacao |
+|---|----------|------|-------------|
+| U1 | "{criterio especifico}" | SUCESSO | {output/side-effect/ausencia} |
+| U2 | "{criterio especifico}" | FALHA | {o que NAO pode acontecer} |
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+SLUG=$(jq -r '.feature' .claude/workflow-state.json 2>/dev/null)
+[ -z "$SLUG" ] || [ "$SLUG" = "null" ] && { echo "❌ workflow-state.json sem feature definida"; exit 1; }
+
+INTERVIEW=".claude/interviews/${SLUG}.md"
+
+test -f "$INTERVIEW" || { echo "❌ Interview não encontrada: $INTERVIEW"; exit 1; }
+
+# Seções obrigatórias (ordem do fluxo)
+grep -q "## Request" "$INTERVIEW" || { echo "❌ Interview sem Request"; exit 1; }
+grep -q "## Descoberta" "$INTERVIEW" || { echo "❌ Interview sem Descoberta"; exit 1; }
+grep -q "## Perguntas e Respostas" "$INTERVIEW" || { echo "❌ Interview sem Q&A"; exit 1; }
+grep -q "## Criterios de Aceite do User" "$INTERVIEW" || { echo "❌ Interview sem Criterios"; exit 1; }
+
+# Validar que Critérios tem conteúdo (não apenas header)
+grep -A1 "## Criterios de Aceite do User" "$INTERVIEW" | grep -q "| U" || { echo "❌ Criterios sem entradas (precisa U1, U2...)"; exit 1; }
+
+echo "✅ Gate 01-understand passou"
+```
+
+---
+
+## Passo 7: Persistir Estado do Workflow
+
+```bash
+mkdir -p .claude
+cat > .claude/workflow-state.json << 'EOF'
+{
+  "workflow": "feature",
+  "feature": "${FEATURE_SLUG}",
+  "currentPhase": "02-analyze",
+  "completedPhases": ["01-understand"],
+  "startedAt": "${TIMESTAMP}",
+  "resumeHint": "Interview coletada. Prox: triage tipo (api/ui/service/job) e carregar playbook",
+  "lastStep": "Passo 7: Persistir Estado",
+  "interview": ".claude/interviews/${FEATURE_SLUG}.md",
+  "analysis": null,
+  "contract": null
+}
+EOF
+```
+
+**Nota:** Substituir `${FEATURE_SLUG}` pelo slug real e `${TIMESTAMP}` por `date -u +%Y-%m-%dT%H:%M:%SZ`
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/02-analyze.md

package/config/commands/feature/02-analyze.md

@@ -0,0 +1,168 @@
+# Fase 2: Analyze
+
+## Responsabilidade
+Explorar codebase e determinar estrategia de teste. Fase INTERNA (sem interacao com user).
+
+---
+
+## Passo 1: Triage de Tipo
+
+Analisar feature e classificar:
+
+| Keyword | Tipo | Playbook |
+|---------|------|----------|
+| endpoint, handler, route, API | api | playbooks/api/ |
+| component, page, form, modal, hook | ui | playbooks/ui/ |
+| service, util, transform, validate | service | playbooks/service/ |
+| cron, job, scheduler, executor | job | playbooks/job/ |
+
+**SE multiplos tipos:** Escolher o DOMINANTE (onde maior parte do codigo ficara).
+
+---
+
+## Passo 2: Carregar Playbook
+
+```
+Read ~/.claude/commands/feature/playbooks/{tipo}/analyze.md
+```
+
+O playbook define:
+- Onde codigo fica
+- Pattern de producao
+- Criterios de testabilidade
+
+---
+
+## Passo 3: Buscar Codigo Existente
+
+### 3.1 Patterns Similares
+```
+Grep: termos em {localizacao-do-playbook}/
+```
+
+### 3.2 Codigo Reutilizavel
+| Necessidade | Codigo Existente | Acao |
+|-------------|------------------|------|
+| [o que precisa] | [arquivo:linha] | Reutilizar/Estender/Criar |
+
+---
+
+## Passo 4: Mapear Mocks
+
+### 4.1 Consultar Existentes
+```
+Read test-utils/mocks/README.md
+```
+
+### 4.2 Verificar Disponibilidade
+| Servico | Mock Existe? | Acao |
+|---------|--------------|------|
+| Database | Verificar | - |
+| [externo] | Verificar | Criar se necessario |
+
+---
+
+## Passo 5: Avaliar Testabilidade
+
+Baseado no playbook carregado:
+
+| Tipo Teste | Requerido? | Motivo |
+|------------|------------|--------|
+| Unit | {do playbook} | {motivo} |
+| Integration | {do playbook} | {motivo} |
+| E2E | {do playbook} | {motivo} |
+
+---
+
+## Passo 6: Cenarios Tecnicos Descobertos
+
+Baseado na exploracao (Passos 3-5), identificar cenarios de falha EVIDENTES no codigo.
+
+### 6.1 Analise do Codigo Existente
+
+Para cada dependencia/input encontrado, verificar:
+- Existe tratamento de erro? (try/catch, .catch, fallback)
+- Existe validacao? (Zod, type guards)
+- Existe retry/circuit breaker?
+
+### 6.2 Documentar Cenarios
+
+| # | Cenario | Categoria | Fonte | Tratado? |
+|---|---------|-----------|-------|----------|
+| T1 | {cenario evidente} | {INPUT/DEPENDENCY/STATE} | {arquivo:linha} | Sim/Nao |
+
+**Categorias**: INPUT, DEPENDENCY, STATE, ENVIRONMENT
+
+> **Regra:** Documentar APENAS cenarios EVIDENTES do codigo.
+
+---
+
+## Passo 7: Persistir Analise
+
+### 7.1 Salvar
+```
+Write .claude/analysis/{slug}.md
+```
+
+### 7.2 Formato
+```markdown
+# Analise: {feature}
+
+## Metadata
+- **Tipo:** {api/ui/service/job}
+- **Playbook:** {arquivo}
+
+## Mocks Mapeados
+| Servico | Existe? | Acao |
+|---------|---------|------|
+
+## Testes Existentes
+| Pattern | Arquivos |
+|---------|----------|
+
+## Cenarios Tecnicos Descobertos
+| # | Cenario | Categoria | Fonte | Tratado? |
+|---|---------|-----------|-------|----------|
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+SLUG=$(jq -r '.feature' .claude/workflow-state.json 2>/dev/null)
+
+# Pré-condição
+test -f ".claude/interviews/${SLUG}.md" || { echo "❌ Pré-condição falhou: interview não existe"; exit 1; }
+
+# Pós-condição
+test -f ".claude/analysis/${SLUG}.md" || { echo "❌ Análise não encontrada: .claude/analysis/${SLUG}.md"; exit 1; }
+grep -q "## Metadata" ".claude/analysis/${SLUG}.md" || { echo "❌ Análise incompleta (falta Metadata)"; exit 1; }
+
+echo "✅ Gate 02-analyze passou"
+```
+
+**Nota:** Esta fase NAO para. Execução automática para 03-strategy.
+
+---
+
+## Passo 8: Atualizar Estado do Workflow
+
+```bash
+if command -v jq &> /dev/null; then
+  jq '
+    .currentPhase = "03-strategy" |
+    .completedPhases += ["02-analyze"] |
+    .resumeHint = "Analise completa. Prox: apresentar testes propostos para aprovacao (UNICA parada)" |
+    .lastStep = "Passo 8: Atualizar Estado" |
+    .analysis = (".claude/analysis/" + .feature + ".md")
+  ' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+else
+  echo "Atualizar .claude/workflow-state.json: currentPhase=03-strategy, add 02-analyze to completedPhases"
+fi
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/03-strategy.md

package/config/commands/feature/03-strategy.md

@@ -0,0 +1,300 @@
+# Fase 3: Strategy
+
+## Responsabilidade
+Aprovar estrategia de testes. **UNICA APROVACAO** do workflow.
+
+---
+
+## Passo 1: Carregar Inputs
+
+### 1.1 Criterios do User (01-understand)
+```
+Read .claude/interviews/${SLUG}.md → secao "## Criterios de Aceite do User"
+```
+
+### 1.2 Cenarios Tecnicos (02-analyze)
+```
+Read .claude/analysis/${SLUG}.md → secao "## Cenarios Tecnicos Descobertos"
+```
+
+### 1.3 Tipo da Feature
+```
+Read .claude/workflow-state.json → campo "featureType" (api/ui/service/job)
+```
+
+> **Razao:** Garante que dados estao em contexto antes de qualquer processamento.
+
+---
+
+## Passo 2: Transformar Criterios do User
+
+Converter criterios em cenarios testaveis:
+
+| Criterio User | Cenario Derivado | Tipo |
+|---------------|------------------|------|
+| "funciona se X" | "X acontece" | SUCESSO |
+| "falha se Y" | "Y nao acontece" | FALHA |
+
+> **Razao:** Normaliza linguagem do user para linguagem de teste.
+
+---
+
+## Passo 3: Complementar com Failure Analysis
+
+```
+Read ~/.claude/techniques/failure-analysis.md
+```
+
+Executar APENAS para categorias NAO cobertas por interview + analysis.
+Budget: max 3-5 cenarios ADICIONAIS.
+
+> **Razao:** Pega edge cases que user e analise tecnica podem ter perdido.
+
+---
+
+## Passo 4: Opcoes de Validacao E2E
+
+Baseado no tipo da feature, identificar opcoes viaveis:
+
+| Tipo Feature | E2E Padrao | Alternativa |
+|--------------|------------|-------------|
+| ui | Playwright (auto) | hybrid |
+| api | API script (semi-auto) | hybrid |
+| service | Integration test (auto) | hybrid |
+| job | hybrid | semi-auto |
+
+Registrar:
+- **Opcao recomendada:** {tipo}
+- **Opcoes alternativas:** {lista}
+- **Custo/beneficio de cada:** {breve}
+
+> **Razao:** ST precisa conhecer opcoes E2E para decidir se vale incluir.
+> Ver: `~/.claude/commands/feature/playbooks/_e2e-base.md` + `playbooks/{tipo}/e2e.md`
+
+---
+
+## Passo 5: Tabela Unificada de Cenarios
+
+Consolidar TODOS os cenarios com fonte e score:
+
+| # | Cenario | Fonte | Nivel | Score | Decisao |
+|---|---------|-------|-------|-------|---------|
+| U1 | "{do user}" | interview | Integration | - | TESTAR |
+| T1 | "{do codigo}" | analysis | Unit | {PxI} | ? |
+| FA1 | "{failure analysis}" | technique | Unit | {PxI} | ? |
+| E2E1 | "{fluxo completo}" | e2e-option | E2E | - | ? |
+
+**Coluna Nivel:** Unit | Integration | E2E
+**Coluna Decisao:** Preenchida no Passo 6 (ST)
+
+**Regras:**
+- Fonte "interview" → SEMPRE TESTAR (criterio do user)
+- Fonte "analysis/technique" → Aplicar P×I (Score >= 6 = TESTAR)
+- Fonte "e2e-option" → Decidido no Passo 6
+
+> **Razao:** Visao completa de TODAS as opcoes de teste antes da reflexao.
+
+---
+
+## Passo 6: Reflexao e Decisao (ST)
+
+Usar `mcp__sequential-thinking__sequentialthinking`:
+
+1. **Inventario completo** - Quantos cenarios tenho? De que fontes?
+2. **Cobertura por nivel** - Quantos Unit vs Integration vs E2E?
+3. **Criterios do user** - Todos estao cobertos? Como?
+4. **Cenarios tecnicos** - Quais tem Score >= 6? Quais < 6?
+5. **E2E vale a pena?** - Custo vs beneficio para esta feature
+6. **Decisao final** - Para cada cenario: TESTAR ou NAO TESTAR
+7. **Justificativa** - Por que cada decisao? Mitigacao para excluidos?
+
+`totalThoughts`: 7
+
+**Output:** Tabela Unificada com coluna "Decisao" preenchida
+
+> **Razao:** ST agora tem TODOS os dados para decidir estrategia completa.
+
+---
+
+## Passo 7: Montar Proposta Unica
+
+Apresentar decisao consolidada:
+
+```markdown
+### Testes que serao implementados
+
+| # | Cenario | Fonte | Nivel | Teste |
+|---|---------|-------|-------|-------|
+| U1 | "{criterio user}" | interview | Integration | `it('...')` |
+| T1 | "{cenario tecnico}" | analysis | Unit | `it('...')` |
+| E2E1 | "{fluxo completo}" | e2e-option | E2E | `test('...')` |
+
+### Cenarios NAO testados (com justificativa)
+
+| # | Cenario | Score | Justificativa | Mitigacao | Arquivo |
+|---|---------|-------|---------------|-----------|---------|
+| FA2 | "{edge case}" | 4 | Baixa probabilidade | try/catch | handler.ts:45 |
+
+### E2E Validation Spec
+
+**Tipo:** {auto | semi-auto | hybrid}
+
+{SE auto}
+**Script/Ferramenta:** {playwright | functional-validator | integration test}
+**Cenario:** {Given/When/Then}
+**Comando:** `{npm run test:e2e ou similar}`
+
+{SE semi-auto}
+**Trigger:** {POST /api/endpoint ou comando}
+**Verificacoes do Claude:**
+- [ ] Response status/body esperado
+- [ ] Query DB: `{collection}.where(...)`
+- [ ] Verificar logs: `grep "{pattern}"`
+
+{SE hybrid}
+**Acao do User:**
+- [ ] {descricao detalhada do que user deve fazer}
+
+**Verificacoes do Claude:**
+- [ ] Query DB: `{collection/table}.where(...)`
+- [ ] Verificar logs: `grep "{pattern}"`
+- [ ] Confirmar side effect: `GET /api/{endpoint}`
+
+**Criterio de Sucesso:**
+- [ ] {condicao verificavel}
+
+### Resumo da Estrategia
+
+- **Unit tests:** {N} cenarios
+- **Integration tests:** {N} cenarios
+- **E2E:** {SIM/NAO} - {justificativa}
+- **Cobertura dos criterios do user:** 100%
+```
+
+> **Razao:** User ve proposta unica e completa, nao fragmentada.
+
+---
+
+## Passo 8: Aprovacao (AUQ)
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Esses testes cobrem suas necessidades?",
+    header: "Aprovacao",
+    options: [
+      { label: "Sim, cobrem", description: "Prosseguir com implementacao autonoma" },
+      { label: "Falta cenario", description: "Vou descrever o que falta" },
+      { label: "Mudar E2E", description: "Quero mudar a estrategia E2E" },
+      { label: "Mudar tipo", description: "Prefiro outro tipo de teste" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### SE "Falta cenario" ou "Mudar tipo":
+1. Coletar feedback
+2. Ajustar proposta
+3. Repetir aprovacao
+
+### SE "Mudar E2E":
+1. Apresentar alternativas E2E do Passo 4
+2. Ajustar spec E2E
+3. Confirmar e prosseguir
+
+---
+
+## Passo 9: Gerar Contract Lock
+
+Apos aprovacao, gerar contrato IMUTAVEL.
+
+### 9.1 Salvar Contract
+```
+Write .claude/contracts/{slug}.md
+```
+
+### 9.2 Formato
+```markdown
+# Contract: {feature}
+
+**Status:** LOCKED
+**Aprovado em:** {YYYY-MM-DD HH:MM}
+
+## Cenarios de Falha (Brainstorm)
+
+| # | Cenario | Categoria | P | I | Score | Decisao |
+|---|---------|-----------|---|---|-------|---------|
+| 1 | {cenario} | INPUT | Alta | Alto | 9 | TESTAR |
+| 2 | {cenario} | DEPENDENCY | Média | Alto | 6 | TESTAR |
+| 3 | {cenario} | STATE | Baixa | Alto | 3 | MITIGAR |
+
+## Criterios Aprovados (Testes)
+
+| # | Criterio | Fonte | Nivel | Cenario Ref | Teste | Status |
+|---|----------|-------|-------|-------------|-------|--------|
+| 1 | "[criterio do user]" | interview | Integration | - | `it('...')` | LOCKED |
+| 2 | "[cenario tecnico]" | analysis | Unit | #T1 | `it('...')` | LOCKED |
+
+## Cenarios Excluidos (com Justificativa)
+
+| # | Cenario Ref | Score | Por que NAO testar | Mitigacao | Arquivo |
+|---|-------------|-------|--------------------|-----------|---------|
+| 3 | #3 | 3 | {justificativa} | {mitigacao} | {arquivo:linha} |
+
+## E2E Validation
+
+**Tipo:** {auto | semi-auto | hybrid}
+**Status:** PENDING
+
+{spec completa conforme Passo 7}
+
+## IMUTABILIDADE
+
+> Mudanca de escopo requer nova aprovacao e re-geracao do contract.
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+SLUG=$(jq -r '.feature' .claude/workflow-state.json 2>/dev/null)
+
+# Pré-condições
+test -f ".claude/interviews/${SLUG}.md" || { echo "❌ Pré: interview não existe"; exit 1; }
+test -f ".claude/analysis/${SLUG}.md" || { echo "❌ Pré: analysis não existe"; exit 1; }
+
+# Pós-condição: Contract
+test -f ".claude/contracts/${SLUG}.md" || { echo "❌ Contract não encontrado: .claude/contracts/${SLUG}.md"; exit 1; }
+grep -q "## Criterios Aprovados" ".claude/contracts/${SLUG}.md" || { echo "❌ Contract sem critérios aprovados"; exit 1; }
+grep -q "## E2E Validation" ".claude/contracts/${SLUG}.md" || { echo "❌ Contract sem E2E Validation spec"; exit 1; }
+grep -q "**Status:** LOCKED" ".claude/contracts/${SLUG}.md" || { echo "❌ Contract não está LOCKED"; exit 1; }
+
+echo "✅ Gate 03-strategy passou"
+```
+
+**IMPORTANTE:** Esta é a ÚNICA parada do workflow. Após aqui, execução é AUTÔNOMA.
+
+---
+
+## Passo 10: Atualizar Estado do Workflow
+
+```bash
+if command -v jq &> /dev/null; then
+  jq '
+    .currentPhase = "04-red" |
+    .completedPhases += ["03-strategy"] |
+    .resumeHint = "Testes APROVADOS. Prox: escrever testes RED, executar autonomamente" |
+    .lastStep = "Passo 10: Atualizar Estado" |
+    .contract = (".claude/contracts/" + .feature + ".md")
+  ' .claude/workflow-state.json > .claude/workflow-state.tmp && mv .claude/workflow-state.tmp .claude/workflow-state.json
+else
+  echo "Atualizar .claude/workflow-state.json: currentPhase=04-red, add 03-strategy to completedPhases"
+fi
+```
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/04-red.md