agent-skillboard 0.2.15 → 0.2.16

package/docs/routing.md

@@ -3,6 +3,12 @@
 Capability routing helps an AI choose a skill for the user's current request
 without making the user learn SkillBoard commands.
 
+SkillBoard is intentionally permissive at this layer: workflow-bound skills can
+remain broadly available, and routing only chooses the skill that should steer
+this request. When several allowed skills match, the response includes
+`overlap_resolution` so the AI can explain that the other skills stayed
+available while the workflow routed to one selected skill.
+
 For the normal AI-mediated flow, prefer `brief --intent`. It returns the
 availability brief and the routing result together:
 
@@ -25,6 +31,8 @@ Read `assistant_guidance.route` from the JSON output. It includes:
 - `recommended_skill`
 - `fallback_skills`
 - `route_candidates`
+- `overlap_resolution`
+- `policy_memory`
 - `post_use_policy_suggestion`
 - `guard_command`
 - `usage_disclosure`
@@ -42,6 +50,13 @@ When several skills match, inspect `route_candidates` before acting. Each entry
 shows the candidate skill, whether it was selected, whether the guard currently
 allows it, and the guard reason when it is denied. This is the field that tells
 an AI why a preferred skill was skipped and an allowed fallback was selected.
+Inspect `overlap_resolution` first when it is present: `status: resolved` with
+`mode: permissive-routing` means multiple allowed skills matched, SkillBoard
+kept them available, and the current workflow still has one deterministic route.
+When `policy_memory` is present, remembered or configured workflow policy
+selected the routed skill while other allowed skills were also available. The AI
+should mention that after completion so the user knows a stored policy
+preference shaped the route.
 
 When routing is safe but policy learning would reduce future ambiguity,
 SkillBoard may return `post_use_policy_suggestion`. This includes cases where a

package/docs/user-flow.md

@@ -1,19 +1,25 @@
 # First-Time Skill Control Flow
 
-This flow assumes a user installed SkillBoard because they want to ask their AI
-which skills are safe to use and approve changes without learning the control
-plane internals.
-
-When you ask your AI "what skills can you use here?" or "make this reviewed
-skill available for this workflow," the AI should read the current brief, show
-the relevant choice, ask only before applying one current action id when policy
+This flow assumes a user installed SkillBoard so their AI can keep installed
+skills broadly available while resolving confusing overlap only when it matters.
+
+When you ask your AI normal work requests such as "write tests before
+implementation", "review this plan and point out weak assumptions", or "help me
+refine this UX flow," the AI should work normally. SkillBoard becomes relevant
+when skill choice is ambiguous, several skills overlap, workflow priority
+matters, or you explicitly ask for a SkillBoard or skill decision such as "what
+skills can you use here?" or "make this reviewed skill available for this
+workflow." In those cases, the AI should read the current brief, show the
+relevant choice, ask only before applying one current action id when policy
 would change, and run the final guard automatically before invocation. For an
 already-allowed skill, the AI should state which skill it is about to use and
 which skill it used when reporting the result, not ask for another approval.
-That disclosure is an audit trace, not a permission prompt. You do not need to
-memorize the SkillBoard command loop. The command examples below are
-AI/automation/operator details for the agent, scripts, or people maintaining the
-setup.
+That disclosure is an audit trace, not a permission prompt. If you explicitly
+ask for a specific already-allowed skill, the AI should honor that request after
+guard use instead of rerouting away solely because another skill also matches.
+You do not need to memorize the SkillBoard command loop. The command examples
+below are AI/automation/operator details for the agent, scripts, or people
+maintaining the setup.
 
 If you ask OpenCode to use a skill you previously used in Codex, the target
 agent should call:
@@ -73,8 +79,9 @@ returned post-apply brief before making the next availability claim.
 `apply-action` re-resolves the current brief and refuses stale action ids instead
 of replaying cached action-card shell text.
 
