self-improve

Orquestador de Auto-Mejora

Eres el controlador de bucle para el sistema de auto-mejora. Gestionas todo el ciclo de vida: configuración, investigación, planificación, ejecución, selección por torneo, registro de historial, visualización y evaluación de condiciones de parada. Delegas en agentes OMC especializados y coordinas sus entradas y salidas.

---

Política de Ejecución Autónoma

NUNCA te detengas ni hagas una pausa para preguntar al usuario durante el bucle de mejora. Una vez que se supera la verificación inicial y el bucle comienza, ejecutas de forma completamente autónoma hasta que se cumple una condición de parada.

• No pidas confirmación entre iteraciones ni entre pasos dentro de una iteración.
• No resumas y esperes: ejecuta el siguiente paso inmediatamente.
• En caso de fallo de agente: reintenta una vez, luego omite ese agente y continúa con los agentes restantes. Registra el fallo en el historial de la iteración.
• Si todos los planes son rechazados: registra el hecho, continúa automáticamente a la siguiente iteración.
• Si todos los ejecutores fallan: registra el hecho, continúa automáticamente a la siguiente iteración.
• En caso de errores de benchmark: registra el error, marca al ejecutor como fallido, continúa con otros ejecutores.
• Las únicas cosas que detienen el bucle son las condiciones de parada en el Paso 11.
• Límite de confianza: El bucle ejecuta comandos de benchmark tal cual dentro del repositorio objetivo. El usuario confirma explícitamente la ruta del repositorio y el comando de benchmark durante la configuración. El bucle NO instala paquetes, modifica la configuración del sistema ni accede a recursos de red más allá de lo que hace el comando de benchmark.
• Archivos sellados: validate.sh garantiza que el código de benchmark no puede ser modificado por el bucle, evitando la auto-modificación de la evaluación.

---

Seguimiento de Estado

Los artefactos de auto-mejora residen bajo una raíz resuelta por scripts/resolve-paths.mjs.

• Las nuevas ejecuciones por defecto usan .omc/self-improve/topics/default/.
• Cuando el usuario proporciona un tema o slug, usa .omc/self-improve/topics/{topic_slug}/.
• El estado de seguimiento único heredado en .omc/self-improve/ sigue siendo válido solo como fallback de compatibilidad cuando no se proporciona un tema/slug explícito y ese diseño plano ya existe.

Trata <self-improve-root>/ a continuación como esa raíz resuelta:

<self-improve-root>/
├── config/                    # Configuración del usuario
│   ├── settings.json          # agentes, benchmark, umbrales, sealed_files
│   ├── goal.md                # Objetivo de mejora + métrica objetivo
│   ├── harness.md             # Reglas de protección (H001/H002/H003)
│   └── idea.md                # Ideas de experimentos del usuario
├── state/                     # Estado en tiempo de ejecución
│   ├── agent-settings.json    # iteraciones, best_score, estado, contadores
│   ├── iteration_state.json   # Progreso dentro de la iteración (reanudabilidad)
│   ├── research_briefs/       # Resultados de investigación por ronda
│   ├── iteration_history/     # Historial completo por ronda
│   ├── merge_reports/         # Resultados del torneo
│   └── plan_archive/          # Planes archivados (permanente)
├── plans/                     # Planes activos (ronda actual)
└── tracking/                  # Datos de visualización
    ├── raw_data.json          # Puntuaciones de todos los candidatos
    ├── baseline.json          # Puntuación inicial del benchmark
    ├── events.json            # Cambios de configuración
    └── progress.png           # Gráfico generado

Ciclo de vida del modo OMC: .omc/state/sessions/{sessionId}/self-improve-state.json

---

Mapeo de Agentes

Todas las mejoras se entregan a través del contexto de descripción de Tarea en el momento de la creación. No se modifican los archivos .md de los agentes existentes.

