kilo-code

name	kilo-code
description	Delegate ALL code generation, testing, and documentation to Kilo Code CLI. Hermes is a LIGHTWEIGHT ORCHESTRATOR only.
version	1.3.0
author	Toolset Personal
license	MIT
platforms	["linux"]
metadata	{"hermes":{"tags":["Coding-Agent","Kilo","Kairos","Orchestration","Automation"],"related_skills":["hermes-agent","markitdown-converter"]}}

Kilo Code — Mandato de Delegación Total

Regla Cardinal

Hermes NO escribe código. Punto. Toda generación de código, testeo, debugging, refactorización, creación de documentación kairos (MASTER-SPEC, TODO, MEMORY, USER-DECISIONS, CHANGELOG) y cualquier archivo .py, .ts, .js, .md de proyecto DEBE ser generado por Kilo CLI.

Hermes solo:

• Recibe la solicitud del usuario
• Carga contexto de Hindsight (recall)
• Construye el prompt para Kilo con instrucciones claras
• Invoca kilo run --auto
• Persiste aprendizajes en Hindsight (retain)
• Reporta resultados al usuario

Si Hermes escribe código directamente, el usuario lo corrige. Señal de alerta: cuando el usuario pregunta "¿Estás usando Kilo CLI para esto?" ya operaste mal.

⚠️ PREAMBLE OBLIGATORIO — Toda invocación a Kilo

Toda invocación a kilo run ... --auto DEBE incluir este preámbulo al INICIO del prompt:

[TAREA ESPECÍFICA]

MARCO OBLIGATORIO (ejecutar en este orden, ANTES de escribir código):
1. Leer docs/REPOMAP.md si existe en el repositorio
2. Leer .agents/rules/01-behavior.md y seguir sus triggers dinámicos
3. hindsight-selfhosted_recall(max_tokens=1024, budget="low") para contexto del proyecto
4. Completar la tarea siguiendo estrictamente las reglas de .agents/
5. Si hubo modificaciones: ejecutar paso a paso .agents/workflows/document.md

El marco va DESPUÉS de la tarea para contrarrestar el sesgo de recencia del modelo. No es opcional. Aplica a TODA ejecución futura de Kilo.

⚠️ ANTI-CORRUPCIÓN — Cómo pasar prompts a Kilo

NUNCA generes prompts largos inline en un tool call de terminal. Si el stream del provider se corta, el comando queda truncado y Kilo recibe garbage.

REGLAS:

1. Prompts de 1-3 palabras sin caracteres especiales → inline aceptable: kilo run "tarea" --auto
2. Prompts con más de 10 palabras, backticks, comillas o saltos de línea → USAR --file:

   write_file /tmp/kilo-prompt.txt {
     content: "[TAREA ESPECÍFICA]\n\nMARCO OBLIGATORIO (ejecutar en orden):\n1. Leer docs/REPOMAP.md\n2. hindsight-selfhosted_recall(max_tokens=1024, budget=\"low\")\n3. Completar tarea siguiendo .agents/\n4. Si hubo modificaciones: ejecutar .agents/workflows/document.md"
   }
   kilo run --file /tmp/kilo-prompt.txt --auto --dir /path
   

3. Prompts que contienen /document o referencias a workflows → SIEMPRE --file y el marco obligatorio DEBE estar presente.

Esto evita que un stream truncado deje a Kilo sin instrucciones.

API Key — Export Correcto

La API key de OpenCode Go NO se exporta correctamente con source simple. Usar SIEMPRE:

set -a && source /home/opc/.hermes/.env && set +a

Luego invocar Kilo en el mismo comando compuesto, o usar el wrapper /opt/researchit/kilo.sh.

Kairos .agents/ — Obligatorio en Cada Proyecto

Para CADA proyecto nuevo o clonado, Hermes DEBE:

1. Clonar .agents/ desde kirlts/kairos en la raíz del proyecto
2. Crear docs/ con MASTER-SPEC.md, TODO.md, MEMORY.md, USER-DECISIONS.md, CHANGELOG.md siguiendo .agents/templates/
3. Ejecutar /document workflow (vía Kilo: kilo run "Ejecuta /document según .agents/workflows/document.md" --auto)
4. Crear bank en Hindsight con bank_id = nombre-del-repo-profile (patron <profile>-profile. Excepcion: toolset usa toolset sin sufijo)
5. Crear skill Hermes para la capacidad permanente
6. Push a GitHub

Estrategia de Delegación

1. Cargar contexto: recall(bank_id="<repo-name>-profile", max_tokens=1024, budget="low", query="contexto del proyecto")
2. Si .agents/ no existe en el repo → clonar desde kirlts/kairos primero
3. Delegar TODO a Kilo (código, tests, docs, debugging)
4. Monitorear: si Kilo excede timeout (exit 124), dividir en subtareas más pequeñas
5. Persistir: retain(bank_id="<repo-name>-profile", content="qué se hizo, qué se aprendió")
6. /document periódico: ejecutar /document tras bloques de trabajo significativos. IMPORTANTE: el /document se ejecuta SIEMPRE en el contexto del repo kirlts/toolset (el repo de gobierno central), NO en el repo donde se trabajó. Toolset es el repo que contiene la configuración global de Hermes, skills, y documentación de infraestructura.
7. Reportar al usuario concreto y sin verborrea

