karajan-code 1.21.2 → 1.23.0

package/package.json

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

package/src/agents/host-agent.js

@@ -0,0 +1,38 @@
+/**
+ * Host Agent — delegates task execution to the MCP host AI via elicitation.
+ *
+ * Instead of spawning a subprocess, returns the prompt to the host AI
+ * (Claude, Codex, etc.) for direct execution. The host has full access
+ * to the codebase and tools — no subprocess overhead.
+ *
+ * Used when: the MCP host IS the same agent configured for a role.
+ */
+
+import { BaseAgent } from "./base-agent.js";
+
+export class HostAgent extends BaseAgent {
+  constructor(config, logger, { askHost }) {
+    super("host", config, logger);
+    this._askHost = askHost;
+  }
+
+  async runTask(task) {
+    const { prompt, onOutput } = task;
+
+    if (!this._askHost) {
+      return { ok: false, output: "", error: "Host agent has no askHost callback" };
+    }
+
+    if (onOutput) onOutput({ stream: "info", line: "[host-agent] Delegating to host AI..." });
+
+    const answer = await this._askHost(prompt);
+
+    if (!answer) {
+      return { ok: false, output: "", error: "Host AI declined or returned no response" };
+    }
+
+    if (onOutput) onOutput({ stream: "info", line: "[host-agent] Host AI completed task" });
+
+    return { ok: true, output: answer, exitCode: 0 };
+  }
+}

package/src/commands/init.js

@@ -204,6 +204,56 @@ async function scaffoldBecariaGateway(config, flags, logger) {
   logger.info("  4. Push the workflow files and enable 'kj run --enable-becaria'");
 }
 
+async function installSkills(logger, interactive) {
+  const projectDir = process.cwd();
+  const commandsDir = path.join(projectDir, ".claude", "commands");
+  const skillsTemplateDir = path.resolve(import.meta.dirname, "../../templates/skills");
+
+  let doInstall = true;
+  if (interactive) {
+    const wizard = createWizard();
+    try {
+      doInstall = await wizard.confirm("Install Karajan skills as slash commands (/kj-code, /kj-review, etc.)?", true);
+    } finally {
+      wizard.close();
+    }
+  }
+
+  if (!doInstall) {
+    logger.info("Skills installation skipped.");
+    return;
+  }
+
+  await ensureDir(commandsDir);
+
+  let installed = 0;
+  try {
+    const files = await fs.readdir(skillsTemplateDir);
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      const src = path.join(skillsTemplateDir, file);
+      const dest = path.join(commandsDir, file);
+      if (await exists(dest)) {
+        logger.info(`  ${file} already exists — skipping`);
+        continue;
+      }
+      const content = await fs.readFile(src, "utf8");
+      await fs.writeFile(dest, content, "utf8");
+      installed += 1;
+    }
+  } catch (err) {
+    logger.warn(`Could not install skills: ${err.message}`);
+    return;
+  }
+
+  if (installed > 0) {
+    logger.info(`Installed ${installed} Karajan skill(s) in .claude/commands/`);
+    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar");
+  } else {
+    logger.info("All skills already installed.");
+  }
+}
+
 export async function initCommand({ logger, flags = {} }) {
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
@@ -219,6 +269,7 @@ export async function initCommand({ logger, flags = {} }) {
   await handleConfigSetup({ config, configExists, interactive, configPath, logger });
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);
+  await installSkills(logger, interactive);
   await setupSonarQube(config, logger);
   await scaffoldBecariaGateway(config, flags, logger);
 }

package/src/commands/run.js

