agent-skillboard 0.1.0

package/profiles/voltagent-awesome-agent-skills.yaml

@@ -0,0 +1,18 @@
+id: github.voltagent.awesome-agent-skills
+source: VoltAgent/awesome-agent-skills
+kind: marketplace
+namespace: voltagent
+target_path_prefix: voltagent
+scope: cache
+default_status: vendor
+default_invocation: manual-only
+default_exposure: exported
+default_category: uncategorized
+provided_components:
+  - marketplace
+  - skills
+skill_paths:
+  - "skills/**/SKILL.md"
+  - "*/SKILL.md"
+permission_risk: low
+rollback: remove cache

package/profiles/wshobson-agents.yaml

@@ -0,0 +1,19 @@
+id: github.wshobson.agents
+source: wshobson/agents
+kind: marketplace
+namespace: wshobson
+target_path_prefix: wshobson
+scope: project
+default_status: candidate
+default_invocation: router-only
+default_exposure: exported
+default_category: uncategorized
+provided_components:
+  - skills
+  - agents
+  - commands
+skill_paths:
+  - "skills/**/SKILL.md"
+  - "*/SKILL.md"
+permission_risk: medium
+rollback: plugin uninstall

package/src/advisor/action-core.mjs

@@ -0,0 +1,74 @@
+const RISK_RANK = { info: 0, low: 1, medium: 2, high: 3, destructive: 4 };
+const INSTALL_UNIT_REVIEW_ACTIONS = new Set([
+  "block-install-unit",
+  "review-install-unit",
+  "trust-install-unit"
+]);
+
+export function makeAction(data) {
+  return {
+    id: `${data.kind}:${data.targetId}`,
+    kind: data.kind,
+    label: data.label,
+    reason: data.reason,
+    risk: data.risk,
+    requires_user_confirmation: data.requiresUserConfirmation ?? requiresConfirmation(data.risk),
+    dry_run: data.dryRun,
+    apply: data.apply,
+    application: data.application ?? emptyApplication(data.blockedReason),
+    applies_to: data.appliesTo,
+    blocked_reason: data.blockedReason,
+    advanced: data.advanced
+  };
+}
+
+export function command(argv) {
+  return { argv, display: argv.map(shellQuote).join(" ") };
+}
+
+export function applyOrNull(workflow, dryRun, argv) {
+  return workflowResolved(workflow) && dryRun !== null ? command(argv) : null;
+}
+
+export function blockedByWorkflow(workflow) {
+  return workflowResolved(workflow) ? null : workflow.blocked_reason ?? "Select a workflow before applying action cards.";
+}
+
+export function workflowResolved(workflow) {
+  return workflow.selected !== null && !workflow.needs_selection && !workflow.unknown;
+}
+
+export function sortActions(left, right) {
+  return left.kind.localeCompare(right.kind)
+    || left.applies_to.id.localeCompare(right.applies_to.id)
+    || RISK_RANK[left.risk] - RISK_RANK[right.risk]
+    || left.id.localeCompare(right.id);
+}
+
+export function linkReviewQueue(reviewQueue, actions) {
+  const byUnit = new Map(actions
+    .filter((entry) => INSTALL_UNIT_REVIEW_ACTIONS.has(entry.kind))
+    .map((entry) => [entry.applies_to.id, entry.id]));
+  return reviewQueue.map((entry) => {
+    const unitId = entry.advanced.install_unit ?? entry.advanced.source_id;
+    return unitId === undefined || !byUnit.has(unitId)
+      ? entry
+      : { ...entry, action_ids: [byUnit.get(unitId)] };
+  });
+}
+
+function requiresConfirmation(risk) {
+  return RISK_RANK[risk] >= RISK_RANK.medium;
+}
+
+function emptyApplication(blockedReason) {
+  return {
+    preview: null,
+    apply: null,
+    blocked_reason: blockedReason ?? "Action cannot be applied directly."
+  };
+}
+
+function shellQuote(value) {
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}

package/src/advisor/actions.mjs

