kakaroto-config 1.0.0 → 1.0.2

package/README.md

@@ -5,43 +5,149 @@ Claude Code configuration for autonomous development workflows.
 ## Quick Install
 
 ```bash
+# Local installation (recommended - installs to ./.claude/)
 npx kakaroto-config
+
+# Global installation (installs to ~/.claude/)
+npx kakaroto-config --global
+```
+
+**Local is recommended** because each project can have its own customizations while inheriting the global rules.
+
+## Updating
+
+To update to the latest version, run the same command again:
+
+```bash
+# Update local installation
+npx kakaroto-config@latest
+
+# Update global installation
+npx kakaroto-config@latest --global
 ```
 
-This installs the configuration to `~/.claude/`.
+The installer will detect the existing `.claude/` folder and ask if you want to overwrite.
 
-## What's Included
+> **Note:** If you previously installed globally (`~/.claude/`) and want to switch to local (`./.claude/`), just run `npx kakaroto-config@latest` in your project folder. Both can coexist - Claude Code will use local config when available.
 
-### Skills (Commands)
+## What Gets Installed
 
-| Skill | Description |
-|-------|-------------|
-| `/feature` | Full feature development workflow (interview → spec → plan → implement → quality) |
-| `/debug` | Bug resolution with 5 Whys methodology (investigate → fix → verify) |
-| `/gate` | Quality gate before PR (runs 7 validation agents) |
+```
+.claude/
+├── CLAUDE.md              # Global rules (autonomy, coding standards)
+├── ARCHITECTURE.md        # Full documentation of the system
+├── commands/              # Skills (invoked via /skill)
+│   ├── feature.md         # /feature orchestrator
+│   ├── feature/           # 5 phases: interview → spec → plan → implement → quality
+│   ├── debug.md           # /debug orchestrator
+│   ├── debug/             # 5 phases: reproduce → investigate → fix → verify → commit
+│   └── gate.md            # /gate - quality gate before PR
+└── agents/                # 7 specialized subagents
+    ├── test-fixer.md
+    ├── code-reviewer.md
+    ├── code-simplifier.md
+    ├── dry-enforcer.md
+    ├── visual-validator.md
+    ├── terraform-validator.md
+    └── memory-sync.md
+```
+
+## Skills (Commands)
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| `/feature` | "adicionar", "implementar", "criar" | Full feature workflow with spec, planning, and quality gates |
+| `/debug` | "bug", "erro", "problema" | Bug resolution with 5 Whys methodology |
+| `/gate` | Manual | Run all 7 quality agents before PR |
 
-### Agents (Subagents)
+## Agents (Subagents)
 
 | Agent | Purpose |
 |-------|---------|
 | `test-fixer` | Runs tests, fixes failures, creates missing tests |
 | `code-reviewer` | Reviews code quality, security, auto-fixes issues |
 | `code-simplifier` | Reduces complexity, improves readability |
-| `dry-enforcer` | Detects duplication, suggests reuse |
+| `dry-enforcer` | Detects duplication, suggests code reuse |
 | `visual-validator` | Validates UI with Playwright |
 | `terraform-validator` | Validates env vars and Terraform consistency |
 | `memory-sync` | Syncs knowledge to MCP Memory |
 
 ## Philosophy
 