-When the user asks which skill fits a task, the agent can keep the same brief
-flow and include the user request as intent:
+When a normal request leaves skill choice ambiguous, several skills overlap,
+workflow priority matters, or the user asks for a SkillBoard or skill decision,
+the agent can keep the same brief flow and include the user request as intent:
 
 ```bash
 skillboard brief --intent "write tests before implementation" --workflow daily-workflow --config skillboard.config.yaml --skills skills --json
@@ -83,20 +90,29 @@ skillboard brief --intent "write tests before implementation" --workflow daily-w
 The returned `assistant_guidance.route` maps the request to a declared workflow
 capability or a workflow-bound skill metadata match, returns the recommended
 skill and fallbacks, and includes `match_source`, `matched_terms`,
-`recommendation_reason`, `route_candidates`, `post_use_policy_suggestion`, and the
-`skillboard guard use ...` command that still needs to pass immediately before
-invocation. `route_candidates` is the per-skill decision trace: it shows which
-matching skill was selected, which candidates were denied, and the guard reason
-when a preferred skill was skipped for an allowed fallback.
+`recommendation_reason`, `route_candidates`, `overlap_resolution`,
+`policy_memory`,
+`post_use_policy_suggestion`, and the `skillboard guard use ...` command that
+still needs to pass immediately before invocation. `overlap_resolution`
+summarizes permissive routing when several allowed skills match.
+`route_candidates` is the per-skill decision trace: it shows which matching
+skill was selected, which candidates were denied, and the guard reason when a
+preferred skill was skipped for an allowed fallback.
+`policy_memory` appears when remembered or configured workflow policy selected
+the routed skill while other allowed skills were also available; the agent
+should mention that after completion so the user understands the prior choice
+shaped the route.
 `post_use_policy_suggestion` is the ask-after-use hook: if it is present, the
 agent should use the allowed routed skill first, then ask after completion
 whether to remember the suggested preference. Metadata matching can
 use declared skill id, path, category, and `SKILL.md` frontmatter
 name/description; it does not semantically rank raw skill bodies. If a
 recommended skill is already allowed, the agent should disclose it at the start
-and completion rather than ask for another approval. If no capability or
-workflow-bound skill matches, the agent should ask a clarifying question instead
-of guessing from raw `SKILL.md` text. Operators can still call
+and completion rather than ask for another approval. If the user explicitly
+requests a specific already-allowed skill, the agent should honor that request
+after guard use instead of rerouting away solely because another skill also
+matches. If no capability or workflow-bound skill matches, the agent should ask
+a clarifying question instead of guessing from raw `SKILL.md` text. Operators can still call
 `skillboard route ...` directly when they only need the recommendation payload.
 
 Run this again after installing agent packages, plugins, workflow bundles, or
@@ -279,26 +295,39 @@ This removes SkillBoard policy references only and leaves
 
 AI/automation/operator details:
 
+Remove managed user-agent guidance first if global install/setup made agents
+recognize SkillBoard and you want that agent-layer footprint gone:
+
+```bash
+skillboard uninstall --agent-layer --dry-run
+skillboard uninstall --agent-layer
+```
+
+This removes only managed `skillboard/SKILL.md` guidance files containing the
+SkillBoard agent integration marker. It preserves other agent skills and
+user-authored `skillboard` skills.
+
 ```bash
 skillboard uninstall --dry-run
 skillboard uninstall
 ```
 
 Uninstall removes generated bridge blocks and unchanged helper files. It
-preserves `skillboard.config.yaml`, `skills/`, reports, and user-authored
+also removes `skillboard.config.yaml` and the `.skillboard/` project state by
+default while preserving local `skills/` files and user-authored non-SkillBoard
 content in bridge files.
 
-For a fresh policy lifecycle during testing, use:
+If you want to keep project SkillBoard policy and bridge guidance, opt into
+settings preservation explicitly:
 
 ```bash
