kakaroto-config 1.0.1 → 1.0.2

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

@@ -3,15 +3,23 @@
 ## Passo 0: Context
 
 Contexto de projeto ja carregado em 01-interview (mesma sessao).
-Buscar apenas patterns para reutilizacao:
 
+### 0.1 Carregar Respostas da Interview
+```
+Read .claude/interviews/current.md
+```
+Este arquivo contém: perguntas respondidas, decisões implícitas, termos-chave.
+**Usar como referência** para manter consistência com o que foi acordado.
+
+### 0.2 Buscar Patterns (se necessário)
 ```
 mcp__memory__search_nodes({ query: "pattern" })
 ```
 
-SE retomando sessao interrompida:
+### 0.3 SE retomando sessão interrompida
 ```
-Read .claude/specs/current.md (se existir)
+Read .claude/interviews/current.md (contexto original)
+Read .claude/specs/current.md (spec parcial, se existir)
 ```
 
 ---
@@ -38,7 +46,7 @@ Grep: termos da feature em services/, utils/, lib/
 Glob: arquivos com nomes similares
 ```
 
-### 1.2 Mapear Reutilização
+### 2.2 Mapear Reutilização
 | Necessidade | Código Existente | Ação |
 |-------------|------------------|------|
 | [o que precisa] | [arquivo:linha] | Reutilizar/Estender/Criar |
@@ -47,88 +55,15 @@ Glob: arquivos com nomes similares
 
 ---
 
-## 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]
+## Passo 3: Gerar Spec
 
-### 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ê] |
+Carregar template:
+```
+Read ~/.claude/templates/spec-template.md
 ```
 
+Preencher template com informações coletadas na interview.
+
 ---
 
 ## Output
@@ -138,7 +73,7 @@ Glob: arquivos com nomes similares
 
 ---
 
-## Passo 3: Persistir Spec
+## Passo 4: Persistir Spec
 
 1. Gerar slug: primeira palavra do problema + data
    Exemplo: `filtro-2026-01-10.md`
@@ -153,21 +88,10 @@ Glob: arquivos com nomes similares
 
 ---
 
-## Passo 4: Checkpoint
-
-Atualizar TodoWrite com conclusao da spec:
+## Passo 5: Checkpoint
 
-```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" }
-  ]
-})
-```
+Usar TodoWrite para registrar items da fase Spec como "completed".
+Adicionar "Planner: criar plano de tarefas" como "pending".
 
 ---
 ## PROXIMA FASE

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

@@ -5,9 +5,18 @@
 SE continuacao direta de 02-spec (mesma sessao):
   Contexto ja disponivel, prosseguir
 
-SE retomando sessao interrompida:
+### 0.1 Carregar Contexto da Interview (SE necessário)
 ```
