karajan-code 2.6.0 → 2.7.0

package/README.md

@@ -53,6 +53,25 @@ Use Karajan when you want:
 
 If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together: Karajan is designed to be used as an MCP server inside Claude Code.
 
+## How Karajan differs from AI frameworks
+
+While Genkit, Mastra, LangChain and Vercel AI SDK call `/v1/messages`, Karajan orchestrates the AI CLIs your developers already use in their terminals.
+
+| Axis | Karajan | Genkit / Mastra / LangChain / Vercel AI SDK |
+|------|---------|---------------------------------------------|
+| Calls provider HTTP API (`/v1/messages`, etc.) | ❌ Delegates to CLIs | ✅ |
+| Orchestrates existing AI CLIs (claude, codex, gemini, aider, opencode) as subprocesses | ✅ | ❌ |
+| Depends on cloud infrastructure | ❌ Fully local | ⚠️ Varies |
+| Vanilla JS (no TypeScript required) | ✅ | ⚠️ TS-first |
+| Token billing | **Uses your existing CLI subscriptions** | Pay per API call |
+
+Two technical facts worth keeping straight:
+
+1. **Subprocess, not PTY.** Karajan spawns each CLI via `execa` / `child_process` with plain `stdin` / `stdout` / `stderr` — see `src/infrastructure/command-runner.js` and `src/agents/*.js`. There is no PTY emulation.
+2. **Fresh subprocess per invocation + state on disk.** Every coder run is a new process; the state lives in `~/.karajan/sessions/` (see `src/session-store.js`) and the per-session journal under `.reviews/<session-id>/`. This is what makes pipelines **reproducible** and **resumable** with `kj resume`.
+
+Full write-up with mental mapping for Genkit / Mastra / LangChain / Vercel AI SDK developers: **[docs/COMPARISON.md](./docs/COMPARISON.md)**.
+
 ## Install
 
 **npm** (recommended):

package/package.json

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

package/src/brain/solomon-consult.js

@@ -8,6 +8,14 @@
  *
  * This is intentionally conservative. A future iteration can make Solomon a
  * binding arbiter for routing (like it is for pipeline-control decisions).
