@cuewright/skills 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuewright/skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI installer for the Cuewright skills framework",
   "type": "module",
   "engines": {
@@ -37,7 +37,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/scriswell/cuewright-cli.git"
+    "url": "git+https://github.com/scriswell/cuewright-cli.git"
   },
   "homepage": "https://github.com/scriswell/cuewright-cli#readme"
 }

package/src/commands/doctor.js

@@ -63,7 +63,7 @@ export async function doctor() {
   }
 
   if (brokenLinks.length === 0) {
-    checks.push(pass(`${wiredCount}/${skills.length} skills wired`));
+    checks.push(pass(`${wiredCount}/${skills.length} skills wired (cw- prefix)`));
   } else {
     allPassed = false;
     checks.push(fail(
@@ -75,6 +75,32 @@ export async function doctor() {
     }
   }
 
+  // 4b. Check for legacy unprefixed skill directories (old install, needs migration)
+  const legacySkillNames = skills.map(s => s.replace(/^cw-/, ''));
+  const legacyFound = [];
+  for (const name of legacySkillNames) {
+    const legacyPath = join(skillsDir, name);
+    try {
+      const stat = await lstat(legacyPath);
+      if (stat.isDirectory()) {
+        legacyFound.push(name);
+      }
+    } catch {
+      // Not present — good
+    }
+  }
+
+  if (legacyFound.length > 0) {
+    allPassed = false;
+    checks.push(fail(
+      `${legacyFound.length} legacy skill director${legacyFound.length === 1 ? 'y' : 'ies'} found (pre-v0.15.0 install)`,
+      'Run `cuewright update` to migrate to cw- prefix and move reference files to arch/references/.'
+    ));
+    for (const name of legacyFound) {
+      checks.push(fail(`  .claude/skills/${name}/`, null));
+    }
+  }
+
   // 5. arch/project-config.md exists
   const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
   if (!await exists(configPath)) {
@@ -107,6 +133,14 @@ export async function doctor() {
     }
   }
 
+  // 6b. arch/references/ exists
+  const referencesDir = join(projectRoot, '.claude', 'skills', 'arch', 'references');
+  if (!await exists(referencesDir)) {
+    checks.push(warn('arch/references/ not found — skill reference files have no home. Run `cuewright update` to scaffold it.'));
+  } else {
+    checks.push(pass('arch/references/ found'));
+  }
+
   // 7. Baseline compatibility check (if baseline present)
   const baselineDir = join(projectRoot, '.claude', 'skills', '_baseline');
   if (await exists(baselineDir)) {

package/src/commands/init.js

@@ -4,7 +4,7 @@ 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 { addSubmodule, configureSparseCheckout } from '../storage/submodule.js';
 import { cloneFramework } from '../storage/copy.js';
 import { getSkillsDir, getFrameworkDir, getSubmodulePath } from '../adapters/claude.js';
 
@@ -76,6 +76,7 @@ async function freshInstall(projectRoot, frameworkDir, skillsDir, options) {
   if (useSubmodule) {
     console.log('Adding git submodule...');
     await addSubmodule(projectRoot, getSubmodulePath(), tag);
+    await configureSparseCheckout(frameworkDir);
   } else {
     console.log('Cloning framework (copy mode)...');
     await cloneFramework(frameworkDir, tag);
@@ -96,6 +97,7 @@ async function freshInstall(projectRoot, frameworkDir, skillsDir, options) {
   }
 
   await scaffoldConfigIfMissing(projectRoot, frameworkDir);
+  await scaffoldArchDirectories(projectRoot);
 
   console.log(chalk.green(`\nDone.`));
   console.log(`  Framework:  v${version}`);
@@ -127,6 +129,18 @@ async function scaffoldConfigIfMissing(projectRoot, frameworkDir) {
   console.log('  Scaffolded arch/project-config.md');
 }
 
+/**
+ * Scaffold arch/references/ and arch/templates/ subdirectories if they don't exist.
+ * These are the project customization roots under the cw- prefix model.
+ */
+async function scaffoldArchDirectories(projectRoot) {
+  const archDir = join(projectRoot, '.claude', 'skills', 'arch');
+  await mkdir(join(archDir, 'references'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'page'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'component'), { recursive: true });
+  await mkdir(join(archDir, 'templates', 'guide'), { recursive: true });
+}
+
 async function exists(path) {
   try {
     await access(path);

package/src/commands/update.js

@@ -1,12 +1,13 @@
 import chalk from 'chalk';
-import { access, readFile, unlink } from 'fs/promises';
+import { access, readFile, unlink, readdir, rename, mkdir } 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 { updateSubmodule, fetchTags, getLatestTag, getLatestTagFromRemote, configureSparseCheckout } from '../storage/submodule.js';
 import { cloneFramework } from '../storage/copy.js';
 import { getSkillsDir, getFrameworkDir } from '../adapters/claude.js';
+import { updateProjectConfigVersion } from '../utils/project-config.js';
 import simpleGit from 'simple-git';
 
 export async function update(options) {
@@ -29,8 +30,17 @@ export async function update(options) {
   const isSubmodule = await exists(join(projectRoot, '.gitmodules'))
     && await isSubmoduleInstall(projectRoot, frameworkDir);
 
-  // Determine target version
-  const targetVersion = options.to || await resolveLatestTag(frameworkDir);
+  // Fetch remote tags before resolving latest — ensures local tag list is current
+  if (isSubmodule && !options.to) {
+    try {
+      await fetchTags(frameworkDir);
+    } catch {
+      // Non-fatal — fallback to remote query below
+    }
+  }
+
+  // Determine target version — always bare (no leading v)
+  const targetVersion = (options.to || await resolveLatestTag(frameworkDir, isSubmodule)).replace(/^v/, '');
 
   if (targetVersion === oldVersion) {
     console.log(chalk.cyan(`Already at v${oldVersion} (latest). Nothing to update.`));
@@ -46,6 +56,7 @@ export async function update(options) {
   if (!dryRun) {
     if (isSubmodule) {
       await updateSubmodule(projectRoot, '.claude/skills/_framework', targetVersion);
+      await configureSparseCheckout(frameworkDir);
     } else {
       await cloneFramework(frameworkDir, targetVersion);
     }
@@ -75,20 +86,39 @@ export async function update(options) {
     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.`));
+        const isRealDir = await isRealDirectory(skillPath);
+        if (isRealDir) {
+          // Check if this is a cw- rename migration (old unprefixed name → cw-name)
+          const isMigrationRename = newSkills.has(`cw-${name}`);
+          if (isMigrationRename) {
+            if (!dryRun) {
+              await migrateSkillDirectory(skillPath, name, skillsDir, projectRoot);
+            } else {
+              console.log(chalk.yellow(`  migrate: ${name}/ → arch/references/${name}/ (reference files) + remove SKILL.md`));
+            }
+          } else {
+            console.log(chalk.yellow(`  warning: '${name}' removed from framework. Local directory at .claude/skills/${name}/ left in place.`));
+          }
         } else {
-          // It's a symlink to a now-missing target — clean it up
+          // Symlink to now-missing target — clean it up
           if (!dryRun) {
             await unlink(skillPath);
           }
-          console.log(`  Removed broken symlink: ${name}`);
+          console.log(`  Removed stale symlink: ${name}`);
         }
       }
     }
   }
 
+  // Scaffold arch/references/ and arch/templates/ if missing
+  if (!dryRun) {
+    const archDir = join(projectRoot, '.claude', 'skills', 'arch');
+    await mkdir(join(archDir, 'references'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'page'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'component'), { recursive: true });
+    await mkdir(join(archDir, 'templates', 'guide'), { recursive: true });
+  }
+
   // Print changelog for the updated range
   const changelogPath = join(frameworkDir, 'CHANGELOG.md');
   if (await exists(changelogPath)) {
@@ -100,6 +130,12 @@ export async function update(options) {
     }
   }
 
+  // Update version in project-config.md
+  if (!dryRun) {
+    const configPath = join(projectRoot, '.claude', 'skills', 'arch', 'project-config.md');
+    await updateProjectConfigVersion(configPath, targetVersion);
+  }
+
   if (!dryRun) {
     console.log(chalk.green(`\nUpdated to v${targetVersion}.`));
   } else {
@@ -108,14 +144,63 @@ export async function update(options) {
 }
 
 /**
- * Resolve the latest semver tag from the installed framework's git history.
+ * Migrate an old skill directory during the cw- rename:
+ * - Move any non-SKILL.md files to arch/references/<name>/
+ * - Remove the SKILL.md (it was a framework copy, overrides are gone)
+ * - Remove the now-empty directory
+ */
+async function migrateSkillDirectory(skillPath, name, skillsDir, projectRoot) {
+  const archReferencesDir = join(projectRoot, '.claude', 'skills', 'arch', 'references', name);
+
+  let entries;
+  try {
+    entries = await readdir(skillPath);
+  } catch {
+    return;
+  }
+
+  const referenceFiles = entries.filter(e => e !== 'SKILL.md');
+
+  if (referenceFiles.length > 0) {
+    await mkdir(archReferencesDir, { recursive: true });
+    for (const file of referenceFiles) {
+      const src = join(skillPath, file);
+      const dest = join(archReferencesDir, file);
+      await rename(src, dest);
+    }
+    console.log(`  Moved ${referenceFiles.length} reference file(s) to arch/references/${name}/`);
+  }
+
+  // Remove SKILL.md and the directory
+  try {
+    await unlink(join(skillPath, 'SKILL.md'));
+  } catch {
+    // Already gone or never existed
+  }
+
+  try {
+    const { rmdir } = await import('fs/promises');
+    await rmdir(skillPath);
+    console.log(`  Removed legacy skill directory: ${name}/`);
+  } catch {
+    console.log(chalk.yellow(`  warning: Could not remove .claude/skills/${name}/ — remove it manually.`));
+  }
+}
+
+/**
+ * Resolve the latest semver tag from the installed framework.
  */
-async function resolveLatestTag(frameworkDir) {
+async function resolveLatestTag(frameworkDir, isSubmodule) {
   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.');
+    // Shallow clone or no local tags — query remote directly
+    try {
+      return await getLatestTagFromRemote();
+    } catch {
+      throw new Error('Could not determine latest framework version. Use --to <version> to specify one.');
+    }
   }
 }
 

package/src/storage/copy.js

@@ -14,5 +14,6 @@ export async function cloneFramework(targetDir, tag) {
   await mkdir(targetDir, { recursive: true });
 
   const git = simpleGit();
-  await git.clone(FRAMEWORK_REPO, targetDir, ['--depth', '1', ...(tag ? ['--branch', tag] : [])]);
+  const gitTag = tag ? (tag.startsWith('v') ? tag : `v${tag}`) : undefined;
+  await git.clone(FRAMEWORK_REPO, targetDir, ['--depth', '1', ...(gitTag ? ['--branch', gitTag] : [])]);
 }

package/src/storage/submodule.js

@@ -5,6 +5,7 @@ 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.
+ * Tag may be bare (0.15.0) or prefixed (v0.15.0) — normalized internally.
  */
 export async function addSubmodule(projectRoot, submodulePath, tag) {
   const git = simpleGit(projectRoot);
@@ -13,7 +14,7 @@ export async function addSubmodule(projectRoot, submodulePath, tag) {
 
   if (tag) {
     const subGit = simpleGit(`${projectRoot}/${submodulePath}`);
-    await subGit.checkout(tag);
+    await subGit.checkout(toGitTag(tag));
 
     // Update the superproject's submodule pointer to this commit
     await git.submoduleUpdate(['--init', submodulePath]);
@@ -22,24 +23,27 @@ export async function addSubmodule(projectRoot, submodulePath, tag) {
 
 /**
  * Update an existing submodule to a specific tag (or latest if no tag given).
- * "Latest" means the most recent semver tag on the remote.
+ * Caller is responsible for fetching tags before calling this.
  */
 export async function updateSubmodule(projectRoot, submodulePath, tag) {
   const subGit = simpleGit(`${projectRoot}/${submodulePath}`);
+  const gitTag = tag ? toGitTag(tag) : toGitTag(await getLatestTag(subGit));
+  await subGit.checkout(gitTag);
+}
 
-  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);
-  }
+/**
+ * Fetch all tags from the remote into the submodule's local repo.
+ * Call this before resolveLatestTag to ensure local tags are current.
+ */
+export async function fetchTags(frameworkDir) {
+  const git = simpleGit(frameworkDir);
+  await git.fetch(['--tags']);
 }
 
 /**
- * Return the latest semver tag from the repo's tag list.
+ * Return the latest semver tag as a bare version string (no leading v).
+ * e.g. "0.15.0" not "v0.15.0"
+ * Uses local tags — call fetchTags() first if stale.
  */
 export async function getLatestTag(git) {
   const result = await git.tags(['--sort=-version:refname']);
@@ -47,5 +51,46 @@ export async function getLatestTag(git) {
   if (semverTags.length === 0) {
     throw new Error('No semver tags found in framework repo');
   }
-  return semverTags[0];
+  return semverTags[0].replace(/^v/, '');
+}
+
+/**
+ * Resolve the latest semver tag directly from the remote.
+ * Fallback for copy-mode installs where local tags are unavailable.
+ */
+export async function getLatestTagFromRemote() {
+  const git = simpleGit();
+  const result = await git.listRemote(['--tags', '--sort=-version:refname', FRAMEWORK_REPO]);
+  const tags = result.split('\n')
+    .map(line => line.match(/refs\/tags\/(v\d+\.\d+\.\d+)$/))
+    .filter(Boolean)
+    .map(m => m[1]);
+  if (tags.length === 0) throw new Error('No semver tags found on remote');
+  return tags[0].replace(/^v/, '');
+}
+
+/**
+ * Configure sparse checkout on a submodule to include only the directories
+ * that consuming projects need: skills/, targets/, core/, plus key root files.
+ * Excludes docs/, .github/, CHANGELOG.md, etc.
+ */
+export async function configureSparseCheckout(submoduleAbsPath) {
+  const git = simpleGit(submoduleAbsPath);
+  await git.raw(['sparse-checkout', 'init', '--no-cone']);
+  await git.raw(['sparse-checkout', 'set',
+    'skills/',
+    'targets/',
+    'core/',
+    'manifest.json',
+    'LICENSE',
+    'README.md',
+  ]);
+}
+
+/**
+ * Normalize a version string to a git tag with v prefix.
+ * "0.15.0" → "v0.15.0", "v0.15.0" → "v0.15.0"
+ */
+function toGitTag(version) {
+  return version.startsWith('v') ? version : `v${version}`;
 }

package/src/utils/project-config.js

@@ -0,0 +1,25 @@
+import { readFile, writeFile, access } from 'fs/promises';
+
+/**
+ * Update the Framework Version line in arch/project-config.md.
+ * Looks for a markdown table row like: | Framework Version | v0.8.0 |
+ * Updates the version value in place. No-ops if the file doesn't exist
+ * or doesn't contain a recognizable version line.
+ */
+export async function updateProjectConfigVersion(configPath, newVersion) {
+  try {
+    await access(configPath);
+  } catch {
+    return; // No project-config — nothing to update
+  }
+
+  const content = await readFile(configPath, 'utf8');
+  const updated = content.replace(
+    /^(\|\s*(?:Framework\s+Version|framework_version)\s*\|\s*)v?\d+\.\d+\.\d+(\s*\|)/im,
+    `$1v${newVersion}$2`
+  );
+
+  if (updated !== content) {
+    await writeFile(configPath, updated, 'utf8');
+  }
+}

package/src/utils/symlink.js

@@ -5,11 +5,9 @@ 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>.
+ * Framework skills use the cw- prefix and are always symlinks — no local
+ * directory overrides. If a real directory is found at a cw-* path, a warning
+ * is emitted and the entry is skipped.
  *
  * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
  */
@@ -36,7 +34,8 @@ export async function syncSymlinks(frameworkDir, skillsDir, skillNames) {
           wired.push(name);
         }
       } else if (stat.isDirectory()) {
-        skipped.push(name); // real directory override — never touch
+        // Real directory at a cw-* path — should not exist
+        errors.push(`${name}: real directory found — framework skills cannot be overridden locally. Remove .claude/skills/${name}/ to restore the framework version.`);
       } else {
         errors.push(`${name}: unexpected file at ${linkPath}`);
       }
@@ -56,10 +55,9 @@ export async function syncSymlinks(frameworkDir, skillsDir, skillNames) {
  * 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.
+ * Framework skills (cw-* prefix) are always auto-generated copies. If a copy
+ * already exists with the auto-generated header, it is refreshed. If a real
+ * override without the header is found, an error is emitted.
  *
  * Returns a summary: { wired: string[], skipped: string[], errors: string[] }
  */
@@ -78,20 +76,19 @@ export async function syncCopies(frameworkDir, skillsDir, skillNames, version) {
     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);
+          // No SKILL.md in a cw-* dir — unexpected
+          errors.push(`${name}: real directory without SKILL.md — framework skills cannot be overridden locally.`);
           continue;
         }
 
         if (existingContent.startsWith('<!-- AUTO-GENERATED')) {
           skipped.push(name); // already wired as a copy
         } else {
-          skipped.push(name); // real override — never touch
+          errors.push(`${name}: real directory with custom SKILL.md found — framework skills cannot be overridden locally. Remove .claude/skills/${name}/ to restore the framework version.`);
         }
         continue;
       }
@@ -120,7 +117,6 @@ 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');