don-cheli-sdd 1.13.0

package/habilidades/optimizacion-tokens/HABILIDAD.md

@@ -0,0 +1,179 @@
+---
+nombre: Optimización de Tokens
+descripcion: "Reducir consumo de tokens sin perder calidad: lazy loading, compresión, selección de modelo"
+version: 1.0.0
+autor: Don Cheli
+tags: [eficiencia, tokens, optimización, costos, modelos]
+activacion: "optimizar tokens", "reducir consumo", "gastar menos tokens"
+---
+
+# Habilidad: Optimización de Tokens
+
+**Versión:** 1.0.0
+**Categoría:** Eficiencia
+**Tipo:** Rígida
+
+> **Auto-anuncio:** "Usando habilidad de Optimización de Tokens para minimizar costos y maximizar calidad."
+
+## Cómo Mejora el Framework
+
+Esta habilidad convierte a Don Cheli en un framework **costo-eficiente**. Sin ella, los LLMs consumen tokens innecesariamente: re-leen archivos, usan modelos caros para tareas simples, y generan prompts verbosos. Con esta habilidad:
+
+- ⬇️ **~60% reducción de costos** por selección correcta de modelo
+- ⬇️ **~40% menos tokens** por carga bajo demanda y referenciación
+- ⬆️ **Mejor calidad** al usar el modelo correcto para cada tarea
+- ⬆️ **Sesiones más largas** sin context rot por gestión proactiva
+
+---
+
+## Principio Central
+
+> **Cada token cuesta dinero y tiempo. Seleccionar modelo y estrategia según la complejidad de la tarea, nunca por hábito.**
+
+---
+
+## Matriz de Selección de Modelos
+
+| Tipo de Tarea | Modelo | Razón |
+|--------------|--------|-------|
+| Q&A simple, resúmenes, formateo | `haiku` | Rápido, barato, suficiente |
+| Generación de código, bug fixes, tests | `sonnet` | Balance calidad/costo |
+| Arquitectura, razonamiento complejo, seguridad | `opus` | Solo cuando se necesita profundidad |
+| Procesamiento batch, transformaciones repetitivas | `haiku` | Tareas de volumen no necesitan opus |
+| Code review, refactor multi-archivo | `sonnet` | Complejidad media |
+| Análisis de seguridad, diseño de sistemas | `opus` | Razonamiento de alto riesgo |
+
+**Regla:** Default a Haiku. Subir solo cuando la calidad sea insuficiente.
+
+---
+
+## Gestión de Ventana de Contexto
+
+### 1. Cargar contexto bajo demanda (lazy)
+
+```
+❌ MALO: Cargar los 12 archivos del módulo antes de responder
+✅ BUENO: Cargar solo el archivo en cuestión.
+          Buscar adyacentes solo si hay dependencia no resuelta.
+```
+
+### 2. Podar system prompts agresivamente
+
+- System prompts < **500 tokens** (se cobran en cada llamada)
+- Mover reglas poco usadas a **skills bajo demanda**
+- Eliminar reglas obsoletas inmediatamente
+
+### 3. Archivos de memoria > re-lectura
+
+Un registro de 50 tokens en memoria ahorra re-leer un archivo de 2,000 tokens repetidamente.
+
+---
+
+## Ingeniería de Prompts para Eficiencia
+
+### Ser explícito, no verboso
+
+```
+❌ MALO (30 tokens, vago):
+"¿Puedes por favor revisar este código y decirme si hay
+algún problema potencial del que debería estar al tanto?"
+
+✅ BUENO (12 tokens, preciso):
+"Busca bugs en esta función. Lista cada uno con: ubicación, problema, fix."
+```
+
+### Outputs estructurados desde el inicio
+
+```
+# En vez de prosa libre, pedir:
+Retorna JSON: { "archivo": string, "linea": number, "problema": string, "fix": string }[]
+```
+
+### Referenciar, no repetir
+
+```
+❌ MALO: Pegar el mismo schema en cada prompt
+✅ BUENO: "Usa el schema definido en api/types.ts línea 45"
+```
+
+---
+
+## Estrategia de Subagentes
+
+### Cuándo usar subagentes
+
+| Situación | Acción |
+|-----------|--------|
+| 3 análisis independientes | 3 llamadas Haiku en paralelo |
+| Archivo >10K tokens | Subagente para aislar contexto |
+| Tarea simple, 1 archivo | NO usar subagente (overhead > ahorro) |
+
+### Asignación de modelo por subagente
+
+```
+Exploración/búsqueda → haiku   (buscar es barato)
+Implementación        → sonnet  (escribir código requiere calidad)
+Arquitectura          → opus    (solo para decisiones de diseño)
+```
+
+---
+
+## Estrategias de Caché
+
+### Caché a nivel de prompt
+
+Colocar contenido estable (system prompt, docs grandes, schemas) al **inicio del contexto**. Claude cachea automáticamente hasta 4 prompts — prefijos repetidos cuestan ~10% del precio normal.
+
+### Caché a nivel de aplicación
+
+- Cachear respuestas para inputs determinísticos
+- TTL: según estabilidad de los datos subyacentes
+
+---
+
+## Playbooks por Tipo de Tarea
+
+| Tarea | Paso 1 | Paso 2 | Paso 3 |
+|-------|--------|--------|--------|
+| **Code Review** | Haiku: escanear estilo/lint | Sonnet: lógica, edge cases, coverage | Opus: solo crypto/auth/distribuido |
+| **Documentación** | Haiku: generar borrador desde código | Sonnet: editar para precisión | Opus: nunca |
+| **Debugging** | Sonnet: leer error, causa raíz, proponer fix | Opus: solo concurrencia/estado distribuido | — |
+| **Tests** | Haiku: boilerplate desde signatures | Sonnet: edge cases + mocks complejos | — |
+| **Scripting** | Haiku siempre | — | — |
+
+---
+
+## Anti-Patrones (Nunca Hacer)
+
+| Anti-Patrón | Problema | Costo |
+|------------|----------|-------|
+| Opus para todo | Formateo y Q&A no necesitan razonamiento profundo | 15x más caro |
+| Cargar todo el codebase | Context rot + tokens desperdiciados | Tokens innecesarios |
+| System prompts verbosos | Se multiplica en cada llamada | Costo compuesto |
+| Re-leer archivos en contexto | Información ya disponible | Tokens duplicados |
+| Secuencial cuando puede ser paralelo | Subagentes independientes deben ser paralelos | Tiempo desperdiciado |
+| Prompts ambiguos | Generan loops de clarificación | 200+ tokens extra |
+
+---
+
+## Guardarraíles de Presupuesto
+
+| Umbral | Acción |
+|--------|--------|
+| Tarea individual > 50K tokens | Dividir en subtareas |
+| Sesión > 200K tokens | Resumir y comprimir contexto |
+| Subagente > 20K tokens | Reducir alcance o usar archivos de memoria |
+| System prompt > 1K tokens | Auditar y podar |
+
+---
+
+## Referencia Rápida
+
+```
+¿Tarea simple?          → Haiku
+¿Tarea media?           → Sonnet
+¿Compleja/alto riesgo?  → Opus (confirmar con usuario primero)
+¿Repetitiva/batch?      → Haiku en subagentes paralelos
+¿Contexto grande?       → Subagente para aislar, luego surfear resultados
+¿Ya lo leíste?          → Referenciarlo, no re-leer
+```