Arquitectura de System Prompt en Kilo

Kilo CLI 7.3.54 construye su system prompt desde tres fuentes, no una:

Fuente A — agent.build.prompt en kilo.jsonc (identidad persistente): Define la identidad del agente efímero. En este stack: gobernanza via .agents/, Hindsight memory, anti-corporate tone. Se inyecta como system message base.

Fuente B — Array instructions en kilo.jsonc (archivos de reglas): Rutas relativas resueltas contra el --dir del proyecto. Cada archivo se lee y se concatena al system prompt. Si un archivo no existe, se skipea silenciosamente — sin warning ni error visible.

Las rutas se resuelven así:

--dir /home/opc/personal
  → "docs/RULES.md"                    → /home/opc/personal/docs/RULES.md
  → ".agents/rules/01-behavior.md"     → /home/opc/personal/.agents/rules/01-behavior.md
  → ".agents/rules/05-constraints.md"  → /home/opc/personal/.agents/rules/05-constraints.md

Fuente C — Carga dinámica en runtime: El agente Kilo lee archivos adicionales durante la ejecución según las reglas de Kairós que ya recibió en Fuente B. Por ejemplo: 01-behavior.md manda leer REPOMAP.md primero, luego carga dinámicamente 02-linguistics.md, MASTER-SPEC.md, etc. según las condiciones de [RULE: DYNAMIC CONTEXT LOAD].

Comportamiento de flags:

Invocación	System Prompt	Permisos
kilo run "x" --auto	Fuentes A + B + C idéntico	Auto-approve todo
kilo run "x"	Fuentes A + B + C idéntico	Prompt por permiso según config
kilo run "x" --dir /path	Resuelve Fuente B contra /path	Según flag --auto

--auto NO cambia el system prompt. Solo activa auto-approval de permisos.

Verificación indirecta del system prompt

Kilo NO expone el system prompt completo en logs. La única forma de verificarlo es inferir de las tool calls que ejecuta. Si el agente lee REPOMAP.md primero y llama a hindsight-selfhosted_recall con los parámetros correctos, las reglas se cargaron bien. Si no, falta la instrucción correspondiente en Fuente B o C.

Pitfalls

