kakaroto-config 1.0.0

package/config/commands/debug/01-investigate.md

@@ -0,0 +1,119 @@
+# Fase 1: Investigate
+
+## Passo 1: Carregar Contexto
+
+```
+mcp__memory__search_nodes({ query: "config" })
+mcp__memory__search_nodes({ query: "<termos-do-bug>" })
+```
+
+Extrair termos relevantes de $ARGUMENTS e buscar bugs similares já resolvidos.
+
+---
+
+## Passo 2: Reproduzir Bug
+
+### 2.1 Executar Passos
+Tentar reproduzir com informações fornecidas.
+
+### 2.2 Documentar
+```
+REPRODUÇÃO:
+- Passos: [...]
+- Input: [...]
+- Output esperado: [...]
+- Output real: [...]
+- Reproduzido: SIM/NAO
+```
+
+### 2.3 Gate
+Se NÃO reproduziu: usar AskUserQuestion para mais detalhes.
+Se reproduziu: continuar.
+
+---
+
+## Passo 3: Verificar Estado Externo (OBRIGATÓRIO para scraping/browser)
+
+**SE o bug envolve:** web scraping, Playwright, Puppeteer, seletores, ou qualquer interação com páginas web externas:
+
+### 3.1 VERIFICAR ANTES DE ASSUMIR
+
+```
+1. mcp__playwright__browser_navigate({ url: "[URL do bug]" })
+2. mcp__playwright__browser_wait_for({ time: 3 })
+3. mcp__playwright__browser_snapshot({})
+```
+
+### 3.2 Comparar Estado Atual vs Esperado
+
+- O que o código espera encontrar?
+- O que realmente existe na página?
+- Quais seletores existem/mudaram?
+
+### 3.3 Gate
+
+- [ ] Estado atual da página VERIFICADO com Playwright?
+- [ ] Diferenças entre esperado e real DOCUMENTADAS?
+
+**PROIBIDO:** Assumir que "a página mudou" sem verificar. SEMPRE abrir a URL e constatar.
+
+---
+
+## Passo 4: Explorar Código Relacionado
+
+### 4.1 Buscar no Codebase
+```
+Grep: termos do bug
+Glob: arquivos com nomes relacionados
+git log --oneline --grep="fix" -- [arquivos suspeitos]
+```
+
+### 4.2 Identificar
+- Arquivos/funções envolvidos
+- Como erros são tratados nesta área
+- Há validação que deveria existir?
+- Há helper existente que resolve?
+
+---
+
+## Passo 5: 5 Whys (Causa Raiz)
+
+Para cada "Por que?", fornecer EVIDÊNCIA de código:
+
+```
+ANÁLISE DE CAUSA RAIZ:
+
+Sintoma: [o que está acontecendo]
+
+Por que #1: [resposta]
+  Evidência: [arquivo:linha] - [código]
+
+Por que #2: [resposta]
+  Evidência: [arquivo:linha] - [código]
+
+Por que #3: [resposta]
+  Evidência: [arquivo:linha] - [código]
+
+CAUSA RAIZ: [declaração clara]
+```
+
+---
+
+## Passo 6: Validar Causa Raiz
+
+A causa raiz deve ser:
+- [ ] Algo que você pode MUDAR
+- [ ] Suportada por evidência de código
+- [ ] Explica TODOS os sintomas
+
+Se não validar: voltar ao Passo 5.
+
+---
+
+## Output
+
+Causa raiz documentada com evidência.
+
+---
+## PRÓXIMA FASE
+AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/debug/02-fix.md

package/config/commands/debug/02-fix.md

