karajan-code 1.36.1 → 1.38.0

package/docs/README.es.md

@@ -1,168 +1,101 @@
 <p align="center">
-  <img src="karajan-code-logo-small.png" alt="Karajan Code" width="200">
+  <img src="karajan-code-logo-small.png" alt="Karajan Code" width="180">
 </p>
 
 <h1 align="center">Karajan Code</h1>
 
 <p align="center">
-  Orquestador local multi-agente con TDD, SonarQube y revision de codigo automatizada.
+  Orquestador local multi-agente. TDD-first, basado en MCP, JavaScript vanilla.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
 </p>
 
 <p align="center">
-  <a href="../README.md">Read in English</a>
+  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a>
 </p>
 
 ---
 
-## Que es Karajan Code?
-
-Karajan Code (`kj`) orquesta multiples agentes de IA a traves de un pipeline automatizado: generacion de codigo, analisis estatico, revision de codigo, testing y auditorias de seguridad — todo en un solo comando.
-
-En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encadena agentes con quality gates. El coder escribe codigo, SonarQube lo analiza, el reviewer lo revisa, y si hay problemas, el coder recibe otra oportunidad. Este bucle se repite hasta que el codigo es aprobado o se alcanza el limite de iteraciones.
-
-**Caracteristicas principales:**
-- **Pipeline multi-agente** con 11 roles configurables
-- **5 agentes de IA soportados**: Claude, Codex, Gemini, Aider, OpenCode
-- **Servidor MCP** con 20 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
-- **Bootstrap obligatorio** — valida prerequisitos del entorno (git, remote, config, agentes, SonarQube) antes de cada ejecucion. Si algo falta, para con instrucciones claras
-- **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
-- **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
-- **Perfiles de revision** — standard, strict, relaxed, paranoid
-- **Tracking de presupuesto** — monitorizacion de tokens y costes por sesion con `--trace`
-- **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
-- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast y limpieza automatica de sesiones expiradas
-- **Sistema de plugins** — extiende con agentes custom via `.karajan/plugins/`
-- **Checkpoints interactivos** — en lugar de matar tareas largas, pausa cada 5 minutos con un informe de progreso y te deja decidir: continuar, parar o ajustar el tiempo
-- **Descomposicion de tareas** — triage detecta cuando una tarea debe dividirse y recomienda subtareas; con integracion Planning Game, crea cards vinculadas con bloqueo secuencial
-- **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
-- **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
-- **Guardarrailes de observabilidad del planner** — telemetria continua de heartbeat/stall, proteccion configurable por silencio maximo (`session.max_agent_silence_minutes`) y limite duro de ejecucion (`session.max_planner_minutes`) para evitar bloqueos prolongados en `kj_plan`/planner
-- **Standby por rate-limit** — cuando un agente alcanza limites de uso, Karajan parsea el tiempo de espera, espera con backoff exponencial y reanuda automaticamente en vez de fallar
-- **Preflight handshake** — `kj_preflight` requiere confirmacion humana de la configuracion de agentes antes de ejecutar, previniendo que la IA cambie asignaciones silenciosamente
-- **Config de 3 niveles** — sesion > proyecto > global con scoping de `kj_agents`
-- **Mediacion inteligente del reviewer** — el scope filter difiere automaticamente issues del reviewer fuera de scope (ficheros no presentes en el diff) como deuda tecnica rastreada en vez de bloquear; Solomon media reviews estancados; el contexto diferido se inyecta en el prompt del coder
-- **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
-
-> **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
-
-## Requisitos
-
-- **Node.js** >= 18
-- **Docker** — necesario para el analisis estatico con SonarQube. Si no tienes Docker o no necesitas SonarQube, desactivalo con `--no-sonar` o `sonarqube.enabled: false` en la config
-- Al menos un agente de IA instalado: Claude, Codex, Gemini o Aider
-
-## Pipeline
+Tu describes lo que quieres construir. Karajan orquesta multiples agentes de IA para planificarlo, implementarlo, testearlo, revisarlo con SonarQube e iterar. Sin que tengas que supervisar cada paso.
 
-```
-triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar? ─> reviewer ─> tester? ─> security? ─> commiter?
-```
+## Que es Karajan?
 
