@bluestep-systems/bspecs 0.10.0

package/README.md

@@ -0,0 +1,129 @@
+# @bluestep-systems/bspecs
+
+CLI for scaffolding BlueStep projects with spec-driven development conventions for Claude Code.
+
+## What it does
+
+`bspecs` generates a project directory ready to use with:
+
+- Claude Code skills (`/spec-create`, `/spec-execute`, `/b6p-pull`, `/b6p-push`, and more)
+- BlueStep subagents — `b6p-task-implementer` (isolated task execution; `/spec-execute` delegates to it), `b6p-commenter` (component README), `b6p-code-review` (report-only review)
+- Automatic hooks (prettier on save, generated-file blocking, `b6p` integration)
+- Instructions for Claude Code (the template tree is the single source of truth)
+- Spec templates (`requirements.md`, `design.md`, `tasks.md`)
+- The `b6p` CLI wired into each project as a devDependency, invoked via `npx b6p` (no global install or shell/PATH detection)
+
+## Installation
+
+`bspecs` and the `b6p` CLI it depends on are published to the **public npm registry**, so there is no
+token or `~/.npmrc` setup — install in one command:
+
+```sh
+npm install -g @bluestep-systems/bspecs
+```
+
+This gives you the `bspecs` command for scaffolding projects. It does **not** put a `b6p` binary on
+your global `PATH` — a dependency's bin is never globally reachable. Instead, every project you
+scaffold declares `@bluestep-systems/b6p-cli` as a devDependency and the skills invoke it via
+`npx b6p`. The scaffolder runs `npm install` in the new project for you (best-effort) to fetch `b6p`;
+if it can't — e.g. you're offline — it prints the command to run by hand. That per-project install
+resolves `@bluestep-systems/b6p-cli` anonymously from public npm, no token needed.
+
+> **Not "zero setup."** Removing the npm token does **not** remove the one-time **BlueStep platform**
+> credential step. Before the `/b6p-pull`, `/b6p-push`, or `/b6p-audit` skills work in a scaffolded
+> project, run `npx b6p auth set` **once per machine** (credentials are stored globally in `~/.b6p`,
+> not per project). This is unrelated to the npm registry and is still required — see the scaffolded
+> project's own README.
+
+> **Migrating from the old GitHub Packages install?** If you previously installed `bspecs` you likely
+> have a line in `~/.npmrc` mapping the scope to GitHub Packages:
+>
+> ```ini
+> @bluestep-systems:registry=https://npm.pkg.github.com
+> ```
+>
+> Remove it (and the matching `//npm.pkg.github.com/:_authToken=...` line). Left in place it keeps
+> routing `@bluestep-systems/*` to GitHub Packages and the public install will 404.
+
+## Usage
+
+### Scaffold a new project
+
+From the parent directory where you want to create the project:
+
+```sh
+bspecs
+```
+
+The interactive wizard asks for the project name, client, and an optional description. When done, it generates the project directory with the full structure and (unless you opt out) runs `git init`.
+
+### Keep a project up to date
+
+When a new version of `bspecs` is published with improvements to skills, hooks, or instructions, update your global install and sync the project:
+
+```sh
+npm update -g @bluestep-systems/bspecs
+cd my-project
+bspecs sync
+```
+
+`bspecs sync` compares each infrastructure file against the state it was in when scaffolded. Files you have not modified locally are updated; files you have edited are left untouched with a warning. If you believe your local changes would be useful across all BlueStep projects, open an issue in this repo so they can be incorporated into the scaffolder.
+
+Projects scaffolded with `bspecs 0.5.0` or later run `bspecs sync` automatically every time Claude Code opens the workspace — no manual action needed.
+
+## Prerequisites
+
+- **Node.js 18+**
+- **`b6p` CLI** — required for the `/b6p-pull`, `/b6p-push`, and `/b6p-audit` skills. Scaffolded
+  projects declare it as a devDependency (`@bluestep-systems/b6p-cli`, resolved from public npm with
+  no token); the scaffolder runs `npm install` for you (re-run it by hand if that failed) and the
+  skills invoke it via `npx b6p` — no global install, no shell/PATH detection. Set your platform
+  credentials once per machine with `npx b6p auth set` (see Installation).
+- **prettier** — required for the auto-format hook. `bspecs` warns if it is not found.
+
+## Generated structure
+
+```
+my-project/
+├── CLAUDE.md                          ← project instructions for Claude
+├── README.md                          ← project documentation
+├── .prettierrc
+├── .gitignore
+├── package.json                      ← declares the b6p-cli devDependency
+└── .claude/
+    ├── bspecs.lock                    ← lock file for bspecs sync
+    ├── settings.json                  ← Claude Code permissions and hooks
+    ├── hooks/                         ← 3 scripts executed by Claude Code
+    ├── skills/                        ← 8 skills (/spec-create, /b6p-pull, etc.)
+    ├── agents/                        ← 3 BlueStep subagents (implementer, commenter, reviewer)
+    ├── instructions/                  ← development rules for Claude
+    ├── spec-templates/                ← spec file templates
+    └── templates/                     ← component scaffolding templates
+```
+
+## Proposing changes
+
+### Global changes (improvements for all projects)
+
+If you find something that should be improved in the skills, hooks, instructions, or templates — something useful across all BlueStep projects — open an issue or PR in this repo. Once merged and published as a new version, `bspecs sync` propagates the change to all existing projects automatically.
+
+### Local changes (specific to your project)
+
+If you need to adjust something only for your project (an extra permission in `settings.json`, a custom skill, changes to your `CLAUDE.md`), edit it directly in your repo. `bspecs sync` detects that those files were locally modified and leaves them untouched on future syncs.
+
+## Publishing
+
+The package is published to the **public npm registry** under the `@bluestep-systems` organization
+(`access: public`). Only `cli.js`, `src/`, and `templates/` are included in the published package.
+
+Releases are automated by GitHub Actions — there is no manual `npm publish`:
+
+1. Bump `version` in `package.json` and commit.
+2. Tag the commit `vX.Y.Z` (matching the new version) and push the tag.
+3. `.github/workflows/publish.yml` fires on the tag, verifies the tag matches `package.json`, runs the
+   smoke checks, and publishes with `npm publish --provenance --access public`.
+
+Publishing needs the `NPM_TOKEN` repo secret (an npm automation token with publish rights to
+`@bluestep-systems`); the version guard fails the run early if the tag and `package.json` disagree.
+`.github/workflows/ci.yml` runs the same smoke checks on every pull request and push to the default
+branch.

