karajan-code 2.6.1 → 2.7.0

package/package.json

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

package/src/cli.js

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

package/src/commands/skills.js

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

package/src/config/schema.js

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

package/src/config.js

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

package/src/orchestrator/flow-runner.js

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

package/src/skills/addyosmani-catalog.js

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

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

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