@@ -7,6 +7,12 @@ import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 
 export async function runCommandHandler({ task, config, logger, flags }) {
+  // Best-effort session cleanup before starting
+  try {
+    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
+    await cleanupExpiredSessions({ logger });
+  } catch { /* non-blocking */ }
+
   const requiredProviders = [
     resolveRole(config, "coder").provider,
     config.reviewer_options?.fallback_reviewer

package/src/mcp/orphan-guard.js

@@ -22,6 +22,53 @@ export function setupOrphanGuard({ intervalMs = DEFAULT_INTERVAL_MS, exitFn = ()
   return { timer, parentPid };
 }
 
+const DEFAULT_MEMORY_CHECK_MS = 30_000;
+const DEFAULT_WARN_HEAP_MB = 512;
+const DEFAULT_CRITICAL_HEAP_MB = 768;
+
+export function setupMemoryWatchdog({
+  intervalMs = DEFAULT_MEMORY_CHECK_MS,
+  warnHeapMb = DEFAULT_WARN_HEAP_MB,
+  criticalHeapMb = DEFAULT_CRITICAL_HEAP_MB,
+  onWarn = null,
+  onCritical = null,
+  exitFn = () => process.exit(1)
+} = {}) {
+  const warnBytes = warnHeapMb * 1024 * 1024;
+  const criticalBytes = criticalHeapMb * 1024 * 1024;
+  let warned = false;
+
+  const timer = setInterval(() => {
+    const { heapUsed, rss } = process.memoryUsage();
+
+    if (heapUsed >= criticalBytes) {
+      if (global.gc) {
+        try { global.gc(); } catch { /* --expose-gc not set */ }
+        const after = process.memoryUsage().heapUsed;
+        if (after < criticalBytes) return; // GC freed enough
+      }
+      const msg = `Memory critical: heap ${(heapUsed / 1024 / 1024).toFixed(0)}MB / rss ${(rss / 1024 / 1024).toFixed(0)}MB — exiting to prevent OOM`;
+      if (onCritical) onCritical(msg);
+      else process.stderr.write(`[karajan-mcp] ${msg}\n`);
+      clearInterval(timer);
+      exitFn();
+      return;
+    }
+
+    if (heapUsed >= warnBytes && !warned) {
+      warned = true;
+      const msg = `Memory warning: heap ${(heapUsed / 1024 / 1024).toFixed(0)}MB / rss ${(rss / 1024 / 1024).toFixed(0)}MB (critical at ${criticalHeapMb}MB)`;
+      if (onWarn) onWarn(msg);
+      else process.stderr.write(`[karajan-mcp] ${msg}\n`);
+    } else if (heapUsed < warnBytes) {
+      warned = false;
+    }
+  }, intervalMs);
+  timer.unref();
+
+  return { timer };
+}
+
 export function setupVersionWatcher({ pkgPath, currentVersion, exitFn = () => process.exit(0) } = {}) {
   if (!pkgPath) return null;
 

package/src/mcp/server-handlers.js

@@ -239,6 +239,12 @@ export async function handleRunDirect(a, server, extra) {
   await assertNotOnBaseBranch(config);
   const logger = createLogger(config.output.log_level, "mcp");
 
+  // Best-effort session cleanup before starting
+  try {
+    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
+    await cleanupExpiredSessions({ logger });
+  } catch { /* non-blocking */ }
+
   const requiredProviders = [
     resolveRole(config, "coder").provider,
     config.reviewer_options?.fallback_reviewer
@@ -287,22 +293,36 @@ export async function handleResumeDirect(a, server, extra) {
   const config = await buildConfig(a);
   const logger = createLogger(config.output.log_level, "mcp");
 
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_resume] started — session="${a.sessionId}"`);
+
   const emitter = new EventEmitter();
   emitter.on("progress", buildProgressHandler(server));
+  emitter.on("progress", (event) => runLog.logEvent(event));
   const progressNotifier = buildProgressNotifier(extra);
   if (progressNotifier) emitter.on("progress", progressNotifier);
 
   const askQuestion = buildAskQuestion(server);
-  const result = await resumeFlow({
-    sessionId: a.sessionId,
-    answer: a.answer || null,
-    config,
-    logger,
-    flags: a,
-    emitter,
-    askQuestion
-  });
-  return { ok: true, ...result };
+  try {
+    const result = await resumeFlow({
+      sessionId: a.sessionId,
+      answer: a.answer || null,
+      config,
+      logger,
+      flags: a,
+      emitter,
+      askQuestion
+    });
+    const ok = !result.paused && (result.approved !== false);
+    runLog.logText(`[kj_resume] finished — ok=${ok}`);
+    return { ok, ...result };
+  } catch (err) {
+    runLog.logText(`[kj_resume] failed: ${err.message}`);
+    throw err;
+  } finally {
+    runLog.close();
+  }
 }
 
 function buildDirectEmitter(server, runLog, extra) {

package/src/mcp/server.js

@@ -50,9 +50,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 });
 
 // --- Orphan process protection + version watcher ---
-import { setupOrphanGuard, setupVersionWatcher } from "./orphan-guard.js";
+import { setupOrphanGuard, setupVersionWatcher, setupMemoryWatchdog } from "./orphan-guard.js";
 setupOrphanGuard();
 setupVersionWatcher({ pkgPath: PKG_PATH, currentVersion: LOADED_VERSION });
+setupMemoryWatchdog();
 
 const transport = new StdioServerTransport();
 await mcpServer.connect(transport);

package/src/orchestrator.js

@@ -958,14 +958,45 @@ async function handleApprovedReview({ config, session, emitter, eventBase, coder
   return { action: "return", result };
 }
 
-async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults }) {
+async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults, logger, askQuestion, task }) {
+  // Escalate to Solomon / human before giving up
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "max_iterations", askQuestion, session,
+    iteration: config.max_iterations,
+    conflict: {
+      stage: "max_iterations",
+      task,
+      iterationCount: config.max_iterations,
+      maxIterations: config.max_iterations,
+      history: [{ agent: "pipeline", feedback: session.last_reviewer_feedback || "Max iterations reached without reviewer approval" }]
+    }
+  });
+
+  if (solomonResult.action === "continue") {
+    if (solomonResult.humanGuidance) {
+      session.last_reviewer_feedback = `User guidance: ${solomonResult.humanGuidance}`;
+    }
+    session.reviewer_retry_count = 0;
+    await saveSession(session);
+    return { approved: false, sessionId: session.id, reason: "max_iterations_extended", humanGuidance: solomonResult.humanGuidance };
+  }
+
+  if (solomonResult.action === "pause") {
+    return { paused: true, sessionId: session.id, question: solomonResult.question, context: "max_iterations" };
+  }
+
+  if (solomonResult.action === "subtask") {
+    return { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "max_iterations_subtask" };
+  }
+
+  // Solomon also couldn't resolve — fail
   session.budget = budgetSummary();
   await markSessionStatus(session, "failed");
   emitProgress(
     emitter,
     makeEvent("session:end", { ...eventBase, stage: "done" }, {
       status: "fail",
-      message: "Max iterations reached",
+      message: "Max iterations reached (Solomon could not resolve)",
       detail: { approved: false, reason: "max_iterations", iterations: config.max_iterations, stages: stageResults, budget: budgetSummary() }
     })
   );
@@ -978,7 +1009,7 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
   const refactorerRole = resolveRole(config, "refactorer");
   const pipelineFlags = resolvePipelineFlags(config);
   const repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
-  const coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent });
+  const coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent, askHost: askQuestion });
   const startedAt = Date.now();
   const eventBase = { sessionId: null, iteration: 0, stage: null, startedAt };
   const { budgetTracker, budgetLimit, budgetSummary, trackBudget } = createBudgetManager({ config, emitter, eventBase });
@@ -1109,7 +1140,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     if (iterResult.action === "retry") { i -= 1; }
   }
 
-  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config, stageResults: ctx.stageResults });
+  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config, stageResults: ctx.stageResults, logger, askQuestion, task });
 }
 
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {
@@ -1162,5 +1193,10 @@ export async function resumeFlow({ sessionId, answer, config, logger, flags = {}
   await saveSession(session);
 
   // Re-run the flow with the existing session context
-  return runFlow({ task, config: sessionConfig, logger, flags, emitter, askQuestion });
+  try {
+    return await runFlow({ task, config: sessionConfig, logger, flags, emitter, askQuestion });
+  } catch (err) {
+    await markSessionStatus(session, "failed");
+    throw err;
+  }
 }

package/src/roles/coder-role.js

@@ -1,6 +1,8 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
+import { isHostAgent } from "../utils/agent-detect.js";
+import { HostAgent } from "../agents/host-agent.js";
 
 function resolveProvider(config) {
   return (
@@ -11,9 +13,10 @@ function resolveProvider(config) {
 }
 
 export class CoderRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+  constructor({ config, logger, emitter = null, createAgentFn = null, askHost = null }) {
     super({ name: "coder", config, logger, emitter });
     this._createAgent = createAgentFn || defaultCreateAgent;
+    this._askHost = askHost;
   }
 
   async execute(input) {
@@ -22,7 +25,14 @@ export class CoderRole extends BaseRole {
       : input || {};
 
     const provider = resolveProvider(this.config);
-    const agent = this._createAgent(provider, this.config, this.logger);
+    const useHost = this._askHost && isHostAgent(provider);
+    const agent = useHost
+      ? new HostAgent(this.config, this.logger, { askHost: this._askHost })
+      : this._createAgent(provider, this.config, this.logger);
+
+    if (useHost) {
+      this.logger.info(`Host-as-coder: delegating to host AI (skipping ${provider} subprocess)`);
+    }
 
     const prompt = buildCoderPrompt({
       task: task || this.context?.task || "",

package/src/session-cleanup.js

@@ -1,48 +1,72 @@
 /**
  * Automatic cleanup of expired sessions.
- * Removes session directories older than session.expiry_days (default: 30).
+ *
+ * Policy (by status):
+ * - failed / stopped: removed after 1 day
+ * - approved: removed after 7 days
+ * - running (stale): marked failed + removed after 1 day (crash without cleanup)
+ * - paused: kept (user may want to resume)
+ *
+ * Runs automatically at the start of every kj_run (best-effort, non-blocking).
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getSessionRoot } from "./utils/paths.js";
 
-const DEFAULT_EXPIRY_DAYS = 30;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 
-async function tryRemoveOrphan({ sessionDir, dirName, cutoff, removed, errors, logger }) {
-  const stat = await fs.stat(sessionDir).catch(() => null);
-  if (!stat || stat.mtimeMs >= cutoff) return;
-  try {
-    await fs.rm(sessionDir, { recursive: true, force: true });
-    removed.push(dirName);
-    logger?.debug?.(`Orphan session dir removed: ${dirName}`);
-  } catch (error_) {
-    errors.push({ session: dirName, error: error_.message });
-  }
+const POLICY = {
+  failed:   { expiryMs: ONE_DAY_MS },
+  stopped:  { expiryMs: ONE_DAY_MS },
+  running:  { expiryMs: ONE_DAY_MS },   // stale — crashed without marking failed
+  approved: { expiryMs: 7 * ONE_DAY_MS },
+  paused:   null                          // never auto-delete
+};
+
+function shouldRemove(session) {
+  const status = session.status || "unknown";
+  const policy = POLICY[status];
+  if (!policy) return false;
+
+  const updatedAt = new Date(session.updated_at || session.created_at).getTime();
+  return Date.now() - updatedAt > policy.expiryMs;
 }
 
-async function tryCleanupSession({ sessionDir, dirName, cutoff, removed, errors, logger }) {
+async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger }) {
   const sessionFile = path.join(sessionDir, "session.json");
+  let session;
   try {
     const raw = await fs.readFile(sessionFile, "utf8");
-    const session = JSON.parse(raw);
-    const updatedAt = new Date(session.updated_at || session.created_at).getTime();
-    if (updatedAt < cutoff) {
-      await fs.rm(sessionDir, { recursive: true, force: true });
-      removed.push(dirName);
-      logger?.debug?.(`Session expired and removed: ${dirName}`);
-    }
+    session = JSON.parse(raw);
   } catch {
-    await tryRemoveOrphan({ sessionDir, dirName, cutoff, removed, errors, logger });
+    // Orphan dir without valid session.json — remove if older than 1 day
+    const stat = await fs.stat(sessionDir).catch(() => null);
+    if (stat && Date.now() - stat.mtimeMs > ONE_DAY_MS) {
+      try {
+        await fs.rm(sessionDir, { recursive: true, force: true });
+        removed.push(dirName);
+        logger?.debug?.(`Orphan session dir removed: ${dirName}`);
+      } catch (err) {
+        errors.push({ session: dirName, error: err.message });
+      }
+    }
+    return;
   }
-}
 
-export async function cleanupExpiredSessions({ config, logger } = {}) {
-  const expiryDays = config?.session?.expiry_days ?? DEFAULT_EXPIRY_DAYS;
-  if (expiryDays <= 0) return { removed: 0, errors: [] };
+  if (!shouldRemove(session)) return;
+
+  try {
+    await fs.rm(sessionDir, { recursive: true, force: true });
+    removed.push(dirName);
+    logger?.debug?.(`Session cleaned up: ${dirName} (status: ${session.status})`);
+  } catch (err) {
+    errors.push({ session: dirName, error: err.message });
+  }
+}
 
+export async function cleanupExpiredSessions({ logger } = {}) {
   const sessionRoot = getSessionRoot();
-  const cutoff = Date.now() - expiryDays * 24 * 60 * 60 * 1000;
 
   let entries;
   try {
@@ -57,7 +81,7 @@ export async function cleanupExpiredSessions({ config, logger } = {}) {
 
   for (const dir of dirs) {
     const sessionDir = path.join(sessionRoot, dir.name);
-    await tryCleanupSession({ sessionDir, dirName: dir.name, cutoff, removed, errors, logger });
+    await tryCleanupSession({ sessionDir, dirName: dir.name, removed, errors, logger });
   }
 
   if (removed.length > 0) {

package/src/session-store.js

@@ -83,8 +83,9 @@ export async function loadMostRecentSession() {
 
 export async function resumeSessionWithAnswer(sessionId, answer) {
   const session = await loadSession(sessionId);
-  if (session.status !== "paused") {
-    throw new Error(`Session ${sessionId} is not paused (status: ${session.status})`);
+  const resumable = new Set(["paused", "running", "failed", "stopped"]);
+  if (!resumable.has(session.status)) {
+    throw new Error(`Session ${sessionId} cannot be resumed (status: ${session.status})`);
   }
   const pausedState = session.paused_state;
   if (!pausedState) {

package/src/utils/agent-detect.js

@@ -30,4 +30,25 @@ export async function detectAvailableAgents() {
   return results;
 }
 
+/**
+ * Detect which AI agent is the current MCP host (if any).
+ * Returns the agent name ("claude", "codex", etc.) or null if not inside an agent.
+ */
+export function detectHostAgent() {
+  if (process.env.CLAUDECODE === "1" || process.env.CLAUDE_CODE === "1") return "claude";
+  if (process.env.CODEX_CLI === "1" || process.env.CODEX === "1") return "codex";
+  if (process.env.GEMINI_CLI === "1") return "gemini";
+  if (process.env.OPENCODE === "1") return "opencode";
+  return null;
+}
+
+/**
+ * Check if a given provider matches the current host agent.
+ * When true, we can skip subprocess spawning and delegate to the host.
+ */
+export function isHostAgent(provider) {
+  const host = detectHostAgent();
+  return host !== null && host === provider;
+}
+
 export { KNOWN_AGENTS };

package/templates/skills/kj-architect.md

@@ -0,0 +1,45 @@
+# kj-architect — Architecture Design
+
+Analyze the task and propose an architecture before implementation.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Read the task and understand the requirements
+2. Explore the existing codebase structure (`ls`, `find`, read key files)
+3. Identify the appropriate architectural approach
+4. Propose a design with tradeoffs
+
+## What to deliver
+
+### Architecture overview
+- Architecture type (layered, hexagonal, event-driven, etc.)
+- Key components/layers and their responsibilities
+- Data flow between components
+
+### API contracts (if applicable)
+- Endpoints with method, path, request/response schema
+- Error handling strategy
+
+### Data model changes (if applicable)
+- New entities/collections
+- Modified fields
+- Migration strategy
+
+### Tradeoffs
+- For each design decision: what was chosen, why, and what alternatives were considered
+- Constraints that influenced the design
+
+### Clarification questions
+- Any ambiguities that could affect the architecture
+- Decisions that need stakeholder input
+
+## Constraints
+
+- Follow existing patterns in the codebase — don't introduce a new architecture without justification
+- Keep it simple — the right amount of complexity is the minimum needed
+- Consider testability in every design decision
+- Do NOT start coding — this is design only

package/templates/skills/kj-code.md

@@ -0,0 +1,51 @@
+# kj-code — Coder with Guardrails
+
+Implement the task with TDD methodology and built-in quality checks.
+
+## Your task
+
+$ARGUMENTS
+
+## Methodology
+
+1. **Tests first**: Write or update tests BEFORE implementation
+2. **Implement**: Write minimal, focused code to pass the tests
+3. **Verify**: Run the test suite (`npm test` or project equivalent)
+4. **Check diff**: Run `git diff` and verify ONLY intended lines changed
+
+## Guardrails (MANDATORY)
+
+After writing code, verify ALL of these before reporting done:
+
+### Security check
+- [ ] No hardcoded credentials, API keys, or secrets in the diff
+- [ ] No `eval()`, `innerHTML` with user input, or SQL string concatenation
+- [ ] User input is validated/sanitized at system boundaries
+
+### Destructive operation check
+- [ ] No `rm -rf /`, `DROP TABLE`, `git push --force`, or similar in the diff
+- [ ] No `fs.rmSync` or `fs.rm` on paths derived from user input
+- [ ] No `process.exit()` in library code
+
+### Performance check
+- [ ] No synchronous file I/O (`readFileSync`, `writeFileSync`) in request handlers
+- [ ] No `document.write()` or layout thrashing patterns
+- [ ] No unbounded loops or missing pagination
+
+### TDD check
+- [ ] Source changes have corresponding test changes
+- [ ] Tests actually run and pass
+
+## File modification safety
+
+- NEVER overwrite existing files entirely — make targeted edits
+- After each edit, verify with `git diff` that ONLY intended lines changed
+- If unintended changes detected, revert immediately with `git checkout -- <file>`
+
+## Completeness check
+
+Before reporting done:
+- Re-read the task description
+- Check every requirement is addressed
+- Run the test suite
+- Verify no regressions

package/templates/skills/kj-discover.md

@@ -0,0 +1,24 @@
+# kj-discover — Gap Detection
+
+Analyze the task for gaps, ambiguities, and missing information BEFORE coding.
+
+## Your task
+
+$ARGUMENTS
+
+## What to do
+
+1. Read the task description carefully
+2. Identify gaps: missing requirements, implicit assumptions, ambiguities, contradictions
+3. Classify each gap: **critical** (blocks implementation), **major** (risks rework), **minor** (reasonable default exists)
+4. For each gap, suggest a specific question to resolve it
+5. Give a verdict: **ready** (no gaps) or **needs_validation** (gaps found)
+
+## Output
+
+Present findings clearly:
+- List each gap with severity and suggested question
+- Give your verdict at the end
+- If ready, say so and suggest proceeding to implementation
+
+Do NOT start coding. This is analysis only.

package/templates/skills/kj-review.md

@@ -0,0 +1,47 @@
+# kj-review — Code Review with Quality Gates
+
+Review the current changes against task requirements and quality standards.
+
+## Your task
+
+Review the changes in the current branch: $ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` (or appropriate base branch) to see all changes
+2. Review each changed file against the priorities below
+3. Report findings clearly
+
+## Review priorities (in order)
+
+1. **Security** — vulnerabilities, exposed secrets, injection vectors
+2. **Correctness** — logic errors, edge cases, broken tests
+3. **Tests** — adequate coverage, meaningful assertions
+4. **Architecture** — patterns, maintainability, SOLID principles
+5. **Style** — naming, formatting (only flag if egregious)
+
+## Scope constraint
+
+- **ONLY review files present in the diff** — do not flag issues in untouched files
+- Out-of-scope issues go as suggestions, never as blocking
+
+## Guardrails (auto-check)
+
+Flag as BLOCKING if any of these are detected in the diff:
+- [ ] Hardcoded credentials, API keys, or secrets
+- [ ] Entire file replaced (massive deletions + additions instead of targeted edits)
+- [ ] `eval()`, `innerHTML` with user input, SQL string concatenation
+- [ ] Missing test changes when source files changed (TDD violation)
+- [ ] `rm -rf`, `DROP TABLE`, `git push --force` or similar destructive operations
+
+## Output
+
+For each issue found:
+- **File and line** where the issue is
+- **Severity**: critical / major / minor
+- **Description**: what's wrong
+- **Suggested fix**: how to fix it
+
+End with a clear verdict:
+- **APPROVED** — no blocking issues found
+- **REQUEST_CHANGES** — blocking issues listed above must be fixed

package/templates/skills/kj-run.md

@@ -0,0 +1,69 @@
+# kj-run — Full Pipeline (Skills Mode)
+
+Execute the complete Karajan pipeline as sequential skills.
+
+## Your task
+
+$ARGUMENTS
+
+## Pipeline steps (execute in order)
+
+### Step 1 — Discover (optional but recommended)
+Analyze the task for gaps before coding:
+- Identify missing requirements, ambiguities, contradictions
+- If critical gaps found, STOP and ask the user before proceeding
+- If ready, continue
+
+### Step 2 — Code (with guardrails)
+Implement the task:
+1. **Tests first** (TDD): write/update tests before implementation
+2. **Implement**: minimal, focused code to fulfill the task
+3. **Verify**: run the test suite
+4. **Security check**: no hardcoded secrets, no injection vectors, no destructive ops in the diff
+5. **Diff check**: run `git diff` and verify only intended lines changed
+6. If any guardrail fails, fix before proceeding
+
+### Step 3 — Review (self-review)
+Review your own changes against quality standards:
+1. Run `git diff main...HEAD` (or base branch)
+2. Check: security, correctness, tests, architecture, style (in that order)
+3. Flag blocking issues:
+   - Hardcoded credentials or secrets
+   - Entire files overwritten instead of targeted edits
+   - Missing tests for new code
+   - SQL injection, XSS, command injection
+   - Destructive operations
+4. If blocking issues found, fix them and re-review
+5. If clean, proceed
+
+### Step 4 — Test audit
+Verify test quality:
+1. Every changed source file has corresponding tests
+2. Run `npm test` (or equivalent) — all must pass
+3. No skipped tests for changed code
+4. If tests fail, fix before proceeding
+
+### Step 5 — Security scan
+Quick security audit on the diff:
+1. Scan for OWASP top 10 in changed files
+2. Check for leaked secrets, injection vectors, missing auth
+3. If critical/high findings, fix before proceeding
+
+### Step 6 — Sonar (if available)
+If SonarQube is running (`docker ps | grep sonarqube`):
+1. Run `npx @sonar/scan`
+2. Check quality gate
+3. Fix blockers and critical issues
+
+### Step 7 — Commit
+If all steps pass:
+1. Stage changed files: `git add <specific files>`
+2. Commit with conventional commit message: `feat:`, `fix:`, `refactor:`, etc.
+3. Do NOT push unless the user explicitly asks
+
+## Important rules
+
+- **Never skip steps** — execute all applicable steps in order
+- **Fix before proceeding** — if a step finds issues, fix them before moving to the next
+- **Report progress** — after each step, briefly state what was done and the result
+- **Stop on critical** — if a critical security or correctness issue can't be fixed, stop and report

package/templates/skills/kj-security.md

@@ -0,0 +1,49 @@
+# kj-security — Security Audit
+
+Perform a security audit on the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to see all changes
+2. Scan for each vulnerability category below
+3. Report findings with severity and remediation
+
+## Vulnerability categories
+
+### Critical
+- [ ] Hardcoded secrets (API keys, passwords, tokens, connection strings)
+- [ ] SQL injection (string concatenation in queries)
+- [ ] Command injection (`exec`, `spawn` with unsanitized input)
+- [ ] Path traversal (file operations with user-controlled paths)
+
+### High
+- [ ] XSS (Cross-Site Scripting) — `innerHTML`, `dangerouslySetInnerHTML` with user input
+- [ ] Missing authentication/authorization checks on new endpoints
+- [ ] Insecure deserialization
+- [ ] SSRF (Server-Side Request Forgery) — fetch/request with user-controlled URLs
+
+### Medium
+- [ ] Missing input validation at system boundaries
+- [ ] Verbose error messages that leak internal details
+- [ ] Missing CSRF protection on state-changing endpoints
+- [ ] Insecure random number generation for security purposes
+
+### Low
+- [ ] Missing security headers
+- [ ] Dependencies with known vulnerabilities (check `npm audit`)
+- [ ] Console.log with sensitive data
+
+## Output
+
+For each finding:
+- **Severity**: critical / high / medium / low
+- **File and line**: where the issue is
+- **Category**: which vulnerability type
+- **Description**: what's wrong
+- **Remediation**: specific fix
+
+End with a summary: total findings by severity, and whether the code is safe to ship.

package/templates/skills/kj-sonar.md

@@ -0,0 +1,41 @@
+# kj-sonar — Static Analysis
+
+Run SonarQube/SonarCloud analysis and fix any issues found.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Check if SonarQube is running: `docker ps | grep sonarqube`
+2. If running, execute scan:
+   ```bash
+   npx @sonar/scan -Dsonar.host.url=http://localhost:9000 -Dsonar.projectKey=<project-key>
+   ```
+3. Check quality gate status:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/qualitygates/project_status?projectKey=<project-key>"
+   ```
+4. List issues:
+   ```bash
+   curl -s -u admin:admin "http://localhost:9000/api/issues/search?projectKeys=<project-key>&statuses=OPEN&ps=50"
+   ```
+
+## If SonarQube is not available
+
+Perform manual static analysis checks:
+- [ ] Cognitive complexity — functions over 15 should be refactored
+- [ ] Duplicated code blocks (3+ lines repeated)
+- [ ] Unused imports and variables
+- [ ] Empty catch blocks without comments
+- [ ] Nested ternary operations
+- [ ] `console.log` left in production code
+
+## Output
+
+Report:
+- Quality gate status (passed/failed)
+- Issues found by severity (blocker, critical, major, minor)
+- For each issue: file, line, rule, and suggested fix
+- Fix critical and blocker issues before proceeding

package/templates/skills/kj-test.md

@@ -0,0 +1,40 @@
+# kj-test — Test Quality Audit
+
+Evaluate test coverage and quality for the current changes.
+
+## Your task
+
+$ARGUMENTS
+
+## Steps
+
+1. Run `git diff main...HEAD` to identify changed source files
+2. For each changed source file, find the corresponding test file
+3. Run the test suite and check results
+4. Evaluate test quality
+
+## Checks
+
+### Coverage
+- [ ] Every changed source file has a corresponding test file
+- [ ] New functions/methods have at least one test
+- [ ] Edge cases are covered (null, empty, boundary values)
+
+### Quality
+- [ ] Tests have meaningful assertions (not just "no error thrown")
+- [ ] Test descriptions clearly state what is being tested
+- [ ] No tests that always pass (e.g., empty test body, `expect(true).toBe(true)`)
+- [ ] Mocks are minimal — prefer real implementations where feasible
+
+### Execution
+- [ ] Run `npm test` (or project equivalent) and report results
+- [ ] All tests pass
+- [ ] No skipped tests (`.skip`) for the changed code
+
+## Output
+
+Report:
+- Test files found/missing for each changed source file
+- Test execution results (pass/fail count)
+- Quality issues found
+- Suggestions for improving coverage