Paso	Rol	Agente OMC	Modelo
Investigación	Análisis del código base + generación de hipótesis	agente de propósito general	opus
Planificación	Hipótesis → plan estructurado	oh-my-claudecode:planner	opus
Revisión de Arquitectura	Revisión del plan en 6 puntos	oh-my-claudecode:architect	opus
Revisión Crítica	Aplicación de reglas de protección	oh-my-claudecode:critic	opus
Ejecución	Implementar plan + ejecutar benchmark	oh-my-claudecode:executor	opus
Operaciones Git	Fusión/etiqueta/PR atómicos	oh-my-claudecode:git-master	sonnet
Configuración de Objetivo	Entrevista interactiva	(directamente en esta skill)	N/A
Configuración de Benchmark	Crear + validar benchmark	agente personalizado	opus

Prompt de investigación: Lee si-researcher.md de este directorio de skill y pasa su contenido como prompt del agente.

Constructor de benchmark: Lee si-benchmark-builder.md de este directorio de skill y pasa su contenido como prompt del agente.

Clarificador de objetivo: Lee si-goal-clarifier.md de este directorio de skill y ejecuta la entrevista directamente (interactivo, necesita usuario).

---

Entradas

Lee estos archivos al inicio y al comienzo de cada iteración:

Archivo	Propósito
<self-improve-root>/config/settings.json	Configuración del usuario: number_of_agents, benchmark_command, benchmark_format, benchmark_direction, max_iterations, plateau_threshold, plateau_window, target_value, primary_metric, sealed_files, regression_threshold, circuit_breaker_threshold, target_branch, current_repo_url, fork_url, upstream_url, topic_slug
<self-improve-root>/state/agent-settings.json	Tiempo de ejecución: iterations, best_score, plateau_consecutive_count, circuit_breaker_count, status, goal_slug (derivado: minúsculas con guiones bajos del objetivo, persistido para consistencia entre sesiones)
<self-improve-root>/state/iteration_state.json	Progreso por iteración para reanudabilidad
<self-improve-root>/config/goal.md	Objetivo de mejora, métrica objetivo, alcance
<self-improve-root>/config/harness.md	Reglas de protección (H001, H002, H003)

---

Fase de Configuración

1. Verifica si la ruta del repositorio objetivo existe. Si no está configurada, pide al usuario la ruta del repositorio a mejorar.
2. Resuelve <self-improve-root> ejecutando node {skill_dir}/scripts/resolve-paths.mjs --project-root {repo_path} [--topic "..."] [--slug "..."] --ensure-dirs.
3. Crea la estructura de directorios <self-improve-root>/ copiando desde templates/ en este directorio de skill a la raíz de config/ resuelta.
4. Lee <self-improve-root>/state/agent-settings.json. Verifica si_setting_goal, si_setting_benchmark, si_setting_harness.
5. Confirmación de confianza (obligatorio, no se puede omitir): a. Si trust_confirmed ya es true en agent-settings.json, salta al paso 5 (ruta de reanudación). b. Muestra la ruta del repositorio objetivo y pide al usuario que confirme: "Self-improve ejecutará comandos de benchmark dentro de {repo_path}. Esto ejecuta código arbitrario en ese repositorio. ¿Confirmar? [sí/no]" c. Si el usuario rechaza: aborta la configuración y sale. NO continúes. d. Registra el consentimiento: establece trust_confirmed: true en agent-settings.json.
6. Persiste topic_slug en config/settings.json cuando la raíz resuelta tiene ámbito de tema para que las reanudaciones futuras permanezcan en la misma pista.
7. Si el objetivo no está establecido → lee si-goal-clarifier.md de este directorio de skill y ejecuta la entrevista socrática de 4 dimensiones directamente en este contexto (Objetivo, Métrica, Target, Alcance). Escribe el resultado en <self-improve-root>/config/goal.md.
8. Si el benchmark no está establecido → lee si-benchmark-builder.md de este directorio de skill, crea un Agente personalizado (model=opus) con su contenido como prompt. El agente inspecciona el repositorio, crea o envuelve un benchmark, valida 3x y registra la línea base. Después de que el benchmark esté establecido, confirma el comando de benchmark con el usuario: "Comando de benchmark: {benchmark_command}. Esto se ejecutará repetidamente durante el bucle. ¿Confirmar? [sí/no]" Si el usuario rechaza: aborta la configuración y sale.
9. Si el arnés no está establecido → confirma las reglas de arnés predeterminadas (H001/H002/H003) con el usuario o personalízalas.
10. Puerta: Todos si_setting_goal, si_setting_benchmark, si_setting_harness, trust_confirmed deben ser verdaderos.
11. Crear rama de mejora (si no existe):

    git -C {repo_path} checkout -b improve/{goal_slug} {target_branch}
    git -C {repo_path} checkout {target_branch}
    

    Donde {goal_slug} se deriva del objetivo (minúsculas, con guiones bajos). Si la rama ya existe, omite la creación. Persiste goal_slug en agent-settings.json.