package/habilidades/optimizador-contexto/HABILIDAD.md

@@ -0,0 +1,106 @@
+---
+nombre: Optimizador de Contexto
+descripcion: "Comprimir y priorizar el contexto del conversation window para máxima eficiencia de tokens"
+version: 1.0.0
+autor: Don Cheli
+tags: [contexto, tokens, rendimiento, optimizacion]
+activacion: "optimizar contexto", "comprimir conversación", "context window lleno"
+---
+
+# Habilidad: Optimizador de Contexto
+
+**Versión:** 1.0.0
+**Categoría:** Rendimiento
+**Tipo:** Rígida
+
+> Adaptado de `context-optimizer` de Pro-Workflow.
+
+## Cómo Mejora el Framework
+
+El contexto del agente es un recurso finito. Sin gestión activa:
+- A 70% → la calidad empieza a degradarse
+- A 90% → entra en la "zona muda" — respuestas genéricas
+- A 100% → errores y hallucinations
+
+## Diagnóstico Rápido
+
+| Uso de Contexto | Estado | Acción |
+|-----------------|--------|--------|
+| < 50% | 🟢 Óptimo | Seguir normal |
+| 50-70% | 🟡 Aceptable | Planificar compactación |
+| 70-90% | 🟠 Degradado | **Compactar AHORA** |
+| > 90% | 🔴 Zona muda | **Sesión nueva inmediatamente** |
+
+## Estrategias de Optimización
+
+### Inmediatas
+
+| Acción | Ahorro | Cuándo |
+|--------|--------|--------|
+| Compactar contexto | 30-50% | Al cambiar de tarea |
+| Desactivar MCPs no usados | ~5% por MCP | Al cambiar de dominio |
+| Delegar a subagentes | Mantiene contexto limpio | Tareas pesadas de lectura |
+| Sesión nueva con traspaso | 100% reset | Trabajo no relacionado |
+
+### Prompts Eficientes en Tokens
+
+- ❌ "Arreglá el código" (obliga al agente a leer todo)
+- ✅ "En src/auth/, corregir el bug de login" (scope acotado)
+- ✅ "No modificar el middleware" (restricción explícita)
+- ✅ "Debe retornar 429 después de 5 intentos" (criterio de aceptación)
+
+### Delegación a Subagentes
+
+Operaciones que generan mucho output van a subagentes:
+- Ejecución de suite de tests completa → subagente
+- Exploración de archivos grandes → subagente
+- Generación de documentación → subagente
+- Análisis de logs → subagente
+
+El contexto principal se mantiene limpio.
+
+### Presupuesto de Contexto por Fase
+
+| Fase | Uso Target | Si Se Excede |
+|------|-----------|--------------|
+| Planificación | < 20% | Mantener planes concisos |
+| Implementación | < 60% | Compactar entre archivos |
+| Testing | < 80% | Delegar a subagente |
+| Revisión | < 90% | Sesión nueva |
+
+## Optimización del System Prompt
+
+- System prompt principal: **< 60 líneas** ideal, **< 150** máx
+- Mover info por paquete a system prompts por módulo
+- Mover preferencias personales a archivo local
+- Eliminar info obvia o que cambia rápidamente
+
+## Auditoría de MCPs
+
+> Mantener < 10 MCPs activos, < 80 herramientas totales.
+> Cada MCP agrega overhead a cada request.
+
+## Señales de Contexto Degradado
+
+- El agente se repite o olvida contexto previo
+- Respuestas genéricas sin conocimiento del proyecto
+- Tool calls que fallan por razones que antes funcionaban
+- "¿Me puedes repetir qué estamos haciendo?"
+
+### Solución
+
+1. Compactar manualmente
+2. Si persiste → sesión nueva con `/especdev:traspasar`
+3. Si es recurrente → reducir system prompt, desactivar MCPs
+
+## Integración con Don Cheli
+
+```yaml
+# .especdev/config.yaml
+contexto:
+  umbral_compactar: 70       # % para auto-compactar
+  umbral_zona_muda: 90       # % para forzar sesión nueva
+  max_mcps_activos: 10
+  max_herramientas: 80
+  subagentes_para_output_pesado: true
+```

