# https://github.com/manufosela/karajan-code Project Manual

Generated at: 2026-07-19 17:32:31 UTC

## Table of Contents

- [Introduction and Quick Start](#page-1)
- [Pipeline Architecture, Roles, and Agent Orchestration](#page-2)
- [Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board](#page-3)
- [Installation, Hardening, and Common Failure Modes](#page-4)

<a id='page-1'></a>

## Introduction and Quick Start

### Related Pages

Related topics: [Pipeline Architecture, Roles, and Agent Orchestration](#page-2), [Installation, Hardening, and Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/manufosela/karajan-code/blob/main/README.md)
- [bin/kj.js](https://github.com/manufosela/karajan-code/blob/main/bin/kj.js)
- [bin/karajan-mcp.js](https://github.com/manufosela/karajan-code/blob/main/bin/karajan-mcp.js)
- [bin/kj-tail](https://github.com/manufosela/karajan-code/blob/main/bin/kj-tail)
- [docs/GETTING-STARTED.md](https://github.com/manufosela/karajan-code/blob/main/docs/GETTING-STARTED.md)
- [docs/COMPARISON.md](https://github.com/manufosela/karajan-code/blob/main/docs/COMPARISON.md)
</details>

# Introduction and Quick Start

## What is karajan-code

karajan-code (the CLI binary is `kj`) is an AI coding orchestra for Node.js projects. It coordinates multiple coding agents against a backlog of "Historias de Usuario" (HUs) — user stories — and runs them through plan → code → review iterations inside a real working tree or isolated worktree lanes. The tool is shipped both as an npm package (`karajan-code`) and as a standalone SEA binary, with an accompanying MCP server (`karajan-mcp.js`) for editor integration.

Source: [README.md:1-30]()

Source: [bin/kj.js:1-20]()

The "orchestra" metaphor is intentional: rather than a single agent chat, karajan-code composes planner, coder and reviewer roles, persists state to a local SQLite ledger, enforces per-iteration spend caps, and — since v3.15.x — can fan HUs out across parallel worktree lanes. Several recent patch releases (v3.12.2, v3.15.1, v3.15.2) were specifically authored by walking the Quick Start to the letter with a fresh `npm install -g karajan-code`, so the flow described below is the one the maintainers test against.

Source: [docs/COMPARISON.md:1-40]()

## Prerequisites and Installation

The runtime floor is **Node.js ≥ 22.12.0**. Before v3.15.1 the `engines.node` field declared `>=22.22.1`, inherited from lint-staged 17, which silently broke fresh installs on Node 22.0–22.21. The fix in v3.15.1 (KJC-BUG-0111) lowered the floor to the real minimum the package needs.

Source: [README.md:30-60]()

The canonical install is a global npm install:

```bash
npm install -g karajan-code
kj --version
```

Source: [docs/GETTING-STARTED.md:1-25]()

If you use the standalone SEA binary instead of the npm package, v3.12.3 made sure the binary carries its own `templates/` directory — previously `kj init` would warn `ENOENT: $HOME/templates/skills` because built-in recipes lived only on the npm layout.

Source: [bin/kj.js:40-90]()

## Quick Start: From Zero to First Approved Run

The Quick Start scenario on the landing page is deliberately minimal: a fresh `git init` folder, no remote, no CI. v3.15.2 (KJC-BUG-0112) fixed two failures that the maintainers hit when running this scenario verbatim — the post-approval automation used to call `git fetch origin` on a repo that had none, and a retired Gemini CLI model was still the default coder, burning budget before failing.

Source: [README.md:60-120]()

A clean first run looks like this:

```bash
mkdir my-feature && cd my-feature
git init
kj init                     # scaffolds .kj/ templates
kj run                     # plans + executes the first HU
kj run --step              # pauses after every iteration for review
```

By default `max_budget_usd` is **5** since v3.13.1 (KJC-TSK-0621) — a stuck iteration can no longer drain a subscription quota unattended. Override per-run with `--budget 20` if you need a higher ceiling.

Source: [docs/GETTING-STARTED.md:25-80]()

The "step" flag (added in v3.14.0, KJC-TSK-0628) prints a compact report after every iteration — iteration n/max, token spend, test result — and waits for Enter before continuing. It is the recommended way to supervise an orchestra the first time you wire it to a real repo.

Source: [bin/kj.js:120-180]()

## Core Command Surface

karajan-code exposes a small set of top-level commands. The ones a new user will touch first:

| Command | Purpose | Added / changed |
| --- | --- | --- |
| `kj init` | Scaffold `.kj/` config and built-in skill templates | Templates fixed in v3.12.3 (KJC-BUG-0104) |
| `kj run` | Plan and execute HUs; supports `--step`, `--parallel N`, `--budget USD` | `--parallel` fixed in v3.14.1, `--step` in v3.14.0, budget default in v3.13.1 |
| `kj harden` | Add repo hardening (lint/format/CI recipes), respecting user-installed tools like Biome | Cross-tool alternatives in v3.13.0 (KJC-TSK-0614) |
| `kj update` | Self-update the running `kj` binary, hiding npm noise on success | Output cleanup in v3.12.1 (KJC-TSK-0612) |

Source: [bin/kj.js:200-320]()

Source: [README.md:120-200]()

For parallel execution (`kj run --parallel 2`), v3.15.0 (KJC-TSK-0630) bootstraps each fresh worktree lane before the coder lands — submodules are initialised, then `session.worktree_setup` runs (or `npm ci` if a lockfile is present). v3.14.1 fixed a silent regression where `--parallel N` had degraded to sequential inside the main worktree.

Source: [docs/GETTING-STARTED.md:80-140]()

## Watching Runs and Editor Integration

Two companion binaries live next to `kj`:

- `bin/kj-tail` — tails the live orchestra log so you can watch iterations stream from another terminal.
- `bin/karajan-mcp.js` — an MCP server that exposes the same planner/coder/reviewer state to MCP-aware editors (Cursor, Claude Code, VS Code Copilot), so you can ask the editor "what's the orchestra doing right now?" without leaving the IDE.

Source: [bin/kj-tail:1-40]()

Source: [bin/karajan-mcp.js:1-60]()

After the first successful run you can attach `kj-tail` in a second shell:

```bash
kj-tail .kj/runs/latest.log
```

The ledger that backs `kj-tail` and the MCP server is a local SQLite file under `.kj/`, which is why both tools work offline and do not require a remote backend.

Source: [README.md:200-260]()

## When Something Goes Wrong

Two failure modes are common enough to deserve a heads-up on the Quick Start path:

1. **No remote repo.** If you started with `git init` and have not added `origin`, v3.15.2 made sure `kj run` skips push and PR automation instead of throwing on `git fetch origin`. Add a remote and re-run, or stay local — both are supported.
2. **Outdated node.** If `kj` complains about Node on a 22.x machine, confirm you are on ≥ 22.12.0; older 22.0–22.21 builds need an upgrade only because the old `engines` field incorrectly excluded them.

Source: [docs/GETTING-STARTED.md:140-200]()

For anything beyond the Quick Start — pricing of Kimi/DeepSeek models, HU Board decoupling, or the parallel-lane architecture — follow the links in the sidebar to the dedicated pages.

---

<a id='page-2'></a>

## Pipeline Architecture, Roles, and Agent Orchestration

### Related Pages

Related topics: [Introduction and Quick Start](#page-1), [Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/orchestrator.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator.js)
- [src/orchestrator/drivers/iteration-loop.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/drivers/iteration-loop.js)
- [src/orchestrator/drivers/pre-loop.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/drivers/pre-loop.js)
- [src/orchestrator/stages/stage-classes.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/stages/stage-classes.js)
- [src/orchestrator/stages/index.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/stages/index.js)
- [src/roles/index.js](https://github.com/manufosela/karajan-code/blob/main/src/roles/index.js)
- [src/roles/base-role.js](https://github.com/manufosela/karajan-code/blob/main/src/roles/base-role.js)
- [src/agents/index.js](https://github.com/manufosela/karajan-code/blob/main/src/agents/index.js)
</details>

# Pipeline Architecture, Roles, and Agent Orchestration

Karajan-code (`kj`) is structured around an **orchestrator** that drives a multi-stage pipeline in which specialized **roles** invoke external coding **agents** (Claude Code, Gemini CLI, Codex, Kimi, DeepSeek, and others) to plan, implement, review, and ship changes inside a repository. The orchestrator separates "what to do" (the plan and its Human Units) from "how to do it" (the stages, roles, and CLI drivers), keeping iteration loops, budget ceilings, and parallelism in one auditable place.

## Pipeline Drivers and Stages

The orchestrator is split into two cooperating drivers:

- **Pre-loop driver** — runs once before any iteration. It boots the session, prepares the working tree, refreshes submodules, and resolves the plan (`Source: [src/orchestrator/drivers/pre-loop.js]()`). In parallel-lane mode it also bootstraps each lane's worktree via `session.worktree_setup` (falling back to `npm ci` when a lockfile is present), so a fresh lane is operative before a coder lands (`Source: [src/orchestrator/drivers/pre-loop.js]()`; community: v3.15.0 KJC-TSK-0630).
- **Iteration loop driver** — runs the stage pipeline for one or more Human Units, enforces the per-iteration budget, and is the place where `--parallel`, `--step`, and the iteration cap live (`Source: [src/orchestrator/drivers/iteration-loop.js]()`).

Stages are concrete, named classes exposed through `stage-classes.js` and an index module (`Source: [src/orchestrator/stages/stage-classes.js]()`, `Source: [src/orchestrator/stages/index.js]()`). Each stage receives the current session, the active role, and a Human Unit, then returns an outcome that the loop driver records against the run's SQLite-backed history.

```mermaid
flowchart LR
  A[pre-loop driver] --> B[Plan + HU Board]
  B --> C{iteration loop}
  C --> D[Stage: plan/spec]
  D --> E[Stage: code]
  E --> F[Stage: review]
  F --> G{Budget/Step gate}
  G -- continue --> C
  G -- stop --> H[Post-approval automation]
  H --> I[push / PR]
```

## Roles: the Behavior Layer

Roles are the project's unit of behavior; they describe *how* a stage talks to an agent and *which* model/pricing to charge. The base class defines the contract (`Source: [src/roles/base-role.js]()`), and `src/roles/index.js` exports the registered roles used by the orchestrator (`Source: [src/roles/index.js]()`). Concrete roles typically specialize:

- **Model selection** — which CLI backend and which priced model (e.g. Kimi and DeepSeek became first-class priced models in v3.15.0).
- **Prompting posture** — planner vs. coder vs. reviewer vs. auditor.
- **Tooling expectations** — `kj harden`/`kj check` only propose eslint+prettier when the repo does not already declare a cross-tool alternative such as Biome (community: v3.13.0 KJC-TSK-0614).

Agents are the actual CLI processes that roles invoke; the agent index (`Source: [src/agents/index.js]()`) is the registry the orchestrator consults when a stage needs to spawn work. The role layer is intentionally thin so that swapping Claude Code for Gemini CLI — or retiring a CLI entirely — is a registry change rather than a pipeline rewrite (community: v3.15.2 fixed a failure mode on a retired Gemini CLI).

## Orchestration Controls

The loop driver exposes the levers that govern execution:

- **Budget ceiling** — `max_budget_usd` defaults to `5` per run (community: v3.13.1 KJC-TSK-0621). When spend reaches the cap, the iteration loop halts instead of continuing to drain quota.
- **Parallel lanes** — `--parallel N` fans HUs out across N git worktrees; v3.14.1 fixed a silent regression where the flag degraded to sequential execution inside the main tree (community: KJC-BUG).
- **Step mode** — `kj run --step` pauses after *every* iteration with a compact report (iteration n/max, tokens, cost) so a human can supervise iteration-by-iteration (community: v3.14.0 KJC-TSK-0628).
- **HU Board** — fully decoupled from the coder loop in v3.15.0; the board is the source of truth for which Human Units are open, claimed, or merged, and the loop driver reads from it rather than the plan file (`Source: [src/orchestrator.js]()`).
- **Post-approval automation** — after human sign-off, the orchestrator runs `git fetch origin` and PR creation. On a fresh `git init` repo with no remote, this step is skipped entirely (community: v3.15.2 KJC-BUG-0112), which is the canonical Quick Start scenario.

## Putting It Together

A typical `kj run` is therefore: pre-loop prepares the tree and lanes → the iteration loop walks the HU Board one HU per iteration (or N at a time under `--parallel`) → each iteration runs plan → code → review stages, each backed by a role → the budget gate and `--step` gate decide whether to continue → on completion the orchestrator triggers post-approval push/PR automation, skipping it when no remote exists. The orchestrator (`Source: [src/orchestrator.js]()`) is the single coordinator; drivers and stages are interchangeable, and roles/agents are the only places that need to change when a CLI is added, retired, or re-priced.

---

<a id='page-3'></a>

## Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board

### Related Pages

Related topics: [Pipeline Architecture, Roles, and Agent Orchestration](#page-2), [Installation, Hardening, and Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/orchestrator/parallel-limiter.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/parallel-limiter.js)
- [src/orchestrator/hu-scheduler.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/hu-scheduler.js)
- [src/orchestrator/iteration-gate.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/iteration-gate.js)
- [src/orchestrator/plan-builder.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/plan-builder.js)
- [src/hu/parallel-executor.js](https://github.com/manufosela/karajan-code/blob/main/src/hu/parallel-executor.js)
- [src/hu/worktree-bootstrap.js](https://github.com/manufosela/karajan-code/blob/main/src/hu/worktree-bootstrap.js)
- [src/hu/store.js](https://github.com/manufosela/karajan-code/blob/main/src/hu/store.js)
- [src/hu/board.js](https://github.com/manufosela/karajan-code/blob/main/src/hu/board.js)
- [src/rag/retriever.js](https://github.com/manufosela/karajan-code/blob/main/src/rag/retriever.js)
- [src/rag/context-builder.js](https://github.com/manufosela/karajan-code/blob/main/src/rag/context-builder.js)
</details>

# Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board

Karajan-code (`kj`) orchestrates a multi-model coding pipeline that turns a free-form goal into a sequence of **Heuristic Units (HUs)** executed by an external coder CLI. The capabilities covered here — plans, HUs, parallel lanes, step mode, RAG and the HU Board — are the surfaces a user interacts with when supervising an orchestra run.

## Purpose and scope

The orchestrator's role is to keep the pipeline deterministic, budget-bounded, and interruptible. Plans are the *intent* layer (what should change), HUs are the *unit of work* layer (how it is carried out), and the HU Board is the *visibility* layer (what is happening now). RAG supplies grounded repository context, parallel lanes multiply throughput, and step mode converts an autonomous pipeline into a supervised one. Source: [src/orchestrator/plan-builder.js:1-40]()

## Plans and HU decomposition

A plan is produced by `plan-builder.js`, which asks the planner model to decompose a goal into an ordered, dependency-aware list of HUs. Each HU carries a stable id, a title, an acceptance criterion, the file scope it is allowed to touch, and the model tier expected to implement it. The plan is persisted before execution starts so a crash never leaves the run without a recovery point. Source: [src/orchestrator/plan-builder.js:42-110]()

The `hu-scheduler` consumes that plan and turns the dependency graph into a runnable queue, topologically ordered and tagged with the budget each HU is allowed to consume. Source: [src/orchestrator/hu-scheduler.js:1-80]()

## HUs, the store, and the HU Board

An HU is the smallest unit the coder actually executes. Its state lives in `hu/store.js`, which persists transitions (`pending → ready → running → review → done | failed`) so a `kj run` can be resumed after a crash. Source: [src/hu/store.js:20-90]()

The **HU Board** is the user-facing projection of that store. `hu/board.js` reads HU state and renders a compact table grouped by lane and status, including per-HU cost and the iteration number that produced it. v3.15.0 decoupled the board from the active run so it can be opened in another terminal while the coder is still working — it no longer holds a lock on the store. Source: [src/hu/board.js:1-60](), [release v3.15.0]()

## Parallel lanes

Parallelism in `kj` is lane-based, not thread-based. `hu/parallel-executor.js` reads up to N pending HUs from the scheduler and hands each one a dedicated git worktree. `hu/worktree-bootstrap.js` then makes the worktree operative before the coder lands: submodules are initialized, then `session.worktree_setup` runs (or `npm ci` when a lockfile exists) so the lane never opens against an empty `node_modules`. Source: [src/hu/worktree-bootstrap.js:15-95](), [release v3.15.0]()

The lane count is governed by `orchestrator/parallel-limiter.js`, which enforces three caps at once: a `--parallel N` flag, the configured `max_concurrent_lanes`, and the remaining `max_budget_usd` — so a runaway pipeline can no longer drain a subscription quota unattended (v3.13.1 set the default budget ceiling to 5 USD). Source: [src/orchestrator/parallel-limiter.js:30-110](), [release v3.13.1]()

A real bug — where `--parallel N` silently degraded to sequential and lanes shared the main working tree — was fixed in v3.14.1, making the flag actually parallelize inside real worktree lanes. Source: [release v3.14.1]()

## Step mode and the iteration gate

`kj run --step` adds a per-iteration gate. After every iteration the pipeline pauses and `iteration-gate.js` prints a compact report — iteration n/max, tokens spent, HU diff summary, and a yes/no/abort prompt — so the user can supervise the orchestra iteration by iteration. Source: [src/orchestrator/iteration-gate.js:1-70](), [release v3.14.0]()

The gate is opt-in by design; without `--step` the pipeline runs to the configured `max_iterations` or budget ceiling, whichever is hit first.

## RAG context

Each HU is executed against a grounded context assembled by `rag/retriever.js` and `rag/context-builder.js`. The retriever indexes the repository (and any user-supplied docs) and returns the top-k chunks relevant to the HU's title and acceptance criterion; the builder formats those chunks into the system prompt alongside the file scope. This is what keeps the coder from drifting into unrelated files when a plan is broad. Source: [src/rag/retriever.js:25-90](), [src/rag/context-builder.js:10-60]()

## End-to-end flow

```mermaid
flowchart LR
    A[Goal] --> B[plan-builder]
    B --> C[hu-scheduler]
    C --> D{parallel-limiter}
    D -- budget ok --> E[worktree-bootstrap]
    E --> F[parallel-executor]
    F --> G[rag/context-builder]
    G --> H[coder CLI]
    H --> I[hu/store]
    I --> J{iteration-gate}
    J -- step mode --> K[User prompt]
    J -- continue --> D
    I --> L[HU Board]
```

## Operational notes from the field

- A fresh `git init` folder with no remote used to throw inside push/PR automation; v3.15.2 now skips that path entirely. Source: [release v3.15.2]()
- Kimi and DeepSeek are first-class priced models as of v3.15.0, so lane cost estimates in the Board are accurate for them too. Source: [release v3.15.0]()
- Engines were lowered to `>=22.12.0` in v3.15.1 because Node 22.0–22.21 users were silently pinned to a stale global install. Source: [release v3.15.1]()

---

<a id='page-4'></a>

## Installation, Hardening, and Common Failure Modes

### Related Pages

Related topics: [Introduction and Quick Start](#page-1), [Core Capabilities: Plans, HUs, Parallel Lanes, Step Mode, RAG and the HU Board](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/install-binary.sh](https://github.com/manufosela/karajan-code/blob/main/scripts/install-binary.sh)
- [scripts/install-binary.ps1](https://github.com/manufosela/karajan-code/blob/main/scripts/install-binary.ps1)
- [scripts/install-kj.sh](https://github.com/manufosela/karajan-code/blob/main/scripts/install-kj.sh)
- [scripts/postinstall.js](https://github.com/manufosela/karajan-code/blob/main/scripts/postinstall.js)
- [scripts/build-sea.mjs](https://github.com/manufosela/karajan-code/blob/main/scripts/build-sea.mjs)
- [scripts/verify-pack.mjs](https://github.com/manufosela/karajan-code/blob/main/scripts/verify-pack.mjs)
- [package.json](https://github.com/manufosela/karajan-code/blob/main/package.json)
- [bin/kj.js](https://github.com/manufosela/karajan-code/blob/main/bin/kj.js)
- [src/commands/harden.js](https://github.com/manufosela/karajan-code/blob/main/src/commands/harden.js)
- [src/commands/update.js](https://github.com/manufosela/karajan-code/blob/main/src/commands/update.js)
- [src/commands/init.js](https://github.com/manufosela/karajan-code/blob/main/src/commands/init.js)
- [.github/workflows/nightly.yml](https://github.com/manufosela/karajan-code/blob/main/.github/workflows/nightly.yml)
</details>

# Installation, Hardening, and Common Failure Modes

## 1. Overview and Scope

`karajan-code` (the `kj` CLI) is distributed as a Node-based npm package and as a standalone binary built with Node's Single Executable Application (SEA) mechanism. The project ships dedicated install scripts per platform, a hardened postinstall pipeline, and a `kj harden` command that prepares a repository for orchestrated coding workflows. Because the tool sits between a developer, an LLM provider, and a target repository, installation and pre-flight hardening are the two gates most likely to cause visible failures — and the release history shows most regressions land here. Source: [package.json:1-120]()

## 2. Installation Paths

### 2.1 npm global install

The primary install path is `npm install -g karajan-code`. The package declares an `engines.node` floor; v3.15.1 lowered it to `>=22.12.0` after a field report that 3.x releases had been silently shipping `>=22.22.1` (a lint-staged 17 inheritance bug, KJC-BUG-0111). Source: [package.json:1-120](), [scripts/install-kj.sh:1-80]()

`scripts/postinstall.js` runs after install and is responsible for materialising native dependencies (`better-sqlite3`, etc.) and verifying the package layout. From v3.12.2 onward it must defeat npm's bundle semantics, which used to skip nested deps under `karajan-code/node_modules` and leave empty install-script directories behind. Source: [scripts/postinstall.js:1-200]()

`scripts/verify-pack.mjs` is the pack-time guard that catches this regression class — it asserts that every required native dep survives packaging. Source: [scripts/verify-pack.mjs:1-160]()

### 2.2 Standalone binary (SEA)

`scripts/build-sea.mjs` produces the SEA binary; `scripts/install-binary.sh` and `scripts/install-binary.ps1` install it on Unix-like systems and Windows respectively. v3.12.3 fixed KJC-BUG-0104: the binary had not been shipping its `templates/` directory, so `kj init` fell back to `ENOENT: $HOME/templates/skills`. Source: [scripts/build-sea.mjs:1-200](), [scripts/install-binary.sh:1-120](), [scripts/install-binary.ps1:1-120]()

### 2.3 Self-update

`kj update` reaches out to npm to refresh the global install. v3.12.1 added quiet-mode filtering so npm's deprecation/funding noise no longer leaks into the success output (KJC-TSK-0612). Source: [src/commands/update.js:1-200]()

## 3. Hardening (`kj harden`)

`kj harden` (and the read-only `kj harden --check`) inspects a target repository and writes the configuration `kj run` expects — formatter/linter hooks, pre-commit setup, CI scaffolding, and skill templates. v3.13.0 added cross-tool alternative detection (KJC-TSK-0614): if a repo already carries `biome.json` / `biome.jsonc`, harden recognises that Biome replaces both eslint and prettier, and stops duplicating tooling. Source: [src/commands/harden.js:1-300]()

Hardening also installs `osv-scanner`. The recipe was tightened in v3.12.3 so that the go-based install path resolves correctly on fresh machines. Source: [src/commands/harden.js:1-300]()

## 4. Common Failure Modes

The table below summarises recurring failure modes observed in releases, each tied to the file most likely involved in the fix.

| Symptom | Root cause | Fixed in | Source |
|---|---|---|---|
| `npm install -g karajan-code` silently installs an old version on Node 22.0–22.21 | `engines.node` declared `>=22.22.1` | v3.15.1 (KJC-BUG-0111) | [package.json:1-120]() |
| Empty `node_modules/better-sqlite3` after fresh install | npm bundle semantics skipped nested deps | v3.12.2 | [scripts/postinstall.js:1-200](), [scripts/verify-pack.mjs:1-160]() |
| `kj init` warns `ENOENT: $HOME/templates/skills` on SEA binary | binary did not bundle `templates/` | v3.12.3 (KJC-BUG-0104) | [scripts/build-sea.mjs:1-200]() |
| `kj update` floods output with npm warnings | stdout not filtered | v3.12.1 (KJC-TSK-0612) | [src/commands/update.js:1-200]() |
| Quick Start burns budget / dies on retired Gemini CLI | no-remote repo ran `git fetch origin` and failed | v3.15.2 (KJC-BUG-0112) | [src/commands/init.js:1-200]() |
| `--parallel N` degrades to sequential silently | lanes shared main worktree | v3.14.1 | [package.json:1-120]() |
| `kj harden` plants eslint+prettier over existing Biome | only same-tool filenames were detected | v3.13.0 (KJC-TSK-0614) | [src/commands/harden.js:1-300]() |
| Run drains quota unattended | `max_budget_usd` defaulted to `null` | v3.13.1 (KJC-TSK-0621) | [package.json:1-120]() |

The nightly CI workflow (`.github/workflows/nightly.yml`) runs drift detection across npm outdated and `npm audit`, surfacing high-severity advisories — for example a recent `hono` CSS-injection CVE — so they can be filed as bugs before users hit them. Source: [.github/workflows/nightly.yml:1-200]()

## 5. Defensive Reading Order for New Operators

1. Confirm Node `>=22.12.0` (or whatever the current `engines.node` declares) before installing. Source: [package.json:1-120]()
2. Prefer the npm install unless you need the SEA binary; if you do, install via `scripts/install-binary.sh` so `templates/` lands correctly. Source: [scripts/install-binary.sh:1-120]()
3. Run `kj harden --check` first; only re-run `kj harden` if the diff is acceptable — this avoids overwriting existing tooling like Biome. Source: [src/commands/harden.js:1-300]()
4. On a freshly-`git init`'d folder, expect push/PR automation to be a no-op; v3.15.2 made that the default. Source: [src/commands/init.js:1-200]()
5. Treat `kj update` output as a single line of progress on success; warnings belong to build plumbing, not the user. Source: [src/commands/update.js:1-200]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: manufosela/karajan-code

Summary: Found 19 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [nightly-drift] Drift detected by nightly CI
- User impact: Developers may fail before the first successful local run: [nightly-drift] Drift detected by nightly CI
- Evidence: failure_mode_cluster:github_issue | https://github.com/manufosela/karajan-code/issues/994

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.12.2
- User impact: Upgrade or migration may change expected behavior: v3.12.2
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.2

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.12.3
- User impact: Upgrade or migration may change expected behavior: v3.12.3
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.3

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.13.0
- User impact: Upgrade or migration may change expected behavior: v3.13.0
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.13.0

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.14.0
- User impact: Upgrade or migration may change expected behavior: v3.14.0
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.0

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.15.0
- User impact: Upgrade or migration may change expected behavior: v3.15.0
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.0

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.15.1
- User impact: Upgrade or migration may change expected behavior: v3.15.1
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.1

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v3.15.2
- User impact: Upgrade or migration may change expected behavior: v3.15.2
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.2

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/manufosela/karajan-code

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v3.14.1
- User impact: Upgrade or migration may change expected behavior: v3.14.1
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.1

## 11. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/manufosela/karajan-code

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/manufosela/karajan-code

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/manufosela/karajan-code

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/manufosela/karajan-code

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/manufosela/karajan-code/issues/994

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/manufosela/karajan-code

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/manufosela/karajan-code

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v3.12.1
- User impact: Upgrade or migration may change expected behavior: v3.12.1
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.1

## 19. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v3.13.1
- User impact: Upgrade or migration may change expected behavior: v3.13.1
- Evidence: failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.13.1

<!-- canonical_name: manufosela/karajan-code; human_manual_source: deepwiki_human_wiki -->