@boopkit/cli 0.3.2 → 0.4.1

package/README.md

@@ -61,7 +61,7 @@ A **capability** is a composable feature bundle. Each capability package ships:
 - **Middleware hooks** — lines wired into `src/server.ts` at the right phase (imports, pre-routes, routes, error-handling)
 - **Scripts** — added to `package.json` (e.g. `db:migrate`, `tailwind:build`)
 - **Post-install steps** — human/agent-readable instructions printed by `boop status`
-- **Agent skills** — `.skill.md` files that teach AI agents the conventions this capability uses
+- **Agent skills** — skill folders (each containing a `SKILL.md`) that teach AI agents the conventions this capability uses
 
 Capabilities can declare `requires` relationships (e.g. `users-and-accounts` requires `database`, `services`, and `web`). `boop add` resolves the dependency graph and installs everything needed.
 
@@ -138,7 +138,7 @@ Flags:
 
 Boop is built for agent-assisted work — the skills and conventions ship with the code so your agent has real guidance, not just a blank repo. Every scaffolded project includes:
 
-- **Skills** — every capability installs `.skill.md` files into `skills/`. These are focused, task-specific instructions (e.g. `design.rest-api-design.skill.md`, `test.tdd-light.skill.md`) that tell an agent the conventions this project uses.
+- **Skills** — every capability installs skill folders into `skills/`. These are focused, task-specific instructions (each folder contains a `SKILL.md`, e.g. `skills/rest-api-design/SKILL.md`, `skills/tdd-light/SKILL.md`) that tell an agent the conventions this project uses.
 - **`boop status`** — after `boop init` or `boop add`, run `boop status`. It prints every capability's post-install steps. Hand this to your agent and say "finish setup."
 - **`boop loop`** — Uses Claude for 'unattended work', building working code and UI from your specifications. 
   - `prefix` mode: Plan work as a tree of issues, then `boop loop --prefix <id>` processes them one at a time, each in its own Claude Code session. Dry-run by default; budget-capped; resumes unfinished work. See [docs/loop.md](docs/loop.md).

package/dist/capability-versions.json

@@ -1,18 +1,18 @@
 {
-  "@boopkit/cap-api": "0.3.1",
-  "@boopkit/cap-background-jobs": "0.3.1",
-  "@boopkit/cap-cloud-storage": "0.3.1",
-  "@boopkit/cap-coding": "0.3.1",
-  "@boopkit/cap-database": "0.3.1",
-  "@boopkit/cap-email": "0.3.1",
-  "@boopkit/cap-hello": "0.3.1",
-  "@boopkit/cap-noticeboard": "0.3.1",
-  "@boopkit/cap-product-design": "0.3.1",
-  "@boopkit/cap-project-mgmt": "0.3.1",
-  "@boopkit/cap-services": "0.3.1",
-  "@boopkit/cap-skills": "0.3.1",
-  "@boopkit/cap-testing": "0.3.1",
-  "@boopkit/cap-users": "0.3.1",
-  "@boopkit/cap-web": "0.3.1",
-  "@boopkit/logger": "0.3.1"
+  "@boopkit/cap-api": "0.4.0",
+  "@boopkit/cap-background-jobs": "0.4.0",
+  "@boopkit/cap-cloud-storage": "0.4.0",
+  "@boopkit/cap-coding": "0.4.0",
+  "@boopkit/cap-database": "0.4.0",
+  "@boopkit/cap-email": "0.4.1",
+  "@boopkit/cap-hello": "0.4.0",
+  "@boopkit/cap-noticeboard": "0.4.0",
+  "@boopkit/cap-product-design": "0.4.0",
+  "@boopkit/cap-project-mgmt": "0.4.0",
+  "@boopkit/cap-services": "0.4.0",
+  "@boopkit/cap-skills": "0.4.0",
+  "@boopkit/cap-testing": "0.4.0",
+  "@boopkit/cap-users": "0.4.1",
+  "@boopkit/cap-web": "0.4.1",
+  "@boopkit/logger": "0.4.0"
 }

package/dist/commands/init.js

@@ -245,6 +245,8 @@ function runInit(name, options) {
     }
     // --- Inject CSS imports for capability partials ---
     (0, scaffold_1.injectCssImports)(targetDir, cssCapMap, { skipBackup: true });
