Referencia de Configuración

Ubicación del fichero de configuración

Fichero	Propósito
~/.karajan/kj.config.yml	Configuración principal (o $KJ_HOME/kj.config.yml)
<proyecto>/.karajan.yml	Overrides de pricing a nivel de proyecto
<proyecto>/.karajan/roles/*.md	Instrucciones de roles a nivel de proyecto
<proyecto>/.karajan/plugins/*.js	Plugins a nivel de proyecto

Los flags CLI sobreescriben los valores del fichero de configuración. Los valores de configuración sobreescriben los defaults.

---

Campos de nivel superior

coder: claude                  # Agente IA que escribe código
reviewer: codex                # Agente IA que revisa código
review_mode: standard          # Perfil de exigencia de revisión
max_iterations: 5              # Máx iteraciones del bucle coder-reviewer
review_rules: ./review-rules.md   # Ruta a reglas de revisión custom
coder_rules: ./coder-rules.md     # Ruta a reglas del coder custom
base_branch: main              # Rama base de git para diffs
max_budget_usd: null           # Presupuesto máximo en USD (null = ilimitado)

Campo	Tipo	Default	Descripción
coder	string	claude	Nombre del CLI del agente: claude, codex, gemini, aider, o un plugin custom
reviewer	string	codex	Nombre del CLI del agente para revisión de código
review_mode	enum	standard	paranoid | strict | standard | relaxed | custom
max_iterations	number	5	Máximo de iteraciones del bucle coder-reviewer (1-20)
review_rules	string	./review-rules.md	Ruta al fichero de instrucciones del reviewer
coder_rules	string	./coder-rules.md	Ruta al fichero de instrucciones del coder
base_branch	string	main	Rama de git usada para comparar diffs
max_budget_usd	number | null	null	Tope de presupuesto estimado por sesión en USD (basado en pricing equivalente a API). null = ilimitado

---

roles

Override de provider y modelo por rol:

roles:
  coder:
    provider: claude
    model: claude-opus-4-6
  reviewer:
    provider: codex
    model: null
  planner:
    provider: null
    model: null
  refactorer:
    provider: null
    model: null
  solomon:
    provider: null
    model: null
  researcher:
    provider: null
    model: null
  tester:
    provider: null
    model: null
  security:
    provider: null
    model: null
  triage:
    provider: null
    model: null
  discover:
    provider: null
    model: null
  hu-reviewer:
    provider: null
    model: null
  architect:
    provider: null
    model: null
  audit:
    provider: null
    model: null
  impeccable:
    provider: null
    model: null
  commiter:
    provider: null
    model: null

Rol	Propósito
coder	Escribe código y tests
reviewer	Revisa código: calidad, seguridad, corrección
planner	Genera planes de implementación antes de codificar
refactorer	Refactoriza código tras la aprobación
solomon	Resuelve conflictos entre coder y reviewer
researcher	Analiza el codebase antes de planificar
tester	Audita la calidad de los tests tras la revisión
security	Auditoría de seguridad OWASP
triage	Clasifica la complejidad de la tarea
discover	Detección de gaps pre-ejecución
hu-reviewer	Certificación de historias de usuario
architect	Diseño de arquitectura de solución
audit	Auditoría de salud del codebase de solo lectura
impeccable	Auditoría automatizada de diseño UI/UX
commiter	Automatización git

fallback: la cadena que corre cuando la primera opción no puede

Cualquier rol acepta un fallback, y un fallback acepta el suyo, así que la cadena es tan larga como necesites (cinco eslabones; a partir de ahí kj avisa e ignora el resto):

roles:
  reviewer:
    provider: codex
    model: gpt-5.6-terra
    fallback:
      provider: codex          # el mismo proveedor, otro modelo
      model: gpt-5.6
      max_wait_hours: 12
      fallback:
        provider: claude       # o directamente otro proveedor
        model: null            # null = el default de ese proveedor

Campo	Tipo	Default	Descripción
provider	string	—	El agente de este eslabón. Obligatorio.
model	string | null	null	El modelo de este eslabón. null pide el default del proveedor.
max_wait_hours	number	12	Ante un muro de cuota, esperar en vez de cambiar cuando el enfriamiento sea menor que esto. Un modelo retirado no espera nunca: no hay nada que lo devuelva.
fallback	object	ninguno	El eslabón siguiente. La misma forma, recursiva.

Dos cosas que conviene saber porque no se ven:

• La cadena se recorre en el orden que escribiste, y el modelo por defecto del proveedor se añade como último eslabón cuando (y solo cuando) fijaste un modelo. Ese paso ocurría antes en silencio dentro de cada agente, y por delante de lo que hubieras declarado; desde la 4.33.0 es la cola de tu cadena, donde se ve.
• Un eslabón que repite al primario se salta, y también uno cuyo proveedor no existe, avisando de cuál. Reintentar el mismo proveedor y el mismo modelo no es avanzar, solo lo parece.

Agotada la cadena, el error dice qué se probó y en qué orden, y kj recuerda un modelo que vio retirar a un proveedor para que la siguiente ejecución no vuelva a pagar esa llamada muerta. Nunca te toca el pin: te nombra la línea para que la cambies tú.

Nota

coder_options.fallback_coder y reviewer_options.fallback_reviewer son la forma antigua: un solo paso y solo de proveedor. Siguen funcionando. roles.<role>.fallback es la que cubre todos los roles y puede cambiar el modelo.

---

pipeline

Activar o desactivar roles opcionales:

pipeline:
  planner:
    enabled: false
  refactorer:
    enabled: false
  solomon:
    enabled: false
  researcher:
    enabled: false
  tester:
    enabled: false
  security:
    enabled: false
  triage:
    enabled: false
  reviewer:
    enabled: true
  discover:
    enabled: false
  hu-reviewer:
    enabled: false
  architect:
    enabled: false
  audit:
    enabled: false
  impeccable:
    enabled: false
  commiter:
    enabled: false

Todos los roles opcionales están desactivados por defecto. Actívalos con flags CLI --enable-<rol> o en la configuración.

---

development

development:
  methodology: tdd
  require_test_changes: true
  test_file_patterns:
    - /tests/
    - /__tests__/
    - .test.
    - .spec.
  source_file_extensions:
    - .js
    - .jsx
    - .ts
    - .tsx
    - .py
    - .go
    - .java
    - .rb
    - .php
    - .cs

Campo	Tipo	Default	Descripción
methodology	enum	tdd	tdd (exigir tests primero) o standard (tests opcionales)
require_test_changes	boolean	true	En TDD, exigir cambios en tests junto con cambios en código fuente
test_file_patterns	string[]	Ver arriba	Patrones para identificar ficheros de test
source_file_extensions	string[]	Ver arriba	Extensiones de ficheros fuente a monitorizar para TDD

---

coder_options

coder_options:
  model: null
  auto_approve: true

Campo	Tipo	Default	Descripción
model	string | null	null	Override de modelo para el coder (ej: claude-opus-4-6)
auto_approve	boolean	true	Permitir al coder auto-aprobar su output si el reviewer aprueba

---

reviewer_options

reviewer_options:
  output_format: json
  require_schema: true
  model: null
  deterministic: true
  retries: 1
  fallback_reviewer: codex

Campo	Tipo	Default	Descripción
output_format	string	json	Formato de salida del reviewer (siempre JSON para revisión estructurada)
require_schema	boolean	true	Validar que la salida del reviewer coincida con el schema esperado
model	string | null	null	Override de modelo para el reviewer
deterministic	boolean	true	Usar modo determinista para revisiones reproducibles
retries	number	1	Reintentos del reviewer ante errores de parseo
fallback_reviewer	string	codex	Provider de respaldo si el reviewer principal falla

---

sonarqube

sonarqube:
  enabled: true
  host: http://localhost:9000
  external: false
  container_name: karajan-sonarqube
  network: karajan_sonar_net
  token: null
  project_key: null
  admin_user: admin
  admin_password: null
  quality_gate: true
  enforcement_profile: pragmatic
  max_scan_retries: 3

  gate_block_on:
    - new_reliability_rating=E
    - new_security_rating=E
    - new_maintainability_rating=E
    - new_coverage<80
    - new_duplicated_lines_density>5

  fail_on:
    - BLOCKER
    - CRITICAL

  ignore_on:
    - INFO

  volumes:
    data: karajan_sonar_data
    logs: karajan_sonar_logs
    extensions: karajan_sonar_extensions

  timeouts:
    healthcheck_seconds: 5
    compose_up_ms: 300000
    compose_control_ms: 120000
    logs_ms: 30000
    scanner_ms: 900000

  coverage:
    enabled: false
    command: null
    timeout_ms: 300000
    block_on_failure: true
    lcov_report_path: null

  scanner:
    sources: "src,public,lib"
    exclusions: "**/node_modules/**,**/dist/**,**/build/**,**/*.min.js"
    test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
    coverage_exclusions: "**/tests/**,**/__tests__/**,**/*.test.js,**/*.spec.js"
    disabled_rules:
      - "javascript:S1116"
      - "javascript:S3776"

