theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/aprendizaje-continuo-v2/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: aprendizaje-continuo-v2
+description: Sistema de aprendizaje basado en instintos que observa las sesiones mediante hooks, crea instintos atómicos con puntuación de confianza y los evoluciona hacia skills/comandos/agentes. La v2.1 añade instintos con ámbito de proyecto para evitar la contaminación entre proyectos.
+version: 2.1.0
+---
+
+# Aprendizaje continuo v2.1 - Arquitectura basada en instintos
+
+Un sistema de aprendizaje avanzado que convierte tus sesiones con el CLI en conocimiento reutilizable mediante "instintos" atómicos: pequeños comportamientos aprendidos con puntuación de confianza.
+
+La **v2.1** añade **instintos con ámbito de proyecto** — los patrones de React se quedan en tu proyecto React, las convenciones de Python se quedan en tu proyecto Python, y los patrones universales (como "valida siempre la entrada") se comparten globalmente.
+
+## Cuándo activarla
+
+- Configurar el aprendizaje automático a partir de las sesiones del CLI
+- Configurar la extracción de comportamientos basada en instintos vía hooks
+- Ajustar los umbrales de confianza de los comportamientos aprendidos
+- Revisar, exportar o importar bibliotecas de instintos
+- Evolucionar instintos hacia skills, comandos o agentes completos
+- Gestionar instintos de ámbito de proyecto vs. globales
+- Promover instintos del ámbito de proyecto al global
+
+## Novedades de la v2.1
+
+| Característica | v2.0 | v2.1 |
+|---------------|------|------|
+| Almacenamiento | Global | Con ámbito de proyecto (`~/.theus/arsenal/projects/<hash>/`) |
+| Ámbito | Todos los instintos aplican en todas partes | De proyecto + global |
+| Detección | Ninguna | URL del remoto git / ruta del repo |
+| Promoción | N/D | Proyecto → global al verse en 2+ proyectos |
+| Comandos | 4 (estado/evolucionar/exportar/importar) | 6 (+promover/proyectos) |
+| Entre proyectos | Riesgo de contaminación | Aislados por defecto |
+
+## Novedades de la v2 (vs. v1)
+
+| Característica | v1 | v2 |
+|---------------|----|----|
+| Observación | Hook Stop (fin de sesión) | PreToolUse/PostToolUse (100 % fiable) |
+| Análisis | Contexto principal | Agente en segundo plano (modelo económico) |
+| Granularidad | Skills completas | "Instintos" atómicos |
+| Confianza | Ninguna | Ponderada 0.3-0.9 |
+| Evolución | Directo a skill | Instintos -> clúster -> skill/comando/agente |
+| Compartición | Ninguna | Exportar/importar instintos |
+
+## El modelo de instinto
+
+Un instinto es un pequeño comportamiento aprendido:
+
+```yaml
+---
+id: prefer-functional-style
+trigger: "al escribir funciones nuevas"
+confidence: 0.7
+domain: "code-style"
+source: "session-observation"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "mi-app-react"
+---
+
+# Preferir estilo funcional
+
+## Action
+Usar patrones funcionales en lugar de clases cuando sea apropiado.
+
+## Evidence
+- Se observaron 5 instancias de preferencia por el patrón funcional
+- El usuario corrigió un enfoque basado en clases hacia funcional el 2025-01-15
+```
+
+**Propiedades:**
+- **Atómico** — un disparador, una acción
+- **Ponderado por confianza** — 0.3 = tentativo, 0.9 = casi seguro
+- **Etiquetado por dominio** — code-style, testing, git, debugging, workflow, etc.
+- **Respaldado por evidencia** — registra qué observaciones lo crearon
+- **Consciente del ámbito** — `project` (por defecto) o `global`
+
+## Cómo funciona
+
+```
+Actividad de la sesión (en un repo git)
+      |
+      | Los hooks capturan prompts + uso de herramientas (100 % fiable)
+      | + detectan el contexto del proyecto (remoto git / ruta del repo)
+      v
++---------------------------------------------+
+|  projects/<hash-proyecto>/observations.jsonl |
+|   (prompts, llamadas a tools, resultados)    |
++---------------------------------------------+
+      |
+      | El agente observador lee (en segundo plano, modelo económico)
+      v
++---------------------------------------------+
+|          DETECCIÓN DE PATRONES               |
+|   * Correcciones del usuario -> instinto     |
+|   * Resoluciones de errores -> instinto      |
+|   * Flujos repetidos -> instinto             |
+|   * Decisión de ámbito: ¿proyecto o global?  |
++---------------------------------------------+
+      |
+      | Crea/actualiza
+      v
++---------------------------------------------+
+|  projects/<hash-proyecto>/instincts/personal/|
+|   * prefer-functional.yaml (0.7) [proyecto]  |
+|   * use-react-hooks.yaml (0.9) [proyecto]    |
++---------------------------------------------+
+|  instincts/personal/  (GLOBAL)               |
+|   * always-validate-input.yaml (0.85) [global]|
+|   * grep-before-edit.yaml (0.6) [global]     |
++---------------------------------------------+
+      |
+      | /evolucionar agrupa + /promover
+      v
++---------------------------------------------+
+|  projects/<hash>/evolved/ (ámbito proyecto)  |
+|  evolved/ (global)                           |
+|   * commands/nueva-funcionalidad.md          |
+|   * skills/flujo-testing.md                  |
+|   * agents/especialista-refactor.md          |
++---------------------------------------------+
+```
+
+## Detección de proyecto
+
+El sistema detecta automáticamente tu proyecto actual:
+
+1. **Variable de entorno `THEUS_PROJECT_DIR`** (máxima prioridad)
+2. **`git remote get-url origin`** — se hashea para crear un ID de proyecto portátil (el mismo repo en distintas máquinas obtiene el mismo ID)
+3. **`git rev-parse --show-toplevel`** — fallback usando la ruta del repo (específica de la máquina)
+4. **Fallback global** — si no se detecta proyecto, los instintos van al ámbito global
+
+Cada proyecto recibe un ID hash de 12 caracteres (p. ej. `a1b2c3d4e5f6`). Un archivo de registro en `~/.theus/arsenal/projects.json` mapea los IDs a nombres legibles.
+
+### Directorio de datos
+
+El estado persistente vive en `~/.theus/arsenal/`, la raíz de datos estándar del arsenal (la misma que resuelve `scripts/lib/agent-data-home.js` para los scripts Node del plugin). Puede sobrescribirse con la variable `THEUS_AGENT_DATA_HOME` (ruta absoluta).
+
+## Inicio rápido
+
+### 1. Habilitar los hooks de observación
+
+El hook de observación es **opt-in**: el plugin no lo registra automáticamente. Para habilitarlo, añade este bloque a tu `~/.theus/settings.json` (ajusta la ruta si tu instalación del plugin vive en otro lugar):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.theus/plugins/theus-arsenal/skills/aprendizaje-continuo-v2/hooks/observe.sh pre"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.theus/plugins/theus-arsenal/skills/aprendizaje-continuo-v2/hooks/observe.sh post"
+      }]
+    }]
+  }
+}
+```
+
+No dupliques el bloque si ya lo tienes registrado: un hook duplicado provoca doble ejecución de cada observación.
+
+### 2. Inicializar la estructura de directorios
+
+El sistema crea los directorios automáticamente en el primer uso, pero también puedes crearlos a mano:
+
+```bash
+# Directorios globales
+mkdir -p ~/.theus/arsenal/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
+
+# Los directorios por proyecto se crean solos la primera vez que el hook corre en un repo git
+```
+
+### 3. Usar los comandos de instintos
+
+```bash
+/instintos-estado    # Muestra los instintos aprendidos (proyecto + global)
+/evolucionar         # Agrupa instintos relacionados en skills/comandos
+/instintos-exportar  # Exporta instintos a un archivo
+/instintos-importar  # Importa instintos de otras personas
+/promover            # Promueve instintos de proyecto al ámbito global
+/proyectos           # Lista los proyectos conocidos y sus recuentos de instintos
+```
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `/instintos-estado` | Muestra todos los instintos (de proyecto + globales) con su confianza |
+| `/evolucionar` | Agrupa instintos relacionados en skills/comandos y sugiere promociones |
+| `/instintos-exportar` | Exporta instintos (filtrables por ámbito/dominio) |
+| `/instintos-importar <archivo>` | Importa instintos con control de ámbito |
+| `/promover [id]` | Promueve instintos de proyecto al ámbito global |
+| `/proyectos` | Lista los proyectos conocidos y sus recuentos de instintos |
+
+## Configuración
+
+Edita `config.json` para controlar el observador en segundo plano:
+
+```json
+{
+  "version": "2.1",
+  "observer": {
+    "enabled": false,
+    "run_interval_minutes": 5,
+    "min_observations_to_analyze": 20
+  }
+}
+```
+
+| Clave | Por defecto | Descripción |
+|-------|-------------|-------------|
+| `observer.enabled` | `false` | Habilita el agente observador en segundo plano |
+| `observer.run_interval_minutes` | `5` | Cada cuánto analiza las observaciones el observador |
+| `observer.min_observations_to_analyze` | `20` | Observaciones mínimas antes de que corra el análisis |
+
+El resto del comportamiento (captura de observaciones, umbrales de instintos, ámbito de proyecto, criterios de promoción) se configura mediante los valores por defecto del código en `instinct-cli.py` y `observe.sh`.
+
+## Estructura de archivos
+
+```
+~/.theus/arsenal/
++-- identity.json           # Tu perfil, nivel técnico
++-- projects.json           # Registro: hash de proyecto -> nombre/ruta/remoto
++-- observations.jsonl      # Observaciones globales (fallback)
++-- instincts/
+|   +-- personal/           # Instintos globales autoaprendidos
+|   +-- inherited/          # Instintos globales importados
++-- evolved/
+|   +-- agents/             # Agentes globales generados
+|   +-- skills/             # Skills globales generadas
+|   +-- commands/           # Comandos globales generados
++-- projects/
+    +-- a1b2c3d4e5f6/       # Hash del proyecto (de la URL del remoto git)
+    |   +-- project.json    # Espejo de metadatos por proyecto (id/nombre/raíz/remoto)
+    |   +-- observations.jsonl
+    |   +-- observations.archive/
+    |   +-- instincts/
+    |   |   +-- personal/   # Autoaprendidos específicos del proyecto
+    |   |   +-- inherited/  # Importados específicos del proyecto
+    |   +-- evolved/
+    |       +-- skills/
+    |       +-- commands/
+    |       +-- agents/
+    +-- f6e5d4c3b2a1/       # Otro proyecto
+        +-- ...
+```
+
+## Guía de decisión de ámbito
+
+| Tipo de patrón | Ámbito | Ejemplos |
+|----------------|--------|----------|
+| Convenciones de lenguaje/framework | **project** | "Usar hooks de React", "Seguir patrones de Django REST" |
+| Preferencias de estructura de archivos | **project** | "Tests en `__tests__/`", "Componentes en src/components/" |
+| Estilo de código | **project** | "Usar estilo funcional", "Preferir dataclasses" |
+| Estrategias de manejo de errores | **project** | "Usar tipo Result para errores" |
+| Prácticas de seguridad | **global** | "Validar la entrada del usuario", "Sanear SQL" |
+| Buenas prácticas generales | **global** | "Escribir tests primero", "Manejar siempre los errores" |
+| Preferencias de flujo de herramientas | **global** | "Grep antes de Edit", "Read antes de Write" |
+| Prácticas de git | **global** | "Commits convencionales", "Commits pequeños y enfocados" |
+
+## Promoción de instintos (proyecto -> global)
+
+Cuando el mismo instinto aparece en varios proyectos con alta confianza, es candidato a promoción al ámbito global.
+
+**Criterios de autopromoción:**
+- Mismo ID de instinto en 2+ proyectos
+- Confianza media >= 0.8
+
+**Cómo promover:**
+
+```bash
+# Promover un instinto concreto
+python3 instinct-cli.py promote prefer-explicit-errors
+
+# Autopromover todos los que califiquen
+python3 instinct-cli.py promote
+
+# Vista previa sin cambios
+python3 instinct-cli.py promote --dry-run
+```
+
+El comando `/evolucionar` también sugiere candidatos a promoción.
+
+## Puntuación de confianza
+
+La confianza evoluciona con el tiempo:
+
+| Puntuación | Significado | Comportamiento |
+|------------|-------------|----------------|
+| 0.3 | Tentativo | Se sugiere pero no se aplica de oficio |
+| 0.5 | Moderado | Se aplica cuando es relevante |
+| 0.7 | Fuerte | Autoaprobado para su aplicación |
+| 0.9 | Casi seguro | Comportamiento central |
+
+**La confianza sube** cuando:
+- El patrón se observa repetidamente
+- El usuario no corrige el comportamiento sugerido
+- Instintos similares de otras fuentes coinciden
+
+**La confianza baja** cuando:
+- El usuario corrige el comportamiento explícitamente
+- El patrón no se observa durante periodos prolongados
+- Aparece evidencia contradictoria
+
+## ¿Por qué hooks en vez de skills para observar?
+
+La v1 dependía de skills para observar. Las skills son probabilísticas: se activan aproximadamente el 50-80 % de las veces según el criterio del modelo.
+
+Los hooks se disparan **el 100 % de las veces**, de forma determinista. Esto significa:
+- Cada llamada a una herramienta se observa
+- No se pierden patrones
+- El aprendizaje es exhaustivo
+
+## Privacidad
+
+- Las observaciones se quedan **en local**, en tu máquina
+- Los instintos con ámbito de proyecto están aislados por proyecto
+- Solo se pueden exportar **instintos** (patrones), no observaciones en bruto
+- No se comparte código real ni contenido de conversaciones
+- Tú controlas qué se exporta y qué se promueve
+
+## Relacionado
+
+- El hook de inicio de sesión del arsenal inyecta automáticamente los instintos de mayor confianza en el contexto (ajustable con `THEUS_INSTINCT_CONFIDENCE_THRESHOLD` y `THEUS_MAX_INJECTED_INSTINCTS`).
+- Comando `/aprender` — extracción de patrones dirigida por el usuario dentro de una sesión.
+
+---
+
+*Aprendizaje basado en instintos: enseñarle tus patrones al agente, un proyecto a la vez.*