@@ -0,0 +1,256 @@
+import {
+  applyOrNull,
+  blockedByWorkflow,
+  command,
+  linkReviewQueue,
+  makeAction,
+  sortActions,
+  workflowResolved
+} from "./action-core.mjs";
+import { withApplicationCommands } from "./application-commands.mjs";
+import { buildSetupGuidanceActions } from "./setup-actions.mjs";
+import { trustRecommendationAction } from "./trust-policy.mjs";
+
+const WRITABLE_MODES = new Set(["manual-only", "router-only", "workflow-auto"]);
+
+export function buildInitActions(paths) {
+  return [makeAction({
+    kind: "init-project",
+    targetId: paths.root,
+    label: "Initialize SkillBoard in this project",
+    reason: "SkillBoard is not initialized for this project.",
+    risk: "low",
+    requiresUserConfirmation: true,
+    dryRun: null,
+    apply: null,
+    appliesTo: { kind: "project", id: paths.root },
+    blockedReason: "skillboard init does not have a dry-run preview command.",
+    advanced: { root: paths.root }
+  })];
+}
+
+export function buildActionCards(context) {
+  const actions = withApplicationCommands([
+    ...buildSetupGuidanceActions(context),
+    ...reviewInstallUnitActions(context),
+    ...activateSkillActions(context),
+    ...blockSkillActions(context),
+    ...hookInstallActions(context),
+    ...removeSkillForceActions(context),
+    resetCleanupAction(context)
+  ].filter(Boolean).sort(sortActions), context);
+  return {
+    actions,
+    reviewQueue: linkReviewQueue(context.reviewQueue, actions)
+  };
+}
+
+function reviewInstallUnitActions({ paths, workflow, reviewQueue }) {
+  const units = new Map();
+  for (const entry of reviewQueue) {
+    const unitId = entry.advanced.install_unit ?? entry.advanced.source_id;
+    if (unitId !== undefined && entry.kind === "install_unit") {
+      units.set(unitId, {
+        risk: entry.risk,
+        recommended: entry.advanced.recommended_trust_level ?? "reviewed"
+      });
+    }
+  }
+  return [...units.entries()].map(([unitId, { risk, recommended }]) => {
+    const action = trustRecommendationAction(recommended);
+    const dryRun = command([
+      "skillboard", "review", "install-unit", unitId, "--trust-level", recommended,
+      "--config", paths.configPath, "--skills", paths.skillsRoot, "--dry-run", "--json"
+    ]);
+    return makeAction({
+      kind: action.kind,
+      targetId: unitId,
+      label: `${action.label} ${unitId}`,
+      reason: action.reason,
+      risk,
+      requiresUserConfirmation: true,
+      dryRun,
+      apply: applyOrNull(workflow, dryRun, [
+        "skillboard", "review", "install-unit", unitId, "--trust-level", recommended,
+        "--config", paths.configPath, "--skills", paths.skillsRoot, "--json"
+      ]),
+      appliesTo: { kind: "install_unit", id: unitId },
+      blockedReason: blockedByWorkflow(workflow),
+      advanced: { trust_level: recommended }
+    });
+  });
+}
+
+function activateSkillActions({ paths, workflow, skills, workspace }) {
+  const candidates = [...skills.not_in_workflow, ...skills.blocked.filter((skill) => missingProvenance(workspace, skill.id))];
+  return candidates.flatMap((skill) => {
+    if (missingProvenance(workspace, skill.id)) {
+      return [blockedActivateAction(paths, workflow, skill)];
+    }
+    if (!canActivate(skill)) {
+      return [];
+    }
+    const mode = skill.advanced.invocation;
+    const risk = riskFromSkill(skill);
+    const dryRun = command([
+      "skillboard", "activate", skill.id, "--workflow", workflow.selected, "--mode", mode,
+      "--config", paths.configPath, "--skills", paths.skillsRoot, "--dry-run", "--json"
+    ]);
+    return [makeAction({
+      kind: "activate-skill",
+      targetId: skill.id,
+      label: `Activate ${skill.id} in this workflow`,
+      reason: "Add this reviewed skill to the selected workflow.",
+      risk,
+      dryRun,
+      apply: applyOrNull(workflow, dryRun, [
+        "skillboard", "activate", skill.id, "--workflow", workflow.selected, "--mode", mode,
+        "--config", paths.configPath, "--skills", paths.skillsRoot, "--json"
+      ]),
+      appliesTo: { kind: "skill", id: skill.id, workflow: workflow.selected },
+      blockedReason: blockedByWorkflow(workflow),
+      advanced: skillAdvanced(skill, { mode })
+    })];
+  });
+}
+
+function blockSkillActions({ paths, workflow, skills }) {
+  if (!workflowResolved(workflow)) {
+    return [];
+  }
+  return [...skills.automatic_allowed, ...skills.manual_allowed].map((skill) => {
+    const dryRun = command([
+      "skillboard", "block", skill.id, "--workflow", workflow.selected,
+      "--config", paths.configPath, "--skills", paths.skillsRoot, "--dry-run", "--json"
+    ]);
+    return makeAction({
+      kind: "block-skill",
+      targetId: skill.id,
+      label: `Disable ${skill.id} in this workflow`,
+      reason: "Workflow-scoped disable; this does not delete the skill.",
+      risk: "medium",
+      dryRun,
+      apply: command([
+        "skillboard", "block", skill.id, "--workflow", workflow.selected,
+        "--config", paths.configPath, "--skills", paths.skillsRoot, "--json"
+      ]),
+      appliesTo: { kind: "skill", id: skill.id, workflow: workflow.selected },
+      blockedReason: null,
+      advanced: skillAdvanced(skill)
+    });
+  });
+}
+
+function hookInstallActions({ paths, workflow }) {
+  if (workflow.selected === null || workflow.unknown) {
+    return [];
+  }
+  const dryRun = command([
+    "skillboard", "hook", "install", "--workflow", workflow.selected,
+    "--config", paths.configPath, "--skills", paths.skillsRoot, "--dry-run", "--json"
+  ]);
+  return [makeAction({
+    kind: "hook-install",
+    targetId: `guard:${workflow.selected}`,
+    label: `Preview guard hook install for ${workflow.selected}`,
+    reason: "Preview the workflow guard hook install; no files will be changed until you apply it.",
+    risk: "high",
+    dryRun,
+    apply: applyOrNull(workflow, dryRun, [
+      "skillboard", "hook", "install", "--workflow", workflow.selected,
+      "--config", paths.configPath, "--skills", paths.skillsRoot, "--json"
+    ]),
+    appliesTo: { kind: "hook", id: `guard:${workflow.selected}`, workflow: workflow.selected },
+    blockedReason: blockedByWorkflow(workflow),
+    advanced: { workflow: workflow.selected }
+  })];
+}
+
+function removeSkillForceActions({ paths, workflow, skills, workspace }) {
+  return skills.blocked
+    .filter((skill) => !missingProvenance(workspace, skill.id))
+    .map((skill) => {
+      const dryRun = command([
+        "skillboard", "remove", "skill", skill.id, "--force",
+        "--config", paths.configPath, "--skills", paths.skillsRoot, "--dry-run", "--json"
+      ]);
+      return makeAction({
+        kind: "remove-skill-force",
+        targetId: skill.id,
+        label: `Remove ${skill.id} from config with force`,
+        reason: "Preview forced config-reference removal before applying it.",
+        risk: "high",
+        dryRun,
+        apply: applyOrNull(workflow, dryRun, [
+          "skillboard", "remove", "skill", skill.id, "--force",
+          "--config", paths.configPath, "--skills", paths.skillsRoot, "--json"
+        ]),
+        appliesTo: { kind: "skill", id: skill.id },
+        blockedReason: blockedByWorkflow(workflow),
+        advanced: skillAdvanced(skill, { force: true })
+      });
+    });
+}
+
+function resetCleanupAction({ paths, workflow, cleanup }) {
+  const dryRun = command([
+    "skillboard", "uninstall", "--dir", paths.root, "--dry-run",
+    "--reset-config", "--remove-reports", "--remove-hooks"
+  ]);
+  return makeAction({
+    kind: "reset-cleanup",
+    targetId: paths.root,
+    label: "Reset SkillBoard generated project files",
+    reason: "Preview full SkillBoard cleanup before applying it.",
+    risk: "destructive",
+    dryRun,
+    apply: applyOrNull(workflow, dryRun, [
+      "skillboard", "uninstall", "--dir", paths.root,
+      "--reset-config", "--remove-reports", "--remove-hooks"
+    ]),
+    appliesTo: { kind: "project", id: paths.root },
+    blockedReason: blockedByWorkflow(workflow),
+    advanced: { full_reset: cleanup.full_reset }
+  });
+}
+
+function blockedActivateAction(paths, workflow, skill) {
+  return makeAction({
+    kind: "activate-skill",
+    targetId: skill.id,
+    label: `Activation blocked for ${skill.id}`,
+    reason: "Skill provenance must be declared before activation can be suggested.",
+    risk: "high",
+    dryRun: null,
+    apply: null,
+    appliesTo: { kind: "skill", id: skill.id, workflow: workflow.selected },
+    blockedReason: `Missing owner_install_unit/provenance for unit-managed skill ${skill.id}.`,
+    advanced: skillAdvanced(skill, { config_path: paths.configPath })
+  });
+}
+
+function canActivate(skill) {
+  return WRITABLE_MODES.has(skill.advanced.invocation) && skill.advanced.trust.reviewed === true;
+}
+
+function missingProvenance(workspace, skillId) {
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  if (skill?.exposure === "unit-managed" && skill.ownerInstallUnit === undefined) {
+    return true;
+  }
+  return skill?.ownerInstallUnit !== undefined
+    && !workspace.installUnits.some((unit) => unit.id === skill.ownerInstallUnit);
+}
+
+function riskFromSkill(skill) {
+  return skill.advanced.trust.permissionRisk === "high" ? "high" : "medium";
+}
+
+function skillAdvanced(skill, extra = {}) {
+  return {
+    invocation: skill.advanced.invocation,
+    owner_install_unit: skill.advanced.owner_install_unit,
+    source_class: skill.advanced.source_class,
+    ...extra
+  };
+}

