cmp-standards 2.0.0 → 2.4.0

package/standards/hooks/mandatory-tracking.md

@@ -0,0 +1,446 @@
+# Sistema de Tracking Obligatorio
+
+## Filosofía
+
+Todo agente de Claude Code **DEBE**:
+1. Registrar qué está haciendo (inicio de tarea)
+2. Mantener visible el plan actual y paso actual
+3. Al terminar, registrar mejoras para el futuro
+4. Todo con timestamp para continuidad
+
+## Flujo Obligatorio
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ SESSION START                                               │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Cargar tareas activas del usuario                        │
+│ 2. Mostrar resumen: "Tienes 2 tareas en progreso..."       │
+│ 3. Cargar mejoras pendientes del área de trabajo           │
+│ 4. Inyectar contexto relevante                              │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│ TASK START (Obligatorio antes de trabajar)                  │
+├─────────────────────────────────────────────────────────────┤
+│ Registrar en DB:                                            │
+│ {                                                           │
+│   id: ulid(),                                               │
+│   type: 'task',                                             │
+│   status: 'in_progress',                                    │
+│   content: {                                                │
+│     title: "Implementar feature X",                         │
+│     plan: ["Paso 1", "Paso 2", "Paso 3"],                  │
+│     currentStep: 0,                                         │
+│     domain: "video-studio",                                 │
+│     userRequest: "mensaje original",                        │
+│     startedAt: "2025-12-24T10:30:00Z",                     │
+│     sessionId: "sess_xyz",                                  │
+│     agentId: "agent_abc"                                    │
+│   }                                                         │
+│ }                                                           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│ DURING WORK (Auto-tracking)                                 │
+├─────────────────────────────────────────────────────────────┤
+│ En cada Edit/Write significativo:                           │
+│ - Actualizar currentStep                                    │
+│ - Registrar archivos modificados                            │
+│ - Actualizar lastActivityAt                                 │
+│                                                             │
+│ Si el agente detecta mejora potencial:                      │
+│ - Capturar inmediatamente en `improvements` array           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│ TASK COMPLETE (Obligatorio)                                 │
+├─────────────────────────────────────────────────────────────┤
+│ ANTES de marcar como completo, DEBE:                        │
+│                                                             │
+│ 1. Registrar resultado:                                     │
+│    result: "Implementado con éxito" | "Parcial" | "Bloqueado"│
+│                                                             │
+│ 2. Registrar mejoras detectadas (OBLIGATORIO):              │
+│    improvements: [                                          │
+│      {                                                      │
+│        area: "video-studio",                                │
+│        title: "Cachear respuestas de Veo API",             │
+│        description: "Durante el trabajo noté que...",       │
+│        priority: "medium",                                  │
+│        detectedAt: "2025-12-24T11:45:00Z"                  │
+│      }                                                      │
+│    ]                                                        │
+│                                                             │
+│ 3. Registrar lecciones aprendidas:                          │
+│    lessons: ["Pattern X funcionó mejor que Y"]              │
+│                                                             │
+│ 4. Actualizar timestamps:                                   │
+│    completedAt: "2025-12-24T12:00:00Z"                     │
+│    duration: "1h 30m"                                       │
+└─────────────────────────────────────────────────────────────┘
+
+## Estructura de Datos
+
+### Task (Tarea en Progreso)
+
+```typescript
+interface TrackedTask {
+  id: string
+  type: 'task'
+  status: 'pending' | 'in_progress' | 'completed' | 'blocked'
+  system: string  // 'SWARMSCALE', 'CHARTER', etc.
+
+  content: {
+    // Identificación
+    title: string
+    description: string
+    userRequest: string  // Mensaje original del usuario
+
+    // Plan
+    plan: string[]       // Pasos del plan
+    currentStep: number  // Índice del paso actual
+
+    // Contexto
+    domain: string       // Área del proyecto
+    files: string[]      // Archivos tocados
+
+    // Tracking
+    sessionId: string
+    agentId: string
+
+    // Timestamps
+    startedAt: string
+    lastActivityAt: string
+    completedAt?: string
+
+    // Resultado (al completar)
+    result?: 'success' | 'partial' | 'blocked'
+    resultNotes?: string
+
+    // Mejoras detectadas (OBLIGATORIO al completar)
+    improvements: Improvement[]
+
+    // Lecciones
+    lessons: string[]
+  }
+}
+```
+
+### Improvement (Mejora Detectada)
+
+```typescript
+interface Improvement {
+  id: string
+  type: 'improvement'
+  status: 'pending' | 'implemented' | 'rejected'
+
+  content: {
+    // Qué mejorar
+    area: string         // Dominio/área del proyecto
+    title: string
+    description: string
+
+    // Contexto
+    detectedInTask: string  // ID de la tarea donde se detectó
+    detectedBy: string      // agentId
+    detectedAt: string
+
+    // Prioridad
+    priority: 'low' | 'medium' | 'high' | 'critical'
+    effort: 'trivial' | 'small' | 'medium' | 'large'
+
+    // Implementación
+    implementedAt?: string
+    implementedInTask?: string
+  }
+}
+```
+
+## Hooks Implementation
+
+### SessionStart Hook
+
+```typescript
+// .claude/hooks/session-start-tracking.ts
+
+export async function onSessionStart(event: SessionStartEvent) {
+  const db = await getDatabase()
+  const system = detectSystem(event.cwd)
+
+  // 1. Cargar tareas activas
+  const activeTasks = await db.query({
+    type: 'task',
+    status: 'in_progress',
+    system
+  })
+
+  // 2. Cargar mejoras pendientes del área
+  const pendingImprovements = await db.query({
+    type: 'improvement',
+    status: 'pending',
+    system
+  })
+
+  // 3. Generar contexto
+  let context = ''
+
+  if (activeTasks.length > 0) {
+    context += `\n## Tareas en Progreso\n`
+    for (const task of activeTasks) {
+      const t = task.content as TaskContent
+      context += `- **${t.title}** (paso ${t.currentStep + 1}/${t.plan.length})\n`
+      context += `  Iniciada: ${formatDate(t.startedAt)}\n`
+      context += `  Último paso: ${t.plan[t.currentStep]}\n`
+    }
+    context += `\nPuedes continuar con "/continue" o empezar algo nuevo.\n`
+  }
+
+  if (pendingImprovements.length > 0) {
+    context += `\n## Mejoras Pendientes (${pendingImprovements.length})\n`
+    const byArea = groupBy(pendingImprovements, i => i.content.area)
+    for (const [area, improvements] of Object.entries(byArea)) {
+      context += `- **${area}**: ${improvements.length} mejoras\n`
+    }
+  }
+
+  return {
+    contextInjection: context,
+    metadata: { activeTasks: activeTasks.length }
+  }
+}
+```
+
+### PreToolUse Hook (Task Tool)
+
+```typescript
+// .claude/hooks/pre-tool-use-task-tracking.ts
+
+export async function onPreToolUse(event: PreToolUseEvent) {
+  // Solo para Task tool (cuando se lanzan agentes)
+  if (event.tool !== 'Task') return { proceed: true }
+
+  const db = await getDatabase()
+
+  // Verificar si hay tarea activa
+  const activeTask = await db.findFirst({
+    type: 'task',
+    status: 'in_progress',
+    'content.sessionId': event.sessionId
+  })
+
+  if (!activeTask) {
+    // OBLIGAR a crear tarea primero
+    return {
+      proceed: false,
+      message: `⚠️ No hay tarea registrada para esta sesión.
+
+Antes de continuar, registra la tarea:
+
+\`\`\`
+Tarea: [descripción breve]
+Plan:
+1. [paso 1]
+2. [paso 2]
+...
+\`\`\`
+
+Esto permite continuidad si se cierra la sesión.`
+    }
+  }
+
+  // Actualizar actividad
+  await db.update(activeTask.id, {
+    'content.lastActivityAt': new Date().toISOString()
+  })
+
+  return { proceed: true }
+}
+```
+
+### PostToolUse Hook (Captura de Mejoras)
+
+```typescript
+// .claude/hooks/post-tool-use-improvements.ts
+
+export async function onPostToolUse(event: PostToolUseEvent) {
+  // Solo después de Write/Edit significativos
+  if (!['Write', 'Edit'].includes(event.tool)) return
+
+  const db = await getDatabase()
+  const activeTask = await getActiveTask(event.sessionId)
+
+  if (!activeTask) return
+
+  // Actualizar archivos modificados
+  const files = activeTask.content.files || []
+  if (!files.includes(event.params.file_path)) {
+    files.push(event.params.file_path)
+    await db.update(activeTask.id, {
+      'content.files': files,
+      'content.lastActivityAt': new Date().toISOString()
+    })
+  }
+}
+```
+
+### Task Completion Guard
+
+```typescript
+// .claude/hooks/task-completion-guard.md
+
+## Task Completion Requirements
+
+Antes de marcar una tarea como completada, DEBES:
+
+### 1. Registrar Resultado
+- `success`: Todo implementado correctamente
+- `partial`: Implementación parcial, quedan pendientes
+- `blocked`: No se pudo completar por bloqueadores
+
+### 2. Registrar Mejoras (OBLIGATORIO)
+Responde estas preguntas:
+- ¿Qué podría hacerse mejor en esta área?
+- ¿Encontraste código que necesita refactoring?
+- ¿Detectaste patrones repetitivos?
+- ¿Hay oportunidades de optimización?
+
+**Mínimo 1 mejora** debe registrarse por tarea.
+Si genuinamente no hay mejoras, documenta por qué.
+
+### 3. Registrar Lecciones
+- ¿Qué aprendiste durante esta tarea?
+- ¿Qué harías diferente la próxima vez?
+
+### Formato de Registro
+
+```json
+{
+  "result": "success",
+  "resultNotes": "Feature implementada correctamente",
+  "improvements": [
+    {
+      "area": "video-studio",
+      "title": "Cachear respuestas de Veo API",
+      "description": "Las llamadas a Veo son lentas (~3s). Podríamos cachear por prompt hash.",
+      "priority": "medium",
+      "effort": "small"
+    }
+  ],
+  "lessons": [
+    "El pattern de retry con backoff funciona mejor que retry simple"
+  ]
+}
+```
+```
+
+## Skill: /continue
+
+```markdown
+---
+name: continue
+description: Continuar con una tarea en progreso
+arguments:
+  - name: taskId
+    description: ID de la tarea (opcional, usa la más reciente)
+    required: false
+---
+
+# Continuar Tarea
+
+## 1. Cargar Tarea
+
+{{#if taskId}}
+Cargar tarea específica: {{taskId}}
+{{else}}
+Cargar la tarea más reciente en progreso.
+{{/if}}
+
+## 2. Mostrar Contexto
+
+Mostrar al usuario:
+- Título de la tarea
+- Plan completo
+- Paso actual (destacado)
+- Archivos ya modificados
+- Tiempo transcurrido
+- Mejoras detectadas hasta ahora
+
+## 3. Retomar
+
+Continuar desde el paso actual del plan.
+Mantener el mismo taskId y sessionId.
+
+## Ejemplo de Output
+
+```
+📋 Continuando: "Implementar cache para Veo API"
+
+Plan:
+✅ 1. Crear servicio de cache
+✅ 2. Integrar con VeoService
+→ 3. Agregar invalidación por TTL   ← AQUÍ
+  4. Escribir tests
+  5. Documentar
+
+Archivos modificados:
+- src/services/cache/VeoCache.ts
+- src/services/ai/VeoService.ts
+
+Tiempo: 45 min (iniciada hace 2h)
+
+Mejoras detectadas: 1 pendiente
+
+Continuando con paso 3...
+```
+```
+
+## Queries Útiles
+
+### Ver tareas activas
+```sql
+SELECT * FROM DEV_Items
+WHERE type = 'task'
+  AND status = 'in_progress'
+  AND system = 'SWARMSCALE'
+ORDER BY JSON_EXTRACT(content, '$.lastActivityAt') DESC
+```
+
+### Ver mejoras por área
+```sql
+SELECT
+  JSON_EXTRACT(content, '$.area') as area,
+  COUNT(*) as count
+FROM DEV_Items
+WHERE type = 'improvement'
+  AND status = 'pending'
+  AND system = 'SWARMSCALE'
+GROUP BY area
+ORDER BY count DESC
+```
+
+### Ver historial de trabajo
+```sql
+SELECT
+  JSON_EXTRACT(content, '$.title') as title,
+  JSON_EXTRACT(content, '$.startedAt') as started,
+  JSON_EXTRACT(content, '$.completedAt') as completed,
+  JSON_EXTRACT(content, '$.result') as result,
+  JSON_LENGTH(JSON_EXTRACT(content, '$.improvements')) as improvements
+FROM DEV_Items
+WHERE type = 'task'
+  AND system = 'SWARMSCALE'
+ORDER BY JSON_EXTRACT(content, '$.startedAt') DESC
+LIMIT 20
+```
+
+## Beneficios
+
+1. **Continuidad**: Cerrar IDE no pierde contexto
+2. **Mejora Continua**: Cada tarea genera insights
+3. **Visibilidad**: Saber qué se está trabajando
+4. **Historial**: Ver evolución del proyecto
+5. **Priorización**: Mejoras acumuladas por área