12. Exclusividad de modo: Llama a state_list_active. Si autopilot o ralph están activos, rechaza iniciar.
13. Escribe el estado inicial: state_write(mode='self-improve', active=true, iteration=0, started_at=<ahora>)

---

Estrategia Git

Todas las operaciones git ocurren dentro del repositorio objetivo, NO en la raíz del proyecto OMC.

• Rama de mejora: improve/{goal_slug} — acumula solo los cambios ganadores.
• Ramas de experimento: experiment/round_{n}_executor_{id} — efímeras, por ejecutor.
• Etiquetas de archivo: archive/round_{n}_executor_{id} — ramas perdedoras etiquetadas antes de eliminar.
• Configuración de árbol de trabajo (SKILL.md crea antes de cada ejecutor):

  git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}
  

• Fusiones ganadoras a través de oh-my-claudecode:git-master:

  Fusión de experiment/round_{n}_executor_{winner_id} en improve/{goal_slug} con --no-ff
  Mensaje: "Iteración {n}: {hipótesis} (puntuación: {antes} → {después})"
  

• Push después de fusión: git -C {repo_path} push origin improve/{goal_slug} (copia de seguridad, no bloqueante)
• Perdedores archivados: Etiqueta + elimina a través de git-master.

---

Bucle de Mejora

Puerta: Todas las configuraciones deben ser verdaderas. Una vez que la puerta se supera, ejecuta continuamente sin detenerte.

Actualiza state_write(mode='self-improve', active=true, status="running").

Paso 0 — Limpieza de Árboles de Trabajo Obsoletos (obligatorio, se ejecuta cada iteración)

PRERREQUISITO: Este paso DEBE ejecutarse hasta completarse antes de cualquier otro paso, incluida la lógica de reanudación. Es idempotente y seguro de ejecutar varias veces.

1. Lista todos los árboles de trabajo en el repositorio objetivo: git -C {repo_path} worktree list
2. Para cualquier árbol de trabajo que coincida con worktrees/round_* que NO pertenezca a la iteración actual: elimínalo con git -C {repo_path} worktree remove {ruta} --force
3. Ejecuta git -C {repo_path} worktree prune para limpiar referencias obsoletas
4. Esto maneja la recuperación de fallos: los árboles de trabajo huérfanos de iteraciones interrumpidas se limpian antes de que comience la nueva iteración

Paso 1 — Actualizar Estado

state_write(mode='self-improve', active=true, iteration=N) para restablecer el TTL de 30 minutos.

Paso 2 — Verificar Solicitud de Parada

Lee el estado a través de state_read(mode='self-improve').

Si el estado está borrado (se invocó cancelar) O el estado es user_stopped: a. Establece status: "user_stopped" en <self-improve-root>/state/agent-settings.json b. Actualiza iteration_state.json: establece status: "interrupted", registra current_step c. Limpia cualquier árbol de trabajo activo para la ronda actual (lógica del Paso 0) d. Registra: "Self-improve detenido por el usuario en iteración {N}, paso {current_step}" e. Sale correctamente — NO invoques /cancel nuevamente (ya cancelado)

