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:

INSTRUCCIÓN PERMANENTE: 
Sigue las reglas de la carpeta .agents/ en todos los repositorios que la contengan, así como Docs/RULES.md.
Usa recall/retain en Hindsight con el bank_id del repo activo (el nombre del repositorio) para contexto y persistencia.

[TAREA ESPECÍFICA]

No es opcional. Aplica a TODA ejecución futura de Kilo.

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 (exactamente el nombre del repo, sin descripciones)
5. Crear skill Hermes para la capacidad permanente
6. Push a GitHub

Estrategia de Delegación

1. Cargar contexto: recall(bank="<repo-name>", 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="<repo-name>", 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
  → "infrastructure/kilo-prompt.md" → /home/opc/personal/infrastructure/kilo-prompt.md
  → ".agents/rules/01-behavior.md"  → /home/opc/personal/.agents/rules/01-behavior.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.

Debugging de System Prompt

Para inspeccionar qué system prompt recibe realmente Kilo:

# Método 1: JSON format captura todas las tool calls
kilo run "." --dir /path --format json 2>&1 | head -5

# Método 2: Print logs muestra inicialización (pero NO el prompt raw)
kilo run "." --dir /path --print-logs 2>&1 | grep -i "prompt\|instruction\|session.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, las reglas se cargaron bien. Si no, falta la instrucción correspondiente en Fuente B o C.

🚨 REGLA CRÍTICA: Diagnóstico de Kilo Hangs

Cuando Kilo CLI se cuelga (>3 min sin tool calls, solo message.part.updated en el log), el problema NO es siempre el tamaño del prompt. Hay DOS causas posibles.

DIAGNÓSTICO PRIMERO, ACCIÓN DESPUÉS. No hacer cambios mientras diagnosticas. Presenta hallazgos al usuario y espera instrucciones antes de actuar.

REVISAR CONFIGURACIÓN ANTES DE CULPAR AL MODELO. Kilo tiene un system prompt pre-inyectado (infrastructure/kilo-system-prompt.md) con instrucciones de recall a Hindsight. Revisa eso antes de asumir que el modelo es el problema.

Causa 1: El recall de Hindsight saturó el contexto

Kilo tiene UNA INSTRUCCIÓN en su system prompt que ordena recuerdos de Hindsight al iniciar:

hindsight-selfhosted_recall(bank=<nombre-del-repo>-profile)

Sin parámetros max_tokens ni budget. Si el banco tiene >100 facts, el recall puede devolver datos masivos (>600KB en el caso del banco toolset con 741 facts).

AMBIGÜEDAD CONOCIDA: El system prompt dice bank=<...>-profile. Pero docs/RULES.md (cargado como instructions file) dice "repo name as bank_id, kebab-case". Son contradictorios. Mientras no se unifiquen, el recall puede apuntar al banco equivocado.

Causa 2: El prompt de Hermes es demasiado grande

Si el prompt que Hermes pasa a Kilo supera ~500 palabras, deepseek-v4-flash se atasca generando texto explicativo sin ejecutar tool calls.

Evidencia empírica: 8+ min de streaming sin tool calls, 359KB de log, cero cambios en git status, cero conexiones de red.

Protocolo de diagnóstico

1. Primeros 30s: git status --porcelain → ¿hay cambios? Si no, no hay tool calls.
2. Primeros 60s: Revisar log de Kilo:
   tail -5 ~/.local/share/kilo/log/$(ls -t ~/.local/share/kilo/log/ | head -1)
   → "message.part.updated" sin otros eventos = modelo atascado generando
   → "command.executed" o "file.watcher.updated" = está trabajando
3. Si >3 min sin tool calls:
   a) Matar proceso (process kill)
   b) Determinar causa:
      - Prompt >500 palabras? → Causa 2
      - Bank target con >100 facts y recall sin max_tokens? → Causa 1
      - ¿Ambas? → Causa combinada
   c) Reportar diagnóstico al usuario. NO relanzar sin autorización.

Reglas post-incidente para delegar a Kilo

1. Prompts SIEMPRE <500 palabras. Si la tarea es compleja, usar patrón script + git.

2. NO usar bash sed para editar GitHub Actions YAML. Los ${{ }} colisionan con anclajes de sed. Usar Python.

3. Señal de alerta temprana: Si git status no muestra cambios tras 30s de ejecución, algo anda mal.

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 inline con $(cat):

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 "$(cat /tmp/kilo-prompt.txt)" --auto

⚠️ NO usar kilo run --file file.txt --auto. El flag --file adjunta archivos como contexto adicional al mensaje, NO como el prompt principal. Sin un positional [message], Kilo falla con "You must provide a message or a command." La forma correcta de pasar un archivo como prompt es kilo run "$(cat file.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