karajan-code 1.39.0 → 1.41.0

package/README.md

@@ -110,87 +110,23 @@ kj-tail --help           # Full options
 **Typical workflow:**
 
 ```
-┌─────────────────────────┐    ┌─────────────────────────┐
-│  Terminal 1              │    │  Terminal 2              │
-│                          │    │                          │
-│  $ claude                │    │  $ kj-tail               │
-│  > implement the next    │    │                          │
-│    priority task         │    │  ├─ 📋 Triage: medium    │
-│                          │    │  ├─ 🔬 Researcher ✅     │
-│  (Claude calls kj_run   │    │  ├─ 🧠 Planner ✅        │
-│   via MCP, you see       │    │  ├─ 🔨 Coder ✅          │
-│   only the final result) │    │  ├─ 🔍 Sonar: OK        │
-│                          │    │  ├─ 👁️ Reviewer ❌       │
-│                          │    │  ├─ ⚖️ Solomon: 2 cond.  │
-│                          │    │  ├─ 🔨 Coder (iter 2) ✅ │
-│                          │    │  ├─ ✅ Review: APPROVED   │
-│                          │    │  ├─ 🧪 Tester: passed    │
-│                          │    │  └─ 🏁 Result: APPROVED  │
-└─────────────────────────┘    └─────────────────────────┘
-```
-
-**Full pipeline example**, a complex task with all roles:
-
-```
-┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
-│                                                                              │
-│  $ claude                                                                    │
-│                                                                              │
-│  > Build a REST API for a booking system. Requirements:                      │
-│  > - Express + TypeScript with Zod validation on every endpoint              │
-│  > - Endpoints: POST /bookings, GET /bookings/:id, PATCH /bookings/:id/cancel│
-│  > - A booking has: id, guestName, roomType (standard|suite|penthouse),      │
-│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
-│  > - Validate: checkOut must be after checkIn, no past dates,                │
-│  >   roomType must be a valid enum value                                     │
-│  > - Cancel returns 409 if already cancelled                                 │
-│  > - Use TDD. Run it through Karajan with architect and planner enabled,     │
-│  >   paranoid review mode. Coder claude, reviewer codex.                     │
-│                                                                              │
-│  Claude calls kj_run via MCP with:                                           │
-│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-
-┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
-│                                                                              │
-│  kj-tail v1.38.1 — .kj/run.log                                              │
-│                                                                              │
-│  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
-│  ├─ ⚙️ Preflight passed — all checks OK                                     │
-│  ├─ 🔬 Researcher: 8 files analyzed, 3 patterns, 5 constraints              │
-│  ├─ 🏗️ Architect: 3-layer design (routes → service → validators)            │
-│  ├─ 🧠 Planner: 6 steps — tests first, then routes, service, validators     │
-│  │                                                                           │
-│  ▶ Iteration 1/5                                                             │
-│  ├─ 🔨 Coder (claude): implemented 3 endpoints + 18 tests                   │
-│  ├─ 📋 TDD: PASS (3 src, 2 test files)                                      │
-│  ├─ 🔍 Sonar: Quality gate OK — 0 blockers                                  │
-│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
-│  │   "Missing 404 for GET nonexistent booking"                               │
-│  │   "Cancel endpoint lacks idempotency test"                                │
-│  ├─ ⚖️ Solomon: approve_with_conditions (2 conditions)                      │
-│  │   "Add 404 response and test for GET /bookings/:id with unknown id"       │
-│  │   "Add test: cancel already-cancelled booking returns 409, not 500"       │
-│  │                                                                           │
-│  ▶ Iteration 2/5                                                             │
-│  ├─ 🔨 Coder (claude): fixed — 22 tests now                                 │
-│  ├─ 📋 TDD: PASS                                                            │
-│  ├─ 🔍 Sonar: OK                                                            │
-│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
-│  ├─ 🧪 Tester: passed — coverage 94%, 22 tests                              │
-│  ├─ 🔒 Security: passed — 0 critical, 1 low (helmet recommended)            │
-│  ├─ 📊 Audit: CERTIFIED (with 3 advisory warnings)                          │
-│  │                                                                           │
-│  🏁 Result: APPROVED                                                         │
-│     🔬 Research: 8 files, 3 patterns identified                              │
-│     🗺 Plan: 6 steps (tests first)                                           │
-│     🧪 Coverage: 94%, 22 tests                                               │
-│     🔒 Security: passed                                                      │
-│     🔍 Sonar: OK                                                             │
-│     💰 Budget: $0.42 (claude: $0.38, codex: $0.04)                           │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
+Terminal 1                       Terminal 2
+
+$ claude                         $ kj-tail
+> implement the next
+  priority task                  [triage]     medium (sw)
+                                 [researcher] 3 patterns, 5 constraints
+(Claude calls kj_run             [planner]    6 steps (tests first)
+ via MCP, you see                [coder]      3 endpoints + 18 tests
+ only the final result)          [tdd]        PASS (3 src, 2 test)
+                                 [sonar]      Quality gate OK
+                                 [reviewer]   REJECTED (2 blocking)
+                                 [solomon]    2 conditions
+                                 [coder]      fixed, 22 tests now
+                                 [reviewer]   APPROVED
+                                 [tester]     94% coverage, 22 tests
+                                 [security]   passed
+                                 Result: APPROVED
 ```
 
 [**Watch the full pipeline demo**](https://karajancode.com#demo): triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.

package/package.json

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

package/src/commands/architect.js

@@ -63,7 +63,7 @@ export async function architectCommand({ task, config, logger, context, json })
   logger.info(`Architect (${architectRole.provider}) starting...`);
 
   const agent = createAgent(architectRole.provider, config, logger);
-  const prompt = buildArchitectPrompt({ task, researchContext: context });
+  const prompt = await buildArchitectPrompt({ task, researchContext: context });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await agent.runTask({ prompt, onOutput, role: "architect" });
 

package/src/commands/code.js

@@ -17,7 +17,7 @@ export async function codeCommand({ task, config, logger }) {
       try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
     }
   }
