kakaroto-config 1.0.4 → 1.0.6

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

@@ -0,0 +1,140 @@
+# Fase 9: Evaluate
+
+## Responsabilidade
+Auto-avaliacao do workflow e propor melhorias.
+
+---
+
+## Passo 1: Coletar Metricas
+
+```bash
+git diff --stat HEAD~1
+git log -1 --format="%s"
+```
+
+---
+
+## Passo 2: Sequential Thinking #1 - DIAGNOSTICO
+
+Usar `mcp__sequential-thinking__sequentialthinking`:
+
+| Criterio | Peso | Como Medir |
+|----------|------|------------|
+| Completude | 40% | Todos itens implementados? |
+| Qualidade | 20% | Review passou limpo? |
+| Testes | 15% | Cobertura adequada? |
+| Build | 10% | Passou na primeira? |
+| Autonomia | 10% | Quantas perguntas? (ideal <=1) |
+| Docs | 5% | Spec reflete implementacao? |
+
+Para criterios < 80%: Aplicar 5 Whys
+
+`totalThoughts`: 5-7
+
+---
+
+## Passo 3: Sequential Thinking #2 - SINTESE
+
+Para cada problema identificado:
+
+1. Tipo de mudanca? (Config/Skill/Pattern)
+2. Qual arquivo editar?
+3. Diff exato?
+4. Efeitos colaterais?
+5. Prioridade?
+
+`totalThoughts`: 3-5
+
+---
+
+## Passo 4: Propor Melhorias (AUQ)
+
+Para melhorias identificadas (max 3):
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Detectei: {problema}. Causa: {causa}. Sugiro: {diff}. Aplicar?",
+    header: "Melhoria",
+    options: [
+      { label: "Aplicar", description: "Editar arquivo" },
+      { label: "Ignorar", description: "Pular desta vez" },
+      { label: "Nunca sugerir", description: "Adicionar excecao" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**Acoes:**
+- **Aplicar:** Edit tool
+- **Ignorar:** Prosseguir
+- **Nunca sugerir:** Adicionar em evaluation-exceptions.json
+
+---
+
+## Passo 5: Relatorio Final
+
+```markdown
+## Workflow Completo
+
+**Score Final:** X%
+- Completude: X%
+- Qualidade: X%
+- Testes: X%
+- Build: X%
+- Autonomia: X%
+
+**Commit:** {hash} {message}
+
+**Melhorias Aplicadas:** N
+- [lista]
+
+**Workflow /feature concluido.**
+```
+
+---
+
+## Gate (BLOQUEANTE)
+
+```bash
+# Verificar que commit existe
+git log -1 --format="%s" | grep -qE "^(feat|fix|refactor|test|docs):" || { echo "❌ Commit não encontrado"; exit 1; }
+
+# Verificar E2E foi executado (no contract)
+SLUG=$(jq -r '.feature' .claude/workflow-state.json 2>/dev/null)
+grep -qE "Status:.*(PASSED|FAILED)" ".claude/contracts/${SLUG}.md" 2>/dev/null || { echo "❌ E2E não executado"; exit 1; }
+
+echo "✅ Gate 09-evaluate passou"
+```
+
+---
+
+## Passo 6: Finalizar Estado do Workflow
+
+```bash
+if command -v jq &> /dev/null; then
+  jq '
+    .currentPhase = "COMPLETED" |
+    .completedPhases += ["09-evaluate"] |
+    .completedAt = "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'" |
+    .resumeHint = "Workflow COMPLETO. Nenhuma acao necessaria." |
+    .lastStep = "Passo 6: Finalizar Estado"
+  ' .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=COMPLETED, all phases complete"
+fi
+
+echo "✅ Workflow /feature COMPLETO"
+cat .claude/workflow-state.json
+```
+
+### Arquivar State File (Opcional)
+
+```bash
+# Mover para histórico após conclusão bem-sucedida
+FEATURE_SLUG=$(jq -r '.feature' .claude/workflow-state.json)
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+mkdir -p .claude/workflow-history
+mv .claude/workflow-state.json ".claude/workflow-history/${FEATURE_SLUG}-${TIMESTAMP}.json"
+```

package/config/commands/feature/playbooks/_e2e-base.md

@@ -0,0 +1,39 @@
+# E2E Validation - Base
+
+## Tipos
+
+| Tipo | Quando | Fluxo |
+|------|--------|-------|
+| auto | UI, scripts prontos | Comando direto |
+| semi-auto | APIs, webhooks | Claude trigger + poll + verify |
+| hybrid | Integracao externa | User acao + Claude verifica |
+
+---
+
+## Verificacoes que Claude Pode Fazer
+
+| Tipo | Como |
+|------|------|
+| Database | Query conforme sintaxe do projeto |
+| API | `GET /api/resource` expect 200 |
+| Logs | `grep "pattern" /logs/file` |
+| File | `ls /path/to/file` |
+
+---
+
+## Criterios de Falha
+
+E2E FALHOU se:
+1. Timeout (auto/semi-auto: 60s, hybrid: 5min)
+2. Criterio de sucesso nao atingido
+3. Erro inesperado
+4. User: "Nao consigo" (hybrid)
+
+---
+
+## Recovery
+
+SE E2E falhou:
+1. Perguntar ao user se quer debugar
+2. SE sim: `/debug` workflow
+3. SE nao: continuar (marcar FAILED)

package/config/commands/feature/playbooks/api/analyze.md

@@ -0,0 +1,20 @@
+# API - Analyze
+
+## Localizacao
+- `api/handlers/` - Handler functions
+- `api/routes/` - Route definitions
+- `services/` - Business logic
+
+## Pattern de Handler (Producao)
+```typescript
+export async function handleFeature(req, res) {
+  const data = featureSchema.parse(req.body);
+  const result = await featureService.execute(data);
+  res.json(result);
+}
+```
+
+## Criterios de Testabilidade
+- Endpoint novo: Integration obrigatorio
+- Validacao de input: Unit recomendado
+- Multiplos servicos: Integration com mocks

package/config/commands/feature/playbooks/api/e2e.md

@@ -0,0 +1,29 @@
+# API - E2E
+
+## Tipo Recomendado: semi-auto
+
+API pode ser testada via request + verificacao automatizada.
+
+## Template
+
+```markdown
+## E2E Validation
+
+**Tipo:** semi-auto
+
+**Trigger:** `POST /api/{endpoint}` com payload:
+```json
+{ "field": "value" }
+```
+
+**Verificacoes do Claude:**
+- [ ] Response status 200/201
+- [ ] Response body contem campos esperados
+- [ ] Query DB: verificar registro criado/atualizado
+
+**Criterio de Sucesso:**
+- [ ] Record existe no DB com campos corretos
+```
+
+## Alternativa: hybrid
+SE depender de integracao externa (OAuth, webhook externo).

package/config/commands/feature/playbooks/api/red.md

@@ -0,0 +1,66 @@
+# API - RED (Testes)
+
+## Testes Requeridos
+
+| Tipo | Obrigatorio | Motivo |
+|------|-------------|--------|
+| Unit | SE complexo | Logica isolada com transformacoes |
+| Integration | **SIM** | Fluxo completo request->response |
+| E2E | NAO | API testada via integration |
+
+## Mocks Tipicos
+- Database: `vi.mock('./databaseService')`
+- APIs externas (identificar do projeto)
+- Auth/Session
+
+## Test Pattern (Vitest)
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock antes do import
+vi.mock('./databaseService', () => ({
+  getAllItems: vi.fn(),
+  createItem: vi.fn(),
+  updateItem: vi.fn(),
+}));
+
+import { handleFeature } from './featureHandler';
+import { getAllItems, createItem } from './databaseService';
+
+describe('handleFeature', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return data when valid input', async () => {
+    vi.mocked(getAllItems).mockResolvedValue([{ id: '1', name: 'Test' }]);
+
+    const result = await handleFeature({ campaign: 'X' });
+
+    expect(result.success).toBe(true);
+    expect(getAllItems).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle empty results', async () => {
+    vi.mocked(getAllItems).mockResolvedValue([]);
+
+    const result = await handleFeature({ campaign: 'Y' });
+
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual([]);
+  });
+
+  it('should propagate errors', async () => {
+    vi.mocked(getAllItems).mockRejectedValue(new Error('DB error'));
+
+    await expect(handleFeature({ campaign: 'Z' }))
+      .rejects.toThrow('DB error');
+  });
+});
+```
+
+## Convenções
+- 1 criterio do contract -> 1+ testes
+- Usar `vi.mocked()` para type-safe mocks
+- `beforeEach` com `vi.clearAllMocks()`

package/config/commands/feature/playbooks/job/analyze.md

@@ -0,0 +1,29 @@
+# Job - Analyze
+
+## Localizacao
+- `cron/` - Cron job definitions
+- `jobs/` - Job handlers
+- `executors/` - Job executors
+
+## Pattern de Job (Producao)
+```typescript
+export async function executeFeatureJob(context: JobContext) {
+  const items = await fetchPendingItems();
+  for (const item of items) {
+    await processItem(item);
+  }
+  return { processed: items.length };
+}
+
+// Executor pattern
+export const featureExecutor = {
+  name: 'feature-job',
+  schedule: '0 */6 * * *',
+  handler: executeFeatureJob
+};
+```
+
+## Criterios de Testabilidade
+- Job novo: Integration obrigatorio
+- Logica de retry: Unit recomendado
+- Job simples: Integration basico

package/config/commands/feature/playbooks/job/e2e.md

@@ -0,0 +1,30 @@
+# Job - E2E
+
+## Tipo Recomendado: hybrid
+
+Jobs requerem trigger manual ou aguardar schedule.
+
+## Template
+
+```markdown
+## E2E Validation
+
+**Tipo:** hybrid
+
+**Acao do User:**
+- [ ] Disparar job via admin/script
+  OU
+- [ ] Aguardar execucao automatica
+
+**Verificacoes do Claude:**
+- [ ] Query DB: verificar status do job
+- [ ] Verificar logs: `grep "job.completed"`
+- [ ] Confirmar side effects: registros processados > 0
+
+**Criterio de Sucesso:**
+- [ ] Job status = 'completed'
+- [ ] Nenhum erro nos logs
+```
+
+## Alternativa: semi-auto
+SE job puder ser disparado via API interna.

package/config/commands/feature/playbooks/job/red.md

@@ -0,0 +1,77 @@
+# Job - RED (Testes)
+
+## Testes Requeridos
+
+| Tipo | Obrigatorio | Motivo |
+|------|-------------|--------|
+| Unit | SE complexo | Logica de transformacao |
+| Integration | **SIM** | Fluxo completo do job |
+| E2E | NAO | Jobs testados via integration |
+
+## Mocks Tipicos
+- Database: `vi.mock('./databaseService')`
+- Schedulers (Cloud Scheduler, cron)
+- APIs externas (notificacoes, etc)
+- Message queue (se aplicavel)
+
+## Test Pattern (Vitest)
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('./databaseService', () => ({
+  getPendingItems: vi.fn(),
+  updateItemStatus: vi.fn(),
+}));
+
+import { executeFeatureJob } from './featureJob';
+import { getPendingItems, updateItemStatus } from './databaseService';
+
+describe('executeFeatureJob', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should process all pending items', async () => {
+    vi.mocked(getPendingItems).mockResolvedValue([
+      { id: '1', status: 'pending' },
+      { id: '2', status: 'pending' },
+    ]);
+    vi.mocked(updateItemStatus).mockResolvedValue(undefined);
+
+    const result = await executeFeatureJob({ runId: 'test' });
+
+    expect(result.processed).toBe(2);
+    expect(updateItemStatus).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle empty queue', async () => {
+    vi.mocked(getPendingItems).mockResolvedValue([]);
+
+    const result = await executeFeatureJob({ runId: 'test' });
+
+    expect(result.processed).toBe(0);
+    expect(updateItemStatus).not.toHaveBeenCalled();
+  });
+
+  it('should continue on item failure', async () => {
+    vi.mocked(getPendingItems).mockResolvedValue([
+      { id: '1', status: 'pending' },
+      { id: '2', status: 'pending' },
+    ]);
+    vi.mocked(updateItemStatus)
+      .mockRejectedValueOnce(new Error('Item 1 failed'))
+      .mockResolvedValueOnce(undefined);
+
+    const result = await executeFeatureJob({ runId: 'test' });
+
+    expect(result.processed).toBe(1);
+    expect(result.errors.length).toBe(1);
+  });
+});
+```
+
+## Convenções
+- Testar processamento em batch
+- Testar comportamento com erros parciais
+- Testar fila vazia

