karajan-code 1.37.0 → 1.38.1

package/README.md

@@ -154,7 +154,7 @@ kj-tail --help           # Full options
 
 ┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
 │                                                                              │
-│  kj-tail v1.37.0 — .kj/run.log                                              │
+│  kj-tail v1.38.0 — .kj/run.log                                              │
 │                                                                              │
 │  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
 │  ├─ ⚙️ Preflight passed — all checks OK                                     │
@@ -205,7 +205,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 | Role | What it does | Default |
 |------|-------------|---------|
-| **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Off |
+| **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Auto (medium/complex) |
 | **triage** | Classifies complexity, activates roles, auto-simplifies for trivial tasks | **On** |
 | **discover** | Detects gaps in requirements (Mom Test, Wendel, JTBD) | Off |
 | **architect** | Designs solution architecture before planning | Off |
@@ -274,16 +274,15 @@ Karajan auto-detects and auto-configures everything it can:
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
 - **Coverage**: Coverage-only quality gate failures treated as advisory
+- **HU Manager**: Complex tasks auto-decompose into formal user stories with dependencies. Each HU runs as its own sub-pipeline with state tracking visible in the HU Board
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
 ## Why vanilla JavaScript?
 
-Because it should be.
+Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Brendan Eich created it in a week and changed the lives of everyone building for the web. I know its guts, its bugs, its quirks. And I know that whoever truly understands JS turns those bugs into features. TypeScript exists so that developers used to strongly-typed languages don't panic when they see JS. I respect that. But I don't need it. Tests are my type safety. JSDoc and a good IDE are my intellisense. And not having a compiler between the code and me is what lets me ship 57 releases in 45 days without fear.
 
-Karajan has **2044 tests** across 161 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
-
-This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. 57 releases in 45 days. That velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
+[Why vanilla JavaScript: the long version](docs/why-vanilla-js.md)
 
 ## Recommended companions
 
@@ -300,7 +299,7 @@ This is a deliberate choice, not a limitation. The tests are the type safety. Th
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 2044 tests with Vitest
+npm test              # Run 2093 tests with Vitest
 npm run validate      # Lint + test
 ```
 
@@ -316,4 +315,4 @@ Issues and pull requests welcome. If something doesn't work as documented, [open
 
 ---
 
-Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.amazon.es/dp/B0D7F4C8KC). 90+ npm packages published.
+Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ npm packages published.

package/docs/README.es.md

@@ -1,62 +1,78 @@
 <p align="center">
+<<<<<<< HEAD
   <img src="karajan-code-logo-small.png" alt="Karajan Code" width="200">
+=======
+  <img src="karajan-code-logo-small.png" alt="Karajan Code" width="180">
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </p>
 
 <h1 align="center">Karajan Code</h1>
 
 <p align="center">
+<<<<<<< HEAD
   Orquestador local multi-agente con TDD, SonarQube y revision de codigo automatizada.
+=======
+  Orquestador local multi-agente. TDD-first, basado en MCP, JavaScript vanilla.
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </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>
+<<<<<<< HEAD
+=======
+  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
   <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">
+<<<<<<< HEAD
   <a href="../README.md">Read in English</a>
+=======
+  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a>
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </p>
 
 ---
 
+<<<<<<< HEAD
 ## 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.
+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
-- **Guardia anti-inyeccion.** Escanea diffs antes de pasarlos a la IA: detecta directivas de override, Unicode invisible y payloads ocultos en comentarios. Tambien como GitHub Action en cada PR
-- **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.
+- **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 SonarQube). Si no lo necesitas, desactivalo con `--no-sonar` o `sonarqube.enabled: false`
+- **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
@@ -67,7 +83,7 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 
 | Rol | Descripcion | Por defecto |
 |-----|-------------|-------------|
-| **triage** | Director de pipeline: analiza la complejidad y activa roles dinamicamente | **On** |
+| **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** |
@@ -76,7 +92,7 @@ triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar?
 | **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** |
+| **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 |
 
 Los roles marcados con `?` son opcionales y se pueden activar por ejecucion o via config.
@@ -129,12 +145,49 @@ Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-
 | **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.
+=======
+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.
+
+## Que es Karajan?
+
+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.
+
+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.
+
+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.
+
+## Por que no usar solo Claude Code?
+
+Claude Code es excelente. Usalo para codificacion interactiva basada en sesiones.
+
+Usa Karajan cuando quieras:
+
+- **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
+
+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.
+
+## Instalacion
+
+```bash
+npm install -g karajan-code
+```
+
+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.
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Tres formas de usar Karajan
 
 Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
 
-### 1. CLI: directamente desde terminal
+<<<<<<< HEAD
+### 1. CLI — Directamente desde terminal
 
 ```bash
 kj run "Implementar autenticacion de usuario con JWT"