-  const prompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+  const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await coder.runTask({ prompt, onOutput, role: "coder" });
   if (!result.ok) {

package/src/commands/init.js

@@ -158,6 +158,15 @@ async function setupSonarQube(config, logger) {
     logger.info("SonarQube disabled — skipping container setup.");
     return;
   }
+
+  // Check Docker first — if not available, disable sonar gracefully
+  const dockerCheck = await runCommand("docker", ["--version"]);
+  if (dockerCheck.exitCode !== 0) {
+    logger.info("Docker not found — disabling SonarQube. Install Docker to enable it later.");
+    config.sonarqube.enabled = false;
+    return;
+  }
+
   const vmCheck = await checkVmMaxMapCount(os.platform());
   if (!vmCheck.ok) {
     logger.warn(`vm.max_map_count check failed: ${vmCheck.reason}`);
@@ -168,7 +177,9 @@ async function setupSonarQube(config, logger) {
 
   const sonar = await sonarUp();
   if (sonar.exitCode !== 0) {
-    throw new Error(`Failed to start SonarQube: ${sonar.stderr || sonar.stdout}`);
+    logger.info(`SonarQube could not be started — disabling for now. You can enable it later with 'kj sonar start'.`);
+    config.sonarqube.enabled = false;
+    return;
   }
 
   logger.info("SonarQube container started");

package/src/commands/review.js

@@ -32,7 +32,7 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
 
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
-  const prompt = buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
+  const prompt = await buildReviewerPrompt({ task, diff, reviewRules: rules, mode: config.review_mode });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
   const result = await reviewer.reviewTask({ prompt, onOutput, role: "reviewer" });
   if (!result.ok) {

package/src/mcp/server-handlers.js

@@ -25,6 +25,8 @@ import { createRunLog, readRunLog } from "../utils/run-log.js";
 import { currentBranch } from "../utils/git.js";
 import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
 import { ensureBootstrap } from "../bootstrap.js";
+import { validateSovereignty } from "./sovereignty-guard.js";
+import { handleSuggestion } from "./suggest-handler.js";
 
 /**
  * Resolve the user's project directory.
@@ -486,7 +488,7 @@ export async function handleCodeDirect(a, server, extra) {
       try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
     }
   }
-  const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
+  const prompt = await buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
   sendTrackerLog(server, "coder", "running", coderRole.provider);
   runLog.logText(`[coder] agent launched, waiting for response...`);
   let result;
@@ -533,7 +535,7 @@ export async function handleReviewDirect(a, server, extra) {
   const diff = await generateDiff({ baseRef: resolvedBase });
   const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
 
-  const prompt = buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
+  const prompt = await buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
   sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
   runLog.logText(`[reviewer] agent launched, waiting for response...`);
   let result;
@@ -823,6 +825,19 @@ async function handleRun(a, server, extra) {
       return failPayload(`Invalid taskType "${a.taskType}". Valid values: ${[...validTypes].join(", ")}`);
     }
   }
+
+  // Sovereignty guard: sanitise params and check for active sessions
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const sovereignty = validateSovereignty(a, { projectDir });
+  if (sovereignty.error) {
+    return failPayload(sovereignty.error);
+  }
+  if (sovereignty.warnings.length > 0) {
+    const logger = createLogger("info", "mcp");
+    for (const w of sovereignty.warnings) logger.warn(`[sovereignty] ${w}`);
+  }
+  Object.assign(a, sovereignty.params);
+
   await runBootstrapGate(server, a);
   if (!isPreflightAcked()) {
     // Auto-acknowledge with defaults for autonomous operation
@@ -963,6 +978,51 @@ async function handleScan(a, server) {
   return runKjCommand({ command: "scan", options: a });
 }
 
+async function handleSuggest(a) {
+  if (!a.suggestion) {
+    return failPayload("Missing required field: suggestion");
+  }
+  return handleSuggestion({
+    suggestion: a.suggestion,
+    context: a.context || null,
+    projectDir: a.projectDir || null
+  });
+}
+
+async function handleSkills(a) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const { isOpenSkillsAvailable, installSkill, removeSkill, listSkills, readSkill } =
+    await import("../skills/openskills-client.js");
+
+  const opts = { projectDir: a.projectDir || null };
+
+  switch (action) {
+    case "install": {
+      if (!a.source) return failPayload("Missing required field: source (required for install)");
+      const available = await isOpenSkillsAvailable();
+      if (!available) {
+        return failPayload("OpenSkills CLI is not available. Install it with: npm install -g openskills");
+      }
+      return installSkill(a.source, { ...opts, global: a.global || false });
+    }
+    case "remove": {
+      if (!a.name) return failPayload("Missing required field: name (required for remove)");
+      return removeSkill(a.name, opts);
+    }
+    case "list": {
+      return listSkills(opts);
+    }
+    case "read": {
+      if (!a.name) return failPayload("Missing required field: name (required for read)");
+      return readSkill(a.name, opts);
+    }
+    default:
+      return failPayload(`Unknown skills action: ${action}`);
+  }
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -986,7 +1046,9 @@ const toolHandlers = {
   kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
   kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
   kj_board:       (a) => handleBoard(a),
-  kj_hu:          (a, server) => handleHu(a, server)
+  kj_hu:          (a, server) => handleHu(a, server),
+  kj_suggest:     (a) => handleSuggest(a),
+  kj_skills:      (a) => handleSkills(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/sovereignty-guard.js

@@ -0,0 +1,112 @@
+/**
+ * Sovereignty guard for MCP inputs.
+ *
+ * Validates kj_run parameters and rejects host-AI attempts to override
+ * pipeline decisions that Karajan makes internally (triage, hu-reviewer, etc.).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Parameters that the host AI is allowed to pass through without restriction. */
+const ALLOWED_PARAMS = new Set([
+  "task", "projectDir", "pgTask", "pgProject",
+  "planner", "coder", "reviewer", "refactorer",
+  "plannerModel", "coderModel", "reviewerModel", "refactorerModel",
+  "enablePlanner", "enableReviewer", "enableRefactorer", "enableResearcher",
+  "enableTester", "enableSecurity", "enableImpeccable",
+  "enableDiscover", "enableArchitect",
+  "architectModel", "huFile",
+  "enableSerena", "enableBecaria",
+  "reviewerFallback", "reviewerRetries",
+  "mode", "maxIterations", "maxIterationMinutes", "maxTotalMinutes",
+  "baseBranch", "baseRef", "methodology",
+  "autoCommit", "autoPush", "autoPr", "autoRebase", "branchPrefix",
+  "autoSimplify", "smartModels", "checkpointInterval",
+  "taskType", "quiet", "noSonar", "enableSonarcloud",
+  "kjHome", "sonarToken", "timeoutMs",
+  // Sovereign flags — validated below but still "known"
+  "enableTriage", "enableHuReviewer",
+]);
+
+const MIN_ITERATIONS = 1;
+const MAX_ITERATIONS = 10;
+const ACTIVE_SESSION_THRESHOLD_MS = 60_000;
+
+/**
+ * Check if a pipeline is already running for this project.
+ * Looks at .kj/run.log modification time.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {{ active: boolean, message?: string }}
+ */
+export function checkActiveSession(projectDir) {
+  if (!projectDir) return { active: false };
+  const logPath = path.join(projectDir, ".kj", "run.log");
+  try {
+    const stat = fs.statSync(logPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < ACTIVE_SESSION_THRESHOLD_MS) {
+      return {
+        active: true,
+        message:
+          "A pipeline is already running for this project. " +
+          "Wait for it to complete or use kj_status to check progress.",
+      };
+    }
+  } catch {
+    // File doesn't exist or can't be read — no active session
+  }
+  return { active: false };
+}
+
+/**
+ * Validate and sanitise kj_run parameters.
+ *
+ * @param {Record<string, unknown>} params - Raw parameters from the MCP call
+ * @param {{ projectDir?: string }} context - Runtime context
+ * @returns {{ params: Record<string, unknown>, warnings: string[], error?: string }}
+ */
+export function validateSovereignty(params, context = {}) {
+  const warnings = [];
+  const sanitized = { ...params };
+
+  // 1. Strip unknown parameters
+  for (const key of Object.keys(sanitized)) {
+    if (!ALLOWED_PARAMS.has(key)) {
+      warnings.push(`Unknown parameter "${key}" stripped`);
+      delete sanitized[key];
+    }
+  }
+
+  // 2. Sovereign flags — pipeline decides, not the host AI
+  if (sanitized.enableHuReviewer === false) {
+    warnings.push("Pipeline decides hu-reviewer activation, ignoring override");
+    delete sanitized.enableHuReviewer;
+  }
+
+  if (sanitized.enableTriage === false) {
+    warnings.push("Triage is mandatory, ignoring override");
+    delete sanitized.enableTriage;
+  }
+
+  // 3. Clamp maxIterations to [1, 10]
+  if (sanitized.maxIterations !== undefined) {
+    const n = Number(sanitized.maxIterations);
+    if (!Number.isFinite(n) || n < MIN_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MIN_ITERATIONS}`);
+      sanitized.maxIterations = MIN_ITERATIONS;
+    } else if (n > MAX_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MAX_ITERATIONS}`);
+      sanitized.maxIterations = MAX_ITERATIONS;
+    }
+  }
+
+  // 4. Active session detection
+  const session = checkActiveSession(context.projectDir);
+  if (session.active) {
+    return { params: sanitized, warnings, error: session.message };
+  }
+
+  return { params: sanitized, warnings };
+}

package/src/mcp/suggest-handler.js

@@ -0,0 +1,91 @@
+/**
+ * Handler for kj_suggest MCP tool.
+ * Allows the host AI to propose observations to Solomon without override power.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "../utils/paths.js";
+
+/**
+ * Find the most recent running session for a given projectDir.
+ * If projectDir is not provided, returns the most recent running session overall.
+ */
+async function findActiveSession(projectDir) {
+  const sessionRoot = getSessionRoot();
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+  // Walk backwards (most recent first)
+  for (let i = dirs.length - 1; i >= 0; i--) {
+    try {
+      const raw = await fs.readFile(path.join(sessionRoot, dirs[i], "session.json"), "utf8");
+      const session = JSON.parse(raw);
+      if (session.status !== "running") continue;
+      if (projectDir && session.projectDir && session.projectDir !== projectDir) continue;
+      return session;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Handle a suggestion from the host AI.
+ * Logs it to the active session's suggestions array for Solomon to evaluate.
+ *
+ * @param {object} params
+ * @param {string} params.suggestion - The observation or proposal
+ * @param {string} [params.context] - Additional context
+ * @param {string} [params.projectDir] - Project directory to scope session lookup
+ * @returns {Promise<object>} Result with accepted status and message
+ */
+export async function handleSuggestion({ suggestion, context, projectDir }) {
+  if (!suggestion || typeof suggestion !== "string" || suggestion.trim() === "") {
+    return {
+      accepted: false,
+      reason: "Suggestion text is required and must be a non-empty string."
+    };
+  }
+
+  const session = await findActiveSession(projectDir);
+
+  if (!session) {
+    return {
+      accepted: false,
+      reason: "No active pipeline session. Suggestions are only evaluated during pipeline execution."
+    };
+  }
+
+  // Initialize suggestions array if not present
+  if (!Array.isArray(session.suggestions)) {
+    session.suggestions = [];
+  }
+
+  const entry = {
+    suggestion: suggestion.trim(),
+    context: context || null,
+    timestamp: new Date().toISOString()
+  };
+
+  session.suggestions.push(entry);
+
+  // Persist the updated session
+  const sessionRoot = getSessionRoot();
+  const sessionFile = path.join(sessionRoot, session.id, "session.json");
+  session.updated_at = new Date().toISOString();
+  await fs.writeFile(sessionFile, JSON.stringify(session, null, 2), "utf8");
+
+  return {
+    accepted: true,
+    status: "logged",
+    sessionId: session.id,
+    message: "Suggestion logged for Solomon evaluation in next iteration. Solomon will decide whether to act on it."
+  };
+}

package/src/mcp/tools.js

@@ -334,5 +334,33 @@ export const tools = [
         projectDir: { type: "string", description: "Project directory (defaults to cwd)" }
       }
     }
+  },
+  {
+    name: "kj_suggest",
+    description: "Propose an observation or suggestion to Karajan's Solomon engine. Solomon will evaluate it and decide whether to accept, reject, or ask the human. You CANNOT override pipeline decisions through this tool, only propose.",
+    inputSchema: {
+      type: "object",
+      required: ["suggestion"],
+      properties: {
+        suggestion: { type: "string", description: "What you observed or want to propose" },
+        context: { type: "string", description: "Additional context (current HU, iteration, etc.)" },
+        projectDir: { type: "string", description: "Project directory" }
+      }
+    }
+  },
+  {
+    name: "kj_skills",
+    description: "Manage OpenSkills for domain-specific agent knowledge. Install skills from the marketplace or GitHub repos to give coders domain expertise.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["install", "remove", "list", "read"], description: "Action to perform" },
+        source: { type: "string", description: "Skill source: marketplace name, GitHub URL, or local path (for install)" },
+        name: { type: "string", description: "Skill name (for remove/read)" },
+        global: { type: "boolean", description: "Install globally (~/.agent/skills/) instead of project-local" },
+        projectDir: { type: "string", description: "Project directory" }
+      },
+      required: ["action"]
+    }
   }
 ];