package/config/commands/feature/playbooks/service/analyze.md

@@ -0,0 +1,28 @@
+# Service - Analyze
+
+## Localizacao
+- `services/` - Business logic services
+- `utils/` - Utility functions
+- `lib/` - Shared libraries
+
+## Pattern de Service (Producao)
+```typescript
+export const featureService = {
+  async execute(input: FeatureInput): Promise<FeatureOutput> {
+    const validated = featureSchema.parse(input);
+    // business logic
+    return result;
+  }
+};
+
+// Utility pattern
+export function transformData(input: Input): Output {
+  // pure transformation
+  return output;
+}
+```
+
+## Criterios de Testabilidade
+- Funcao pura: Unit obrigatorio
+- Servico com DB: Unit + Integration
+- Utility simples: Unit basico

package/config/commands/feature/playbooks/service/e2e.md

@@ -0,0 +1,25 @@
+# Service - E2E
+
+## Tipo Recomendado: auto (integration test)
+
+Services sao testados via integration tests existentes.
+
+## Template
+
+```markdown
+## E2E Validation
+
+**Tipo:** auto
+
+**Script/Ferramenta:** integration test existente
+
+**Cenario:**
+- Given: {pre-condicao}
+- When: service.execute({input})
+- Then: {resultado esperado}
+
+**Comando:** `npm test -- --grep "{nome-do-teste}"`
+```
+
+## Alternativa: hybrid
+SE depender de sistema externo nao mockavel.

