cmp-standards 2.0.1 → 2.4.0

package/standards/experts/expert-routing.md

@@ -0,0 +1,215 @@
+# Expert Routing - Cuándo Consultar Expertos
+
+## Principio
+
+Los expertos (`/experts`) validan código crítico. No todo código necesita revisión de expertos.
+
+## Cuándo Consultar
+
+### SIEMPRE Consultar
+
+| Área | Expertos | Por qué |
+|------|----------|---------|
+| **Finanzas** | Security, Architecture | Dinero real, dual-write requerido |
+| **Autenticación** | Security, Architecture | Seguridad crítica |
+| **Schema DB** | Database, Architecture | Cambios irreversibles |
+| **Pagos externos** | Security, Performance | Integraciones sensibles |
+
+```bash
+# Ejemplos de rutas críticas
+src/server/api/routers/finances/**
+src/server/api/routers/auth/**
+src/server/schema/**
+drizzle/migrations/**
+```
+
+### CONSIDERAR Consultar
+
+| Área | Expertos | Cuándo |
+|------|----------|--------|
+| **APIs** | Performance, Architecture | Si es nueva o cambia contrato |
+| **Componentes UI** | UX, Performance | Si es core o afecta muchos usuarios |
+| **Refactoring** | Architecture | Si toca múltiples dominios |
+
+### NO Consultar
+
+- Typos y fixes menores
+- Documentación
+- Tests
+- Código experimental/WIP
+- Generado automáticamente
+
+## Proceso de Consulta
+
+```
+1. Identificar cambios críticos
+   ↓
+2. Ejecutar /experts [archivos]
+   ↓
+3. Esperar consenso
+   ↓
+4. Si APPROVED → continuar
+   Si REJECTED → aplicar feedback → volver a 2
+```
+
+## Decisiones por Experto
+
+### Security Expert
+
+**Consultar cuando:**
+- Input de usuario no validado
+- Queries a base de datos
+- Operaciones financieras
+- Cambios de permisos
+
+**Busca:**
+- SQL injection
+- XSS vulnerabilities
+- Missing Zod validation
+- Finance dual-write violations
+
+### Performance Expert
+
+**Consultar cuando:**
+- Loops con await
+- Queries en componentes
+- Imports de librerías pesadas
+- Cambios en data fetching
+
+**Busca:**
+- N+1 queries
+- API waterfalls
+- Missing lazy loading
+- Unnecessary re-renders
+
+### Architecture Expert
+
+**Consultar cuando:**
+- Nuevos módulos/dominios
+- Cambios de estructura
+- Tipos compartidos
+- Imports cross-domain
+
+**Busca:**
+- Type inference chain breaks
+- Circular dependencies
+- SOLID violations
+- ADR misalignment
+
+### Database Expert
+
+**Consultar cuando:**
+- Cambios de schema
+- Nuevas migraciones
+- Queries complejas
+- Relaciones entre tablas
+
+**Busca:**
+- Missing constraints
+- Type sync issues
+- Unsafe migrations
+- N+1 patterns
+
+### UX Expert
+
+**Consultar cuando:**
+- Componentes de formulario
+- Navegación
+- Modales/overlays
+- Responsive design
+
+**Busca:**
+- Missing ARIA
+- Touch target size
+- Hardcoded colors
+- i18n issues
+
+## Reglas de Consenso
+
+### Código Crítico (Unanimidad)
+
+Todos los expertos deben aprobar:
+
+```
+✅ Security: APPROVE
+✅ Architecture: APPROVE
+✅ Database: APPROVE
+⊝ Memory: ABSTAIN
+
+Result: APPROVED (3/3 voting approved)
+```
+
+### Código Normal (Mayoría)
+
+≥3 de 5 expertos aprueban:
+
+```
+✅ Security: APPROVE
+✅ Architecture: APPROVE
+❌ Performance: REJECT
+✅ UX: APPROVE
+⊝ Memory: ABSTAIN
+
+Result: APPROVED (3/4 voting approved, 1 rejected)
+```
+
+## Integración en Workflow
+
+```markdown
+## Después de implementar
+
+1. Verificar si cambios son críticos:
+   - ¿Toca finanzas/auth/schema?
+   - ¿Nuevo dominio o refactoring grande?
+
+2. Si es crítico:
+   /experts [archivos modificados]
+
+3. Esperar resultado:
+   - APPROVED → commit
+   - REJECTED → aplicar fixes → volver a consultar
+```
+
+## Memory Expert (Especial)
+
+El Memory Expert **nunca rechaza** - su rol es aprender:
+
+- Detecta patrones repetidos (3+ = auto-improve)
+- Genera reglas ESLint automáticamente
+- Crea memorias de gotchas
+- Propone ADRs para decisiones
+
+Siempre vota ABSTAIN pero captura aprendizajes.
+
+## Comandos Rápidos
+
+```bash
+# Review archivos específicos
+/experts src/server/api/routers/finances/expenses.ts
+
+# Review directorio
+/experts src/server/api/routers/finances/
+
+# Solo expertos específicos
+/experts src/file.ts --only security,architecture
+
+# Modo verbose
+/experts src/file.ts --verbose
+```
+
+## Ejemplo de Flujo
+
+```
+Tarea: Agregar endpoint de pago
+
+1. Implementar endpoint
+2. Detectar: es código financiero → CRÍTICO
+3. Ejecutar: /experts src/server/api/routers/payments/...
+4. Resultado:
+   ❌ REJECTED - Security Expert
+   "Missing LedgerService.createEntry() for dual-write"
+5. Aplicar fix
+6. Re-ejecutar: /experts ...
+7. ✅ APPROVED
+8. Commit
+```