@@ -0,0 +1,108 @@
+# Fase 2: Fix
+
+## Contexto
+Causa raiz identificada. Implementar fix de forma AUTÔNOMA.
+
+---
+
+## Passo 0: Gate de Criticidade
+
+### 0.1 Identificar Paths Afetados
+
+Extrair arquivos da causa raiz documentada na investigacao (fase 01-investigate).
+
+### 0.2 Lista de Paths Criticos
+
+```
+PATHS_CRITICOS:
+- **/auth/**
+- **/payment/**
+- **/migration*/**
+- **/oauth*
+- **/credential*
+- **/secret*
+- api/middleware.ts
+- services/*Service.ts (core services)
+```
+
+### 0.3 Decision Gate
+
+**SE** arquivos afetados ∩ PATHS_CRITICOS **nao vazio**:
+
+1. Documentar fix planejado:
+   - Causa raiz (com evidencia)
+   - Arquivos a modificar
+   - Mudancas propostas
+   - Riscos identificados
+
+2. Chamar `EnterPlanMode`
+   - Escrever plano de fix em `.claude/plans/debug-fix-{timestamp}.md`
+   - User aprova ou rejeita via ExitPlanMode
+
+3. Apos aprovacao: Prosseguir para Passo 1
+
+**SENAO** (nao critico):
+Prosseguir direto para Passo 1 (autonomia total)
+
+---
+
+## Passo 1: Teste de Regressao
+
+### 1.1 Criar Teste que Reproduz o Bug
+```typescript
+describe('[contexto do bug]', () => {
+  it('should [comportamento esperado]', () => {
+    // Arrange: setup que causa o bug
+    // Act: ação que dispara o bug
+    // Assert: verificar comportamento correto
+  })
+})
+```
+
+### 1.2 Verificar que Teste FALHA
+```bash
+npm test -- --testPathPattern="[arquivo]"
+```
+
+O teste DEVE falhar antes do fix. Se passar, o teste não reproduz o bug.
+
+---
+
+## Passo 2: Implementar Fix
+
+### 2.1 Fix Mínimo
+```
+FIX:
+Arquivo: [arquivo:linha]
+Antes: [código atual]
+Depois: [código novo]
+Justificativa: [por que resolve a causa raiz]
+```
+
+### 2.2 Regras
+- APENAS o necessário para resolver a causa raiz
+- NÃO refatorar código não relacionado
+- NÃO adicionar features
+- Seguir patterns existentes do projeto
+
+---
+
+## Passo 3: Verificar Fix
+
+### 3.1 Teste Deve Passar
+```bash
+npm test -- --testPathPattern="[arquivo]"
+```
+
+### 3.2 Bug Não Reproduz
+Executar passos originais. Bug não deve ocorrer.
+
+---
+
+## Output
+
+Fix implementado. Teste de regressão passando.
+
+---
+## PRÓXIMA FASE
+AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/debug/03-verify.md

package/config/commands/debug/03-verify.md

@@ -0,0 +1,66 @@
+# Fase 3: Verify
+
+## Contexto
+Fix implementado. Verificar e finalizar de forma AUTÔNOMA.
+
+---
+
+## Passo 1: Quality Gates
+
+Rodar em sequência:
+```bash
+npm test
+npx tsc --noEmit
+npm run build
+```
+
+**Se falhar:** Corrigir e rodar novamente. Não prosseguir até passar.
+
+---
+
+## Passo 2: Verificação Final
+
+- [ ] Testes passam
+- [ ] TypeScript sem erros
+- [ ] Build bem-sucedido
+- [ ] Bug não reproduz mais
+
+---
+
+## Passo 3: Memory Sync (se bug não-óbvio)
+
+Se o bug foi difícil de encontrar, salvar na memory:
+
+```javascript
+mcp__memory__create_entities({
+  entities: [{
+    name: "{prefix}:bug:{nome-descritivo}",
+    entityType: "bug",
+    observations: [
+      "Sintoma: [...]",
+      "Causa raiz: [...]",
+      "Solução: [...]",
+      "Arquivos: [...]"
+    ]
+  }]
+})
+```
+
+---
+
+## Passo 4: Relatório Final
+
+Reportar ao user:
+- Bug resolvido
+- Causa raiz identificada
+- Fix implementado
+- Teste de regressão criado
+- Quality gates passando
+
+---
+
+## Regras Invioláveis
+
+1. **PROIBIDO** prosseguir com testes falhando
+2. **PROIBIDO** prosseguir com build falhando
+3. **PROIBIDO** perguntar ao user (só reportar no final)

package/config/commands/debug.md

@@ -0,0 +1,19 @@
+---
+model: opus
+---
+# Debug Workflow
+
+Investigar e resolver: $ARGUMENTS
+
+## INICIAR
+AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/debug/01-investigate.md
+Seguir instruções. Cada fase aponta para a próxima.
+
+## Fluxo
+Investigate → Fix → Verify → Fim (SEM PARADAS)
+
+## Regras
+1. ZERO paradas até o final
+2. ZERO perguntas ao user (exceto se não conseguir reproduzir)
+3. Fix mínimo - só o necessário para resolver
+4. Erros: corrigir e continuar, não abandonar

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

