Visión General de la Arquitectura

Karajan Code implementa un patrón de Orquestación de IA basada en Roles. El sistema coordina múltiples agentes de IA a través de un pipeline estructurado donde cada responsabilidad (codificar, revisar, testear, seguridad) es un rol discreto e independientemente configurable.

Principios de Diseño

Roles de agente desacoplados. Cada capacidad IA es un rol separado con sus propias instrucciones, agente y modelo
Ciclo de vida estandarizado. Todos los roles implementan la misma interfaz BaseRole (init, execute, report)
CLI-first. Envuelve CLIs existentes de agentes IA (Claude, Codex, Gemini, Aider, OpenCode) en lugar de llamar APIs directamente
Zero-config. Detecta automáticamente frameworks de test, arranca SonarQube, simplifica el pipeline para tareas triviales. No requiere configuración por proyecto
Quality gates. Análisis estático (SonarQube), revisión de código, TDD obligatorio y escaneo de inyección integrados
Solomon como jefe del pipeline. Cada rechazo del reviewer es evaluado por Solomon, que puede anular bloqueos por estilo y mediar conflictos
Guardia de inyección. Los diffs se escanean en busca de prompt injection antes de llegar al reviewer IA
Bootstrap gate. Todos los prerequisitos se validan antes de que cualquier herramienta se ejecute. Falla con instrucciones de corrección, nunca degrada silenciosamente
Fail-fast con escalado. La detección de repeticiones activa arbitraje Solomon o intervención humana
Persistencia de sesión. Todo el estado se almacena en disco para pausa/reanudación y recuperación ante caídas
Extensible. Agentes custom via plugins, reglas custom via ficheros markdown

Diagrama del Sistema

┌─────────────────────────────────────────────────────────────────┐
│                    CLI / MCP / kj-tail                           │
│              (kj run, kj_run tool, kj-tail)                     │
└──────────────────────┬──────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Bootstrap Gate                                 │
│         (git, remote, config, agents, SonarQube)                 │
└──────────────────────┬───────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                      Orchestrator                                │
│          (pipeline loop, fail-fast, budget, session)             │
│                                                                  │
│  ┌────────────┐ ┌────────┐ ┌────────┐ ┌─────────┐ ┌────────┐   │
│  │HU-Reviewer?│→│ Triage │→│Discover│→│Architect│→│Planner │   │
│  └────────────┘ └────────┘ └────────┘ └─────────┘ └───┬────┘   │
│                                                        │        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │        │
│  │ Commiter │←│  Audit   │←│ Security │←│  Tester  │←─┤        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │        │
│                                                        ▼        │
│                ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│                │ Solomon  │←│ Reviewer │←│  Sonar   │←── Coder  │
│                └────┬─────┘ └──────────┘ └──────────┘           │
│                     │         ▲                                  │
│            override?│    Injection                               │
│             continue│     Guard                                  │
│                     │                                            │
│                approved? ──no──→ loop back to Coder              │
└─────────────────────┬────────────────────────────────────────────┘
                      │
         ┌────────────┼────────────────┐
         ▼            ▼                ▼
  ┌─────────────┐ ┌───────────┐ ┌──────────────┐
  │ Agent Layer │ │  SonarQube │ │ Session Store │
  │ (BaseAgent) │ │  (Docker)  │ │    (disk)     │
  └──────┬──────┘ └───────────┘ └──────────────┘
         │
  ┌──────┴───────────────────────────────────┐
  │ Claude │ Codex │ Gemini │ Aider │ OpenCode │ Plugins
  └──────────────────────────────────────────┘

Estructura de Módulos