Campos clave de SonarQube

Campo	Tipo	Default	Descripción
enabled	boolean	true	Activar escaneo SonarQube
host	string	http://localhost:9000	URL del servidor SonarQube
external	boolean	false	Si true, asumir SonarQube externo (no gestionar Docker)
token	string | null	null	Token de autenticación. Preferir la variable KJ_SONAR_TOKEN
quality_gate	boolean	true	Comprobar estado del quality gate tras el escaneo
enforcement_profile	enum	pragmatic	pragmatic (bloquear solo en ERROR) o paranoid (bloquear en cualquier estado distinto de OK)
max_scan_retries	number	3	Reintentar escaneos fallidos

Niveles de severidad de issues

Severidad	Significado
BLOCKER	Crash de la aplicación, pérdida de datos
CRITICAL	Agujero de seguridad, error lógico
MAJOR	Problema de calidad que afecta funcionalidad
MINOR	Code smell, inconsistencia
INFO	Convención, clarificación

---

git

git:
  auto_commit: false
  auto_push: false
  auto_pr: false
  auto_rebase: true
  branch_prefix: feat/

Campo	Tipo	Default	Descripción
auto_commit	boolean	false	Hacer commit de todos los cambios tras aprobación
auto_push	boolean	false	Push de la rama a origin tras el commit
auto_pr	boolean	false	Crear pull request hacia base_branch
auto_rebase	boolean	true	Rebase sobre base_branch antes de push
branch_prefix	string	feat/	Prefijo para nombres de rama (ej: feat/, fix/)