package/src/advisor/application-commands.mjs

@@ -0,0 +1,59 @@
+import {
+  command,
+  workflowResolved
+} from "./action-core.mjs";
+
+export function withApplicationCommands(actions, { paths, workflow }) {
+  return actions.map((action) => {
+    return {
+      ...action,
+      application: applicationCommand(action, paths, workflow)
+    };
+  });
+}
+
+function applicationCommand(action, paths, workflow) {
+  const blockedReason = applicationBlockedReason(action, workflow);
+  if (blockedReason !== null) {
+    return {
+      preview: null,
+      apply: null,
+      blocked_reason: blockedReason
+    };
+  }
+
+  const base = [
+    "skillboard", "apply-action", action.id,
+    ...workflowArgs(workflow),
+    "--dir", paths.root,
+    "--config", paths.configPath,
+    "--skills", paths.skillsRoot,
+    "--json"
+  ];
+  return {
+    preview: command([...base, "--dry-run"]),
+    apply: command([...base, "--yes", ...destructiveArgs(action)]),
+    blocked_reason: null
+  };
+}
+
+function applicationBlockedReason(action, workflow) {
+  if (action.blocked_reason !== null) {
+    return action.blocked_reason;
+  }
+  if (action.apply === null) {
+    return "Action cannot be applied directly.";
+  }
+  if (!workflowResolved(workflow)) {
+    return workflow.blocked_reason ?? "Select a workflow before applying action cards.";
+  }
+  return null;
+}
+
+function workflowArgs(workflow) {
+  return workflowResolved(workflow) ? ["--workflow", workflow.selected] : [];
+}
+
+function destructiveArgs(action) {
+  return action.kind === "reset-cleanup" ? ["--allow-destructive"] : [];
+}

