@silverassist/agents-toolkit 2.3.0 → 2.5.0

package/bin/cli.js

@@ -7,7 +7,9 @@
 
 import fs from 'fs';
 import path from 'path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'url';
+import { VERSION } from '../src/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -49,7 +51,7 @@ const DEFAULT_CONFIG = {
  */
 const FILE_CATEGORIES = {
   instructions: {
-    react: ['css-styling', 'react-components', 'server-actions', 'tests', 'typescript'],
+    react: ['caching', 'css-styling', 'react-components', 'seo-ai-optimization', 'server-actions', 'tests', 'typescript'],
     wordpress: ['php-standards', 'wordpress-plugin-architecture', 'testing-standards'],
     universal: ['documentation-language', 'github-workflow'],
   },
@@ -59,18 +61,21 @@ const FILE_CATEGORIES = {
     universal: [
       'analyze-ticket', 'work-ticket', 'analyze-github-issue', 'work-github-issue',
       'create-plan', 'create-pr', 'prepare-pr', 'finalize-pr',
-      'review-code', 'fix-issues', 'add-tests', 'prepare-release',
+      'create-github-pr', 'finalize-github-pr',
+      'review-code', 'fix-issues', 'add-tests', 'prepare-github-release',
     ],
     jira: ['analyze-ticket', 'work-ticket', 'create-pr', 'finalize-pr'],
-    github: ['analyze-github-issue', 'work-github-issue'],
+    github: ['analyze-github-issue', 'work-github-issue', 'create-github-pr', 'finalize-github-pr'],
   },
   partials: {
+    react: ['release-node'],
+    wordpress: ['release-wordpress'],
     jira: ['jira-integration'],
     github: ['github-integration'],
     universal: ['git-operations', 'pr-template', 'validations', 'documentation'],
   },
   skills: {
-    react: ['component-architecture', 'testing-patterns'],
+    react: ['component-architecture', 'nextjs-caching', 'testing-patterns'],
     wordpress: ['create-component', 'plugin-creation', 'quality-checks', 'testing'],
     universal: ['domain-driven-design', 'release-management'],
   },
@@ -179,6 +184,242 @@ function getClaudeTargetDir(global = false) {
   return path.join(process.cwd(), '.claude');
 }
 
+/**
+ * Get the canonical skills directory following the `npx skills` standard.
+ * Skills live here once (single source of truth) and each agent's skills
+ * directory symlinks to it.
+ * @param {boolean} global - Use user-level ~/.agents/skills/
+ * @returns {string} Path to .agents/skills directory
+ */
+function getAgentsSkillsDir(global = false) {
+  const base = global ? getHomeDir() : process.cwd();
+  return path.join(base, '.agents', 'skills');
+}
+
+/** Path to the project-level lockfile. */
+const LOCKFILE_NAME = 'agents-toolkit-lock.json';
+
+/**
+ * Compute a hex-encoded SHA-256 hash of a skill's SKILL.md content.
+ * Matches the algorithm used by `npx skills` (Vercel).
+ * @param {string} skillDir - Absolute path to the skill directory
+ * @returns {string|null} Hex hash string, or null if SKILL.md is missing
+ */
+function computeSkillHash(skillDir) {
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMdPath)) return null;
+  const content = fs.readFileSync(skillMdPath, 'utf-8');
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Read and parse the project lockfile.
+ * @param {string} [cwd] - Directory to look in (defaults to process.cwd())
+ * @returns {Object|null} Parsed lockfile, or null if absent or invalid
+ */
+function readLockfile(cwd = process.cwd()) {
+  const lockPath = path.join(cwd, LOCKFILE_NAME);
+  if (!fs.existsSync(lockPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the project lockfile, merging new skills with any existing entries.
+ * This preserves skills installed by a previous `install --target` run so that
+ * running `install` followed by `install --claude` does not lose the first
+ * target's entries in the lockfile.
+ * @param {Object} params
+ * @param {Record<string, {computedHash: string|null, agents: string[]}>} params.skills - Newly installed skills map
+ * @param {{ stack: string, tracker: string }} params.config - Active install config
+ * @param {string} params.packageVersion - Current package version
+ * @param {string} [params.cwd] - Directory to write to (defaults to process.cwd())
+ */
+function writeLockfile({ skills, config, packageVersion, cwd = process.cwd() }) {
+  const lockPath = path.join(cwd, LOCKFILE_NAME);
+
+  // Merge with any existing lockfile so successive multi-target installs
+  // (e.g. `install` then `install --claude`) accumulate entries.
+  const existing = readLockfile(cwd);
+  const mergedSkills = Object.assign({}, existing?.skills ?? {});
+
+  for (const [name, meta] of Object.entries(skills)) {
+    const prev = mergedSkills[name];
+    // Merge agents arrays: union of previous and new agent dirs.
+    const prevAgents = prev?.agents ?? [];
+    const allAgents = Array.from(new Set([...prevAgents, ...meta.agents]));
+    mergedSkills[name] = {
+      source: '@silverassist/agents-toolkit',
+      packageVersion,
+      computedHash: meta.computedHash,
+      agents: allAgents,
+    };
+  }
+
+  const lockfile = {
+    version: 1,
+    packageVersion,
+    config,
+    skills: mergedSkills,
+  };
+  fs.writeFileSync(lockPath, JSON.stringify(lockfile, null, 2) + '\n', 'utf-8');
+  success(`Wrote ${LOCKFILE_NAME}`);
+}
+
+/**
+ * Append skills-managed entries to .gitignore if not already present.
+ * Never runs during dry-run or global installs.
+ * @param {string} cwd - Project root directory
+ */
+function appendSkillsToGitignore(cwd) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const block = [
+    '',
+    '# agents-toolkit managed — regenerate with: npx @silverassist/agents-toolkit restore',
+    '.agents/skills/',
+    '.github/skills/',
+    '.claude/skills/',
+  ].join('\n');
+
+  let existing = '';
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+
+  // Only append if none of the three managed paths are already present.
+  if (
+    existing.includes('.agents/skills/') ||
+    existing.includes('.github/skills/') ||
+    existing.includes('.claude/skills/')
+  ) {
+    return;
+  }
+
+  fs.writeFileSync(gitignorePath, existing + block + '\n', 'utf-8');
+  info('Updated .gitignore with agents-toolkit managed paths');
+}
+
+/**
+ * Link a single skill from the canonical store into an agent's skills
+ * directory, following the `npx skills` standard (symlink with copy fallback).
+ * @param {string} canonicalSkillDir - Absolute path to the canonical skill folder
+ * @param {string} agentSkillLinkPath - Absolute path where the agent expects the skill
+ * @param {Object} options - Link options
+ * @param {boolean} [options.dryRun] - Only report what would happen
+ * @param {boolean} [options.force] - Replace an existing non-matching entry
+ * @param {boolean} [options.copy] - Force a copy instead of a symlink
+ * @returns {{ written: number, planned: number }} Change counters
+ */
+function linkSkill(canonicalSkillDir, agentSkillLinkPath, options = {}) {
+  const { dryRun = false, force = false, copy = false } = options;
+  const totals = { written: 0, planned: 0 };
+
+  const relTarget = path.relative(path.dirname(agentSkillLinkPath), canonicalSkillDir);
+  const rel = (p) => path.relative(process.cwd(), p);
+
+  // Inspect any existing entry at the link path.
+  let existing = null;
+  try {
+    existing = fs.lstatSync(agentSkillLinkPath);
+  } catch {
+    existing = null;
+  }
+
+  if (existing) {
+    // Already a symlink pointing at our canonical store — nothing to do.
+    if (existing.isSymbolicLink()) {
+      const current = fs.readlinkSync(agentSkillLinkPath);
+      const resolved = path.resolve(path.dirname(agentSkillLinkPath), current);
+      if (resolved === path.resolve(canonicalSkillDir) && !copy) {
+        return totals;
+      }
+    }
+    if (!force) {
+      warn(`Skipping existing skill: ${rel(agentSkillLinkPath)}`);
+      return totals;
+    }
+    if (!dryRun) {
+      fs.rmSync(agentSkillLinkPath, { recursive: true, force: true });
+    }
+  }
+
+  totals.planned++;
+
+  if (dryRun) {
+    info(copy ? `Would copy skill: ${rel(agentSkillLinkPath)}` : `Would link: ${rel(agentSkillLinkPath)} -> ${relTarget}`);
+    return totals;
+  }
+
+  fs.mkdirSync(path.dirname(agentSkillLinkPath), { recursive: true });
+
+  const doCopy = () => {
+    copyDir(canonicalSkillDir, agentSkillLinkPath, { force: true });
+  };
+
+  if (copy) {
+    doCopy();
+  } else {
+    try {
+      fs.symlinkSync(relTarget, agentSkillLinkPath, 'dir');
+    } catch {
+      // Symlinks unsupported (e.g. Windows without developer mode) — copy instead.
+      doCopy();
+    }
+  }
+
+  totals.written++;
+  return totals;
+}
+
+/**
+ * Install skills following the `npx skills` standard: copy each skill once
+ * into the canonical .agents/skills store, then symlink the agent's skills
+ * directory entries to that store.
+ * @param {Object} params - Install parameters
+ * @param {boolean} params.isGlobal - Install at user level
+ * @param {string} params.agentSkillsDir - Agent skills dir (.claude/skills or .github/skills)
+ * @param {boolean} [params.force] - Overwrite existing files/links
+ * @param {boolean} [params.dryRun] - Only report planned changes
+ * @param {boolean} [params.copy] - Copy instead of symlink
+ * @param {(name: string) => boolean} [params.dirFilter] - Skill folder filter
+ * @returns {{ written: number, planned: number, installedSkills: Record<string, { canonicalDir: string }> }} Aggregated change counters and installed skill metadata
+ */
+function installSkillsStandard({ isGlobal, agentSkillsDir, force = false, dryRun = false, copy = false, dirFilter = null }) {
+  const totals = { written: 0, planned: 0, installedSkills: {} };
+  const skillsSrc = path.join(TEMPLATES_DIR, 'shared', 'skills');
+  const canonicalDir = getAgentsSkillsDir(isGlobal);
+
+  if (!fs.existsSync(skillsSrc)) {
+    return totals;
+  }
+
+  // 1. Populate the canonical store once (filtered by stack).
+  const canonicalResult = copyDir(skillsSrc, canonicalDir, { force, dryRun, dirFilter });
+  totals.written += canonicalResult.written;
+  totals.planned += canonicalResult.planned;
+
+  // 2. Symlink each included skill folder into the agent's skills directory.
+  const entries = fs.readdirSync(skillsSrc, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (dirFilter && !dirFilter(entry.name)) continue;
+
+    const canonicalSkillDir = path.join(canonicalDir, entry.name);
+    const agentSkillLinkPath = path.join(agentSkillsDir, entry.name);
+    const linkResult = linkSkill(canonicalSkillDir, agentSkillLinkPath, { dryRun, force, copy });
+    totals.written += linkResult.written;
+    totals.planned += linkResult.planned;
+
+    // Track for lockfile even during dry-run (so callers know what would be installed).
+    totals.installedSkills[entry.name] = { canonicalDir: canonicalSkillDir };
+  }
+
+  return totals;
+}
+
 /**
  * Strip GitHub Copilot frontmatter from a prompt file
  * Removes the ---\nagent: ...\ndescription: ...\n--- block
@@ -303,7 +544,38 @@ function getChangeCount(result, dryRun) {
   return dryRun ? result.planned : result.written;
 }
 
-function installHooks({ targetDir, force = false, dryRun = false }) {
+/**
+ * Finalize installed hook configs so Copilot can resolve the script command.
+ * Copilot runs a hook `command` from the workspace root by default, not from
+ * the hooks directory, so the relative `scripts/<name>.sh` command needs a
+ * `cwd` pointing at the actual hooks dir. Also ensures the required
+ * `version: 1` field is present.
+ * @param {string} hooksDest - Absolute path to the installed hooks directory
+ * @param {boolean} isGlobal - Whether this is a global (~/.copilot) install
+ */
+function finalizeHookConfigs(hooksDest, isGlobal) {
+  // Global installs have no workspace anchor → use the absolute hooks path.
+  // Project installs use a path relative to the workspace root so the config
+  // stays portable/committable across machines and teammates.
+  const cwd = isGlobal
+    ? hooksDest
+    : path.relative(process.cwd(), hooksDest).split(path.sep).join('/');
+
+  const jsonFiles = fs.readdirSync(hooksDest).filter((f) => f.endsWith('.json'));
+  for (const file of jsonFiles) {
+    const filePath = path.join(hooksDest, file);
+    const config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    config.version = 1;
+    for (const events of Object.values(config.hooks || {})) {
+      for (const entry of events) {
+        entry.cwd = cwd;
+      }
+    }
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+  }
+}
+
+function installHooks({ targetDir, force = false, dryRun = false, global: isGlobal = false }) {
   const hooksSrc = path.join(TEMPLATES_DIR, 'shared', 'hooks');
   const hooksDest = path.join(targetDir, 'hooks');
 
@@ -315,7 +587,7 @@ function installHooks({ targetDir, force = false, dryRun = false }) {
   // Copy hook JSON configs and scripts
   const result = copyDir(hooksSrc, hooksDest, { force, dryRun });
 
-  // Make scripts executable (non-dry-run only)
+  // Make scripts executable and finalize configs (non-dry-run only)
   if (!dryRun) {
     const scriptsDir = path.join(hooksDest, 'scripts');
     if (fs.existsSync(scriptsDir)) {
@@ -325,6 +597,9 @@ function installHooks({ targetDir, force = false, dryRun = false }) {
         fs.chmodSync(scriptPath, 0o755);
       }
     }
+    if (fs.existsSync(hooksDest)) {
+      finalizeHookConfigs(hooksDest, isGlobal);
+    }
   }
 
   if (!dryRun && result.written > 0) {
@@ -472,6 +747,7 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
     force = false,
     append = false,
     dryRun = false,
+    copy = false,
     global: isGlobal = false,
     filters = { stack: 'all', tracker: 'all' },
   } = options;
@@ -479,6 +755,8 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
   const targetDir = getTargetDir(isGlobal);
   const scope = getInstallScope(options);
   let totalChanges = 0;
+  /** @type {Record<string, { canonicalDir: string, agents: string[] }>} */
+  const installedSkillsMap = {};
 
   const makeFilter = (category) => (name) => {
     const basename = name.replace(/\.(prompt\.md|instructions\.md|md)$/, '');
@@ -519,18 +797,32 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
   }
 
   if (scope.shouldInstallSkills) {
-    info('Installing skills...');
-    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'skills'), path.join(targetDir, 'skills'), { force, dryRun, dirFilter: makeFilter('skills') });
+    info('Installing skills (npx skills standard)...');
+    const result = installSkillsStandard({
+      isGlobal,
+      agentSkillsDir: path.join(targetDir, 'skills'),
+      force,
+      dryRun,
+      copy,
+      dirFilter: makeFilter('skills'),
+    });
     totalChanges += getChangeCount(result, dryRun);
+    // Merge installed skills for lockfile (agent dir = .github/skills or ~/.copilot/skills).
+    for (const [name, meta] of Object.entries(result.installedSkills)) {
+      if (!installedSkillsMap[name]) {
+        installedSkillsMap[name] = { canonicalDir: meta.canonicalDir, agents: [] };
+      }
+      installedSkillsMap[name].agents.push(path.relative(process.cwd(), path.join(targetDir, 'skills')));
+    }
 
     if (!dryRun && result.written > 0) {
-      success(`Installed ${result.written} skill files`);
+      success(`Installed ${result.written} skill files/links`);
     }
   }
 
   if (scope.shouldInstallHooks) {
     info('Installing hooks...');
-    const hooksResult = installHooks({ targetDir, force, dryRun });
+    const hooksResult = installHooks({ targetDir, force, dryRun, global: isGlobal });
     totalChanges += getChangeCount(hooksResult, dryRun);
   }
 
@@ -550,6 +842,19 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
     totalChanges += getChangeCount(agentsResult, dryRun);
   }
 
+  // Write lockfile and update .gitignore for project (non-global, non-dry-run) installs.
+  if (!isGlobal && !dryRun && scope.shouldInstallSkills && Object.keys(installedSkillsMap).length > 0) {
+    const skillsForLock = {};
+    for (const [name, meta] of Object.entries(installedSkillsMap)) {
+      skillsForLock[name] = {
+        computedHash: computeSkillHash(meta.canonicalDir),
+        agents: meta.agents,
+      };
+    }
+    writeLockfile({ skills: skillsForLock, config: filters, packageVersion: VERSION });
+    appendSkillsToGitignore(process.cwd());
+  }
+
   console.log('');
   if (dryRun) {
     info(`Dry run complete. ${totalChanges} files would be installed.`);
@@ -598,11 +903,13 @@ function installCodex(options = {}) {
  * @param {Object} options - Install options
  */
 function installClaude(options = {}) {
-  const { force = false, dryRun = false, global: isGlobal = false, filters = { stack: 'all', tracker: 'all' } } = options;
+  const { force = false, dryRun = false, copy = false, global: isGlobal = false, filters = { stack: 'all', tracker: 'all' } } = options;
   const scope = getInstallScope(options);
   const claudeDir = getClaudeTargetDir(isGlobal);
   const githubDir = getTargetDir(isGlobal);
   let totalChanges = 0;
+  /** @type {Record<string, { canonicalDir: string, agents: string[] }>} */
+  const installedSkillsMap = {};
 
   const makeFilter = (category) => (name) => {
     const basename = name.replace(/\.(prompt\.md|instructions\.md|md)$/, '');
@@ -646,12 +953,25 @@ function installClaude(options = {}) {
   }
 
   if (scope.shouldInstallSkills) {
-    info('Installing skills...');
-    const result = copyDir(path.join(TEMPLATES_DIR, 'shared', 'skills'), path.join(githubDir, 'skills'), { force, dryRun, dirFilter: makeFilter('skills') });
+    info('Installing skills (npx skills standard)...');
+    const result = installSkillsStandard({
+      isGlobal,
+      agentSkillsDir: path.join(claudeDir, 'skills'),
+      force,
+      dryRun,
+      copy,
+      dirFilter: makeFilter('skills'),
+    });
     totalChanges += getChangeCount(result, dryRun);
+    for (const [name, meta] of Object.entries(result.installedSkills)) {
+      if (!installedSkillsMap[name]) {
+        installedSkillsMap[name] = { canonicalDir: meta.canonicalDir, agents: [] };
+      }
+      installedSkillsMap[name].agents.push(path.relative(process.cwd(), path.join(claudeDir, 'skills')));
+    }
 
     if (!dryRun && result.written > 0) {
-      success(`Installed ${result.written} skill files`);
+      success(`Installed ${result.written} skill files/links to .claude/skills/`);
     }
   }
 
@@ -678,6 +998,19 @@ function installClaude(options = {}) {
   const configResult = ensureConfigFile({ dryRun, global: isGlobal });
   totalChanges += getChangeCount(configResult, dryRun);
 
+  // Write lockfile and update .gitignore for project (non-global, non-dry-run) installs.
+  if (!isGlobal && !dryRun && scope.shouldInstallSkills && Object.keys(installedSkillsMap).length > 0) {
+    const skillsForLock = {};
+    for (const [name, meta] of Object.entries(installedSkillsMap)) {
+      skillsForLock[name] = {
+        computedHash: computeSkillHash(meta.canonicalDir),
+        agents: meta.agents,
+      };
+    }
+    writeLockfile({ skills: skillsForLock, config: filters, packageVersion: VERSION });
+    appendSkillsToGitignore(process.cwd());
+  }
+
   console.log('');
   if (dryRun) {
     info(`Dry run complete. ${totalChanges} files would be installed.`);
@@ -700,6 +1033,158 @@ function installClaude(options = {}) {
   console.log('');
 }
 
+/**
+ * Restore skills from the lockfile.
+ * Reads agents-toolkit-lock.json, reinstalls all skills, and verifies hashes.
+ * Restore always overwrites existing skill files — that is its purpose.
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun] - Only report planned changes
+ * @param {boolean} [options.copy] - Copy instead of symlink
+ */
+function restore(options = {}) {
+  const { dryRun = false, copy = false } = options;
+  log('\n🔄 Agents Toolkit Restore\n', 'bright');
+
+  const lockfile = readLockfile();
+  if (!lockfile) {
+    error(`No ${LOCKFILE_NAME} found. Run "install" first to generate it.`);
+    process.exit(1);
+  }
+
+  if (lockfile.packageVersion !== VERSION) {
+    warn(`Lockfile was created with v${lockfile.packageVersion}, current package is v${VERSION}.`);
+    warn('Run "update" to refresh the lockfile for the current version.');
+  }
+
+  if (dryRun) {
+    info('Dry run mode - no files will be restored\n');
+  }
+
+  const { stack = 'all', tracker = 'all' } = lockfile.config || {};
+  const filters = { stack, tracker };
+  const makeFilter = (category) => (name) => {
+    const basename = name.replace(/\.(prompt\.md|instructions\.md|md)$/, '');
+    return shouldIncludeFile(basename, category, filters);
+  };
+
+  // Determine which agent dirs were recorded in the lockfile.
+  const agentDirs = new Set();
+  for (const meta of Object.values(lockfile.skills || {})) {
+    for (const agentDir of (meta.agents || [])) {
+      agentDirs.add(agentDir);
+    }
+  }
+
+  // Reinstall into each unique agent skills dir.
+  let totalRestored = 0;
+  for (const agentDir of agentDirs) {
+    const agentSkillsDir = path.join(process.cwd(), agentDir);
+    const result = installSkillsStandard({
+      isGlobal: false,
+      agentSkillsDir,
+      force: true, // restore always overwrites — that is its purpose
+      dryRun,
+      copy,
+      dirFilter: makeFilter('skills'),
+    });
+    totalRestored += dryRun ? result.planned : result.written;
+  }
+
+  if (dryRun) {
+    info(`Dry run complete. ${totalRestored} files would be restored.`);
+    return;
+  }
+
+  // Verify hashes match the lockfile.
+  const canonicalDir = getAgentsSkillsDir(false);
+  let allMatch = true;
+  for (const [name, meta] of Object.entries(lockfile.skills || {})) {
+    const canonicalSkillDir = path.join(canonicalDir, name);
+    const hash = computeSkillHash(canonicalSkillDir);
+    if (hash !== meta.computedHash) {
+      warn(`Hash mismatch for skill "${name}" — expected ${meta.computedHash?.slice(0, 12)}… got ${hash?.slice(0, 12)}…`);
+      allMatch = false;
+    }
+  }
+
+  console.log('');
+  if (allMatch) {
+    success(`Restored ${Object.keys(lockfile.skills || {}).length} skills successfully.`);
+  } else {
+    warn(`Restored with hash mismatches. Run "update" to refresh the lockfile.`);
+  }
+  console.log('');
+}
+
+/**
+ * Show the status of installed skills relative to the lockfile.
+ * Exits with code 1 if any skill is missing or has a hash mismatch.
+ */
+function status() {
+  log('\n📊 Agents Toolkit Status\n', 'bright');
+
+  const lockfile = readLockfile();
+  if (!lockfile) {
+    error(`No ${LOCKFILE_NAME} found. Run "install" first to generate it.`);
+    process.exit(1);
+  }
+
+  const canonicalDir = getAgentsSkillsDir(false);
+  const skills = lockfile.skills || {};
+  let hasIssues = false;
+
+  if (Object.keys(skills).length === 0) {
+    info('No skills recorded in lockfile.');
+    return;
+  }
+
+  if (lockfile.packageVersion !== VERSION) {
+    warn(`Lockfile package version: v${lockfile.packageVersion} — current: v${VERSION}`);
+  }
+
+  console.log('');
+  const COL_NAME = 28;
+  const COL_STATUS = 14;
+  const header = `${'Skill'.padEnd(COL_NAME)} ${'Status'.padEnd(COL_STATUS)} Hash`;
+  log(header, 'cyan');
+  log('─'.repeat(header.length), 'cyan');
+
+  for (const [name, meta] of Object.entries(skills)) {
+    const canonicalSkillDir = path.join(canonicalDir, name);
+    const hash = computeSkillHash(canonicalSkillDir);
+
+    let statusLabel;
+    let statusColor;
+
+    if (hash === null) {
+      statusLabel = 'missing';
+      statusColor = 'red';
+      hasIssues = true;
+    } else if (hash !== meta.computedHash) {
+      statusLabel = 'modified';
+      statusColor = 'yellow';
+      hasIssues = true;
+    } else {
+      statusLabel = 'up-to-date';
+      statusColor = 'green';
+    }
+
+    const hashDisplay = hash ? hash.slice(0, 12) + '…' : '—';
+    const line = `${name.padEnd(COL_NAME)} ${statusLabel.padEnd(COL_STATUS)} ${hashDisplay}`;
+    log(line, statusColor);
+  }
+
+  console.log('');
+
+  if (hasIssues) {
+    warn('Some skills are out of sync. Run "restore" or "update" to fix.');
+    process.exit(1);
+  } else {
+    success(`All ${Object.keys(skills).length} skills are up-to-date.`);
+  }
+  console.log('');
+}
+
 /**
  * List available prompts
  */
@@ -718,7 +1203,7 @@ function list() {
     .map(f => f.replace('.prompt.md', ''));
 
   log('Workflow Prompts:', 'cyan');
-  const workflowPrompts = ['analyze-ticket', 'create-plan', 'work-ticket', 'prepare-pr', 'create-pr', 'finalize-pr'];
+  const workflowPrompts = ['analyze-ticket', 'create-plan', 'work-ticket', 'prepare-pr', 'create-pr', 'finalize-pr', 'analyze-github-issue', 'work-github-issue', 'create-github-pr', 'finalize-github-pr'];
   workflowPrompts.forEach((p, i) => {
     if (prompts.includes(p)) {
       console.log(`  ${i + 1}. ${p}`);
@@ -777,8 +1262,10 @@ function showHelp() {
   
   log('Commands:', 'cyan');
   console.log('  install     Install prompts (default target: copilot)');
+  console.log('  restore     Restore skills from agents-toolkit-lock.json');
+  console.log('  status      Check if installed skills match the lockfile');
+  console.log('  update      Update existing prompts and refresh the lockfile');
   console.log('  list        List available prompts');
-  console.log('  update      Update existing prompts (alias for install --force)');
   console.log('  help        Show this help message');
   
   console.log('');
@@ -796,6 +1283,7 @@ function showHelp() {
   console.log('  --partials-only     Only install partials');
   console.log('  --skills-only       Only install skills');
   console.log('  --hooks-only        Only install hooks (PostToolUse validation scripts)');
+  console.log('  --copy              Copy skills instead of symlinking to .agents/skills/');
   console.log('  --dry-run           Show what would be installed');
 
   console.log('');
@@ -874,6 +1362,7 @@ function parseArgs() {
     instructionsOnly: flags.includes('--instructions-only'),
     hooksOnly: flags.includes('--hooks-only'),
     dryRun: flags.includes('--dry-run'),
+    copy: flags.includes('--copy'),
     claude: flags.includes('--claude'),
     codex: flags.includes('--codex'),
     append: flags.includes('--append'),
@@ -1017,6 +1506,12 @@ function main() {
         install({ ...options, filters });
       }
       break;
+    case 'restore':
+      restore(options);
+      break;
+    case 'status':
+      status();
+      break;
     case 'update':
       if (target === 'claude') {
         installClaude({ ...options, force: true, filters });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverassist/agents-toolkit",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Reusable AI agent prompts for development workflows with Jira integration — supports GitHub Copilot, Claude Code, and Codex",
   "author": "Santiago Ramirez",
   "license": "PolyForm-Noncommercial-1.0.0",