El flujo de automatización Git tras aprobación: rebase (si está activo) → commit → push → PR.

---

session

session:
  max_iteration_minutes: 15
  max_total_minutes: 120
  max_planner_minutes: 60
  max_agent_silence_minutes: 20
  fail_fast_repeats: 2
  repeat_detection_threshold: 2
  max_sonar_retries: 3
  max_reviewer_retries: 3
  max_tester_retries: 1
  max_security_retries: 1
  expiry_days: 30

Campo	Tipo	Default	Descripción
max_iteration_minutes	number	15	Tiempo límite por ciclo coder-reviewer
max_total_minutes	number	120	Tiempo límite total de sesión
max_planner_minutes	number	60	Límite duro de runtime para planificación (kj_plan/kj plan)
max_agent_silence_minutes	number	20	Finaliza la ejecución si no hay salida del agente durante estos minutos
fail_fast_repeats	number	2	Salir tras N fallos idénticos repetidos
repeat_detection_threshold	number	2	Iteraciones antes de detectar patrones repetidos
max_sonar_retries	number	3	Máx reintentos de escaneo SonarQube
max_reviewer_retries	number	3	Máx reintentos del reviewer ante error de parseo
max_tester_retries	number	1	Máx reintentos de auditoría de tests
max_security_retries	number	1	Máx reintentos de auditoría de seguridad
expiry_days	number	30	Auto-limpieza de sesiones más antiguas que esto