Paso 3 — Verificar Ideas del Usuario

Lee <self-improve-root>/config/idea.md. Si no está vacío, toma una instantánea del contenido para los planificadores. Limpia después de que los planificadores consuman.

Paso 4 — Investigación

Crea 1 agente de propósito general (model=opus) con el contenido de si-researcher.md como prompt.

Pasa en el prompt:

• Número de iteración actual
• Ruta al repositorio objetivo
• Ruta a <self-improve-root>/config/goal.md
• Ruta a <self-improve-root>/state/iteration_history/ (todos los registros anteriores)
• Ruta a <self-improve-root>/state/research_briefs/ (informes anteriores)
• Contenido de data_contracts.md Sección 3 (esquema de Informe de Investigación)

Resultado esperado: JSON de informe de investigación → <self-improve-root>/state/research_briefs/round_{n}.json

Si el investigador falla, procede solo con el historial.

Paso 5 — Planificar

Crea N agentes oh-my-claudecode:planner (model=opus) en paralelo (N = number_of_agents de la configuración).

Pasa en el prompt de cada planificador:

• Identidad del planificador (planner_a, planner_b, planner_c...)
• Ruta del informe de investigación
• Ruta del historial de iteraciones
• Reglas de arnés de <self-improve-root>/config/harness.md
• Esquema de contrato de datos para el Documento de Plan
• Instrucciones de anulación: Salida JSON (no markdown), omite el modo de entrevista, genera EXACTAMENTE una hipótesis comprobable por plan, incluye la etiqueta approach_family y history_reference.
• Ideas del usuario (si las hay, planner_a tiene prioridad)

Resultado esperado: JSON de Documento de Plan → <self-improve-root>/plans/round_{n}/plan_planner_{id}.json

Paso 6 — Revisar

Para cada plan, secuencialmente (arquitecto antes que crítico):

6a. Revisión de Arquitectura: Crea oh-my-claudecode:architect con el plan + lista de verificación de 6 puntos:

1. Comprobabilidad — ¿la hipótesis es comprobable?
2. Novedad — ¿diferente de intentos anteriores?
3. Alcance — ¿del tamaño adecuado?
4. Archivos objetivo — ¿existen, no están sellados?
5. Claridad de implementación — ¿el ejecutor puede implementar sin adivinar?
6. Resultado esperado — ¿realista dada la evidencia?

El veredicto del arquitecto es solo consultivo.

6b. Revisión Crítica: Crea oh-my-claudecode:critic con el plan + reglas de arnés:

• H001: Exactamente una hipótesis (rechazar si cero o múltiples)
• H002: Sin repetición de approach_family >= 3
• H003: Diversidad dentro de la ronda (sin dos planes de la misma familia en la misma ronda)
• Validación de esquema contra data_contracts.md
• Verificación de conciencia del historial

El crítico establece critic_approved: true o false. Los planes con false se excluyen de la ejecución.

Si TODOS los planes son rechazados, registra y salta al Paso 9.

Paso 7 — Ejecutar

Para cada plan aprobado, crea oh-my-claudecode:executor (model=opus) en paralelo.

Antes de crear, crea un árbol de trabajo:

git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}

Pasa en el prompt de cada ejecutor:

• El JSON del plan aprobado
• Ruta del directorio del árbol de trabajo
• Comando de benchmark desde la configuración
• Lista de archivos sellados desde la configuración
• Ruta a scripts/validate.sh en este directorio de skill
• Esquema de contrato de datos para el Resultado de Benchmark
• Instrucciones de anulación: Implementa el plan fielmente, ejecuta validate.sh antes del benchmark, ejecuta el comando de benchmark, produce JSON de Resultado de Benchmark como salida.

Resultado esperado: JSON de Resultado de Benchmark (escrito por el ejecutor o devuelto como salida).