-| Rol | Descripcion | Por defecto |
-|-----|-------------|-------------|
-| **triage** | Director de pipeline — analiza la complejidad y activa roles dinamicamente | **On** |
-| **researcher** | Investiga el contexto del codebase antes de planificar | Off |
-| **planner** | Genera planes de implementacion estructurados | Off |
-| **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre activo** |
-| **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
-| **sonar** | Ejecuta analisis estatico SonarQube y quality gates | On (si configurado) |
-| **reviewer** | Revision de codigo con perfiles de exigencia configurables | **Siempre activo** |
-| **tester** | Quality gate de tests y verificacion de cobertura | **On** |
-| **security** | Auditoria de seguridad OWASP | **On** |
-| **solomon** | Supervisor de sesion — monitoriza salud de iteraciones con 5 reglas (incl. reviewer overreach), media reviews estancados, escala ante anomalias | **On** |
-| **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
+Karajan es un orquestador de codigo local. Corre en tu maquina, usa tus proveedores de IA existentes (Claude, Codex, Gemini, Aider, OpenCode) y coordina un pipeline de agentes especializados que trabajan juntos en tu codigo.
 
-Los roles marcados con `?` son opcionales y se pueden activar por ejecucion o via config.
+No es un servicio en la nube. No es una extension de VS Code. Es una herramienta que instalas una vez y usas desde la terminal o como servidor MCP dentro de tu agente de IA.
 
-## Instalacion
+El nombre viene de Herbert von Karajan, el director de orquesta que creia que las mejores orquestas estan formadas por grandes musicos independientes que saben exactamente cuando tocar y cuando escuchar. La misma idea, aplicada a agentes de IA.
 
-### Desde npm (recomendado)
+## Por que no usar solo Claude Code?
 
-```bash
-npm install -g karajan-code
-kj init
-```
-
-### Desde codigo fuente
-
-```bash
-git clone https://github.com/manufosela/karajan-code.git
-cd karajan-code
-./scripts/install.sh
-```
+Claude Code es excelente. Usalo para codificacion interactiva basada en sesiones.
 
-### Setup no interactivo (CI/automatizacion)
+Usa Karajan cuando quieras:
 
-```bash
-./scripts/install.sh \
-  --non-interactive \
-  --kj-home /ruta/a/.karajan \
-  --sonar-host http://localhost:9000 \
-  --sonar-token "$KJ_SONAR_TOKEN" \
-  --coder claude \
-  --reviewer codex \
-  --run-doctor true
-```
+- **TDD por defecto.** Los tests se escriben antes de la implementacion, no despues
+- **Integracion con SonarQube.** Quality gates como parte del flujo, no como algo secundario
+- **Solomon como jefe del pipeline.** Cada rechazo del reviewer es evaluado por un supervisor que decide si es valido o solo ruido de estilo
+- **Enrutamiento multi-proveedor.** Claude como coder, Codex como reviewer, o cualquier combinacion
+- **Operacion zero-config.** Auto-detecta frameworks de test, arranca SonarQube, simplifica el pipeline para tareas triviales
+- **Arquitectura de roles composable.** Comportamientos de agente definidos como ficheros markdown que viajan con tu proyecto
+- **Local-first.** Tu codigo, tus claves, tu maquina. Ningun dato sale salvo que tu lo digas
+- **Zero costes de API.** Karajan usa CLIs de agentes de IA (Claude Code, Codex, Gemini CLI), no APIs. Pagas tu suscripcion existente (Claude Pro, ChatGPT Plus), no tarifas por token
 
-### Setup multi-instancia
+Si Claude Code es un programador de pares inteligente, Karajan es el pipeline CI/CD para desarrollo asistido por IA. Funcionan genial juntos: Karajan esta disenado para usarse como servidor MCP dentro de Claude Code.
 
-Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-two-instances.md`](install-two-instances.md)
+## Instalacion
 
 ```bash
-./scripts/setup-multi-instance.sh
+npm install -g karajan-code
 ```
 
-## Agentes soportados
-
-| Agente | CLI | Instalacion |
-|--------|-----|-------------|
-| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
-| **Codex** | `codex` | `npm install -g @openai/codex` |
-| **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
-
-`kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
+Eso es todo. No requiere Docker (SonarQube usa Docker, pero Karajan lo gestiona automaticamente). Sin ficheros de configuracion que copiar. `kj init` auto-detecta tus agentes instalados.
 
 ## Tres formas de usar Karajan
 
 Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
 