+ *
+ * Architectural invariant: this module is the ONLY sanctioned path from
+ * Brain to Solomon for routing concerns. Stages / rules / agents must not
+ * bypass Brain to reach Solomon directly — see the note on `invokeSolomon`
+ * in `src/orchestrator/solomon-escalation.js` and docs/ARCHITECTURE.md.
+ *
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
  */
 
 /**
@@ -17,7 +25,7 @@
  * @param {import("./decisor.js").Decision} args.decision
  * @param {Object} args.triage
  * @param {string} args.task
- * @returns {Object} conflict
+ * @returns {Conflict} conflict
  */
 export function buildRoutingConflict({ decision, triage, task }) {
   return {

package/src/cli.js

@@ -217,7 +217,7 @@ program
 
 program
   .command("skills [action]")
-  .description("Manage the local OpenSkills cache (actions: list | clear-cache)")
+  .description("Manage the skill cache (actions: list | clear-cache | sync-addyosmani | list-addyosmani)")
   .action(async (action) => {
     const { skillsCommand } = await import("./commands/skills.js");
     const exitCode = await skillsCommand({ action: action || "list" });

package/src/commands/skills.js

@@ -1,12 +1,15 @@
 /**
- * `kj skills` — manage the local OpenSkills cache.
+ * `kj skills` — manage the local OpenSkills cache and the addyosmani catalog.
  *
  * Subcommands:
- *   - list         : print cached skills with their age and freshness.
- *   - clear-cache  : delete all cached metadata (forces re-install on next session).
+ *   - list                  : print cached OpenSkills with their age and freshness.
+ *   - clear-cache           : delete all cached metadata (forces re-install on next session).
+ *   - sync-addyosmani       : force a git pull of addyosmani/agent-skills.
+ *   - list-addyosmani       : enumerate slugs available in the cached catalog.
  */
 
 import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
+import { refreshIfStale, listAvailableSlugs, getCatalogRoot, loadSkillBySlug } from "../skills/addyosmani-catalog.js";
 
 function humanAge(cachedAt) {
   const ms = Date.now() - Date.parse(cachedAt);
@@ -22,8 +25,12 @@ export async function skillsCommand({ action = "list" } = {}) {
       return listAction();
     case "clear-cache":
       return clearAction();
+    case "sync-addyosmani":
+      return syncAddyosmaniAction();
+    case "list-addyosmani":
+      return listAddyosmaniAction();
     default:
-      console.error(`Unknown action: ${action}. Use: list | clear-cache`);
+      console.error(`Unknown action: ${action}. Use: list | clear-cache | sync-addyosmani | list-addyosmani`);
       return 1;
   }
 }
@@ -47,3 +54,33 @@ async function clearAction() {
   console.log(`Cleared ${removed} cached skill${removed === 1 ? "" : "s"} from ${getCacheRoot()}`);
   return 0;
 }
+
+async function syncAddyosmaniAction() {
+  console.log("Syncing addyosmani/agent-skills catalog...");
+  const logger = { warn: (m) => console.warn(`  warn: ${m}`), info: (m) => console.log(`  ${m}`) };
+  const result = await refreshIfStale({ force: true, logger });
+  if (!result.ok) {
+    console.error(`Sync failed: ${result.error || result.action}`);
+    return 1;
+  }
+  const slugs = await listAvailableSlugs();
+  console.log(`${result.action === "cloned" ? "Cloned" : "Pulled"} at ${getCatalogRoot()}`);
+  console.log(`Available slugs: ${slugs.length}`);
+  return 0;
+}
+
+async function listAddyosmaniAction() {
+  const slugs = await listAvailableSlugs();
+  if (slugs.length === 0) {
+    console.log(`No addyosmani catalog found at ${getCatalogRoot()}`);
+    console.log("Run `kj skills sync-addyosmani` to bootstrap it.");
+    return 0;
+  }
+  console.log(`addyosmani/agent-skills catalog at ${getCatalogRoot()}\n${slugs.length} slug(s):\n`);
+  for (const slug of slugs) {
+    const skill = await loadSkillBySlug(slug);
+    const desc = skill?.description ? ` — ${skill.description.slice(0, 100)}${skill.description.length > 100 ? "..." : ""}` : "";
+    console.log(`  ${slug}${desc}`);
+  }
+  return 0;
+}

package/src/config/schema.js

@@ -151,6 +151,30 @@ const Budget = v.optional(v.looseObject({
   pricing: v.optional(v.unknown()),
 }));
 
+/**
+ * skills.addyosmani subtree (KJC-TSK-0327). Governs the addyosmani/agent-skills
+ * catalog provider: enabled flag, refresh TTL and repo URL.
+ */
+const SkillsAddyosmani = v.looseObject({
+  enabled: v.optional(v.boolean()),
+  refreshDays: v.optional(v.pipe(
+    v.number(),
+    v.minValue(0, "skills.addyosmani.refreshDays must be >= 0")
+  )),
+  repoUrl: v.optional(v.string()),
+});
+
+/**
+ * skills.* subtree. `sources` controls which providers Karajan consults and in
+ * what order (addyosmani → openskills → local by default). `mode` is the
+ * existing regex/semantic/auto/none knob from semantic-detector.js.
+ */
+const Skills = v.optional(v.looseObject({
+  mode: v.optional(v.picklist(["auto", "regex", "semantic", "none"], "skills.mode must be one of: auto | regex | semantic | none")),
+  sources: v.optional(v.array(v.string())),
+  addyosmani: v.optional(SkillsAddyosmani),
+}));
+
 /**
  * Main config schema. `looseObject` lets every consumer that reads an
  * undeclared key keep working while the schema catches the bugs we care
@@ -181,6 +205,7 @@ export const ConfigSchema = v.looseObject({
   hu_language: v.optional(v.string()),
   policies: v.optional(v.record(v.string(), v.unknown())),
   telemetry: v.optional(v.boolean()),
+  skills: Skills,
 });
 
 /**

package/src/config.js

@@ -141,6 +141,15 @@ const DEFAULTS = {
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
+  skills: {
+    mode: "auto",
+    sources: ["addyosmani", "openskills", "local"],
+    addyosmani: {
+      enabled: true,
+      refreshDays: 7,
+      repoUrl: "https://github.com/addyosmani/agent-skills.git"
+    }
+  },
   ci: { enabled: false, review_event: "kj-review", comment_event: "kj-comment", comment_prefix: true },
   git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
   output: { report_dir: "./.reviews", log_level: "info", quiet: true },

package/src/orchestrator/flow-runner.js

@@ -39,6 +39,8 @@ import { setRunner as setGitRunner } from "../utils/git.js";
 import { detectNeededSkills, autoInstallSkills, cleanupAutoInstalledSkills } from "../skills/skill-detector.js";
 import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
 import { refineSkillsSemantically, resolveSkillsMode } from "../skills/semantic-detector.js";
+import { refreshIfStale as refreshAddyosmaniCatalog, listAvailableSlugs as listAddyosmaniSlugs } from "../skills/addyosmani-catalog.js";
+import { resolveAddyosmaniSlugs } from "../skills/addyosmani-role-map.js";
 
 // Extracted modules
 import {
@@ -832,6 +834,20 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
       // User explicitly opted out. Skip detection entirely.
       return { plannedTask, updatedConfig };
     }
+
+    // FIRST source: addyosmani/agent-skills (process skills per role).
+    // This runs BEFORE OpenSkills detection because process skills are the
+    // canonical workflows (TDD, code-review, security, performance...) that
+    // should shape every role's prompt; stack skills come second.
+    await ensureAddyosmaniSkills({
+      task: plannedTask,
+      config: updatedConfig,
+      logger,
+      session,
+      emitter,
+      eventBase,
+    });
+
     let neededSkills = skillsMode === "semantic"
       ? []
       : await detectNeededSkills(plannedTask, skillProjectDir);
@@ -879,6 +895,80 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   return { plannedTask, updatedConfig };
 }
 
+/**
+ * Ensure the addyosmani/agent-skills catalog is present and fresh, then
+ * resolve which upstream slugs are relevant for the current task. The
+ * resolved slugs are stored on `session.addyosmaniSkills` so downstream
+ * prompt builders can inject them ahead of OpenSkills-detected stack skills.
+ *
+ * Config surface (all optional, sensible defaults):
+ *   skills:
+ *     sources: ["addyosmani", "openskills", "local"]  # default
+ *     addyosmani:
+ *       enabled: true
+ *       refreshDays: 7
+ *       repoUrl: "https://github.com/addyosmani/agent-skills.git"
+ *
+ * Setting skills.addyosmani.enabled = false, or removing "addyosmani" from
+ * skills.sources, disables this step entirely (reverts to OpenSkills-only).
+ */
+async function ensureAddyosmaniSkills({ task, config, logger, session, emitter, eventBase }) {
+  const skillsConfig = config?.skills || {};
+  const sources = Array.isArray(skillsConfig.sources) ? skillsConfig.sources : ["addyosmani", "openskills", "local"];
+  const addyConfig = skillsConfig.addyosmani || {};
+  // Test harness override: tests/setup.js sets __KJ_DEFAULT_ADDYOSMANI_ENABLED
+  // to false so orchestrator tests don't spawn git. Tests that need the real
+  // catalog opt in by setting config.skills.addyosmani.enabled = true.
+  const globalDefault = globalThis.__KJ_DEFAULT_ADDYOSMANI_ENABLED;
+  const enabledFromConfig = addyConfig.enabled === true
+    || (addyConfig.enabled !== false && globalDefault !== false);
+  const enabled = enabledFromConfig && sources.includes("addyosmani");
+  if (!enabled) return;
+
+  const refreshDays = Number.isFinite(addyConfig.refreshDays) ? addyConfig.refreshDays : 7;
+  const refreshMs = Math.max(0, refreshDays) * 24 * 60 * 60 * 1000;
+
+  try {
+    const refreshResult = await refreshAddyosmaniCatalog({
+      refreshMs,
+      repoUrl: addyConfig.repoUrl,
+      logger,
+    });
+
+    if (!refreshResult.ok) {
+      session.addyosmaniSkills = { available: false, reason: refreshResult.error || "refresh failed" };
+      emitProgress(emitter, makeEvent("skills:addyosmani-unavailable", { ...eventBase, stage: "skills" }, {
+        message: `addyosmani/agent-skills catalog unavailable: ${refreshResult.error || refreshResult.action}`,
+        detail: { action: refreshResult.action, hint: "Install git to enable process skills from addyosmani/agent-skills" },
+      }));
+      return;
+    }
+
+    const available = new Set(await listAddyosmaniSlugs());
+    const resolved = resolveAddyosmaniSlugs({ role: null, task }); // role resolution happens per-stage later
+    const valid = resolved.filter((slug) => available.has(slug));
+
+    session.addyosmaniSkills = {
+      available: true,
+      action: refreshResult.action,
+      resolvedSlugs: valid,
+      allAvailable: Array.from(available),
+    };
+
+    emitProgress(emitter, makeEvent("skills:addyosmani-ready", { ...eventBase, stage: "skills" }, {
+      message: `addyosmani/agent-skills ${refreshResult.action} — ${available.size} slug(s) available, ${valid.length} relevant to task`,
+      detail: {
+        action: refreshResult.action,
+        relevantSlugs: valid,
+        availableCount: available.size,
+      },
+    }));
+  } catch (err) {
+    logger.warn(`addyosmani catalog step failed (non-blocking): ${err.message}`);
+    session.addyosmaniSkills = { available: false, reason: err.message };
+  }
+}
+
 /**
  * Auto-generate HU batch from triage decomposition when no manual huFile is present.
  * Runs after researcher/architect/planner so that context is available for better HUs.

package/src/orchestrator/solomon-escalation.js

@@ -3,6 +3,23 @@ import { addCheckpoint, pauseSession, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { msg, getLang } from "../utils/messages.js";
 
+/**
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
+ */
+
+/**
+ * Architectural invariant (DO NOT BREAK):
+ * `invokeSolomon` MUST NOT be called directly from stages, rules or agent
+ * code. The only callers should be:
+ *   - Karajan Brain (via `src/brain/solomon-consult.js`)
+ *   - The orchestrator's escalation path (`src/orchestrator/flow-runner.js`)
+ *     on behalf of Brain.
+ * The v2.3.0 audit fixed 21 violations of this rule. Keeping Solomon behind
+ * Brain is what the "Brain-as-gateway, Solomon-as-judge" architecture
+ * depends on — see docs/ARCHITECTURE.md §Brain/Solomon.
+ */
+
 /**
  * Build a human-readable escalation message from raw Solomon conflict data.
  * Replaces the raw JSON dump with structured, plain-text output.
@@ -81,6 +98,23 @@ function extractSolomonHistory(session) {
     }));
 }
 
+/**
+ * Consult Solomon (or fall back to human escalation) for a given conflict.
+ * See the Conflict typedef for the shape of the `conflict` argument and
+ * the invariant above for who is allowed to call this.
+ *
+ * @param {Object}    params
+ * @param {Object}    params.config
+ * @param {Object}    params.logger
+ * @param {Object}    [params.emitter]
+ * @param {Object}    [params.eventBase]
+ * @param {string}    params.stage
+ * @param {Conflict}  params.conflict
+ * @param {Function}  [params.askQuestion]
+ * @param {Object}    [params.session]
+ * @param {number}    [params.iteration]
+ * @returns {Promise<SolomonResult>}
+ */
 export async function invokeSolomon({ config, logger, emitter, eventBase, stage, conflict, askQuestion, session, iteration }) {
   const solomonEnabled = Boolean(config.pipeline?.solomon?.enabled);
 

package/src/roles/agent-role.js

@@ -3,6 +3,15 @@
  * Handles the common execute() flow: resolve provider → create agent → call LLM → parse output.
  * Subclasses override hooks (buildPrompt, parseOutput, buildSuccessResult, buildSummary)
  * instead of reimplementing the full execute() boilerplate.
+ *
+ * Conceptual mapping: `AgentRole` is a Karajan Role that delegates to an AI CLI
+ * subprocess (not to a provider HTTP API). From the outside it plays the same
+ * role as a Genkit Flow — named unit of work with a prompt and a parsed output —
+ * but every invocation spawns a fresh `execa` subprocess (claude, codex, gemini,
+ * aider, opencode) and the state lives in Karajan's session store, not in a
+ * provider-side conversation. See `docs/COMPARISON.md`.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
  */
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";

package/src/roles/base-role.js

@@ -49,6 +49,23 @@ async function loadFirstExisting(paths) {
   return null;
 }
 
+/**
+ * Base class for every pipeline role (coder, reviewer, planner, refactorer,
+ * researcher, architect, triage, discover, tester, security, impeccable,
+ * hu-reviewer, audit, solomon, commiter, karajan-brain, domain-curator).
+ *
+ * Conceptual mapping for developers coming from other ecosystems:
+ * `BaseRole` (and every subclass) is Karajan's equivalent of a **Flow** in the
+ * Genkit sense — a named, composable unit of work with a prompt, an invocation
+ * and a parsed output. The important difference: a Karajan Role executes over
+ * a **subprocess CLI** (`claude`, `codex`, `gemini`, `aider`, `opencode`), not
+ * by calling an HTTP provider API. No PTY, no long-lived session — each run
+ * is a fresh subprocess with state on disk under `~/.karajan/sessions/`.
+ *
+ * See `docs/COMPARISON.md` for the full positioning.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
+ */
 export class BaseRole {
   constructor({ name, config, logger, emitter = null }) {
     if (!name) throw new Error("Role name is required");

package/src/skills/addyosmani-catalog.js

@@ -0,0 +1,293 @@
+/**
+ * addyosmani/agent-skills catalog provider (KJC-TSK-0327).
+ *
+ * Fetches and caches the addyosmani/agent-skills repository (20+ process
+ * skills: TDD, code-review, security, performance, git-workflow, debugging,
+ * CI/CD, docs, spec-driven, planning...) and exposes them as a first-class
+ * skill source for Karajan's pipeline.
+ *
+ * This catalog is ORTHOGONAL to the OpenSkills marketplace (which hosts stack
+ * skills like astro, react, prisma, python-data). Together they cover:
+ *   - addyosmani    → lifecycle/process skills mapped per role
+ *   - OpenSkills    → stack/framework skills detected from task + deps
+ *   - local skills  → project-specific skills under .claude/skills
+ *
+ * Lifecycle:
+ *   1. ensureCatalog()      – clone (depth=1) on first use
+ *   2. refreshIfStale()     – git pull when older than TTL (default 7d)
+ *   3. loadSkillBySlug()    – read /skills/<slug>/SKILL.md from disk
+ *   4. listAvailableSlugs() – enumerate the /skills/ directory
+ *
+ * Degradation contract: when git is missing, the network is unreachable, or
+ * the catalog directory is malformed, every exported function returns safe
+ * empty values and logs a warning. The pipeline NEVER blocks on this module.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+const REPO_URL = "https://github.com/addyosmani/agent-skills.git";
+const CATALOG_DIR_NAME = "agent-skills";
+const SKILLS_SUBDIR = "skills";
+const SKILL_FILE = "SKILL.md";
+const DEFAULT_REFRESH_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const META_FILENAME = ".karajan-catalog-meta.json";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Absolute path to the cached catalog inside ~/.karajan/.
+ * @returns {string}
+ */
+export function getCatalogRoot() {
+  return path.join(getKarajanHome(), CATALOG_DIR_NAME);
+}
+
+function getSkillsRoot() {
+  return path.join(getCatalogRoot(), SKILLS_SUBDIR);
+}
+
+function getMetaPath() {
+  return path.join(getCatalogRoot(), META_FILENAME);
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readMeta() {
+  try {
+    const raw = await fs.readFile(getMetaPath(), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function writeMeta(meta) {
+  await fs.mkdir(getCatalogRoot(), { recursive: true });
+  await fs.writeFile(getMetaPath(), JSON.stringify(meta, null, 2), "utf8");
+}
+
+/**
+ * Check whether `git` is on PATH. Cached per-process.
+ * @returns {Promise<boolean>}
+ */
+let _gitAvailable = null;
+export async function isGitAvailable() {
+  if (_gitAvailable !== null) return _gitAvailable;
+  try {
+    const result = await runCommand("git", ["--version"], { timeout: 5_000 });
+    _gitAvailable = result.exitCode === 0;
+  } catch {
+    _gitAvailable = false;
+  }
+  return _gitAvailable;
+}
+
+// Internal: reset the cached probe (tests use this to re-evaluate git presence).
+export function __resetGitProbe() {
+  _gitAvailable = null;
+}
+
+/**
+ * Clone the addyosmani/agent-skills repo (shallow) if it does not already
+ * exist locally. No-op when it is already present.
+ *
+ * @param {{ repoUrl?: string, logger?: object }} [opts]
+ * @returns {Promise<{ok: boolean, path?: string, error?: string, skipped?: boolean}>}
+ */
+export async function ensureCatalog(opts = {}) {
+  const { repoUrl = REPO_URL, logger } = opts;
+  const root = getCatalogRoot();
+
+  if (await pathExists(path.join(root, ".git"))) {
+    return { ok: true, path: root, skipped: true };
+  }
+
+  if (!(await isGitAvailable())) {
+    logger?.warn?.("addyosmani-catalog: git not available — skipping catalog bootstrap");
+    return { ok: false, error: "git not available" };
+  }
+
+  await fs.mkdir(path.dirname(root), { recursive: true });
+
+  const result = await runCommand(
+    "git",
+    ["clone", "--depth", "1", repoUrl, root],
+    { timeout: 120_000 }
+  );
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    logger?.warn?.(`addyosmani-catalog: clone failed — ${stderr}`);
+    return { ok: false, error: stderr || `clone failed (exit ${result.exitCode})` };
+  }
+
+  await writeMeta({
+    repoUrl,
+    clonedAt: new Date().toISOString(),
+    lastPullAt: new Date().toISOString(),
+  });
+
+  return { ok: true, path: root };
+}
+
+/**
+ * Refresh the catalog via `git pull` when the cached copy is older than
+ * `refreshMs`. When the catalog does not exist yet, delegates to
+ * ensureCatalog().
+ *
+ * @param {{ refreshMs?: number, repoUrl?: string, force?: boolean, logger?: object }} [opts]
+ * @returns {Promise<{ok: boolean, action: "cloned"|"pulled"|"fresh"|"skipped", error?: string}>}
+ */
+export async function refreshIfStale(opts = {}) {
+  const { refreshMs = DEFAULT_REFRESH_MS, repoUrl = REPO_URL, force = false, logger } = opts;
+  const root = getCatalogRoot();
+
+  if (!(await pathExists(path.join(root, ".git")))) {
+    const cloneResult = await ensureCatalog({ repoUrl, logger });
+    return cloneResult.ok
+      ? { ok: true, action: "cloned" }
+      : { ok: false, action: "skipped", error: cloneResult.error };
+  }
+
+  const meta = await readMeta();
+  const lastPull = meta?.lastPullAt ? Date.parse(meta.lastPullAt) : 0;
+  const age = Date.now() - (Number.isFinite(lastPull) ? lastPull : 0);
+  if (!force && age < refreshMs) {
+    return { ok: true, action: "fresh" };
+  }
+
+  if (!(await isGitAvailable())) {
+    logger?.warn?.("addyosmani-catalog: git unavailable — using stale cache");
+    return { ok: true, action: "skipped" };
+  }
+
+  const result = await runCommand(
+    "git",
+    ["-C", root, "pull", "--ff-only", "--depth", "1"],
+    { timeout: 60_000 }
+  );
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    logger?.warn?.(`addyosmani-catalog: git pull failed — ${stderr} (keeping stale cache)`);
+    return { ok: false, action: "skipped", error: stderr };
+  }
+
+  await writeMeta({
+    ...(meta || {}),
+    repoUrl,
+    lastPullAt: new Date().toISOString(),
+  });
+
+  return { ok: true, action: "pulled" };
+}
+
+/**
+ * Parse YAML frontmatter for name + description (we intentionally avoid a
+ * YAML dep — a tiny regex is enough for the fields we care about and stays
+ * compatible with addyosmani's SKILL.md format).
+ *
+ * @param {string} raw
+ * @returns {{name: string|null, description: string|null, body: string}}
+ */
+export function parseFrontmatter(raw) {
+  if (!raw) return { name: null, description: null, body: "" };
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) {
+    return { name: null, description: null, body: raw };
+  }
+  const frontmatter = match[1];
+  const body = match[2] || "";
+
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+
+  return {
+    name: nameMatch ? stripQuotes(nameMatch[1]) : null,
+    description: descMatch ? stripQuotes(descMatch[1]) : null,
+    body,
+  };
+}
+
+function stripQuotes(value) {
+  const trimmed = value.trim();
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"'))
+    || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/**
+ * Enumerate available skill slugs under /skills/.
+ *
+ * @returns {Promise<string[]>}
+ */
+export async function listAvailableSlugs() {
+  const root = getSkillsRoot();
+  let entries;
+  try {
+    entries = await fs.readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => !name.startsWith("."))
+    .sort();
+}
+
+/**
+ * Load a skill by its slug. Returns null when the slug is not present or the
+ * SKILL.md file is missing/unreadable.
+ *
+ * @param {string} slug
+ * @returns {Promise<{slug: string, name: string, description: string|null, content: string, path: string}|null>}
+ */
+export async function loadSkillBySlug(slug) {
+  if (!slug || typeof slug !== "string") return null;
+  const safeSlug = slug.trim().replace(/[^A-Za-z0-9._-]/g, "");
+  if (!safeSlug) return null;
+
+  const skillPath = path.join(getSkillsRoot(), safeSlug, SKILL_FILE);
+  let raw;
+  try {
+    raw = await fs.readFile(skillPath, "utf8");
+  } catch {
+    return null;
+  }
+
+  const parsed = parseFrontmatter(raw);
+  return {
+    slug: safeSlug,
+    name: parsed.name || safeSlug,
+    description: parsed.description,
+    content: raw,
+    path: skillPath,
+  };
+}
+
+/**
+ * Load multiple skills by slug in parallel. Silently drops missing entries.
+ *
+ * @param {string[]} slugs
+ * @returns {Promise<Array<{slug: string, name: string, description: string|null, content: string, path: string}>>}
+ */
+export async function loadSkillsBySlugs(slugs = []) {
+  if (!Array.isArray(slugs) || slugs.length === 0) return [];
+  const results = await Promise.all(slugs.map((s) => loadSkillBySlug(s)));
+  return results.filter(Boolean);
+}
+
+export { DEFAULT_REFRESH_MS, REPO_URL };

package/src/skills/addyosmani-role-map.js

@@ -0,0 +1,133 @@
+/**
+ * Role → addyosmani/agent-skills slug mapping (KJC-TSK-0327).
+ *
+ * The addyosmani catalog is process-oriented (not stack-oriented), so the
+ * natural keying is by Karajan role: reviewer wants code-review workflows,
+ * tester wants TDD, security wants hardening, etc.
+ *
+ * Task-text triggers complement the role map: e.g. a task that mentions
+ * "performance" or "Core Web Vitals" pulls in performance-optimization,
+ * regardless of which role is running.
+ *
+ * Every slug listed here MUST exist in the upstream repo at:
+ *   https://github.com/addyosmani/agent-skills/tree/main/skills/<slug>
+ * If upstream renames or removes a slug, loadSkillBySlug() degrades silently
+ * (returns null) and the pipeline continues without blocking.
+ */
+
+/**
+ * Role → array of upstream slugs.
+ * Keep slugs lowercase-hyphenated, matching addyosmani's directory names.
+ */
+export const ROLE_TO_ADDYOSMANI_SLUGS = {
+  // The coder role benefits from broad process context: how to iterate,
+  // how to engineer context, and how to debug when things break.
+  coder: [
+    "incremental-implementation",
+    "source-driven-development",
+    "context-engineering",
+    "debugging-and-error-recovery",
+  ],
+
+  // Reviewer wants the review + simplification workflows.
+  reviewer: [
+    "code-review-and-quality",
+    "code-simplification",
+  ],
+
+  // Tester focuses on TDD and browser verification.
+  tester: [
+    "test-driven-development",
+    "browser-testing-with-devtools",
+  ],
+
+  // Security role uses the dedicated hardening workflow.
+  security: [
+    "security-and-hardening",
+  ],
+
+  // Architect covers spec-driven, API design and planning skills.
+  architect: [
+    "spec-driven-development",
+    "api-and-interface-design",
+    "planning-and-task-breakdown",
+  ],
+
+  // Planner overlaps with architect but leans on task breakdown and spec.
+  planner: [
+    "planning-and-task-breakdown",
+    "spec-driven-development",
+  ],
+
+  // Researcher / discover benefit from the idea-refine workflow.
+  researcher: [
+    "idea-refine",
+  ],
+  discover: [
+    "idea-refine",
+  ],
+
+  // Impeccable (UI/UX audit) uses the frontend engineering workflow.
+  impeccable: [
+    "frontend-ui-engineering",
+  ],
+
+  // Refactorer uses simplification and debugging workflows.
+  refactorer: [
+    "code-simplification",
+    "debugging-and-error-recovery",
+  ],
+};
+
+/**
+ * Task-text patterns → addyosmani slug. These are applied in addition to the
+ * role map, so a reviewer task that mentions "performance" also pulls in the
+ * performance-optimization skill.
+ */
+export const TASK_PATTERN_TO_SLUG = [
+  { pattern: /\bperformance\b|\bcore\s+web\s+vitals\b|\blcp\b|\bcls\b|\binp\b/i, slug: "performance-optimization" },
+  { pattern: /\bsecurity\b|\bhardening\b|\bauth(entication|orization)?\b|\bxss\b|\bcsrf\b|\binjection\b/i, slug: "security-and-hardening" },
+  { pattern: /\btdd\b|\btest[- ]driven\b/i, slug: "test-driven-development" },
+  { pattern: /\bfrontend\b|\bui\b|\bux\b|\bcss\b|\bresponsive\b/i, slug: "frontend-ui-engineering" },
+  { pattern: /\bapi\b|\bendpoint\b|\binterface\s+design\b|\bopenapi\b|\brest\b|\bgraphql\b/i, slug: "api-and-interface-design" },
+  { pattern: /\bci\b|\bcd\b|\bci\/cd\b|\bpipeline\b|\bgithub\s+actions\b|\bworkflow\b/i, slug: "ci-cd-and-automation" },
+  { pattern: /\bgit\b|\bcommit\b|\bbranch\b|\bmerge\b|\bversioning\b|\bsemver\b/i, slug: "git-workflow-and-versioning" },
+  { pattern: /\bdebug\b|\berror\s+recovery\b|\bstack\s+trace\b/i, slug: "debugging-and-error-recovery" },
+  { pattern: /\bdeprecat|\bmigrat/i, slug: "deprecation-and-migration" },
+  { pattern: /\bdocs?\b|\badr\b|\breadme\b|\bdocumentation\b/i, slug: "documentation-and-adrs" },
+  { pattern: /\brelease\b|\blaunch\b|\bship\b/i, slug: "shipping-and-launch" },
+  { pattern: /\bspec\b|\bspecification\b|\bprd\b/i, slug: "spec-driven-development" },
+  { pattern: /\bidea\b|\brefine\b|\bdiscover/i, slug: "idea-refine" },
+  { pattern: /\bbrowser\s+test|\bdevtools\b|\bchrome\s+devtools\b/i, slug: "browser-testing-with-devtools" },
+];
+
+/**
+ * Resolve the set of addyosmani slugs that apply to a given (role, task)
+ * tuple. Returns a deduped array preserving role-first ordering (so role
+ * skills appear before task-inferred ones in the prompt).
+ *
+ * @param {{role?: string|null, task?: string|null}} args
+ * @returns {string[]}
+ */
+export function resolveAddyosmaniSlugs({ role = null, task = null } = {}) {
+  const out = [];
+  const seen = new Set();
+
+  const push = (slug) => {
+    if (!slug || seen.has(slug)) return;
+    seen.add(slug);
+    out.push(slug);
+  };
+
+  if (role && ROLE_TO_ADDYOSMANI_SLUGS[role]) {
+    for (const slug of ROLE_TO_ADDYOSMANI_SLUGS[role]) push(slug);
+  }
+
+  if (task && typeof task === "string") {
+    for (const { pattern, slug } of TASK_PATTERN_TO_SLUG) {
+      if (pattern.test(task)) push(slug);
+    }
+  }
+
+  return out;
+}

package/src/types/index.js

@@ -29,6 +29,10 @@
  *
  * @typedef {import("./policy.js").ResolvedPolicies} ResolvedPolicies
  * @typedef {import("./policy.js").QualityGateResult} QualityGateResult
+ *
+ * @typedef {import("./solomon.js").Conflict} SolomonConflict
+ * @typedef {import("./solomon.js").ConflictHistoryEntry} SolomonConflictHistoryEntry
+ * @typedef {import("./solomon.js").SolomonResult} SolomonResult
  */
 
 export {};

package/src/types/solomon.js

@@ -0,0 +1,87 @@
+/**
+ * Typedefs for Solomon — the AI judge consulted by Brain on genuine dilemmas.
+ *
+ * Architectural invariant (enforced by convention, see docs/ARCHITECTURE.md):
+ *   Solomon is **NEVER** invoked directly from stages, rules or roles.
+ *   The only legitimate entry points are:
+ *     - `src/brain/solomon-consult.js#consultSolomonForRouting`
+ *     - `src/orchestrator/solomon-escalation.js#invokeSolomon`
+ *   Both are called by Brain (or by the orchestrator on Brain's behalf).
+ *   The v2.3.0 audit fixed 21 violations where stages bypassed Brain and
+ *   called Solomon directly. Don't reintroduce that pattern.
+ *
+ * This module is runtime-empty — it only carries JSDoc annotations.
+ *
+ * @module types/solomon
+ */
+
+/**
+ * A single turn of feedback attributed to a pipeline agent. Used to build
+ * `Conflict.history` when Brain escalates a decision to Solomon.
+ *
+ * @typedef {Object} ConflictHistoryEntry
+ * @property {string} agent     - slug of the agent that produced the feedback
+ *                                (e.g. "reviewer", "sonar", "tester",
+ *                                "coder_rate_limit").
+ * @property {string} feedback  - raw textual feedback to be weighted by Solomon.
+ */
+
+/**
+ * The bundle of context Brain hands to Solomon when it cannot decide on its
+ * own. Solomon reads only this object + the stage + task; it never sees
+ * session internals beyond what is packed here.
+ *
+ * Historical shape: this matches the argument already used by
+ * `invokeSolomon({ ..., conflict })` — the typedef formalizes the contract
+ * so future drift is caught by `npm run typecheck`.
+ *
+ * @typedef {Object} Conflict
+ * @property {string} stage
+ *           Pipeline stage that triggered escalation (e.g. "reviewer",
+ *           "sonar", "tester", "init_error", "coder_rate_limit").
+ * @property {string} task
+ *           Original user task (denormalized so Solomon sees what the user
+ *           actually asked for, not just the stage context).
+ * @property {number} iterationCount
+ *           Current iteration number inside the escalating sub-loop.
+ * @property {number} maxIterations
+ *           Configured cap for that sub-loop (reviewer retries, tester
+ *           retries, full pipeline iterations, etc.). Hitting this cap is
+ *           the canonical trigger for Solomon consultation.
+ * @property {string|null} [cooldownUntil]
+ *           ISO timestamp for rate-limit / standby escalations. Null when
+ *           the conflict is not a rate-limit.
+ * @property {number|null} [cooldownMs]
+ *           Remaining cooldown in milliseconds. Null outside rate-limit
+ *           escalations.
+ * @property {ConflictHistoryEntry[]} history
+ *           Ordered list of agent feedback Solomon should weigh. Most
+ *           recent last. Must be non-empty — Solomon should always see at
+ *           least one piece of evidence.
+ */
+
+/**
+ * Solomon's ruling on a `Conflict`. Returned by `invokeSolomon()` and
+ * consumed by the orchestrator to decide what happens next.
+ *
+ * @typedef {Object} SolomonResult
+ * @property {"continue"|"pause"|"subtask"} action
+ *           - `continue`: retry the sub-loop with optional `humanGuidance`
+ *             appended to the next feedback round.
+ *           - `pause`: stop the pipeline and surface a question to the
+ *             human operator (`SolomonResult.question`).
+ *           - `subtask`: bifurcate into a named sub-task defined in
+ *             `SolomonResult.subtask`.
+ * @property {string} [rationale]         - human-readable reasoning for the
+ *                                          chosen action. Logged to the
+ *                                          decisions journal.
+ * @property {string} [humanGuidance]     - text to merge into the next
+ *                                          coder/reviewer prompt when
+ *                                          action === "continue".
+ * @property {string} [question]          - prompt shown to the human when
+ *                                          action === "pause".
+ * @property {Object} [subtask]           - sub-task descriptor when
+ *                                          action === "subtask".
+ */
+
+export {};