worclaude 1.7.0 → 1.9.0

package/README.md

@@ -10,7 +10,7 @@
 
 [Full Documentation](https://sefaertunc.github.io/Worclaude/) · [Interactive Demo](https://sefaertunc.github.io/Worclaude/demo/) · [npm](https://www.npmjs.com/package/worclaude)
 
-Worclaude scaffolds a complete Claude Code workflow into any project in seconds. It implements all [tips by Boris Cherny](https://www.howborisusesclaudecode.com/) — the creator of Claude Code at Anthropic — as a reusable, upgradable scaffold. One `init` command gives you 23 agents, 12 slash commands, 13 skills, hooks, permissions, and a CLAUDE.md template tuned for your tech stack. Whether you're starting fresh or adding structure to an existing project, Worclaude handles the setup so you can focus on building.
+Worclaude scaffolds a complete Claude Code workflow into any project in seconds. It implements all [tips by Boris Cherny](https://www.howborisusesclaudecode.com/) — the creator of Claude Code at Anthropic — as a reusable, upgradable scaffold. One `init` command gives you 25 agents, 16 slash commands, 14 skills, hooks, permissions, and a CLAUDE.md template tuned for your tech stack. Whether you're starting fresh or adding structure to an existing project, Worclaude handles the setup so you can focus on building.
 
 ---
 
@@ -18,25 +18,27 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 
 `worclaude init` installs a production-ready Claude Code workflow:
 
-**Agents (23 total)**
+**Agents (25 total)**
 
 - 5 universal: plan-reviewer, code-simplifier, test-writer, build-validator, verify-app
-- 18 optional across 6 categories: Backend, Frontend, DevOps, Quality, Documentation, Data/AI
+- 20 optional across 6 categories: Backend, Frontend, DevOps, Quality, Documentation, Data/AI
 
-**Slash Commands (12)**
-`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup` `/sync` `/conflict-resolver`
+**Slash Commands (16)**
+`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage`
 
-**Skills (13)**
+**Skills (14)**
 
-- 9 universal knowledge files (testing, git conventions, context management, and more)
+- 10 universal knowledge files (testing, git conventions, context management, security, and more)
 - 3 project-specific templates filled in by `/setup`
 - 1 generated agent routing guide (dynamically built from your agent selection)
 
 **Hooks**
 
+- SessionStart context injection (auto-loads CLAUDE.md, PROGRESS.md, and last session on launch)
 - PostToolUse formatter (auto-formats on every write)
 - PostCompact re-injection (re-reads key files after compaction)
 - Stop notifications (desktop alert when Claude finishes)
+- Hook profiles (`WORCLAUDE_HOOK_PROFILE`) — minimal, standard, or strict
 
 **Configuration**
 
@@ -70,6 +72,8 @@ For parallel tasks, run Claude with worktrees: `claude --worktree --tmux`
 | `worclaude backup`  | Create timestamped backup of workflow files    |
 | `worclaude restore` | Restore from a previous backup                 |
 | `worclaude diff`    | Compare current setup vs latest version        |
+| `worclaude delete`  | Remove worclaude workflow from project         |
+| `worclaude doctor`  | Validate workflow installation health          |
 
 The `init` command detects existing setups and merges intelligently — no data is overwritten without your confirmation. Use `upgrade` to pull in new features while preserving your customizations.
 

package/package.json

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

package/src/commands/doctor.js

@@ -0,0 +1,319 @@
+import path from 'node:path';
+import { readWorkflowMeta, workflowMetaExists, getPackageVersion } from '../core/config.js';
+import { hashFile } from '../utils/hash.js';
+import { fileExists, readFile, listFilesRecursive } from '../utils/file.js';
+import {
+  UNIVERSAL_AGENTS,
+  COMMAND_FILES,
+  UNIVERSAL_SKILLS,
+  TEMPLATE_SKILLS,
+} from '../data/agents.js';
+import * as display from '../utils/display.js';
+
+// Check categories
+const PASS = 'pass';
+const WARN = 'warn';
+const FAIL = 'fail';
+
+function result(status, label, detail) {
+  return { status, label, detail };
+}
+
+function printResult(r) {
+  const icon =
+    r.status === PASS
+      ? display.green('✓')
+      : r.status === WARN
+        ? display.yellow('⚠')
+        : display.red('✗');
+  const text = r.status === PASS ? display.dimColor(r.label) : display.white(r.label);
+  console.log(`  ${icon} ${text}`);
+  if (r.detail && r.status !== PASS) {
+    console.log(`    ${display.dimColor(r.detail)}`);
+  }
+}
+
+async function checkWorkflowMeta(projectRoot) {
+  if (!(await workflowMetaExists(projectRoot))) {
+    return result(FAIL, 'workflow-meta.json', 'Missing — run `worclaude init` to create');
+  }
+  const meta = await readWorkflowMeta(projectRoot);
+  if (!meta) {
+    return result(FAIL, 'workflow-meta.json', 'Exists but contains invalid JSON');
+  }
+  if (!meta.version || !meta.projectTypes || !meta.techStack) {
+    return result(
+      WARN,
+      'workflow-meta.json',
+      'Missing required fields (version, projectTypes, or techStack)'
+    );
+  }
+  return result(PASS, 'workflow-meta.json', null);
+}
+
+async function checkClaudeMd(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (!(await fileExists(claudeMdPath))) {
+    return result(FAIL, 'CLAUDE.md', 'Missing — run `worclaude init` to create');
+  }
+  try {
+    const content = await readFile(claudeMdPath);
+    const lines = content.split('\n').length;
+    if (lines < 10) {
+      return result(
+        WARN,
+        'CLAUDE.md',
+        `Only ${lines} lines — may be a stub. Run /setup to fill it in.`
+      );
+    }
+    return result(PASS, 'CLAUDE.md', null);
+  } catch {
+    return result(FAIL, 'CLAUDE.md', 'Exists but could not be read');
+  }
+}
+
+async function checkSettingsJson(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  if (!(await fileExists(settingsPath))) {
+    return result(FAIL, 'settings.json', 'Missing — run `worclaude init` to create');
+  }
+  try {
+    const raw = await readFile(settingsPath);
+    const settings = JSON.parse(raw);
+
+    const issues = [];
+    if (!settings.permissions?.allow || settings.permissions.allow.length === 0) {
+      issues.push('no permissions configured');
+    }
+    if (!settings.hooks || Object.keys(settings.hooks).length === 0) {
+      issues.push('no hooks configured');
+    }
+    if (!settings.hooks?.PostCompact) {
+      issues.push('missing PostCompact hook (context recovery after compaction)');
+    }
+    if (!settings.hooks?.SessionStart) {
+      issues.push('missing SessionStart hook (session persistence)');
+    }
+
+    if (issues.length > 0) {
+      return result(WARN, 'settings.json', issues.join('; '));
+    }
+    return result(PASS, 'settings.json', null);
+  } catch {
+    return result(FAIL, 'settings.json', 'Contains invalid JSON');
+  }
+}
+
+async function checkAgents(projectRoot, meta) {
+  const agentsDir = path.join(projectRoot, '.claude', 'agents');
+  const results = [];
+
+  // Check universal agents
+  for (const agent of UNIVERSAL_AGENTS) {
+    const agentPath = path.join(agentsDir, `${agent}.md`);
+    if (!(await fileExists(agentPath))) {
+      results.push(result(FAIL, `agents/${agent}.md`, 'Missing universal agent'));
+    }
+  }
+
+  // Check selected optional agents from meta
+  if (meta?.optionalAgents) {
+    for (const agent of meta.optionalAgents) {
+      const agentPath = path.join(agentsDir, `${agent}.md`);
+      if (!(await fileExists(agentPath))) {
+        results.push(result(WARN, `agents/${agent}.md`, 'Selected optional agent is missing'));
+      }
+    }
+  }
+
+  if (results.length === 0) {
+    const totalExpected = UNIVERSAL_AGENTS.length + (meta?.optionalAgents?.length || 0);
+    results.push(result(PASS, `agents/ (${totalExpected} expected, all present)`, null));
+  }
+
+  return results;
+}
+
+async function checkCommands(projectRoot) {
+  const commandsDir = path.join(projectRoot, '.claude', 'commands');
+  const missing = [];
+
+  for (const cmd of COMMAND_FILES) {
+    const cmdPath = path.join(commandsDir, `${cmd}.md`);
+    if (!(await fileExists(cmdPath))) {
+      missing.push(cmd);
+    }
+  }
+
+  if (missing.length === 0) {
+    return [result(PASS, `commands/ (${COMMAND_FILES.length} expected, all present)`, null)];
+  }
+  return missing.map((cmd) => result(WARN, `commands/${cmd}.md`, 'Missing command'));
+}
+
+async function checkSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+  const missing = [];
+  const allExpected = [...UNIVERSAL_SKILLS, ...TEMPLATE_SKILLS, 'agent-routing'];
+
+  for (const skill of allExpected) {
+    const skillPath = path.join(skillsDir, `${skill}.md`);
+    if (!(await fileExists(skillPath))) {
+      missing.push(skill);
+    }
+  }
+
+  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'));
+}
+
+async function checkHashIntegrity(projectRoot, meta) {
+  if (!meta?.fileHashes || Object.keys(meta.fileHashes).length === 0) {
+    return [result(WARN, 'File integrity', 'No file hashes in workflow-meta.json — cannot verify')];
+  }
+
+  let modified = 0;
+  let missing = 0;
+  let intact = 0;
+
+  for (const [relPath, storedHash] of Object.entries(meta.fileHashes)) {
+    const fullPath = path.join(projectRoot, '.claude', ...relPath.split('/'));
+    if (!(await fileExists(fullPath))) {
+      missing++;
+    } else {
+      const currentHash = await hashFile(fullPath);
+      if (currentHash !== storedHash) {
+        modified++;
+      } else {
+        intact++;
+      }
+    }
+  }
+
+  const total = Object.keys(meta.fileHashes).length;
+  const results = [];
+
+  if (missing > 0) {
+    results.push(result(FAIL, `File integrity: ${missing}/${total} files missing`, null));
+  }
+  if (modified > 0) {
+    results.push(
+      result(PASS, `File integrity: ${modified}/${total} files customized (expected)`, null)
+    );
+  }
+  if (results.length === 0) {
+    results.push(
+      result(PASS, `File integrity: all ${total} files present (${intact} intact)`, null)
+    );
+  }
+
+  return results;
+}
+
+async function checkSessions(projectRoot) {
+  const sessionsDir = path.join(projectRoot, '.claude', 'sessions');
+  if (!(await fileExists(sessionsDir))) {
+    return result(
+      WARN,
+      'sessions/',
+      "Directory missing — session persistence won't work. Run `worclaude init` or create .claude/sessions/ manually."
+    );
+  }
+  return result(PASS, 'sessions/', null);
+}
+
+async function checkDocSpecs(projectRoot) {
+  const results = [];
+  const progressPath = path.join(projectRoot, 'docs', 'spec', 'PROGRESS.md');
+  const specPath = path.join(projectRoot, 'docs', 'spec', 'SPEC.md');
+
+  if (!(await fileExists(progressPath))) {
+    results.push(
+      result(WARN, 'docs/spec/PROGRESS.md', 'Missing — /start and /sync depend on this')
+    );
+  }
+  if (!(await fileExists(specPath))) {
+    results.push(result(WARN, 'docs/spec/SPEC.md', 'Missing — plan-reviewer references this'));
+  }
+
+  if (results.length === 0) {
+    results.push(result(PASS, 'docs/spec/ (PROGRESS.md + SPEC.md present)', null));
+  }
+  return results;
+}
+
+async function checkPendingReviewFiles(projectRoot) {
+  const pending = [];
+  try {
+    const claudeDir = path.join(projectRoot, '.claude');
+    const allFiles = await listFilesRecursive(claudeDir);
+    for (const fp of allFiles) {
+      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
+      if (rel.endsWith('.workflow-ref.md')) {
+        pending.push(rel);
+      }
+    }
+  } catch {
+    // .claude dir might not exist
+  }
+
+  const suggestionsPath = path.join(projectRoot, 'CLAUDE.md.workflow-suggestions');
+  if (await fileExists(suggestionsPath)) {
+    pending.push('CLAUDE.md.workflow-suggestions');
+  }
+
+  if (pending.length === 0) {
+    return [result(PASS, 'No pending review files', null)];
+  }
+  return pending.map((f) => result(WARN, `Pending review: ${f}`, 'Merge or delete this file'));
+}
+
+export async function doctorCommand() {
+  const projectRoot = process.cwd();
+  const version = await getPackageVersion();
+
+  display.newline();
+  display.sectionHeader('WORCLAUDE DOCTOR');
+  display.dim(`CLI version: v${version}`);
+  display.newline();
+
+  // Core files
+  display.barLine(display.white('Core Files'));
+  const metaResult = await checkWorkflowMeta(projectRoot);
+  printResult(metaResult);
+
+  const meta = await readWorkflowMeta(projectRoot);
+
+  printResult(await checkClaudeMd(projectRoot));
+  printResult(await checkSettingsJson(projectRoot));
+  printResult(await checkSessions(projectRoot));
+  display.newline();
+
+  // Components
+  display.barLine(display.white('Components'));
+  for (const r of await checkAgents(projectRoot, meta)) printResult(r);
+  for (const r of await checkCommands(projectRoot)) printResult(r);
+  for (const r of await checkSkills(projectRoot)) printResult(r);
+  display.newline();
+
+  // Docs
+  display.barLine(display.white('Documentation'));
+  for (const r of await checkDocSpecs(projectRoot)) printResult(r);
+  display.newline();
+
+  // Integrity
+  display.barLine(display.white('Integrity'));
+  for (const r of await checkHashIntegrity(projectRoot, meta)) printResult(r);
+  for (const r of await checkPendingReviewFiles(projectRoot)) printResult(r);
+  display.newline();
+
+  // Summary
+  if (metaResult.status === FAIL) {
+    display.error('Workflow is not installed. Run `worclaude init` to set up.');
+  } else {
+    display.success('Doctor complete. Review any warnings above.');
+  }
+  display.newline();
+}

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';
@@ -349,17 +349,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,
@@ -478,6 +468,10 @@ 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/';
+
     await computeAndWriteWorkflowMeta(projectRoot, selections, version);
     spinner.text = 'Created .claude/workflow-meta.json';
 
@@ -501,6 +495,7 @@ 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 (skipped.progressMd) {

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,8 +13,7 @@ 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';
 
@@ -211,16 +211,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);

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/merger.js

@@ -238,36 +238,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 +290,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 +436,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/remover.js

@@ -181,7 +181,12 @@ 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/workflow-meta.json',
+  ]);
 
   const filtered = lines.filter((line) => !REMOVE_LINES.has(line.trim()));
 