package/src/orchestrator/solomon-escalation.js

@@ -1,5 +1,5 @@
 import { SolomonRole } from "../roles/solomon-role.js";
-import { addCheckpoint, pauseSession } from "../session-store.js";
+import { addCheckpoint, pauseSession, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 
 /**
@@ -80,11 +80,19 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     })
   );
 
+  // Collect pending suggestions from the session for Solomon's context
+  const pendingSuggestions = Array.isArray(session.suggestions) && session.suggestions.length > 0
+    ? session.suggestions.slice()
+    : null;
+
   const solomon = new SolomonRole({ config, logger, emitter });
   await solomon.init({ task: conflict.task || session.task, iteration });
   let ruling;
   try {
-    ruling = await solomon.run({ conflict });
+    const conflictWithSuggestions = pendingSuggestions
+      ? { ...conflict, hostSuggestions: pendingSuggestions }
+      : conflict;
+    ruling = await solomon.run({ conflict: conflictWithSuggestions });
   } catch (err) {
     logger.warn(`Solomon threw: ${err.message}`);
     return escalateToHuman({
@@ -93,6 +101,12 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     });
   }
 
+  // Clear processed suggestions from session
+  if (pendingSuggestions) {
+    session.suggestions = [];
+    try { await saveSession(session); } catch { /* best-effort */ }
+  }
+
   const solomonError = ruling.result?.error;
   if (!ruling.ok && solomonError) {
     logger.warn(`Solomon execution failed: ${solomonError}`);

package/src/orchestrator.js

@@ -40,6 +40,8 @@ import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js"
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
 import { detectRtk } from "./utils/rtk-detect.js";
+import { detectNeededSkills, autoInstallSkills, cleanupAutoInstalledSkills } from "./skills/skill-detector.js";
+import { isOpenSkillsAvailable } from "./skills/openskills-client.js";
 
 
 // --- Product Context loader ---
@@ -97,8 +99,8 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
   const projectDir = config.projectDir || process.cwd();
   const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
   const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
-  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
+  const coderPrompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
+  const reviewerPrompt = await buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available), productContext: config.productContext || null });
 
   const summary = {
     dry_run: true,
@@ -845,6 +847,29 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
   stageResults.triage = triageResult.stageResult;
 
+  // --- Auto-install skills based on task + project detection ---
+  const projectDir = config.projectDir || process.cwd();
+  try {
+    const osAvailable = await isOpenSkillsAvailable();
+    if (osAvailable) {
+      const neededSkills = await detectNeededSkills(task, projectDir);
+      if (neededSkills.length > 0) {
+        const skillResult = await autoInstallSkills(neededSkills, projectDir);
+        if (skillResult.installed.length > 0) {
+          session.autoInstalledSkills = skillResult.installed;
+        }
+        emitProgress(emitter, makeEvent("skills:auto-install", { ...eventBase, stage: "triage" }, {
+          message: skillResult.installed.length > 0
+            ? `Auto-installed ${skillResult.installed.length} skill(s): ${skillResult.installed.join(", ")}`
+            : `Skills detected (${neededSkills.join(", ")}) — all already installed or unavailable`,
+          detail: skillResult
+        }));
+      }
+    }
+  } catch (err) {
+    logger.warn(`Skill auto-install 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) {
@@ -1387,44 +1412,60 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
   const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
 
-  // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
-  if (needsSubPipeline(ctx.stageResults.huReviewer)) {
-    logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);
-    emitProgress(emitter, makeEvent("hu:sub-pipeline:start", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
-      message: `Running ${ctx.stageResults.huReviewer.certified} HUs as sub-pipelines`,
-      detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
-    }));
+  try {
+    // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
+    if (needsSubPipeline(ctx.stageResults.huReviewer)) {
+      logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);
+      emitProgress(emitter, makeEvent("hu:sub-pipeline:start", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+        message: `Running ${ctx.stageResults.huReviewer.certified} HUs as sub-pipelines`,
+        detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
+      }));
 
-    const subPipelineResult = await runHuSubPipeline({
-      huReviewerResult: ctx.stageResults.huReviewer,
-      runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
-      emitter,
-      eventBase: ctx.eventBase,
-      logger
-    });
+      const subPipelineResult = await runHuSubPipeline({
+        huReviewerResult: ctx.stageResults.huReviewer,
+        runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
+        emitter,
+        eventBase: ctx.eventBase,
+        logger
+      });
 
-    emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
-      status: subPipelineResult.approved ? "ok" : "fail",
-      message: subPipelineResult.approved
-        ? "All HUs completed successfully"
-        : `Sub-pipeline finished with failures (${subPipelineResult.blockedIds.length} blocked)`,
-      detail: { results: subPipelineResult.results, blockedIds: subPipelineResult.blockedIds }
-    }));
+      emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+        status: subPipelineResult.approved ? "ok" : "fail",
+        message: subPipelineResult.approved
+          ? "All HUs completed successfully"
+          : `Sub-pipeline finished with failures (${subPipelineResult.blockedIds.length} blocked)`,
+        detail: { results: subPipelineResult.results, blockedIds: subPipelineResult.blockedIds }
+      }));
 
-    const finalResult = {
-      approved: subPipelineResult.approved,
-      sessionId: ctx.session.id,
-      huResults: subPipelineResult.results,
-      blockedIds: subPipelineResult.blockedIds
-    };
-    await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
-    return finalResult;
-  }
+      const finalResult = {
+        approved: subPipelineResult.approved,
+        sessionId: ctx.session.id,
+        huResults: subPipelineResult.results,
+        blockedIds: subPipelineResult.blockedIds
+      };
+      await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
+      return finalResult;
+    }
 
-  // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
-  const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
-  await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
-  return result;
+    // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
+    const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
+    await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
+    return result;
+  } finally {
+    // --- Cleanup auto-installed skills ---
+    const autoSkills = ctx.session?.autoInstalledSkills;
+    if (autoSkills && autoSkills.length > 0) {
+      const cleanProjectDir = ctx.config?.projectDir || process.cwd();
+      try {
+        const cleanupResult = await cleanupAutoInstalledSkills(autoSkills, cleanProjectDir);
+        if (cleanupResult.removed.length > 0) {
+          logger.info(`Cleaned up ${cleanupResult.removed.length} auto-installed skill(s): ${cleanupResult.removed.join(", ")}`);
+        }
+      } catch (err) {
+        logger.warn(`Skill cleanup failed (non-blocking): ${err.message}`);
+      }
+    }
+  }
 }
 
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {

package/src/prompts/architect.js

@@ -1,3 +1,5 @@
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -6,7 +8,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null }) {
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, projectDir = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -41,6 +43,14 @@ export function buildArchitectPrompt({ task, instructions, researchContext = nul
 
   sections.push(`## Task\n${task}`);
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }
 

package/src/prompts/coder.js

@@ -1,4 +1,5 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -31,7 +32,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null }) {
+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 }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -83,5 +84,13 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(deferredContext);
   }
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }

package/src/prompts/reviewer.js

@@ -1,4 +1,5 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -22,7 +23,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null }) {
+export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, projectDir = null }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const sections = [
@@ -53,5 +54,13 @@ export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabl
     `Git diff:\n${truncatedDiff}`
   );
 
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    const skillSection = buildSkillSection(skills);
+    if (skillSection) {
+      sections.push(skillSection);
+    }
+  }
+
   return sections.join("\n\n");
 }

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 = 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 });
     const runArgs = { prompt, role: "architect" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/roles/coder-role.js

@@ -34,7 +34,7 @@ export class CoderRole extends BaseRole {
       this.logger.info(`Host-as-coder: delegating to host AI (skipping ${provider} subprocess)`);
     }
 
-    const prompt = buildCoderPrompt({
+    const prompt = await buildCoderPrompt({
       task: task || this.context?.task || "",
       reviewerFeedback: reviewerFeedback || null,
       sonarSummary: sonarSummary || null,

package/src/skills/openskills-client.js

@@ -0,0 +1,157 @@
+/**
+ * OpenSkills CLI client.
+ * Wraps `npx openskills` commands for installing, removing, listing, and reading skills.
+ */
+
+import { runCommand } from "../utils/process.js";
+
+const NPX = "npx";
+const PKG = "openskills";
+
+function buildCwd(projectDir) {
+  return projectDir || process.cwd();
+}
+
+/**
+ * Check whether the openskills CLI is available.
+ * @returns {Promise<boolean>}
+ */
+export async function isOpenSkillsAvailable() {
+  try {
+    const result = await runCommand(NPX, [PKG, "--version"], {
+      timeout: 15_000
+    });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install a skill from a marketplace name, GitHub URL, or local path.
+ * @param {string} source - Skill source identifier.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @param {boolean} [opts.global] - Install globally (~/.agent/skills/).
+ * @returns {Promise<{ok: boolean, name?: string, error?: string}>}
+ */
+export async function installSkill(source, { projectDir, global: isGlobal } = {}) {
+  if (!source) {
+    return { ok: false, error: "source is required for install" };
+  }
+
+  const args = [PKG, "install", source];
+  if (isGlobal) args.push("--global");
+
+  const result = await runCommand(NPX, args, {
+    cwd: buildCwd(projectDir),
+    timeout: 60_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `install failed (exit ${result.exitCode})` };
+  }
+
+  // Try to extract the skill name from stdout
+  const output = (result.stdout || "").trim();
+  const nameMatch = output.match(/installed\s+(?:skill\s+)?["']?([^\s"']+)["']?/i)
+    || output.match(/([^\s/]+)\s*$/);
+  const name = nameMatch ? nameMatch[1] : source;
+
+  return { ok: true, name };
+}
+
+/**
+ * Remove an installed skill by name.
+ * @param {string} name - Skill name.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
+export async function removeSkill(name, { projectDir } = {}) {
+  if (!name) {
+    return { ok: false, error: "name is required for remove" };
+  }
+
+  const result = await runCommand(NPX, [PKG, "remove", name], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `remove failed (exit ${result.exitCode})` };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * List installed skills.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, skills?: Array<{name: string, source?: string, scope?: string}>, error?: string}>}
+ */
+export async function listSkills({ projectDir } = {}) {
+  const result = await runCommand(NPX, [PKG, "list", "--json"], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    // Fallback: try without --json
+    const fallback = await runCommand(NPX, [PKG, "list"], {
+      cwd: buildCwd(projectDir),
+      timeout: 30_000
+    });
+
+    if (fallback.exitCode !== 0) {
+      const stderr = (fallback.stderr || "").trim();
+      return { ok: false, error: stderr || `list failed (exit ${fallback.exitCode})` };
+    }
+
+    // Parse text output: each line is a skill name
+    const lines = (fallback.stdout || "").split("\n").map(l => l.trim()).filter(Boolean);
+    const skills = lines.map(line => ({ name: line }));
+    return { ok: true, skills };
+  }
+
+  // Parse JSON output
+  const stdout = (result.stdout || "").trim();
+  try {
+    const parsed = JSON.parse(stdout);
+    const skills = Array.isArray(parsed) ? parsed : (parsed.skills || []);
+    return { ok: true, skills };
+  } catch {
+    // If JSON parse fails, treat as text
+    const lines = stdout.split("\n").map(l => l.trim()).filter(Boolean);
+    const skills = lines.map(line => ({ name: line }));
+    return { ok: true, skills };
+  }
+}
+
+/**
+ * Read a skill's content by name.
+ * @param {string} name - Skill name.
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Working directory.
+ * @returns {Promise<{ok: boolean, content?: string, error?: string}>}
+ */
+export async function readSkill(name, { projectDir } = {}) {
+  if (!name) {
+    return { ok: false, error: "name is required for read" };
+  }
+
+  const result = await runCommand(NPX, [PKG, "read", name], {
+    cwd: buildCwd(projectDir),
+    timeout: 30_000
+  });
+
+  if (result.exitCode !== 0) {
+    const stderr = (result.stderr || "").trim();
+    return { ok: false, error: stderr || `read failed (exit ${result.exitCode})` };
+  }
+
+  return { ok: true, content: (result.stdout || "").trim() };
+}

package/src/skills/skill-detector.js

@@ -0,0 +1,187 @@
+/**
+ * Detects needed skills from task description and project files,
+ * then auto-installs them via OpenSkills if available.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadAvailableSkills } from "./skill-loader.js";
+import { isOpenSkillsAvailable, installSkill, removeSkill } from "./openskills-client.js";
+
+/**
+ * Known frameworks detectable from package.json dependencies.
+ * Maps dependency name to the skill name to search for.
+ */
+const PKG_JSON_FRAMEWORKS = {
+  astro: "astro",
+  next: "nextjs",
+  react: "react",
+  "react-dom": "react",
+  vue: "vue",
+  svelte: "svelte",
+  "@angular/core": "angular",
+  express: "express",
+  fastify: "fastify",
+  "@nestjs/core": "nestjs",
+};
+
+/**
+ * Language markers: file presence maps to a skill name.
+ * Reuses the same concept as src/utils/project-detect.js LANGUAGE_MARKERS.
+ */
+const LANGUAGE_FILE_MARKERS = [
+  { file: "pom.xml", skill: "java" },
+  { file: "build.gradle", skill: "java" },
+  { file: "build.gradle.kts", skill: "kotlin" },
+  { file: "go.mod", skill: "go" },
+  { file: "Cargo.toml", skill: "rust" },
+  { file: "pyproject.toml", skill: "python" },
+  { file: "setup.py", skill: "python" },
+  { file: "Gemfile", skill: "ruby" },
+  { file: "pubspec.yaml", skill: "flutter" },
+  { file: "Package.swift", skill: "swift" },
+  { file: "phpunit.xml", skill: "php" },
+  { file: "composer.json", skill: "php" },
+];
+
+/**
+ * Patterns to detect framework/skill mentions in the task text.
+ * Each entry: regex pattern (case-insensitive) -> skill name.
+ */
+const TASK_TEXT_PATTERNS = [
+  { pattern: /\bastro\b/i, skill: "astro" },
+  { pattern: /\bnext\.?js\b/i, skill: "nextjs" },
+  { pattern: /\breact\b/i, skill: "react" },
+  { pattern: /\bvue\b/i, skill: "vue" },
+  { pattern: /\bsvelte\b/i, skill: "svelte" },
+  { pattern: /\bangular\b/i, skill: "angular" },
+  { pattern: /\bexpress\b/i, skill: "express" },
+  { pattern: /\bfastify\b/i, skill: "fastify" },
+  { pattern: /\bnest\.?js\b/i, skill: "nestjs" },
+  { pattern: /\bjava\b/i, skill: "java" },
+  { pattern: /\bkotlin\b/i, skill: "kotlin" },
+  { pattern: /\bgo(?:lang)?\b/i, skill: "go" },
+  { pattern: /\brust\b/i, skill: "rust" },
+  { pattern: /\bpython\b/i, skill: "python" },
+  { pattern: /\bruby\b/i, skill: "ruby" },
+  { pattern: /\bflutter\b/i, skill: "flutter" },
+  { pattern: /\bswift\b/i, skill: "swift" },
+  { pattern: /\bphp\b/i, skill: "php" },
+];
+
+/**
+ * Analyze the task and project to determine what skills might be needed.
+ * @param {string} task - The task description text.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<string[]>} Array of unique skill names to search for.
+ */
+export async function detectNeededSkills(task, projectDir) {
+  const needed = new Set();
+
+  // 1. Scan package.json for known frameworks
+  if (projectDir) {
+    try {
+      const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
+      const pkg = JSON.parse(pkgRaw);
+      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const [dep, skill] of Object.entries(PKG_JSON_FRAMEWORKS)) {
+        if (allDeps[dep]) {
+          needed.add(skill);
+        }
+      }
+    } catch { /* no package.json or parse error — skip */ }
+
+    // 2. Check for language markers
+    for (const marker of LANGUAGE_FILE_MARKERS) {
+      try {
+        await fs.access(path.join(projectDir, marker.file));
+        needed.add(marker.skill);
+      } catch { /* file not found — skip */ }
+    }
+  }
+
+  // 3. Check task text for framework mentions
+  if (task) {
+    for (const { pattern, skill } of TASK_TEXT_PATTERNS) {
+      if (pattern.test(task)) {
+        needed.add(skill);
+      }
+    }
+  }
+
+  return Array.from(needed);
+}
+
+/**
+ * Auto-install needed skills that are not yet installed.
+ * @param {string[]} neededSkills - Skill names to ensure are installed.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{installed: string[], failed: string[], alreadyInstalled: string[]}>}
+ */
+export async function autoInstallSkills(neededSkills, projectDir) {
+  const result = { installed: [], failed: [], alreadyInstalled: [] };
+
+  if (!neededSkills || neededSkills.length === 0) {
+    return result;
+  }
+
+  // Check which skills are already installed locally
+  const existingSkills = await loadAvailableSkills(projectDir);
+  const existingNames = new Set(existingSkills.map(s => s.name.toLowerCase()));
+
+  // Check if OpenSkills is available
+  const osAvailable = await isOpenSkillsAvailable();
+  if (!osAvailable) {
+    // All skills count as "failed" silently — caller should check osAvailable separately
+    return result;
+  }
+
+  for (const skillName of neededSkills) {
+    if (existingNames.has(skillName.toLowerCase())) {
+      result.alreadyInstalled.push(skillName);
+      continue;
+    }
+
+    try {
+      const installResult = await installSkill(skillName, { projectDir });
+      if (installResult.ok) {
+        result.installed.push(installResult.name || skillName);
+      } else {
+        result.failed.push(skillName);
+      }
+    } catch {
+      result.failed.push(skillName);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove skills that were auto-installed during this session.
+ * @param {string[]} skillNames - Skill names to remove.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{removed: string[], failed: string[]}>}
+ */
+export async function cleanupAutoInstalledSkills(skillNames, projectDir) {
+  const result = { removed: [], failed: [] };
+
+  if (!skillNames || skillNames.length === 0) {
+    return result;
+  }
+
+  for (const name of skillNames) {
+    try {
+      const removeResult = await removeSkill(name, { projectDir });
+      if (removeResult.ok) {
+        result.removed.push(name);
+      } else {
+        result.failed.push(name);
+      }
+    } catch {
+      result.failed.push(name);
+    }
+  }
+
+  return result;
+}

package/src/skills/skill-loader.js

@@ -0,0 +1,58 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SKILL_DIRS = [".agent/skills", ".claude/skills"];
+const SKILL_FILE = "SKILL.md";
+
+/**
+ * Scans known skill directories for SKILL.md files.
+ * @param {string} projectDir — absolute path to the project root
+ * @returns {Promise<Array<{name: string, content: string}>>}
+ */
+export async function loadAvailableSkills(projectDir) {
+  const skills = [];
+
+  for (const rel of SKILL_DIRS) {
+    const dir = join(projectDir, rel);
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue; // directory does not exist — skip
+    }
+
+    for (const entry of entries) {
+      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 });
+      } catch {
+        // no SKILL.md in this subdirectory — skip
+      }
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Builds a prompt section from loaded skills.
+ * @param {Array<{name: string, content: string}>} skills
+ * @returns {string} prompt section or empty string
+ */
+export function buildSkillSection(skills) {
+  if (!skills || skills.length === 0) return "";
+
+  const header = [
+    "## Domain Skills",
+    "",
+    "The following domain-specific knowledge is available for this task:"
+  ].join("\n");
+
+  const blocks = skills.map(
+    (s) => `### ${s.name}\n${s.content}`
+  );
+
+  return [header, ...blocks].join("\n\n");
+}