@cuewright/skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Criswell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @cuewright/skills
+
+CLI installer for the [Cuewright skills framework](https://github.com/scriswell/cuewright).
+
+Install the framework into any project in one command — no manual submodule wiring, no shell loops, no symlink errors on Windows.
+
+> **Pre-public note:** While the framework repo is private, `cuewright init` requires GitHub credentials (SSH key or GitHub token). Anyone with read access to `scriswell/cuewright` can use the CLI today.
+
+## Quick start
+
+```bash
+npx @cuewright/skills init
+```
+
+Then follow with `/align-project-skills` in Claude Code to complete setup.
+
+## Commands
+
+### `cuewright init`
+
+Installs the Cuewright framework into the current project.
+
+```bash
+npx @cuewright/skills init [options]
+```
+
+**What it does:**
+1. Clones the framework as a git submodule at `.claude/skills/_framework/`
+2. Creates skill symlinks at `.claude/skills/<name>/` for each skill in the manifest
+3. Scaffolds `arch/project-config.md` from the framework template
+4. Creates `arch/fragments/project/`
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--tag <version>` | Pin to a specific framework version (default: latest) |
+| `--no-submodule` | Clone as a plain directory instead of a git submodule |
+| `--copy` | Force copy mode — creates file copies instead of symlinks (auto-enabled on Windows) |
+| `--symlink` | Force symlink mode — exits with an error on Windows if symlinks are unavailable |
+
+**Existing project adoption:**
+If `.claude/skills/_framework/manifest.json` already exists (manual install), `init` adopts the installation without re-cloning. It syncs any missing symlinks and scaffolds the config if absent.
+
+---
+
+### `cuewright update`
+
+Updates the framework to the latest version (or a specified version).
+
+```bash
+npx @cuewright/skills update [options]
+```
+
+**What it does:**
+- Bumps the submodule pointer (or replaces the directory in copy mode)
+- Detects added/removed skills and syncs wiring accordingly
+- Warns if a removed skill has a local override directory
+- Prints the changelog for the updated version range
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--to <version>` | Target version (default: latest) |
+| `--dry-run` | Show what would change without making changes |
+
+Works on projects installed manually — detects existing installations and adopts them.
+
+---
+
+### `cuewright doctor`
+
+Verifies the installation is healthy.
+
+```bash
+npx @cuewright/skills doctor
+```
+
+**Example output:**
+```
+✓ Framework installed at v0.14.33
+✓ 25/25 skills wired
+✓ arch/project-config.md found
+✓ Target lit-browser found
+```
+
+Exits 0 if all checks pass, 1 if any fail. Each failure includes a fix suggestion.
+
+---
+
+### `cuewright status`
+
+Shows a snapshot of the current installation.
+
+```bash
+npx @cuewright/skills status [--json]
+```
+
+**Example output:**
+```
+Cuewright v0.14.33
+Target:     lit-browser
+Skills:     25 total · 2 overridden · 0 from baseline
+
+Governance:
+  CSS             Enforcement
+  Accessibility   Remediation
+  Security        Discovery
+```
+
+`--json` outputs machine-readable JSON for scripting.
+
+---
+
+## Windows support
+
+On Windows, directory symlinks require Developer Mode or admin privileges. The CLI detects this automatically and uses copy mode instead. Copied `SKILL.md` files include a header marking them as auto-generated so `update` knows which files to refresh.
+
+To force copy mode on any platform: `--copy`.
+
+## Manual installation
+
+Teams that cannot use Node.js can still install the framework manually. See the [Cuewright adoption guide](https://github.com/scriswell/cuewright/blob/main/docs/adoption-guide.md#manual-installation) for the shell commands.
+
+## License
+
+MIT

package/bin/cuewright.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+program
+  .name('cuewright')
+  .description('CLI installer for the Cuewright skills framework')
+  .version(version);
+
+program
+  .command('init')
+  .description('Install the Cuewright framework into this project')
+  .option('--tag <version>', 'pin to a specific framework version (default: latest)')
+  .option('--no-submodule', 'copy framework content instead of adding a git submodule')
+  .option('--copy', 'force copy mode (auto-enabled on Windows)')
+  .option('--symlink', 'force symlink mode (may fail on Windows without developer mode)')
+  .option('--model <models>', 'AI model adapter(s) to wire (default: claude)', 'claude')
+  .action(async (options) => {
+    const { init } = await import('../src/commands/init.js');
+    await init(options);
+  });
+
+program
+  .command('update')
+  .description('Update the framework to the latest or a specified version')
+  .option('--to <version>', 'target version (default: latest)')
+  .option('--dry-run', 'show what would change without making changes')
+  .action(async (options) => {
+    const { update } = await import('../src/commands/update.js');
+    await update(options);
+  });
+
+program
+  .command('doctor')
+  .description('Verify the framework installation is healthy')
+  .action(async () => {
+    const { doctor } = await import('../src/commands/doctor.js');
+    await doctor();
+  });
+
+program
+  .command('status')
+  .description('Show installed version, skill count, and active target')
+  .option('--json', 'output as JSON')
+  .action(async (options) => {
+    const { status } = await import('../src/commands/status.js');
+    await status(options);
+  });
+
+program
+  .command('add-baseline')
+  .description('Wire a team baseline as a second submodule')
+  .argument('<repo-url>', 'URL of the baseline repository')
+  .action(async (repoUrl) => {
+    const { addBaseline } = await import('../src/commands/add-baseline.js');
+    await addBaseline(repoUrl);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cuewright/skills",
+  "version": "0.1.0",
+  "description": "CLI installer for the Cuewright skills framework",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "cuewright": "bin/cuewright.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "simple-git": "^3.22.0"
+  },
+  "devDependencies": {
+    "execa": "^9.6.1",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "cuewright",
+    "claude",
+    "skills",
+    "ai",
+    "governance"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scriswell/cuewright-cli.git"
+  },
+  "homepage": "https://github.com/scriswell/cuewright-cli#readme"
+}

package/src/adapters/claude.js

@@ -0,0 +1,23 @@
+import { join } from 'path';
+
+/**
+ * Return the Claude Code skills discovery directory for a project.
+ * Claude Code discovers skills at: <projectRoot>/.claude/skills/<name>/SKILL.md
+ */
+export function getSkillsDir(projectRoot) {
+  return join(projectRoot, '.claude', 'skills');
+}
+
+/**
+ * Return the framework installation path for a project.
+ */
+export function getFrameworkDir(projectRoot) {
+  return join(projectRoot, '.claude', 'skills', '_framework');
+}
+
+/**
+ * Return the submodule path (relative to project root) used when adding the submodule.
+ */
+export function getSubmodulePath() {
+  return '.claude/skills/_framework';
+}

package/src/commands/add-baseline.js

@@ -0,0 +1,5 @@
+// Issue (Phase 2): add-baseline command
+
+export async function addBaseline(repoUrl) {
+  throw new Error('add-baseline command not yet implemented');
+}

package/src/commands/doctor.js

@@ -0,0 +1,225 @@
+import chalk from 'chalk';
+import { access, readFile, lstat } from 'fs/promises';
+import { join } from 'path';
+import { cwd } from 'process';
+import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
+
+export async function doctor() {
+  const projectRoot = cwd();
+  const frameworkDir = getFrameworkDir(projectRoot);
+  const skillsDir = getSkillsDir(projectRoot);
+
+  let allPassed = true;
+  const checks = [];
+
+  // 1. Framework directory exists
+  if (!await exists(frameworkDir)) {
+    checks.push(fail('Framework not found at .claude/skills/_framework/', 'Run `cuewright init` to install it.'));
+    allPassed = false;
+    printChecks(checks);
+    process.exit(1);
+  }
+
+  // 2. manifest.json exists and is valid JSON
+  let manifest;
+  try {
+    manifest = await readManifest(frameworkDir);
+    checks.push(pass(`Framework installed at v${getVersion(manifest)}`));
+  } catch (err) {
+    checks.push(fail('manifest.json missing or invalid', `Check .claude/skills/_framework/manifest.json — ${err.message}`));
+    allPassed = false;
+    printChecks(checks);
+    process.exit(1);
+  }
+
+  // 3 & 4. Each skill wired and symlink targets valid
+  const skills = listSkills(manifest);
+  let wiredCount = 0;
+  const brokenLinks = [];
+
+  for (const name of skills) {
+    const skillPath = join(skillsDir, name);
+    if (!await exists(skillPath)) {
+      brokenLinks.push({ name, reason: 'missing' });
+    } else {
+      try {
+        const stat = await lstat(skillPath);
+        if (stat.isSymbolicLink()) {
+          // Check the symlink target is valid
+          try {
+            await access(skillPath);
+            wiredCount++;
+          } catch {
+            brokenLinks.push({ name, reason: 'broken symlink' });
+          }
+        } else {
+          wiredCount++; // real directory override — counts as wired
+        }
+      } catch {
+        brokenLinks.push({ name, reason: 'stat error' });
+      }
+    }
+  }
+
+  if (brokenLinks.length === 0) {
+    checks.push(pass(`${wiredCount}/${skills.length} skills wired`));
+  } else {
+    allPassed = false;
+    checks.push(fail(
+      `${wiredCount}/${skills.length} skills wired (${brokenLinks.length} broken)`,
+      'Run `cuewright update` to repair broken symlinks.'
+    ));
+    for (const { name, reason } of brokenLinks) {
+      checks.push(fail(`  ${name}: ${reason}`, null));
+    }
+  }
+
+  // 5. arch/project-config.md exists
+  const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
+  if (!await exists(configPath)) {
+    allPassed = false;
+    checks.push(fail(
+      'arch/project-config.md not found',
+      'Run `cuewright init` to scaffold it, or create it manually from _framework/targets/_template/project-config-template.md.'
+    ));
+  } else {
+    checks.push(pass('arch/project-config.md found'));
+
+    // 6. Target named in project-config exists
+    const targetName = await extractTargetName(configPath);
+    if (targetName) {
+      const targetDir = join(frameworkDir, 'targets', targetName);
+      const projectTargetDir = join(projectRoot, '.claude', 'skills', 'arch', 'targets', targetName);
+
+      if (await exists(targetDir) || await exists(projectTargetDir)) {
+        checks.push(pass(`Target ${targetName} found`));
+      } else {
+        allPassed = false;
+        const availableTargets = await listAvailableTargets(frameworkDir);
+        checks.push(fail(
+          `Target '${targetName}' not found`,
+          `Update arch/project-config.md with a valid target. Available: ${availableTargets.join(', ')}`
+        ));
+      }
+    } else {
+      checks.push(warn('Could not read target name from arch/project-config.md'));
+    }
+  }
+
+  // 7. Baseline compatibility check (if baseline present)
+  const baselineDir = join(projectRoot, '.claude', 'skills', '_baseline');
+  if (await exists(baselineDir)) {
+    const baselineJsonPath = join(baselineDir, 'baseline.json');
+    if (!await exists(baselineJsonPath)) {
+      allPassed = false;
+      checks.push(fail('_baseline/baseline.json not found', 'The baseline directory is present but missing its manifest.'));
+    } else {
+      try {
+        const baselineJson = JSON.parse(await readFile(baselineJsonPath, 'utf8'));
+        const compat = baselineJson.framework_compatibility;
+        const current = getVersion(manifest);
+        if (compat && !isCompatible(compat, current)) {
+          allPassed = false;
+          checks.push(fail(
+            `Baseline requires framework ${compat}, installed: v${current}`,
+            'Update the framework (`cuewright update`) or update your baseline.'
+          ));
+        } else {
+          checks.push(pass('Baseline compatible'));
+        }
+      } catch {
+        checks.push(warn('Could not parse _baseline/baseline.json'));
+      }
+    }
+  }
+
+  printChecks(checks);
+  process.exit(allPassed ? 0 : 1);
+}
+
+function pass(message) {
+  return { ok: true, message };
+}
+
+function fail(message, fix) {
+  return { ok: false, message, fix };
+}
+
+function warn(message) {
+  return { ok: null, message };
+}
+
+function printChecks(checks) {
+  for (const check of checks) {
+    if (check.ok === true) {
+      console.log(chalk.green('✓') + ' ' + check.message);
+    } else if (check.ok === false) {
+      console.log(chalk.red('✗') + ' ' + check.message);
+      if (check.fix) {
+        console.log('  ' + chalk.dim(check.fix));
+      }
+    } else {
+      console.log(chalk.yellow('?') + ' ' + check.message);
+    }
+  }
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse the target name from the Stack table in project-config.md.
+ * Looks for a line like: | Target | lit-browser |
+ */
+async function extractTargetName(configPath) {
+  try {
+    const content = await readFile(configPath, 'utf8');
+    const match = content.match(/^\|\s*Target\s*\|\s*([a-z0-9-]+)\s*\|/m);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List target names from _framework/targets/ (excluding _template).
+ */
+async function listAvailableTargets(frameworkDir) {
+  const { readdir } = await import('fs/promises');
+  try {
+    const entries = await readdir(join(frameworkDir, 'targets'));
+    return entries.filter(e => !e.startsWith('_'));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Very simple semver compatibility check.
+ * compat is a string like ">=0.14.0" or "0.14.x".
+ * Returns true if current satisfies the constraint.
+ */
+function isCompatible(compat, current) {
+  const gteMatch = compat.match(/^>=(\d+\.\d+\.\d+)/);
+  if (gteMatch) {
+    return !isOlder(current, gteMatch[1]);
+  }
+  // Treat as exact prefix match (e.g. "0.14.x")
+  const prefix = compat.replace(/\.x$/, '');
+  return current.startsWith(prefix);
+}
+
+function isOlder(a, b) {
+  const [aMaj, aMin, aPat] = a.split('.').map(Number);
+  const [bMaj, bMin, bPat] = b.split('.').map(Number);
+  if (aMaj !== bMaj) return aMaj < bMaj;
+  if (aMin !== bMin) return aMin < bMin;
+  return aPat < bPat;
+}

package/src/commands/init.js

@@ -0,0 +1,147 @@
+import chalk from 'chalk';
+import { access, mkdir, copyFile } from 'fs/promises';
+import { join } from 'path';
+import { cwd } from 'process';
+import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { syncSymlinks, syncCopies, platformSupportsSymlinks } from '../utils/symlink.js';
+import { addSubmodule } from '../storage/submodule.js';
+import { cloneFramework } from '../storage/copy.js';
+import { getSkillsDir, getFrameworkDir, getSubmodulePath } from '../adapters/claude.js';
+
+export async function init(options) {
+  const projectRoot = cwd();
+  const frameworkDir = getFrameworkDir(projectRoot);
+  const skillsDir = getSkillsDir(projectRoot);
+
+  // Resolve copy vs symlink mode
+  if (options.symlink && !platformSupportsSymlinks()) {
+    console.error(chalk.red('Error: symlink mode is not supported on this platform.'));
+    console.error('Windows requires Developer Mode or admin privileges for directory symlinks.');
+    console.error('Enable Developer Mode in Settings → Privacy & Security → Developer Mode,');
+    console.error('or run without --symlink to use copy mode instead.');
+    process.exit(1);
+  }
+
+  // Detect existing installation
+  const alreadyInstalled = await exists(join(frameworkDir, 'manifest.json'));
+
+  if (alreadyInstalled) {
+    await adoptExisting(projectRoot, frameworkDir, skillsDir, options);
+  } else {
+    await freshInstall(projectRoot, frameworkDir, skillsDir, options);
+  }
+}
+
+/**
+ * Existing project adoption path.
+ * Framework is already present (manually installed or prior CLI run).
+ * Sync any missing symlinks and scaffold config if absent.
+ */
+async function adoptExisting(projectRoot, frameworkDir, skillsDir, options) {
+  const manifest = await readManifest(frameworkDir);
+  const version = getVersion(manifest);
+  const skills = listSkills(manifest);
+  const useCopies = resolveCopyMode(options);
+
+  console.log(chalk.cyan(`Found existing framework installation: v${version}`));
+  console.log(`Syncing skill ${useCopies ? 'copies' : 'symlinks'}...`);
+
+  const { wired, skipped, errors } = useCopies
+    ? await syncCopies(frameworkDir, skillsDir, skills, version)
+    : await syncSymlinks(frameworkDir, skillsDir, skills);
+
+  if (errors.length) {
+    for (const e of errors) console.log(chalk.yellow(`  warning: ${e}`));
+  }
+
+  console.log(chalk.green(`  ${wired.length} new symlink(s) created`) + (wired.length ? ': ' + wired.join(', ') : ''));
+  console.log(`  ${skipped.length} skill(s) already wired or overridden`);
+
+  await scaffoldConfigIfMissing(projectRoot, frameworkDir);
+
+  console.log(chalk.green('\nDone. Framework adopted.'));
+}
+
+/**
+ * Fresh install path.
+ * Clones or adds the framework, wires symlinks, scaffolds config.
+ */
+async function freshInstall(projectRoot, frameworkDir, skillsDir, options) {
+  const useSubmodule = options.submodule !== false && !options.copy;
+  const useCopies = resolveCopyMode(options);
+  const tag = options.tag || null;
+
+  console.log(chalk.cyan(`Installing Cuewright framework${tag ? ` @ ${tag}` : ' (latest)'}...`));
+
+  if (useSubmodule) {
+    console.log('Adding git submodule...');
+    await addSubmodule(projectRoot, getSubmodulePath(), tag);
+  } else {
+    console.log('Cloning framework (copy mode)...');
+    await cloneFramework(frameworkDir, tag);
+  }
+
+  const manifest = await readManifest(frameworkDir);
+  const version = getVersion(manifest);
+  const skills = listSkills(manifest);
+
+  console.log(`Framework v${version} installed. Wiring ${skills.length} skills...`);
+
+  const { wired, skipped, errors } = useCopies
+    ? await syncCopies(frameworkDir, skillsDir, skills, version)
+    : await syncSymlinks(frameworkDir, skillsDir, skills);
+
+  if (errors.length) {
+    for (const e of errors) console.log(chalk.yellow(`  warning: ${e}`));
+  }
+
+  await scaffoldConfigIfMissing(projectRoot, frameworkDir);
+
+  console.log(chalk.green(`\nDone.`));
+  console.log(`  Framework:  v${version}`);
+  console.log(`  Skills wired: ${wired.length}`);
+  console.log(`  Config:     .claude/skills/arch/project-config.md`);
+  console.log('');
+  console.log('Next: edit project-config.md to set your target, then run /align-project-skills');
+}
+
+/**
+ * Scaffold arch/project-config.md from the framework template if it does not yet exist.
+ */
+async function scaffoldConfigIfMissing(projectRoot, frameworkDir) {
+  const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
+  const configExists = await exists(configPath);
+
+  if (configExists) {
+    console.log('  project-config.md already exists — skipping scaffold');
+    return;
+  }
+
+  const templatePath = join(frameworkDir, 'targets', '_template', 'project-config-template.md');
+  const fragmentsDir = join(projectRoot, '.claude', 'skills', 'arch', 'fragments', 'project');
+
+  await mkdir(join(projectRoot, '.claude', 'skills', 'arch'), { recursive: true });
+  await mkdir(fragmentsDir, { recursive: true });
+  await copyFile(templatePath, configPath);
+
+  console.log('  Scaffolded arch/project-config.md');
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determine whether to use file copies instead of symlinks.
+ * True when: --copy flag set, OR on Windows and --symlink not forced.
+ */
+function resolveCopyMode(options) {
+  if (options.copy) return true;
+  if (options.symlink) return false;
+  return !platformSupportsSymlinks();
+}

package/src/commands/status.js

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import { access, readFile, lstat, readdir } from 'fs/promises';
+import { join } from 'path';
+import { cwd } from 'process';
+import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
+
+export async function status(options = {}) {
+  const projectRoot = cwd();
+  const frameworkDir = getFrameworkDir(projectRoot);
+  const skillsDir = getSkillsDir(projectRoot);
+
+  // Framework must be installed
+  if (!await exists(join(frameworkDir, 'manifest.json'))) {
+    console.error(chalk.red('Framework not installed. Run `cuewright init` first.'));
+    process.exit(1);
+  }
+
+  const manifest = await readManifest(frameworkDir);
+  const version = getVersion(manifest);
+  const skills = listSkills(manifest);
+
+  // Count overridden and baseline skills
+  let overridden = 0;
+  let fromBaseline = 0;
+  const baselineDir = join(projectRoot, '.claude', 'skills', '_baseline');
+  const hasBaseline = await exists(baselineDir);
+
+  for (const name of skills) {
+    const skillPath = join(skillsDir, name);
+    try {
+      const stat = await lstat(skillPath);
+      if (stat.isSymbolicLink()) {
+        if (hasBaseline) {
+          // Check if symlink points into _baseline
+          const { readlink } = await import('fs/promises');
+          const target = await readlink(skillPath);
+          if (target.includes('_baseline')) fromBaseline++;
+        }
+      } else if (stat.isDirectory()) {
+        overridden++;
+      }
+    } catch {
+      // Skill not wired — not counted
+    }
+  }
+
+  // Read project-config for target and governance
+  const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
+  const configExists = await exists(configPath);
+  let targetName = null;
+  let governanceRows = [];
+
+  if (configExists) {
+    const content = await readFile(configPath, 'utf8');
+    targetName = extractTargetName(content);
+    governanceRows = extractGovernanceTable(content);
+  }
+
+  if (options.json) {
+    const output = {
+      version,
+      target: targetName,
+      skills: {
+        total: skills.length,
+        overridden,
+        fromBaseline,
+      },
+      governance: governanceRows,
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  console.log(chalk.bold(`Cuewright v${version}`));
+  console.log(`Target:     ${targetName || chalk.dim('(not configured)')}`);
+  console.log(`Skills:     ${skills.length} total · ${overridden} overridden · ${fromBaseline} from baseline`);
+
+  if (governanceRows.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Governance:'));
+    const maxLen = Math.max(...governanceRows.map(r => r.concern.length));
+    for (const { concern, stage } of governanceRows) {
+      const stageColor = stage === 'Enforcement' ? chalk.green
+        : stage === 'Remediation' ? chalk.yellow
+        : chalk.dim;
+      console.log(`  ${concern.padEnd(maxLen + 2)}${stageColor(stage)}`);
+    }
+  } else if (!configExists) {
+    console.log('');
+    console.log(chalk.dim('No project-config.md found. Run `cuewright init` to scaffold it.'));
+  }
+}
+
+/**
+ * Extract target name from project-config.md Stack table.
+ */
+function extractTargetName(content) {
+  const match = content.match(/^\|\s*Target\s*\|\s*([a-z0-9-]+)\s*\|/m);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract governance stage rows from project-config.md.
+ * Looks for a table with columns like | Concern | Stage |
+ */
+function extractGovernanceTable(content) {
+  const rows = [];
+  const lines = content.split('\n');
+  let inGovernance = false;
+
+  for (const line of lines) {
+    if (/governance/i.test(line) && line.startsWith('#')) {
+      inGovernance = true;
+      continue;
+    }
+    if (inGovernance && line.startsWith('#')) {
+      inGovernance = false;
+    }
+    if (inGovernance) {
+      const match = line.match(/^\|\s*([A-Za-z ]+\S)\s*\|\s*(Discovery|Remediation|Enforcement)\s*\|/);
+      if (match) {
+        rows.push({ concern: match[1].trim(), stage: match[2].trim() });
+      }
+    }
+  }
+
+  return rows;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/commands/update.js

@@ -0,0 +1,187 @@
+import chalk from 'chalk';
+import { access, readFile, unlink } from 'fs/promises';
+import { join } from 'path';
+import { cwd } from 'process';
+import { readManifest, listSkills, getVersion } from '../utils/manifest.js';
+import { syncSymlinks, syncCopies, platformSupportsSymlinks, buildHeader } from '../utils/symlink.js';
+import { updateSubmodule, getLatestTag } from '../storage/submodule.js';
+import { cloneFramework } from '../storage/copy.js';
+import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
+import simpleGit from 'simple-git';
+
+export async function update(options) {
+  const projectRoot = cwd();
+  const frameworkDir = getFrameworkDir(projectRoot);
+  const skillsDir = getSkillsDir(projectRoot);
+  const dryRun = options.dryRun || false;
+
+  // Framework must already be installed
+  const manifestPath = join(frameworkDir, 'manifest.json');
+  if (!await exists(manifestPath)) {
+    console.error(chalk.red('Framework not installed. Run `cuewright init` first.'));
+    process.exit(1);
+  }
+
+  const oldManifest = await readManifest(frameworkDir);
+  const oldVersion = getVersion(oldManifest);
+
+  // Detect whether this is a submodule or a plain copy
+  const isSubmodule = await exists(join(projectRoot, '.gitmodules'))
+    && await isSubmoduleInstall(projectRoot, frameworkDir);
+
+  // Determine target version
+  const targetVersion = options.to || await resolveLatestTag(frameworkDir);
+
+  if (targetVersion === oldVersion) {
+    console.log(chalk.cyan(`Already at v${oldVersion} (latest). Nothing to update.`));
+    return;
+  }
+
+  console.log(chalk.cyan(`Updating framework: v${oldVersion} → v${targetVersion}`));
+
+  if (dryRun) {
+    console.log(chalk.yellow('Dry run — no changes will be made.'));
+  }
+
+  if (!dryRun) {
+    if (isSubmodule) {
+      await updateSubmodule(projectRoot, '.claude/skills/_framework', targetVersion);
+    } else {
+      await cloneFramework(frameworkDir, targetVersion);
+    }
+  }
+
+  const newManifest = await readManifest(frameworkDir);
+  const newSkills = new Set(listSkills(newManifest));
+  const oldSkills = new Set(listSkills(oldManifest));
+
+  // Diff skills
+  const added = [...newSkills].filter(s => !oldSkills.has(s));
+  const removed = [...oldSkills].filter(s => !newSkills.has(s));
+
+  if (added.length > 0) {
+    console.log(`New skills: ${added.join(', ')}`);
+    if (!dryRun) {
+      const useCopies = !platformSupportsSymlinks();
+      if (useCopies) {
+        await syncCopies(frameworkDir, skillsDir, added, targetVersion);
+      } else {
+        await syncSymlinks(frameworkDir, skillsDir, added);
+      }
+    }
+  }
+
+  if (removed.length > 0) {
+    for (const name of removed) {
+      const skillPath = join(skillsDir, name);
+      if (await exists(skillPath)) {
+        const isOverride = await isRealDirectory(skillPath);
+        if (isOverride) {
+          console.log(chalk.yellow(`  warning: skill '${name}' was removed from the framework but you have a local override at .claude/skills/${name}/. It has been left in place.`));
+        } else {
+          // It's a symlink to a now-missing target — clean it up
+          if (!dryRun) {
+            await unlink(skillPath);
+          }
+          console.log(`  Removed broken symlink: ${name}`);
+        }
+      }
+    }
+  }
+
+  // Print changelog for the updated range
+  const changelogPath = join(frameworkDir, 'CHANGELOG.md');
+  if (await exists(changelogPath)) {
+    const changelog = await readFile(changelogPath, 'utf8');
+    const relevant = extractChangelogRange(changelog, oldVersion, targetVersion);
+    if (relevant) {
+      console.log('\n' + chalk.bold('What changed:'));
+      console.log(relevant);
+    }
+  }
+
+  if (!dryRun) {
+    console.log(chalk.green(`\nUpdated to v${targetVersion}.`));
+  } else {
+    console.log(chalk.yellow(`\nDry run complete. Run without --dry-run to apply changes.`));
+  }
+}
+
+/**
+ * Resolve the latest semver tag from the installed framework's git history.
+ */
+async function resolveLatestTag(frameworkDir) {
+  try {
+    const git = simpleGit(frameworkDir);
+    return await getLatestTag(git);
+  } catch {
+    throw new Error('Could not determine latest framework version. Use --to <version> to specify one.');
+  }
+}
+
+/**
+ * Check whether _framework was installed as a git submodule.
+ */
+async function isSubmoduleInstall(projectRoot, frameworkDir) {
+  try {
+    const gitmodulesPath = join(projectRoot, '.gitmodules');
+    const content = await readFile(gitmodulesPath, 'utf8');
+    return content.includes('.claude/skills/_framework');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract changelog entries between two versions.
+ * Returns the text for versions newer than oldVersion up to and including targetVersion.
+ */
+function extractChangelogRange(changelog, oldVersion, targetVersion) {
+  const lines = changelog.split('\n');
+  const sections = [];
+  let inRange = false;
+  let currentSection = [];
+
+  for (const line of lines) {
+    const versionMatch = line.match(/^## v(\d+\.\d+\.\d+)/);
+    if (versionMatch) {
+      const v = versionMatch[1];
+      if (currentSection.length > 0 && inRange) {
+        sections.push(currentSection.join('\n').trim());
+      }
+      currentSection = [line];
+      inRange = isNewer(v, oldVersion) && !isNewer(v, targetVersion);
+    } else if (inRange) {
+      currentSection.push(line);
+    }
+  }
+
+  if (currentSection.length > 0 && inRange) {
+    sections.push(currentSection.join('\n').trim());
+  }
+
+  return sections.join('\n\n');
+}
+
+function isNewer(a, b) {
+  const [aMaj, aMin, aPat] = a.split('.').map(Number);
+  const [bMaj, bMin, bPat] = b.split('.').map(Number);
+  if (aMaj !== bMaj) return aMaj > bMaj;
+  if (aMin !== bMin) return aMin > bMin;
+  return aPat > bPat;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isRealDirectory(path) {
+  const { lstat } = await import('fs/promises');
+  const stat = await lstat(path);
+  return stat.isDirectory() && !stat.isSymbolicLink();
+}

package/src/storage/copy.js

@@ -0,0 +1,18 @@
+import simpleGit from 'simple-git';
+import { mkdir, rm } from 'fs/promises';
+import { join } from 'path';
+
+const FRAMEWORK_REPO = 'https://github.com/scriswell/cuewright';
+
+/**
+ * Clone the framework as a plain directory (not a submodule).
+ * Used when --no-submodule is passed or on platforms where submodules are impractical.
+ */
+export async function cloneFramework(targetDir, tag) {
+  // Remove if exists (re-install scenario)
+  await rm(targetDir, { recursive: true, force: true });
+  await mkdir(targetDir, { recursive: true });
+
+  const git = simpleGit();
+  await git.clone(FRAMEWORK_REPO, targetDir, ['--depth', '1', ...(tag ? ['--branch', tag] : [])]);
+}

package/src/storage/submodule.js

@@ -0,0 +1,51 @@
+import simpleGit from 'simple-git';
+
+const FRAMEWORK_REPO = 'https://github.com/scriswell/cuewright';
+
+/**
+ * Add the framework as a git submodule.
+ * If tag is provided, checks out that tag after adding.
+ */
+export async function addSubmodule(projectRoot, submodulePath, tag) {
+  const git = simpleGit(projectRoot);
+
+  await git.submoduleAdd(FRAMEWORK_REPO, submodulePath);
+
+  if (tag) {
+    const subGit = simpleGit(`${projectRoot}/${submodulePath}`);
+    await subGit.checkout(tag);
+
+    // Update the superproject's submodule pointer to this commit
+    await git.submoduleUpdate(['--init', submodulePath]);
+  }
+}
+
+/**
+ * Update an existing submodule to a specific tag (or latest if no tag given).
+ * "Latest" means the most recent semver tag on the remote.
+ */
+export async function updateSubmodule(projectRoot, submodulePath, tag) {
+  const subGit = simpleGit(`${projectRoot}/${submodulePath}`);
+
+  await subGit.fetch(['--tags']);
+
+  if (tag) {
+    await subGit.checkout(tag);
+  } else {
+    // Checkout the latest semver tag
+    const latestTag = await getLatestTag(subGit);
+    await subGit.checkout(latestTag);
+  }
+}
+
+/**
+ * Return the latest semver tag from the repo's tag list.
+ */
+export async function getLatestTag(git) {
+  const result = await git.tags(['--sort=-version:refname']);
+  const semverTags = result.all.filter(t => /^v\d+\.\d+\.\d+/.test(t));
+  if (semverTags.length === 0) {
+    throw new Error('No semver tags found in framework repo');
+  }
+  return semverTags[0];
+}

package/src/utils/manifest.js

@@ -0,0 +1,26 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * Read and parse a manifest.json file.
+ * Returns the parsed object or throws if the file is missing or invalid JSON.
+ */
+export async function readManifest(frameworkDir) {
+  const manifestPath = join(frameworkDir, 'manifest.json');
+  const raw = await readFile(manifestPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Return the list of skill names from a parsed manifest.
+ */
+export function listSkills(manifest) {
+  return Object.keys(manifest.skills);
+}
+
+/**
+ * Return the framework version string from a parsed manifest.
+ */
+export function getVersion(manifest) {
+  return manifest.framework_version;
+}

package/src/utils/symlink.js

@@ -0,0 +1,135 @@
+import { symlink, mkdir, access, lstat, readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+/**
+ * Ensure all skills in the manifest are wired into the skills discovery dir
+ * using directory symlinks.
+ *
+ * For each skill name:
+ *   - If a real directory already exists at <skillsDir>/<name>: skip (override preserved).
+ *   - If a valid symlink already exists: skip.
+ *   - If a broken symlink exists: re-create it.
+ *   - Otherwise: create a directory symlink pointing to <frameworkDir>/skills/<name>.
+ *
+ * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
+ */
+export async function syncSymlinks(frameworkDir, skillsDir, skillNames) {
+  const wired = [];
+  const skipped = [];
+  const errors = [];
+
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const name of skillNames) {
+    const linkPath = join(skillsDir, name);
+    const targetPath = join(frameworkDir, 'skills', name);
+
+    try {
+      const stat = await lstat(linkPath);
+      if (stat.isSymbolicLink()) {
+        try {
+          await access(linkPath);
+          skipped.push(name); // valid symlink already present
+        } catch {
+          // Broken symlink — re-create
+          await symlink(targetPath, linkPath, 'dir');
+          wired.push(name);
+        }
+      } else if (stat.isDirectory()) {
+        skipped.push(name); // real directory override — never touch
+      } else {
+        errors.push(`${name}: unexpected file at ${linkPath}`);
+      }
+    } catch {
+      // Path does not exist — create symlink
+      await symlink(targetPath, linkPath, 'dir');
+      wired.push(name);
+    }
+  }
+
+  return { wired, skipped, errors };
+}
+
+/**
+ * Ensure all skills in the manifest are wired via file copies (Windows / --copy mode).
+ *
+ * Copies <frameworkDir>/skills/<name>/SKILL.md → <skillsDir>/<name>/SKILL.md,
+ * prepending an auto-generated header so consumers know not to edit the file directly.
+ *
+ * For each skill name:
+ *   - If a real directory exists at <skillsDir>/<name> WITHOUT the auto-gen header: skip (override).
+ *   - If a copy with the header already exists: skip (already wired).
+ *   - Otherwise: create <skillsDir>/<name>/ and write SKILL.md with header.
+ *
+ * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
+ */
+export async function syncCopies(frameworkDir, skillsDir, skillNames, version) {
+  const wired = [];
+  const skipped = [];
+  const errors = [];
+
+  await mkdir(skillsDir, { recursive: true });
+
+  for (const name of skillNames) {
+    const destDir = join(skillsDir, name);
+    const destFile = join(destDir, 'SKILL.md');
+    const srcFile = join(frameworkDir, 'skills', name, 'SKILL.md');
+
+    try {
+      const stat = await lstat(destDir);
+      if (stat.isDirectory()) {
+        // Check if it's an auto-generated copy or a real override
+        let existingContent = '';
+        try {
+          existingContent = await readFile(destFile, 'utf8');
+        } catch {
+          // No SKILL.md — treat as override directory
+          skipped.push(name);
+          continue;
+        }
+
+        if (existingContent.startsWith('<!-- AUTO-GENERATED')) {
+          skipped.push(name); // already wired as a copy
+        } else {
+          skipped.push(name); // real override — never touch
+        }
+        continue;
+      }
+    } catch {
+      // Directory does not exist — proceed to create
+    }
+
+    try {
+      const srcContent = await readFile(srcFile, 'utf8');
+      const header = buildHeader(name, version);
+      await mkdir(destDir, { recursive: true });
+      await writeFile(destFile, header + srcContent, 'utf8');
+      wired.push(name);
+    } catch (err) {
+      errors.push(`${name}: ${err.message}`);
+    }
+  }
+
+  return { wired, skipped, errors };
+}
+
+/**
+ * Build the auto-generated header prepended to copied SKILL.md files.
+ */
+export function buildHeader(skillName, version) {
+  return [
+    `<!-- AUTO-GENERATED: Copied from _framework/skills/${skillName}/SKILL.md (v${version}) -->`,
+    `<!-- Do not edit directly. Run \`npx @cuewright/skills update\` to refresh. -->`,
+    `<!-- To override: delete this file and create your own SKILL.md in this directory. -->`,
+    '',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Detect whether symlinks can be created on the current platform.
+ * On Windows, directory symlinks require developer mode or admin privileges.
+ */
+export function platformSupportsSymlinks() {
+  return process.platform !== 'win32';
+}