@karajan-family/code 4.21.0

package/src/skills/addyosmani-catalog.js

@@ -0,0 +1,315 @@
+/**
+ * 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"|"reset"|"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 pullResult = await runCommand(
+    "git",
+    ["-C", root, "pull", "--ff-only", "--depth", "1"],
+    { timeout: 60_000 }
+  );
+
+  let action = "pulled";
+  if (pullResult.exitCode !== 0) {
+    // The cached catalog is read-only (we never commit to it), so a
+    // non-fast-forward result is virtually always upstream rewriting
+    // history with `git push --force` — see KJC-BUG-0033 / N3-2 (the
+    // user hit this on 2026-05-07 when addyosmani force-pushed his
+    // skills repo). Recover by fetching shallow and hard-resetting to
+    // FETCH_HEAD: there's nothing local to lose.
+    const fetchResult = await runCommand(
+      "git",
+      ["-C", root, "fetch", "--depth", "1", "origin", "HEAD"],
+      { timeout: 60_000 }
+    );
+    const resetResult = fetchResult.exitCode === 0
+      ? await runCommand("git", ["-C", root, "reset", "--hard", "FETCH_HEAD"], { timeout: 30_000 })
+      : { exitCode: fetchResult.exitCode, stderr: fetchResult.stderr };
+
+    if (resetResult.exitCode !== 0) {
+      const pullErr = (pullResult.stderr || "").trim();
+      const recoveryErr = (resetResult.stderr || "").trim();
+      const combined = recoveryErr ? `${pullErr} | recovery: ${recoveryErr}` : pullErr;
+      logger?.warn?.(`addyosmani-catalog: git pull failed — ${combined} (keeping stale cache)`);
+      return { ok: false, action: "skipped", error: combined };
+    }
+    action = "reset";
+    logger?.info?.("addyosmani-catalog: ff-only failed, recovered via fetch+reset (upstream force-pushed)");
+  }
+
+  await writeMeta({
+    ...(meta || {}),
+    repoUrl,
+    lastPullAt: new Date().toISOString(),
+  });
+
+  return { ok: true, action };
+}
+
+/**
+ * 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().replaceAll(/[^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,139 @@
+/**
+ * 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" },
+  // Accessibility (a11y / WCAG / ARIA / screen reader / keyboard nav).
+  // No dedicated addyosmani skill exists yet for a11y; until one ships,
+  // route to frontend-ui-engineering — the closest authoritative source
+  // for WCAG-aware UI work. When upstream ships an a11y skill, change
+  // only the `slug` field here.
+  { pattern: /\baccessibility\b|\ba11y\b|\bwcag\b|\baria\b|\bscreen[\s-]?reader\b|\bkeyboard[\s-]?nav(igation)?\b/i, slug: "frontend-ui-engineering" },
+  { pattern: /\bapi\b|\bendpoint\b|\binterface\s+design\b|\bopenapi\b|\brest\b|\bgraphql\b/i, slug: "api-and-interface-design" },
+  { pattern: /\bci\b|\bcd\b|\bci\/cd\b|\bpipeline\b|\bgithub\s+actions\b|\bworkflow\b/i, slug: "ci-cd-and-automation" },
+  { pattern: /\bgit\b|\bcommit\b|\bbranch\b|\bmerge\b|\bversioning\b|\bsemver\b/i, slug: "git-workflow-and-versioning" },
+  { pattern: /\bdebug\b|\berror\s+recovery\b|\bstack\s+trace\b/i, slug: "debugging-and-error-recovery" },
+  { pattern: /\bdeprecat|\bmigrat/i, slug: "deprecation-and-migration" },
+  { pattern: /\bdocs?\b|\badr\b|\breadme\b|\bdocumentation\b/i, slug: "documentation-and-adrs" },
+  { pattern: /\brelease\b|\blaunch\b|\bship\b/i, slug: "shipping-and-launch" },
+  { pattern: /\bspec\b|\bspecification\b|\bprd\b/i, slug: "spec-driven-development" },
+  { pattern: /\bidea\b|\brefine\b|\bdiscover/i, slug: "idea-refine" },
+  { pattern: /\bbrowser\s+test|\bdevtools\b|\bchrome\s+devtools\b/i, slug: "browser-testing-with-devtools" },
+];
+
+/**
+ * Resolve the set of addyosmani slugs that apply to a given (role, task)
+ * tuple. Returns a deduped array preserving role-first ordering (so role
+ * skills appear before task-inferred ones in the prompt).
+ *
+ * @param {{role?: string|null, task?: string|null}} args
+ * @returns {string[]}
+ */
+export function resolveAddyosmaniSlugs({ role = null, task = null } = {}) {
+  const out = [];
+  const seen = new Set();
+
+  const push = (slug) => {
+    if (!slug || seen.has(slug)) return;
+    seen.add(slug);
+    out.push(slug);
+  };
+
+  if (role && ROLE_TO_ADDYOSMANI_SLUGS[role]) {
+    for (const slug of ROLE_TO_ADDYOSMANI_SLUGS[role]) push(slug);
+  }
+
+  if (task && typeof task === "string") {
+    for (const { pattern, slug } of TASK_PATTERN_TO_SLUG) {
+      if (pattern.test(task)) push(slug);
+    }
+  }
+
+  return out;
+}

package/src/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 { /* openskills CLI not available */
+    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() };
+}