worclaude 1.8.0 → 2.0.0

package/src/commands/init.js

@@ -3,13 +3,13 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import { scaffoldFile, updateGitignore } from '../core/scaffolder.js';
 import {
+  computeFileHashes,
   createWorkflowMeta,
   getPackageVersion,
   readWorkflowMeta,
   writeWorkflowMeta,
 } from '../core/config.js';
-import { fileExists, writeFile, listFilesRecursive } from '../utils/file.js';
-import { hashFile } from '../utils/hash.js';
+import { fileExists, writeFile } from '../utils/file.js';
 import * as display from '../utils/display.js';
 import { promptProjectType } from '../prompts/project-type.js';
 import { promptTechStack } from '../prompts/tech-stack.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 {
@@ -349,17 +371,7 @@ function buildTemplateVariables(selections) {
 }
 
 async function computeAndWriteWorkflowMeta(projectRoot, selections, version) {
-  const fileHashes = {};
-  const claudeFiles = await listFilesRecursive(path.join(projectRoot, '.claude'));
-  for (const filePath of claudeFiles) {
-    const relativePath = path
-      .relative(path.join(projectRoot, '.claude'), filePath)
-      .split(path.sep)
-      .join('/');
-    if (relativePath !== 'workflow-meta.json' && relativePath !== 'settings.json') {
-      fileHashes[relativePath] = await hashFile(filePath);
-    }
-  }
+  const fileHashes = await computeFileHashes(projectRoot);
 
   const meta = createWorkflowMeta({
     version,
@@ -420,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
       );
@@ -430,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
       );
@@ -439,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';
@@ -478,6 +490,15 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     }
     spinner.text = 'Created docs/spec/';
 
+    // Create sessions directory for session persistence
+    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';
 
@@ -501,8 +522,12 @@ function displayFreshSuccess(selections, skipped) {
   display.success(`.claude/agents/${display.dimColor(`        ${totalAgents} agents`)}`);
   display.success(`.claude/commands/${display.dimColor(`      ${COMMAND_FILES.length} commands`)}`);
   display.success(`.claude/skills/${display.dimColor(`        ${totalSkills} skills`)}`);
+  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

@@ -3,6 +3,7 @@ import { execSync } from 'node:child_process';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import {
+  computeFileHashes,
   readWorkflowMeta,
   workflowMetaExists,
   writeWorkflowMeta,
@@ -12,10 +13,10 @@ import { createBackup } from '../core/backup.js';
 import { categorizeFiles } from '../core/file-categorizer.js';
 import { buildSettingsJson, mergeSettingsPermissionsAndHooks } from '../core/merger.js';
 import { readTemplate, updateGitignore } from '../core/scaffolder.js';
-import { hashFile } from '../utils/hash.js';
-import { writeFile, fileExists, listFilesRecursive } from '../utils/file.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);
@@ -211,16 +241,11 @@ export async function upgradeCommand() {
       spinner.text = 'Settings merged...';
     }
 
+    // Ensure sessions directory exists for session persistence
+    await writeFile(path.join(projectRoot, '.claude', 'sessions', '.gitkeep'), '');
+
     // Recompute file hashes
-    const fileHashes = {};
-    const claudeDir = path.join(projectRoot, '.claude');
-    const allFiles = await listFilesRecursive(claudeDir);
-    for (const filePath of allFiles) {
-      const relKey = path.relative(claudeDir, filePath).split(path.sep).join('/');
-      if (relKey !== 'workflow-meta.json' && relKey !== 'settings.json') {
-        fileHashes[relKey] = await hashFile(filePath);
-      }
-    }
+    const fileHashes = await computeFileHashes(projectRoot);
 
     // Ensure .gitignore has worclaude entries
     await updateGitignore(projectRoot);
@@ -252,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/config.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { readFile, writeFile, fileExists } from '../utils/file.js';
+import { readFile, writeFile, fileExists, listFilesRecursive } from '../utils/file.js';
+import { hashFile } from '../utils/hash.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
@@ -57,3 +58,20 @@ export async function writeWorkflowMeta(projectRoot, meta) {
   const metaPath = path.join(projectRoot, '.claude', 'workflow-meta.json');
   await writeFile(metaPath, JSON.stringify(meta, null, 2));
 }
+
+export async function computeFileHashes(projectRoot) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const allFiles = await listFilesRecursive(claudeDir);
+  const fileHashes = {};
+  for (const filePath of allFiles) {
+    const relKey = path.relative(claudeDir, filePath).split(path.sep).join('/');
+    if (
+      relKey !== 'workflow-meta.json' &&
+      relKey !== 'settings.json' &&
+      !relKey.startsWith('sessions/')
+    ) {
+      fileHashes[relKey] = await hashFile(filePath);
+    }
+  }
+  return fileHashes;
+}

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');
   }
 }
 