src/
├── cli.js                    # CLI entry point (Commander.js)
├── orchestrator.js           # Main pipeline coordinator
├── bootstrap.js              # Bootstrap gate (prerequisite validation)
├── config.js                 # Config loading & validation
├── session-store.js          # Session persistence (create, pause, resume)
├── session-cleanup.js        # Expired session cleanup
├── repeat-detector.js        # Fail-fast: detect repeated issues
├── activity-log.js           # Session activity logging
│
├── orchestrator/             # Pipeline stage implementations
│   ├── pre-loop-stages.js    #   HU-reviewer, triage, discover, researcher, architect, planner
│   ├── iteration-stages.js   #   Coder, refactorer, guards, TDD, sonar, injection guard, reviewer
│   ├── post-loop-stages.js   #   Tester, security, impeccable, audit
│   ├── stages/               #   Stage sub-modules (split from monolithic stage files)
│   │   ├── triage.js         #     Triage stage logic
│   │   ├── research.js       #     Research stage logic
│   │   ├── architect.js      #     Architect stage logic
│   │   ├── planner.js        #     Planner stage logic
│   │   ├── hu-reviewer.js    #     HU reviewer stage logic
│   │   ├── coder.js          #     Coder stage logic
│   │   ├── sonar.js          #     SonarQube stage logic
│   │   └── reviewer.js       #     Reviewer stage logic
│   ├── preflight-checks.js   #   Pre-run environment validation
│   ├── solomon-escalation.js #   Conflict resolution and escalation
│   ├── solomon-rules.js      #   Solomon's 5 evaluation rules
│   ├── reviewer-fallback.js  #   Fallback reviewer logic
│   ├── agent-fallback.js     #   Fallback agent selection
│   ├── standby.js            #   Rate-limit standby with backoff
│   └── pipeline-context.js   #   Shared pipeline state object
│
├── roles/                       # Clases de rol — 2 clases base + 20 roles concretos. El pipeline de `kj run` orquesta **24 etapas** en total: 18 de estas clases + 6 etapas deterministas sin clase (intent, skills, acceptance, output-guard, perf-guard, tdd) que viven en el orquestador. Las otras 2 clases (`commiter`, `repairer`) son post-aprobación / auxiliares internas, no etapas independientes del pipeline. Ver handbook/pipeline-roles para el catálogo completo.
│   ├── base-role.js             #   Clase base abstracta (init, execute, report) — NO es un rol del pipeline
│   ├── agent-role.js            #   Clase base para roles respaldados por LLM — NO es un rol del pipeline
│   ├── triage-role.js           #   Clasificador de complejidad
│   ├── domain-curator-role.js   #   Síntesis de conocimiento de dominio de negocio
│   ├── discover-role.js         #   Detección de gaps (Mom Test, Wendel, JTBD)
│   ├── researcher-role.js       #   Investigación del codebase
│   ├── architect-role.js        #   Diseño de arquitectura
│   ├── planner-role.js          #   Planificación de implementación
│   ├── hu-reviewer-role.js      #   Certificación de historias de usuario (6 dimensiones, 7 antipatrones)
│   ├── coder-role.js            #   Generación de código y tests
│   ├── refactorer-role.js       #   Mejora de claridad del código
│   ├── sonar-role.js            #   Wrapper de SonarQube (no IA)
│   ├── reviewer-role.js         #   Revisión de código
│   ├── tester-role.js           #   Quality gate de tests
│   ├── security-role.js         #   Auditoría de seguridad OWASP
│   ├── impeccable-role.js       #   Auditoría UI/UX (a11y, rendimiento, theming)
│   ├── perf-role.js             #   Quality gate WebPerf (Core Web Vitals)
│   ├── audit-role.js            #   Análisis read-only de salud del codebase (puntuaciones A-F)
│   ├── solomon-role.js          #   Pipeline boss, arbitraje de conflictos
│   ├── karajan-brain-role.js    #   Orquestador IA central (routing, compresión, ejecución de acciones)
│   ├── repairer-role.js         #   Repara tests de aceptación rotos en runtime
│   ├── commiter-role.js         #   Automatización git (post-aprobación)
│   └── index.js                 #   Registro de roles
│
├── agents/                   # AI agent adapters (5 agents)
│   ├── index.js              #   Agent registry (register, create)
│   ├── base-agent.js         #   Abstract base class
│   ├── claude-agent.js       #   Claude CLI wrapper
│   ├── codex-agent.js        #   Codex CLI wrapper
│   ├── gemini-agent.js       #   Gemini CLI wrapper
│   ├── aider-agent.js        #   Aider CLI wrapper
│   ├── opencode-agent.js     #   OpenCode CLI wrapper
│   ├── host-agent.js         #   Delegate to host AI agent (MCP mode)
│   ├── model-registry.js     #   Model availability & pricing
│   ├── availability.js       #   Check if agents are installed
│   └── resolve-bin.js        #   Resolve agent binary path
│
├── guards/                   # Deterministic guards (no AI)
│   ├── intent-guard.js       #   Validates coder output matches task intent
│   ├── output-guard.js       #   Validates coder output structure
│   ├── perf-guard.js         #   Performance regression detection
│   └── policy-resolver.js    #   Task-type policy resolution
│
├── hu/                       # HU (User Story) system
│   ├── store.js              #   Local HU file storage
│   ├── graph.js              #   Dependency graph with topological sort
│   └── parallel-executor.js  #   Parallel HU execution via git worktrees
│
├── webperf/                  # WebPerf Quality Gate
│   └── runner.js             #   Core Web Vitals measurement via Chrome DevTools
│
├── commands/                 # CLI command handlers
│   ├── run.js, code.js, review.js, plan.js, resume.js
│   ├── audit.js, architect.js, discover.js, researcher.js, triage.js
│   ├── init.js, doctor.js, config.js, report.js, board.js
│   ├── roles.js, agents.js, scan.js, sonar.js
│
├── mcp/                      # MCP server (27 tools)
│   ├── server.js             #   Stdio transport entry point
│   ├── tools.js              #   Tool schemas (27 tools)
│   ├── server-handlers.js    #   Tool handlers
│   ├── handlers/             #   Handler sub-modules (split from server-handlers)
│   │   ├── run.js            #     kj_run handler
│   │   ├── direct.js         #     Direct role handlers (code, review, plan, etc.)
│   │   ├── management.js     #     Management handlers (agents, config, status, etc.)
│   │   └── hu.js             #     HU Board handlers
│   ├── direct-role-runner.js #   Shared boilerplate for standalone role MCP tools
│   ├── run-kj.js             #   Subprocess spawner
│   ├── progress.js           #   Real-time notifications
│   ├── preflight.js          #   MCP preflight validation
│   ├── orphan-guard.js       #   Zombie process prevention
│   └── tool-arg-normalizers.js # Input normalization
│
├── prompts/                  # Prompt builders
│   ├── coder.js              #   Task + feedback + rules
│   ├── reviewer.js           #   Diff + rules
│   ├── planner.js            #   Task + research context
│   ├── architect.js          #   Architecture design prompt
│   ├── triage.js             #   Complexity classification prompt
│   ├── discover.js           #   Gap detection prompt (5 modes)
│   ├── hu-reviewer.js        #   HU certification prompt
│   ├── audit.js              #   Codebase health analysis prompt
│   └── rtk-snippet.js        #   Shared RTK token optimization instructions
│
├── review/                   # Code review infrastructure
│   ├── profiles.js           #   standard/strict/paranoid/relaxed
│   ├── schema.js             #   Reviewer output JSON schema
│   ├── parser.js             #   Parse reviewer response
│   ├── diff-generator.js     #   Git diff generation
│   ├── tdd-policy.js         #   TDD compliance check
│   └── scope-filter.js       #   Defer out-of-scope issues as tech debt
│
├── sonar/                    # SonarQube integration
│   ├── manager.js            #   Docker compose lifecycle (auto-start)
│   ├── scanner.js            #   sonar-scanner execution
│   ├── cloud-scanner.js      #   SonarCloud support
│   ├── api.js                #   REST API client
│   ├── enforcer.js           #   Quality gate enforcement
│   ├── credentials.js        #   Token management (no hardcoded defaults)
│   └── project-key.js        #   Project key detection
│
├── plugins/                  # Plugin system
│   └── loader.js             #   Discover & load plugins
│
├── planning-game/            # Planning Game integration
│   ├── adapter.js            #   Card ID parsing, task enrichment
│   ├── pipeline-adapter.js   #   Event-driven pipeline status updates
│   ├── client.js             #   REST client
│   ├── decomposition.js      #   Task decomposition with linked cards
│   └── architect-adrs.js     #   Auto ADR generation from tradeoffs
│
├── becaria/                  # BecarIA gateway (GitHub PR automation)
│   ├── dispatch.js           #   PR event dispatcher
│   ├── repo.js               #   Repository operations
│   └── pr-diff.js            #   PR diff extraction
│
├── git/                      # Git automation
│   └── automation.js         #   Branch, commit, push, PR
│
└── utils/                    # Shared utilities
    ├── injection-guard.js    #   Prompt injection scanner (directives, unicode, payloads)
    ├── budget.js             #   Token & cost tracking
    ├── pricing.js            #   Model pricing lookup
    ├── model-selector.js     #   Smart model selection per role
    ├── retry.js              #   Exponential backoff
    ├── rate-limit-detector.js #  Rate limit and provider outage detection
    ├── stall-detector.js     #   Agent heartbeat and stall detection
    ├── process.js            #   Subprocess execution
    ├── json-extract.js       #   Robust JSON extraction from agent output
    ├── run-log.js            #   File-based run log for kj-tail
    ├── git.js                #   Git operations
    ├── agent-detect.js       #   Agent binary detection
    ├── project-detect.js     #   Test framework & SonarQube config detection
    ├── rtk-detect.js         #   RTK availability detection
    ├── os-detect.js          #   OS-aware install commands
    ├── events.js             #   Event emission
    ├── display.js            #   CLI formatting (icons, colors, stage output)
    ├── logger.js             #   Logging
    ├── paths.js              #   KJ_HOME resolution
    ├── wizard.js             #   Interactive prompts
    └── fs.js                 #   File system helpers