package/standards/general/code-quality.md

@@ -0,0 +1,86 @@
+# Estándares de Calidad de Código
+
+## TypeScript
+
+### Tipos
+- **NO usar `any`** - Usar tipos específicos o `unknown` con validación
+- **NO usar `as` casting** innecesario - Preferir type guards
+- **Inferir tipos** cuando sea posible - No duplicar tipos manualmente
+
+```typescript
+// MAL
+const data: any = await fetch(...)
+const user = response as User
+
+// BIEN
+const data: unknown = await fetch(...)
+if (isUser(data)) {
+  // data es User aquí
+}
+```
+
+### Imports
+- Usar **barrel exports** (`index.ts`)
+- Imports **absolutos** con aliases (`@/components/...`)
+- NO importar tipos con `import type` a menos que sea necesario para evitar ciclos
+
+### Async/Await
+- **NO await en loops** - Usar `Promise.all` o `Promise.allSettled`
+- Manejar errores con try/catch o `.catch()`
+
+```typescript
+// MAL
+for (const item of items) {
+  await processItem(item)  // N+1 pattern
+}
+
+// BIEN
+await Promise.all(items.map(item => processItem(item)))
+```
+
+## React
+
+### Componentes
+- **Server Components por defecto** - Solo usar Client cuando necesites interactividad
+- **NO inline functions en JSX** para event handlers
+- Usar **hooks personalizados** para lógica reutilizable
+
+```tsx
+// MAL
+<Button onClick={() => setOpen(true)} />
+
+// BIEN
+const handleOpen = useCallback(() => setOpen(true), [])
+<Button onClick={handleOpen} />
+```
+
+### Estado
+- **Mínimo estado local** - Preferir server state (React Query/tRPC)
+- **NO prop drilling** - Usar Context o composición
+
+## Base de Datos (Drizzle)
+
+### Queries
+- Siempre **filtrar por sistema** en tablas compartidas
+- Usar **transacciones** para operaciones múltiples
+- Evitar **N+1 queries** - Usar joins o Promise.all
+
+```typescript
+// MAL
+const items = await db.select().from(devItems)
+
+// BIEN
+const items = await db.select().from(devItems)
+  .where(eq(devItems.system, 'MYPROJECT'))
+```
+
+### Migraciones
+- **Nunca** modificar migraciones ya ejecutadas
+- Siempre revisar el SQL generado antes de push
+- Usar `tablesFilter` para no afectar tablas de otros proyectos
+
+## Tests
+
+- Tests para **lógica crítica** (pagos, auth, cálculos)
+- **NO tests para código trivial**
+- Preferir **integration tests** sobre unit tests para APIs

package/standards/general/memory-usage.md