package/habilidades/orquestacion-autonoma/HABILIDAD.md

@@ -0,0 +1,133 @@
+---
+nombre: Orquestación Autónoma
+descripcion: "Ejecutar múltiples tareas de forma autónoma con coordinación entre agentes y checkpoints humanos"
+version: 1.0.0
+autor: Don Cheli
+tags: [automatización, orquestación, agentes, autónomo]
+activacion: "ejecutar autónomamente", "modo autónomo", "sin supervisión"
+---
+
+# Habilidad: Orquestación Autónoma (Máquina de Estados)
+
+**Versión:** 1.0.0
+**Categoría:** Automatización
+**Tipo:** Flexible
+
+> Adaptado de OpenAI Symphony — máquina de estados para ejecución autónoma.
+
+## Cómo Mejora el Framework
+
+El bucle autónomo (`/bucle`) actual ejecuta tareas secuencialmente sin un modelo formal de estados. Symphony introduce una máquina de estados que permite:
+
+- Reintentos automáticos con backoff exponencial
+- Reconciliación (detectar tareas obsoletas)
+- Concurrencia controlada
+- Recuperación después de fallos
+
+## Estados de Orquestación
+
+```
+                    ┌──────────────┐
+                    │  Sin Reclamar │
+                    └──────┬───────┘
+                           │ dispatch
+                           ▼
+                    ┌──────────────┐
+                    │   Reclamada   │
+                    └──────┬───────┘
+                           │ workspace listo
+                           ▼
+┌───────────┐      ┌──────────────┐      ┌───────────────┐
+│  Reintento │◄─────│  Ejecutando   │─────►│   Completada   │
+│  Pendiente │      └──────────────┘      └───────────────┘
+└─────┬─────┘              │
+      │ timer              │ fallo / timeout
+      │                    ▼
+      │              ┌──────────────┐
+      └─────────────►│   Fallada     │
+                     └──────┬───────┘
+                            │ max reintentos
+                            ▼
+                     ┌──────────────┐
+                     │   Liberada    │
+                     └──────────────┘
+```
+
+## Fases de un Intento
+
+| Fase | Qué Sucede |
+|------|-----------|
+| `PreparandoWorkspace` | Crear/reusar directorio aislado |
+| `ConstruyendoPrompt` | Renderizar template con contexto |
+| `LanzandoAgente` | Iniciar sesión del agente |
+| `EjecutandoTareas` | Agente trabaja en las tareas |
+| `Verificando` | Ejecutar stop hooks |
+| `Exitoso` | Todo pasó |
+| `Fallido` | Algo falló → reintento |
+| `Timeout` | Excedió tiempo → reintento |
+| `Detenido` | Reconciliación detectó cambio de estado |
+
+## Reintentos con Backoff Exponencial
+
+```
+Intento 1: falla → esperar 10s
+Intento 2: falla → esperar 20s
+Intento 3: falla → esperar 40s
+Intento 4: falla → esperar 80s
+...hasta max_backoff (5 min por default)
+```
+
+### Reintentos de Continuación
+
+Cuando una tarea termina normalmente pero el issue sigue activo:
+- Reintento después de 1 segundo
+- Re-verificar si la tarea sigue siendo candidata
+- Si sí → nueva sesión de agente
+- Si no → liberar
+
+## Workspace Aislado por Tarea
+
+```
+.especdev/workspaces/
+├── PROJ-42/              # Workspace para issue PROJ-42
+│   ├── repo/             # Copia/clone del código
+│   ├── logs/             # Logs de la sesión
+│   └── metrics.json      # Métricas de la sesión
+├── PROJ-43/              # Otro workspace aislado
+└── ...
+```
+
+### Invariantes de Seguridad
+
+1. **Agente solo opera dentro de su workspace** — nunca fuera
+2. **Workspace siempre dentro de workspace root** — prevenir path traversal
+3. **Nombres sanitizados** — solo `[A-Za-z0-9._-]` en nombres de directorio
+
+## Hooks de Ciclo de Vida
+
+| Hook | Cuándo | Si Falla |
+|------|--------|----------|
+| `despues_crear` | Workspace recién creado | Fatal (no se crea) |
+| `antes_ejecutar` | Antes de cada ejecución | Fatal (intento falla) |
+| `despues_ejecutar` | Después de cada ejecución | Log y continuar |
+| `antes_eliminar` | Antes de limpiar workspace | Log y continuar |
+
+## Integración con WORKFLOW.md
+
+```yaml
+# WORKFLOW.md front matter
+agente:
+  max_turnos: 15
+  max_reintentos: 3
+  timeout_sesion_ms: 1800000
+concurrencia:
+  max_agentes: 3
+```
+
+## Cuándo Usar
+
+| Situación | Comando |
+|-----------|---------|
+| Una tarea a la vez, manual | `/especdev:implementar` |
+| Pipeline completo, un cambio | `/especdev:aplicar` |
+| Múltiples issues del tracker, autónomo | **Orquestación** |