templates/
├── roles/                    # Role instruction files (.md)
│   ├── coder.md, reviewer.md, planner.md, architect.md
│   ├── triage.md, discover.md, researcher.md, hu-reviewer.md
│   ├── tester.md, security.md, solomon.md, sonar.md
│   ├── impeccable.md, audit.md, commiter.md, refactorer.md
│   └── reviewer-strict.md, reviewer-paranoid.md, reviewer-relaxed.md
└── skills/                   # Skill definitions for MCP tools
    ├── kj-run.md, kj-code.md, kj-review.md, kj-audit.md
    ├── kj-discover.md, kj-architect.md, kj-security.md
    ├── kj-test.md, kj-sonar.md, kj-board.md

packages/
└── hu-board/                 # HU Board dashboard (standalone app)
    ├── src/server.js         #   Express server
    ├── src/db.js             #   SQLite storage
    ├── src/sync.js           #   File watcher (chokidar)
    ├── src/routes/api.js     #   REST API
    ├── public/               #   Vanilla JS frontend (kanban, sessions)
    └── Dockerfile            #   Docker deployment

Abstracciones Principales

BaseRole

Cada rol del pipeline extiende BaseRole. Proporciona un ciclo de vida uniforme:

class BaseRole {
  constructor({ name, config, logger, emitter })
  async init(context)       // Load instructions from .md template
  async execute(input)      // Role-specific logic
  async run(input)          // Wrapper: init, execute, validate, emit events
  report()                  // { role, ok, result, summary, timestamp }
}