+    // --- Symlink skills/* into .claude/skills/ for Claude Code auto-discovery ---
+    (0, scaffold_1.linkSkillsToClaude)(targetDir);
     // --- Merge capability scripts into package.json ---
     if (Object.keys(allScripts).length > 0) {
         const pkgPath = path.join(targetDir, 'package.json');
@@ -263,8 +265,6 @@ function runInit(name, options) {
     if (fs.existsSync(profileRefDir)) {
         (0, safe_io_1.safeCopyDir)(profileRefDir, path.join(targetDir, 'reference'), { onConflict: 'skip' });
     }
-    // --- Generate skills index from installed skill files ---
-    (0, scaffold_1.generateSkillsIndex)(targetDir);
     // --- Build capabilityConfig for capabilities with env vars ---
     const capabilityConfig = {};
     const envEntries = [];

package/dist/commands/loop.js

@@ -332,7 +332,7 @@ ${issue.description}
 ## Instructions
 1. Read AGENTS.md for project orientation
 2. Claim the issue: bd update ${issue.id} --claim
-3. Read relevant skills from skills/index.md before making changes
+3. Read relevant skills from skills/ (list folders, read each SKILL.md) before making changes
 4. Implement the changes following TDD-Lite: observe, implement, verify
 5. Run tests if applicable: npm test
 6. Commit your changes with a message referencing ${issue.id}
@@ -566,10 +566,21 @@ async function runLoop(options) {
         return;
     }
     if (flow && !fs.existsSync(flow)) {
-        console.error(`\x1b[31mERR\x1b[0m --flow file not found: ${flow}`);
+        console.error(`\x1b[31mERR\x1b[0m --flow path not found: ${flow}`);
         process.exitCode = 1;
         return;
     }
+    // If --flow points to a directory (e.g. a skill folder), resolve to its SKILL.md
+    let resolvedFlow = flow;
+    if (flow && fs.statSync(flow).isDirectory()) {
+        const skillPath = path.join(flow, 'SKILL.md');
+        if (!fs.existsSync(skillPath)) {
+            console.error(`\x1b[31mERR\x1b[0m --flow directory has no SKILL.md: ${flow}`);
+            process.exitCode = 1;
+            return;
+        }
+        resolvedFlow = skillPath;
+    }
     const dryRun = !options.run;
     const maxIssues = parseInt(options.max || '0', 10);
     const budget = options.budget || '5.00';
@@ -586,12 +597,12 @@ async function runLoop(options) {
     const logDir = path.join(projectDir, 'labs', 'claude-runs');
     fs.mkdirSync(logDir, { recursive: true });
     // Planning mode dry-run
-    if (dryRun && work && flow) {
+    if (dryRun && work && resolvedFlow) {
         const workContent = fs.readFileSync(work, 'utf8');
-        const flowContent = fs.readFileSync(flow, 'utf8');
+        const flowContent = fs.readFileSync(resolvedFlow, 'utf8');
         console.log('[bd-loop] PLANNING MODE (dry-run)');
         console.log(`[bd-loop]   Work file: ${work}`);
-        console.log(`[bd-loop]   Flow file: ${flow}`);
+        console.log(`[bd-loop]   Flow file: ${resolvedFlow}${resolvedFlow !== flow ? ` (resolved from ${flow})` : ''}`);
         console.log('[bd-loop]   Planning prompt that would be sent:');
         console.log('---');
         console.log(buildPlanningPrompt(workContent, flowContent, prefix));
@@ -600,10 +611,10 @@ async function runLoop(options) {
         return;
     }
     // Planning phase: create feature tree before looping
-    if (work && flow) {
+    if (work && resolvedFlow) {
         const planResult = await planWork({
             workPath: work,
-            flowPath: flow,
+            flowPath: resolvedFlow,
             prefix,
             budget,
             model,

package/dist/commands/update.js

@@ -40,6 +40,7 @@ const child_process_1 = require("child_process");
 const project_1 = require("../lib/project");
 const capability_1 = require("../lib/capability");
 const update_1 = require("../lib/update");
+const scaffold_1 = require("../lib/scaffold");
 function runUpdate(capabilityName, options) {
     const targetDir = process.cwd();
     // Must be in a boop project
@@ -108,7 +109,8 @@ function runUpdate(capabilityName, options) {
                 const icon = action.action === 'overwrite' ? '\x1b[32m↑\x1b[0m'
                     : action.action === 'skip' ? '\x1b[33m◐\x1b[0m'
                         : action.action === 'add' ? '\x1b[32m+\x1b[0m'
-                            : '\x1b[90m⚠\x1b[0m';
+                            : action.action === 'migrate' ? '\x1b[36m↗\x1b[0m'
+                                : '\x1b[90m⚠\x1b[0m';
                 console.log(`  ${icon} ${action.relativePath} — ${action.reason}`);
             }
         }
@@ -127,6 +129,7 @@ function runUpdate(capabilityName, options) {
                 forcedOverwrite: [],
                 skippedDeleted: [],
                 pruned: [],
+                migrated: [],
                 unchangedCount: plan.unchangedCount,
             });
             continue;
@@ -134,6 +137,10 @@ function runUpdate(capabilityName, options) {
         const result = (0, update_1.executeUpdatePlan)(plan, { force: options.force, restore: options.restore, prune: options.prune });
         results.push(result);
     }
+    // Refresh .claude/skills/ symlinks for any new skill folders added by this update
+    if (!options.dryRun) {
+        (0, scaffold_1.linkSkillsToClaude)(targetDir);
+    }
     // Output
     if (options.json) {
         console.log(JSON.stringify({ capabilities: results }, null, 2));
@@ -144,6 +151,9 @@ function runUpdate(capabilityName, options) {
         const summary = (0, update_1.formatUpdateSummary)(result);
         console.log(`${result.capability}: ${summary}`);
         // Show details for non-trivial updates
+        for (const f of result.migrated || []) {
+            console.log(`  \x1b[36m↗\x1b[0m ${f} (migrated to folder)`);
+        }
         for (const f of result.overwritten) {
             if (result.forcedOverwrite.includes(f)) {
                 console.log(`  \x1b[33m⚠\x1b[0m ${f} (force-overwritten, backup saved)`);

package/dist/lib/execute.js

@@ -100,6 +100,7 @@ function executeTask(task, manifest) {
     switch (task.op) {
         case 'copy-files': {
             (0, scaffold_1.copyCapabilityFiles)(targetDir, capabilityName);
+            (0, scaffold_1.linkSkillsToClaude)(targetDir);
             break;
         }
         case 'merge-deps': {
@@ -154,10 +155,6 @@ function executeTask(task, manifest) {
             (0, scaffold_1.injectCssImports)(targetDir, data.cssCapMap, { skipBackup: true });
             break;
         }
-        case 'generate-skills-index': {
-            (0, scaffold_1.generateSkillsIndex)(targetDir);
-            break;
-        }
         case 'update-manifest': {
             const data = task.data;
             const projectManifest = (0, project_1.readProjectManifest)(targetDir);

package/dist/lib/manifest.d.ts

@@ -7,7 +7,7 @@
  * Phase 2 (execute) walks the manifest, performing each operation and
  * updating task status.
  */
-export type ManifestOp = 'copy-files' | 'merge-deps' | 'merge-scripts' | 'link-package' | 'inject-hook' | 'inject-css' | 'set-env' | 'generate-skills-index' | 'update-manifest' | 'run-command';
+export type ManifestOp = 'copy-files' | 'merge-deps' | 'merge-scripts' | 'link-package' | 'inject-hook' | 'inject-css' | 'set-env' | 'update-manifest' | 'run-command';
 export type TaskStatus = 'pending' | 'done' | 'failed' | 'skipped';
 export interface ManifestTask {
     op: ManifestOp;

package/dist/lib/preflight.js

@@ -329,14 +329,6 @@ function planAdd(targetDir, capabilityName) {
             data: { cssCapMap },
         });
     }
-    // Task: regenerate skills index
-    tasks.push({
-        op: 'generate-skills-index',
-        source: capabilityName,
-        target: path.join(targetDir, 'skills', 'index.md'),
-        detail: 'Regenerate skills/index.md',
-        status: 'pending',
-    });
     // Task: update manifest
     tasks.push({
         op: 'update-manifest',

package/dist/lib/scaffold.d.ts

@@ -36,6 +36,18 @@ export declare function hashFile(filePath: string): string;
  * Returns list of copied file paths relative to targetDir, and file hashes.
  */
 export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[]): string[];
+/**
+ * Symlink each skill folder under `<targetDir>/skills/` into
+ * `<targetDir>/.claude/skills/` so Claude Code's built-in Skill tool
+ * auto-discovers them alongside any plugin-installed skills.
+ *
+ * Per-folder symlinks (rather than a single dir-level symlink) so existing
+ * `.claude/skills/<other>` entries (Claude Code plugins, user-authored skills)
+ * are preserved.
+ *
+ * Idempotent. Returns the relative paths of symlinks created or already present.
+ */
+export declare function linkSkillsToClaude(targetDir: string): string[];
 /**
  * Merge dependencies into an existing package.json.
  * Does not overwrite existing dependency versions.
@@ -83,9 +95,4 @@ interface CapabilityHookEntry {
  * prevent arbitrary code injection into scaffolded projects.
  */
 export declare function collectHooks(capabilities: CapabilityHookEntry[]): HookVariables;
-/**
- * Generate skills/index.md from the .skill.md files present in the project.
- * Overwrites any existing index.md.
- */
-export declare function generateSkillsIndex(targetDir: string): void;
 export {};

package/dist/lib/scaffold.js

@@ -40,11 +40,11 @@ exports.renderTemplate = renderTemplate;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
 exports.copyCapabilityFiles = copyCapabilityFiles;
+exports.linkSkillsToClaude = linkSkillsToClaude;
 exports.getBoopkitVersion = getBoopkitVersion;
 exports.mergePackageJson = mergePackageJson;
 exports.injectCssImports = injectCssImports;
 exports.collectHooks = collectHooks;
-exports.generateSkillsIndex = generateSkillsIndex;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
@@ -139,6 +139,19 @@ function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
     // Fallback to source tree
     return copyFromSourceTree(targetDir, capabilityName);
 }
+function walkDir(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDir(fullPath));
+        }
+        else {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
 /**
  * Copy capability files from a package directory.
  */
@@ -153,10 +166,14 @@ function copyFromPackage(targetDir, capabilityName, pkgDir, boopkit) {
             (0, safe_io_1.safeCopyDir)(skillsDir, destSkillsDir, { onConflict: 'skip' });
             const entries = fs.readdirSync(skillsDir);
             for (const entry of entries) {
-                const destPath = path.join(destSkillsDir, entry);
-                copied.push(path.join('skills', entry));
-                if (fs.existsSync(destPath)) {
-                    fileHashes[path.join('skills', entry)] = hashFile(destPath);
+                const srcEntryPath = path.join(skillsDir, entry);
+                if (fs.statSync(srcEntryPath).isDirectory()) {
+                    const files = walkDir(path.join(destSkillsDir, entry));
+                    for (const filePath of files) {
+                        const rel = path.join('skills', entry, path.relative(path.join(destSkillsDir, entry), filePath));
+                        copied.push(rel);
+                        fileHashes[rel] = hashFile(filePath);
+                    }
                 }
             }
         }
@@ -182,6 +199,42 @@ function copyFromPackage(targetDir, capabilityName, pkgDir, boopkit) {
     }
     return copied;
 }
+/**
+ * Symlink each skill folder under `<targetDir>/skills/` into
+ * `<targetDir>/.claude/skills/` so Claude Code's built-in Skill tool
+ * auto-discovers them alongside any plugin-installed skills.
+ *
+ * Per-folder symlinks (rather than a single dir-level symlink) so existing
+ * `.claude/skills/<other>` entries (Claude Code plugins, user-authored skills)
+ * are preserved.
+ *
+ * Idempotent. Returns the relative paths of symlinks created or already present.
+ */
+function linkSkillsToClaude(targetDir) {
+    const skillsDir = path.join(targetDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
+    fs.mkdirSync(claudeSkillsDir, { recursive: true });
+    const linked = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const linkPath = path.join(claudeSkillsDir, entry.name);
+        const target = path.join('..', '..', 'skills', entry.name);
+        const rel = path.join('.claude', 'skills', entry.name);
+        const existing = fs.lstatSync(linkPath, { throwIfNoEntry: false });
+        if (existing) {
+            if (existing.isSymbolicLink() && fs.readlinkSync(linkPath) === target) {
+                linked.push(rel);
+            }
+            continue;
+        }
+        fs.symlinkSync(target, linkPath);
+        linked.push(rel);
+    }
+    return linked;
+}
 /**
  * Copy capability files from the capabilities/ source tree (test fixtures only).
  */
@@ -198,7 +251,13 @@ function copyFromSourceTree(targetDir, capabilityName) {
         (0, safe_io_1.safeCopyDir)(skillsDir, destSkillsDir, { onConflict: 'skip' });
         const entries = fs.readdirSync(skillsDir);
         for (const entry of entries) {
-            copied.push(path.join('skills', entry));
+            const srcEntryPath = path.join(skillsDir, entry);
+            if (fs.statSync(srcEntryPath).isDirectory()) {
+                const files = walkDir(path.join(destSkillsDir, entry));
+                for (const filePath of files) {
+                    copied.push(path.join('skills', entry, path.relative(path.join(destSkillsDir, entry), filePath)));
+                }
+            }
         }
     }
     // Scaffold files declared in the capability manifest
@@ -481,97 +540,3 @@ function collectHooks(capabilities) {
         hookPostRoutes: renderPhase('postRoutes'),
     };
 }
-/**
- * Preamble for generated skills/index.md.
- * Edit here to change the header text in every generated project.
- */
-const SKILLS_INDEX_PREAMBLE = [
-    '# About Skills',
-    '## Writing new skills',
-    'When writing a new skill, create a markdown file in this directory using the pattern `<topic>.skill.md`.',
-    'Each skill is a concise set of concrete steps that an AI agent can take to achieve a specific goal or perform a specific task.',
-    'Preface the skill with "When you ... " to help the agent understand when to use it.',
-    '',
-    '## Current skills',
-];
-/**
- * Category display names for skill file prefixes.
- * Unknown prefixes get title-cased automatically.
- */
-const SKILL_CATEGORIES = {
-    code: 'Code',
-    design: 'Design',
-    product: 'Product',
-    proj: 'Project',
-    reqs: 'Requirements and Docs',
-    skills: 'Skills',
-    test: 'Testing',
-    web: 'Web',
-    world: 'World',
-};
-/**
- * Extract the H1 title and first content line from a skill markdown file.
- */
-function parseSkillFile(content) {
-    const lines = content.split('\n');
-    let title = '';
-    let description = '';
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!title && trimmed.startsWith('# ')) {
-            title = trimmed.slice(2).trim();
-            continue;
-        }
-        if (title && !description && trimmed.length > 0 && !trimmed.startsWith('#')) {
-            description = trimmed;
-            break;
-        }
-    }
-    return { title: title || 'Untitled', description };
-}
-/**
- * Generate skills/index.md from the .skill.md files present in the project.
- * Overwrites any existing index.md.
- */
-function generateSkillsIndex(targetDir) {
-    const skillsDir = path.join(targetDir, 'skills');
-    if (!fs.existsSync(skillsDir))
-        return;
-    const files = fs.readdirSync(skillsDir)
-        .filter(f => f.endsWith('.skill.md'))
-        .sort();
-    if (files.length === 0)
-        return;
-    const entries = [];
-    for (const filename of files) {
-        const content = fs.readFileSync(path.join(skillsDir, filename), 'utf-8');
-        const { title, description } = parseSkillFile(content);
-        const category = filename.split('.')[0];
-        entries.push({ filename, title, description, category });
-    }
-    // Group by category
-    const grouped = new Map();
-    for (const entry of entries) {
-        const list = grouped.get(entry.category) || [];
-        list.push(entry);
-        grouped.set(entry.category, list);
-    }
-    // Sort categories by display name
-    const sortedCategories = [...grouped.keys()].sort((a, b) => {
-        const nameA = SKILL_CATEGORIES[a] || a;
-        const nameB = SKILL_CATEGORIES[b] || b;
-        return nameA.localeCompare(nameB);
-    });
-    const lines = [...SKILLS_INDEX_PREAMBLE];
-    for (const category of sortedCategories) {
-        const displayName = SKILL_CATEGORIES[category]
-            || category.charAt(0).toUpperCase() + category.slice(1);
-        lines.push(`### ${displayName}`);
-        for (const skill of grouped.get(category)) {
-            const desc = skill.description ? ` - ${skill.description}` : '';
-            lines.push(`- [**${skill.title}**](${skill.filename})${desc}`);
-        }
-        lines.push('');
-    }
-    fs.writeFileSync(path.join(skillsDir, 'index.md'), lines.join('\n'), 'utf-8');
-}

package/dist/lib/update.d.ts

@@ -10,7 +10,7 @@ export interface FileUpdateAction {
     /** Relative path from project root */
     relativePath: string;
     /** What will happen to this file */
-    action: 'overwrite' | 'skip' | 'add' | 'deprecate';
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate';
     /** Why this action was chosen */
     reason: string;
     /** Stored hash from config */
@@ -19,6 +19,8 @@ export interface FileUpdateAction {
     currentHash?: string;
     /** New hash from package */
     newHash?: string;
+    /** For migrate actions: the old file path being replaced */
+    oldPath?: string;
 }
 export interface UpdatePlan {
     capability: string;
@@ -46,6 +48,8 @@ export interface UpdateResult {
     skippedDeleted: string[];
     /** Files removed from disk via --prune */
     pruned: string[];
+    /** Files migrated from old flat format to new folder format */
+    migrated: string[];
     /** Count of files unchanged in both package and locally */
     unchangedCount: number;
 }

package/dist/lib/update.js

@@ -92,15 +92,19 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
             collectFiles(scaffoldDir, scaffoldDir, packageFiles);
         }
     }
-    // Collect files from package skills dir
+    // Collect files from package skills dir (both flat files and folder-based skills)
     if (boopkit.skillsDir) {
         const skillsDir = path.join(pkgDir, boopkit.skillsDir);
         if (fs.existsSync(skillsDir)) {
             const entries = fs.readdirSync(skillsDir);
             for (const entry of entries) {
                 const srcPath = path.join(skillsDir, entry);
-                if (fs.statSync(srcPath).isFile()) {
-                    packageFiles.set(path.join('skills', entry), srcPath);
+                if (fs.statSync(srcPath).isDirectory()) {
+                    const subFiles = new Map();
+                    collectFiles(srcPath, srcPath, subFiles);
+                    for (const [subRel, subAbs] of subFiles) {
+                        packageFiles.set(path.join('skills', entry, subRel), subAbs);
+                    }
                 }
             }
         }
@@ -184,6 +188,53 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
             });
         }
     }
+    // Apply skill migration logic: upgrade deprecate+add pairs to migrate actions
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    if (fs.existsSync(capJsonPath)) {
+        const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+        const migrations = capJson.skill_migrations;
+        if (migrations) {
+            for (const [newSkillName, oldFlatFilename] of Object.entries(migrations)) {
+                const oldRelPath = path.join('skills', oldFlatFilename);
+                const newPrefix = path.join('skills', newSkillName) + path.sep;
+                const oldStoredHash = storedHashes[oldRelPath];
+                if (!oldStoredHash)
+                    continue;
+                const oldFilePath = path.join(targetDir, oldRelPath);
+                const oldState = compareFileHash(oldFilePath, oldStoredHash);
+                if (oldState === 'modified') {
+                    // User modified the old file — skip new folder files, keep old file
+                    for (const action of actions) {
+                        if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
+                            action.action = 'skip';
+                            action.reason = `Skipped: old skill file '${oldRelPath}' was locally modified`;
+                        }
+                    }
+                    // Change deprecate to skip for the old file
+                    const oldAction = actions.find(a => a.relativePath === oldRelPath);
+                    if (oldAction) {
+                        oldAction.action = 'skip';
+                        oldAction.reason = 'Locally modified (migration skipped)';
+                    }
+                }
+                else if (oldState === 'match') {
+                    // Old file unmodified — convert deprecate to migrate
+                    const oldAction = actions.find(a => a.relativePath === oldRelPath);
+                    if (oldAction) {
+                        oldAction.action = 'migrate';
+                        oldAction.reason = `Migrated to folder: skills/${newSkillName}/`;
+                    }
+                    // Tag new folder files with the old path they're replacing
+                    for (const action of actions) {
+                        if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
+                            action.oldPath = oldRelPath;
+                        }
+                    }
+                }
+                // oldState === 'missing': old file already gone, add new files normally
+            }
+        }
+    }
     const upToDate = actions.length === 0;
     return {
         capability: capabilityName,
@@ -210,6 +261,7 @@ function executeUpdatePlan(plan, options = {}) {
         forcedOverwrite: [],
         skippedDeleted: [],
         pruned: [],
+        migrated: [],
         unchangedCount: plan.unchangedCount,
     };
     const pkgJson = JSON.parse(fs.readFileSync(path.join(plan.packageDir, 'package.json'), 'utf-8'));
@@ -294,6 +346,17 @@ function executeUpdatePlan(plan, options = {}) {
                 }
                 break;
             }
+            case 'migrate': {
+                const oldFilePath = path.join(plan.targetDir, action.relativePath);
+                if (fs.existsSync(oldFilePath)) {
+                    (0, safe_io_1.createBackup)(oldFilePath);
+                    fs.unlinkSync(oldFilePath);
+                }
+                delete newHashes[action.relativePath];
+                result.migrated.push(action.relativePath);
+                console.warn(`\x1b[33mWARN\x1b[0m Migrated skill: ${action.relativePath} → ${action.reason}`);
+                break;
+            }
         }
     }
     // Update .boop/config.json
@@ -314,10 +377,10 @@ function executeUpdatePlan(plan, options = {}) {
  * Resolve the source path for a relative file path from the package.
  */
 function resolveSourcePath(pkgDir, boopkit, relativePath) {
-    // Skills are stored as skills/<filename> in relPath
+    // Skills are stored as skills/<filename> or skills/<folder>/<file> in relPath
     if (relativePath.startsWith('skills/') && boopkit.skillsDir) {
-        const filename = relativePath.slice('skills/'.length);
-        const srcPath = path.join(pkgDir, boopkit.skillsDir, filename);
+        const subPath = relativePath.slice('skills/'.length);
+        const srcPath = path.join(pkgDir, boopkit.skillsDir, subPath);
         return fs.existsSync(srcPath) ? srcPath : null;
     }
     // Scaffold files
@@ -348,6 +411,9 @@ function collectFiles(baseDir, dir, result) {
  */
 function formatUpdateSummary(result) {
     const parts = [];
+    if (result.migrated && result.migrated.length > 0) {
+        parts.push(`migrated ${result.migrated.length} skill${result.migrated.length === 1 ? '' : 's'}`);
+    }
     const normalOverwrites = result.overwritten.length - result.forcedOverwrite.length;
     if (normalOverwrites > 0) {
         parts.push(`Updated ${normalOverwrites} file${normalOverwrites === 1 ? '' : 's'}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [
@@ -20,8 +20,8 @@
   "scripts": {
     "build": "tsc && node tools/generate-version-manifest.js",
     "build:caps": "./tools/build-caps.sh",
-    "publish" : "./tools/publish-caps.sh",
-    "release" : "./tools/publish-caps.sh --release",
+    "publish": "./tools/publish-caps.sh",
+    "release": "./tools/publish-caps.sh --release",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "test": "jest"

package/src/templates/kernel/AGENTS.md.hbs

@@ -9,8 +9,7 @@ Don't confirm a hypothesis (or take action) without observation - logs, tests, a
 
 ## How to work in this project
 
-0. **Read the skills index now.** Open [skills/index.md](skills/index.md) before doing anything else in this session. You need to know what skills exist before you can apply rule 1.
-1. **Check skills first.** Before coding, reviewing, testing, designing, debugging, filing issues, or proposing any non-trivial change, check [skills/index.md](skills/index.md) for a matching skill and follow its process. Do not rely on general knowledge when a project skill exists.
+1. **Prefer project skills over general knowledge.** When a skill matches your task — coding, reviewing, testing, designing, debugging, filing issues — follow its `SKILL.md` instead of working from memory. Skills live in `skills/` (each is a folder with a `SKILL.md`) and are also exposed at `.claude/skills/` for tooling that auto-discovers there. If your tooling does not auto-surface skills, list `skills/` and read each `SKILL.md`'s frontmatter (`name`, `description`) to find a match.
 2. **Use boop for capabilities.** Run `boop caps` to see what's available. To add features like database, auth, or other services and infrastructure, run `boop add <capability>` — don't install or wire things manually.
 3. **Check project status.** If the system isn't working or new capabilities need to be added run `boop status` to see what's configured and what needs attention.
 4. **Run `boop --help`** for the full command list.
@@ -21,7 +20,7 @@ Read [reference/boop-guide.ref.md](reference/boop-guide.ref.md) to understand ho
 
 ## Project layout
 - `src/` — source code
-- `skills/` — process skills for agents (read `skills/index.md`)
+- `skills/` — process skills for agents (each skill is a folder with a `SKILL.md`); also linked from `.claude/skills/` for Claude Code's built-in skill discovery
 - `reference/` — architecture and coding standards ("what exists now")
 - `specs/` — design docs and specifications ("future state")
 - `tests/` — `npm test` (Jest)