---

budget

Nota

Costes estimados, no facturación real. Karajan ejecuta agentes CLI (Claude Code, Codex, etc.) bajo tus suscripciones existentes — no tiene coste adicional. El sistema de budget cuenta tokens y estima lo que la sesión habría costado si usaras las APIs directamente, basándose en las tarifas publicadas. Es útil para comparar enfoques y establecer guardarraíles, no para facturación.

budget:
  warn_threshold_pct: 80
  currency: usd
  exchange_rate_eur: 0.92
  pricing:
    claude:
      input_per_million: 0.003
      output_per_million: 0.015

Campo	Tipo	Default	Descripción
warn_threshold_pct	number	80	Avisar cuando el gasto estimado alcance este % de max_budget_usd
currency	enum	usd	Moneda de visualización: usd o eur
exchange_rate_eur	number	0.92	Tipo de cambio EUR a USD
pricing	object	Built-in	Tarifas de pricing por agente para estimación (input_per_million, output_per_million)

La sección pricing también puede definirse en el fichero .karajan.yml a nivel de proyecto para sobrescribir tarifas de estimación por proyecto.

---

retry

retry:
  max_attempts: 3
  initial_backoff_ms: 1000
  max_backoff_ms: 30000
  backoff_multiplier: 2
  jitter_factor: 0.1

Campo	Tipo	Default	Descripción
max_attempts	number	3	Máx reintentos para errores transitorios de API
initial_backoff_ms	number	1000	Delay inicial de backoff (1 segundo)
max_backoff_ms	number	30000	Delay máximo de backoff (30 segundos)
backoff_multiplier	number	2	Multiplicador exponencial de backoff
jitter_factor	number	0.1	Jitter aleatorio como fracción del backoff (10%)

---

output

output:
  report_dir: ./.reviews
  log_level: info

Campo	Tipo	Default	Descripción
report_dir	string	./.reviews	Directorio para informes y logs de sesión
log_level	enum	info	Nivel de logging: debug | info | warn | error

---

planning_game

Integración con Planning Game — un sistema de gestión de proyectos ágil (metodología XP) disponible como servidor MCP.

planning_game:
  enabled: false
  project_id: null
  codeveloper: null

Campo	Tipo	Default	Descripción
enabled	boolean	false	Activar integración con Planning Game MCP
project_id	string | null	null	ID del proyecto en Planning Game
codeveloper	string | null	null	ID del developer para el campo codeveloper

---

becaria

becaria:
  enabled: false
  review_event: becaria-review
  comment_event: becaria-comment
  comment_prefix: true

Campo	Tipo	Default	Descripción
enabled	boolean	false	Activar BecarIA Gateway — publica resultados del pipeline como comentarios/reviews en PRs vía GitHub App
review_event	string	becaria-review	Tipo de evento repository_dispatch de GitHub para reviews formales (APPROVE/REQUEST_CHANGES)
comment_event	string	becaria-comment	Tipo de evento repository_dispatch de GitHub para comentarios de agentes
comment_prefix	boolean	true	Prefijar comentarios con [Agente] (ej: [Reviewer], [Sonar])

Cuando enabled: true, Karajan establece automáticamente git.auto_commit, git.auto_push y git.auto_pr a true. Ver Flujos del Pipeline para la arquitectura completa de BecarIA.

---

serena

serena:
  enabled: false

Campo	Tipo	Default	Descripción
enabled	boolean	false	Activar integración con Serena para contexto con conocimiento del codebase

---

model_selection

model_selection:
  enabled: true
  tiers: {}
  role_overrides: {}