@@ -0,0 +1,151 @@
+# Fase 1: Interview
+
+## Passo 1: Exploração Autônoma (ANTES de qualquer pergunta)
+
+### 1.1 Carregar Contexto
+```
+mcp__memory__search_nodes({ query: "config" })
+mcp__memory__search_nodes({ query: "<termos-da-feature>" })
+```
+
+### 1.2 Explorar Codebase
+```
+Glob: **/*.ts, **/*.tsx
+Read: package.json, schema.prisma (se existir)
+Grep: termos relacionados à feature
+```
+
+### 1.3 Identificar Patterns
+- Como components similares funcionam
+- Como services são estruturados
+- Como erros são tratados
+- Como loading states funcionam
+
+**Você DEVE saber (não perguntar):**
+- Estrutura de pastas
+- Schema do banco
+- Libs disponíveis
+- Patterns existentes
+
+---
+
+## Passo 2: Reflexão (ANTES de perguntar)
+
+Usar `mcp__sequential-thinking__sequentialthinking`:
+
+1. **O que descobri** - Síntese da exploração (patterns, services, schema encontrados)
+2. **O que ainda posso descobrir** - Gaps que consigo preencher explorando mais código
+3. **O que APENAS o user pode responder** - Decisões de produto, preferências de UX
+4. **Tentar descobrir o que falta** - Última tentativa autônoma antes de perguntar
+5. **Formular perguntas mínimas** - Só o essencial que não consegui descobrir
+
+`totalThoughts`: 5
+
+---
+
+## Passo 3: Perguntas ao User (APENAS decisões de produto)
+
+**Usar AskUserQuestion para todas as perguntas.**
+
+### 3.1 Problema e Escopo
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Qual problema principal essa feature resolve?",
+      header: "Problema",
+      multiSelect: false,
+      options: [
+        { label: "Eficiência", description: "Processo manual que precisa ser automatizado" },
+        { label: "Funcionalidade", description: "Capacidade que não existe hoje" },
+        { label: "UX", description: "Experiência que precisa melhorar" }
+      ]
+    },
+    {
+      question: "Qual escopo para primeira versão?",
+      header: "Escopo",
+      multiSelect: false,
+      options: [
+        { label: "MVP mínimo", description: "Só o essencial" },
+        { label: "MVP completo", description: "Casos principais cobertos" },
+        { label: "Feature completa", description: "Todos os casos de uso" }
+      ]
+    }
+  ]
+})
+```
+
+### 3.2 UX (se aplicável)
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Há design/mockup de referência?",
+    header: "Design",
+    multiSelect: false,
+    options: [
+      { label: "Sim, tenho", description: "Vou compartilhar" },
+      { label: "Seguir padrão", description: "Usar patterns do app" },
+      { label: "Proponha", description: "Quero sugestão" }
+    ]
+  }]
+})
+```
+
+### 3.3 Trade-offs (apenas se houver decisão com impacto)
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Encontrei 2 approaches. Qual prefere?",
+    header: "Approach",
+    multiSelect: false,
+    options: [
+      { label: "Approach A", description: "[trade-off A]" },
+      { label: "Approach B", description: "[trade-off B]" }
+    ]
+  }]
+})
+```
+
+---
+
+## Passo 4: Apresentar Descobertas
+
+Mostrar ao user:
+- Services/patterns encontrados
+- Tabelas relevantes do schema
+- Libs que serão usadas
+- Pattern que será seguido
+
+---
+
+## Passo 5: Checkpoint
+
+Usar TodoWrite para registrar conclusao da fase:
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Interview: contexto carregado", status: "completed", activeForm: "Loading context" },
+    { content: "Interview: codebase explorado", status: "completed", activeForm: "Exploring codebase" },
+    { content: "Interview: perguntas respondidas", status: "completed", activeForm: "Answering questions" },
+    { content: "Interview: descobertas documentadas", status: "completed", activeForm: "Documenting findings" },
+    { content: "Spec: gerar especificacao", status: "pending", activeForm: "Generating spec" }
+  ]
+})
+```
+
+**Gate:** SE items de Interview nao estao "completed" → Completar antes de prosseguir
+
+---
+
+## Output
+
+Resumo estruturado:
+- Problema identificado
+- Escopo definido
+- Decisões de UX
+- Patterns a seguir
+
+---
+## PRÓXIMA FASE
+AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/feature/02-spec.md

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