-- **FAZER, não perguntar** - Agents fix issues automatically
-- **BUSCAR, não pedir contexto** - Use MCP Memory and codebase exploration
-- **Código sem teste = PR rejeitado** - Tests are mandatory
-- **Erros: corrigir e continuar** - Don't stop on failures
+The configuration enforces autonomous development:
+
+| Principle | Meaning |
+|-----------|---------|
+| **FAZER, nao perguntar** | Agents fix issues automatically, don't ask for confirmation |
+| **BUSCAR, nao pedir contexto** | Use MCP Memory and codebase exploration, don't ask user for context |
+| **Codigo sem teste = PR rejeitado** | Tests are mandatory (blocking) |
+| **Erros: corrigir e continuar** | Fix errors automatically, don't stop workflow |
+
+## After Installation
+
+### 1. Create Project CLAUDE.md (Optional but Recommended)
+
+Create a `CLAUDE.md` in your project root with project-specific info:
+
+```markdown
+# Project Name
+
+## Commands
+- `npm run dev` - Start dev server
+- `npm run build` - Build
+- `npm run test` - Run tests
+
+## Structure
+- `src/` - Source code
+- `tests/` - Tests
+
+## MCP Memory Namespace
+Prefix: `myproject:`
+```
+
+### 2. Add Custom Skills (Optional)
+
+Create `.claude/commands/your-skill.md` for project-specific workflows.
+
+## Workflow Examples
+
+### Feature Development
+
+```
+User: "adiciona filtro de data na listagem"
+         ↓
+Claude automatically triggers /feature
+         ↓
+01-interview → Explores codebase, asks clarifying questions
+02-spec      → Generates technical specification
+03-planner   → Creates implementation plan (requires approval)
+04-implement → Writes code following spec and plan
+05-quality   → Runs all 7 quality agents
+         ↓
+Ready for PR
+```
+
+### Bug Resolution
+
+```
+User: "erro ao salvar formulario"
+         ↓
+Claude automatically triggers /debug
+         ↓
+01-reproduce   → Reproduces the bug
+02-investigate → 5 Whys analysis with evidence
+03-fix         → Minimal fix + mandatory test
+04-verify      → Confirms fix works
+05-commit      → Creates commit
+         ↓
+Done
+```
 
-## Documentation
+## Requirements
 
-After installation, read `~/.claude/ARCHITECTURE.md` for full documentation.
+- Claude Code CLI
+- MCP Memory server (optional, for knowledge persistence)
+- Playwright MCP (optional, for visual validation)
 
 ## License
 

package/bin/install.js

