karajan-code 1.40.0 → 1.42.0

package/package.json

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

package/src/audit/basal-cost.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFile, execFileSync } from "node:child_process";
+import { getKarajanHome } from "../utils/paths.js";
+
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".tsx", ".jsx",
+  ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift", ".c", ".cpp", ".h",
+  ".vue", ".svelte", ".astro", ".php", ".cs", ".sh"
+]);
+
+const EXCLUDE_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "coverage", ".next",
+  ".nuxt", ".output", "__pycache__", ".cache", ".parcel-cache"
+]);
+
+function slugify(projectDir) {
+  return path.basename(projectDir).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function walkSourceFiles(dir) {
+  // Use git ls-files for speed (instant vs recursive walk)
+  try {
+    const output = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], { cwd: dir, encoding: "utf8", timeout: 5000 });
+    return output.trim().split("\n")
+      .filter(f => f && SOURCE_EXTENSIONS.has(path.extname(f)) && !EXCLUDE_DIRS.has(f.split("/")[0]))
+      .map(f => path.join(dir, f));
+  } catch {
+    // Fallback to recursive walk if not a git repo
+    const files = [];
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return files;
+    }
+    for (const entry of entries) {
+      if (EXCLUDE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...walkSourceFiles(full));
+      } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+        files.push(full);
+      }
+    }
+    return files;
+  }
+}
+
+function countLines(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return content.split("\n").length;
+  } catch {
+    return 0;
+  }
+}
+
+function countDependencies(projectDir) {
+  const pkgPath = path.join(projectDir, "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const deps = Object.keys(pkg.dependencies || {});
+    const devDeps = Object.keys(pkg.devDependencies || {});
+    return { dependencies: deps.length, devDependencies: devDeps.length, total: deps.length + devDeps.length };
+  } catch {
+    return { dependencies: 0, devDependencies: 0, total: 0 };
+  }
+}
+
+function runDepcheck(projectDir) {
+  return new Promise((resolve) => {
+    execFile("npx", ["depcheck", "--json"], { cwd: projectDir, timeout: 30000 }, (err, stdout) => {
+      if (err && !stdout) {
+        resolve({ unused: [], note: "depcheck not available or failed" });
+        return;
+      }
+      try {
+        const result = JSON.parse(stdout);
+        const unused = [
+          ...(result.dependencies || []),
+          ...(result.devDependencies || [])
+        ];
+        resolve({ unused });
+      } catch {
+        resolve({ unused: [], note: "depcheck output not parseable" });
+      }
+    });
+  });
+}
+
+function findDeadExports(sourceFiles) {
+  const exportMap = new Map(); // file -> [exportName]
+  const importedNames = new Set();
+
+  const exportRe = /export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
+  const namedExportRe = /export\s*\{([^}]+)\}/g;
+  const importRe = /import\s+\{([^}]+)\}\s+from/g;
+  const defaultImportRe = /import\s+(\w+)\s+from/g;
+
+  for (const file of sourceFiles) {
+    let content;
+    try {
+      content = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+
+    const exports = [];
+    for (const match of content.matchAll(exportRe)) {
+      exports.push(match[1]);
+    }
+    for (const match of content.matchAll(namedExportRe)) {
+      const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/).pop().trim());
+      exports.push(...names);
+    }
+    if (exports.length > 0) {
+      exportMap.set(file, exports);
+    }
+
+    for (const match of content.matchAll(importRe)) {
+      const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/)[0].trim());
+      for (const name of names) importedNames.add(name);
+    }
+    for (const match of content.matchAll(defaultImportRe)) {
+      importedNames.add(match[1]);
+    }
+  }
+
+  const dead = [];
+  for (const [file, exports] of exportMap) {
+    for (const name of exports) {
+      if (!importedNames.has(name)) {
+        dead.push({ file, name });
+      }
+    }
+  }
+  return dead;
+}
+
+export async function measureBasalCost(projectDir) {
+  const sourceFiles = walkSourceFiles(projectDir);
+  let totalLines = 0;
+  for (const f of sourceFiles) {
+    totalLines += countLines(f);
+  }
+
+  const depInfo = countDependencies(projectDir);
+  const depcheck = await runDepcheck(projectDir);
+  const deadExports = findDeadExports(sourceFiles);
+
+  return {
+    totalLines,
+    totalFiles: sourceFiles.length,
+    dependencies: depInfo,
+    unusedDependencies: depcheck,
+    deadExports
+  };
+}
+
+function auditDir() {
+  return path.join(getKarajanHome(), "audits");
+}
+
+export function loadPreviousAudit(projectDir) {
+  const file = path.join(auditDir(), slugify(projectDir), "latest.json");
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function saveAuditSnapshot(projectDir, metrics) {
+  const dir = path.join(auditDir(), slugify(projectDir));
+  fs.mkdirSync(dir, { recursive: true });
+  const snapshot = { ...metrics, timestamp: new Date().toISOString() };
+  fs.writeFileSync(path.join(dir, "latest.json"), JSON.stringify(snapshot, null, 2));
+  return snapshot;
+}
+
+export function computeGrowthDelta(current, previous) {
+  if (!previous) return null;
+  return {
+    lines: current.totalLines - previous.totalLines,
+    files: current.totalFiles - previous.totalFiles,
+    deps: current.dependencies.total - (previous.dependencies?.total ?? 0),
+    since: previous.timestamp || null
+  };
+}

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/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/hu/lazy-planner.js

@@ -0,0 +1,104 @@
+/**
+ * Lazy HU Planner — refines HUs one at a time using context from completed HUs.
+ *
+ * Instead of fully planning all HUs upfront, only the first HU is decomposed
+ * with full acceptance criteria. Subsequent HUs are refined lazily before
+ * execution, incorporating learnings from previously completed HUs.
+ */
+import { createAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.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.",
+  "Do NOT use any MCP tools. Focus only on refining the user story."
+].join(" ");
+
+/**
+ * Build a prompt asking the AI to refine an HU based on context from completed HUs.
+ * @param {object} hu - The HU to refine (with at least id, original.text or certified.text).
+ * @param {Array<object>} completedHus - Array of completed HU results with summaries.
+ * @returns {string} The assembled refinement prompt.
+ */
+export function buildRefinementPrompt(hu, completedHus) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  sections.push("## HU Refinement");
+  sections.push(
+    "You are a senior product owner. Refine the following user story by adding or updating its acceptance criteria.",
+    "Use the context from previously completed HUs to make the criteria more precise and avoid redundant work."
+  );
+
+  if (completedHus.length > 0) {
+    sections.push("## Previously Completed HUs");
+    for (const completed of completedHus) {
+      const title = completed.certified?.title || completed.id;
+      const summary = completed.resultSummary || completed.certified?.text || completed.original?.text || "No summary available";
+      sections.push(`### ${completed.id} — ${title}\nResult: ${summary}`);
+    }
+  }
+
+  const huText = hu.certified?.text || hu.original?.text || `Implement HU ${hu.id}`;
+  sections.push(`## HU to Refine\n### ${hu.id}\n${huText}`);
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: {"id":string,"title":string,"text":string,"acceptanceCriteria":[string]}`,
+    "Rules:",
+    "- Keep the same HU id",
+    "- Refine the description to be more specific based on what was learned",
+    "- Add concrete, testable acceptance criteria",
+    "- Avoid repeating work already done in completed HUs",
+    "- The text field should be the full story description ready for implementation"
+  );
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Refine an HU using AI, incorporating context from completed HUs.
+ * @param {object} hu - The HU story object to refine.
+ * @param {Array<object>} completedHus - Completed HU stories with results.
+ * @param {object} config - Pipeline configuration.
+ * @param {object} logger - Logger instance.
+ * @returns {Promise<object>} Updated HU object with refined description and AC.
+ */
+export async function refineHuWithContext(hu, completedHus, config, logger) {
+  const provider = config?.roles?.hu_reviewer?.provider || config?.roles?.coder?.provider || "claude";
+  const prompt = buildRefinementPrompt(hu, completedHus);
+
+  logger.info(`Lazy planner: refining HU ${hu.id} with context from ${completedHus.length} completed HU(s)`);
+
+  const agent = createAgent(provider, config, logger);
+  let result;
+  try {
+    result = await agent.runTask({ prompt, role: "hu-reviewer" });
+  } catch (err) {
+    logger.warn(`Lazy planner: refinement failed for HU ${hu.id}: ${err.message}`);
+    return hu;
+  }
+
+  if (!result.ok) {
+    logger.warn(`Lazy planner: refinement returned not-ok for HU ${hu.id}`);
+    return hu;
+  }
+
+  const parsed = extractFirstJson(result.output);
+  if (!parsed || !parsed.text) {
+    logger.warn(`Lazy planner: could not parse refinement output for HU ${hu.id}`);
+    return hu;
+  }
+
+  // Update the HU with refined content
+  const refined = { ...hu };
+  refined.certified = {
+    ...(hu.certified || {}),
+    text: parsed.text,
+    title: parsed.title || hu.certified?.title || hu.id,
+    acceptanceCriteria: parsed.acceptanceCriteria || []
+  };
+  refined.needsRefinement = false;
+
+  logger.info(`Lazy planner: HU ${hu.id} refined successfully`);
+  return refined;
+}

package/src/mcp/server-handlers.js

@@ -488,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;
@@ -535,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;
@@ -989,6 +989,40 @@ async function handleSuggest(a) {
   });
 }
 
+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 = {
@@ -1013,7 +1047,8 @@ const toolHandlers = {
   kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
   kj_board:       (a) => handleBoard(a),
   kj_hu:          (a, server) => handleHu(a, server),
-  kj_suggest:     (a) => handleSuggest(a)
+  kj_suggest:     (a) => handleSuggest(a),
+  kj_skills:      (a) => handleSkills(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -347,5 +347,20 @@ export const tools = [
         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/hu-sub-pipeline.js

@@ -5,6 +5,7 @@
 import { topologicalSort } from "../hu/graph.js";
 import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
+import { refineHuWithContext } from "../hu/lazy-planner.js";
 
 /**
  * Determine whether the HU reviewer result requires a sub-pipeline
@@ -72,7 +73,7 @@ function buildHuTask(story) {
  * @param {object} params.logger - Logger instance
  * @returns {Promise<{approved: boolean, results: object[], blockedIds: string[]}>}
  */
-export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger }) {
+export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger, config = null }) {
   const batchSessionId = huReviewerResult.batchSessionId;
   let batch;
   try {
@@ -108,6 +109,40 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
       continue;
     }
 
+    // --- Lazy refinement: refine HU if it needs it, using completed HU context ---
+    if (story.needsRefinement && config) {
+      const completedHus = results
+        .filter(r => r.approved)
+        .map(r => {
+          const completedStory = batch.stories.find(s => s.id === r.huId);
+          return {
+            ...completedStory,
+            resultSummary: r.result?.summary || r.result?.reason || null
+          };
+        });
+
+      emitProgress(emitter, makeEvent("hu:refine-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        message: `Refining HU ${story.id} with context from ${completedHus.length} completed HU(s)`,
+        detail: { huId: story.id, completedCount: completedHus.length }
+      }));
+
+      try {
+        const refined = await refineHuWithContext(story, completedHus, config, logger);
+        // Apply refinement to the batch story in-place
+        Object.assign(story, refined);
+        story.needsRefinement = false;
+        await saveHuBatch(batchSessionId, batch);
+
+        emitProgress(emitter, makeEvent("hu:refine-end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+          message: `HU ${story.id} refined successfully`,
+          detail: { huId: story.id }
+        }));
+      } catch (err) {
+        logger.warn(`Lazy refinement failed for HU ${story.id}: ${err.message} — proceeding with original`);
+        story.needsRefinement = false;
+      }
+    }
+
     const huTask = buildHuTask(story);
 
     // --- hu:start ---

package/src/orchestrator/pre-loop-stages.js

@@ -646,11 +646,17 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
       config, logger, emitter, eventBase, session, coderRole, trackBudget
     });
     if (decomposed && decomposed.length > 1) {
-      stories = decomposed.map(hu => ({
-        id: hu.id,
-        text: `As a ${hu.role}, I want to ${hu.goal}, so that ${hu.benefit}\n\nTitle: ${hu.title}\nAcceptance Criteria:\n${hu.acceptanceCriteria.map(ac => `- ${ac}`).join("\n")}`,
-        blocked_by: hu.dependsOn || []
-      }));
+      stories = decomposed.map((hu, idx) => {
+        const isFirst = idx === 0;
+        const fullText = `As a ${hu.role}, I want to ${hu.goal}, so that ${hu.benefit}\n\nTitle: ${hu.title}\nAcceptance Criteria:\n${hu.acceptanceCriteria.map(ac => `- ${ac}`).join("\n")}`;
+        const skeletonText = `As a ${hu.role}, I want to ${hu.goal}, so that ${hu.benefit}\n\nTitle: ${hu.title}`;
+        return {
+          id: hu.id,
+          text: isFirst ? fullText : skeletonText,
+          blocked_by: hu.dependsOn || [],
+          needsRefinement: !isFirst
+        };
+      });
     } else {
       stories = [{ id: "HU-AUTO-001", text: session.task }];
     }

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,61 @@ 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,
+        config: ctx.config
+      });
 
-    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/audit.js

@@ -14,7 +14,7 @@ const VALID_SCORES = new Set(["A", "B", "C", "D", "F"]);
 const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low"]);
 const VALID_IMPACT = new Set(["high", "medium", "low"]);
 
-export function buildAuditPrompt({ task, instructions, dimensions = null, context = null }) {
+export function buildAuditPrompt({ task, instructions, dimensions = null, context = null, basalCost = null, growthDelta = null }) {
   const sections = [SUBAGENT_PREAMBLE];
 
   if (instructions) {
@@ -112,6 +112,40 @@ export function buildAuditPrompt({ task, instructions, dimensions = null, contex
     `Only include dimensions you were asked to analyze: ${activeDimensions.join(", ")}`
   );
 
+  if (basalCost) {
+    const lines = [
+      "## Basal Cost",
+      `- Total source lines: ${basalCost.totalLines}`,
+      `- Total source files: ${basalCost.totalFiles}`,
+      `- Dependencies: ${basalCost.dependencies?.total ?? 0} (${basalCost.dependencies?.dependencies ?? 0} prod + ${basalCost.dependencies?.devDependencies ?? 0} dev)`
+    ];
+    if (basalCost.unusedDependencies?.unused?.length > 0) {
+      lines.push(`- Unused dependencies: ${basalCost.unusedDependencies.unused.join(", ")}`);
+    } else if (basalCost.unusedDependencies?.note) {
+      lines.push(`- Unused dependencies: ${basalCost.unusedDependencies.note}`);
+    }
+    if (basalCost.deadExports?.length > 0) {
+      lines.push(`- Dead exports (exported but never imported): ${basalCost.deadExports.length}`);
+      for (const de of basalCost.deadExports.slice(0, 20)) {
+        lines.push(`  - ${de.name} in ${de.file}`);
+      }
+      if (basalCost.deadExports.length > 20) {
+        lines.push(`  - ... and ${basalCost.deadExports.length - 20} more`);
+      }
+    }
+    if (growthDelta) {
+      lines.push("");
+      lines.push("### Growth since last audit");
+      lines.push(`- Lines: ${growthDelta.lines >= 0 ? "+" : ""}${growthDelta.lines}`);
+      lines.push(`- Files: ${growthDelta.files >= 0 ? "+" : ""}${growthDelta.files}`);
+      lines.push(`- Dependencies: ${growthDelta.deps >= 0 ? "+" : ""}${growthDelta.deps}`);
+      if (growthDelta.since) lines.push(`- Since: ${growthDelta.since}`);
+    }
+    lines.push("");
+    lines.push("Flag if basal cost is growing faster than feature delivery. Recommend elimination of unused code and dependencies.");
+    sections.push(lines.join("\n"));
+  }
+
   if (context) {
     sections.push(`## Context\n${context}`);
   }

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/audit-role.js

@@ -1,6 +1,7 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
 
 function resolveProvider(config) {
   return (
@@ -57,7 +58,18 @@ export class AuditRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context });
+    const projectDir = this.config?.projectDir || process.cwd();
+    let basalCost = null;
+    let growthDelta = null;
+    try {
+      basalCost = await measureBasalCost(projectDir);
+      const previous = loadPreviousAudit(projectDir);
+      growthDelta = computeGrowthDelta(basalCost, previous);
+    } catch {
+      // basal cost is best-effort, don't fail the audit
+    }
+
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context, basalCost, growthDelta });
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);
@@ -82,12 +94,18 @@ export class AuditRole extends BaseRole {
         };
       }
 
+      if (basalCost) {
+        try { saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ }
+      }
+
       return {
         ok: true,
         result: {
           summary: parsed.summary,
           dimensions: parsed.dimensions,
           topRecommendations: parsed.topRecommendations,
+          basalCost: basalCost || undefined,
+          growthDelta: growthDelta || undefined,
           provider
         },
         summary: buildSummary(parsed),

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");
+}