Las instrucciones de rol se cargan desde ficheros markdown en orden de prioridad:

Override de proyecto: .karajan/roles/<role>.md
Override de usuario: ~/.karajan/roles/<role>.md
Default built-in: templates/roles/<role>.md

BaseAgent

Cada adaptador de agente IA extiende BaseAgent:

class BaseAgent {
  constructor(name, config, logger)
  async runTask(task)       // Execute coding/planning task
  async reviewTask(task)    // Execute review task
  getRoleModel(role)        // Get configured model for role
}

Los agentes envuelven herramientas CLI como subprocesos. El registry de agentes permite registro al arranque (built-in) o via plugins (custom).

Agent Registry

registerAgent("claude", ClaudeAgent, { bin: "claude", installUrl: "..." })
const agent = createAgent("claude", config, logger)
const result = await agent.runTask({ prompt, role: "coder" })

Orchestrator

El orchestrator impulsa el pipeline completo a través de tres fases:

Pre-loop. Bootstrap gate, HU-reviewer, triage, discover, researcher, architect, planner
Bucle de iteración. Coder, refactorer, guards, TDD check, sonar, injection guard, reviewer, Solomon (se repite hasta aprobación o máximo de iteraciones)
Post-loop. Tester, security, impeccable, audit, commiter (solo tras aprobación)

