agent-skillboard 0.2.7 → 0.2.9

package/src/control/variant-files.mjs

@@ -35,7 +35,7 @@ export function resolveVariantSnapshotFile({ configPath, snapshotPath }) {
     throw new Error(`snapshot path must stay under ${SNAPSHOT_ROOT}`);
   }
   return {
-    storedPath: relative(configDir, absolutePath).replaceAll("\\", "/"),
+    storedPath: relative(configDir, absolutePath).replace(/\\/g, "/"),
     absolutePath,
     rootPath: root
   };
@@ -213,7 +213,7 @@ function normalizeStoredSnapshotPath(value) {
   if (value.includes("\0")) {
     throw new Error("snapshot path must not contain null bytes");
   }
-  const normalized = value.replaceAll("\\", "/");
+  const normalized = value.replace(/\\/g, "/");
   if (normalized.startsWith("/") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
     throw new Error("snapshot path must be relative to the config directory");
   }

package/src/doctor.mjs

@@ -45,7 +45,7 @@ export async function doctorProject(options = {}) {
   };
 
   if (!configExists) {
-    return finalizeDoctor(base, ["run skillboard init"]);
+    return finalizeDoctor(base, ["run skillboard setup once per user/agent install if agents should use SkillBoard for skill priority"]);
   }
 
   let workspace;

package/src/hook-plan.mjs

@@ -143,7 +143,7 @@ function modeToPermissions(mode) {
 }
 
 function shellQuote(value) {
-  return `'${value.replaceAll("'", "'\\''")}'`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
 function safeHookFilePart(value) {

package/src/install-output-detector.mjs

@@ -315,9 +315,9 @@ function normalizePath(value, root) {
 
 function displayPath(path, root) {
   if (!isAbsolute(path)) {
-    return path.replaceAll("\\", "/");
+    return path.replace(/\\/g, "/");
   }
-  const rel = relative(root, path).replaceAll("\\", "/");
+  const rel = relative(root, path).replace(/\\/g, "/");
   return rel.startsWith("..") ? path : rel;
 }
 

package/src/lifecycle-cli.mjs

@@ -1,7 +1,13 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 
+const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
+const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
+
 export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
   const root = resolve(options.get("dir") ?? ".");
   const result = await initProject({
@@ -36,6 +42,39 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
   return 0;
 }
 
+export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("dir") !== undefined) {
+    throw new Error("skillboard setup is agent-layer setup and does not accept --dir");
+  }
+  const targets = await agentSetupTargets(options, runtime);
+  if (targets.length === 0) {
+    stdout.write("No supported agent user skill roots were detected.\n");
+    stdout.write(`Create a supported agent home or pass --agent ${supportedAgentNames().join(",")} to choose targets.\n`);
+    return 1;
+  }
+  if (options.get("yes") !== "true") {
+    writeSetupConfirmation(stdout, targets, commandPrefix(runtime));
+    if (!canPrompt(runtime)) {
+      return 1;
+    }
+    const confirmed = await promptForSetup(runtime);
+    if (!confirmed) {
+      stdout.write("Skipped SkillBoard setup.\n");
+      return 1;
+    }
+  }
+  const result = await installAgentIntegration(targets);
+  stdout.write("SkillBoard agent integration installed.\n");
+  writeList(stdout, "Created", result.created);
+  writeList(stdout, "Updated", result.updated);
+  writeList(stdout, "Unchanged", result.unchanged);
+  writeList(stdout, "Preserved", result.preserved);
+  stdout.write("Next:\n");
+  stdout.write("- Restart or refresh agents that cache user skills.\n");
+  stdout.write('- Ask the agent in a workspace: "Which skill should you use for this?"\n');
+  return 0;
+}
+
 export async function runUninstallCommand(options, stdout) {
   const removeConfig = options.get("remove-config") === "true";
   const resetConfig = options.get("reset-config") === "true";
@@ -85,15 +124,15 @@ function writeCountedList(stdout, label, values) {
 }
 
 function writeSafetyDefault(stdout, safety) {
-  stdout.write("Safety default:\n");
-  stdout.write("- Installed does not mean allowed.\n");
+  stdout.write("Skill selection default:\n");
+  stdout.write("- Installed user skills are usable unless runtime, user, or local instructions disable them.\n");
   if (safety.automatic === 0) {
     stdout.write("- No automatic model invocation was enabled.\n");
   } else {
     stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
   }
-  stdout.write("- Imported local skills are manual-only.\n");
-  stdout.write("- Runtime/plugin/system skills require source review before manual activation.\n");
+  stdout.write("- Imported local skills are available on request in generated local policy.\n");
+  stdout.write("- Runtime/plugin/system skills require source review before automatic invocation.\n");
   stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
   stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
   stdout.write(`- ${safety.routerOnly} router-only skills available\n`);
@@ -120,6 +159,40 @@ function writeNextCommands(stdout, next) {
   stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)}${dir} --verbose\n`);
 }
 
+function writeSetupConfirmation(stdout, targets, command) {
+  stdout.write("SkillBoard setup installs agent-layer integration, not project files.\n");
+  stdout.write("It writes a SkillBoard guidance skill into detected user agent skill roots so agents can resolve skill priority when choices overlap.\n");
+  stdout.write("Targets:\n");
+  for (const target of targets) {
+    stdout.write(`- ${target.agent}: ${target.skillPath}\n`);
+  }
+  stdout.write("Run with --yes to install agent-layer integration:\n");
+  stdout.write(`- ${command} setup --agent ${targets.map((target) => target.agent).join(",")} --yes\n`);
+}
+
+function canPrompt(runtime) {
+  return runtime.stdin?.isTTY === true && runtime.stdout?.isTTY === true;
+}
+
+async function promptForSetup(runtime) {
+  const rl = createInterface({
+    input: runtime.stdin,
+    output: runtime.stdout
+  });
+  try {
+    const answer = await question(rl, "Install SkillBoard agent integration now? [y/N] ");
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+function question(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
 function formatList(values) {
   return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
 }
@@ -143,9 +216,96 @@ function defaultRuntime() {
   };
 }
 
+async function agentSetupTargets(options, runtime) {
+  const env = runtime.env ?? process.env;
+  const home = env.HOME ?? env.USERPROFILE;
+  const requested = readCsv(options.get("agent"));
+  const supported = new Set(supportedAgentNames());
+  const names = requested.length === 0 ? supportedAgentNames() : requested;
+  const targets = [];
+  for (const name of names) {
+    if (!supported.has(name)) {
+      throw new Error(`Unsupported setup agent: ${name}`);
+    }
+    targets.push(...await setupAgentSkillTargets(name, home, env, { includeFallback: requested.length > 0 }));
+  }
+  return targets;
+}
+
+async function installAgentIntegration(targets) {
+  const created = [];
+  const updated = [];
+  const unchanged = [];
+  const preserved = [];
+  const content = agentIntegrationSkill();
+  for (const target of targets) {
+    const existing = await readFile(target.skillPath, "utf8").catch((error) => {
+      if (error?.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    });
+    if (existing === content) {
+      unchanged.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    if (existing !== null && !existing.includes(AGENT_INTEGRATION_START)) {
+      preserved.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    await mkdir(dirname(target.skillPath), { recursive: true });
+    await writeFile(target.skillPath, content, "utf8");
+    (existing === null ? created : updated).push(`${target.agent}:${target.skillPath}`);
+  }
+  return { created, updated, unchanged, preserved };
+}
+
+function agentIntegrationSkill() {
+  return `---
+name: skillboard
+description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, or the user asks which skill should be used, preferred, avoided, reviewed, or prioritized for the current workflow.
+---
+${AGENT_INTEGRATION_START}
+# SkillBoard Agent Integration
+
+Use this skill to let SkillBoard guide skill selection above individual projects.
+
+## Layering
+
+- SkillBoard is the user-level control plane for skill priority, overlap resolution, and workflow-aware routing.
+- Project management belongs to the agent or workspace layer. Do not initialize, attach, rewrite, or manage a project just because SkillBoard is installed.
+- Package install and \`skillboard setup\` install user-agent guidance only.
+
+## Default Behavior
+
+- Installed user skills are usable by default unless the runtime, user, or local instructions disable them.
+- Do not ask for permission merely because you selected a skill.
+- When you use a skill, disclose it briefly at the start and completion.
+- Use SkillBoard when more than one skill matches, when skills overlap, or when workflow priority should choose between plausible skills.
+
+## Cross-Agent Skill Reuse
+
+- When the user wants to use a skill from another agent, run \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --json\`.
+- If SkillBoard reports the skill is compatible, install it with \`--yes\` and use the copied target-agent skill.
+- If SkillBoard reports \`needs-adaptation\`, explain the compatibility reasons and ask before changing the skill body for this agent.
+- If the user approves, inspect the source skill, write an adapted \`SKILL.md\` for this agent, then install it with \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --adapted-file <adapted-skill.md> --yes --json\`.
+- This is still user-agent setup. Do not create or mutate project policy files for cross-agent skill reuse.
+
+## Ambiguity Resolution
+
+1. Identify the candidate skills that match the request.
+2. Prefer the skill whose description, workflow guidance, and local instructions most directly match the user's task.
+3. If a project or agent has explicit SkillBoard policy, use \`skillboard brief --intent <request> --json\` or \`skillboard route <intent> --workflow <name> --json\` to break ties.
+4. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
+5. Continue with the selected skill; do not stop only because other candidate skills exist.
+
+${AGENT_INTEGRATION_END}
+`;
+}
+
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
-  const normalized = entrypoint.replaceAll("\\", "/");
+  const normalized = entrypoint.replace(/\\/g, "/");
   if (normalized.includes("/_npx/")) {
     const packageSpec = runtime.packageSpec ?? "agent-skillboard";
     return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
@@ -160,7 +320,7 @@ function isSourceTreeEntrypoint(entrypoint) {
   if (entrypoint === "") {
     return false;
   }
-  const normalized = entrypoint.replaceAll("\\", "/");
+  const normalized = entrypoint.replace(/\\/g, "/");
   return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
     && !normalized.includes("/node_modules/")
     && !normalized.includes("/_npx/")
@@ -169,7 +329,7 @@ function isSourceTreeEntrypoint(entrypoint) {
 
 function sourceTreeEntrypoint(entrypoint, cwd) {
   const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
-  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replaceAll("\\", "/");
+  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
   if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
     return shellQuote(relativeEntrypoint);
   }
@@ -180,5 +340,5 @@ function shellQuote(value) {
   if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
     return value;
   }
-  return `'${value.replaceAll("'", "'\\''")}'`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
 }

package/src/lifecycle-content.mjs

@@ -31,7 +31,7 @@ Your responsibility is to answer skill availability questions from SkillBoard, t
 
 ## Availability
 
-- Use SkillBoard as the source of truth; installed \`SKILL.md\` files are not automatically callable.
+- Use SkillBoard as the source of truth for project-local policy and workflow priority; installed \`SKILL.md\` files are candidates, not enough to resolve overlap by themselves.
 - Read the current brief before answering: \`skillboard brief --json --config skillboard.config.yaml --skills skills\`. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` when the user wants you to mediate a change.
 - When the user asks which skill fits a task, read \`skillboard brief --intent <request> --json --config skillboard.config.yaml --skills skills\`. Include \`--workflow <name>\` when known. Read \`assistant_guidance.route\`; use \`recommended_skill\`, \`fallback_skills\`, \`route_candidates\`, \`post_use_policy_suggestion\`, and \`guard_command\` instead of guessing from raw skill text. Inspect \`route_candidates\` when several skills match so denied candidates and selected fallbacks are clear. If \`post_use_policy_suggestion\` is present, work first with the allowed routed skill, then ask after completion whether to remember the suggested policy. If no skill matches, ask a clarifying question before choosing a skill.
 - Treat the brief sections headed "What your AI can use now", "Needs your decision", and "Blocked for safety" as the availability summary; do not infer availability from \`SKILL.md\` bodies.

package/src/skill-paths.mjs

@@ -5,7 +5,7 @@ export function normalizeSkillPath(value, label = "skill path") {
   if (value.includes("\0")) {
     throw new Error(`${label} must not contain null bytes`);
   }
-  const normalized = value.replaceAll("\\", "/");
+  const normalized = value.replace(/\\/g, "/");
   if (normalized.startsWith("/") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
     throw new Error(`${label} must be relative to the skills root`);
   }

package/src/source-cache.mjs

@@ -164,7 +164,7 @@ function resolveUnderRoot(root, path) {
 }
 
 function relativePath(root, path) {
-  const rel = relative(root, path).replaceAll("\\", "/");
+  const rel = relative(root, path).replace(/\\/g, "/");
   return rel.startsWith("..") ? path : rel;
 }
 

package/src/source-profiles.mjs

@@ -14,7 +14,7 @@ export async function importSource(options) {
   const matchedFiles = files
     .map((file) => ({
       file,
-      relativeFile: relative(sourceRoot, file).replaceAll("\\", "/")
+      relativeFile: relative(sourceRoot, file).replace(/\\/g, "/")
     }))
     .filter((entry) => matchesAnyProfilePattern(entry.relativeFile, profile.skillPaths))
     .sort((left, right) => left.relativeFile.localeCompare(right.relativeFile));
@@ -238,9 +238,9 @@ function matchingPathRule(file, profile) {
 function patternToRegExp(pattern) {
   const escaped = pattern
     .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replaceAll("**", "\0")
-    .replaceAll("*", "[^/]*")
-    .replaceAll("\0", ".*");
+    .split("**").join("\0")
+    .split("*").join("[^/]*")
+    .split("\0").join(".*");
   return new RegExp(`^${escaped}$`);
 }
 

package/src/source-verification.mjs

@@ -165,7 +165,7 @@ export async function sourceDigest(path) {
 
 async function addPathDigest(hash, root, path) {
   const stats = await lstat(path);
-  const rel = relative(root, path).replaceAll("\\", "/") || ".";
+  const rel = relative(root, path).replace(/\\/g, "/") || ".";
   if (stats.isSymbolicLink()) {
     hash.update(`symlink\0${rel}\0${await readlink(path)}\n`);
     return;

package/src/uninstall.mjs

@@ -1,3 +1,4 @@
+// allow: SIZE_OK - uninstall lifecycle split is deferred from the 0.2.7 release gate.
 import { access, lstat, readFile, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { BRIDGE_END, BRIDGE_START, defaultConfig, hookReadme, profileReadme } from "./lifecycle-content.mjs";

package/src/workspace.mjs

@@ -51,7 +51,7 @@ async function discoverInstalledSkills(skillsRoot, declaredSkills, options = {})
     const skillFiles = await findSkillFiles(skillsRoot);
     for (const file of skillFiles) {
       const frontmatter = parseSkillFrontmatter(await readFile(file, "utf8"));
-      const path = relative(skillsRoot, file).replaceAll("\\", "/").replace(/\/SKILL\.md$/, "");
+      const path = relative(skillsRoot, file).replace(/\\/g, "/").replace(/\/SKILL\.md$/, "");
       const declared = declaredSkills.find((skill) => skill.path === path);
       appendInstalledSkill(installed, installedKeys, {
         id: declared?.id ?? frontmatter.name ?? path,