@@ -143,27 +196,60 @@ kj review "Revisar los cambios de autenticacion"
 kj plan "Refactorizar la capa de base de datos"
 ```
 
-### 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.
+=======
+### 1. CLI: directamente desde terminal
+
+Ejecuta Karajan directamente. Ves la salida completa del pipeline en tiempo real.
+
+```bash
+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
+
+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.
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ```
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
+<<<<<<< HEAD
 **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:
+=======
+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
+
+**La herramienta compañera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ```bash
 kj-tail
 ```
 
-Veras la salida del pipeline en vivo (etapas, resultados, iteraciones, errores) tal como ocurren.
+<<<<<<< HEAD
+Veras la salida del pipeline en vivo — etapas, resultados, iteraciones, errores — tal como ocurren.
 
 ```bash
+=======
+Veras la salida del pipeline en vivo (etapas, resultados, iteraciones, errores) tal como ocurren. La misma vista que ejecutar `kj run` directamente.
+
+```
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 kj-tail                  # Seguir pipeline en tiempo real (por defecto)
 kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
 kj-tail -t               # Mostrar timestamps
@@ -186,7 +272,11 @@ kj-tail --help           # Todas las opciones
 │    prioritaria            │    │  ├─ 🔬 Researcher ✅      │
 │                           │    │  ├─ 🧠 Planner ✅         │
 │  (Claude llama a kj_run   │    │  ├─ 🔨 Coder ✅           │
+<<<<<<< HEAD
+│   via MCP — solo ves      │    │  ├─ 🔍 Sonar: OK         │
+=======
 │   via MCP, solo ves       │    │  ├─ 🔍 Sonar: OK         │
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 │   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
 │                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
 │                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
@@ -196,7 +286,8 @@ kj-tail --help           # Todas las opciones
 └──────────────────────────┘    └──────────────────────────┘
 ```
 
-**Ejemplo con pipeline completo**, tarea compleja con todos los roles:
+<<<<<<< HEAD
+**Ejemplo con pipeline completo** — tarea compleja con todos los roles:
 
 ```
 ┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
@@ -222,7 +313,7 @@ kj-tail --help           # Todas las opciones
 
 ┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
 │                                                                              │
-│  kj-tail v1.37.0 — .kj/run.log                                              │
+│  kj-tail v1.36.1 — .kj/run.log                                              │
 │                                                                              │
 │  ├─ 📋 Triage: medium (sw) — activando researcher, architect, planner        │
 │  ├─ ⚙️ Preflight passed — all checks OK                                     │
@@ -333,7 +424,108 @@ Cada rol tiene un template `.md` con instrucciones que el agente de IA sigue. Lo
 
 Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override de proyecto para personalizar el comportamiento por proyecto.
 
-**Variantes de revision**: `reviewer-strict`, `reviewer-relaxed`, `reviewer-paranoid`, seleccionables via flag `--mode` o config `review_mode`.
+**Variantes de revision**: `reviewer-strict`, `reviewer-relaxed`, `reviewer-paranoid` — seleccionables via flag `--mode` o config `review_mode`.
+=======
+[**Ver la demo completa del pipeline**](https://karajancode.com#demo): triage, arquitectura, TDD, SonarQube, code review, arbitraje de Solomon, auditoria de seguridad.
+
+## El pipeline
+
+```
+hu-reviewer? → triage → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
+```
+
+**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) | Auto (media/compleja) |
+| **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"
+```
+
+**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`.
+
+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)).
+
+## La arquitectura de roles
+
+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.
+
+```
+.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.
+
+Usa `kj roles show <rol>` para inspeccionar cualquier template.
+
+## Zero-config por diseño
+
+Karajan auto-detecta y auto-configura todo lo que puede:
+
+- **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
+- **HU Manager**: Las tareas complejas se descomponen automaticamente en historias de usuario formales con dependencias. Cada HU se ejecuta como su propio sub-pipeline con seguimiento de estado visible en el HU Board
+
+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 |
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Contribuir
 