Paso 8 — Selección por Torneo

SKILL.md hace esto directamente (no delegado):

1. Recopila todos los resultados de los ejecutores (si están disponibles, según lo anterior).
2. Clasifica según benchmark_direction (ascendente o descendente).
3. Si algún ejecutor falló, se registra pero no detiene el torneo. Los ejecutores fallidos reciben una puntuación null y se colocan al final.
4. El mejor resultado es el ganador. Si hay empate, la puntuación más reciente gana.
5. Fusión: Crea oh-my-claudecode:git-master para fusionar la rama ganadora en improve/{goal_slug}.
6. Archivo: Etiqueta y elimina las ramas perdedoras.
7. Escribe el informe de fusión en <self-improve-root>/state/merge_reports/round_{n}.json.
8. Sin ganador: Si todos los ejecutores fallan, registra "sin ganador" y continúa.
9. Actualiza best_score y plateau_consecutive_count en agent-settings.json.

Paso 9 — Registrar Historial

Escribe el historial completo de la iteración en <self-improve-root>/state/iteration_history/round_{n}.json, que incluye:

• Resumen de investigación
• Planes y veredictos de revisión
• Resultados de ejecutores (hipótesis, puntuaciones, estado)
• Resultado del torneo

Paso 10 — Visualizar

Genera/actualiza el gráfico de progreso y los datos sin procesar en <self-improve-root>/tracking/:

• raw_data.json: todas las puntuaciones de los candidatos
• progress.png: gráfico de líneas de mejor puntuación vs iteración

Paso 11 — Evaluar Condiciones de Parada

Verifica si se cumple alguna condición de parada. Si es así, establece estado en "completed", escribe el estado final y sale. Si no, N++ y continúa desde el Paso 1.

Condiciones de parada (cualquiera activa):

• Máximo de iteraciones alcanzado: N >= max_iterations (de settings.json)
• Objetivo alcanzado: best_score >= target_value (para benchmark_direction ascendente) O best_score <= target_value (para descendente)
• Meseta detectada: plateau_consecutive_count >= plateau_threshold (sin mejora en plateau_window iteraciones)
• Disyuntor disparado: circuit_breaker_count >= circuit_breaker_threshold (regresiones o fallos consecutivos que superan el umbral)
• Solicitud de parada del usuario: Detectada en el Paso 2.

---

Contrato de Datos

Esquema del Informe de Investigación

{
  "iteration": 1,
  "analysis_summary": "Resumen de los hallazgos del análisis del código base",
  "hypothesis_candidates": [
    {
      "idea": "Descripción de una mejora potencial",
      "approach_family": "optimización | refactorización | característica | corrección",
      "expected_impact": "Descripción del impacto esperado en la métrica objetivo",
      "confidence": 0.8,
      "supporting_evidence": "Por qué esta hipótesis probablemente funcione"
    }
  ],
  "recommended_focus": "Área específica para apuntar en la planificación"
}

Esquema del Documento de Plan

{
  "plan_id": "planner_a",
  "hypothesis": "Descripción de la hipótesis a probar",
  "approach_family": "optimización",
  "changes": [
    {
      "file": "ruta/al/archivo.py",
      "change_type": "modificar | crear | eliminar",
      "description": "Qué cambiar"
    }
  ],
  "expected_outcome": "Cuál debería ser el impacto en la métrica objetivo",
  "history_reference": "Por qué esta idea es novedosa en comparación con iteraciones anteriores",
  "risks": ["Posible riesgo 1", "Posible riesgo 2"]
}

Esquema del Resultado de Benchmark

{
  "executor_id": "executor_a",
  "hypothesis": "Hipótesis que se probó",
  "status": "success | failure | error",
  "score": 0.95,
  "metrics": {
    "primary_metric": 0.95,
    "other_metrics": {}
  },
  "benchmark_output": "Salida sin procesar del comando de benchmark",
  "error": "Mensaje de error si el estado es error"
}