@@ -0,0 +1,205 @@
+# Uso de Memory
+
+## Filosofía
+
+El sistema de memoria captura **conocimiento que persiste** entre sesiones:
+
+- Tareas que estamos haciendo
+- Aprendizajes del trabajo
+- Patrones detectados
+- Decisiones tomadas
+
+## Cuándo Registrar
+
+### Al Empezar Tarea
+
+```typescript
+// Registrar tarea nueva
+await taskTracker.startTask({
+  title: "Implementar feature X",
+  description: "Agregar funcionalidad para...",
+  userRequest: "mensaje original del usuario"
+})
+```
+
+### Durante el Trabajo
+
+```typescript
+// Capturar idea que surge
+await ideaCollector.capture({
+  title: "Optimización posible",
+  description: "Podríamos cachear este query...",
+  category: "performance",
+  priority: "medium"
+})
+```
+
+### Al Completar
+
+```typescript
+// Registrar resultado
+await taskTracker.completeTask(taskId, {
+  result: "Implementado con éxito",
+  lessonsLearned: ["Pattern X funcionó mejor que Y"]
+})
+```
+
+### Al Aprender Algo Nuevo
+
+```typescript
+// Crear memoria de conocimiento
+await memoryClient.create({
+  type: 'memory',
+  title: "Pattern: Lazy loading de mapas",
+  body: "Para evitar errores de SSR...",
+  domain: "architecture",
+  tags: ["performance", "ssr", "maps"]
+})
+```
+
+## Qué NO Registrar
+
+- Información trivial
+- Datos temporales de sesión
+- Detalles de implementación obvios
+- Código completo (solo referencias)
+
+## Tipos de Memoria
+
+### 1. Tasks
+
+Trabajo en progreso:
+
+```typescript
+{
+  type: 'task',
+  status: 'pending' | 'in_progress' | 'completed',
+  title: string,
+  description: string,
+  context: { /* datos relevantes */ }
+}
+```
+
+### 2. Ideas
+
+Insights capturados:
+
+```typescript
+{
+  type: 'idea',
+  title: string,
+  description: string,
+  category: 'feature' | 'optimization' | 'fix' | 'research',
+  priority: 'low' | 'medium' | 'high'
+}
+```
+
+### 3. Memories
+
+Conocimiento persistente:
+
+```typescript
+{
+  type: 'memory',
+  title: string,
+  body: string,        // Markdown
+  domain: string,      // 'architecture', 'performance', etc.
+  tags: string[],
+  importance: 'low' | 'normal' | 'critical'
+}
+```
+
+### 4. Patterns
+
+Patrones detectados:
+
+```typescript
+{
+  type: 'pattern',
+  name: string,
+  description: string,
+  occurrences: number,
+  autoImprove: boolean  // true si >= 3 ocurrencias
+}
+```
+
+## Auto-Improvement
+
+Cuando un patrón se detecta 3+ veces:
+
+1. Sistema genera regla ESLint
+2. Crea entrada en memoria (gotcha)
+3. Actualiza estándares locales
+
+```
+Pattern detectado 3x: "await en loop"
+  ↓
+ESLint rule: no-await-in-loop
+  ↓
+Memory: "Usar Promise.all en lugar de await secuencial"
+  ↓
+Próxima sesión: IDE muestra warning
+```
+
+## Búsqueda de Conocimiento
+
+Antes de empezar tarea, buscar conocimiento previo:
+
+```typescript
+// Buscar memorias relevantes
+const relevant = await memoryClient.search({
+  query: "lazy loading components",
+  domain: "architecture",
+  limit: 5
+})
+
+// Aplicar conocimiento encontrado
+for (const memory of relevant) {
+  console.log(`Conocimiento previo: ${memory.title}`)
+}
+```
+
+## Integración con Workflow
+
+```
+1. EMPEZAR TAREA
+   └→ taskTracker.startTask()
+
+2. BUSCAR CONTEXTO
+   └→ memoryClient.search()
+
+3. TRABAJAR
+   └→ ideaCollector.capture() (si surge idea)
+
+4. COMPLETAR
+   └→ taskTracker.completeTask()
+   └→ memoryClient.create() (si aprendí algo)
+
+5. DETECTAR PATRONES
+   └→ patternDetector.scan()
+   └→ autoImprover.improve() (si 3+ ocurrencias)
+```
+
+## Comandos
+
+```bash
+# Ver estado de memoria
+claude-memory status
+
+# Buscar en memoria
+claude-memory search "query"
+
+# Ver patrones detectados
+claude-memory patterns
+
+# Ejecutar auto-mejora
+claude-memory improve
+```
+
+## Best Practices
+
+1. **Ser selectivo** - Solo registrar lo valioso
+2. **Títulos descriptivos** - Facilita búsqueda futura
+3. **Tags consistentes** - Usar vocabulario común
+4. **Actualizar, no duplicar** - Si existe, actualizar
+5. **Dominio correcto** - Clasificar apropiadamente