Campo	Tipo	Default	Descripción
enabled	boolean	true	Activar selección inteligente de modelo basada en complejidad de la tarea
tiers	object	{}	Tiers con nombre y asignación de modelo (ej: fast, balanced, powerful)
role_overrides	object	{}	Overrides de modelo por rol que saltan la selección por tier

Ejemplo con tiers:

model_selection:
  enabled: true
  tiers:
    fast:
      model: claude-sonnet-4-6
    balanced:
      model: claude-opus-4-6
  role_overrides:
    reviewer:
      model: claude-opus-4-6

Desactivar con el flag CLI --no-smart-models.

---

failFast

failFast:
  repeatThreshold: 2

Campo	Tipo	Default	Descripción
repeatThreshold	number	2	Detener el pipeline tras este número de fallos idénticos consecutivos

Esto es independiente de session.fail_fast_repeats — failFast aplica a la detección global de repeticiones del orquestador entre todas las etapas.

---

release_check

Lo que kj release check comprueba además de los genéricos (manifest contra CHANGELOG contra tags, escaneo de privacidad de los ficheros publicables, la policy vigente). Cada item lo pone el proyecto.

release_check:
  items:
    - name: la landing desplegada muestra la versión como current
      command: curl -sf https://example.com/docs/ | grep -q 'v{version}'
      remedied_by: firebase deploy
    - name: el pie lleva la versión
      file_contains:
        path: public/footer.html
        pattern: v{version}

Campo	Tipo	Descripción
name	string	Con qué nombre se informa del item
command	string	Se pasa a sh -c; exit 0 es pasar. {version} se sustituye por la versión del manifest
file_contains.path	string	Fichero a leer, relativo al proyecto
file_contains.pattern	string	Texto que tiene que aparecer; {version} se sustituye también
remedied_by	string	El comando que REPARA este item, si lo hay

remedied_by existe porque un item en rojo no puede bloquear justo la acción que lo pondría en verde. El caso es la landing: el check quiere el sitio desplegado con la versión nueva, y el despliegue que lo consigue estaba bloqueado por ese mismo check. Las palabras tienen que aparecer en el comando en orden, así que firebase deploy cubre firebase --account a@b --project p deploy --only hosting:main.

El item levantado sigue en rojo en el informe, porque el hecho no ha cambiado, y el gate dice cuál ha levantado. Lo demás sigue bloqueando, y publicar el paquete no se exime nunca: npm publish y gh release create son irreversibles, diga lo que diga un item.

---

Variables de entorno

Variable	Propósito	Default
KJ_HOME	Sobreescribir directorio de configuración de Karajan	~/.karajan
KJ_SONAR_TOKEN	Token de autenticación de SonarQube	Desde config
KJ_SONAR_ADMIN_USER	Usuario admin de SonarQube	admin
KJ_SONAR_ADMIN_PASSWORD	Contraseña admin de SonarQube	Desde config
KJ_SONAR_PROJECT_KEY	Sobreescribir project key de SonarQube	Desde config
VISUAL / EDITOR	Editor para kj config --edit	vi

Las variables de entorno tienen precedencia sobre los valores del fichero de configuración para los campos que mapean.

---

Perfiles de modo de revisión

El ajuste review_mode controla la exigencia del reviewer al evaluar código:

standard (por defecto)

• Prioridad: Seguridad → Corrección → Tests → Arquitectura → Estilo
• Bloquean: Problemas de seguridad, errores lógicos, tests rotos, sobreescritura de ficheros
• No bloquean: Sugerencias de estilo

paranoid

• Filosofía: Todo cambio es sospechoso hasta que se demuestre seguro
• Prioridad: Seguridad → Corrección → Tests → Integridad de datos → Arquitectura → Estilo
• Bloquean: Todas las comprobaciones de seguridad, falta de manejo de errores, falta de validación de inputs, falta de tests, sobreescritura de ficheros
• Umbral de confianza: Aprobar solo si confianza > 0.85. Default a RECHAZO