@@ -0,0 +1,174 @@
+# Fase 2: Spec
+
+## Passo 0: Context
+
+Contexto de projeto ja carregado em 01-interview (mesma sessao).
+Buscar apenas patterns para reutilizacao:
+
+```
+mcp__memory__search_nodes({ query: "pattern" })
+```
+
+SE retomando sessao interrompida:
+```
+Read .claude/specs/current.md (se existir)
+```
+
+---
+
+## Passo 1: Pensamento Estruturado
+
+Usar `mcp__sequential-thinking__sequentialthinking` para planejar:
+
+1. **Thought 1**: Quais componentes esta feature precisa?
+2. **Thought 2**: Onde código similar existe no codebase?
+3. **Thought 3**: Quais patterns do projeto devo seguir?
+4. **Thought 4**: Quais trade-offs arquiteturais existem?
+5. **Thought 5**: Qual a abordagem mais simples que resolve?
+
+`totalThoughts`: 5-8 (ajustar conforme complexidade)
+
+---
+
+## Passo 2: Análise de Reutilização
+
+### 2.1 Buscar Código Existente
+```
+Grep: termos da feature em services/, utils/, lib/
+Glob: arquivos com nomes similares
+```
+
+### 1.2 Mapear Reutilização
+| Necessidade | Código Existente | Ação |
+|-------------|------------------|------|
+| [o que precisa] | [arquivo:linha] | Reutilizar/Estender/Criar |
+
+**Default = reutilizar. Código novo precisa justificativa.**
+
+---
+
+## Passo 2: Gerar Spec
+
+```markdown
+# Spec: [Nome da Feature]
+
+**Status:** Draft
+
+## Problema
+[1-2 frases - o problema, não a solução]
+
+## Solução
+[Descrição de alto nível]
+
+## Escopo
+
+### Inclui
+- [Deliverable 1]
+- [Deliverable 2]
+
+### Não Inclui
+- [O que não será feito]
+
+## Design Técnico
+
+### Dados
+[Estruturas, campos novos, tabelas]
+
+### Services
+| Service | Mudanças |
+|---------|----------|
+| [nome] | [o que muda] |
+
+### API (se aplicável)
+[Endpoints, signatures]
+
+### Tratamento de Erros
+| Cenário | Comportamento |
+|---------|---------------|
+| [erro] | [o que acontece] |
+
+### Reutilização Obrigatória
+| Existente | Uso |
+|-----------|-----|
+| [código] | [como usar] |
+
+### Justificativa para Código Novo
+| Novo Código | Por que não reutilizar existente? |
+|-------------|-----------------------------------|
+| [arquivo/função] | [justificativa] |
+
+## UI/UX (se aplicável)
+
+### Fluxo
+1. User faz X
+2. Sistema responde Y
+
+### Estados
+| Estado | Display |
+|--------|---------|
+| Loading | [desc] |
+| Empty | [desc] |
+| Error | [desc] |
+| Success | [desc] |
+
+## Edge Cases
+| Caso | Tratamento |
+|------|------------|
+| [edge] | [como tratar] |
+
+## Testes
+
+### Unitários (OBRIGATÓRIO)
+| Função | Arquivo Teste | Casos |
+|--------|---------------|-------|
+| [func] | [file.test.ts] | [casos] |
+
+## Decisões
+| Decisão | Justificativa |
+|---------|---------------|
+| [escolha] | [por quê] |
+```
+
+---
+
+## Output
+
+1. MOSTRAR spec completa ao user (visibilidade)
+2. Spec = contrato, implementacao deve seguir
+
+---
+
+## Passo 3: Persistir Spec
+
+1. Gerar slug: primeira palavra do problema + data
+   Exemplo: `filtro-2026-01-10.md`
+
+2. Salvar spec:
+   ```
+   Write .claude/specs/{slug}.md
+   Write .claude/specs/current.md (copia do conteudo)
+   ```
+
+3. Confirmar: "Spec salva em .claude/specs/{slug}.md"
+
+---
+
+## Passo 4: Checkpoint
+
+Atualizar TodoWrite com conclusao da spec:
+
+```javascript
+TodoWrite({
+  todos: [
+    // items anteriores como completed
+    { content: "Spec: especificacao gerada", status: "completed", activeForm: "Generating spec" },
+    { content: "Spec: reutilizacao mapeada", status: "completed", activeForm: "Mapping reuse" },
+    { content: "Spec: spec persistida em arquivo", status: "completed", activeForm: "Persisting spec" },
+    { content: "Planner: criar plano de tarefas", status: "pending", activeForm: "Creating plan" }
+  ]
+})
+```
+
+---
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/03-planner.md