worclaude 1.9.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "CLI tool that scaffolds a comprehensive Claude Code workflow into any project",
   "type": "module",
   "bin": {

package/src/commands/backup.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import ora from 'ora';
 import { createBackup } from '../core/backup.js';
-import { fileExists, dirExists, listFiles } from '../utils/file.js';
+import { fileExists, dirExists, listFiles, listSkillDirs } from '../utils/file.js';
 import * as display from '../utils/display.js';
 
 export async function backupCommand() {
@@ -33,11 +33,13 @@ export async function backupCommand() {
   if (await dirExists(claudeBackup)) {
     const agents = await listFiles(path.join(claudeBackup, 'agents'));
     const commands = await listFiles(path.join(claudeBackup, 'commands'));
-    const skills = await listFiles(path.join(claudeBackup, 'skills'));
+    const skillFiles = await listFiles(path.join(claudeBackup, 'skills'));
+    const skillDirs = await listSkillDirs(path.join(claudeBackup, 'skills'));
+    const skillCount = skillDirs.length + skillFiles.length;
     const parts = [];
     if (agents.length > 0) parts.push(`${agents.length} agents`);
     if (commands.length > 0) parts.push(`${commands.length} commands`);
-    if (skills.length > 0) parts.push(`${skills.length} skills`);
+    if (skillCount > 0) parts.push(`${skillCount} skills`);
     contents.push(`.claude/ (${parts.join(', ')})`);
   }
 

package/src/commands/doctor.js

@@ -1,3 +1,4 @@
+import fs from 'fs-extra';
 import path from 'node:path';
 import { readWorkflowMeta, workflowMetaExists, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
@@ -72,6 +73,48 @@ async function checkClaudeMd(projectRoot) {
   }
 }
 
+async function checkClaudeMdSize(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (!(await fileExists(claudeMdPath))) {
+    return []; // Already covered by existing checkClaudeMd
+  }
+  try {
+    const content = await readFile(claudeMdPath);
+    const charCount = content.length;
+    const WARN_THRESHOLD = 30000;
+    const FAIL_THRESHOLD = 38000;
+    const HARD_LIMIT = 40000;
+
+    if (charCount > FAIL_THRESHOLD) {
+      return [
+        result(
+          FAIL,
+          `CLAUDE.md size: ${charCount.toLocaleString()} chars`,
+          `Exceeds recommended limit (${FAIL_THRESHOLD.toLocaleString()}/${HARD_LIMIT.toLocaleString()}). Claude Code caps at ${HARD_LIMIT.toLocaleString()} chars. Move domain-specific content to conditional skills with paths frontmatter.`
+        ),
+      ];
+    }
+    if (charCount > WARN_THRESHOLD) {
+      return [
+        result(
+          WARN,
+          `CLAUDE.md size: ${charCount.toLocaleString()} chars`,
+          `Approaching limit (${WARN_THRESHOLD.toLocaleString()}/${HARD_LIMIT.toLocaleString()}). Consider moving content to skills.`
+        ),
+      ];
+    }
+    return [
+      result(
+        PASS,
+        `CLAUDE.md size: ${charCount.toLocaleString()} chars (limit: ${HARD_LIMIT.toLocaleString()})`,
+        null
+      ),
+    ];
+  } catch {
+    return [];
+  }
+}
+
 async function checkSettingsJson(projectRoot) {
   const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
   if (!(await fileExists(settingsPath))) {
@@ -134,6 +177,62 @@ async function checkAgents(projectRoot, meta) {
   return results;
 }
 
+async function checkAgentDescription(projectRoot) {
+  const agentsDir = path.join(projectRoot, '.claude', 'agents');
+  const results = [];
+
+  try {
+    const entries = await fs.readdir(agentsDir, { withFileTypes: true });
+    const mdFiles = entries.filter((e) => e.isFile() && e.name.endsWith('.md'));
+
+    for (const file of mdFiles) {
+      const filePath = path.join(agentsDir, file.name);
+      const content = await readFile(filePath);
+
+      // Parse YAML frontmatter
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!frontmatterMatch) {
+        results.push(
+          result(
+            FAIL,
+            `agents/${file.name}`,
+            'No YAML frontmatter — agent is invisible to Claude Code'
+          )
+        );
+        continue;
+      }
+
+      const frontmatter = frontmatterMatch[1];
+      const hasName = /^name:\s*.+/m.test(frontmatter);
+      const hasDescription = /^description:\s*.+/m.test(frontmatter);
+
+      if (!hasName) {
+        results.push(
+          result(FAIL, `agents/${file.name}`, 'Missing required "name" field in frontmatter')
+        );
+      } else if (!hasDescription) {
+        results.push(
+          result(
+            FAIL,
+            `agents/${file.name}`,
+            'Missing required "description" field — agent is invisible to Claude Code\'s /agents and routing'
+          )
+        );
+      }
+    }
+
+    if (results.length === 0 && mdFiles.length > 0) {
+      results.push(
+        result(PASS, `agents/ frontmatter (${mdFiles.length} agents have required fields)`, null)
+      );
+    }
+  } catch {
+    // agents/ doesn't exist — covered by existing component checks
+  }
+
+  return results;
+}
+
 async function checkCommands(projectRoot) {
   const commandsDir = path.join(projectRoot, '.claude', 'commands');
   const missing = [];
@@ -157,7 +256,7 @@ async function checkSkills(projectRoot) {
   const allExpected = [...UNIVERSAL_SKILLS, ...TEMPLATE_SKILLS, 'agent-routing'];
 
   for (const skill of allExpected) {
-    const skillPath = path.join(skillsDir, `${skill}.md`);
+    const skillPath = path.join(skillsDir, skill, 'SKILL.md');
     if (!(await fileExists(skillPath))) {
       missing.push(skill);
     }
@@ -166,7 +265,49 @@ async function checkSkills(projectRoot) {
   if (missing.length === 0) {
     return [result(PASS, `skills/ (${allExpected.length} expected, all present)`, null)];
   }
-  return missing.map((s) => result(WARN, `skills/${s}.md`, 'Missing skill'));
+  return missing.map((s) => result(WARN, `skills/${s}/SKILL.md`, 'Missing skill'));
+}
+
+async function checkSkillFormat(projectRoot) {
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+  const results = [];
+
+  try {
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const flatMdFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => e.name);
+
+    if (flatMdFiles.length > 0) {
+      results.push(
+        result(
+          FAIL,
+          `skills/ has ${flatMdFiles.length} flat .md file(s)`,
+          `Flat .md files in .claude/skills/ are invisible to Claude Code. Expected format: skill-name/SKILL.md. Run \`worclaude upgrade\` to migrate. Files: ${flatMdFiles.join(', ')}`
+        )
+      );
+    }
+
+    // Also check directory-format skills exist
+    const skillDirs = entries.filter((e) => e.isDirectory());
+    let validDirSkills = 0;
+    for (const dir of skillDirs) {
+      const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
+      if (await fileExists(skillMd)) {
+        validDirSkills++;
+      }
+    }
+
+    if (validDirSkills > 0 && flatMdFiles.length === 0) {
+      results.push(
+        result(PASS, `skills/ format (${validDirSkills} directory-format skills)`, null)
+      );
+    }
+  } catch {
+    // skills/ doesn't exist — covered by existing component checks
+  }
+
+  return results;
 }
 
 async function checkHashIntegrity(projectRoot, meta) {
@@ -287,6 +428,7 @@ export async function doctorCommand() {
   const meta = await readWorkflowMeta(projectRoot);
 
   printResult(await checkClaudeMd(projectRoot));
+  for (const r of await checkClaudeMdSize(projectRoot)) printResult(r);
   printResult(await checkSettingsJson(projectRoot));
   printResult(await checkSessions(projectRoot));
   display.newline();
@@ -294,8 +436,10 @@ export async function doctorCommand() {
   // Components
   display.barLine(display.white('Components'));
   for (const r of await checkAgents(projectRoot, meta)) printResult(r);
+  for (const r of await checkAgentDescription(projectRoot)) printResult(r);
   for (const r of await checkCommands(projectRoot)) printResult(r);
   for (const r of await checkSkills(projectRoot)) printResult(r);
+  for (const r of await checkSkillFormat(projectRoot)) printResult(r);
   display.newline();
 
   // Docs

package/src/commands/init.js

@@ -185,11 +185,27 @@ async function runAgents(selections) {
   return { ...selections, selectedAgents };
 }
 
+async function runMemoryMd(selections) {
+  const { includeMemoryMd } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'includeMemoryMd',
+      message: 'Scaffold a MEMORY.md template? (for Claude Code memory system)',
+      choices: [
+        { name: 'No', value: false },
+        { name: 'Yes', value: true },
+      ],
+    },
+  ]);
+  return { ...selections, includeMemoryMd };
+}
+
 const STEP_RUNNERS = {
   projectInfo: runProjectInfo,
   projectType: runProjectType,
   techStack: runTechStack,
   agents: runAgents,
+  memoryMd: runMemoryMd,
 };
 
 // --- Confirmation ---
@@ -253,6 +269,7 @@ async function runInteractivePrompts(projectRoot) {
     languages: [],
     useDocker: false,
     selectedAgents: [],
+    includeMemoryMd: false,
   };
 
   let confirmed = false;
@@ -264,6 +281,7 @@ async function runInteractivePrompts(projectRoot) {
       selections = await runProjectType(selections);
       selections = await runTechStack(selections);
       selections = await runAgents(selections);
+      selections = await runMemoryMd(selections);
       firstRun = false;
     }
 
@@ -279,6 +297,7 @@ async function runInteractivePrompts(projectRoot) {
         languages: [],
         useDocker: false,
         selectedAgents: [],
+        includeMemoryMd: false,
       };
       display.newline();
       display.info('Starting over...');
@@ -287,6 +306,7 @@ async function runInteractivePrompts(projectRoot) {
       selections = await runProjectType(selections);
       selections = await runTechStack(selections);
       selections = await runAgents(selections);
+      selections = await runMemoryMd(selections);
     } else if (confirmation === 'adjust') {
       const { step } = await inquirer.prompt([
         {
@@ -332,7 +352,9 @@ function buildTemplateVariables(selections) {
 
   const commandsText = buildCommandsBlock(languages, useDocker);
 
-  const skillsLines = TEMPLATE_SKILLS.map((s) => `- ${s}.md — Run /setup to fill automatically`);
+  const skillsLines = TEMPLATE_SKILLS.map(
+    (s) => `- ${s}/SKILL.md — Run /setup to fill automatically`
+  );
   const skillsText = skillsLines.join('\n');
 
   return {
@@ -410,7 +432,7 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     for (const skill of UNIVERSAL_SKILLS) {
       await scaffoldFile(
         `skills/universal/${skill}.md`,
-        path.join('.claude', 'skills', `${skill}.md`),
+        path.join('.claude', 'skills', skill, 'SKILL.md'),
         {},
         projectRoot
       );
@@ -420,7 +442,7 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     for (const skill of TEMPLATE_SKILLS) {
       await scaffoldFile(
         `skills/templates/${skill}.md`,
-        path.join('.claude', 'skills', `${skill}.md`),
+        path.join('.claude', 'skills', skill, 'SKILL.md'),
         variables,
         projectRoot
       );
@@ -429,7 +451,7 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
 
     const agentRoutingContent = buildAgentRoutingSkill(selectedAgents, projectTypes);
     await writeFile(
-      path.join(projectRoot, '.claude', 'skills', 'agent-routing.md'),
+      path.join(projectRoot, '.claude', 'skills', 'agent-routing', 'SKILL.md'),
       agentRoutingContent
     );
     spinner.text = 'Created agent routing guide';
@@ -472,6 +494,11 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     await writeFile(path.join(projectRoot, '.claude', 'sessions', '.gitkeep'), '');
     spinner.text = 'Created .claude/sessions/';
 
+    if (selections.includeMemoryMd) {
+      await scaffoldFile('core/memory-md.md', 'MEMORY.md', {}, projectRoot);
+      spinner.text = 'Created MEMORY.md';
+    }
+
     await computeAndWriteWorkflowMeta(projectRoot, selections, version);
     spinner.text = 'Created .claude/workflow-meta.json';
 
@@ -498,6 +525,9 @@ function displayFreshSuccess(selections, skipped) {
   display.success('.claude/sessions/');
   display.success('.mcp.json');
   display.success('.gitignore');
+  if (selections.includeMemoryMd) {
+    display.success('MEMORY.md');
+  }
   if (skipped.progressMd) {
     display.dim('  docs/spec/PROGRESS.md — already exists, skipped');
   }

package/src/commands/upgrade.js

@@ -16,6 +16,7 @@ import { readTemplate, updateGitignore } from '../core/scaffolder.js';
 import { writeFile, fileExists } from '../utils/file.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
 import * as display from '../utils/display.js';
+import { semverLessThan, migrateSkillFormat, patchAgentDescriptions } from '../core/migration.js';
 
 function selfUpdate(latestVersion) {
   const spinner = ora(`Updating worclaude to v${latestVersion}...`).start();
@@ -181,6 +182,35 @@ export async function upgradeCommand() {
     const backupDir = await createBackup(projectRoot);
     spinner.text = 'Backup created, applying updates...';
 
+    // v2.0.0 migrations (version-gated)
+    let skillReport = { migrated: 0, skipped: 0, names: [] };
+    let agentReport = { autoPatched: 0, prompted: 0, declined: 0, skipped: [] };
+
+    if (semverLessThan(installedVersion, '2.0.0')) {
+      spinner.text = 'Running v2.0.0 migrations...';
+
+      // Item 14: Skill format migration (flat .md → skill-name/SKILL.md)
+      skillReport = await migrateSkillFormat(projectRoot, meta);
+
+      // Item 15: Agent frontmatter patch (add missing description)
+      spinner.stop();
+      agentReport = await patchAgentDescriptions(projectRoot, meta, async (agentName) => {
+        const { patch } = await inquirer.prompt([
+          {
+            type: 'list',
+            name: 'patch',
+            message: `Agent "${agentName}" has been customized. Add missing description field?`,
+            choices: [
+              { name: 'Yes', value: true },
+              { name: 'No, skip', value: false },
+            ],
+          },
+        ]);
+        return patch;
+      });
+      spinner.start('Applying updates...');
+    }
+
     // Auto-update files
     for (const { key, templatePath } of categories.autoUpdate) {
       const content = await readTemplate(templatePath);
@@ -247,6 +277,22 @@ export async function upgradeCommand() {
         `Customized:  ${categories.modified.length} files ${display.dimColor('(no updates needed)')}`
       );
     }
+    if (skillReport.migrated > 0) {
+      display.barLine(`Migrated:    ${skillReport.migrated} skills to directory format`);
+    }
+    const patchedTotal = agentReport.autoPatched + agentReport.prompted;
+    if (patchedTotal > 0) {
+      const detail =
+        agentReport.autoPatched > 0 && agentReport.prompted > 0
+          ? ` (${agentReport.autoPatched} auto, ${agentReport.prompted} confirmed)`
+          : '';
+      display.barLine(`Patched:     ${patchedTotal} agents with description${detail}`);
+    }
+    if (agentReport.skipped.length > 0) {
+      display.barLine(
+        `Skipped:     ${agentReport.skipped.length} user-created agents ${display.dimColor(`(${agentReport.skipped.join(', ')})`)}`
+      );
+    }
     display.newline();
     display.barLine(display.dimColor(`Backup: ${path.basename(backupDir)}/`));
 

package/src/core/detector.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { fileExists, dirExists, readFile, listFiles } from '../utils/file.js';
+import { fileExists, dirExists, readFile, listFiles, listSkillDirs } from '../utils/file.js';
 import { workflowMetaExists } from './config.js';
 
 export async function detectScenario(projectRoot) {
@@ -35,6 +35,7 @@ export async function scanExistingSetup(projectRoot) {
     hasSettingsJson: await fileExists(path.join(projectRoot, '.claude', 'settings.json')),
     hasMcpJson: await fileExists(path.join(projectRoot, '.mcp.json')),
     existingSkills: await listFiles(path.join(projectRoot, '.claude', 'skills')),
+    existingSkillDirs: await listSkillDirs(path.join(projectRoot, '.claude', 'skills')),
     existingAgents: await listFiles(path.join(projectRoot, '.claude', 'agents')),
     existingCommands: await listFiles(path.join(projectRoot, '.claude', 'commands')),
     hasProgressMd: await fileExists(path.join(projectRoot, 'docs', 'spec', 'PROGRESS.md')),

package/src/core/file-categorizer.js

@@ -41,18 +41,18 @@ export async function buildTemplateHashMap() {
     map[key] = { templatePath, hash: hashContent(content), type: 'command' };
   }
 
-  // Universal skills: key = skills/{name}.md, templatePath = skills/universal/{name}.md
+  // Universal skills: key = skills/{name}/SKILL.md, templatePath = skills/universal/{name}.md
   for (const name of UNIVERSAL_SKILLS) {
-    const key = `skills/${name}.md`;
+    const key = `skills/${name}/SKILL.md`;
     const templatePath = `skills/universal/${name}.md`;
     const content = await readTemplate(templatePath);
     map[key] = { templatePath, hash: hashContent(content), type: 'universal-skill' };
   }
 
-  // Template skills: key = skills/{name}.md, templatePath = skills/templates/{name}.md
+  // Template skills: key = skills/{name}/SKILL.md, templatePath = skills/templates/{name}.md
   // These contain {variable} placeholders — raw hash won't match stored (substituted) hash
   for (const name of TEMPLATE_SKILLS) {
-    const key = `skills/${name}.md`;
+    const key = `skills/${name}/SKILL.md`;
     const templatePath = `skills/templates/${name}.md`;
     const content = await readTemplate(templatePath);
     map[key] = { templatePath, hash: hashContent(content), type: 'template-skill' };

package/src/core/merger.js

@@ -111,39 +111,41 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
   ];
 
   for (const skill of allSkills) {
-    const filename = `${skill.name}.md`;
-    const destDir = path.join('.claude', 'skills');
+    const destPath = path.join('.claude', 'skills', skill.name, 'SKILL.md');
+    const existsAsDir = existingScan.existingSkillDirs.includes(skill.name);
+    const existsAsFlat = existingScan.existingSkills.includes(`${skill.name}.md`);
 
-    if (existingScan.existingSkills.includes(filename)) {
+    if (existsAsDir || existsAsFlat) {
       // Tier 2: conflict — save as .workflow-ref.md
       await scaffoldFile(
         skill.templatePath,
-        path.join(destDir, `${skill.name}.workflow-ref.md`),
+        path.join('.claude', 'skills', skill.name, 'SKILL.workflow-ref.md'),
         skill.vars,
         projectRoot
       );
-      report.conflicts.skills.push(filename);
+      report.conflicts.skills.push(skill.name);
     } else {
       // Tier 1: add
-      await scaffoldFile(skill.templatePath, path.join(destDir, filename), skill.vars, projectRoot);
-      report.added.skills.push(filename);
+      await scaffoldFile(skill.templatePath, destPath, skill.vars, projectRoot);
+      report.added.skills.push(skill.name);
     }
   }
 
-  // Generated skill: agent-routing.md
-  const routingFilename = 'agent-routing.md';
+  // Generated skill: agent-routing
   const skillsDir = path.join('.claude', 'skills');
   const routingContent = buildAgentRoutingSkill(selections.selectedAgents, selections.projectTypes);
+  const routingExistsAsDir = existingScan.existingSkillDirs.includes('agent-routing');
+  const routingExistsAsFlat = existingScan.existingSkills.includes('agent-routing.md');
 
-  if (existingScan.existingSkills.includes(routingFilename)) {
+  if (routingExistsAsDir || routingExistsAsFlat) {
     await writeFile(
-      path.join(projectRoot, skillsDir, 'agent-routing.workflow-ref.md'),
+      path.join(projectRoot, skillsDir, 'agent-routing', 'SKILL.workflow-ref.md'),
       routingContent
     );
-    report.conflicts.skills.push(routingFilename);
+    report.conflicts.skills.push('agent-routing');
   } else {
-    await writeFile(path.join(projectRoot, skillsDir, routingFilename), routingContent);
-    report.added.skills.push(routingFilename);
+    await writeFile(path.join(projectRoot, skillsDir, 'agent-routing', 'SKILL.md'), routingContent);
+    report.added.skills.push('agent-routing');
   }
 }
 

package/src/core/migration.js

@@ -0,0 +1,144 @@
+import path from 'node:path';
+import { AGENT_CATALOG } from '../data/agents.js';
+import { readFile, writeFile, dirExists, moveFile, listFiles } from '../utils/file.js';
+import { hashFile } from '../utils/hash.js';
+
+// --- Version comparison ---
+
+export function semverLessThan(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return true;
+    if ((pa[i] || 0) > (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+// --- Agent description lookup ---
+
+const UNIVERSAL_AGENT_DESCRIPTIONS = {
+  'plan-reviewer': 'Reviews implementation plans for specificity, gaps, and executability',
+  'code-simplifier': 'Reviews changed code and simplifies overly complex implementations',
+  'test-writer': 'Writes comprehensive, meaningful tests for recently changed code',
+  'build-validator': 'Validates that the project builds and all tests pass',
+  'verify-app':
+    'Verifies the running application end-to-end — tests actual behavior, not just code reading',
+};
+
+function getAgentDescription(agentName) {
+  if (UNIVERSAL_AGENT_DESCRIPTIONS[agentName]) {
+    return UNIVERSAL_AGENT_DESCRIPTIONS[agentName];
+  }
+  if (AGENT_CATALOG[agentName]) {
+    return AGENT_CATALOG[agentName].description;
+  }
+  return null;
+}
+
+// --- Item 14: Skill Format Migration ---
+
+export async function migrateSkillFormat(projectRoot, meta) {
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+  const report = { migrated: 0, skipped: 0, names: [] };
+
+  if (!(await dirExists(skillsDir))) return report;
+
+  const files = await listFiles(skillsDir);
+  const mdFiles = files.filter((f) => f.endsWith('.md') && !f.endsWith('.workflow-ref.md'));
+  const refFiles = files.filter((f) => f.endsWith('.workflow-ref.md'));
+
+  for (const file of mdFiles) {
+    const skillName = file.replace(/\.md$/, '');
+    const newDir = path.join(skillsDir, skillName);
+
+    if (await dirExists(newDir)) {
+      report.skipped++;
+      continue;
+    }
+
+    await moveFile(path.join(skillsDir, file), path.join(newDir, 'SKILL.md'));
+
+    // Move corresponding .workflow-ref.md if exists
+    const refFile = `${skillName}.workflow-ref.md`;
+    if (refFiles.includes(refFile)) {
+      await moveFile(path.join(skillsDir, refFile), path.join(newDir, 'SKILL.workflow-ref.md'));
+    }
+
+    // Update meta hash keys
+    if (meta?.fileHashes) {
+      const oldKey = `skills/${file}`;
+      const newKey = `skills/${skillName}/SKILL.md`;
+      if (meta.fileHashes[oldKey] !== undefined) {
+        meta.fileHashes[newKey] = meta.fileHashes[oldKey];
+        delete meta.fileHashes[oldKey];
+      }
+
+      const oldRefKey = `skills/${refFile}`;
+      const newRefKey = `skills/${skillName}/SKILL.workflow-ref.md`;
+      if (meta.fileHashes[oldRefKey] !== undefined) {
+        meta.fileHashes[newRefKey] = meta.fileHashes[oldRefKey];
+        delete meta.fileHashes[oldRefKey];
+      }
+    }
+
+    report.migrated++;
+    report.names.push(skillName);
+  }
+
+  return report;
+}
+
+// --- Item 15: Agent Frontmatter Patch ---
+
+export async function patchAgentDescriptions(projectRoot, meta, promptFn) {
+  const agentsDir = path.join(projectRoot, '.claude', 'agents');
+  const report = { autoPatched: 0, prompted: 0, declined: 0, skipped: [] };
+
+  if (!(await dirExists(agentsDir))) return report;
+
+  const files = await listFiles(agentsDir);
+  const mdFiles = files.filter((f) => f.endsWith('.md') && !f.endsWith('.workflow-ref.md'));
+
+  for (const file of mdFiles) {
+    const filePath = path.join(agentsDir, file);
+    const content = await readFile(filePath);
+
+    // Check if frontmatter exists
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) continue;
+
+    // Skip if description already present
+    if (/^description:\s*.+/m.test(frontmatterMatch[1])) continue;
+
+    const agentName = file.replace(/\.md$/, '');
+    const description = getAgentDescription(agentName);
+
+    if (!description) {
+      report.skipped.push(agentName);
+      continue;
+    }
+
+    // Check if user has modified the file
+    const storedHash = meta?.fileHashes?.[`agents/${file}`];
+    const currentHash = await hashFile(filePath);
+    const isModified = storedHash && currentHash !== storedHash;
+
+    if (isModified && promptFn) {
+      const confirmed = await promptFn(agentName);
+      if (!confirmed) {
+        report.declined++;
+        continue;
+      }
+      report.prompted++;
+    } else {
+      report.autoPatched++;
+    }
+
+    // Insert description after name line
+    const updated = content.replace(/^(name:\s*.+)$/m, `$1\ndescription: "${description}"`);
+    await writeFile(filePath, updated);
+  }
+
+  return report;
+}

package/src/core/remover.js

@@ -118,7 +118,7 @@ export async function removeTrackedFiles(projectRoot, fileKeys) {
   for (const subdir of ['agents', 'commands', 'skills']) {
     const dirPath = path.join(claudeDir, subdir);
     if (await dirExists(dirPath)) {
-      const remaining = await listFiles(dirPath);
+      const remaining = await listFilesRecursive(dirPath);
       if (remaining.length === 0) {
         await removeDirectory(dirPath);
       }
@@ -185,7 +185,9 @@ export async function cleanGitignore(projectRoot) {
     '# Worclaude (generated workflow files)',
     '.claude/',
     '.claude/sessions/',
+    '.claude/settings.local.json',
     '.claude/workflow-meta.json',
+    '.claude/worktrees/',
   ]);
 
   const filtered = lines.filter((line) => !REMOVE_LINES.has(line.trim()));