strict

• Prioridad: Seguridad → Corrección → Tests → Arquitectura → Estilo
• Bloquean: Todos los problemas de seguridad, errores lógicos, cobertura de tests insuficiente, falta de manejo de errores para llamadas externas
• Umbral de confianza: Rechazar si confianza < 0.80

relaxed

• Filosofía: Preferir aprobar con sugerencias
• Prioridad: Seguridad crítica → Bugs claros → Tests de rutas críticas
• Bloquean: Solo seguridad crítica (secrets, SQL injection, XSS) y errores lógicos claros
• Umbral de confianza: Rechazar si confianza < 0.60

custom

Usa el fichero base reviewer.md (a nivel de proyecto, global o built-in) sin un perfil predefinido. Control total a través de tu fichero review-rules.md.

---

Jerarquía de resolución de ficheros

Las instrucciones de rol se resuelven en este orden (el primero encontrado gana):

1. Proyecto: <proyecto>/.karajan/roles/{rol}.md
2. Global: ~/.karajan/roles/{rol}.md
3. Built-in: templates/roles/{rol}.md (incluido con Karajan)

Los perfiles de modo de revisión siguen el mismo patrón:

1. .karajan/roles/reviewer-{modo}.md
2. ~/.karajan/roles/reviewer-{modo}.md
3. templates/roles/reviewer-{modo}.md

Los plugins se cargan de todas las ubicaciones (no first-wins):

1. <proyecto>/.karajan/plugins/*.js
2. ~/.karajan/plugins/*.js

---

Estructura de directorios

~/.karajan/                           # Config global ($KJ_HOME)
├── kj.config.yml                     # Configuración principal
├── roles/                            # Instrucciones de roles globales
│   ├── coder.md
│   ├── reviewer.md
│   ├── reviewer-paranoid.md
│   └── ...
├── plugins/                          # Plugins globales
│   └── my-agent.js
├── sessions/                         # Logs de sesión
│   └── session-{id}/
└── docker-compose.sonar.yml          # Config Docker de SonarQube

<proyecto>/
├── .karajan/                         # Overrides a nivel de proyecto
│   ├── roles/                        # Instrucciones de roles del proyecto
│   │   └── reviewer.md
│   └── plugins/                      # Plugins del proyecto
│       └── my-plugin.js
├── .karajan.yml                      # Overrides de pricing del proyecto
├── coder-rules.md                    # Directrices del coder
└── review-rules.md                   # Directrices de revisión

---

Recetas de configuración

Seguridad estricta

review_mode: paranoid
development:
  methodology: tdd
sonarqube:
  enabled: true
  enforcement_profile: paranoid
  quality_gate: true
pipeline:
  security:
    enabled: true
  tester:
    enabled: true
max_iterations: 5
git:
  auto_commit: false

Prototipado rápido

review_mode: relaxed
development:
  methodology: standard
sonarqube:
  enabled: false
max_iterations: 2
session:
  max_total_minutes: 30

Pipeline CI/CD

review_mode: strict
development:
  methodology: tdd
sonarqube:
  enabled: true
  enforcement_profile: paranoid
pipeline:
  tester:
    enabled: true
  security:
    enabled: true
git:
  auto_commit: true
  auto_push: true
  auto_pr: true
max_iterations: 5
max_budget_usd: 5.00

Multi-agente

pipeline:
  planner:
    enabled: true
  researcher:
    enabled: true
  refactorer:
    enabled: true
  security:
    enabled: true
development:
  methodology: tdd
session:
  max_total_minutes: 240
max_iterations: 7

BecarIA Gateway

becaria:
  enabled: true
  review_event: becaria-review
  comment_event: becaria-comment
  comment_prefix: true
pipeline:
  triage:
    enabled: true
  planner:
    enabled: true
  tester:
    enabled: true
  security:
    enabled: true
  solomon:
    enabled: true
review_mode: strict
development:
  methodology: tdd
max_iterations: 5