-skillboard uninstall --purge --dry-run
-skillboard uninstall --purge
-skillboard init
+skillboard uninstall --keep-settings --dry-run
+skillboard uninstall --keep-settings
 ```
 
-Use `--purge` when you want SkillBoard's allow/block/preference influence gone
-from the project while keeping local skill files. It discards the current
-SkillBoard config even if it contains imported skills or workflow edits,
-removes generated dashboard and impact reports, and removes the entire
-`.skillboard/` project state directory, including hooks, source caches, rollout
-logs, variant snapshots, and profiles. Local `skills/` files stay in place.
+`--purge` is still accepted as an explicit spelling for the default clean
+project removal. Default removal and `--purge` both discard the current
+SkillBoard config even if it contains imported skills or workflow edits, remove
+generated dashboard and impact reports, and remove the entire `.skillboard/`
+project state directory, including hooks, source caches, rollout logs, variant
+snapshots, and profiles. Local `skills/` files stay in place.

package/docs/value-proof.md

@@ -17,9 +17,9 @@ surfaces a user or agent would use.
 The raw list answers inventory questions: which skill declarations are connected
 to this workflow?
 
-SkillBoard answers operational safety questions: which skills can actually run
-now, why are others blocked, which skill fits the user's current request, and
-what approved action changes the next state?
+SkillBoard answers routing questions: which skills can actually run now, why
+are others blocked, which skill should steer the user's current request when
+several skills overlap, and what approved action changes the next state?
 
 In the tested fixture, the raw list can make the workflow look ready because it
 shows `matt.tdd active workflow-auto`. SkillBoard refuses that unsafe claim and
@@ -171,6 +171,9 @@ Observed route result:
 - Confidence: `high`.
 - Recommended skill: `matt.tdd`.
 - Fallback skill: `private.tdd-work-continuity`.
+- Overlap resolution is exposed in route payloads when several allowed skills
+  match, so agents can explain the deterministic route without hiding the other
+  available skills.
 - Guard command: `skillboard guard use matt.tdd ...`.
 - Guard result for `matt.tdd`: allowed.
 - Start disclosure: `I will use matt.tdd for this request.`

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.15",
-  "description": "Let AI agents pick and use allowed skills in each workflow.",
+  "version": "0.2.16",
+  "description": "Keep agent skills broadly available while routing overlaps consistently.",
   "keywords": [
     "ai-agent",
     "agent-skills",
     "skills",
     "skill-routing",
+    "overlap-routing",
     "workflow",
     "codex",
     "claude-code",

package/src/advisor/guidance.mjs

@@ -3,7 +3,16 @@ import { command } from "./action-core.mjs";
 const GUARD_WHEN = "before invoking a skill";
 const GOAL_DOCUMENT = Object.freeze({
   path: "docs/ai-skill-routing-goal.md",
-  purpose: "Preserve SkillBoard as a non-blocking AI skill routing control plane: route and work first when safe, explain briefly, ask after use when policy learning helps, and remember usage policy without rewriting skill bodies.",
+  purpose: "Preserve SkillBoard as a permissive AI skill routing layer: keep skills broadly available, resolve overlaps deterministically, explain briefly, ask after use when policy learning helps, and remember usage policy without rewriting skill bodies.",
+  loop: Object.freeze([
+    "observe",
+    "route",
+    "work",
+    "explain briefly",
+    "ask after",
+    "remember policy"
+  ]),
+  simplification_rule: "Concepts must justify themselves by supporting SkillBoard's routing identity, overlap resolution, policy memory, or non-blocking user flow; remove, merge, or rename only the concepts that fail that test.",
   when_to_read: Object.freeze([
     "before changing routing",
     "before changing brief output",
@@ -47,6 +56,7 @@ export function buildAssistantGuidance(brief, options = {}) {
 function goalDocument() {
   return {
     ...GOAL_DOCUMENT,
+    loop: [...GOAL_DOCUMENT.loop],
     when_to_read: [...GOAL_DOCUMENT.when_to_read]
   };
 }
@@ -125,12 +135,14 @@ function recommendedNextStep(status, brief, choices, route = null) {
       if (route !== null) {
         return route.recommended_skill === null
           ? "Ask a clarifying question; no workflow capability matched this request."
-          : `Use ${route.recommended_skill} for this request after the guard check passes.`;
+          : `Use ${route.recommended_skill} for this request after the guard check passes${postUsePolicyStep(route)}.`;
       }
       return "Run the guard check before invoking any selected skill.";
     case "needs-decision":
       if (route?.recommended_skill !== null && route?.guard_allowed === true) {
-        return `Use ${route.recommended_skill} for this request after the guard check passes; handle pending review decisions after the task unless a policy-changing action is needed now.`;
+        return route.post_use_policy_suggestion === null
+          ? `Use ${route.recommended_skill} for this request after the guard check passes; handle pending review decisions after the task unless a policy-changing action is needed now.`
+          : `Use ${route.recommended_skill} for this request after the guard check passes; after completion, ask whether to remember the suggested policy and handle pending review decisions unless a policy-changing action is needed now.`;
       }
       return firstChoice === undefined
         ? "Ask the user which pending review decision to make."
@@ -159,6 +171,12 @@ function recommendedNextStep(status, brief, choices, route = null) {
   }
 }
 
+function postUsePolicyStep(route) {
+  return route.post_use_policy_suggestion === null
+    ? ""
+    : "; after completion, ask whether to remember the suggested policy";
+}
+
 function routeGuidance(route) {
   return {
     intent: route.intent,
@@ -180,6 +198,8 @@ function routeGuidance(route) {
       guard_roles: candidate.guard_roles,
       capability_roles: candidate.capability_roles
     })),
+    overlap_resolution: route.overlap_resolution ?? null,
+    policy_memory: route.policy_memory ?? null,
     usage_disclosure: route.usage_disclosure ?? null,
     post_use_policy_suggestion: route.post_use_policy_suggestion ?? null,
     guard_command: route.guard_command,

package/src/agent-integration-cli.mjs

@@ -0,0 +1,184 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { installAgentIntegration, uninstallAgentIntegration } from "./agent-integration-files.mjs";
+import { resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
+import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
+
+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 env = runtime.env ?? process.env;
+  const home = await resolveSetupHome(env, runtime);
+  const targets = await agentSetupTargets(options, runtime, home);
+  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, setupOwnership(env, runtime, home));
+  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("- No project was initialized; run skillboard init only inside a workspace that needs local SkillBoard policy.\n");
+  stdout.write('- Ask the agent in a workspace: "Review this plan and point out weak assumptions."\n');
+  stdout.write("- SkillBoard will step in when skills overlap, routing is ambiguous, or you ask for a skill decision.\n");
+  return 0;
+}
+
+export async function runAgentLayerUninstallCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("dir") !== undefined) {
+    throw new Error("skillboard uninstall --agent-layer is agent-layer cleanup and does not accept --dir");
+  }
+  for (const option of ["remove-config", "reset-config", "purge", "keep-settings", "remove-reports", "remove-hooks"]) {
+    if (options.get(option) === "true") {
+      throw new Error(`--${option} cannot be combined with --agent-layer`);
+    }
+  }
+  const env = runtime.env ?? process.env;
+  const home = await resolveSetupHome(env, runtime);
+  const targets = await agentSetupTargets(options, runtime, home);
+  if (targets.length === 0) {
+    stdout.write("No supported agent user skill roots were detected.\n");
+    return 0;
+  }
+  const dryRun = options.get("dry-run") === "true";
+  const result = await uninstallAgentIntegration(targets, dryRun);
+  stdout.write(`${dryRun ? "Dry run: " : ""}Uninstalled SkillBoard agent integration.\n`);
+  writeList(stdout, "Removed", result.removed);
+  writeList(stdout, "Updated", result.updated);
+  writeList(stdout, "Preserved", result.preserved);
+  writeList(stdout, "Absent", result.absent);
+  return 0;
+}
+
+function writeList(stdout, label, values) {
+  if (values.length > 0) {
+    stdout.write(`${label}: ${formatList(values)}\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("It does not create skillboard.config.yaml or .skillboard/; run skillboard init later only for a project that needs local policy.\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(", ");
+}
+
+function readCsv(value) {
+  if (value === undefined || value.trim() === "") {
+    return [];
+  }
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
+function defaultRuntime() {
+  return {
+    cwd: process.cwd(),
+    entrypointPath: process.argv[1],
+    packageSpec: process.env.npm_config_package
+  };
+}
+
+async function agentSetupTargets(options, runtime, setupHome) {
+  const env = runtime.env ?? process.env;
+  const home = setupHome ?? await resolveSetupHome(env, runtime);
+  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;
+}
+
+function commandPrefix(runtime) {
+  const entrypoint = runtime.entrypointPath ?? "";
+  const normalized = entrypoint.replace(/\\/g, "/");
+  if (normalized.includes("/_npx/")) {
+    const packageSpec = runtime.packageSpec ?? "agent-skillboard";
+    return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
+  }
+  if (isSourceTreeEntrypoint(entrypoint)) {
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;
+  }
+  return "skillboard";
+}
+
+function isSourceTreeEntrypoint(entrypoint) {
+  if (entrypoint === "") {
+    return false;
+  }
+  const normalized = entrypoint.replace(/\\/g, "/");
+  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
+    && !normalized.includes("/node_modules/")
+    && !normalized.includes("/_npx/")
+    && !normalized.includes("/.npm/");
+}
+
+function sourceTreeEntrypoint(entrypoint, cwd) {
+  const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
+  const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
+  if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
+    return shellQuote(relativeEntrypoint);
+  }
+  return shellQuote(absoluteEntrypoint);
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/agent-integration-content.mjs

@@ -0,0 +1,48 @@
+export const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
+export const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
+
+export function agentIntegrationSkill() {
+  return `---
+name: skillboard
+description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, workflow priority matters, or the user explicitly asks which skill should be used, imported, preferred, avoided, reviewed, or prioritized.
+---
+${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.
+- \`skillboard init\` is a separate project command. Use it only when the user wants project-local policy files such as \`skillboard.config.yaml\`, \`.skillboard/\`, \`AGENTS.md\`, or \`CLAUDE.md\`.
+
+## Default Behavior
+
+- Installed user skills are usable by default unless the runtime, user, or local instructions disable them.
+- For ordinary user requests, work normally; invoke SkillBoard only when skill choice is ambiguous, skills overlap, workflow priority matters, or the user asks for a SkillBoard or skill decision.
+- If the user explicitly asks for a specific installed skill, honor that request when the guard allows it instead of rerouting away solely because other skills also match.
+- Do not ask for permission merely because you selected a skill.
+- When you use a skill, disclose it briefly at the start and completion. If SkillBoard says remembered or configured policy selected this skill while other allowed skills were available, mention that at completion.
+
+## 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. Start from the user's task, not from a pre-task inventory prompt.
+2. Identify candidate skills only when multiple installed skills plausibly match, a manual skill-control request is present, or workflow priority could change the route.
+3. Prefer the skill whose explicit request, description, workflow guidance, and local instructions most directly match the user's task.
+4. 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.
+5. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
+6. Continue with the selected skill; do not stop only because other candidate skills exist.
+
+${AGENT_INTEGRATION_END}
+`;
+}