@@ -238,36 +240,50 @@ export async function mergeSettingsPermissionsAndHooks(projectRoot, workflowSett
     if (!existing.hooks[category]) existing.hooks[category] = [];
 
     const existingEntries = existing.hooks[category];
-    const existingMatchers = new Map(existingEntries.map((h) => [h.matcher, h]));
+    const existingByMatcher = new Map();
+    for (const entry of existingEntries) {
+      if (!existingByMatcher.has(entry.matcher)) {
+        existingByMatcher.set(entry.matcher, []);
+      }
+      existingByMatcher.get(entry.matcher).push(entry);
+    }
+    const matched = new Set();
 
     for (const workflowEntry of workflowHooks[category]) {
-      if (existingMatchers.has(workflowEntry.matcher)) {
-        const existingEntry = existingMatchers.get(workflowEntry.matcher);
-
-        // If hooks are identical, skip — no conflict to resolve
-        const existingCmd = existingEntry.hooks?.[0]?.command || '';
-        const workflowCmd = workflowEntry.hooks?.[0]?.command || '';
-        if (existingCmd === workflowCmd) {
-          continue;
-        }
+      const candidates = existingByMatcher.get(workflowEntry.matcher) || [];
+      const workflowCmd = workflowEntry.hooks?.[0]?.command || '';
+
+      // Try exact match first (identical command = skip)
+      const exactMatch = candidates.find(
+        (c) => !matched.has(c) && (c.hooks?.[0]?.command || '') === workflowCmd
+      );
+      if (exactMatch) {
+        matched.add(exactMatch);
+        continue;
+      }
+
+      // Try unmatched candidate with same matcher (conflict)
+      const conflictCandidate = candidates.find((c) => !matched.has(c));
+      if (conflictCandidate) {
+        matched.add(conflictCandidate);
 
         // Tier 3: conflict — ask user
-        const resolution = await promptHookConflict(category, existingEntry, workflowEntry);
+        const resolution = await promptHookConflict(category, conflictCandidate, workflowEntry);
 
         if (resolution === 'replace') {
-          const idx = existingEntries.indexOf(existingEntry);
+          const idx = existingEntries.indexOf(conflictCandidate);
           existingEntries[idx] = workflowEntry;
           report.hookConflicts.push(
             `${category} "${workflowEntry.matcher}": replaced with workflow hook`
           );
         } else if (resolution === 'chain') {
-          const idx = existingEntries.indexOf(existingEntry);
+          const idx = existingEntries.indexOf(conflictCandidate);
           existingEntries[idx] = {
-            matcher: existingEntry.matcher,
+            matcher: conflictCandidate.matcher,
             hooks: [
               {
                 type: 'command',
-                command: `${existingEntry.hooks[0].command} && ${workflowEntry.hooks[0].command}`,
+                command: `${conflictCandidate.hooks[0].command} && ${workflowEntry.hooks[0].command}`,
               },
             ],
           };
@@ -276,7 +292,7 @@ export async function mergeSettingsPermissionsAndHooks(projectRoot, workflowSett
           report.hookConflicts.push(`${category} "${workflowEntry.matcher}": kept existing hook`);
         }
       } else {
-        // Tier 1: no conflict — append
+        // Tier 1: no match — append
         existingEntries.push(workflowEntry);
         report.added.hooks++;
       }
@@ -422,6 +438,10 @@ export async function performMerge(
   if (spinner) spinner.start();
 
   await mergeMcpJson(projectRoot, existingScan);
+
+  // Ensure sessions directory exists for session persistence
+  await writeFile(path.join(projectRoot, '.claude', 'sessions', '.gitkeep'), '');
+
   await mergeDocSpecs(projectRoot, existingScan, variables, selections, report);
 
   // Stop spinner before CLAUDE.md merge — interactive prompts for section selection

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);
       }
@@ -181,7 +181,14 @@ export async function cleanGitignore(projectRoot) {
   const content = await readFile(gitignorePath);
   const lines = content.split(/\r?\n/);
 
-  const REMOVE_LINES = new Set(['# Worclaude (generated workflow files)', '.claude/']);
+  const REMOVE_LINES = new Set([
+    '# 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()));