don-cheli-sdd 1.13.0

package/habilidades/code-rag/HABILIDAD.md

@@ -0,0 +1,306 @@
+---
+nombre: CodeRAG
+descripcion: "Indexar repos de referencia y recuperar patrones relevantes usando RAG para informar implementación"
+version: 1.0.0
+autor: Don Cheli
+tags: [contexto, RAG, código, patrones, referencia]
+activacion: "buscar referencia", "código similar", "RAG", "cómo lo hicieron otros"
+---
+
+# Habilidad: CodeRAG (Retrieval-Augmented Generation para Código)
+
+**Versión:** 1.0.0
+**Categoría:** Contexto
+**Tipo:** Flexible
+
+> Adaptado de DeepCode (HKUDS/DeepCode) — CodeRAG System con dependency graphs y semantic analysis.
+
+## Cómo Mejora el Framework
+
+Don Cheli tiene memoria persistente (Engram) para decisiones y convenciones, pero carece de un sistema para **indexar y recuperar patrones de código relevantes** de repos de referencia. CodeRAG permite inyectar conocimiento de código existente durante la generación, sin cargar repos completos en contexto.
+
+## El Concepto
+
+```
+Sin CodeRAG:
+  Tarea: "Implementar webhook handler"
+  Agente: Genera desde cero (posibles anti-patrones)
+
+Con CodeRAG:
+  Tarea: "Implementar webhook handler"
+  CodeRAG: Busca patrones similares → encuentra 3 implementaciones
+  Agente: Genera informado por mejores prácticas reales
+```
+
+## Arquitectura
+
+```
+Repositorio(s) de Referencia
+        │
+        ▼
+┌─────────────────────┐
+│  1. Indexación       │  Escanear → extraer → clasificar
+│     - Dependencias   │
+│     - Patrones       │
+│     - APIs           │
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  2. Índice Local     │  .especdev/code-rag/
+│     - patterns.json  │  Patrones indexados
+│     - deps.json      │  Grafo de dependencias
+│     - apis.json      │  APIs y contratos
+└────────┬────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│  3. Recuperación     │  Query → match → inject
+│     - Por similitud  │
+│     - Por dependencia │
+│     - Por API        │
+└─────────────────────┘
+```
+
+## Pipeline de Indexación
+
+### Paso 1: Seleccionar Fuentes
+
+```yaml
+# .especdev/code-rag/fuentes.yaml
+fuentes:
+  - tipo: local
+    ruta: "../proyecto-hermano"
+    descripcion: "Proyecto con patrones similares"
+
+  - tipo: github
+    repo: "org/proyecto-referencia"
+    branch: "main"
+    solo_directorios:
+      - "src/services/"
+      - "src/utils/"
+    descripcion: "Microservicio de referencia del equipo"
+
+  - tipo: snapshot
+    ruta: ".especdev/code-rag/snapshots/auth-pattern.ts"
+    descripcion: "Patrón de auth aprobado por el equipo"
+```
+
+### Paso 2: Extraer Patrones
+
+Para cada fuente, se extraen:
+
+| Artefacto | Qué Captura | Ejemplo |
+|-----------|-------------|---------|
+| **Patrones** | Estructuras repetidas | Factory pattern, Repository pattern |
+| **Dependencias** | Grafo de imports | `auth.ts` → `jwt.ts` → `crypto.ts` |
+| **APIs** | Contratos públicos | `createUser(data: UserInput): Promise<User>` |
+| **Convenciones** | Naming, estructura | snake_case, carpeta por feature |
+| **Error handling** | Estrategias de manejo | Custom exceptions, error boundaries |
+
+### Paso 3: Clasificar y Almacenar
+
+```json
+// .especdev/code-rag/patterns.json
+{
+  "patterns": [
+    {
+      "id": "webhook-handler",
+      "tipo": "architectural",
+      "nombre": "Webhook Handler con Verificación",
+      "fuente": "org/proyecto-referencia:src/services/webhook.ts",
+      "tags": ["webhook", "security", "async"],
+      "complejidad": "media",
+      "snippet": "// Extracto relevante (< 50 líneas)",
+      "dependencias": ["crypto", "queue"],
+      "notas": "Incluye verificación de firma HMAC"
+    }
+  ]
+}
+```
+
+## Recuperación Contextual
+
+### Cuándo Recuperar
+
+CodeRAG se activa automáticamente durante:
+
+| Momento | Trigger |
+|---------|---------|
+| `/especdev:planificar-tecnico` | Buscar patrones arquitectónicos relevantes |
+| `/especdev:implementar` | Inyectar snippets de referencia |
+| `/especdev:desglosar` | Informar complejidad real basada en código similar |
+| Manual | `Consulta CodeRAG: <query>` |
+
+### Cómo Recuperar
+
+```
+1. Extraer keywords de la tarea actual
+2. Buscar en el índice por:
+   a. Tags coincidentes (exacto)
+   b. Similitud de nombre/descripción (fuzzy)
+   c. Dependencias compartidas (grafo)
+3. Rankear por relevancia
+4. Inyectar top-3 como contexto (máx 200 líneas total)
+```
+
+### Formato de Inyección
+
+```markdown
+## Referencia CodeRAG (3 patrones relevantes)
+
+### 1. Webhook Handler con Verificación (relevancia: 0.92)
+Fuente: org/proyecto-referencia:src/services/webhook.ts
+```typescript
+// Extracto: verificación de firma + procesamiento async
+export async function handleWebhook(req: Request): Promise<void> {
+  const signature = req.headers['x-webhook-signature'];
+  if (!verifySignature(req.body, signature, secret)) {
+    throw new UnauthorizedError('Invalid webhook signature');
+  }
+  await queue.enqueue('webhook', req.body);
+}
+```
+
+### 2. ... (más patrones)
+
+> Nota: Estos son patrones de REFERENCIA, no código para copiar directamente.
+> Adaptar al contexto y convenciones del proyecto actual.
+```
+
+## Grafo de Conocimiento (LightRAG)
+
+> Mejorado con conceptos de [LightRAG](https://github.com/HKUDS/LightRAG) — Retrieval dual-level con grafo de entidades y relaciones.
+
+### Enfoque Dual-Level
+
+```
+Query
+  ├─→ Traversal de grafo (relaciones entre entidades)
+  │   └─→ Nodo A → usa → Nodo B → extiende → Nodo C
+  │
+  └─→ Búsqueda semántica (similitud por tags/nombre)
+      └─→ Match fuzzy por descripción
+
+  ├─→ Combinar resultados con contexto relacional
+  └─→ Inyectar top-3 con grafo de dependencias incluido
+```
+
+### Entidades y Relaciones
+
+El grafo extrae automáticamente:
+
+| Entidad | Ejemplos |
+|---------|----------|
+| **Función** | `handleWebhook`, `createUser` |
+| **Clase** | `AuthService`, `UserRepository` |
+| **Módulo** | `src/services/auth`, `src/utils/jwt` |
+| **Patrón** | Factory, Repository, Observer |
+| **Interfaz** | `UserInput`, `WebhookPayload` |
+
+| Relación | Significado |
+|----------|-----------|
+| `calls` | Función A invoca función B |
+| `extends` | Clase A hereda de clase B |
+| `implements` | Clase A implementa interfaz B |
+| `imports` | Módulo A importa desde módulo B |
+| `composes` | Patrón A se compone con patrón B |
+| `depends_on` | Componente A depende de componente B |
+
+### Queries Multi-Nivel
+
+| Modo | Qué busca | Ejemplo |
+|------|----------|---------|
+| **Local** | Contexto específico de un módulo | "error handling en auth service" |
+| **Global** | Patrones cross-módulo | "todas las implementaciones de Factory" |
+| **Híbrido** | Combina local + global | "auth patterns + sus dependencias" |
+
+### Almacenamiento
+
+```
+.especdev/code-rag/
+├── patterns.json     # Patrones indexados
+├── entities.json     # Entidades extraídas (funciones, clases, módulos)
+├── relations.json    # Relaciones entre entidades (grafo)
+├── deps.json         # Grafo de dependencias de archivos
+├── apis.json         # APIs y contratos
+└── fuentes.yaml      # Configuración de fuentes
+```
+
+```json
+// .especdev/code-rag/entities.json
+{
+  "entities": [
+    {"id": "auth-service", "tipo": "service", "archivo": "src/services/auth.ts",
+     "tags": ["auth", "jwt", "security"]},
+    {"id": "jwt-util", "tipo": "utility", "archivo": "src/utils/jwt.ts",
+     "tags": ["jwt", "crypto", "token"]}
+  ]
+}
+
+// .especdev/code-rag/relations.json
+{
+  "relations": [
+    {"from": "auth-service", "to": "jwt-util", "tipo": "imports"},
+    {"from": "auth-service", "to": "user-model", "tipo": "depends_on"},
+    {"from": "auth-handler", "to": "auth-service", "tipo": "calls"}
+  ]
+}
+```
+
+### Ventaja sobre RAG tradicional
+
+```
+RAG tradicional:
+  Query: "async error handling"
+  → Busca por similitud → Devuelve snippets sueltos
+
+CodeRAG + LightRAG:
+  Query: "async error handling"
+  → Extrae entidades: [error_handler, async_fn, middleware]
+  → Traversa grafo: async_fn --calls--> error_handler --wraps--> middleware
+  → Devuelve: snippet + contexto relacional + patrones asociados
+  → Bonus: "Este patrón se compone con logging middleware"
+```
+
+## Gestión del Índice
+
+| Acción | Cuándo |
+|--------|--------|
+| **Crear** | `/especdev:iniciar` si se configuran fuentes |
+| **Actualizar** | Manualmente o al detectar cambios en fuentes |
+| **Limpiar** | `/especdev:archivar` al completar proyecto |
+| **Exportar** | Para compartir índice entre proyectos similares |
+
+## Límites de Tokens
+
+| Elemento | Límite |
+|----------|--------|
+| Snippet por patrón | 50 líneas máximo |
+| Patrones inyectados por query | 3 máximo |
+| Contexto total inyectado | 200 líneas máximo |
+| Tamaño del índice | 500 patrones máximo |
+
+## Integración con Habilidades Existentes
+
+```
+CodeRAG ←→ Mapa Arquitectónico
+  El mapa usa el grafo de dependencias de CodeRAG
+
+CodeRAG ←→ Ingeniería de Contexto
+  CodeRAG respeta los límites de contexto
+
+CodeRAG ←→ Memoria Persistente (Engram)
+  Decisiones sobre patrones se guardan en Engram
+
+CodeRAG ←→ Generador de Specs
+  Specs se informan con patrones existentes
+```
+
+## Guardrails
+
+- **Nunca** copiar código de referencia directamente — siempre adaptar
+- **Nunca** indexar archivos con credenciales o secretos
+- **Nunca** exceder los límites de inyección (200 líneas)
+- **Siempre** indicar la fuente del patrón inyectado
+- **Siempre** verificar que el patrón sigue siendo válido (fuente puede cambiar)

package/habilidades/contabilidad-tokens/HABILIDAD.md

@@ -0,0 +1,109 @@
+---
+nombre: Contabilidad de Tokens
+descripcion: "Trackear consumo de tokens por tarea, sesión y modelo. Genera reportes de costo y uso"
+version: 1.0.0
+autor: Don Cheli
+tags: [tokens, observabilidad, costos, métricas]
+activacion: "cuántos tokens", "costo de la sesión", "consumo", "budget"
+---
+
+# Habilidad: Contabilidad de Tokens
+
+**Versión:** 1.0.0
+**Categoría:** Observabilidad
+**Tipo:** Flexible
+
+> Adaptado de OpenAI Symphony §13.5 — Session Metrics and Token Accounting.
+
+## Cómo Mejora el Framework
+
+Sin contabilidad de tokens, se pierde visibilidad sobre:
+- Cuánto cuesta cada feature
+- Qué tareas consumen más recursos
+- Dónde optimizar el uso de tokens
+- Si se está rompiendo el presupuesto
+
+## Métricas por Sesión
+
+```json
+{
+  "sesion_id": "sess_20260321_163000",
+  "tarea": "PROJ-42",
+  "inicio": "2026-03-21T16:30:00",
+  "fin": "2026-03-21T16:37:23",
+  "duracion_segundos": 443,
+  "tokens": {
+    "input": 45230,
+    "output": 12890,
+    "total": 58120,
+    "cache_hit": 8200
+  },
+  "turnos": 15,
+  "reintentos": 0,
+  "modelo": "sonnet",
+  "costo_estimado_usd": 0.14,
+  "archivos_modificados": 8,
+  "lineas_agregadas": 234,
+  "lineas_eliminadas": 45,
+  "tests_ejecutados": 47,
+  "tests_pasaron": 47
+}
+```
+
+## Métricas Acumulativas
+
+```markdown
+# Dashboard de Tokens — Marzo 2026
+
+## Totales del Mes
+| Métrica | Valor |
+|---------|-------|
+| Sesiones | 34 |
+| Tokens totales | 1,245,890 |
+| Costo estimado | $3.42 |
+| Tiempo total | 4h 12m |
+| Features completadas | 8 |
+| Bugs corregidos | 12 |
+
+## Costo por Feature (Top 5)
+| Feature | Tokens | Costo | Duración |
+|---------|--------|-------|----------|
+| OAuth login | 158,000 | $0.42 | 32m |
+| Dashboard UI | 234,000 | $0.65 | 48m |
+| Email service | 89,000 | $0.24 | 18m |
+| DB migrations | 45,000 | $0.12 | 9m |
+| API pagination | 67,000 | $0.18 | 14m |
+
+## Eficiencia
+- Costo promedio por feature: $0.43
+- Costo promedio por bug: $0.08
+- Ratio tokens/línea de código: 42
+- Tasa de reintentos: 8%
+```
+
+## Alertas de Presupuesto
+
+```yaml
+# .especdev/config.yaml
+tokens:
+  presupuesto_diario: 500000
+  presupuesto_mensual: 5000000
+  alertar_al: 80  # % del presupuesto
+  modelo_preferido_bajo_presupuesto: "haiku"
+  pausar_al_exceder: false  # true = pausar, false = advertir
+```
+
+## Integración con Prueba de Trabajo
+
+Cada `prueba-trabajo.md` incluye automáticamente la sección de tokens,
+vinculando costo con resultado para análisis ROI.
+
+## Archivo de Métricas
+
+```
+.especdev/metricas/
+├── 2026-03/
+│   ├── sesiones.jsonl      # Una línea JSON por sesión
+│   ├── resumen-diario.md   # Generado automáticamente
+│   └── resumen-mensual.md  # Generado al final del mes
+```

package/habilidades/delta-specs/HABILIDAD.md

@@ -0,0 +1,102 @@
+---
+nombre: Delta Specs — Specs Incrementales
+descripcion: "Detectar cambios entre versiones de specs y generar diff semántico con impacto en código"
+version: 1.0.0
+autor: Don Cheli
+tags: [delta, specs, diff, incremental]
+activacion: "delta spec", "qué cambió en la spec", "diff de specs", "cambios en requisitos"
+---
+
+# Habilidad: Delta Specs — Specs Incrementales
+
+**Versión:** 1.0.0
+**Categoría:** Especificación
+**Tipo:** Rígida
+
+> Adaptado de OpenSpec (Fission-AI/OpenSpec) — concepto clave para desarrollo brownfield.
+
+## Cómo Mejora el Framework
+
+Sin delta specs, cada cambio requiere reescribir la spec completa. Esto es:
+- Costoso en tokens
+- Propenso a errores (se puede borrar algo sin querer)
+- Inviable en proyectos grandes con muchas specs
+
+Con delta specs, describes **QUÉ CAMBIA** — no reestas todo.
+
+## Qué es un Delta Spec
+
+Un delta spec describe la **diferencia** entre el estado actual y el estado deseado de una spec:
+
+```markdown
+# Delta Spec: Agregar OAuth a Autenticación
+
+## Spec Base
+specs/auth/spec.md
+
+## Cambios
+
+### Nuevo Requisito: Login Social
+El sistema DEBE permitir autenticación via Google y GitHub OAuth2.
+
+#### Escenario: Login con Google exitoso
+- DADO un usuario con cuenta de Google
+- CUANDO selecciona "Entrar con Google"
+- ENTONCES recibe un JWT token válido
+- Y su perfil se completa con datos de Google
+
+#### Escenario: Vincular OAuth a cuenta existente
+- DADO un usuario registrado con email
+- CUANDO intenta login con Google usando el mismo email
+- ENTONCES se vincula la cuenta OAuth a la existente
+- Y puede usar ambos métodos de login
+
+### Requisito Modificado: Session Expiration
+- ANTES: "Las sesiones expiran después de 30 minutos"
+- AHORA: "Las sesiones expiran después de 30 minutos para login local, 
+          y según configuración del provider para OAuth"
+
+### Requisito Sin Cambios
+- User Authentication (sin cambios)
+- Password Reset (sin cambios)
+```
+
+## Por Qué Deltas en Vez de Specs Completas
+
+| Aspecto | Spec Completa | Delta Spec |
+|---------|--------------|------------|
+| **Tokens** | Reescribir TODO (~2000 tokens) | Solo lo nuevo (~500 tokens) |
+| **Riesgo** | Borrar algo sin querer | Solo se toca lo que cambia |
+| **Revisión** | Comparar todo el doc | Ver solo los cambios |
+| **Merge** | Reemplazar | Aplicar incrementalmente |
+| **Brownfield** | Difícil con specs grandes | Natural y escalable |
+
+## El Ciclo Virtuoso
+
+```
+1. Specs describen comportamiento actual
+2. Delta specs proponen modificaciones
+3. Implementación hace los cambios reales
+4. /especdev:archivar merge deltas en specs principales
+5. Specs ahora describen el nuevo comportamiento
+6. Siguiente cambio se basa en specs actualizadas
+```
+
+## Secciones de un Delta Spec
+
+| Sección | Contenido |
+|---------|-----------|
+| `## Spec Base` | Referencia a la spec que se modifica |
+| `### Nuevo Requisito:` | Requisitos completamente nuevos |
+| `### Requisito Modificado:` | Requisitos existentes que cambian (ANTES/AHORA) |
+| `### Requisito Eliminado:` | Requisitos que se retiran |
+| `### Sin Cambios` | Requisitos que permanecen igual (para contexto) |
+
+## Integración con el Pipeline
+
+```
+/especdev:proponer → propuesta.md
+→ /especdev:especificar → delta-spec.md (NO spec completa)
+→ /especdev:implementar → código
+→ /especdev:archivar → merge delta en spec principal
+```

package/habilidades/desarrollo-subagentes/HABILIDAD.md

@@ -0,0 +1,51 @@
+---
+nombre: Desarrollo por Subagentes
+descripcion: "Dividir tareas complejas en subtareas y asignarlas a subagentes paralelos con el modelo adecuado"
+version: 1.0.0
+autor: Don Cheli
+tags: [orquestación, subagentes, paralelismo, agentes, SDD]
+activacion: "subagentes", "dividir tarea", "paralelizar", "agentes en paralelo"
+---
+
+# Habilidad: Desarrollo por Subagentes (SDD)
+
+**Versión:** 1.0.0
+**Categoría:** Orquestación
+**Tipo:** Rígida
+
+## Propósito
+
+Transformar ejecución monolítica en flujos de trabajo multi-agente orquestados.
+
+## El Problema
+
+La ejecución con un solo agente tiene limitaciones:
+- **Contaminación de contexto:** Sesiones largas acumulan contexto irrelevante
+- **Confusión de roles:** Mismo agente planifica, implementa y revisa
+- **Sin perspectiva fresca:** Auto-revisión es menos efectiva
+
+## La Solución SDD
+
+```
+Controlador (Opus)
+    │
+    ├── Planifica tareas
+    ├── Cura contexto por tarea
+    ├── Despacha a subagentes
+    ├── Revisa resultados
+    └── Integra trabajo
+
+Ejecutor (Sonnet)           Revisor (Opus)
+    │                           │
+    ├── Contexto fresco        ├── Contexto fresco
+    ├── Foco en una tarea      ├── Revisión independiente
+    └── Retorna estado         └── Evaluación de calidad
+```
+
+## Principios
+
+1. **El controlador NUNCA implementa**
+2. **Cada subagente recibe contexto fresco**
+3. **El contexto se cura, no se vuelca**
+4. **Revisión de dos etapas es obligatoria**
+5. **Máximo 3 rondas de revisión**