@whitehatd/crag 0.0.1 → 0.2.1

package/src/commands/check.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function check() {
+  const cwd = process.cwd();
+  const checks = [
+    ['.claude/skills/pre-start-context/SKILL.md', 'Pre-start skill (universal)'],
+    ['.claude/skills/post-start-validation/SKILL.md', 'Post-start skill (universal)'],
+    ['.claude/governance.md', 'Governance rules'],
+    ['.claude/hooks/drift-detector.sh', 'Drift detector hook'],
+    ['.claude/hooks/circuit-breaker.sh', 'Circuit breaker hook'],
+    ['.claude/agents/test-runner.md', 'Test runner agent'],
+    ['.claude/agents/security-reviewer.md', 'Security reviewer agent'],
+    ['.claude/ci-playbook.md', 'CI playbook'],
+    ['.claude/settings.local.json', 'Settings with hooks'],
+  ];
+
+  const optional = [
+    ['.claude/.session-name', 'Session name (remote access)'],
+    ['.claude/hooks/pre-compact-snapshot.sh', 'Pre-compact hook (MemStack)'],
+    ['.claude/hooks/post-compact-recovery.sh', 'Post-compact hook (MemStack)'],
+    ['.claude/rules/knowledge.md', 'MemStack knowledge rule'],
+    ['.claude/rules/diary.md', 'MemStack diary rule'],
+    ['.claude/rules/echo.md', 'MemStack echo rule'],
+  ];
+
+  console.log(`\n  Checking crag infrastructure in ${cwd}\n`);
+
+  console.log(`  Core:`);
+  let missing = 0;
+  for (const [file, name] of checks) {
+    const exists = fs.existsSync(path.join(cwd, file));
+    const icon = exists ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`    ${icon} ${name}`);
+    if (!exists) missing++;
+  }
+
+  console.log(`\n  Optional:`);
+  for (const [file, name] of optional) {
+    const exists = fs.existsSync(path.join(cwd, file));
+    const icon = exists ? '\x1b[32m✓\x1b[0m' : '\x1b[90m○\x1b[0m';
+    console.log(`    ${icon} ${name}`);
+  }
+
+  console.log(`\n  ${checks.length - missing}/${checks.length} core files present.`);
+  if (missing > 0) {
+    console.log(`  Run 'crag init' to generate missing files.\n`);
+  } else {
+    console.log(`  Infrastructure complete.\n`);
+  }
+}
+
+module.exports = { check };