package/habilidades/permisos-seguridad/HABILIDAD.md

@@ -0,0 +1,76 @@
+---
+nombre: Sistema de Permisos y Seguridad
+descripcion: "Gestionar permisos de archivos, validar acceso y prevenir operaciones peligrosas en el proyecto"
+version: 1.0.0
+autor: Don Cheli
+tags: [seguridad, permisos, acceso, proteccion]
+activacion: "permisos", "seguridad", "acceso a archivos", "operación peligrosa"
+---
+
+# Habilidad: Sistema de Permisos y Seguridad
+
+**Versión:** 1.0.0
+**Categoría:** Seguridad
+**Tipo:** Rígida
+
+> Inspirado en el componente Permissions de Gentle-AI.
+
+## Cómo Mejora el Framework
+
+Los agentes de IA acceden a archivos, ejecutan comandos y modifican configuraciones. Sin permisos explícitos, pueden:
+- Leer `.env` y exponer secrets
+- Ejecutar `git push --force` sin confirmación
+- Borrar archivos o directorios por error
+- Instalar dependencias no deseadas
+
+## Permisos por Defecto (Security-First)
+
+### 🔒 DENEGADO (nunca sin confirmación explícita)
+
+| Acción | Razón |
+|--------|-------|
+| Leer `.env`, `.env.*`, secrets | Proteger credenciales |
+| `git push --force` | Prevenir pérdida de historial |
+| `git reset --hard` | Prevenir pérdida de cambios |
+| `rm -rf` en directorios | Prevenir borrado accidental |
+| Instalar dependencias globales | Prevenir contaminación del sistema |
+| Modificar archivos fuera del proyecto | Prevenir efectos laterales |
+
+### ⚠️ CONFIRMACIÓN REQUERIDA
+
+| Acción | Razón |
+|--------|-------|
+| `git push` a main/master/production | Ramas protegidas |
+| Eliminar archivos >5 archivos | Borrado masivo |
+| Cambiar configuración de CI/CD | Infraestructura crítica |
+| Agregar dependencia nueva | Evaluar necesidad |
+
+### ✅ PERMITIDO
+
+| Acción | Razón |
+|--------|-------|
+| Leer/escribir archivos del proyecto | Trabajo normal |
+| Ejecutar tests | Operación segura |
+| `git add`, `git commit` | Operaciones locales |
+| Crear archivos y directorios | Trabajo normal |
+| Ejecutar linter | Operación segura |
+
+## Configuración
+
+```yaml
+# .especdev/config.yaml
+permisos:
+  archivos_bloqueados:
+    - ".env"
+    - ".env.*"
+    - "*.pem"
+    - "*.key"
+  comandos_confirmacion:
+    - "git push"
+    - "rm -rf"
+    - "npm publish"
+  directorios_protegidos:
+    - "/"
+    - "/usr"
+    - "/etc"
+```