Flujo del Pipeline

Input (descripción de tarea)
    │
    ▼
┌─ Bootstrap Gate ───────────┐
│  Validate: git, remote,    │
│  config, agents, sonar     │
└────────────┬───────────────┘
    │
    ▼
┌─ Pre-loop ─────────────────────┐
│  [HU-Reviewer?] → certify HU  │
│  [Triage]       → classify     │
│  [Discover?]    → detect gaps  │
│  [Researcher?]  → investigate  │
│  [Architect?]   → design       │
│  [Planner?]     → plan steps   │
└────────────────────────────────┘
    │
    ▼
┌─ Iteration Loop (1..N) ─────────────────────────────────┐
│                                                          │
│  [Coder]          → write code & tests                  │
│  [Refactorer?]    → improve clarity                     │
│  [Guards]         → intent + output + perf checks       │
│  [TDD Check]      → enforce test changes                │
│  [SonarQube?]     → static analysis + quality gate      │
│  [Impeccable?]    → UI/UX audit (frontend tasks)        │
│  [Injection Guard] → scan diff for prompt injection     │
│  [Reviewer]       → code review                         │
│       ├→ approved   → exit loop                         │
│       └→ rejected   → Solomon evaluates                 │
│  [Solomon]        → override style-only? continue? stop?│
│       ├→ continue   → loop back with conditions         │
│       ├→ override   → approve despite reviewer          │
│       └→ escalate   → human intervention                │
│                                                          │
└──────────────────────────────────────────────────────────┘
    │
    ▼
┌─ Post-loop ────────────────────┐
│  [Tester?]     → test quality  │
│  [Security?]   → OWASP audit   │
│  [Audit]       → certify code  │
│  [Commiter?]   → git finalize  │
└────────────────────────────────┘
    │
    ▼
Resultado (informe de sesión, presupuesto, commits)

Resolución de Configuración

La configuración se carga y fusiona en este orden:

Defaults built-in en config.js
Config de usuario en ~/.karajan/kj.config.yml (o $KJ_HOME/kj.config.yml)
Config de proyecto en .karajan.yml en la raíz del proyecto
Contexto de producto en .karajan/context.md (se inyecta en todos los prompts de roles)
Flags CLI sobreescriben todo

La selección de modelo sigue una jerarquía similar:

roles.<role>.model → <role>_options.model → agent default

Ciclo de Vida de Sesión

create → running → [pause?] → approved | failed
                       ↓
                    paused → resume → running

Las sesiones se persisten en ~/.karajan/sessions/{sessionId}/session.json e incluyen:

Descripción de tarea y snapshot de configuración
Checkpoints por etapa (timestamp, iteración, notas)
Historial de feedback del reviewer
Tracking de presupuesto (tokens, costes estimados)
Estado de pausa (pregunta, contexto, respuesta)

Esto permite recuperación ante caídas, pausa/reanudación e informes post-ejecución.

Inspiraciones

La arquitectura se nutre de varias fuentes:

jorgecasar/ai-orchestration Arquitectura hexagonal limpia con puertos y adaptadores para orquestación de IA. Influyó en el diseño de adaptadores de agentes y la abstracción de roles de Karajan.
Augmented Coding Patterns (lexler). Un catálogo mantenido por la comunidad de patrones para programación asistida por IA. Los role-prompts de Karajan codifican directamente varios de sus remedios: Active Partner (el coder plantea un bloqueo real antes de programar en vez de acatar en silencio), Check Alignment (reformula lo que ha entendido en tareas no triviales antes de escribir código) y Point the Target (las instrucciones de más impacto dicen qué hacer, no solo qué evitar). El catálogo es validación externa de que son patrones reconocidos, no una idiosincrasia de este proyecto.
Arquitectura Hexagonal (Puertos y Adaptadores). La capa de agentes actúa como adaptadores (Claude, Codex, etc.) detrás de un puerto unificado (BaseAgent).
Patrón Pipeline. El orchestrator compone roles en un pipeline configurable e iterativo con quality gates.
Arquitectura Dirigida por Eventos. Los roles emiten eventos para tracking de progreso, notificaciones MCP y monitorización en tiempo real con kj-tail.