package/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { intro, outro, cancel, log } from '@clack/prompts';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { runPrompts } from './src/prompts.js';
+import { scaffold } from './src/scaffold.js';
+import { sync } from './src/sync.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
+
+const HELP = `bspecs — spec-driven BlueStep development with AI agents
+
+Scaffold a new BlueStep project with Claude Code skills, hooks, and
+project conventions for spec-driven development.
+
+Usage:
+  bspecs           Run the interactive scaffolder in the current directory.
+  bspecs sync      Sync infrastructure files in the current project.
+  bspecs -v        Print version.
+  bspecs -h        Print this help.
+
+Options for bspecs sync:
+  --silent         Suppress all output (used by the SessionStart hook).
+`;
+
+function parseArgs(argv) {
+  const flags = new Set(argv.filter(a => a.startsWith('-')));
+  const positional = argv.filter(a => !a.startsWith('-'));
+  if (flags.has('-v') || flags.has('--version')) return { mode: 'version' };
+  if (flags.has('-h') || flags.has('--help'))    return { mode: 'help' };
+  if (positional[0] === 'sync') return { mode: 'sync', silent: flags.has('--silent') };
+  return { mode: 'interactive' };
+}
+
+async function main() {
+  const { mode, silent } = parseArgs(process.argv.slice(2));
+
+  if (mode === 'version') {
+    console.log(pkg.version);
+    return;
+  }
+  if (mode === 'help') {
+    console.log(HELP);
+    return;
+  }
+  if (mode === 'sync') {
+    await sync({ silent });
+    return;
+  }
+
+  intro('bspecs — spec-driven BlueStep development with AI agents');
+
+  const answers = await runPrompts();
+  if (!answers) {
+    cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  await scaffold(answers);
+
+  outro(
+    `Project created at ${answers.projectName}\n` +
+    `  Next steps:\n` +
+    `    cd ${answers.projectName}\n` +
+    `    wsl bash -lc 'b6p pull "<DAV URL>"'   (creates the U-folder and component skeleton)`
+  );
+}
+
+main().catch((err) => {
+  log.error(err.message || String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@bluestep-systems/bspecs",
+  "version": "0.10.0",
+  "description": "Spec-driven BlueStep development with AI agents — scaffolder and project conventions for Claude Code",
+  "type": "module",
+  "bin": {
+    "bspecs": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "start": "node cli.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bluestep-Systems/bspecs.git"
+  }
+}

package/src/prompts.js

@@ -0,0 +1,74 @@
+import { text, confirm, isCancel, cancel } from '@clack/prompts';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+function titleCase(s) {
+  return s
+    .replace(/[-_]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function bail(value) {
+  if (isCancel(value)) {
+    cancel('Cancelled.');
+    process.exit(0);
+  }
+  return value;
+}
+
+export async function runPrompts() {
+  const projectName = bail(
+    await text({
+      message: 'Project folder name',
+      placeholder: 'my-bluestep-project',
+      validate: (v) => {
+        if (!v || !v.trim()) return 'Project name is required';
+        if (/[<>:"/\\|?*]/.test(v)) return 'Invalid characters in name';
+        if (existsSync(join(process.cwd(), v))) return `Folder "${v}" already exists`;
+        return undefined;
+      },
+    })
+  );
+
+  const clientName = bail(
+    await text({
+      message: 'Client name',
+      initialValue: titleCase(projectName),
+      validate: (v) => (v && v.trim() ? undefined : 'Client name is required'),
+    })
+  );
+
+  const projectDescription = bail(
+    await text({
+      message: 'Project description (optional — gives Claude project context)',
+      placeholder: 'What does this project do? Press Enter to skip.',
+    })
+  );
+
+  const initGit = bail(
+    await confirm({
+      message:
+        'Initialize a git repository? (skipping degrades the implementer agent, which relies on git diff)',
+      initialValue: true,
+    })
+  );
+
+  const proceed = bail(
+    await confirm({
+      message: `Create project "${projectName}" in ${process.cwd()}?`,
+      initialValue: true,
+    })
+  );
+
+  if (!proceed) return null;
+
+  return {
+    projectName,
+    clientName,
+    projectDescription: projectDescription || '',
+    initGit,
+  };
+}

package/src/scaffold.js

@@ -0,0 +1,152 @@
+import { execSync } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { log } from '@clack/prompts';
+import { ensureDir, copyTemplateTree, applyTemplate, TEMPLATES_DIR, sha256 } from './utils.js';
+import { SYNC_TARGETS } from './sync.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+function writeBspecsLock(projectDir, vars) {
+  const files = {};
+  for (const target of SYNC_TARGETS) {
+    const templatePath = join(TEMPLATES_DIR, target.templateSrc);
+    if (!existsSync(templatePath)) continue;
+    const rendered = applyTemplate(readFileSync(templatePath, 'utf8'), vars);
+    files[target.destRel] = sha256(rendered);
+  }
+
+  const lock = {
+    bspecs_version: pkg.version,
+    synced_at: new Date().toISOString().split('T')[0],
+    vars: {
+      PROJECT_NAME: vars.PROJECT_NAME,
+      CLIENT_NAME: vars.CLIENT_NAME,
+      PROJECT_DESCRIPTION: vars.PROJECT_DESCRIPTION,
+      SCAFFOLD_DATE: vars.SCAFFOLD_DATE,
+    },
+    files,
+  };
+
+  writeFileSync(join(projectDir, '.claude', 'bspecs.lock'), JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+
+export async function scaffold(answers) {
+  const projectDir = join(process.cwd(), answers.projectName);
+  ensureDir(projectDir);
+
+  const vars = {
+    PROJECT_NAME: answers.projectName,
+    CLIENT_NAME: answers.clientName,
+    PROJECT_DESCRIPTION: answers.projectDescription,
+    SCAFFOLD_DATE: new Date().toISOString().split('T')[0],
+  };
+
+  copyTemplateTree('root', projectDir, vars);
+  copyTemplateTree('claude', join(projectDir, '.claude'), vars, { makeExecutable: true });
+  copyTemplateTree('module', join(projectDir, '.claude', 'templates'), vars);
+
+  writeBspecsLock(projectDir, vars);
+
+  log.success('Files generated.');
+
+  checkPrettierOnPath();
+  installDependencies(answers.projectName, projectDir);
+
+  if (answers.initGit) {
+    if (isInsideGitRepo(projectDir)) {
+      log.warn(
+        'An existing git repository was found in a parent directory. Skipping git init to avoid nesting a repository inside another — initialize manually if that was intended.'
+      );
+    } else {
+      try {
+        execSync('git init', { cwd: projectDir, stdio: 'ignore' });
+        execSync('git add -A', { cwd: projectDir, stdio: 'ignore' });
+        execSync('git commit -m "chore: initial scaffold via bspecs"', {
+          cwd: projectDir,
+          stdio: 'ignore',
+        });
+        log.success('Git repository initialized.');
+      } catch (err) {
+        log.warn('Could not initialize git repository (git may not be installed).');
+      }
+    }
+  } else {
+    log.warn(
+      'Skipped git init. The implementer agent relies on `git diff` to summarize its work — run `git init` in the project before using /spec-execute.'
+    );
+  }
+}
+
+// Detect whether the freshly created project directory sits inside an existing
+// git repository (a parent has a .git). Running `git init` here would nest a
+// repo inside another, which surprises users and breaks the implementer agent's
+// `git diff`. Returns false if git is unavailable so the normal init path runs.
+function isInsideGitRepo(dir) {
+  try {
+    const out = execSync('git rev-parse --is-inside-work-tree', {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.toString().trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+// Best-effort check that prettier is reachable, so we can warn that the
+// prettier-on-save hook will be a no-op until it is installed. The hook runs
+// inside WSL on Windows, so we probe WSL there in addition to the native PATH.
+// Stderr is silenced because interactive shells often emit banners/warnings.
+// Warning only — this never blocks the scaffold.
+function checkPrettierOnPath() {
+  const probes = process.platform === 'win32'
+    ? ['where prettier', 'wsl bash -lc "command -v prettier"', 'wsl zsh -ic "command -v prettier"']
+    : ['command -v prettier'];
+  for (const cmd of probes) {
+    try {
+      execSync(cmd, { stdio: ['ignore', 'ignore', 'ignore'] });
+      return; // found
+    } catch {
+      // try the next probe
+    }
+  }
+  const installCmd = process.platform === 'linux' || process.platform === 'darwin'
+    ? 'npm i -g prettier'
+    : 'npm i -g prettier  (in PowerShell)  or  wsl bash -lc "npm i -g prettier"  (in WSL)';
+  log.warn(`prettier not found in either the native or WSL PATH. The prettier-on-save hook will be a no-op until you run: ${installCmd}`);
+}
+
+// Install the project's dependencies on a best-effort basis. We attempt
+// `npm install` so the b6p CLI (a devDependency) is present without a manual
+// step, but it can legitimately fail and we must NOT assume it will succeed:
+// @bluestep-systems/b6p-cli installs anonymously from the public npm registry
+// (no token, no ~/.npmrc), so the realistic failure mode is the machine being
+// offline at scaffold time. On any failure we fall back to printing the manual
+// install reminder rather than failing the scaffold or leaving the project
+// half-installed. The skills invoke `npx b6p`, so `node_modules/.bin/b6p` must
+// exist before the first b6p skill runs — hence the reminder on failure.
+function installDependencies(projectName, projectDir) {
+  log.info(`Installing dependencies in ${projectName} (npm install)…`);
+  try {
+    execSync('npm install', { cwd: projectDir, stdio: 'ignore' });
+    log.success('Dependencies installed — b6p is ready via `npx b6p`.');
+  } catch {
+    log.warn(
+      [
+        'Could not run `npm install` automatically. Install dependencies by hand',
+        'before using the b6p skills:',
+        '',
+        `    cd ${projectName}`,
+        '    npm install',
+        '',
+        'This fetches @bluestep-systems/b6p-cli (a devDependency) so the /b6p-pull,',
+        '/b6p-push, and /b6p-audit skills can run `npx b6p …`. It installs from the',
+        'public npm registry with no token or ~/.npmrc setup — the most common cause',
+        'of this failure is simply being offline.',
+      ].join('\n')
+    );
+  }
+}

package/src/sync.js

@@ -0,0 +1,123 @@
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { log } from '@clack/prompts';
+import { TEMPLATES_DIR, applyTemplate, writeFile, sha256, enumerateClaudeTargets } from './utils.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+// Files the scaffolder writes once but sync must NOT manage afterwards.
+// Empty today; add a templateSrc path (forward-slashed, e.g.
+// 'claude/skills/foo/SKILL.md') to opt a future scaffold-once file out of sync.
+const SYNC_EXCLUDE = [];
+
+// Every file under templates/claude/** is synced infrastructure (skills, hooks,
+// settings, spec-templates, instructions). Derived by walking the tree rather
+// than a hardcoded list, so new files flow into `bspecs sync` and bspecs.lock
+// automatically — no hand-maintained array to drift. templates/root/ (user-owned
+// CLAUDE.md/README) and templates/module/ (scaffold-once) live outside this tree
+// and are excluded by construction. Claude-only: no .github mirror.
+export const SYNC_TARGETS = enumerateClaudeTargets(SYNC_EXCLUDE);
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (true) {
+    if (existsSync(join(dir, '.claude', 'bspecs.lock'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readLock(projectRoot) {
+  return JSON.parse(readFileSync(join(projectRoot, '.claude', 'bspecs.lock'), 'utf8'));
+}
+
+function writeLock(projectRoot, obj) {
+  writeFileSync(join(projectRoot, '.claude', 'bspecs.lock'), JSON.stringify(obj, null, 2) + '\n', 'utf8');
+}
+
+function syncFiles(projectRoot, lock, silent) {
+  const vars = lock.vars || {};
+  const newFiles = {};
+  let updated = 0;
+  let skipped = 0;
+
+  for (const target of SYNC_TARGETS) {
+    const templatePath = join(TEMPLATES_DIR, target.templateSrc);
+    if (!existsSync(templatePath)) continue;
+
+    const newContent = applyTemplate(readFileSync(templatePath, 'utf8'), vars);
+    const newHash = sha256(newContent);
+    const destAbs = join(projectRoot, target.destRel);
+    const lockHash = lock.files[target.destRel];
+
+    if (!existsSync(destAbs)) {
+      writeFile(destAbs, newContent);
+      if (destAbs.endsWith('.sh')) {
+        try { chmodSync(destAbs, 0o755); } catch { /* Windows */ }
+      }
+      newFiles[target.destRel] = newHash;
+      updated++;
+      if (!silent) log.info(`  added   ${target.destRel}`);
+      continue;
+    }
+
+    const diskHash = sha256(readFileSync(destAbs, 'utf8'));
+
+    if (lockHash !== undefined && diskHash !== lockHash) {
+      // Usuario editó este archivo localmente — no tocar
+      newFiles[target.destRel] = lockHash;
+      skipped++;
+      if (!silent) log.warn(`  skipped ${target.destRel}  (locally modified)`);
+    } else {
+      writeFile(destAbs, newContent);
+      if (destAbs.endsWith('.sh')) {
+        try { chmodSync(destAbs, 0o755); } catch { /* Windows */ }
+      }
+      newFiles[target.destRel] = newHash;
+      if (diskHash !== newHash) {
+        updated++;
+        if (!silent) log.info(`  updated ${target.destRel}`);
+      }
+    }
+  }
+
+  return { updated, skipped, newFiles };
+}
+
+export async function sync({ silent = false } = {}) {
+  try {
+    const projectRoot = findProjectRoot(process.cwd());
+
+    if (!projectRoot) {
+      if (!silent) {
+        console.error(
+          'No bspecs.lock found. Run bspecs sync from a project scaffolded with bspecs 0.5.0 or later.\n' +
+          'If this project was scaffolded earlier, re-run bspecs in the parent directory to re-scaffold.'
+        );
+      }
+      return;
+    }
+
+    const lock = readLock(projectRoot);
+    if (!silent) log.info(`Syncing infrastructure files in: ${projectRoot}`);
+
+    const { updated, skipped, newFiles } = syncFiles(projectRoot, lock, silent);
+
+    writeLock(projectRoot, {
+      bspecs_version: pkg.version,
+      synced_at: new Date().toISOString().split('T')[0],
+      vars: lock.vars || {},
+      files: newFiles,
+    });
+
+    if (!silent) {
+      log.success(`Sync complete. Updated ${updated} file${updated !== 1 ? 's' : ''}, skipped ${skipped} (locally modified).`);
+    }
+  } catch (err) {
+    if (!silent) throw err;
+    // En modo --silent (hook SessionStart): nunca bloquear el startup de Claude Code
+  }
+}

package/src/utils.js

@@ -0,0 +1,95 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync, statSync } from 'fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+
+export function applyTemplate(str, vars) {
+  return str.replace(/\{\{(\w+)\}\}/g, (match, key) =>
+    Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match
+  );
+}
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function writeFile(path, content) {
+  ensureDir(dirname(path));
+  writeFileSync(path, content, 'utf8');
+}
+
+export function readTemplate(relativePath) {
+  return readFileSync(join(TEMPLATES_DIR, relativePath), 'utf8');
+}
+
+export function copyTemplateTree(srcRel, destAbs, vars, opts = {}) {
+  const { makeExecutable = false, stripTemplateExt = true } = opts;
+  const srcAbs = join(TEMPLATES_DIR, srcRel);
+  if (!existsSync(srcAbs)) return;
+  walk(srcAbs, srcAbs, destAbs, vars, { makeExecutable, stripTemplateExt });
+}
+
+function walk(rootSrc, src, dest, vars, opts) {
+  for (const entry of readdirSync(src)) {
+    const srcEntry = join(src, entry);
+    const stats = statSync(srcEntry);
+    if (stats.isDirectory()) {
+      walk(rootSrc, srcEntry, join(dest, entry), vars, opts);
+    } else {
+      const targetName = opts.stripTemplateExt && entry.endsWith('.template')
+        ? entry.slice(0, -'.template'.length)
+        : entry;
+      const destFile = join(dest, targetName);
+      const raw = readFileSync(srcEntry, 'utf8');
+      const rendered = applyTemplate(raw, vars);
+      writeFile(destFile, rendered);
+      if (opts.makeExecutable && destFile.endsWith('.sh')) {
+        try { chmodSync(destFile, 0o755); } catch { /* Windows can't chmod, ignore */ }
+      }
+    }
+  }
+}
+
+// Walk templates/claude/** and return one sync target per file:
+//   { templateSrc, destRel }
+// templateSrc is relative to TEMPLATES_DIR (forward-slashed, e.g.
+//   'claude/instructions/reference/foo.md.template'); destRel maps it into the
+// scaffolded project ('.claude/instructions/reference/foo.md') — leading
+// 'claude/' becomes '.claude/', a trailing '.template' is stripped, subfolders
+// preserved. This is the same transform copyTemplateTree applies, so it
+// reproduces the formerly-hardcoded skills/hooks/settings/spec-template entries
+// exactly and picks up the instructions tree automatically. Claude-only: no
+// .github mirror target is emitted. `exclude` lists templateSrc paths to skip —
+// the escape hatch for any future scaffold-once file under claude/.
+export function enumerateClaudeTargets(exclude = []) {
+  const root = join(TEMPLATES_DIR, 'claude');
+  if (!existsSync(root)) return [];
+  const skip = new Set(exclude);
+  const targets = [];
+  walkClaude(root, 'claude', skip, targets);
+  return targets;
+}
+
+function walkClaude(absDir, relDir, skip, targets) {
+  for (const entry of readdirSync(absDir).sort()) {
+    const abs = join(absDir, entry);
+    const rel = `${relDir}/${entry}`;
+    if (statSync(abs).isDirectory()) {
+      walkClaude(abs, rel, skip, targets);
+    } else if (!skip.has(rel)) {
+      const destRel = '.claude/' + rel.slice('claude/'.length).replace(/\.template$/, '');
+      targets.push({ templateSrc: rel, destRel });
+    }
+  }
+}
+
+export function exists(path) {
+  return existsSync(path);
+}
+
+export function sha256(str) {
+  return createHash('sha256').update(str, 'utf8').digest('hex');
+}