@@ -341,7 +533,8 @@ 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 2044 tests con Vitest
+<<<<<<< HEAD
+npm test              # Ejecutar 1040+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```
@@ -349,11 +542,29 @@ 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
+=======
+npm test              # Ejecutar 2093 tests con Vitest
+npm run validate      # Lint + test
+```
+
+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.
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Enlaces
 
 - [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
+<<<<<<< HEAD
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
 - [Licencia (AGPL-3.0)](../LICENSE)
 - [Issues](https://github.com/manufosela/karajan-code/issues)
+=======
+- [Documentacion completa](https://karajancode.com/docs/)
+- [Changelog](../CHANGELOG.md)
+- [Politica de seguridad](../SECURITY.md)
+- [Licencia (AGPL-3.0)](../LICENSE)
+
+---
+
+Construido por [@manufosela](https://github.com/manufosela). Head of Engineering en Geniova Technologies, co-organizador de NodeJS Madrid, autor de [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ paquetes npm publicados.
+>>>>>>> 8792e49efcdc75995e024d81339b100c7b253920

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.37.0",
+  "version": "1.38.1",
   "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/commands/code.js

@@ -13,7 +13,9 @@ export async function codeCommand({ task, config, logger }) {
   if (config.coder_rules) {
     try {
       coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* no coder rules file, that's ok */ }
+    } catch {
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
   }
   const prompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);

package/src/commands/init.js

@@ -128,7 +128,7 @@ async function ensureReviewRules(reviewRulesPath, logger) {
     "# Review Rules\n\n- Focus on security, correctness, and test coverage.\n",
     "utf8"
   );
-  logger.info("Created review-rules.md");
+  logger.info("Created .karajan/review-rules.md");
 }
 
 async function ensureCoderRules(coderRulesPath, logger) {
@@ -150,7 +150,7 @@ async function ensureCoderRules(coderRulesPath, logger) {
     ].join("\n");
   }
   await fs.writeFile(coderRulesPath, content, "utf8");
-  logger.info("Created coder-rules.md");
+  logger.info("Created .karajan/coder-rules.md");
 }
 
 async function setupSonarQube(config, logger) {
@@ -271,8 +271,10 @@ export async function initCommand({ logger, flags = {} }) {
   logger.info(`Ensured ${karajanHome} exists`);
 
   const configPath = getConfigPath();
-  const reviewRulesPath = path.resolve(process.cwd(), "review-rules.md");
-  const coderRulesPath = path.resolve(process.cwd(), "coder-rules.md");
+  const karajanDir = path.join(process.cwd(), ".karajan");
+  await ensureDir(karajanDir);
+  const reviewRulesPath = path.resolve(karajanDir, "review-rules.md");
+  const coderRulesPath = path.resolve(karajanDir, "coder-rules.md");
 
   const { config, exists: configExists } = await loadConfig();
   const interactive = flags.noInteractive !== true && isTTY();

package/src/config.js

@@ -39,8 +39,8 @@ const DEFAULTS = {
   review_mode: "standard",
   max_iterations: 5,
   max_budget_usd: null,
-  review_rules: "./review-rules.md",
-  coder_rules: "./coder-rules.md",
+  review_rules: "./.karajan/review-rules.md",
+  coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",
   coder_options: { model: null, auto_approve: true, fallback_coder: null },
   reviewer_options: {