-### 1. CLI — Directamente desde terminal
+### 1. CLI: directamente desde terminal
+
+Ejecuta Karajan directamente. Ves la salida completa del pipeline en tiempo real.
 
 ```bash
-kj run "Implementar autenticacion de usuario con JWT"
-kj code "Anadir validacion de inputs al formulario de registro"
-kj review "Revisar los cambios de autenticacion"
-kj plan "Refactorizar la capa de base de datos"
+kj run "Crea una utilidad que valide numeros de DNI español, con tests"
+kj code "Añade validacion de inputs al formulario de registro"     # Solo coder
+kj review "Revisa los cambios de autenticacion"                     # Revisar diff actual
+kj audit "Analisis completo de salud de este codebase"              # Auditoria solo-lectura
+kj plan "Refactorizar la capa de base de datos"                     # Planificar sin codificar
 ```
 
-### 2. MCP — Dentro de tu agente de IA
+### 2. MCP: dentro de tu agente de IA
 
-El caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. El agente tiene acceso a 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y delega el trabajo pesado al pipeline de Karajan.
+Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. Le pides algo a tu agente de IA y el delega el trabajo pesado al pipeline de Karajan.
 
 ```
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
+El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y las usa segun necesite.
+
 **El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
 
-### 3. kj-tail — Monitorizar desde otro terminal
+### 3. kj-tail: monitorizar desde otro terminal
 
-**La herramienta companera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
+**La herramienta compañera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
 
 ```bash
 kj-tail
 ```
 
-Veras la salida del pipeline en vivo — etapas, resultados, iteraciones, errores — tal como ocurren.
+Veras la salida del pipeline en vivo (etapas, resultados, iteraciones, errores) tal como ocurren. La misma vista que ejecutar `kj run` directamente.
 
-```bash
+```
 kj-tail                  # Seguir pipeline en tiempo real (por defecto)
 kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
 kj-tail -t               # Mostrar timestamps
@@ -185,7 +118,7 @@ kj-tail --help           # Todas las opciones
 │    prioritaria            │    │  ├─ 🔬 Researcher ✅      │
 │                           │    │  ├─ 🧠 Planner ✅         │
 │  (Claude llama a kj_run   │    │  ├─ 🔨 Coder ✅           │
-│   via MCP — solo ves      │    │  ├─ 🔍 Sonar: OK         │
+│   via MCP, solo ves       │    │  ├─ 🔍 Sonar: OK         │
 │   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
 │                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
 │                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
@@ -195,144 +128,104 @@ kj-tail --help           # Todas las opciones
 └──────────────────────────┘    └──────────────────────────┘
 ```
 