package/src/core/scaffolder.js

@@ -46,7 +46,7 @@ export async function scaffoldDirectory(templateDir, destDir, variables, project
 
 export async function updateGitignore(projectDir) {
   const gitignorePath = path.join(projectDir, '.gitignore');
-  const entries = ['.claude/', '.claude-backup-*/'];
+  const entries = ['.claude/sessions/', '.claude/workflow-meta.json', '.claude-backup-*/'];
   const header = '# Worclaude (generated workflow files)';
 
   let content = '';
@@ -56,12 +56,27 @@ export async function updateGitignore(projectDir) {
     if (err.code !== 'ENOENT') throw err;
   }
 
+  // Migrate: remove old blanket .claude/ entry (and its header) if present
+  const lines = content.split(/\r?\n/);
+  const hasBlanketEntry = lines.some((l) => l.trim() === '.claude/');
+  if (hasBlanketEntry) {
+    const filtered = lines.filter((l) => {
+      const t = l.trim();
+      return t !== '.claude/' && t !== header;
+    });
+    content = filtered.join('\n');
+  }
+
   const missing = entries.filter((entry) => !content.includes(entry));
-  if (missing.length === 0) return false;
+  if (missing.length === 0 && !hasBlanketEntry) return false;
+
+  if (missing.length > 0) {
+    const needsNewline = content.length > 0 && !content.endsWith('\n');
+    const addition = (needsNewline ? '\n' : '') + '\n' + header + '\n' + missing.join('\n') + '\n';
+    content += addition;
+  }
 
-  const needsNewline = content.length > 0 && !content.endsWith('\n');
-  const addition = (needsNewline ? '\n' : '') + '\n' + header + '\n' + missing.join('\n') + '\n';
-  await fs.appendFile(gitignorePath, addition);
+  await fs.writeFile(gitignorePath, content);
   return true;
 }