-Read .claude/specs/current.md
+Read .claude/interviews/current.md
+```
+Consultar SE surgir dúvida sobre decisões já tomadas na Interview.
+Evita re-perguntar o que já foi respondido.
+
+### 0.2 SE retomando sessão interrompida
+```
+Read .claude/interviews/current.md (decisões originais)
+Read .claude/specs/current.md (spec aprovada)
+Read .claude/plans/current.md (plano parcial, se existir)
 ```
 
 ---
@@ -95,7 +104,62 @@ Apos implementacao:
 
 ---
 
-## Passo 7: Persistir Plano
+## Passo 7: Registro de Decisões
+
+### 7.1 Decisões Tomadas
+Documentar decisões feitas autonomamente durante o planejamento:
+
+| Decisão | Opções Consideradas | Escolha | Justificativa |
+|---------|---------------------|---------|---------------|
+| [ex: estrutura de dados] | Array / Map | Map | Lookup O(1) necessário |
+| [ex: local do código] | services/ / utils/ | services/ | Segue pattern existente |
+
+### 7.2 Decisões Pendentes
+Listar decisões que APENAS o user pode tomar:
+
+| Decisão | Opções | Impacto na Feature |
+|---------|--------|-------------------|
+| [ex: formato export] | CSV / JSON / Excel | Afeta UX de download |
+
+**Critérios para classificar como "Pendente":**
+1. Impacta comportamento/UX visível ao user final
+2. Não existe default claro no projeto
+3. Não foi respondida na Interview (verificar interviews/current.md)
+
+---
+
+## Passo 8: Clarificações (CONDICIONAL)
+
+**SE "Decisões Pendentes" NÃO estiver vazio:**
+
+Usar AskUserQuestion para resolver cada decisão pendente.
+**Limite:** Máximo 5 perguntas por execução.
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "[Decisão pendente como pergunta]",
+    header: "[2-3 palavras]",
+    options: [
+      { label: "[Opção A]", description: "[trade-off/impacto]" },
+      { label: "[Opção B]", description: "[trade-off/impacto]" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+Após respostas:
+1. Mover decisões de "Pendentes" para "Tomadas"
+2. Adicionar resposta do user na coluna "Escolha"
+3. Atualizar plano se necessário
+
+**SE "Decisões Pendentes" estiver vazio:**
+Prosseguir direto para Passo 9.
+
+---
+
+## Passo 9: Persistir Plano
 
 1. Usar mesmo slug da spec (gerado em 02-spec)
 
@@ -107,12 +171,25 @@ Apos implementacao:
 
 ---
 
+## Passo 10: Checkpoint
+
+Usar TodoWrite para registrar items da fase Planner como "completed".
+Adicionar "Implement: executar plano aprovado" como "pending".
+
+**Gates:**
+- Plano deve estar salvo
+- "Decisões Pendentes" deve estar vazio (todas resolvidas)
+
+---
+
 ## Output
 
 1. Salvar plano (usar TodoWrite para tracking)
-2. Chamar `EnterPlanMode`
+2. Chamar `EnterPlanMode` (não AskUserQuestion para aprovação)
 3. **AGUARDAR aprovacao do user**
 
+**Nota:** EnterPlanMode é para aprovar o PLANO. Decisões pendentes devem ser resolvidas ANTES via AskUserQuestion (Passo 8).
+
 ---
 
 ## Pos-Aprovacao

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

@@ -3,6 +3,12 @@
 ## Contexto
 Plano foi aprovado. Executar de forma AUTÔNOMA até o fim.
 
+**Regras desta fase:**
+- Executar sem pedir confirmação ao user
+- Erros devem ser corrigidos, não abandonados
+- Seguir spec aprovada, não modificar escopo
+- Toda função nova precisa de teste
+
 ---
 
 ## Passo 1: Setup
@@ -56,6 +62,15 @@ Se falhar: corrigir e continuar (não parar).
 
 ---
 
+## Passo 4: Checkpoint
+
+Usar TodoWrite para marcar todas tarefas de implementação como "completed".
+Adicionar "Quality: executar quality gates" como "pending".
+
+**Gate:** Todas tarefas do plano devem estar "completed".
+
+---
+
 ## Output
 
 Implementação completa.
@@ -64,11 +79,3 @@ Implementação completa.
 ## PRÓXIMA FASE
 AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/feature/05-quality.md
 
----
-
-## Regras Invioláveis
-
-1. **PROIBIDO** pedir confirmação ao user
-2. **PROIBIDO** abandonar por erro (corrigir e continuar)
-3. **PROIBIDO** modificar escopo (seguir spec aprovada)
-4. **PROIBIDO** pular testes

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

@@ -3,6 +3,8 @@
 ## Contexto
 Implementação completa. Executar quality gates de forma AUTÔNOMA.
 
+**Regra:** Não prosseguir com testes/build falhando.
+
 ---
 
 ## Passo 1: Agents de Qualidade
@@ -77,6 +79,16 @@ Task({
 })
 ```
 
+### 1.7 CRUD Validation (SE nova entidade)
+Apenas se criou novo endpoint CRUD em `api/handlers/`:
+```javascript
+Task({
+  subagent_type: "test-fixer",
+  prompt: "Executar CRUD smoke test. Para novos endpoints POST/PUT, testar criação e verificar response 200/201.",
+  description: "CRUD smoke test"
+})
+```
+
 ---
 
 ## Passo 2: Quality Gates Finais
@@ -114,9 +126,15 @@ Reportar ao user:
 
 ---
 
