karajan-code 1.57.0 → 1.58.1

package/src/orchestrator/stages/domain-curator-stage.js

@@ -0,0 +1,82 @@
+/**
+ * Domain Curator stage logic.
+ * Runs the Domain Curator role to discover and synthesize domain knowledge.
+ * Slots after Triage and before Researcher/Architect/Planner.
+ */
+
+import { DomainCuratorRole } from "../../roles/domain-curator-role.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+/**
+ * @param {Object} params
+ * @param {Object} params.config
+ * @param {Object} params.logger
+ * @param {Object} params.emitter
+ * @param {Object} params.eventBase
+ * @param {Object} params.session
+ * @param {Function} params.trackBudget
+ * @param {string[]} params.domainHints — from triage
+ * @param {Function & {interactive: boolean}} [params.askQuestion]
+ * @returns {Promise<{domainContext: string|null, stageResult: Object}>}
+ */
+export async function runDomainCuratorStage({ config, logger, emitter, eventBase, session, trackBudget, domainHints = [], askQuestion = null }) {
+  logger.setContext?.({ iteration: 0, stage: "domain-curator" });
+
+  emitProgress(
+    emitter,
+    makeEvent("domain-curator:start", { ...eventBase, stage: "domain-curator" }, {
+      message: "Domain Curator discovering domain knowledge",
+      detail: { domainHints, interactive: Boolean(askQuestion?.interactive) }
+    })
+  );
+
+  const start = Date.now();
+  const curator = new DomainCuratorRole({ config, logger });
+
+  let curatorOutput;
+  try {
+    curatorOutput = await curator.execute({
+      task: session.task,
+      domainHints,
+      askQuestion,
+      projectDir: config.projectDir || null
+    });
+  } catch (err) {
+    logger.warn(`Domain Curator threw: ${err.message}`);
+    curatorOutput = {
+      ok: true,
+      result: { selectedDomains: [], domainContext: null, domainsFound: 0, domainsUsed: 0, source: "error" },
+      summary: `Domain Curator error: ${err.message}`
+    };
+  }
+
+  trackBudget({
+    role: "domain-curator",
+    provider: "local",
+    model: null,
+    result: curatorOutput,
+    duration_ms: Date.now() - start
+  });
+
+  const domainContext = curatorOutput.result?.domainContext || null;
+
+  const stageResult = {
+    ok: curatorOutput.ok,
+    domainsFound: curatorOutput.result?.domainsFound || 0,
+    domainsUsed: curatorOutput.result?.domainsUsed || 0,
+    selectedDomains: curatorOutput.result?.selectedDomains || [],
+    source: curatorOutput.result?.source || "none",
+    hasDomainContext: Boolean(domainContext)
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("domain-curator:done", { ...eventBase, stage: "domain-curator" }, {
+      status: "ok",
+      message: curatorOutput.summary,
+      detail: stageResult
+    })
+  );
+
+  return { domainContext, stageResult };
+}

package/src/orchestrator/stages/triage-stage.js

@@ -99,6 +99,8 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
   const shouldDecompose = triageOutput.result?.shouldDecompose || false;
   const subtasks = triageOutput.result?.subtasks || [];
 
+  const domainHints = triageOutput.result?.domainHints || [];
+
   const stageResult = {
     ok: triageOutput.ok,
     level: triageOutput.result?.level || null,
@@ -106,7 +108,8 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     reasoning: triageOutput.result?.reasoning || null,
     taskType: triageOutput.result?.taskType || "sw",
     shouldDecompose,
-    subtasks
+    subtasks,
+    domainHints
   };
 
   const modelSelection = applyModelSelection(triageOutput, config, emitter, eventBase);

package/src/orchestrator.js

@@ -34,6 +34,7 @@ import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { msg, getLang } from "./utils/messages.js";
 import { PipelineContext } from "./orchestrator/pipeline-context.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage, runHuReviewerStage } from "./orchestrator/pre-loop-stages.js";
+import { runDomainCuratorStage } from "./orchestrator/stages/domain-curator-stage.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage, runImpeccableStage, runFinalAuditStage } from "./orchestrator/post-loop-stages.js";
 import { needsSubPipeline, runHuSubPipeline } from "./orchestrator/hu-sub-pipeline.js";
@@ -919,6 +920,23 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
     logger.warn(`Skill auto-install failed (non-blocking): ${err.message}`);
   }
 