package/src/commands/compile.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseGovernance, flattenGates } = require('../governance/parse');
+const { generateGitHubActions } = require('../compile/github-actions');
+const { generateHusky } = require('../compile/husky');
+const { generatePreCommitConfig } = require('../compile/pre-commit');
+const { generateAgentsMd } = require('../compile/agents-md');
+const { generateCursorRules } = require('../compile/cursor-rules');
+const { generateGeminiMd } = require('../compile/gemini-md');
+const { generateCopilot } = require('../compile/copilot');
+const { generateCline } = require('../compile/cline');
+const { generateContinue } = require('../compile/continue');
+const { generateWindsurf } = require('../compile/windsurf');
+const { generateZed } = require('../compile/zed');
+const { generateCody } = require('../compile/cody');
+
+// All supported compile targets in dispatch order.
+// Grouped: CI (3) + AI agent native (3) + AI agent extras (6)
+const ALL_TARGETS = [
+  'github',
+  'husky',
+  'pre-commit',
+  'agents-md',
+  'cursor',
+  'gemini',
+  'copilot',
+  'cline',
+  'continue',
+  'windsurf',
+  'zed',
+  'cody',
+];
+
+function compile(args) {
+  const targetIdx = args.indexOf('--target');
+  const target = targetIdx !== -1 ? args[targetIdx + 1] : args[1];
+  const cwd = process.cwd();
+  const govPath = path.join(cwd, '.claude', 'governance.md');
+
+  if (!fs.existsSync(govPath)) {
+    console.error('  Error: No .claude/governance.md found. Run crag init first.');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(govPath, 'utf-8');
+  const parsed = parseGovernance(content);
+  const flat = flattenGates(parsed.gates);
+  const gateCount = Object.values(flat).flat().length;
+
+  if (!target || target === 'list') {
+    console.log(`\n  crag compile — ${parsed.name || 'unnamed project'}`);
+    console.log(`  ${gateCount} gate(s) in ${Object.keys(parsed.gates).length} section(s), ${parsed.runtimes.length} runtime(s) detected\n`);
+    console.log('  CI / git hooks:');
+    console.log('    crag compile --target github       .github/workflows/gates.yml');
+    console.log('    crag compile --target husky        .husky/pre-commit');
+    console.log('    crag compile --target pre-commit   .pre-commit-config.yaml\n');
+    console.log('  AI coding agents — native formats:');
+    console.log('    crag compile --target agents-md    AGENTS.md (Codex, Aider, Factory)');
+    console.log('    crag compile --target cursor       .cursor/rules/governance.mdc');
+    console.log('    crag compile --target gemini       GEMINI.md\n');
+    console.log('  AI coding agents — additional formats:');
+    console.log('    crag compile --target copilot      .github/copilot-instructions.md');
+    console.log('    crag compile --target cline        .clinerules');
+    console.log('    crag compile --target continue     .continuerules');
+    console.log('    crag compile --target windsurf     .windsurfrules');
+    console.log('    crag compile --target zed          .zed/rules.md');
+    console.log('    crag compile --target cody         .sourcegraph/cody-instructions.md\n');
+    console.log('  Combined:');
+    console.log('    crag compile --target all          All 12 targets at once\n');
+    return;
+  }
+
+  const targets = target === 'all' ? ALL_TARGETS : [target];
+
+  console.log(`\n  Compiling governance.md → ${targets.join(', ')}`);
+  console.log(`  ${gateCount} gates, ${parsed.runtimes.length} runtimes detected\n`);
+
+  for (const t of targets) {
+    switch (t) {
+      case 'github':     generateGitHubActions(cwd, parsed); break;
+      case 'husky':      generateHusky(cwd, parsed); break;
+      case 'pre-commit': generatePreCommitConfig(cwd, parsed); break;
+      case 'agents-md':  generateAgentsMd(cwd, parsed); break;
+      case 'cursor':     generateCursorRules(cwd, parsed); break;
+      case 'gemini':     generateGeminiMd(cwd, parsed); break;
+      case 'copilot':    generateCopilot(cwd, parsed); break;
+      case 'cline':      generateCline(cwd, parsed); break;
+      case 'continue':   generateContinue(cwd, parsed); break;
+      case 'windsurf':   generateWindsurf(cwd, parsed); break;
+      case 'zed':        generateZed(cwd, parsed); break;
+      case 'cody':       generateCody(cwd, parsed); break;
+      default:
+        console.error(`  Unknown target: ${t}`);
+        console.error(`  Valid targets: ${ALL_TARGETS.join(', ')}, all, list`);
+        process.exit(1);
+    }
+  }
+
+  console.log('\n  Done. Governance is now executable infrastructure.\n');
+}
+
+module.exports = { compile, ALL_TARGETS };

package/src/commands/diff.js

@@ -0,0 +1,289 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { parseGovernance, flattenGates } = require('../governance/parse');
+
+/**
+ * crag diff — compare governance.md against codebase reality.
+ */
+function diff(args) {
+  const cwd = process.cwd();
+  const govPath = path.join(cwd, '.claude', 'governance.md');
+
+  if (!fs.existsSync(govPath)) {
+    console.error('  Error: No .claude/governance.md found. Run crag init or crag analyze first.');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(govPath, 'utf-8');
+  const parsed = parseGovernance(content);
+  const flat = flattenGates(parsed.gates);
+
+  console.log(`\n  Governance vs Reality — ${parsed.name || 'project'}\n`);
+
+  const results = { match: 0, drift: 0, missing: 0, extra: 0 };
+
+  // Check each gate command
+  for (const [section, cmds] of Object.entries(flat)) {
+    for (const cmd of cmds) {
+      const check = checkGateReality(cwd, cmd);
+      const icon = check.status === 'match' ? '\x1b[32mMATCH\x1b[0m'
+        : check.status === 'drift' ? '\x1b[33mDRIFT\x1b[0m'
+        : '\x1b[31mMISSING\x1b[0m';
+      console.log(`  ${icon}   ${cmd}`);
+      if (check.detail) console.log(`          ${check.detail}`);
+      results[check.status]++;
+    }
+  }
+
+  // Check for CI gates not in governance
+  const ciGates = extractCIGateCommands(cwd);
+  const govCommands = Object.values(flat).flat();
+  for (const ciGate of ciGates) {
+    if (!govCommands.some(g => normalizeCmd(g) === normalizeCmd(ciGate))) {
+      console.log(`  \x1b[36mEXTRA\x1b[0m   ${ciGate}`);
+      console.log(`          In CI workflow but not in governance`);
+      results.extra++;
+    }
+  }
+
+  // Check branch strategy
+  checkBranchStrategy(cwd, content, results);
+
+  // Check commit convention
+  checkCommitConvention(cwd, content, results);
+
+  // Summary
+  const total = results.match + results.drift + results.missing + results.extra;
+  console.log(`\n  ${results.match} match, ${results.drift} drift, ${results.missing} missing, ${results.extra} extra (${total} total)\n`);
+}
+
+function checkGateReality(cwd, cmd) {
+  // Check if the tool referenced in the command actually exists
+  const toolChecks = [
+    { pattern: /^npx\s+(\w+)/, check: (tool) => hasNpmDep(cwd, tool) || hasNpmBin(cwd, tool) },
+    { pattern: /^npm\s+run\s+(\w+)/, check: (script) => hasNpmScript(cwd, script) },
+    { pattern: /^node\s+--check\s+(.+)/, check: (file) => fs.existsSync(path.join(cwd, file.trim())) },
+    { pattern: /^node\s+(\S+)/, check: (file) => fs.existsSync(path.join(cwd, file.trim())) },
+    { pattern: /^cargo\s+/, check: () => fs.existsSync(path.join(cwd, 'Cargo.toml')) },
+    { pattern: /^go\s+/, check: () => fs.existsSync(path.join(cwd, 'go.mod')) },
+    { pattern: /^(\.\/)?gradlew\s+/, check: () => fs.existsSync(path.join(cwd, 'gradlew')) || fs.existsSync(path.join(cwd, 'gradlew.bat')) },
+    { pattern: /^pytest/, check: () => fs.existsSync(path.join(cwd, 'pyproject.toml')) || fs.existsSync(path.join(cwd, 'setup.py')) },
+    { pattern: /^ruff\s+/, check: () => fs.existsSync(path.join(cwd, 'ruff.toml')) || fs.existsSync(path.join(cwd, '.ruff.toml')) || fs.existsSync(path.join(cwd, 'pyproject.toml')) },
+    { pattern: /^docker\s+/, check: () => fs.existsSync(path.join(cwd, 'Dockerfile')) || fs.existsSync(path.join(cwd, 'docker-compose.yml')) },
+  ];
+
+  // Verify commands
+  const verifyMatch = cmd.match(/^Verify\s+(\S+)\s+contains\s+/i);
+  if (verifyMatch) {
+    const file = verifyMatch[1];
+    if (!fs.existsSync(path.join(cwd, file))) {
+      return { status: 'missing', detail: `File ${file} does not exist` };
+    }
+    return { status: 'match', detail: null };
+  }
+
+  for (const { pattern, check } of toolChecks) {
+    const m = cmd.match(pattern);
+    if (m) {
+      if (check(m[1])) return { status: 'match', detail: null };
+      return { status: 'drift', detail: `Tool or dependency not found for: ${cmd}` };
+    }
+  }
+
+  // Unknown command — assume match (can't verify)
+  return { status: 'match', detail: null };
+}
+
+function checkBranchStrategy(cwd, content, results) {
+  const govStrategy = content.includes('Feature branches') || content.includes('feature branches')
+    ? 'feature-branches' : content.includes('Trunk-based') || content.includes('trunk-based')
+    ? 'trunk-based' : null;
+
+  if (!govStrategy) return;
+
+  try {
+    const branches = execSync('git branch -a --format="%(refname:short)"', { cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+    const list = branches.trim().split('\n');
+    const featureBranches = list.filter(b => /^(feat|fix|docs|chore|feature|hotfix)\//.test(b));
+    const actual = featureBranches.length > 2 ? 'feature-branches' : 'trunk-based';
+
+    if (actual !== govStrategy) {
+      console.log(`  \x1b[33mDRIFT\x1b[0m   Branch strategy: governance says ${govStrategy}, git shows ${actual}`);
+      results.drift++;
+    } else {
+      results.match++;
+    }
+  } catch { /* skip */ }
+}
+
+function checkCommitConvention(cwd, content, results) {
+  const govConvention = content.includes('Conventional commits') || content.includes('conventional commits')
+    ? 'conventional' : content.includes('Free-form') || content.includes('free-form')
+    ? 'free-form' : null;
+
+  if (!govConvention) return;
+
+  try {
+    const log = execSync('git log --oneline -20', { cwd, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] });
+    const lines = log.trim().split('\n');
+    const conventional = lines.filter(l => /\b(feat|fix|docs|chore|style|refactor|test|build|ci|perf|revert)[\(:!]/.test(l));
+    const actual = conventional.length > lines.length * 0.3 ? 'conventional' : 'free-form';
+
+    if (actual !== govConvention) {
+      console.log(`  \x1b[33mDRIFT\x1b[0m   Commit convention: governance says ${govConvention}, git shows ${actual}`);
+      results.drift++;
+    } else {
+      results.match++;
+    }
+  } catch { /* skip */ }
+}
+
+function extractCIGateCommands(cwd) {
+  const gates = [];
+  const workflowDir = path.join(cwd, '.github', 'workflows');
+  if (!fs.existsSync(workflowDir)) return gates;
+
+  try {
+    // Walk recursively to catch nested workflow files
+    const walk = (d) => {
+      const out = [];
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory()) out.push(...walk(full));
+        else if (entry.name.endsWith('.yml') || entry.name.endsWith('.yaml')) out.push(full);
+      }
+      return out;
+    };
+
+    for (const file of walk(workflowDir)) {
+      const content = fs.readFileSync(file, 'utf-8');
+      for (const cmd of extractRunCommands(content)) {
+        if (isGateCommand(cmd)) gates.push(cmd);
+      }
+    }
+  } catch { /* skip */ }
+
+  return gates;
+}
+
+/**
+ * Extract commands from YAML `run:` steps, handling block scalars.
+ */
+function extractRunCommands(content) {
+  const commands = [];
+  const lines = content.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = line.match(/^(\s*)-?\s*run:\s*(.*)$/);
+    if (!m) continue;
+
+    const baseIndent = m[1].length;
+    const rest = m[2].trim();
+
+    if (/^[|>][+-]?\s*$/.test(rest)) {
+      // Block scalar
+      for (let j = i + 1; j < lines.length; j++) {
+        const ln = lines[j];
+        if (ln.trim() === '') continue;
+        const indentMatch = ln.match(/^(\s*)/);
+        if (indentMatch[1].length <= baseIndent) break;
+        const trimmed = ln.trim();
+        if (trimmed && !trimmed.startsWith('#')) commands.push(trimmed);
+      }
+    } else if (rest && !rest.startsWith('#')) {
+      commands.push(rest.replace(/^["']|["']$/g, ''));
+    }
+  }
+
+  return commands;
+}
+
+function isGateCommand(cmd) {
+  const patterns = [
+    /npm (run|test|ci)/, /npx /, /node /, /cargo /, /go (test|build|vet)/,
+    /pytest/, /ruff/, /mypy/, /eslint/, /biome/, /prettier/, /tsc/, /gradle/,
+  ];
+  return patterns.some(p => p.test(cmd));
+}
+
+/**
+ * Normalize commands to a canonical form for equality comparison.
+ * Handles common aliases:
+ *   - `npm test` ⇔ `npm run test`
+ *   - `npm start` ⇔ `npm run start`
+ *   - `./gradlew x` ⇔ `gradlew x`
+ *   - `./mvnw x` ⇔ `mvnw x`
+ *   - quoted arguments ⇔ unquoted (lexical equality only for simple cases)
+ */
+function normalizeCmd(cmd) {
+  let c = String(cmd).replace(/\s+/g, ' ').trim().toLowerCase();
+
+  // npm lifecycle aliases: `npm <script>` → `npm run <script>` (except reserved verbs)
+  const npmReserved = new Set([
+    'test', 'start', 'stop', 'restart', 'install', 'uninstall', 'ci', 'publish',
+    'pack', 'audit', 'ls', 'list', 'run', 'exec', 'init', 'update', 'outdated',
+    'version', 'view', 'whoami', 'login', 'logout', 'link', 'unlink', 'config',
+    'cache', 'prune', 'dedupe', 'rebuild', 'shrinkwrap', 'help',
+  ]);
+  const npmMatch = c.match(/^npm\s+(\S+)(\s+.*)?$/);
+  if (npmMatch && (npmMatch[1] === 'test' || npmMatch[1] === 'start' || npmMatch[1] === 'stop' || npmMatch[1] === 'restart')) {
+    // npm test == npm run test
+    c = `npm run ${npmMatch[1]}${npmMatch[2] || ''}`;
+  }
+
+  // gradlew aliases: ./gradlew == gradlew
+  c = c.replace(/^\.\/gradlew/, 'gradlew');
+  c = c.replace(/^\.\/mvnw/, 'mvnw');
+  c = c.replace(/^\.\/(\S+)/, '$1'); // any other ./x
+
+  return c;
+}
+
+// Memoize package.json reads per cwd — diff runs many checks per call.
+const _pkgCache = new Map();
+function getPkg(cwd) {
+  if (_pkgCache.has(cwd)) return _pkgCache.get(cwd);
+  let pkg = null;
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf-8'));
+  } catch { /* missing or malformed */ }
+  _pkgCache.set(cwd, pkg);
+  return pkg;
+}
+
+// Memoize bin directory entries per cwd.
+const _binCache = new Map();
+function getBins(cwd) {
+  if (_binCache.has(cwd)) return _binCache.get(cwd);
+  const binDir = path.join(cwd, 'node_modules', '.bin');
+  let set;
+  try {
+    set = new Set(fs.readdirSync(binDir));
+  } catch {
+    set = new Set();
+  }
+  _binCache.set(cwd, set);
+  return set;
+}
+
+function hasNpmDep(cwd, dep) {
+  const pkg = getPkg(cwd);
+  if (!pkg) return false;
+  return !!(pkg.dependencies?.[dep] || pkg.devDependencies?.[dep] || pkg.peerDependencies?.[dep] || pkg.optionalDependencies?.[dep]);
+}
+
+function hasNpmBin(cwd, bin) {
+  const bins = getBins(cwd);
+  return bins.has(bin) || bins.has(bin + '.cmd') || bins.has(bin + '.exe');
+}
+
+function hasNpmScript(cwd, script) {
+  const pkg = getPkg(cwd);
+  return !!(pkg && pkg.scripts?.[script]);
+}
+
+module.exports = { diff, normalizeCmd, extractRunCommands, isGateCommand };

package/src/commands/init.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const { execSync, spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SRC = path.join(__dirname, '..');
+const AGENT_SRC = path.join(SRC, 'crag-agent.md');
+const PRE_START_SRC = path.join(SRC, 'skills', 'pre-start-context.md');
+const POST_START_SRC = path.join(SRC, 'skills', 'post-start-validation.md');
+const GLOBAL_AGENT_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'agents');
+const GLOBAL_AGENT_PATH = path.join(GLOBAL_AGENT_DIR, 'crag-project.md');
+
+function install() {
+  if (!fs.existsSync(GLOBAL_AGENT_DIR)) {
+    fs.mkdirSync(GLOBAL_AGENT_DIR, { recursive: true });
+  }
+  fs.copyFileSync(AGENT_SRC, GLOBAL_AGENT_PATH);
+  console.log(`  Installed crag-project agent to ${GLOBAL_AGENT_PATH}`);
+  console.log(`  Run /crag-project from any Claude Code session.`);
+}
+
+function installSkills(targetDir) {
+  const skillDirs = [
+    path.join(targetDir, '.claude', 'skills', 'pre-start-context'),
+    path.join(targetDir, '.claude', 'skills', 'post-start-validation'),
+    path.join(targetDir, '.agents', 'workflows'),
+  ];
+
+  for (const dir of skillDirs) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Copy skills
+  fs.copyFileSync(PRE_START_SRC, path.join(targetDir, '.claude', 'skills', 'pre-start-context', 'SKILL.md'));
+  fs.copyFileSync(POST_START_SRC, path.join(targetDir, '.claude', 'skills', 'post-start-validation', 'SKILL.md'));
+
+  // Workflow copies (remove name: line)
+  for (const [src, name] of [[PRE_START_SRC, 'pre-start-context.md'], [POST_START_SRC, 'post-start-validation.md']]) {
+    const content = fs.readFileSync(src, 'utf-8').replace(/^name:.*\n/m, '');
+    fs.writeFileSync(path.join(targetDir, '.agents', 'workflows', name), content);
+  }
+
+  console.log(`  Installed universal skills to ${targetDir}`);
+}
+
+function init() {
+  const cwd = process.cwd();
+
+  // Pre-flight: check claude CLI
+  try {
+    execSync('claude --version', { stdio: 'ignore', timeout: 5000 });
+  } catch {
+    console.error('  Error: Claude Code CLI not found (or did not respond in 5s).');
+    console.error('  Install: https://claude.com/claude-code');
+    process.exit(1);
+  }
+
+  // Pre-flight: warn if not a git repo (non-blocking, just informative)
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.warn('  \x1b[33m!\x1b[0m Warning: not a git repository.');
+    console.warn('    crag works best in git repos (branch inference, commit conventions,');
+    console.warn('    discovery cache keyed by commit hash). Run: git init');
+  }
+
+  // Pre-flight: warn if existing governance.md would be overwritten by interview
+  const existingGov = path.join(cwd, '.claude', 'governance.md');
+  if (fs.existsSync(existingGov)) {
+    console.warn('  \x1b[33m!\x1b[0m Warning: .claude/governance.md already exists.');
+    console.warn('    The interview will suggest changes; review before saving.');
+    console.warn('    To update skills only without interview, use: crag upgrade');
+  }
+
+  // Install universal skills first
+  console.log(`\n  Installing universal skills...`);
+  installSkills(cwd);
+
+  // Install agent globally if needed
+  if (!fs.existsSync(GLOBAL_AGENT_PATH)) {
+    install();
+  }
+
+  console.log(`\n  Starting crag interview...\n`);
+  console.log(`  Claude Code will ask about your project.`);
+  console.log(`  It generates: governance.md, hooks, agents, settings.`);
+  console.log(`  The universal skills are already installed.\n`);
+  console.log(`  >>> Type "go" and press Enter to start the interview <<<\n`);
+
+  const claude = spawn('claude', ['--agent', 'crag-project'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  claude.on('error', (err) => {
+    console.error(`\n  Error launching claude: ${err.message}`);
+    process.exit(1);
+  });
+
+  claude.on('exit', (code, signal) => {
+    if (code === 0) {
+      console.log(`\n  crag setup complete. Run 'crag check' to verify.`);
+    } else if (signal) {
+      console.error(`\n  Interview terminated by signal: ${signal}`);
+      process.exit(1);
+    } else if (code !== null) {
+      console.error(`\n  Interview exited with code ${code}`);
+      process.exit(code);
+    }
+  });
+}
+
+module.exports = { init, install, installSkills };

package/src/commands/upgrade.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const path = require('path');
+const { syncSkills } = require('../update/skill-sync');
+const { detectWorkspace } = require('../workspace/detect');
+const { enumerateMembers } = require('../workspace/enumerate');
+
+/**
+ * crag upgrade — update universal skills to latest version.
+ */
+function upgrade(args) {
+  const checkOnly = args.includes('--check');
+  const workspace = args.includes('--workspace');
+  const force = args.includes('--force');
+  const cwd = process.cwd();
+
+  console.log(`\n  crag upgrade${checkOnly ? ' --check' : ''}${force ? ' --force' : ''}\n`);
+
+  // Upgrade current project
+  const result = syncSkills(cwd, { force, dryRun: checkOnly });
+  printResult(cwd, result, checkOnly);
+
+  // Upgrade workspace members if requested
+  if (workspace) {
+    const ws = detectWorkspace(cwd);
+    if (ws.type !== 'none') {
+      const members = enumerateMembers(ws);
+      console.log(`\n  Workspace: ${ws.type} (${members.length} members)\n`);
+
+      for (const member of members) {
+        if (member.hasClaude) {
+          const memberResult = syncSkills(member.path, { force, dryRun: checkOnly });
+          printResult(member.path, memberResult, checkOnly);
+        }
+      }
+    } else {
+      console.log('  No workspace detected.\n');
+    }
+  }
+}
+
+function printResult(dir, result, checkOnly) {
+  const label = path.basename(dir);
+  const prefix = checkOnly ? '(dry run) ' : '';
+
+  for (const item of result.updated) {
+    console.log(`  \x1b[32m✓\x1b[0m ${prefix}${label}/${item.name}: ${item.from} → ${item.to}`);
+  }
+
+  for (const item of result.skipped) {
+    console.log(`  \x1b[90m○\x1b[0m ${label}/${item.name}: ${item.version} (${item.reason})`);
+  }
+
+  for (const item of result.conflicted) {
+    console.log(`  \x1b[33m!\x1b[0m ${label}/${item.name}: ${item.installed} → ${item.available} (${item.reason})`);
+    console.log(`      Run with --force to overwrite (backup will be created)`);
+  }
+
+  if (result.updated.length === 0 && result.conflicted.length === 0) {
+    console.log(`  \x1b[32m✓\x1b[0m ${label}: all skills current`);
+  }
+}
+
+module.exports = { upgrade };