package/config/commands/feature/playbooks/service/red.md

@@ -0,0 +1,75 @@
+# Service - RED (Testes)
+
+## Testes Requeridos
+
+| Tipo | Obrigatorio | Motivo |
+|------|-------------|--------|
+| Unit | **SIM** | Logica pura e isolada |
+| Integration | SE multi-service | Interacao entre servicos |
+| E2E | NAO | Servicos testados via unit/integration |
+
+## Mocks Tipicos
+- Database: `vi.mock('./databaseService')`
+- APIs externas
+- File system (se aplicavel)
+
+## Test Pattern (Vitest) - Service
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('./databaseService', () => ({
+  getAll: vi.fn(),
+  getItems: vi.fn(),
+  create: vi.fn(),
+  update: vi.fn(),
+}));
+
+import { processItems } from './itemService';
+import { getAll, create } from './databaseService';
+
+describe('processItems', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create new items from unique tags', async () => {
+    vi.mocked(getAll).mockResolvedValue([
+      { id: 'item-1', tags: ['Tag A'] },
+      { id: 'item-2', tags: ['Tag A', 'Tag B'] },
+    ]);
+    vi.mocked(create).mockResolvedValue('new-id');
+
+    const result = await processItems();
+
+    expect(result.success).toBe(true);
+    expect(result.created).toBe(2);
+    expect(create).toHaveBeenCalledTimes(2);
+  });
+});
+```
+
+## Test Pattern (Vitest) - Utility
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { transformData } from './dataTransformer';
+
+describe('transformData', () => {
+  it('should transform input correctly', () => {
+    const input = { raw: 'value' };
+    const result = transformData(input);
+    expect(result.processed).toBe('VALUE');
+  });
+
+  it('should handle edge cases', () => {
+    expect(transformData({ raw: '' })).toEqual({ processed: '' });
+    expect(transformData({ raw: null })).toEqual({ processed: null });
+  });
+});
+```
+
+## Convenções
+- Services: mock dependencias externas
+- Utilities: testar como funcoes puras (sem mocks)
+- `vi.clearAllMocks()` no beforeEach

