agent-skillboard 0.1.2 → 0.2.2

package/src/control.mjs

@@ -14,11 +14,18 @@ import {
 import {
   activateSkill,
   addSkill,
+  addSkillVariant,
   blockSkill,
   preferSkill,
   quarantineSkill,
   removeSkill
 } from "./control/skill-crud.mjs";
+import {
+  approveSkillVariant,
+  forkSkillVariant
+} from "./control/skill-variants.mjs";
+import { resetSkillVariant } from "./control/variant-reset.mjs";
+import { variantLifecycleStatus } from "./control/variant-status.mjs";
 import { addHarness, addWorkflow } from "./control/workflow-crud.mjs";
 import {
   GUARD_HOOK_MODE,
@@ -116,15 +123,20 @@ export {
   activateSkill,
   addHarness,
   addSkill,
+  addSkillVariant,
   addWorkflow,
+  approveSkillVariant,
   auditSources,
   blockSkill,
   canUseSkill,
   classifySkillSource,
   classifySkillTrust,
+  forkSkillVariant,
   preferSkill,
   quarantineSkill,
-  removeSkill
+  removeSkill,
+  resetSkillVariant,
+  variantLifecycleStatus
 };
 
 export async function installGuardHook(options) {

package/src/domain/rules/skills.mjs

@@ -4,6 +4,10 @@ import {
   validateSkillState
 } from "../skill-state-matrix.mjs";
 
+const VARIANT_STATUS_VALUES = new Set(["draft", "approved"]);
+const VARIANT_DIGEST_PATTERN = /^sha256:[0-9a-fA-F]{64}$/;
+const VARIANT_SNAPSHOT_PREFIX = ".skillboard/variant-snapshots/";
+
 export const skillRules = [
   {
     id: "SKILL-STATUS-001",
@@ -71,6 +75,19 @@ export const skillRules = [
       return diagnostics;
     }
   },
+  {
+    id: "SKILL-VARIANT-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const skill of ctx.skills) {
+        if (skill.variant === null || skill.variant === undefined) {
+          continue;
+        }
+        diagnostics.push(...validateVariantMetadata(ctx, skill));
+      }
+      return diagnostics;
+    }
+  },
   {
     id: "SKILL-OWNER-001",
     check(ctx) {
@@ -103,3 +120,46 @@ function validateStatusInvocation(skill) {
   }
   return diagnostics;
 }
+
+function validateVariantMetadata(ctx, skill) {
+  const diagnostics = [];
+  const { variant } = skill;
+  if (!ctx.skillsById.has(variant.of)) {
+    diagnostics.push(`Skill ${skill.id} variant.of references undeclared skill: ${variant.of}`);
+  }
+  if (!ctx.capabilitiesByName.has(variant.capability)) {
+    diagnostics.push(`Skill ${skill.id} variant.capability references undeclared capability: ${variant.capability}`);
+  }
+  if (!ctx.workflowsByName.has(variant.workflow)) {
+    diagnostics.push(`Skill ${skill.id} variant.workflow references undeclared workflow: ${variant.workflow}`);
+  }
+  if (!VARIANT_STATUS_VALUES.has(variant.status)) {
+    diagnostics.push(`Skill ${skill.id} variant.status must be one of: draft, approved; got ${variant.status}.`);
+  }
+  diagnostics.push(...validateVariantCheckpoint(skill, "base", variant.base));
+  if (variant.approved !== undefined) {
+    diagnostics.push(...validateVariantCheckpoint(skill, "approved", variant.approved));
+  }
+  return diagnostics;
+}
+
+function validateVariantCheckpoint(skill, key, checkpoint) {
+  const diagnostics = [];
+  if (!VARIANT_DIGEST_PATTERN.test(checkpoint.contentDigest)) {
+    diagnostics.push(`Skill ${skill.id} variant.${key}.content_digest must match sha256:<64 hex chars>.`);
+  }
+  if (!isVariantSnapshotPath(checkpoint.snapshot)) {
+    diagnostics.push(`Skill ${skill.id} variant.${key}.snapshot must be a relative path under ${VARIANT_SNAPSHOT_PREFIX}.`);
+  }
+  return diagnostics;
+}
+
+function isVariantSnapshotPath(value) {
+  if (value.startsWith("/") || /^[A-Za-z]:/.test(value) || value.includes("\\")) {
+    return false;
+  }
+  if (!value.startsWith(VARIANT_SNAPSHOT_PREFIX) || value.length <= VARIANT_SNAPSHOT_PREFIX.length) {
+    return false;
+  }
+  return value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}

package/src/domain/rules/workflows.mjs

@@ -3,6 +3,7 @@ import {
   NON_CALLABLE_WORKFLOW_INVOCATIONS,
   NON_CALLABLE_WORKFLOW_STATUSES
 } from "../constants.mjs";
+import { workflowConflictEntries } from "../../conflicts.mjs";
 
 export const workflowRules = [
   {
@@ -90,6 +91,18 @@ export const workflowRules = [
       }
       return diagnostics;
     }
+  },
+  {
+    id: "WF-CONFLICT-001",
+    check(ctx) {
+      const diagnostics = [];
+      for (const workflow of ctx.workflows) {
+        for (const conflict of workflowConflictEntries(ctx.workspace, workflow)) {
+          diagnostics.push(`Workflow ${workflow.name} has active skill conflict: ${conflict.skill} conflicts_with ${conflict.conflictingSkill}.`);
+        }
+      }
+      return diagnostics;
+    }
   }
 ];
 

package/src/hook-plan.mjs

@@ -58,10 +58,10 @@ function renderGuardHookScript(options) {
   return `#!/usr/bin/env sh
 set -eu
 
-SKILLBOARD_BIN=\${SKILLBOARD_BIN:-${shellQuote(options.command)}}
-SKILLBOARD_CONFIG=\${SKILLBOARD_CONFIG:-${shellQuote(options.configPath)}}
-SKILLBOARD_SKILLS=\${SKILLBOARD_SKILLS:-${shellQuote(options.skillsRoot)}}
-SKILLBOARD_WORKFLOW=\${SKILLBOARD_WORKFLOW:-${shellQuote(options.workflow)}}
+SKILLBOARD_BIN=${shellQuote(options.command)}
+SKILLBOARD_CONFIG=${shellQuote(options.configPath)}
+SKILLBOARD_SKILLS=${shellQuote(options.skillsRoot)}
+SKILLBOARD_WORKFLOW=${shellQuote(options.workflow)}
 
 if [ "\${SKILLBOARD_SKILL_ID:-}" != "" ]; then
   skill_id="$SKILLBOARD_SKILL_ID"
@@ -72,8 +72,8 @@ else
   exit 64
 fi
 
-# Split SKILLBOARD_BIN so local hook configs can use commands like:
-#   SKILLBOARD_BIN="node bin/skillboard.mjs"
+# Split the install-time command so hooks can use commands like:
+#   --skillboard-bin "node bin/skillboard.mjs"
 # Paths containing spaces should be provided through an environment wrapper.
 set -- $SKILLBOARD_BIN
 exec "$@" guard use "$skill_id" --workflow "$SKILLBOARD_WORKFLOW" --config "$SKILLBOARD_CONFIG" --skills "$SKILLBOARD_SKILLS"

package/src/impact.mjs

@@ -1,21 +1,30 @@
-export function impactDisable(workspace, skillId) {
+import {
+  activeConflictEntriesForSkill,
+  conflictingSkillIds
+} from "./conflicts.mjs";
+
+export function impactDisable(workspace, skillId) {
   const affectedWorkflowEntries = workspace.workflows
     .filter((workflow) => workflow.activeSkills.includes(skillId) || workflow.requiredCapabilities.some((capability) => {
       return capability.preferred === skillId || capability.fallback.includes(skillId);
     }));
   const affectedWorkflows = affectedWorkflowEntries.map((workflow) => workflow.name);
   const affectedOutputs = [...new Set(affectedWorkflowEntries.flatMap((workflow) => workflow.requiredOutputs))];
-  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
-  const alternatives = alternativesForSkill(workspace, skillId, skill);
-  return {
-    skillId,
-    exists: skill !== undefined,
-    affectedWorkflows,
-    affectedOutputs,
-    alternatives,
-    risk: riskFor(skill, affectedWorkflows, alternatives)
-  };
-}
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  const alternatives = alternativesForSkill(workspace, skillId, skill);
+  const conflictingSkills = conflictingSkillIds(workspace, skillId);
+  const activeConflicts = activeConflictEntriesForSkill(workspace, skillId);
+  return {
+    skillId,
+    exists: skill !== undefined,
+    affectedWorkflows,
+    affectedOutputs,
+    alternatives,
+    conflictingSkills,
+    activeConflicts,
+    risk: riskFor(skill, affectedWorkflows, alternatives)
+  };
+}
 
 function alternativesForSkill(workspace, skillId, skill) {
   if (skill?.replacedBy !== undefined) {

package/src/index.mjs

@@ -15,15 +15,19 @@ import { detectInstallOutput } from "./install-output-detector.mjs";
 import { rolloutApply, rolloutAudit, rolloutPlan, rolloutReport, rolloutRollback } from "./rollout.mjs";
 import { reviewInstallUnit } from "./review.mjs";
 import { buildSkillBrief } from "./advisor.mjs";
+import { routeSkill } from "./route.mjs";
 import {
   activateSkill,
   addHarness,
   addSkill,
+  addSkillVariant,
   addWorkflow,
+  approveSkillVariant,
   auditSources,
   blockSkill,
   canUseSkill,
   explainSkill,
+  forkSkillVariant,
   installGuardHook,
   listHarnesses,
   listInstallUnits,
@@ -31,14 +35,18 @@ import {
   listWorkflows,
   preferSkill,
   quarantineSkill,
-  removeSkill
+  removeSkill,
+  resetSkillVariant,
+  variantLifecycleStatus
 } from "./control.mjs";
 
 export {
   activateSkill,
   addHarness,
   addSkill,
+  addSkillVariant,
   addWorkflow,
+  approveSkillVariant,
   agentInventoryDetectors,
   auditSources,
   blockSkill,
@@ -49,6 +57,7 @@ export {
   detectInstallOutput,
   doctorProject,
   explainSkill,
+  forkSkillVariant,
   impactDisable,
   importSource,
   initProject,
@@ -64,6 +73,7 @@ export {
   preferSkill,
   quarantineSkill,
   removeSkill,
+  resetSkillVariant,
   reconcileWorkspace,
   refreshAgentInventory,
   refreshSourcePins,
@@ -74,9 +84,11 @@ export {
   rolloutPlan,
   rolloutReport,
   rolloutRollback,
+  routeSkill,
   renderImportFragment,
   renderReconcilePlan,
   uninstallProject,
   verifySources,
+  variantLifecycleStatus,
   writeLockfile
 };

package/src/lifecycle-cli.mjs

@@ -30,7 +30,8 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
   writeSafetyDefault(stdout, result.safety);
   writeNextCommands(stdout, {
     command: commandPrefix(runtime),
-    dir: options.get("dir")
+    dir: options.get("dir"),
+    workflows: result.scan.addedWorkflows ?? []
   });
   return 0;
 }
@@ -85,7 +86,7 @@ function writeSafetyDefault(stdout, safety) {
     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 are quarantined until reviewed.\n");
+  stdout.write("- Runtime/plugin/system skills require source review before manual activation.\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`);
@@ -94,10 +95,22 @@ function writeSafetyDefault(stdout, safety) {
 
 function writeNextCommands(stdout, next) {
   const dir = next.dir === undefined ? "" : ` --dir ${shellQuote(next.dir)}`;
+  const workflows = sorted(next.workflows ?? []);
   stdout.write("Next:\n");
+  stdout.write('- Ask your AI: "What skills can you use in this project?"\n');
   stdout.write(`- ${next.command} doctor${dir} --summary\n`);
-  stdout.write(`- ${next.command} brief${dir}\n`);
-  stdout.write(`- ${next.command} brief${dir} --verbose\n`);
+  if (workflows.length === 0) {
+    stdout.write(`- ${next.command} brief${dir}\n`);
+    stdout.write(`- ${next.command} brief${dir} --verbose\n`);
+    return;
+  }
+  const workflow = workflows[0];
+  stdout.write(`Choose a workflow: ${formatList(workflows)}\n`);
+  stdout.write(`Example workflow brief: ${formatList([workflow])}\n`);
+  stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)}${dir}\n`);
+  stdout.write('Example task routing: "write tests before implementation"\n');
+  stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)} --intent ${shellQuote("write tests before implementation")}${dir}\n`);
+  stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)}${dir} --verbose\n`);
 }
 
 function formatList(values) {
@@ -127,10 +140,8 @@ function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
   const normalized = entrypoint.replaceAll("\\", "/");
   if (normalized.includes("/_npx/")) {
-    if (runtime.packageSpec !== undefined && runtime.packageSpec !== "agent-skillboard") {
-      return `npm exec --yes --package ${shellQuote(runtime.packageSpec)} -- skillboard`;
-    }
-    return "npx agent-skillboard";
+    const packageSpec = runtime.packageSpec ?? "agent-skillboard";
+    return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
   }
   if (isSourceTreeEntrypoint(entrypoint)) {
     return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;

package/src/lifecycle-content.mjs

@@ -20,31 +20,38 @@ export function bridgeBlock() {
   return `${BRIDGE_START}
 # SkillBoard Control Plane
 