-## Regras Invioláveis
+## Passo 5: Checkpoint
+
+Usar TodoWrite para marcar quality gates como "completed".
+Adicionar "Commit: commitar e fazer push" como "pending".
+
+**Gate:** Todos quality gates devem passar (test, tsc, build).
+
+---
+
+## PRÓXIMA FASE
+AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/feature/06-commit.md
 
-1. **PROIBIDO** pular agents de qualidade
-2. **PROIBIDO** prosseguir com testes falhando
-3. **PROIBIDO** prosseguir com build falhando
-4. **PROIBIDO** perguntar ao user (só reportar no final)

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

@@ -0,0 +1,91 @@
+# Fase 6: Commit & Push
+
+## Contexto
+Quality passou. Commitar e fazer push de forma AUTÔNOMA.
+
+---
+
+## Passo 1: Verificar Mudanças
+
+```bash
+git status
+```
+
+**Se não houver mudanças:** Reportar "Nada a commitar" → FIM
+
+---
+
+## Passo 2: Analisar Diff
+
+```bash
+git diff --stat
+git log --oneline -3
+```
+
+Usar diff para gerar mensagem descritiva.
+Usar log para seguir padrão de commits existentes.
+
+---
+
+## Passo 3: Commit
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+{type}: {descrição concisa em inglês}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Tipos:**
+- `feat:` nova funcionalidade
+- `fix:` correção de bug
+- `refactor:` reestruturação sem mudar comportamento
+- `docs:` documentação
+- `test:` testes
+
+---
+
+## Passo 4: Push
+
+```bash
+git push
+```
+
+**Se falhar:** Reportar erro ao user.
+
+---
+
+## Passo 5: Confirmar
+
+```bash
+git status
+git log --oneline -1
+```
+
+Reportar ao user: commit criado e pushed.
+
+---
+
+## Passo 6: Checkpoint
+
+Usar TodoWrite para marcar commit como "completed".
+Adicionar "Evaluate: auto-avaliação do workflow" como "pending".
+
+**Gate:** Commit deve estar pushed com sucesso.
+
+---
+
+## Regras
+
+1. **1 feature = 1 commit atômico**
+2. **Mensagem em inglês**
+3. **NUNCA** --force push
+4. **NUNCA** commitar se quality falhou
+
+---
+
+## PROXIMA FASE
+ACAO OBRIGATORIA: Read ~/.claude/commands/feature/07-evaluate.md

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

