Instead of running one AI agent and manually reviewing its output, kj orchestrates specialized roles — each executed by the AI agent you choose. The coder writes code, guards check for destructive patterns, SonarQube scans it, the reviewer checks it, and if issues are found, the coder gets another attempt. Roles define what to do; agents define who does it.
Executable Acceptance Tests (v2.4)
Each HU carries acceptance_tests: an array of shell commands Brain runs after every coder iteration. All pass → HU approved. Any fail → Brain reads the exact error output and sends a concrete diagnostic to the coder. No reviewer. No generic tester. Concrete pass/fail. Demo result: 6 HUs, 280 tests, 97% coverage, 0 vulnerabilities.
Karajan Brain (v2.0)
AI-powered central orchestrator that routes all role-to-role communication, enriches feedback with file hints, verifies outputs via git diff, executes direct actions (npm install, gitignore), and compresses role outputs for 40-70% token savings. Consults Solomon only on genuine dilemmas.
Solomon — AI Judge (v2.0)
Refined from pipeline boss to AI judge. Consulted only on genuine dilemmas: security-vs-deadline, conflicting quality gates, stalled loops, risk evaluation. Security issues bypass Solomon deterministically and go straight back to the coder.
Multi-Agent Pipeline
16 configurable roles: discover, triage, domain-curator, researcher, architect, planner, coder, refactorer, sonar, impeccable, reviewer, tester, security, solomon, commiter, hu-reviewer. Mandatory audit post-approval ensures generated code is certified clean before completing.
5 AI Agents
Claude, Codex, Gemini, Aider, and OpenCode. Mix and match — use Claude as coder and Codex as reviewer, or any combination. Extensible via plugins.
MCP Server
24 tools exposed via MCP — including kj_discover, kj_triage, kj_researcher, kj_architect for standalone role execution, kj_preflight for human-confirmed agent config, kj_board for HU Board management, kj_status for live parsed status, and kj_undo for reverting pipeline runs. Real-time progress notifications for all tools. Graceful restart after npm updates.
TDD Enforcement
Test changes required when source files change. The pipeline rejects iterations without matching tests.
Plugin System
Extend with custom agents via .karajan/plugins/. Auto-discovered at startup.
Pipeline Tracker
Cumulative progress view during kj_run — see which stages are done, running, or pending in real time via MCP and CLI.
Rate-Limit Standby
Auto-detects rate limits, parses cooldown times, waits with exponential backoff, and auto-resumes — up to 5 retries before asking a human.
Preflight Handshake
kj_preflight requires human confirmation of agent assignments before execution. 3-tier config: session > project > global.
Solomon — Pipeline Boss
Evaluates every reviewer rejection, classifies issues as critical vs. style-only, and can override style-only blocks. 6 rules including scope guard, reviewer overreach, and smart iteration control.
Intelligent Reviewer Mediation
Scope filter auto-defers out-of-scope reviewer issues instead of stalling the pipeline. Deferred issues tracked as tech debt and fed back to the coder.
Real-Time Monitoring
Stall detector, continuous heartbeats, max-silence guardrails, planner runtime cap. kj-tail for colorized live log. kj_status for parsed status.
BecarIA Gateway
Full CI/CD integration with GitHub PRs as source of truth. All agents post comments and reviews on PRs. Early PR creation, configurable dispatch events, and embedded workflow templates.
Pre-Execution Discovery
kj_discover analyzes tasks for gaps before coding begins. 5 modes: gap detection, Mom Test questions, Wendel behavior change checklist, START/STOP/DIFFERENT classification, and Jobs-to-be-Done generation.
Deterministic Guards
Output guard blocks destructive operations and credential leaks. Perf guard catches frontend anti-patterns. Intent classifier pre-triages obvious tasks without LLM cost. All configurable with custom patterns.
Impeccable Design Audit
Automated UI/UX quality gate. Audits changed frontend files for accessibility, performance, theming, responsive, and anti-pattern issues. Runs after SonarQube, applies fixes automatically.
SonarQube + SonarCloud
Dual static analysis: SonarQube (local Docker, blocking quality gates) and SonarCloud (cloud, advisory). Both run together in the same pipeline.
Standalone Role Commands
Run any pre-build role independently: kj discover, kj triage, kj researcher, kj architect. Available as both CLI commands and MCP tools.
Resilient Run
Auto-diagnoses failures and resumes crashed sessions — up to 2 retries. Non-recoverable errors (config, auth, missing agent) fail immediately. Configurable via session.max_auto_resumes.
Host-as-Coder
When the MCP host is the same agent as the coder (e.g., Claude calling kj_run with coder=claude), Karajan delegates directly — no subprocess, no overhead. All guardrails still apply.
Skills Mode
8 slash commands (/kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar) with built-in guardrails. No MCP needed — works directly in Claude Code.
Zero-Config Pipeline
Auto-detects TDD based on project test framework. Auto-manages SonarQube Docker lifecycle and config generation. Skips sonar/TDD for infra and doc tasks automatically. Simple tasks run lightweight (coder-only), complex tasks get full pipeline — automatically based on triage.
1925+ Automated Tests
130 test files covering every pipeline role, guard, config option, and MCP tool. Full suite runs in under 14 seconds with Vitest.
Codebase Health Audit
Read-only analysis across 5 dimensions: security, code quality (SOLID/DRY/KISS/YAGNI), performance, architecture, and testing. Generates a health report with A-F scores and prioritized recommendations without modifying any files.
HU Story Certification
Mandatory quality gate that evaluates user stories across 6 dimensions (JTBD context, user specificity, behavior change, control zone, time constraints, survivable experiment). Detects 7 antipatterns, rewrites weak stories, pauses for FDE context. Supports dependency graphs.
HU Board Dashboard
Web dashboard for visualizing HU stories and sessions across all projects. Kanban board, session timeline, quality scores. Docker-ready, auto-syncs from local files.
kj undo
Revert the last pipeline run with a soft reset or --hard. Safely undo changes when a run produces unexpected results.
kj status Dashboard
Terminal dashboard showing HU states, current stage, timing, and progress. MCP returns structured JSON for programmatic access.
Auto-Detect Stack
kj init scans package.json, go.mod, Cargo.toml and more to detect your framework and language. Auto-enables impeccable for frontend projects.
Telemetry (Opt-Out)
Anonymous usage statistics (version, OS, command, pipeline duration, success rate) to help improve Karajan. Fully opt-out with telemetry: false in config.
Documentation Links in Errors
All error messages include a direct URL to the relevant documentation page, making troubleshooting faster.
Zero API Costs
Runs on your existing AI subscriptions. No additional API keys or cloud services required. Pair with RTK for additional 60-90% token savings.