-This project uses SkillBoard as the source of truth for agent skill activation.
+Your responsibility is to answer skill availability questions from SkillBoard, translate user intent into current action ids, ask for one confirmation only before policy-changing actions, apply one current action, reread the post-apply brief, and run the guard automatically before invocation.
 
-- Read \`skillboard.config.yaml\` before assuming an installed skill is active.
-- Installed \`SKILL.md\` files are not automatically callable.
-- When a user asks what skills are available, run \`skillboard brief --json --config skillboard.config.yaml --skills skills\` before answering. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` only when the user wants machine-readable change suggestions.
+## Product Goal
+
+- SkillBoard is a non-blocking AI skill routing control plane, not a pre-task settings checklist.
+- Read \`docs/ai-skill-routing-goal.md\` before changing routing, brief, bridge, policy, or workflow UX.
+- Preserve the loop: observe → route → work → explain briefly → ask after → remember policy.
+- SkillBoard does not rewrite \`SKILL.md\` bodies to personalize behavior; record usage policy for when to use, prefer, reference, avoid, or block skills.
+
+## Availability
+
+- Use SkillBoard as the source of truth; installed \`SKILL.md\` files are not automatically callable.
+- 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.
 - Treat "Needs your decision" as a one-time decision queue, not a persistent blocked state. "Blocked for safety" means the skill/source/workflow is hard-blocked until policy or provenance changes.
 - Use \`skillboard can-use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills --json\` for machine-readable agent decisions.
-- Approval loop for action cards: read the current \`skillboard brief --json\`, pick one current action id, ask the user for confirmation, then run \`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json\` and include \`--workflow <name>\` when a workflow is selected.
-- After \`skillboard apply-action <action-id> ... --yes --json\`, read the returned post-apply brief before answering the next availability question or applying another action. \`apply-action\` re-resolves current actions; do not apply cached or stale action ids, do not apply multiple actions, and do not run raw action-card shell text as the primary apply path.
-- Immediately before actual invocation, run \`skillboard guard use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\`.
-- Run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources.
-- Run \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\` after reviewing an external source and before enabling automatic invocation from it.
-- Manual underlying hook detail: preview guard hook installation with \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card approval loop.
-- Prefer workflow-scoped skills over global skill invocation.
-- Only \`global-meta\` skills may be treated as globally available.
-- Run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\` to inspect control-plane health; add \`--strict\` when review-needed safe mode should fail automation.
-- Run \`skillboard check --config skillboard.config.yaml --skills skills\` when policy state matters.
-- Run \`skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md\` to refresh the visible control map.
-- Run \`skillboard add skill <skill-id> --path <relative-skill-path> --config skillboard.config.yaml --skills skills\` to register a user-owned skill without treating the file as automatically active.
-- Run \`skillboard add harness <harness-name> --config skillboard.config.yaml --skills skills\` and \`skillboard add workflow <workflow-name> --harness <harness-name> --config skillboard.config.yaml --skills skills --skill <skill-id>\` to add local growth paths without editing YAML by hand.
-- Use \`skillboard activate <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` and \`skillboard block <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` for workflow-scoped enablement.
-- Use \`skillboard remove skill <skill-id> --config skillboard.config.yaml --skills skills --force\` only after reviewing \`skillboard impact disable <skill-id> --config skillboard.config.yaml --skills skills\`; removal updates policy references while leaving \`SKILL.md\` files on disk.
-- Run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing a new local agent skill pack, plugin, workflow bundle, or harness.
-- Run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
+
+## Intent to Action
+
+- Translate user intent into current action ids from the current brief, not saved output.
+- For action cards, read \`skillboard brief --json --config skillboard.config.yaml --skills skills --include-actions\`, pick one current action id, ask the user for one confirmation, then run \`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json\`. Include \`--workflow <name>\` when a workflow is selected.
+- After \`skillboard apply-action <action-id> ... --yes --json\`, reread the returned post-apply brief before answering the next availability question or applying another action. \`apply-action\` re-resolves current actions; do not apply cached or stale action ids, do not apply multiple actions, and do not run raw action-card shell text as the primary apply path.
+- For an already-allowed skill, do not ask for another approval. Run \`skillboard guard use <skill-id> --workflow <name> --config skillboard.config.yaml --skills skills\` automatically. Say at the start: "I will use <skill-id> for this request." Say at completion: "I used <skill-id> for this request." Treat this disclosure as an audit trace, not a permission prompt. Ask the user only if the guard denies use or a policy-changing action is needed.
+
+## Operations
+
+- Source trust: run \`skillboard audit sources --config skillboard.config.yaml --skills skills\` before trusting newly imported external skill sources; after review, use \`skillboard review install-unit <unit-id> --trust-level reviewed --config skillboard.config.yaml --skills skills\`. Unreviewed runtime sources are a one-time review decision, not a default block recommendation; after review, activate only the needed quarantined skills as manual-only workflow skills and use ask-after policy suggestions for future preferences.
+- Health: run \`skillboard doctor --config skillboard.config.yaml --skills skills\` or \`skillboard status --config skillboard.config.yaml --skills skills --json\`; add \`--strict\` when review-needed safe mode should fail automation.
+- Hook action cards: prefer \`skillboard apply-action <action-id> --yes --json\`. The underlying manual preview is \`skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh --dry-run --json\`; inspect \`planned.preview.shell\` before materializing an executable guard hook outside the action-card control loop. Generated hooks pin the install-time SkillBoard command, config, skills root, and workflow; set those values with hook install options such as \`--skillboard-bin\`, not runtime environment overrides.
+- Inventory/import growth: run \`skillboard inventory refresh --dry-run --config skillboard.config.yaml\` after installing local skill packs, plugins, workflow bundles, or harnesses; run \`skillboard import --profile <id-or-path> --source-root <repo> --out .skillboard/reports/import-fragment.yaml\` after installing a new skill repository, then review the fragment before merging it into \`skillboard.config.yaml\`.
+- Prefer workflow-scoped skills over global skill invocation. Only \`global-meta\` skills may be treated as globally available.
 
 ${BRIDGE_END}`;
 }
@@ -77,11 +84,14 @@ skillboard hook install --workflow <name> --config skillboard.config.yaml --skil
 skillboard hook install --workflow <name> --config skillboard.config.yaml --skills skills --out .skillboard/hooks/<name>-guard.sh
 \`\`\`
 
-For hook action cards, prefer the bridge approval loop with
+For hook action cards, prefer the bridge control loop with
 \`skillboard apply-action <action-id> --yes --json\`. These raw hook commands
 are the underlying manual detail: preview the JSON plan first and inspect
 \`planned.preview.shell\` before materializing an executable guard hook.
-The generated script delegates to \`skillboard guard use\` and can be wired into
-the hook mechanism of the active harness.
+Generated hooks pin the install-time SkillBoard command, config, skills root,
+and workflow; set those values with hook install options such as
+\`--skillboard-bin\`, not runtime environment overrides. The generated script
+delegates to \`skillboard guard use\` and can be wired into the hook mechanism of
+the active harness.
 `;
 }