@@ -0,0 +1,129 @@
+# Fase 7: Auto-Avaliacao
+
+## Contexto
+Commit feito. Avaliar workflow e propor melhorias ao config.
+
+---
+
+## Passo 1: Coletar Metricas
+
+```bash
+git diff --stat HEAD~1
+git log -1 --format="%s"
+```
+
+Ler:
+- .claude/specs/current.md (spec implementada)
+- .claude/plans/current.md (plano seguido)
+
+Coletar:
+- Arquivos modificados
+- Linhas adicionadas/removidas
+- Testes criados
+
+---
+
+## Passo 2: Sequential Thinking #1 - DIAGNOSTICO
+
+Usar mcp__sequential-thinking__sequentialthinking para:
+
+**Objetivo:** Identificar problemas e causas raiz
+
+### 2.1 Avaliar Criterios (0-100%)
+
+| Criterio | Peso | Como Medir |
+|----------|------|------------|
+| Completude | 40% | Todos itens do spec implementados? |
+| Qualidade | 20% | Code review passou limpo? Issues criticas? |
+| Testes | 15% | Funcoes novas tem cobertura? |
+| Build | 10% | Passou na primeira tentativa? |
+| Autonomia | 10% | Quantas perguntas ao user? (ideal: <=2) |
+| Docs | 5% | Spec/plan refletem implementacao final? |
+
+### 2.2 Para Criterios < 80%: Aplicar 5 Whys
+
+1. Por que o score foi baixo?
+2. Qual foi a causa raiz?
+3. O que poderia ter prevenido?
+4. Que informacao/regra faltou?
+5. Onde essa informacao deveria estar?
+
+**Output esperado:** Lista de {problema, causa_raiz, local_ideal}
+
+---
+
+## Passo 3: Sequential Thinking #2 - SINTESE
+
+Usar mcp__sequential-thinking__sequentialthinking novamente:
+
+**Objetivo:** Transformar diagnosticos em mudancas acionaveis
+
+Para cada problema identificado no Passo 2:
+
+1. **Tipo de mudanca?**
+   - Config: Regra no CLAUDE.md
+   - Skill: Gate/validacao em fase
+   - Pattern: Conhecimento para memoria
+
+2. **Qual arquivo editar?**
+   - ~/.claude/CLAUDE.md
+   - ~/.claude/commands/feature/*.md
+   - ~/.claude/commands/debug/*.md
+
+3. **Diff exato da mudanca?**
+   - Escrever o texto exato a adicionar
+
+4. **Efeitos colaterais?**
+   - Vai afetar outros workflows?
+   - Pode causar falsos positivos?
+
+5. **Prioridade?**
+   - Alta: Problema recorrente ou critico
+   - Media: Melhoria de qualidade
+   - Baixa: Nice-to-have
+
+**Output esperado:** Lista de {tipo, arquivo, diff_sugerido, prioridade}
+
+---
+
+## Passo 4: Propor Melhorias ao Usuario
+
+Para cada melhoria identificada (MAXIMO 3 por execucao):
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Detectei: {problema}. Causa: {causa_raiz}. Sugiro adicionar em {arquivo}: '{diff}'. Aplicar?",
+    header: "Melhoria",
+    options: [
+      { label: "Aplicar", description: "Editar {arquivo} com a mudanca sugerida" },
+      { label: "Ignorar", description: "Pular desta vez, pode sugerir novamente" },
+      { label: "Nunca sugerir", description: "Adicionar excecao permanente" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### Acoes por Resposta:
+- **Aplicar:** Usar Edit tool para modificar arquivo
+- **Ignorar:** Prosseguir sem acao
+- **Nunca sugerir:** Adicionar em ~/.claude/evaluation-exceptions.json
+
+---
+
+## Passo 5: Finalizar
+
+Reportar ao user:
+
+```
+## Avaliacao do Workflow
+
+**Score Final:** X% (Completude: X%, Qualidade: X%, Testes: X%, Build: X%, Autonomia: X%, Docs: X%)
+
+**Melhorias Aplicadas:** N
+- [lista de mudancas aplicadas]
+
+**Workflow /feature concluido.**
+```
+

package/config/commands/feature.md

@@ -10,10 +10,4 @@ AÇÃO OBRIGATÓRIA: Read ~/.claude/commands/feature/01-interview.md
 Seguir instruções. Cada fase aponta para a próxima.
 
 ## Fluxo
-Interview → Spec → Planner → [APROVAÇÃO] → Implement → Quality → Fim
-
-## Regras
-1. PROIBIDO parar entre fases (exceto EnterPlanMode)
-2. PROIBIDO AskUserQuestion para aprovar spec/planner
-3. PROIBIDO pedir confirmação após aprovação do plano
-4. Erros: corrigir e continuar, não abandonar
+Interview → Spec → Planner → [APROVAÇÃO] → Implement → Quality → Commit → Evaluate

package/config/templates/spec-template.md

@@ -0,0 +1,92 @@
+# 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] |
+
+### API/Integração (SE CRUD)
+| Endpoint | Método | Casos |
+|----------|--------|-------|
+| [/api/X] | [POST] | [criar, validação 400, erro 500] |
+
+### E2E/Smoke (SE UI)
+| Fluxo | Verificação |
+|-------|-------------|
+| [Criar via form] | [Entidade aparece na lista] |
+
+### Infraestrutura (SE Banco)
+| Recurso | Configuração |
+|---------|--------------|
+| [Collection X] | [Índice: accountId + createdAt DESC] |
+
+## Decisões
+| Decisão | Justificativa |
+|---------|---------------|
+| [escolha] | [por quê] |

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "kakaroto-config",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Claude Code configuration by Pedro Jahara - autonomous workflows for /feature, /debug, /gate",
   "bin": {
     "kakaroto-config": "./bin/install.js"
   },
+  "scripts": {
+    "release": "node bin/release.js"
+  },
   "files": [
     "bin",
     "config"