-**Ejemplo con pipeline completo** — tarea compleja con todos los roles:
+[**Ver la demo completa del pipeline**](https://karajancode.com#demo): triage, arquitectura, TDD, SonarQube, code review, arbitraje de Solomon, auditoria de seguridad.
+
+## El pipeline
 
 ```
-┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
-│                                                                              │
-│  $ claude                                                                    │
-│                                                                              │
-│  > Construye una API REST para un sistema de reservas. Requisitos:           │
-│  > - Express + TypeScript con validacion Zod en cada endpoint                │
-│  > - Endpoints: POST /bookings, GET /bookings/:id,                           │
-│  >   PATCH /bookings/:id/cancel                                              │
-│  > - Una reserva tiene: id, guestName, roomType (standard|suite|penthouse),  │
-│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
-│  > - Validar: checkOut posterior a checkIn, sin fechas pasadas,              │
-│  >   roomType debe ser un valor valido del enum                              │
-│  > - Cancelar devuelve 409 si ya esta cancelada                              │
-│  > - Usa TDD. Ejecutalo con Karajan con architect y planner activos,         │
-│  >   modo paranoid. Coder claude, reviewer codex.                            │
-│                                                                              │
-│  Claude llama a kj_run via MCP con:                                          │
-│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-
-┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
-│                                                                              │
-│  kj-tail v1.36.1 — .kj/run.log                                              │
-│                                                                              │
-│  ├─ 📋 Triage: medium (sw) — activando researcher, architect, planner        │
-│  ├─ ⚙️ Preflight passed — all checks OK                                     │
-│  ├─ 🔬 Researcher: 8 ficheros, 3 patrones, 5 restricciones                  │
-│  ├─ 🏗️ Architect: diseno 3 capas (routes → service → validators)            │
-│  ├─ 🧠 Planner: 6 pasos — tests primero, luego rutas, servicio, validadores │
-│  │                                                                           │
-│  ▶ Iteracion 1/5                                                             │
-│  ├─ 🔨 Coder (claude): 3 endpoints + 18 tests                               │
-│  ├─ 📋 TDD: PASS (3 src, 2 test)                                            │
-│  ├─ 🔍 Sonar: Quality gate OK                                               │
-│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
-│  │   "Falta 404 para GET booking inexistente"                                │
-│  │   "Endpoint cancel sin test de idempotencia"                              │
-│  ├─ ⚖️ Solomon: approve_with_conditions (2 condiciones)                     │
-│  │   "Anadir respuesta 404 y test para GET /bookings/:id con id desconocido" │
-│  │   "Anadir test: cancelar reserva ya cancelada devuelve 409, no 500"       │
-│  │                                                                           │
-│  ▶ Iteracion 2/5                                                             │
-│  ├─ 🔨 Coder (claude): corregido — 22 tests                                 │
-│  ├─ 📋 TDD: PASS                                                            │
-│  ├─ 🔍 Sonar: OK                                                            │
-│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
-│  ├─ 🧪 Tester: passed — cobertura 94%, 22 tests                             │
-│  ├─ 🔒 Security: passed — 0 criticos, 1 bajo (helmet recomendado)           │
-│  ├─ 📊 Audit: CERTIFIED (3 advertencias)                                    │
-│  │                                                                           │
-│  🏁 Resultado: APPROVED                                                      │
-│     🔬 Investigacion: 8 ficheros, 3 patrones                                 │
-│     🗺 Plan: 6 pasos (tests primero)                                         │
-│     🧪 Cobertura: 94%, 22 tests                                              │
-│     🔒 Seguridad: OK                                                         │
-│     🔍 Sonar: OK                                                             │
-│     💰 Presupuesto: $0.42 (claude: $0.38, codex: $0.04)                      │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
+hu-reviewer? → triage → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
 ```
 
-## Comandos CLI
-
-Consulta la [documentacion completa de comandos](../README.md#cli-commands) en el README principal (ingles). Resumen:
-
-| Comando | Descripcion |
-|---------|-------------|
-| `kj init` | Wizard interactivo de configuracion |
-| `kj run <task>` | Pipeline completo: coder → sonar → reviewer |
-| `kj code <task>` | Solo coder (sin revision) |
-| `kj review <task>` | Solo reviewer (sobre diff actual) |
-| `kj plan <task>` | Generar plan de implementacion |
-| `kj scan` | Ejecutar analisis SonarQube |
-| `kj doctor` | Verificar entorno (git, Docker, agentes, SonarQube) |
-| `kj config` | Mostrar configuracion actual |
-| `kj report` | Informes de sesion con tracking de presupuesto |
-| `kj resume <id>` | Reanudar sesion pausada |
-| `kj roles` | Inspeccionar roles y templates del pipeline |
-| `kj sonar` | Gestionar contenedor Docker de SonarQube |
-
-## Servidor MCP
-
-Karajan Code expone un servidor MCP para integracion con cualquier host compatible (Claude, Codex, agentes custom).
-
-Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en las configs de Claude y Codex. Config manual:
-
-```json
-{
-  "mcpServers": {
-    "karajan-mcp": {
-      "command": "karajan-mcp"
-    }
-  }
-}
+**15 roles**, cada uno ejecutado por el agente de IA que elijas:
+
+| Rol | Que hace | Por defecto |
+|-----|----------|-------------|
+| **hu-reviewer** | Certifica historias de usuario antes de codificar (6 dimensiones, 7 antipatrones) | Off |
+| **triage** | Clasifica complejidad, activa roles, auto-simplifica para tareas triviales | **On** |
+| **discover** | Detecta huecos en requisitos (Mom Test, Wendel, JTBD) | Off |
+| **architect** | Disena la arquitectura de la solucion antes de planificar | Off |
+| **planner** | Genera planes de implementacion estructurados | Off |
+| **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre on** |
+| **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
+| **sonar** | Analisis estatico SonarQube con quality gate enforcement | On (auto-gestionado) |
+| **impeccable** | Auditoria UI/UX para tareas frontend (a11y, rendimiento, theming) | Auto (frontend) |
+| **reviewer** | Code review con perfiles de exigencia configurables | **Siempre on** |
+| **tester** | Quality gate de tests y verificacion de cobertura | **On** |
+| **security** | Auditoria de seguridad OWASP | **On** |
+| **solomon** | Jefe del pipeline: evalua cada rechazo, anula bloqueos solo de estilo | **On** |
+| **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
+| **audit** | Analisis de salud del codebase solo-lectura (5 dimensiones, scores A-F) | Standalone |
+
+## 5 agentes de IA soportados
+
+| Agente | CLI | Instalacion |
+|--------|-----|-------------|
+| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
+| **Codex** | `codex` | `npm install -g @openai/codex` |
+| **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
+| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
+| **OpenCode** | `opencode` | Ver [OpenCode docs](https://github.com/nicepkg/opencode) |
+
+Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
+
+## Servidor MCP (20 herramientas)
+
+Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
+
+```bash
+# Claude: anadir a ~/.claude.json → "mcpServers":
+# { "karajan-mcp": { "command": "karajan-mcp" } }
+
+# Codex: anadir a ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
+# command = "karajan-mcp"
 ```
 
-### Herramientas MCP
+**20 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`.
 
-| Herramienta | Descripcion |
-|-------------|-------------|
-| `kj_init` | Inicializar config y SonarQube |
-| `kj_doctor` | Verificar dependencias del sistema |
-| `kj_config` | Mostrar configuracion |
-| `kj_scan` | Ejecutar analisis SonarQube |
-| `kj_run` | Ejecutar pipeline completo (con notificaciones de progreso en tiempo real) |
-| `kj_resume` | Reanudar sesion pausada |
-| `kj_report` | Leer informes de sesion (soporta `--trace`) |
-| `kj_roles` | Listar roles o mostrar templates |
-| `kj_code` | Modo solo coder |
-| `kj_review` | Modo solo reviewer |
-| `kj_plan` | Generar plan de implementacion con telemetria heartbeat/stall y diagnostico mas claro |
+Usa `kj-tail` en un terminal separado para ver lo que el pipeline esta haciendo en tiempo real (ver [Tres formas de usar Karajan](#tres-formas-de-usar-karajan)).
 
-### MCPs complementarios recomendados
+## La arquitectura de roles
 
-Karajan Code funciona perfectamente solo, pero combinarlo con estos servidores MCP le da a tu agente un entorno de desarrollo completo:
+Cada rol en Karajan esta definido por un fichero markdown: un documento plano que describe como debe comportarse el agente, que revisar y como es un buen output.
 
-| MCP | Para que | Caso de uso |
-|-----|----------|-------------|
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Puente MCP para [Planning Game](https://github.com/AgenteIA-Geniova/planning-game), gestor agil open-source (tareas, sprints, estimacion, XP). Solo necesario si usas Planning Game | `kj_run` con `--pg-task` obtiene contexto completo de la tarea y actualiza el estado al completar |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Crear PRs, gestionar issues, leer repos desde el agente | Combinar con `--auto-push` para flujo completo: codigo → revision → push → PR |
-| [**Serena**](https://github.com/oramasearch/serena) | Navegacion a nivel de simbolo (find references, go-to-definition) para proyectos JS/TS | Activar con `--enable-serena` para inyectar contexto de simbolos en prompts de coder/reviewer |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Automatizacion de navegador, screenshots, inspeccion de consola/red | Verificar cambios de UI visualmente tras modificar codigo frontend |
+```
+.karajan/roles/         # Overrides de proyecto (opcional)
+~/.karajan/roles/       # Overrides globales (opcional)
+templates/roles/        # Defaults built-in (incluidos en el paquete)
+```
+
+Puedes sobreescribir cualquier rol built-in o crear nuevos. Sin codigo. Los agentes leen los ficheros de rol y adaptan su comportamiento. Codifica las convenciones de tu equipo, reglas de dominio y estandares de calidad, y cada ejecucion de Karajan los aplica automaticamente.
 
-## Templates de roles
+Usa `kj roles show <rol>` para inspeccionar cualquier template.
 
-Cada rol tiene un template `.md` con instrucciones que el agente de IA sigue. Los templates se resuelven en orden de prioridad:
+## Zero-config por diseño
 
-1. **Override de proyecto**: `.karajan/roles/<rol>.md` (en la raiz del proyecto)
-2. **Override de usuario**: `$KJ_HOME/roles/<rol>.md`
-3. **Built-in**: `templates/roles/<rol>.md` (incluido en el paquete)
+Karajan auto-detecta y auto-configura todo lo que puede:
 
-Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override de proyecto para personalizar el comportamiento por proyecto.
+- **TDD**: Detecta framework de tests (vitest, jest, mocha) y auto-activa TDD
+- **Bootstrap gate**: Valida todos los prerequisitos (repo git, remote, config, agentes, SonarQube) antes de ejecutar. Falla con instrucciones claras, nunca degrada silenciosamente
+- **Injection guard**: Escanea diffs en busca de prompt injection antes del review de IA. Detecta directivas de override, Unicode invisible, payloads en comentarios sobredimensionados. Tambien como GitHub Action en cada PR
+- **SonarQube**: Auto-arranca contenedor Docker, genera config si falta
+- **Complejidad del pipeline**: Triage clasifica la tarea, las triviales saltan el loop del reviewer
+- **Caidas de proveedor**: Reintentos en 500/502/503/504 con backoff (igual que rate limits)
+- **Cobertura**: Fallos de quality gate solo por cobertura se tratan como advisory
 
-**Variantes de revision**: `reviewer-strict`, `reviewer-relaxed`, `reviewer-paranoid` — seleccionables via flag `--mode` o config `review_mode`.
+Sin configuracion por proyecto requerida. Si quieres personalizar, la config se apila: sesion > proyecto > global.
+
+## Por qué JavaScript vanilla?
+
+No es nostalgia ni cabezonería. Es que llevo usando JavaScript desde 1997, cuando Brendan Eich lo creó en una semana y nos cambió la vida a los que hacíamos webs. Conozco sus tripas, sus bugs, sus rarezas. Y sé que quien conoce JS de verdad convierte esos bugs en features. TypeScript existe para que developers acostumbrados a lenguajes fuertemente tipados no entren en pánico al ver JS. Respeto eso. Pero yo no lo necesito. Los tests son mi seguridad de tipos. JSDoc y un buen IDE son mi intellisense. Y no tener un compilador entre el código y yo es lo que me permite moverme a 57 releases en 45 días sin miedo.
+
+[Por qué JavaScript vanilla: la versión larga](why-vanilla-js.md)
+
+## Compañeros recomendados
+
+| Herramienta | Por que |
+|-------------|---------|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Reduce consumo de tokens 60-90% en salidas de comandos Bash |
+| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Gestion agil de proyectos (tareas, sprints, estimacion), nativo XP |
+| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Crear PRs, gestionar issues directamente desde el agente |
+| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verificar cambios de UI visualmente tras modificar frontend |
 
 ## Contribuir
 
@@ -340,19 +233,20 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 1040+ tests con Vitest
-npm run test:watch    # Modo watch
+npm test              # Ejecutar 2044 tests con Vitest
 npm run validate      # Lint + test
 ```
 
-- Tests: [Vitest](https://vitest.dev/)
-- Commits: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`)
-- PRs: un solo proposito por PR, < 300 lineas cambiadas
+Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [abre un issue](https://github.com/manufosela/karajan-code/issues). Es la contribucion mas util en esta fase.
 
 ## Enlaces
 
 - [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
+- [Documentacion completa](https://karajancode.com/docs/)
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
 - [Licencia (AGPL-3.0)](../LICENSE)
-- [Issues](https://github.com/manufosela/karajan-code/issues)
+
+---
+
+Construido por [@manufosela](https://github.com/manufosela). Head of Engineering en Geniova Technologies, co-organizador de NodeJS Madrid, autor de [Liderazgo Afectivo](https://www.amazon.es/dp/B0D7F4C8KC). 90+ paquetes npm publicados.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.36.1",
+  "version": "1.38.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/agents/resolve-bin.js

@@ -5,13 +5,21 @@ import { execFileSync } from "node:child_process";
 
 const cache = new Map();
 
-const SEARCH_DIRS = [
-  "/opt/node/bin",
-  path.join(os.homedir(), ".npm-global", "bin"),
-  "/usr/local/bin",
-  path.join(os.homedir(), ".local", "bin"),
-  path.join(os.homedir(), ".opencode", "bin"),
-];
+const isWin = process.platform === "win32";
+
+const SEARCH_DIRS = isWin
+  ? [
+    path.join(os.homedir(), "AppData", "Roaming", "npm"),
+    path.join(os.homedir(), "AppData", "Local", "npm"),
+    path.join(os.homedir(), ".opencode", "bin"),
+  ]
+  : [
+    "/opt/node/bin",
+    path.join(os.homedir(), ".npm-global", "bin"),
+    "/usr/local/bin",
+    path.join(os.homedir(), ".local", "bin"),
+    path.join(os.homedir(), ".opencode", "bin"),
+  ];
 
 function getNvmDirs() {
   const nvmDir = process.env.NVM_DIR || path.join(os.homedir(), ".nvm");
@@ -26,13 +34,14 @@ function getNvmDirs() {
 export function resolveBin(name) {
   if (cache.has(name)) return cache.get(name);
 
-  // 1. Try system PATH via `which`
+  // 1. Try system PATH via `which` (Unix) or `where` (Windows)
   try {
-    const resolved = execFileSync("which", [name], {
+    const whichCmd = isWin ? "where" : "which";
+    const resolved = execFileSync(whichCmd, [name], {
       encoding: "utf8",
       timeout: 3000,
       stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
+    }).trim().split(/\r?\n/)[0];
     if (resolved) {
       cache.set(name, resolved);
       return resolved;
@@ -43,11 +52,14 @@ export function resolveBin(name) {
 
   // 2. Search known directories
   const dirs = [...SEARCH_DIRS, ...getNvmDirs()];
+  const extensions = isWin ? ["", ".cmd", ".exe", ".bat"] : [""];
   for (const dir of dirs) {
-    const candidate = path.join(dir, name);
-    if (existsSync(candidate)) {
-      cache.set(name, candidate);
-      return candidate;
+    for (const ext of extensions) {
+      const candidate = path.join(dir, name + ext);
+      if (existsSync(candidate)) {
+        cache.set(name, candidate);
+        return candidate;
+      }
     }
   }
 

package/src/hu/store.js

@@ -4,6 +4,21 @@ import { getKarajanHome } from "../utils/paths.js";
 
 // FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
 
+/**
+ * Valid HU story status values.
+ * @type {Readonly<{PENDING: "pending", CODING: "coding", REVIEWING: "reviewing", DONE: "done", FAILED: "failed", BLOCKED: "blocked", CERTIFIED: "certified", NEEDS_CONTEXT: "needs_context"}>}
+ */
+export const HU_STATUS = Object.freeze({
+  PENDING: "pending",
+  CODING: "coding",
+  REVIEWING: "reviewing",
+  DONE: "done",
+  FAILED: "failed",
+  BLOCKED: "blocked",
+  CERTIFIED: "certified",
+  NEEDS_CONTEXT: "needs_context"
+});
+
 /** @returns {string} Path to the hu-stories directory (evaluated at call time). */
 function getHuDir() {
   return path.join(getKarajanHome(), "hu-stories");
@@ -151,3 +166,45 @@ export function answerContextRequest(batch, storyId, answer) {
   story.updated_at = new Date().toISOString();
   return story;
 }
+
+/**
+ * Create a lightweight history record for a pipeline run.
+ * Stores a minimal single-HU batch in the same hu-stories directory
+ * so the HU Board can pick it up alongside full batches.
+ * @param {string} sessionId - The session identifier.
+ * @param {{task: string, result: string, approved: boolean, summary?: string, timestamp?: string}} data
+ * @returns {Promise<object>} The created batch object.
+ */
+export async function createHistoryRecord(sessionId, { task, result, approved, summary, timestamp }) {
+  const ts = timestamp || new Date().toISOString();
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const batch = {
+    session_id: sessionId,
+    created_at: ts,
+    stories: [
+      {
+        id: `HU-hist-${sessionId}`,
+        status: approved ? "certified" : "failed",
+        original: { text: task },
+        blocked_by: [],
+        certified: approved ? { summary: summary || result } : null,
+        quality: null,
+        context_requests: [],
+        created_at: ts,
+        updated_at: ts
+      }
+    ],
+    history: {
+      task,
+      result,
+      approved,
+      summary: summary || null,
+      timestamp: ts
+    }
+  };
+
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+  return batch;
+}