package/src/advisor/apply-action.mjs

@@ -0,0 +1,183 @@
+import { buildSkillBrief } from "../advisor.mjs";
+import {
+  activateSkill,
+  blockSkill,
+  installGuardHook,
+  removeSkill
+} from "../control.mjs";
+import { reviewInstallUnit } from "../review.mjs";
+import { uninstallProject } from "../uninstall.mjs";
+
+const INSTALL_UNIT_ACTIONS = new Set([
+  "block-install-unit",
+  "review-install-unit",
+  "trust-install-unit"
+]);
+
+export class ApplyActionError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "ApplyActionError";
+    this.code = code;
+  }
+}
+
+export async function applyAdvisorAction(actionId, options) {
+  if (actionId === undefined || actionId.length === 0) {
+    throw new ApplyActionError("missing-action-id", "Usage: skillboard apply-action <action-id>");
+  }
+
+  const action = await resolveCurrentAction(actionId, options);
+  if (action.blocked_reason !== null) {
+    throw new ApplyActionError("blocked-action", action.blocked_reason);
+  }
+
+  if (previewMode(options)) {
+    return {
+      ok: true,
+      mode: "preview",
+      changed: false,
+      action
+    };
+  }
+
+  if (action.apply === null) {
+    throw new ApplyActionError("action-not-applicable", `Action cannot be applied directly: ${action.id}`);
+  }
+
+  if (action.kind === "reset-cleanup" && options.allowDestructive !== true) {
+    throw new ApplyActionError(
+      "destructive-confirmation-required",
+      "reset-cleanup is destructive; pass --allow-destructive with --yes to apply it."
+    );
+  }
+
+  const control = await dispatchAction(action, options);
+  const brief = await buildActionBrief(options);
+  return {
+    ok: true,
+    mode: "applied",
+    changed: controlChanged(action, control),
+    action,
+    control,
+    brief
+  };
+}
+
+export function applyActionErrorPayload(error) {
+  if (error instanceof ApplyActionError) {
+    return { ok: false, error: { code: error.code, message: error.message } };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "apply-action-failed",
+      message: error instanceof Error ? error.message : String(error)
+    }
+  };
+}
+
+async function resolveCurrentAction(actionId, options) {
+  const brief = await buildActionBrief(options);
+  const actions = Array.isArray(brief.actions) ? brief.actions : [];
+  const matches = actions.filter((action) => action.id === actionId);
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new ApplyActionError("ambiguous-action", `Action id resolved more than once: ${actionId}`);
+  }
+  throw new ApplyActionError(
+    "stale-action",
+    `Action is no longer current or was not found: ${actionId}`
+  );
+}
+
+function buildActionBrief(options) {
+  return buildSkillBrief({
+    includeActions: true,
+    workflow: options.workflow,
+    configPath: options.configPath,
+    skillsRoot: options.skillsRoot,
+    root: options.root
+  });
+}
+
+function previewMode(options) {
+  return options.dryRun === true || options.yes !== true;
+}
+
+async function dispatchAction(action, options) {
+  if (INSTALL_UNIT_ACTIONS.has(action.kind)) {
+    return await reviewInstallUnit({
+      unitId: action.applies_to.id,
+      trustLevel: action.advanced.trust_level,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: false
+    });
+  }
+
+  if (action.kind === "activate-skill") {
+    return await activateSkill({
+      skillId: action.applies_to.id,
+      workflow: action.applies_to.workflow,
+      mode: action.advanced.mode,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: false
+    });
+  }
+
+  if (action.kind === "block-skill") {
+    return await blockSkill({
+      skillId: action.applies_to.id,
+      workflow: action.applies_to.workflow,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: false
+    });
+  }
+
+  if (action.kind === "hook-install") {
+    return await installGuardHook({
+      workflow: action.advanced.workflow,
+      out: options.hookOut,
+      command: options.skillboardBin,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot
+    });
+  }
+
+  if (action.kind === "remove-skill-force") {
+    return await removeSkill({
+      skillId: action.applies_to.id,
+      force: true,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: false
+    });
+  }
+
+  if (action.kind === "reset-cleanup") {
+    return await uninstallProject({
+      root: action.applies_to.id,
+      dryRun: false,
+      resetConfig: true,
+      removeReports: true,
+      removeHooks: true
+    });
+  }
+
+  throw new ApplyActionError("unsupported-action", `Unsupported action kind: ${action.kind}`);
+}
+
+function controlChanged(action, control) {
+  if (typeof control.changed === "boolean") {
+    return control.changed;
+  }
+  if (action.kind === "reset-cleanup") {
+    return control.removed.length > 0 || control.updated.length > 0;
+  }
+  return true;
+}