package/habilidades/persona/HABILIDAD.md

@@ -0,0 +1,66 @@
+---
+nombre: Persona del Agente
+descripcion: "Asumir un rol especializado (arquitecto, QA, DBA, etc.) para ofrecer perspectiva experta"
+version: 1.0.0
+autor: Don Cheli
+tags: [persona, rol, configuracion, agente]
+activacion: "actúa como", "rol de", "perspectiva de", "persona"
+---
+
+# Habilidad: Persona del Agente
+
+**Versión:** 1.0.0
+**Categoría:** Configuración
+**Tipo:** Flexible
+
+> Inspirado en el sistema de Personas de Gentle-AI.
+
+## Cómo Mejora el Framework
+
+Un agente de IA sin persona es un chatbot genérico. Con persona:
+- **Enseña** en vez de solo completar código
+- **Desafía** malas prácticas con el POR QUÉ
+- **Consistente** en tono y estilo
+
+## Personas Disponibles
+
+### 🎓 Maestro (Default)
+
+```markdown
+Eres un Senior Architect mentor que enseña mientras construye.
+- Explica el POR QUÉ detrás de cada decisión
+- Desafía malas prácticas con justificación técnica
+- Usa analogías para conceptos complejos
+- Si el usuario pide algo anti-patrón, primero explica la alternativa
+- Idioma: Español
+```
+
+### 🔧 Profesional
+
+```markdown
+Eres un desarrollador senior profesional y directo.
+- Sin personalidad, solo hechos y código
+- Conciso y técnico
+- No explica a menos que se pida
+```
+
+### 🎨 Personalizado
+
+El usuario define su propia persona en `.especdev/persona.md`:
+
+```markdown
+# Mi Persona Personalizada
+
+Eres un desarrollador que:
+- Habla con humor y referencias a la cultura pop
+- Usa emojis para indicar estado
+- Explica con metáforas de cocina
+```
+
+## Configuración
+
+```yaml
+# .especdev/config.yaml
+persona: "maestro"  # maestro | profesional | personalizado
+# Si es personalizado, leer de .especdev/persona.md
+```