@@ -5,7 +5,26 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 
-const CLAUDE_DIR = path.join(os.homedir(), '.claude');
+const args = process.argv.slice(2);
+const isGlobal = args.includes('--global');
+const showHelp = args.includes('--help') || args.includes('-h');
+
+if (showHelp) {
+  console.log(`
+Usage: npx kakaroto-config [options]
+
+Options:
+  --global    Install to ~/.claude/ (global, all projects)
+  --help, -h  Show this help message
+
+Default: Install to ./.claude/ (local, current project)
+`);
+  process.exit(0);
+}
+
+const CLAUDE_DIR = isGlobal
+  ? path.join(os.homedir(), '.claude')
+  : path.join(process.cwd(), '.claude');
 const CONFIG_DIR = path.join(__dirname, '..', 'config');
 
 const rl = readline.createInterface({
@@ -52,9 +71,12 @@ function countFiles(dir) {
 }
 
 async function main() {
+  const targetPath = isGlobal ? '~/.claude/' : './.claude/ (local)';
+  const targetDisplay = isGlobal ? '~/.claude/' : '.claude/';
+
   console.log('\n🥋 kakaroto-config - Claude Code Configuration\n');
-  console.log('This will install the following to ~/.claude/:');
-  console.log('  - CLAUDE.md (global rules)');
+  console.log(`This will install the following to ${targetPath}:`);
+  console.log('  - CLAUDE.md (rules)');
   console.log('  - ARCHITECTURE.md (documentation)');
   console.log('  - commands/ (skills: /feature, /debug, /gate)');
   console.log('  - agents/ (7 specialized subagents)\n');
@@ -63,7 +85,7 @@ async function main() {
   console.log(`Total: ${fileCount} files\n`);
 
   if (fs.existsSync(CLAUDE_DIR)) {
-    const answer = await question('~/.claude/ already exists. Overwrite? (y/N): ');
+    const answer = await question(`${targetDisplay} already exists. Overwrite? (y/N): `);
     if (answer.toLowerCase() !== 'y') {
       console.log('\nAborted. No changes made.');
       rl.close();
@@ -89,7 +111,7 @@ async function main() {
     console.log('  2. Try /feature to create a new feature');
     console.log('  3. Try /debug to fix a bug');
     console.log('  4. Try /gate before creating a PR\n');
-    console.log('Read ~/.claude/ARCHITECTURE.md for full documentation.\n');
+    console.log(`Read ${targetDisplay}ARCHITECTURE.md for full documentation.\n`);
   } catch (err) {
     console.error('Error during installation:', err.message);
     process.exit(1);

package/bin/release.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execFileSync } = require('child_process');
+
+// Constants
+const HOME_CLAUDE = path.join(os.homedir(), '.claude');
+const PROJECT_ROOT = path.join(__dirname, '..');
+const CONFIG_DIR = path.join(PROJECT_ROOT, 'config');
+const PACKAGE_JSON = path.join(PROJECT_ROOT, 'package.json');
+
+// Exclusions - personal files not to publish
+const EXCLUDED_COMMANDS = ['audit-command', 'audit-command.md'];
+
+// Semver validation regex
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+
+// Readline interface
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+function cleanDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function copyRecursive(src, dest, excludes = []) {
+  const stats = fs.statSync(src);
+
+  if (stats.isDirectory()) {
+    const baseName = path.basename(src);
+    if (excludes.includes(baseName)) {
+      return; // Skip excluded directories
+    }
+
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+
+    const files = fs.readdirSync(src);
+    for (const file of files) {
+      if (excludes.includes(file)) {
+        continue; // Skip excluded files
+      }
+      copyRecursive(path.join(src, file), path.join(dest, file), excludes);
+    }
+  } else {
+    const baseName = path.basename(src);
+    if (excludes.includes(baseName)) {
+      return; // Skip excluded files
+    }
+    fs.copyFileSync(src, dest);
+    console.log(`  + ${path.relative(CONFIG_DIR, dest)}`);
+  }
+}
+
+function bumpVersion(version) {
+  if (!SEMVER_REGEX.test(version)) {
+    throw new Error(`Invalid semver format: ${version}. Expected X.Y.Z`);
+  }
+  const parts = version.split('.');
+  parts[2] = String(parseInt(parts[2], 10) + 1);
+  return parts.join('.');
+}
+
+function execCommandSafe(executable, args, description) {
+  console.log(`\n${description}...`);
+  try {
+    execFileSync(executable, args, { cwd: PROJECT_ROOT, stdio: 'inherit' });
+    return true;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return false;
+  }
+}
+
+function countFiles(dir, excludes = []) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+
+  const items = fs.readdirSync(dir);
+  for (const item of items) {
+    if (excludes.includes(item)) continue;
+
+    const fullPath = path.join(dir, item);
+    if (fs.statSync(fullPath).isDirectory()) {
+      count += countFiles(fullPath, excludes);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+async function main() {
+  console.log('\n🥋 kakaroto-config - Release\n');
+
+  // Check ~/.claude exists
+  if (!fs.existsSync(HOME_CLAUDE)) {
+    console.error(`Error: ${HOME_CLAUDE} does not exist`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // Read current version
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf8'));
+  } catch (err) {
+    console.error(`Error reading package.json: ${err.message}`);
+    rl.close();
+    process.exit(1);
+  }
+
+  const currentVersion = pkg.version;
+  let newVersion;
+  try {
+    newVersion = bumpVersion(currentVersion);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // Count files to sync
+  const commandsCount = countFiles(path.join(HOME_CLAUDE, 'commands'), EXCLUDED_COMMANDS);
+  const agentsCount = countFiles(path.join(HOME_CLAUDE, 'agents'));
+  const templatesCount = countFiles(path.join(HOME_CLAUDE, 'templates'));
+  const totalFiles = commandsCount + agentsCount + templatesCount + 2; // +2 for CLAUDE.md and ARCHITECTURE.md
+
+  // Show preview
+  console.log('This will:');
+  console.log(`  1. Sync ${totalFiles} files from ~/.claude/ to config/`);
+  console.log(`     - CLAUDE.md`);
+  console.log(`     - ARCHITECTURE.md`);
+  console.log(`     - commands/ (${commandsCount} files, excluding audit-command)`);
+  console.log(`     - agents/ (${agentsCount} files)`);
+  console.log(`     - templates/ (${templatesCount} files)`);
+  console.log(`  2. Bump version: ${currentVersion} → ${newVersion}`);
+  console.log(`  3. Git commit and push`);
+  console.log(`  4. Publish to npm\n`);
+
+  // Confirm
+  const answer = await question('Proceed with release? (Y/n): ');
+  if (answer.toLowerCase() === 'n') {
+    console.log('\nAborted. No changes made.');
+    rl.close();
+    process.exit(0);
+  }
+
+  console.log('\n--- Syncing files ---\n');
+
+  // Clean directories
+  cleanDir(path.join(CONFIG_DIR, 'commands'));
+  cleanDir(path.join(CONFIG_DIR, 'agents'));
+  cleanDir(path.join(CONFIG_DIR, 'templates'));
+
+  // Ensure config directory exists
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  // Copy files with existence check
+  const claudeMdPath = path.join(HOME_CLAUDE, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    console.log('Copying CLAUDE.md...');
+    fs.copyFileSync(claudeMdPath, path.join(CONFIG_DIR, 'CLAUDE.md'));
+    console.log('  + CLAUDE.md');
+  } else {
+    console.warn('Warning: CLAUDE.md not found, skipping');
+  }
+
+  const archMdPath = path.join(HOME_CLAUDE, 'ARCHITECTURE.md');
+  if (fs.existsSync(archMdPath)) {
+    console.log('Copying ARCHITECTURE.md...');
+    fs.copyFileSync(archMdPath, path.join(CONFIG_DIR, 'ARCHITECTURE.md'));
+    console.log('  + ARCHITECTURE.md');
+  } else {
+    console.warn('Warning: ARCHITECTURE.md not found, skipping');
+  }
+
+  console.log('Copying commands/...');
+  copyRecursive(
+    path.join(HOME_CLAUDE, 'commands'),
+    path.join(CONFIG_DIR, 'commands'),
+    EXCLUDED_COMMANDS
+  );
+
+  console.log('Copying agents/...');
+  copyRecursive(
+    path.join(HOME_CLAUDE, 'agents'),
+    path.join(CONFIG_DIR, 'agents')
+  );
+
+  if (fs.existsSync(path.join(HOME_CLAUDE, 'templates'))) {
+    console.log('Copying templates/...');
+    copyRecursive(
+      path.join(HOME_CLAUDE, 'templates'),
+      path.join(CONFIG_DIR, 'templates')
+    );
+  }
+
+  // Update package.json
+  console.log('\n--- Updating version ---\n');
+  pkg.version = newVersion;
+  fs.writeFileSync(PACKAGE_JSON, JSON.stringify(pkg, null, 2) + '\n');
+  console.log(`Updated package.json: ${currentVersion} → ${newVersion}`);
+
+  // Git operations - use execCommandSafe for commands with user-derived values
+  if (!execCommandSafe('git', ['add', '.'], 'Staging changes')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  // Use execCommandSafe to prevent command injection via newVersion
+  if (!execCommandSafe('git', ['commit', '-m', `release: v${newVersion}`], 'Creating commit')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  if (!execCommandSafe('git', ['push'], 'Pushing to remote')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  // npm publish
+  if (!execCommandSafe('npm', ['publish'], 'Publishing to npm')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  console.log(`\n✅ Release complete! Published v${newVersion}\n`);
+  console.log('Users can update with:');
+  console.log(`  npx kakaroto-config@${newVersion}\n`);
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error(`Unexpected error: ${err.message}`);
+  rl.close();
+  process.exit(1);
+});

package/config/ARCHITECTURE.md

@@ -132,7 +132,8 @@ projeto/.claude/
 │
 ├── settings.json             # Config do Claude Code
 ├── visual-validation.json    # Routes para visual-validator (opcional)
-└── terraform-validation.json # Paths para terraform-validator (opcional)
+├── terraform-validation.json # Paths para terraform-validator (opcional)
+└── debug-logs.json           # Comandos para query de logs de producao (opcional)
 ```
 
 **Personalizacoes por projeto:**
@@ -142,6 +143,7 @@ projeto/.claude/
 | `commands/*.md` | Skills especificas (deploy, E2E, migrations) | Quando projeto tem workflows unicos |
 | `visual-validation.json` | Mapeia components → routes para teste | Projetos com UI complexa |
 | `terraform-validation.json` | Paths de env vars e terraform | Projetos com infra como codigo |
+| `debug-logs.json` | Comandos para query de logs de producao | Projetos com logs em Cloud Logging, CloudWatch, etc. |
 | `settings.json` | Modelo default, permissoes, etc. | Config avancada |
 
 **CLAUDE.md do projeto deve conter:**

package/config/CLAUDE.md

@@ -22,3 +22,7 @@ Exceções: config files, .d.ts, UI puro sem lógica.
 ## Memory
 Namespace: ver CLAUDE.md do projeto.
 Sincronizar via `memory-sync` ao final de workflows.
+
+## Auto-Avaliacao
+Apos /feature e /debug: executar fase de avaliacao (07/06-evaluate).
+Dual-loop sequential thinking: diagnostico → sintese → propor melhorias ao user.

package/config/agents/memory-sync.md

@@ -15,14 +15,29 @@ Sincronizar conhecimento adquirido com MCP Memory apos desenvolvimento.
 2. `git diff --stat` para entender escopo das mudancas
 3. Identificar o prefixo do projeto via `mcp__memory__search_nodes({ query: "config" })`
 
-## Fase 2: Verificar Entidades Existentes
+## Fase 2: Verificar Entidades Existentes + Garbage Collection
 
 1. `mcp__memory__read_graph()` para ver todas entidades do projeto
 2. Filtrar entidades pelo prefixo do projeto (ex: `sm:` para social-medias)
-3. Para cada arquivo modificado/deletado:
+3. **CONTAR entidades do projeto atual**:
+   - Se > 50 entidades → executar Garbage Collection abaixo
+   - Se ≤ 50 → prosseguir normalmente
+
+### Garbage Collection (se > 50 entidades)
+
+Identificar e REMOVER:
+
+| Candidata | Critério | Ação |
+|-----------|----------|------|
+| Bugs | entityType === "bug" | DELETE todos |
+| Outros projetos | nome não começa com prefixo atual | DELETE |
+| Versões duplicadas | nome contém "-v2", "-v3" | MERGE em original, DELETE versão |
+| Arquivos inexistentes | observation referencia arquivo deletado | DELETE se única referência |
+
+4. Para cada arquivo modificado/deletado:
    - Buscar entidades que o referenciam (grep no campo observations)
-   - SE arquivo deletado -> marcar entidade para atualizacao
-   - SE arquivo renomeado -> atualizar referencias
+   - SE arquivo deletado -> marcar entidade para atualização
+   - SE arquivo renomeado -> atualizar referências
    - SE comportamento mudou -> atualizar observations
 
 ## Fase 3: Atualizar Entidades Obsoletas
@@ -45,13 +60,15 @@ Avaliar o que foi desenvolvido e criar entidades conforme tabela:
 
 | Situacao | Namespace | Criar? |
 |----------|-----------|--------|
-| Padrao novo implementado | `{prefix}:pattern:{nome}` | SIM |
+| Padrão novo implementado | `{prefix}:pattern:{nome}` | SIM |
 | Fluxo complexo entendido | `{prefix}:fluxo:{nome}` | SIM |
-| Bug nao-obvio resolvido | `{prefix}:bug:{nome}` | SIM |
-| Servico novo/modificado significativamente | `{prefix}:servico:{nome}` | SE significativo |
-| Tipo importante descoberto | `{prefix}:tipo:{nome}` | SE reutilizavel |
+| Serviço novo/modificado significativamente | `{prefix}:servico:{nome}` | SE significativo |
+| Tipo importante descoberto | `{prefix}:tipo:{nome}` | SE reutilizável |
 | Procedimento documentado | `{prefix}:procedimento:{nome}` | SIM |
-| Analise importante feita | `{prefix}:analise:{nome}` | SE referenciavel |
+| Análise importante feita | `{prefix}:analise:{nome}` | SE referenciável |
+| Config de projeto | `{prefix}:config:{nome}` | APENAS config:main |
+
+**REMOVIDO**: `{prefix}:bug:{nome}` - bugs são efêmeros, fixes vão no código
 
 ### Criterio "Vale Salvar"
 
@@ -68,18 +85,34 @@ Avaliar o que foi desenvolvido e criar entidades conforme tabela:
 - Detalhes de implementacao que mudam frequentemente
 - Duplicatas de entidades existentes
 
+### Pre-Flight Check (OBRIGATÓRIO antes de criar)
+
+Antes de `mcp__memory__create_entities`, verificar:
+
+```
+[ ] Nome usa prefixo correto do projeto atual?
+[ ] Nome está em kebab-case?
+[ ] Não é um bug? (bugs não devem ser salvos)
+[ ] Não existe entidade similar? (usar search_nodes)
+[ ] Não é versão de entidade existente? (update, não create)
+[ ] Máximo 10 observations?
+[ ] Informação não é óbvia pelo código?
+```
+
+Se QUALQUER check falhar → NÃO CRIAR
+
 ### Formato de Entidade
 
 ```javascript
 mcp__memory__create_entities({
   entities: [{
     name: "{prefix}:{tipo}:{nome-kebab-case}",
-    entityType: "{tipo}",  // pattern, bug, fluxo, servico, etc.
+    entityType: "{tipo}",  // pattern, fluxo, servico, etc. (NUNCA bug)
     observations: [
-      "Primeira linha: resumo do que e",
+      "Primeira linha: resumo do que é",
       "Segunda linha: arquivo principal: path/to/file.ts",
-      "Demais linhas: detalhes relevantes",
-      "Ultima linha: quando/por que foi criado"
+      "Demais linhas: detalhes relevantes (max 8 linhas adicionais)",
+      "Última linha: quando/por que foi criado"
     ]
   }]
 })
@@ -110,13 +143,48 @@ Ao final, reportar:
 - OU: Todas entidades ja estao atualizadas
 ```
 
-## Regras
+## Regras OBRIGATÓRIAS
+
+### Namespace & Escopo
+
+1. **Prefixo obrigatório**: TODA entidade DEVE usar o prefixo do projeto atual
+2. **NUNCA criar entidades de outros projetos** (ex: `ga:`, `kk:` quando trabalhando em `sm:`)
+3. **Validar namespace**: Antes de criar, verificar se prefixo corresponde ao projeto
+
+### Controle de Tamanho
+
+4. **Max 10 observations por entidade**: Se precisar de mais, dividir em entidades relacionadas
+5. **Max 50 entidades por projeto**: Se ultrapassar, fazer garbage collection
+6. **Nomes kebab-case**: `sm:pattern:graceful-shutdown`, não `sm:pattern:GracefulShutdown`
+7. **Observations atômicas**: Uma informação por linha, fácil de deletar/atualizar
+
+### O que NÃO salvar
+
+8. **NUNCA salvar bugs como entidades** - bugs são efêmeros, fixes vão no código
+   - Exception: Bug recorrente que revela pattern arquitetural → salvar como `pattern:`
+9. **NUNCA criar versões** (v2, v3) - ATUALIZAR a entidade existente
+10. **NUNCA duplicar**: Buscar entidade similar antes de criar (`search_nodes`)
+11. **Minimalismo radical**: Na dúvida, NÃO salvar
+
+### Garbage Collection (executar se >50 entidades)
+
+```javascript
+// Identificar candidatas a remoção:
+// 1. Entidades que referenciam arquivos deletados
+// 2. Entidades com >15 observations (muito verbosas)
+// 3. Entidades com informação duplicada de outra
+// 4. Bugs antigos (>30 dias)
+```
+
+### Anti-Patterns a EVITAR
 
-1. **Prefixo obrigatorio**: Toda entidade deve usar o prefixo do projeto
-2. **Nomes kebab-case**: `sm:bug:tiktok-media-id-vazio`, nao `sm:bug:TikTokMediaIdVazio`
-3. **Observations atomicas**: Uma informacao por linha, facil de deletar/atualizar
-4. **Nao duplicar**: Verificar se entidade similar ja existe antes de criar
-5. **Minimalismo**: Na duvida, nao salvar. Menos entidades de qualidade > muitas entidades ruins
+| Anti-Pattern | Exemplo | Correção |
+|--------------|---------|----------|
+| Bug como entidade | `sm:bug:login-error` | DELETE - fix está no código |
+| Versões separadas | `sm:pattern:X-v2` | UPDATE `sm:pattern:X` |
+| Cross-project | `ga:feature:Y` no sm: | DELETE - pertence a outro projeto |
+| Observations demais | 17 observations | Condensar em 8-10 |
+| Tipo duplicado | `pattern` + `padrao` | Usar apenas `pattern` |
 
 ---
 

package/config/agents/test-fixer.md

@@ -58,6 +58,30 @@ npm run test
 
 ---
 
+## Step Extra: CRUD Smoke Test (SE nova entidade)
+
+**Trigger:** Arquivo em `api/handlers/` com novo endpoint POST/PUT criado.
+
+1. Identificar endpoints novos:
+   ```bash
+   git diff --name-only HEAD~1 | grep 'api/handlers/'
+   ```
+
+2. Para cada arquivo de handler modificado:
+   - Buscar métodos POST/PUT/DELETE
+   - Construir payload de teste válido
+   - Executar request contra servidor local (se rodando)
+   - Verificar response 200/201
+
+3. Reportar:
+   - Endpoints testados
+   - Resultados (PASS/FAIL)
+   - Erros encontrados
+
+**Nota:** Este step é condicional. Só executar se houver novos endpoints CRUD.
+
+---
+
 ## Test Creation Guidelines
 
 ### File Location