+  // --- Domain Curator (after triage + skill auto-install, before planning phases) ---
+  const domainHints = triageResult.stageResult?.domainHints || [];
+  if (domainHints.length > 0 || config.projectDir) {
+    try {
+      const { domainContext, stageResult: dcStageResult } = await runDomainCuratorStage({
+        config, logger, emitter, eventBase, session, trackBudget,
+        domainHints, askQuestion
+      });
+      stageResults.domainCurator = dcStageResult;
+      if (domainContext) {
+        config = { ...config, domainContext };
+      }
+    } catch (err) {
+      logger.warn(`Domain Curator failed (non-blocking): ${err.message}`);
+    }
+  }
+
   // --- HU Reviewer auto-activation from triage (post-triage, no huFile needed) ---
   const triageRoles = new Set(triageResult.stageResult?.roles || []);
   if (triageRoles.has("hu-reviewer") && !stageResults.huReviewer) {

package/src/prompts/architect.js

@@ -9,7 +9,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, projectDir = null, language = "en" }) {
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en" }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
@@ -39,6 +39,10 @@ export async function buildArchitectPrompt({ task, instructions, researchContext
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (domainContext) {
+    sections.push(`## Domain Context\n${domainContext}`);
+  }
+
   if (researchContext) {
     sections.push(`## Research Context\n${researchContext}`);
   }

package/src/prompts/coder.js

@@ -33,7 +33,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null, projectDir = null, language = "en" }) {
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en" }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
@@ -56,6 +56,10 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (domainContext) {
+    sections.push(`## Domain Context\n${domainContext}`);
+  }
+
   if (plan) {
     sections.push(`## Implementation Plan (from planner)\nFollow these steps:\n${plan}`);
   }

package/src/prompts/hu-reviewer.js

@@ -22,7 +22,7 @@ const DIMENSION_KEYS = [
  * @param {{stories: Array<{id: string, text: string}>, instructions: string|null, context?: string|null}} params
  * @returns {string} The assembled prompt.
  */
-export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null, hu_language = "en" }) {
+export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null, domainContext = null, hu_language = "en" }) {
   const langInstruction = getLanguageInstruction(hu_language);
   const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
@@ -45,6 +45,10 @@ export function buildHuReviewerPrompt({ stories, instructions, context = null, p
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (domainContext) {
+    sections.push(`## Domain Context\n${domainContext}`);
+  }
+
   if (context) {
     sections.push(`## Additional Context\n${context}`);
   }

package/src/prompts/planner.js

@@ -64,7 +64,7 @@ function formatArchitectContext(architectContext) {
   return lines.length > 1 ? lines.join("\n") : null;
 }
 
-export function buildPlannerPrompt({ task, context, architectContext, productContext = null }) {
+export function buildPlannerPrompt({ task, context, architectContext, productContext = null, domainContext = null }) {
   const parts = [
     "You are an expert software architect. Create an implementation plan for the following task.",
     "",
@@ -77,6 +77,10 @@ export function buildPlannerPrompt({ task, context, architectContext, productCon
     parts.push("## Product Context", productContext, "");
   }
 
+  if (domainContext) {
+    parts.push("## Domain Context", domainContext, "");
+  }
+
   if (context) {
     parts.push("## Context", context, "");
   }

package/src/prompts/reviewer.js

@@ -24,7 +24,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, projectDir = null, language = "en" }) {
+export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en" }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const langInstruction = getLanguageInstruction(language);
@@ -51,6 +51,10 @@ export async function buildReviewerPrompt({ task, diff, reviewRules, mode, seren
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (domainContext) {
+    sections.push(`## Domain Context\n${domainContext}`);
+  }
+
   sections.push(
     `Task context:\n${task}`,
     `Review rules:\n${reviewRules}`,

package/src/roles/architect-role.js

@@ -59,7 +59,7 @@ export class ArchitectRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = await buildArchitectPrompt({ task, instructions: this.instructions, researchContext, productContext: this.config?.productContext || null });
+    const prompt = await buildArchitectPrompt({ task, instructions: this.instructions, researchContext, productContext: this.config?.productContext || null, domainContext: this.config?.domainContext || null });
     const runArgs = { prompt, role: "architect" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/coder-role.js

@@ -43,7 +43,8 @@ export class CoderRole extends BaseRole {
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled),
       rtkAvailable: Boolean(this.config?.rtk?.available),
-      productContext: this.config?.productContext || null
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null
     });
 
     const coderArgs = { prompt, role: "coder" };

package/src/roles/domain-curator-role.js

@@ -0,0 +1,141 @@
+/**
+ * Domain Curator role.
+ * Discovers, proposes and synthesizes domain knowledge for the pipeline.
+ * Operates deterministically (loader + registry + synthesizer) — no LLM call needed
+ * unless the user wants to generate domain knowledge from scratch.
+ */
+
+import { loadDomains } from "../domains/domain-loader.js";
+import { DomainRegistry } from "../domains/domain-registry.js";
+import { synthesizeDomainContext } from "../domains/domain-synthesizer.js";
+
+export class DomainCuratorRole {
+  constructor({ config, logger }) {
+    this.config = config;
+    this.logger = logger;
+  }
+
+  /**
+   * Execute domain curation.
+   * @param {Object} input
+   * @param {string} input.task — the task description
+   * @param {string[]} input.domainHints — keywords from triage
+   * @param {Function & {interactive: boolean}} [input.askQuestion] — interactive question function
+   * @param {string} [input.projectDir] — project root
+   * @returns {Promise<{ok: boolean, result: Object, summary: string}>}
+   */
+  async execute({ task, domainHints = [], askQuestion = null, projectDir = null }) {
+    // 1. Load domains from filesystem
+    const fileDomains = await loadDomains(projectDir);
+
+    // 2. Search registry for additional matches
+    let registryDomains = [];
+    if (domainHints.length > 0) {
+      try {
+        const registry = await DomainRegistry.load();
+        registryDomains = registry.search(domainHints);
+      } catch {
+        this.logger.warn("Domain Curator: failed to load registry, continuing with file domains only");
+      }
+    }
+
+    // 3. Deduplicate (file domains take precedence over registry entries)
+    const allDomains = deduplicateDomains(fileDomains, registryDomains);
+
+    // 4. No domains found
+    if (allDomains.length === 0) {
+      if (askQuestion?.interactive) {
+        const answer = await askQuestion({
+          message: "No domain knowledge found for this task.\nDo you have domain documents to provide, or should the pipeline continue without domain context?",
+          type: "confirm"
+        });
+        // For now, just log. Future: support document ingestion.
+        if (answer === true) {
+          this.logger.info("Domain Curator: user indicated domain documents available — future feature");
+        }
+      } else {
+        this.logger.warn("Domain Curator: no domain knowledge found, continuing without domain context");
+      }
+
+      return {
+        ok: true,
+        result: {
+          selectedDomains: [],
+          domainContext: null,
+          domainsFound: 0,
+          domainsUsed: 0,
+          source: "none"
+        },
+        summary: "Domain Curator: no domains found"
+      };
+    }
+
+    // 5. Propose selection to user (if interactive) or use all
+    let selectedDomains;
+
+    if (askQuestion?.interactive && allDomains.length > 1) {
+      const options = allDomains.map(d => ({
+        id: d.name,
+        label: `${d.name} (v${d.version || "?"}) — ${d.description || "no description"}`,
+        default: true
+      }));
+
+      const selected = await askQuestion({
+        message: `Found ${allDomains.length} domain knowledge package(s):`,
+        type: "multi-select",
+        options,
+        defaults: allDomains.map(d => d.name)
+      });
+
+      if (Array.isArray(selected) && selected.length > 0) {
+        const selectedSet = new Set(selected);
+        selectedDomains = allDomains.filter(d => selectedSet.has(d.name));
+      } else {
+        selectedDomains = allDomains; // fallback to all
+      }
+    } else {
+      // Single domain or non-interactive: use all
+      selectedDomains = allDomains;
+    }
+
+    // 6. Synthesize context
+    const domainContext = synthesizeDomainContext({
+      task,
+      domainHints,
+      selectedDomains
+    });
+
+    const source = selectedDomains.some(d => d.origin === "project") ? "project+user" : "user";
+
+    return {
+      ok: true,
+      result: {
+        selectedDomains: selectedDomains.map(d => d.name),
+        domainContext: domainContext || null,
+        domainsFound: allDomains.length,
+        domainsUsed: selectedDomains.length,
+        source
+      },
+      summary: `Domain Curator: ${selectedDomains.length}/${allDomains.length} domain(s) selected`
+    };
+  }
+}
+
+/**
+ * Deduplicate domains — file domains override registry entries by name.
+ */
+function deduplicateDomains(fileDomains, registryDomains) {
+  const byName = new Map();
+
+  // Registry entries first (lower priority)
+  for (const rd of registryDomains) {
+    if (rd.name) byName.set(rd.name, rd);
+  }
+
+  // File domains override
+  for (const fd of fileDomains) {
+    if (fd.name) byName.set(fd.name, fd);
+  }
+
+  return Array.from(byName.values());
+}

package/src/roles/hu-reviewer-role.js

@@ -52,7 +52,7 @@ export class HuReviewerRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context, productContext: this.config?.productContext || null });
+    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context, productContext: this.config?.productContext || null, domainContext: this.config?.domainContext || null });
     const runArgs = { prompt, role: "hu-reviewer" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/planner-role.js

@@ -63,7 +63,7 @@ function appendArchitectSection(sections, architectContext) {
   sections.push("");
 }
 
-function buildPrompt({ task, instructions, research, triageDecomposition, architectContext, productContext = null }) {
+function buildPrompt({ task, instructions, research, triageDecomposition, architectContext, productContext = null, domainContext = null }) {
   const sections = [];
 
   if (instructions) {
@@ -80,6 +80,10 @@ function buildPrompt({ task, instructions, research, triageDecomposition, archit
     sections.push("## Product Context", productContext, "");
   }
 
+  if (domainContext) {
+    sections.push("## Domain Context", domainContext, "");
+  }
+
   appendDecompositionSection(sections, triageDecomposition);
   appendArchitectSection(sections, architectContext);
   appendResearchSection(sections, research);
@@ -106,7 +110,7 @@ export class PlannerRole extends BaseRole {
     const provider = resolveProvider(this.config);
 
     const agent = this._createAgent(provider, this.config, this.logger);
-    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition, architectContext, productContext: this.config?.productContext || null });
+    const prompt = buildPrompt({ task: taskStr, instructions: this.instructions, research, triageDecomposition, architectContext, productContext: this.config?.productContext || null, domainContext: this.config?.domainContext || null });
 
     const runArgs = { prompt, role: "planner" };
     if (onOutput) runArgs.onOutput = onOutput;

package/src/roles/reviewer-role.js

@@ -25,7 +25,7 @@ function truncateDiff(diff) {
     : diff;
 }
 
-function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false, productContext = null }) {
+function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false, productContext = null, domainContext = null }) {
   const sections = [];
 
   sections.push(SUBAGENT_PREAMBLE);
@@ -46,6 +46,10 @@ function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAva
     sections.push(`## Product Context\n${productContext}`);
   }
 
+  if (domainContext) {
+    sections.push(`## Domain Context\n${domainContext}`);
+  }
+
   if (rtkAvailable) {
     sections.push(RTK_INSTRUCTIONS);
   }
@@ -89,7 +93,8 @@ export class ReviewerRole extends BaseRole {
       reviewMode: this.config?.review_mode || "standard",
       instructions: this.instructions,
       rtkAvailable: Boolean(this.config?.rtk?.available),
-      productContext: this.config?.productContext || null
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null
     });
 
     const reviewArgs = { prompt, role: "reviewer" };

package/src/roles/triage-role.js

@@ -33,6 +33,13 @@ function normalizeSubtasks(subtasks) {
     .slice(0, 5);
 }
 
+function normalizeDomainHints(hints) {
+  if (!Array.isArray(hints)) return [];
+  return hints
+    .map((h) => (typeof h === "string" ? h.trim().toLowerCase() : ""))
+    .filter(Boolean);
+}
+
 export class TriageRole extends BaseRole {
   constructor({ config, logger, emitter = null, createAgentFn = null }) {
     super({ name: "triage", config, logger, emitter });
@@ -90,11 +97,14 @@ export class TriageRole extends BaseRole {
       const subtasks = normalizeSubtasks(parsed.subtasks);
       const taskType = VALID_TASK_TYPES.has(parsed.taskType) ? parsed.taskType : FALLBACK_TASK_TYPE;
 
+      const domainHints = normalizeDomainHints(parsed.domainHints);
+
       const triageResult = {
         level,
         roles,
         reasoning,
         taskType,
+        domainHints,
         provider
       };
 

package/src/skills/skill-loader.js

@@ -3,14 +3,37 @@ import { join } from "node:path";
 
 const SKILL_DIRS = [".agent/skills", ".claude/skills"];
 const SKILL_FILE = "SKILL.md";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Extract the `type` field from SKILL.md frontmatter.
+ * Returns "technical" (default) or "domain".
+ * @param {string} content — raw SKILL.md content
+ * @returns {{type: string, body: string}}
+ */
+function parseSkillType(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { type: "technical", body: content };
+
+  const frontmatter = match[1];
+  const body = match[2];
+
+  // Simple regex extraction — avoid full YAML parser for a single field
+  const typeMatch = frontmatter.match(/^type:\s*(.+)$/m);
+  const type = typeMatch ? typeMatch[1].trim().toLowerCase() : "technical";
+
+  return { type, body };
+}
 
 /**
  * Scans known skill directories for SKILL.md files.
  * @param {string} projectDir — absolute path to the project root
- * @returns {Promise<Array<{name: string, content: string}>>}
+ * @param {{type?: string}} [options] — filter by type: "technical" (default), "domain", or undefined (all)
+ * @returns {Promise<Array<{name: string, content: string, type: string}>>}
  */
-export async function loadAvailableSkills(projectDir) {
+export async function loadAvailableSkills(projectDir, options = {}) {
   const skills = [];
+  const filterType = options.type || null;
 
   for (const rel of SKILL_DIRS) {
     const dir = join(projectDir, rel);
@@ -25,8 +48,16 @@ export async function loadAvailableSkills(projectDir) {
       if (!entry.isDirectory()) continue;
       const skillPath = join(dir, entry.name, SKILL_FILE);
       try {
-        const content = await readFile(skillPath, "utf-8");
-        skills.push({ name: entry.name, content });
+        const raw = await readFile(skillPath, "utf-8");
+        const { type, body } = parseSkillType(raw);
+
+        // Filter by type if specified
+        if (filterType && type !== filterType) continue;
+
+        // For backward compat: existing callers get content without frontmatter for domain skills,
+        // but full content for technical skills (they never had frontmatter before)
+        const content = type === "domain" ? body.trim() : raw;
+        skills.push({ name: entry.name, content, type });
       } catch {
         // no SKILL.md in this subdirectory — skip
       }

package/src/utils/process.js

@@ -76,6 +76,10 @@ async function awaitWithTimeout(subprocess, timeout, getStdout) {
 
 export async function runCommand(command, args = [], options = {}) {
   const { timeout, onOutput, silenceTimeoutMs, partialOutputFlushMs, ...rest } = options;
+  // Always detach stdin: KJ subprocesses never need interactive input.
+  // Without this, a subprocess prompting for input (sonar credentials,
+  // agent approval, npm prompts) hangs forever since there is no TTY.
+  if (!rest.stdin) rest.stdin = "ignore";
   const subprocess = execa(command, args, { reject: false, ...rest });
 
   let stdoutAccum = "";

package/src/utils/welcome.js

@@ -0,0 +1,52 @@
+const A = {
+  reset:   "\x1b[0m",
+  bold:    "\x1b[1m",
+  dim:     "\x1b[2m",
+  cyan:    "\x1b[36m",
+  green:   "\x1b[32m",
+  yellow:  "\x1b[33m",
+};
+
+const BAR = `${A.dim}${"─".repeat(44)}${A.reset}`;
+
+const QUICK_START = [
+  ["kj run <task>",  "Run the full coder+reviewer pipeline"],
+  ["kj init",        "Initialize config and setup"],
+  ["kj doctor",      "Check environment and agent availability"],
+  ["kj status",      "Show pipeline dashboard"],
+  ["kj report",      "Show latest session report"],
+];
+
+/**
+ * Print the CLI welcome screen.
+ * @param {object} opts
+ * @param {string} opts.version - Version string (required)
+ * @param {object} [opts.config]  - Loaded KJ config (optional, shows configured agents)
+ */
+export function printWelcomeScreen({ version, config = null }) {
+  console.log();
+  console.log(BAR);
+  console.log(`  ${A.bold}${A.cyan}▶ Karajan Code${A.reset}  ${A.dim}v${version}${A.reset}`);
+  console.log(`  ${A.dim}AI-powered coding pipeline${A.reset}`);
+  console.log(BAR);
+  console.log();
+
+  if (config) {
+    const coder    = config.roles?.coder?.provider    || config.coder    || "claude";
+    const reviewer = config.roles?.reviewer?.provider || config.reviewer || "codex";
+    console.log(`  ${A.bold}Agents${A.reset}`);
+    console.log(`    ${A.dim}coder:${A.reset}    ${coder}`);
+    console.log(`    ${A.dim}reviewer:${A.reset} ${reviewer}`);
+    console.log();
+  }
+
+  console.log(`  ${A.bold}Quick start${A.reset}`);
+  for (const [cmd, desc] of QUICK_START) {
+    const padded = cmd.padEnd(20);
+    console.log(`    ${A.green}${padded}${A.reset}  ${A.dim}${desc}${A.reset}`);
+  }
+
+  console.log();
+  console.log(`  ${A.dim}Run ${A.reset}kj --help${A.dim} to see all commands.${A.reset}`);
+  console.log();
+}