karajan-code 1.30.0 → 1.31.0

package/README.md

@@ -5,473 +5,173 @@
 <h1 align="center">Karajan Code</h1>
 
 <p align="center">
-  Local multi-agent coding orchestrator with TDD, SonarQube, and automated code review.
+  Local multi-agent coding orchestrator. TDD-first, MCP-based, vanilla JavaScript.
 </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="docs/README.es.md">Leer en Español</a>
+  <a href="docs/README.es.md">Leer en Español</a> · <a href="https://karajancode.com">Documentation</a>
 </p>
 
 ---
 
-## What is Karajan Code?
-
-Karajan Code (`kj`) orchestrates multiple AI coding agents through an automated pipeline: code generation, static analysis, code review, testing, and security audits — all in a single command.
-
-Instead of running one AI agent and manually reviewing its output, `kj` chains agents together with quality gates. The coder writes code, SonarQube scans it, the reviewer checks it, and if issues are found, the coder gets another attempt. This loop runs until the code is approved or the iteration limit is reached.
-
-**Key features:**
-- **Multi-agent pipeline** with 11 configurable roles
-- **4 AI agents supported**: Claude, Codex, Gemini, Aider
-- **MCP server** with 15 tools — use `kj` from Claude, Codex, or any MCP-compatible host without leaving your agent. [See MCP setup](#mcp-server)
-- **TDD enforcement** — test changes required when source files change
-- **SonarQube integration** — static analysis with quality gate enforcement (requires [Docker](#requirements))
-- **Review profiles** — standard, strict, relaxed, paranoid
-- **Budget tracking** — per-session token and cost monitoring with `--trace`
-- **Git automation** — auto-commit, auto-push, auto-PR after approval
-- **Session management** — pause/resume with fail-fast detection and automatic cleanup of expired sessions
-- **Plugin system** — extend with custom agents via `.karajan/plugins/`
-- **Smart model selection** — auto-selects optimal model per role based on triage complexity (lighter models for trivial tasks, powerful models for complex ones)
-- **Interactive checkpoints** — instead of killing long-running tasks, pauses every 5 minutes with a progress report and lets you decide: continue, stop, or adjust the time
-- **Task decomposition** — triage detects when tasks should be split and recommends subtasks; with Planning Game integration, creates linked cards with sequential blocking
-- **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
-- **Pipeline stage tracker** — cumulative progress view during `kj_run` showing which stages are done, running, or pending — both in CLI and via MCP events for real-time host rendering
-- **Planner observability guardrails** — continuous heartbeat/stall telemetry, configurable max-silence protection (`session.max_agent_silence_minutes`), and hard runtime cap (`session.max_planner_minutes`) to avoid long stuck planner runs
-- **Rate-limit standby** — when agents hit rate limits, Karajan parses cooldown times, waits with exponential backoff, and auto-resumes instead of failing
-- **Preflight handshake** — `kj_preflight` requires human confirmation of agent assignments before execution, preventing AI from silently overriding your config
-- **3-tier config** — session > project > global config layering with `kj_agents` scoping
-- **Intelligent reviewer mediation** — scope filter auto-defers out-of-scope reviewer issues (files not in the diff) as tracked tech debt instead of stalling; Solomon mediates stalled reviews; deferred context injected into coder prompt
-- **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
-
-> **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
-
-## Requirements
-
-- **Node.js** >= 18
-- **Docker** — required for SonarQube static analysis. If you don't have Docker or don't need SonarQube, disable it with `--no-sonar` or set `sonarqube.enabled: false` in config
-- At least one AI agent CLI installed: Claude, Codex, Gemini, or Aider
-
-## Pipeline
+You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate — without you babysitting every step.
 
-```
-triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar? ─> reviewer ─> tester? ─> security? ─> commiter?
-```
-
-| Role | Description | Default |
-|------|-------------|---------|
-| **triage** | Pipeline director — analyzes task complexity and activates roles dynamically | **On** |
-| **researcher** | Investigates codebase context before planning | Off |
-| **planner** | Generates structured implementation plans | Off |
-| **coder** | Writes code and tests following TDD methodology | **Always on** |
-| **refactorer** | Improves code clarity without changing behavior | Off |
-| **sonar** | Runs SonarQube static analysis and quality gate checks | On (if configured) |
-| **reviewer** | Code review with configurable strictness profiles | **Always on** |
-| **tester** | Test quality gate and coverage verification | **On** |
-| **security** | OWASP security audit | **On** |
-| **solomon** | Session supervisor — monitors iteration health with 5 rules (incl. reviewer overreach), mediates stalled reviews, escalates on anomalies | **On** |
-| **commiter** | Git commit, push, and PR automation after approval | Off |
-
-Roles marked with `?` are optional and can be enabled per-run or via config.
-
-## Installation
-
-### From npm (recommended)
-
-```bash
-npm install -g karajan-code
-kj init
-```
-
-### From source
-
-```bash
-git clone https://github.com/manufosela/karajan-code.git
-cd karajan-code
-./scripts/install.sh
-```
+## What is Karajan?
 
-### Non-interactive setup (CI/automation)
+Karajan is a local coding orchestrator. It runs on your machine, uses your existing AI providers (Claude, Codex, Gemini, Aider, OpenCode), and coordinates a pipeline of specialized agents that work together on your code.
 
-```bash
-./scripts/install.sh \
-  --non-interactive \
-  --kj-home /path/to/.karajan \
-  --sonar-host http://localhost:9000 \
-  --sonar-token "$KJ_SONAR_TOKEN" \
-  --coder claude \
-  --reviewer codex \
-  --run-doctor true
-```
-
-### Multi-instance setup
-
-Full guides: [`docs/multi-instance.md`](docs/multi-instance.md) | [`docs/install-two-instances.md`](docs/install-two-instances.md)
-
-```bash
-./scripts/setup-multi-instance.sh
-```
-
-## Supported Agents
-
-| Agent | CLI | Install |
-|-------|-----|---------|
-| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
-| **Codex** | `codex` | `npm install -g @openai/codex` |
-| **Gemini** | `gemini` | See [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pip install aider-chat` |
+It is not a hosted service. It is not a VS Code extension. It is a tool you install once and use from the terminal or as an MCP server inside your AI agent.
 
-`kj init` auto-detects installed agents. If only one is available, it is assigned to all roles automatically.
-
-## Quick Start
-
-```bash
-# Run a task with defaults (claude=coder, codex=reviewer, TDD)
-kj run "Implement user authentication with JWT"
-
-# Coder-only mode (skip review)
-kj code "Add input validation to the signup form"
-
-# Review-only mode (review current diff)
-kj review "Check the authentication changes"
-
-# Generate an implementation plan
-kj plan "Refactor the database layer to use connection pooling"
-
-# Full pipeline with all options
-kj run "Fix critical SQL injection in search endpoint" \
-  --coder claude \
-  --reviewer codex \
-  --reviewer-fallback claude \
-  --methodology tdd \
-  --enable-triage \
-  --enable-tester \
-  --enable-security \
-  --auto-commit \
-  --auto-push \
-  --max-iterations 5
-```
+The name comes from Herbert von Karajan — the conductor who believed that the best orchestras are made of great independent musicians who know exactly when to play and when to listen. Same idea here, applied to AI agents.
 
-## CLI Commands
+## Why not just use Claude Code?
 
-### `kj init`
+Claude Code is excellent. Use it for interactive, session-based coding.
 
-Interactive setup wizard. Auto-detects installed agents and guides coder/reviewer selection, SonarQube configuration, and methodology choice.
+Use Karajan when you want:
 
-```bash
-kj init                  # Interactive wizard
-kj init --no-interactive # Use defaults (for CI)
-```
+- **A repeatable, documented pipeline** that runs the same way every time
+- **TDD by default** — tests are written before implementation, not after
+- **SonarQube integration** — code quality gates as part of the flow, not an afterthought
+- **Solomon as pipeline boss** — every reviewer rejection is evaluated by a supervisor that decides if it's valid or just style noise
+- **Multi-provider routing** — Claude as coder, Codex as reviewer, or any combination
+- **Zero-config operation** — auto-detects test frameworks, starts SonarQube, simplifies pipeline for trivial tasks
+- **Composable role architecture** — define agent behaviors as plain markdown files that travel with your project
+- **Local-first** — your code, your keys, your machine, no data leaves unless you say so
 
-### `kj run <task>`
+If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together — Karajan is designed to be used as an MCP server inside Claude Code.
 
-Run the full pipeline: coder → sonar → reviewer loop.
+## Install
 
 ```bash
-kj run "Fix the login bug" [options]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--coder <name>` | AI agent for coding (claude, codex, gemini, aider) |
-| `--reviewer <name>` | AI agent for review |
-| `--reviewer-fallback <name>` | Fallback reviewer if primary fails |
-| `--coder-model <name>` | Specific model for coder |
-| `--reviewer-model <name>` | Specific model for reviewer |
-| `--planner-model <name>` | Specific model for planner |
-| `--methodology <name>` | `tdd` or `standard` |
-| `--mode <name>` | Review mode: `standard`, `strict`, `paranoid`, `relaxed` |
-| `--max-iterations <n>` | Max coder/reviewer loops |
-| `--max-iteration-minutes <n>` | Timeout per iteration |
-| `--max-total-minutes <n>` | Total session timeout |
-| `--base-branch <name>` | Base branch for diff (default: `main`) |
-| `--base-ref <ref>` | Explicit base ref for diff |
-| `--enable-planner` | Enable planner role |
-| `--enable-refactorer` | Enable refactorer role |
-| `--enable-researcher` | Enable researcher role |
-| `--enable-tester` | Enable tester role |
-| `--enable-security` | Enable security audit role |
-| `--enable-triage` | Enable dynamic triage |
-| `--enable-serena` | Enable Serena MCP integration |
-| `--auto-commit` | Git commit after approval |
-| `--auto-push` | Git push after commit |
-| `--auto-pr` | Create PR after push |
-| `--no-auto-rebase` | Disable auto-rebase before push |
-| `--branch-prefix <prefix>` | Branch naming prefix (default: `feat/`) |
-| `--smart-models` | Enable smart model selection based on triage complexity |
-| `--no-smart-models` | Disable smart model selection |
-| `--no-sonar` | Skip SonarQube analysis |
-| `--checkpoint-interval <n>` | Minutes between interactive checkpoints (default: 5) |
-| `--pg-task <cardId>` | Planning Game card ID for task context |
-| `--pg-project <projectId>` | Planning Game project ID |
-| `--dry-run` | Show what would run without executing |
-| `--json` | Output JSON only |
-
-### `kj code <task>`
-
-Run coder only (no review loop).
-
-```bash
-kj code "Add error handling to the API client" --coder claude --coder-model sonnet
+npm install -g karajan-code
 ```
 
-### `kj review <task>`
+That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages it). No config files to copy. `kj init` auto-detects your installed agents.
 
-Run reviewer only against current diff.
+## Quick start
 
 ```bash
-kj review "Check auth changes" --reviewer codex --base-ref HEAD~3
+# Run a task — Karajan handles the rest
+kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 ```
 
-### `kj plan <task>`
-
-Generate an implementation plan without writing code.
+Karajan will:
+1. Triage the task complexity and activate the right roles
+2. Write tests first (TDD)
+3. Implement code to pass those tests
+4. Run SonarQube analysis (auto-starts Docker if needed)
+5. Review the code (Solomon evaluates every rejection)
+6. Iterate until approved or escalate to you
 
 ```bash
-kj plan "Migrate from REST to GraphQL" --planner claude --context "We use Apollo Server"
+# More examples
+kj code "Add input validation to the signup form"     # Coder only
+kj review "Check the authentication changes"           # Review current diff
+kj audit "Full health analysis of this codebase"       # Read-only audit
+kj plan "Refactor the database layer"                  # Plan without coding
 ```
 
-### `kj scan`
-
-Run SonarQube analysis on the current project.
-
-### `kj doctor`
-
-Check environment: git, Docker, SonarQube, agent CLIs, rule files.
+## The pipeline
 
-### `kj config`
-
-Show current configuration.
-
-```bash
-kj config          # Pretty print
-kj config --json   # JSON output
-kj config --edit   # Open in $EDITOR
 ```
-
-### `kj report`
-
-Show session reports with budget tracking.
-
-```bash
-kj report                          # Latest session report
-kj report --list                   # List all session IDs
-kj report --session-id <id>        # Specific session
-kj report --trace                  # Chronological stage breakdown
-kj report --trace --currency eur   # Costs in EUR
-kj report --format json            # JSON output
+hu-reviewer? → triage → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
 ```
 
-### `kj resume <sessionId>`
-
-Resume a paused session (e.g., after fail-fast).
+**15 roles**, each executed by the AI agent you choose:
 
-```bash
-kj resume s_2026-02-28T20-47-24-270Z --answer "yes, proceed with the fix"
-```
+| Role | What it does | Default |
+|------|-------------|---------|
+| **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Off |
+| **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 |
+| **planner** | Generates structured implementation plans | Off |
+| **coder** | Writes code and tests following TDD methodology | **Always on** |
+| **refactorer** | Improves code clarity without changing behavior | Off |
+| **sonar** | SonarQube static analysis with quality gate enforcement | On (auto-managed) |
+| **impeccable** | UI/UX audit for frontend tasks (a11y, performance, theming) | Auto (frontend) |
+| **reviewer** | Code review with configurable strictness profiles | **Always on** |
+| **tester** | Test quality gate and coverage verification | **On** |
+| **security** | OWASP security audit | **On** |
+| **solomon** | Pipeline boss — evaluates every rejection, overrides style-only blocks | **On** |
+| **commiter** | Git commit, push, and PR automation after approval | Off |
+| **audit** | Read-only codebase health analysis (5 dimensions, A-F scores) | Standalone |
 
-### `kj agents`
+## 5 AI agents supported
 
-List or change AI agent assignments per role.
+| Agent | CLI | Install |
+|-------|-----|---------|
+| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
+| **Codex** | `codex` | `npm install -g @openai/codex` |
+| **Gemini** | `gemini` | See [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
+| **Aider** | `aider` | `pip install aider-chat` |
+| **OpenCode** | `opencode` | See [OpenCode docs](https://github.com/nicepkg/opencode) |
 
-```bash
-kj agents                       # List current agents (with scope column)
-kj agents set coder gemini      # Set coder to gemini (project scope)
-kj agents set reviewer claude --global  # Set reviewer globally
-```
+Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-### `kj roles`
+## MCP server — 20 tools
 
-Inspect pipeline roles and their template instructions.
+Karajan is designed to be used as an MCP server inside your AI agent. After install, it auto-registers in Claude and Codex:
 
 ```bash
-kj roles              # List all roles with provider and status
-kj roles show coder   # Show coder role template
-kj roles show reviewer-paranoid  # Show paranoid review variant
+# Already done by npm install, but manual config if needed:
+# Add to ~/.claude.json → "mcpServers":
+# { "karajan-mcp": { "command": "karajan-mcp" } }
 ```
 
-### `kj sonar`
+**20 tools** available: `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`.
 
-Manage the SonarQube Docker container.
+## The role architecture
 
-```bash
-kj sonar status   # Check container status
-kj sonar start    # Start container
-kj sonar stop     # Stop container
-kj sonar logs     # View container logs
-kj sonar open     # Open dashboard in browser
-```
+Every role in Karajan is defined by a markdown file — a plain document that describes how the agent should behave, what to check, and what good output looks like.
 
-## Configuration
-
-Configuration file: `~/.karajan/kj.config.yml` (or `$KJ_HOME/kj.config.yml`)
-
-Generated by `kj init`. Full reference:
-
-```yaml
-# AI Agents
-coder: claude
-reviewer: codex
-
-# Review settings
-review_mode: standard          # standard | strict | paranoid | relaxed
-max_iterations: 5
-review_rules: ./review-rules.md
-coder_rules: ./coder-rules.md
-base_branch: main
-
-# Coder settings
-coder_options:
-  model: null                  # Override model (e.g., sonnet, o4-mini)
-  auto_approve: true
-
-# Reviewer settings
-reviewer_options:
-  output_format: json
-  require_schema: true
-  model: null
-  deterministic: true
-  retries: 1
-  fallback_reviewer: codex
-
-# Development methodology
-development:
-  methodology: tdd             # tdd | standard
-  require_test_changes: true
-
-# SonarQube
-sonarqube:
-  enabled: true
-  host: http://localhost:9000
-  token: null                  # Set via KJ_SONAR_TOKEN env var
-  quality_gate: true
-  enforcement_profile: pragmatic
-  fail_on: [BLOCKER, CRITICAL]
-  ignore_on: [INFO]
-  max_scan_retries: 3
-
-# Git automation (post-approval)
-git:
-  auto_commit: false
-  auto_push: false
-  auto_pr: false
-  auto_rebase: true
-  branch_prefix: feat/
-
-# Session limits
-session:
-  max_iteration_minutes: 15
-  max_total_minutes: 120
-  checkpoint_interval_minutes: 5  # Interactive checkpoint every N minutes
-  max_budget_usd: null         # null = unlimited
-  fail_fast_repeats: 2
-
-# Budget tracking
-budget:
-  currency: usd                # usd | eur
-  exchange_rate_eur: 0.92
-
-# Smart model selection (requires --enable-triage)
-model_selection:
-  enabled: true                # Auto-select models based on triage complexity
-  tiers:                       # Override default tier map per provider
-    claude:
-      simple: claude/sonnet    # Use sonnet even for simple tasks
-  role_overrides:              # Override level mapping per role
-    reviewer:
-      trivial: medium          # Reviewer always at least medium tier
-
-# Output
-output:
-  report_dir: ./.reviews
-  log_level: info              # debug | info | warn | error
 ```
-
-### Environment variables
-
-| Variable | Description |
-|----------|-------------|
-| `KJ_HOME` | Override config/sessions directory |
-| `KJ_SONAR_TOKEN` | SonarQube authentication token |
-
-## MCP Server
-
-Karajan Code exposes an MCP server for integration with any MCP-compatible host (Claude, Codex, custom agents).
-
-### Setup
-
-After `npm install -g karajan-code`, the MCP server is auto-registered in Claude and Codex configs. Manual config:
-
-```json
-{
-  "mcpServers": {
-    "karajan-mcp": {
-      "command": "karajan-mcp"
-    }
-  }
-}
+.karajan/roles/         # Project overrides (optional)
+~/.karajan/roles/       # Global overrides (optional)
+templates/roles/        # Built-in defaults (shipped with package)
 ```
 
-### MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `kj_init` | Initialize config and SonarQube |
-| `kj_doctor` | Check system dependencies |
-| `kj_config` | Show configuration |
-| `kj_scan` | Run SonarQube scan |
-| `kj_run` | Run full pipeline (with real-time progress notifications) |
-| `kj_resume` | Resume a paused session |
-| `kj_report` | Read session reports (supports `--trace`) |
-| `kj_roles` | List roles or show role templates |
-| `kj_agents` | List or change agent assignments (session/project/global scope) |
-| `kj_preflight` | Human confirms agent config before kj_run/kj_code executes |
-| `kj_code` | Run coder-only mode (with progress notifications) |
-| `kj_review` | Run reviewer-only mode (with progress notifications) |
-| `kj_plan` | Generate implementation plan (with progress notifications) |
-| `kj_status` | Live parsed status of current run (stage, agent, iteration, errors) |
+You can override any built-in role or create new ones. No code required. The agents read the role files and adapt their behavior. This means you can encode your team's conventions, domain rules, and quality standards — and every run of Karajan will apply them automatically.
 
-### MCP restart after version updates
+Use `kj roles show <role>` to inspect any template.
 
-If you update Karajan Code (for example `npm install -g karajan-code` to a new version) while your MCP host session is still open, the current `karajan-mcp` process may exit and the host can show `Transport closed`.
+## Zero-config by design
 
-This is expected behavior: the MCP server detects a version mismatch and exits so the host can spawn a fresh process with the new code.
+Karajan auto-detects and auto-configures everything it can:
 
-Quick recovery:
+- **TDD**: Detects test framework (vitest, jest, mocha) → auto-enables TDD
+- **SonarQube**: Auto-starts Docker container, generates config if missing
+- **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
 
-1. Restart your MCP host session (Claude/Codex/new terminal session).
-2. Verify the server is listed (`codex mcp list` or your host equivalent).
-3. Run a lightweight check (`kj_config`) before continuing with larger runs.
+No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
-### Recommended Companion MCPs
+## Why vanilla JavaScript?
 
-Karajan Code works great on its own, but combining it with these MCP servers gives your AI agent a complete development environment:
+Because it should be.
 
-| MCP | Why | Use case |
-|-----|-----|----------|
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | MCP bridge for [Planning Game](https://github.com/AgenteIA-Geniova/planning-game), an open-source agile project manager (tasks, sprints, estimation, XP). Only needed if you use Planning Game for task management | `kj_run` with `--pg-task` fetches full task context and updates card status on completion |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues, read repos directly from the agent | Combine with `--auto-push` for end-to-end: code → review → push → PR |
-| [**Serena**](https://github.com/oramasearch/serena) | Symbol-level code navigation (find references, go-to-definition) for JS/TS projects | Enable with `--enable-serena` to inject symbol context into coder/reviewer prompts |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Browser automation, screenshots, console/network inspection | Verify UI changes visually after `kj` modifies frontend code |
-| [**RTK**](https://github.com/rtk-ai/rtk) | Reduces LLM token consumption by 60-90% on Bash command outputs (git, test, build) | Install globally with `brew install rtk && rtk init --global` — all KJ agent commands automatically compressed |
+Karajan has **1847 tests** across 149 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.
 
-## Role Templates
+This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **52 releases in 23 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
 
-Each role has a `.md` template with instructions that the AI agent follows. Templates are resolved in priority order:
+## Recommended companions
 
-1. **Project override**: `.karajan/roles/<role>.md` (in project root)
-2. **User override**: `$KJ_HOME/roles/<role>.md`
-3. **Built-in**: `templates/roles/<role>.md` (shipped with the package)
-
-Use `kj roles show <role>` to inspect any template. Create a project override to customize behavior per-project.
-
-**Review variants**: `reviewer-strict`, `reviewer-relaxed`, `reviewer-paranoid` — selectable via `--mode` flag or `review_mode` config.
+| Tool | Why |
+|------|-----|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
+| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Agile project management (tasks, sprints, estimation) — XP-native |
+| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues directly from the agent |
+| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
 
 ## Contributing
 
@@ -479,19 +179,20 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1190+ tests with Vitest
-npm run test:watch    # Watch mode
+npm test              # Run 1847 tests with Vitest
 npm run validate      # Lint + test
 ```
 
-- Tests: [Vitest](https://vitest.dev/)
-- Commits: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`)
-- PRs: one purpose per PR, < 300 lines changed
+Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues) — that's the most useful contribution at this stage.
 
 ## Links
 
 - [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))
+- [Full documentation](https://karajancode.com/docs/)
 - [Changelog](CHANGELOG.md)
 - [Security Policy](SECURITY.md)
 - [License (AGPL-3.0)](LICENSE)
-- [Issues](https://github.com/manufosela/karajan-code/issues)
+
+---
+
+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.

package/package.json

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

package/src/cli.js

@@ -112,6 +112,8 @@ program
   .option("--no-smart-models", "Disable smart model selection")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
+  .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
+  .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
   .action(async (task, flags) => {
     await withConfig("run", flags, async ({ config, logger }) => {
       await runCommandHandler({ task, config, logger, flags });

package/src/commands/resume.js

@@ -1,10 +1,32 @@
 import { EventEmitter } from "node:events";
+import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display.js";
 
+function createCliAskQuestion() {
+  return async (question, context) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n\u2753 ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}
+
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
+  const quietMode = config.output?.quiet !== false;
 
   const emitter = new EventEmitter();
   let activityLog = null;
@@ -20,17 +42,19 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
     }
 
     if (!jsonMode) {
-      printEvent(event);
+      printEvent(event, { quiet: quietMode });
     }
   });
 
+  const askQuestion = createCliAskQuestion();
   const result = await resumeFlow({
     sessionId,
     answer: answer || null,
     config,
     logger,
     flags: flags || {},
-    emitter
+    emitter,
+    askQuestion
   });
 
   if (jsonMode || !answer) {

package/src/commands/run.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
@@ -6,6 +7,26 @@ import { printHeader, printEvent } from "../utils/display.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 
+function createCliAskQuestion() {
+  return async (question, context) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n\u2753 ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}
+
 export async function runCommandHandler({ task, config, logger, flags }) {
   // Best-effort session cleanup before starting
   try {
@@ -33,6 +54,8 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   const pgProject = flags?.pgProject || config.planning_game?.project_id || null;
 
   const jsonMode = flags?.json;
+  // Quiet mode is the default; --verbose disables it
+  const quietMode = config.output?.quiet !== false;
 
   const emitter = new EventEmitter();
   let activityLog = null;
@@ -48,7 +71,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
 
     if (!jsonMode) {
-      printEvent(event);
+      printEvent(event, { quiet: quietMode });
     }
   });
 
@@ -56,7 +79,8 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     printHeader({ task: task, config });
   }
 
-  const result = await runFlow({ task: task, config, logger, flags, emitter, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+  const askQuestion = createCliAskQuestion();
+  const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
   if (jsonMode) {
     console.log(JSON.stringify(result, null, 2));

package/src/config.js

@@ -123,7 +123,7 @@ const DEFAULTS = {
   planning_game: { enabled: false, project_id: null, codeveloper: null },
   becaria: { enabled: false, review_event: "becaria-review", comment_event: "becaria-comment", comment_prefix: true },
   git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
-  output: { report_dir: "./.reviews", log_level: "info" },
+  output: { report_dir: "./.reviews", log_level: "info", quiet: true },
   budget: {
     warn_threshold_pct: 80,
     currency: "usd",
@@ -366,6 +366,17 @@ function applyBecariaOverride(out, flags) {
   }
 }
 
+function applyOutputModeOverrides(out, flags) {
+  out.output = out.output || {};
+  // --verbose explicitly overrides quiet
+  if (flags.verbose === true) {
+    out.output.quiet = false;
+  } else if (flags.quiet === true) {
+    out.output.quiet = true;
+  }
+  // quiet defaults to true (set in DEFAULTS)
+}
+
 function applyMiscOverrides(out, flags) {
   if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
   if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
@@ -404,6 +415,7 @@ export function applyRunOverrides(config, flags) {
   applyMethodologyOverride(out, flags);
   applyBecariaOverride(out, flags);
   applyMiscOverrides(out, flags);
+  applyOutputModeOverrides(out, flags);
 
   return out;
 }

package/src/mcp/run-kj.js

@@ -62,6 +62,8 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   addOptionalValue(args, "--checkpoint-interval", options.checkpointInterval);
   addOptionalValue(args, "--pg-task", options.pgTask);
   addOptionalValue(args, "--pg-project", options.pgProject);
+  if (options.quiet === true) args.push("--quiet");
+  if (options.quiet === false) args.push("--verbose");
 
   const runEnv = {
     ...process.env,

package/src/mcp/tools.js

@@ -97,6 +97,7 @@ export const tools = [
         smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
         checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
         taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
+        quiet: { type: "boolean", description: "Suppress raw agent output lines, show only stage status (default: true). Set false for verbose output." },
         noSonar: { type: "boolean" },
         enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
         kjHome: { type: "string" },

package/src/orchestrator.js

@@ -1069,9 +1069,11 @@ async function runSingleIteration(ctx) {
   const becariaEnabled = Boolean(config.becaria?.enabled) && ctx.gitCtx?.enabled;
   logger.setContext({ iteration: i, stage: "iteration" });
 
+  const reviewerRetryCount = session.reviewer_retry_count || 0;
+  const maxReviewerRetries = config.session.max_reviewer_retries ?? config.session.fail_fast_repeats;
   emitProgress(emitter, makeEvent("iteration:start", { ...eventBase, stage: "iteration" }, {
     message: `Iteration ${i}/${config.max_iterations}`,
-    detail: { iteration: i, maxIterations: config.max_iterations }
+    detail: { iteration: i, maxIterations: config.max_iterations, reviewerRetryCount, maxReviewerRetries }
   }));
   logger.info(`Iteration ${i}/${config.max_iterations}`);
 

package/src/utils/display.js

@@ -245,8 +245,13 @@ const EVENT_HANDLERS = {
   "session:start": () => {},
 
   "iteration:start": (event, icon, elapsed) => {
+    const retryCount = event.detail?.reviewerRetryCount || 0;
+    const maxRetries = event.detail?.maxReviewerRetries;
+    const retrySuffix = retryCount > 0 && maxRetries
+      ? ` ${ANSI.dim}\u2014 reviewer retry ${retryCount}/${maxRetries}${ANSI.reset}`
+      : "";
     console.log(
-      `\n${ANSI.bold}${icon} Iteration ${event.detail?.iteration}/${event.detail?.maxIterations}${ANSI.reset}  ${elapsed}`
+      `\n${ANSI.bold}${icon} Iteration ${event.detail?.iteration}/${event.detail?.maxIterations}${ANSI.reset}${retrySuffix}  ${elapsed}`
     );
   },
 
@@ -418,9 +423,25 @@ const EVENT_HANDLERS = {
   }
 };
 
+/* ── Quiet-mode filter ──────────────────────────────────────── */
+
+/** Event types suppressed in quiet mode (raw agent output noise). */
+const QUIET_SUPPRESSED = new Set([
+  "agent:output"
+]);
+
 /* ── Main entry point ───────────────────────────────────────── */
 
-export function printEvent(event) {
+/**
+ * @param {object} event
+ * @param {object} [opts]
+ * @param {boolean} [opts.quiet] - When true, suppress raw agent output lines.
+ */
+export function printEvent(event, opts = {}) {
+  if (opts.quiet && QUIET_SUPPRESSED.has(event.type)) {
+    return;
+  }
+
   const icon = ICONS[event.type] || "\u2022";
   const elapsed = event.elapsed === undefined ? "" : `${ANSI.dim}[${formatElapsed(event.elapsed)}]${ANSI.reset}`;
   const status = event.status ? STATUS_ICON[event.status] || "" : "";