• Archivos instructions faltantes se skipean en silencio: Si un archivo listado en el array instructions de kilo.jsonc no existe en el filesystem, Kilo NO muestra warning ni error. Simplemente no se inyecta. Esto es peligroso porque el operador cree que ciertas reglas se están aplicando cuando no. Verificar siempre que los archivos referenciados existan contra el --dir usado. La ausencia se detecta indirectamente: si el agente Kilo no ejecuta las tool calls esperadas (ej: no lee REPOMAP.md al inicio), una instrucción se perdió.
• Bash quoting en prompts largos: Si el prompt contiene backticks (), comillas simples ('), o caracteres especiales, kilo run 'prompt'puede fallar con errores de sintaxis bash. Preferir escribir el prompt en un archivo temporal y pasarlo con--file prompt.txt. Alternativa: usar export OPENC...E_API_KEYen unset -a && source && set +a` compuesto.
• PREAMBLE OBLIGATORIO OLVIDADO: Cada invocación a Kilo DEBE empezar con la instrucción permanente sobre .agents/ y recall/retain. Si Kilo no sabe que debe seguir .agents/, las reglas de kairos no se aplican y el output puede ser inconsistente.
• Timeout vs error: Exit code 124 = time-out (dividir tarea en subtareas más pequeñas). Exit code 1 = error real (revisar API key, sintaxis del prompt, .agents/).
• set -a obligatorio: Sin set -a antes de source .env, las variables de entorno no llegan a procesos hijo (Kilo, Python) y fallan con 401 o "Missing API key".
• Non-interactive: NO usar kilo run con pty=true. --auto es suficiente. No hay TUI que necesite pty.
• Composio REMOTE_WORKBENCH no tiene acceso al filesystem local: El sandbox del workbench NO puede leer archivos del VPS. Soluciones: Google Drive (subir directo), GitHub Releases (gh release create + URL pública), Base64 inline solo para < 50KB.

Prompts Complejos con Kilo

Cuando el prompt contiene caracteres especiales (backticks, comillas, $, saltos de línea), kilo run 'prompt' falla con errores de sintaxis bash. Dos estrategias:

Estrategia A (Recomendada): Escribir el prompt en un archivo y pasarlo con --file:

cat > /tmp/kilo-prompt.txt << 'EOF'
INSTRUCCIÓN PERMANENTE: Sigue .agents/ y reglas kairos.
Usa recall/retain en Hindsight con bank_id del repo activo.

[TAREA con carácteres especiales: `backticks`, $variables, "comillas"]
EOF
kilo run --file /tmp/kilo-prompt.txt --auto

Estrategia B: Prompt inline pero con variables de entorno exportadas antes:

set -a && source /home/opc/.hermes/.env && set +a && \
  kilo run 'tarea simple sin caracteres especiales' --auto

Monitoreo de Kilo en Background

⚠️ REGLA ABSOLUTA 1: El usuario exige updates CADA 3 MINUTOS durante ejecuciones largas. Textual: "necesito que me avises cada tres minutos qué es lo que está haciendo Kilo y necesito saber inmediatamente si es que ocurre algún problema o si es que se detiene abruptamente el proceso. Es inaceptable que no hables durante el proceso."

⚠️ REGLA ABSOLUTA 2: NUNCA poner timeout a Kilo CLI. Kilo CLI ejecuta workflows multi-step que pueden tomar 5+ minutos. Usar SIEMPRE terminal(background=true, notify_on_complete=true, timeout=600). Foreground timeout menor a 600 mata el proceso y deja el workflow incompleto. Esto aplica a TODOS los perfiles, sin excepción.

Esto es OBLIGATORIO, no opcional. Si han pasado 3 minutos desde tu último update y la tarea sigue corriendo, manda un update aunque sea para decir que no hay cambios.

Cuando Kilo corre en background (especialmente para tareas largas como análisis multi-fase):

1. Lanzar con notify_on_complete: terminal(background=true, notify_on_complete=true) para saber exactamente cuándo termina.
2. Update IMMEDIATO al lanzar: Apenas lanzas Kilo, di "Kilo lanzado (PID XXXX) para [tarea]."
3. Estructura de updates CADA 3 MINUTOS: "Update N (~X min desde inicio) — Kilo lleva Ns ejecutándose. [qué está haciendo, qué fase/falta, qué señales de progreso]. Próximo update en 3 min."
4. Verificar archivos de salida periódicamente: Si Kilo debe escribir archivos como deliverable, revisa ls -la de los directorios de salida entre polls.
5. Alertar inmediatamente si el proceso muere: Si el proceso ya no está (PID gone), avisar al usuario de inmediato con el último output disponible.
6. Si hay output parcial: Aunque Kilo no haya terminado, si produce stdout temprano, reportalo al usuario como señal de progreso.
7. Si Kilo se traba/atasca: No esperes a que termine. Detecta que el preview no cambia por >30s, mata el proceso, y escala al usuario con el diagnóstico. Relanza con un approach diferente si aplica.

Multi-Phase Analysis Pattern

Para tareas complejas de análisis que requieren múltiples fases (ej: leer informe → sintetizar causas raíz → contrastar contra documentación → generar diagnóstico → generar PDF):

Estructura del prompt:

INSTRUCCIÓN PERMANENTE: Sigue .agents/ y reglas kairos.
Usa recall/retain en Hindsight con bank_id del repo activo.

## MISIÓN: [Nombre del análisis]

Tienes N fases que ejecutar SECUENCIALMENTE. Cada fase produce un archivo markdown.

### INSUMOS:
- Ruta al archivo 1
- Ruta a la documentación

### FASE 1: [nombre]
Instrucciones específicas para la fase 1.
Escribe el resultado en: /path/to/output-1.md

### FASE 2: [nombre]
Instrucciones específicas para la fase 2.
Escribe el resultado en: /path/to/output-2.md

### REPORTE FINAL
Al terminar todas las fases, imprime en stdout:
1. Ruta de cada archivo generado
2. Métricas clave (hallazgos, discrepancias, etc.)
3. Resumen de una línea

Beneficios:

• Kilo maneja la secuencia sin intervención de Hermes
• Cada fase produce un artifact tangible
• El stdout final da las métricas para reportar al usuario
• Se puede monitorear progreso verificando la existencia de cada archivo de salida

Cuándo usarlo:

• Análisis forense post-incidente
• Auditorías multi-documento
• Investigaciones que requieren síntesis + contraste + recomendaciones
• Cualquier tarea donde el resultado sea un conjunto de documentos relacionados

Flags Importantes

Flag	Propósito
--auto	Modo autónomo — no requiere intervención
--continue	Continuar sesión anterior
--file <path>	Pasar archivo(s) como contexto

Exit codes: 0 = éxito, 124 = time-out (dividir tarea), 1 = error.

Integración con Toolset

• Los cambios de infraestructura (docker-compose, deploy.sh) se versionan en kirlts/toolset/infrastructure/
• Las skills de Hermes se versionan en toolset/infrastructure/hermes/skills/
• El CI/CD es el único mecanismo para cambios de infraestructura (INFRA-01)
• Los nuevos servicios se agregan al docker-compose.yml canónico de toolset