package/config/commands/feature/playbooks/ui/analyze.md

@@ -0,0 +1,26 @@
+# UI - Analyze
+
+## Localizacao
+- `components/` - React components
+- `app/` - Next.js pages/routes
+- `hooks/` - Custom hooks
+
+## Pattern de Component (Producao)
+```typescript
+export function FeatureComponent({ data }: FeatureProps) {
+  const { state, actions } = useFeature(data);
+  return <div>...</div>;
+}
+
+// Hook pattern
+export function useFeature(initial) {
+  const [state, setState] = useState(initial);
+  // ...
+  return { state, actions };
+}
+```
+
+## Criterios de Testabilidade
+- Formulario novo: E2E obrigatorio
+- Hook com logica: Unit obrigatorio
+- Componente display-only: Nenhum

package/config/commands/feature/playbooks/ui/e2e.md

@@ -0,0 +1,61 @@
+# UI - E2E
+
+## Tipo Recomendado: auto (Playwright)
+
+Fluxos visuais testados via browser automation.
+
+## Template
+
+```markdown
+## E2E Validation
+
+**Tipo:** auto
+
+**Script/Ferramenta:** Playwright + functional-validator
+
+**Cenario:**
+- Given: Usuario na pagina {page}
+- When: Usuario preenche form e submete
+- Then: {resultado visual/funcional}
+
+**Comando:** `npm run test:e2e -- {arquivo.spec.ts}`
+```
+
+## Playwright Pattern
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('should submit form successfully', async ({ page }) => {
+  await page.goto('/feature');
+
+  await page.fill('[name="title"]', 'Test Title');
+  await page.fill('[name="description"]', 'Test Description');
+  await page.click('button[type="submit"]');
+
+  await expect(page.locator('.success-message')).toBeVisible();
+  await expect(page).toHaveURL(/\/feature\/[a-z0-9]+/);
+});
+```
+
+## Alternativa: hybrid (fallback)
+SE Playwright falhar ou for overkill:
+
+```markdown
+## E2E Validation
+
+**Tipo:** hybrid
+
+**Acao do User:**
+- [ ] Navegue para {url}
+- [ ] Execute {acao}
+- [ ] Confirme visualmente o resultado
+
+**Verificacoes do Claude:**
+- [ ] API call: `GET /api/{resource}` retorna dados esperados
+- [ ] Query DB: verificar dados persistidos
+
+**Criterio de Sucesso:**
+- [ ] User confirma que UI funcionou
+- [ ] Dados persistidos corretamente
+```