worclaude 1.8.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.8.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;
 }
 

package/src/index.js

@@ -9,6 +9,7 @@ import { backupCommand } from './commands/backup.js';
 import { restoreCommand } from './commands/restore.js';
 import { diffCommand } from './commands/diff.js';
 import { deleteCommand } from './commands/delete.js';
+import { doctorCommand } from './commands/doctor.js';
 
 const program = new Command();
 
@@ -52,4 +53,9 @@ program
   .description('Remove worclaude workflow from project')
   .action(deleteCommand);
 
+program
+  .command('doctor')
+  .description('Validate workflow installation health')
+  .action(doctorCommand);
+
 program.parse();

package/templates/commands/commit-push-pr.md

@@ -6,20 +6,42 @@ Do not add Co-Authored-By trailers or AI-generated footers to commits or PR desc
 Feature branches contain ONLY the task changes. Do NOT touch shared-state
 files (see git-conventions.md for the canonical list).
 
-1. Stage all changes: git add -A
-2. Write a clear, conventional commit message
-3. Push to the current branch
-4. Create a PR targeting develop: gh pr create --base develop
-5. Include in PR description: title, changes, testing done, reviewer notes
+1. Write a session summary to .claude/sessions/:
+   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
+   - Content format:
+     ```
+     # Session: {date}
+     **Branch:** {current branch}
+     **Task:** {one-line summary of what was worked on}
+
+     ## Completed
+     - {what was done, 3-5 bullet points}
+
+     ## Files Modified
+     - {list key files changed, from git diff --name-only}
+
+     ## Notes for Next Session
+     - {anything the next session should know}
+     ```
+   - Keep it concise — this is for machine consumption at session start,
+     not a detailed report
+2. Stage all changes: git add -A
+3. Write a clear, conventional commit message
+4. Push to the current branch
+5. Create a PR targeting develop: gh pr create --base develop
+6. Include in PR description: title, changes, testing done, reviewer notes
 
 ## On develop
 
 Only used for release merges after /sync has been run.
 
-1. Stage all changes: git add -A
-2. Write a clear, conventional commit message
-3. Push to develop
-4. Create a PR targeting main: gh pr create --base main
+1. Write a session summary to .claude/sessions/:
+   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
+   - Same format as the feature branch session summary above
+2. Stage all changes: git add -A
+3. Write a clear, conventional commit message
+4. Push to develop
+5. Create a PR targeting main: gh pr create --base main
 
 ## On any other branch
 

package/templates/commands/end.md

@@ -11,7 +11,11 @@ Do NOT update PROGRESS.md — /sync handles that on develop after merging.
    - What is left to do
    - Decisions or context the next session needs
    - Files that were modified
-3. git add -A
-4. git commit -m "wip: handoff for [task description]"
+3. Write a session summary to .claude/sessions/:
+   - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
+   - Same format as /commit-push-pr session summaries
+   - Mark the task as "IN PROGRESS" since /end means work is unfinished
+4. git add -A
+5. git commit -m "wip: handoff for [task description]"
    Use exactly this message format — no trailers or Co-Authored-By lines.
-5. git push
+6. git push

package/templates/commands/refactor-clean.md

@@ -1,44 +1,52 @@
-Run a focused cleanup pass on the codebase. Delegates to the
-code-simplifier agent for structural improvements.
+Run a focused cleanup pass on recently changed code. This command
+runs INLINE in your current session — it reads uncommitted changes,
+improves them in place, and leaves everything uncommitted for
+/commit-push-pr.
 
-## What Gets Cleaned
+Do NOT spawn a subagent or worktree for this. Work directly on
+the files in the current working directory.
 
-1. **Dead code removal**
-   - Unused imports and variables
-   - Commented-out code blocks (git has history)
-   - Unreachable branches after early returns
-   - Functions defined but never called
+## What to Clean
 
-2. **Duplication reduction**
-   - Identical or near-identical code blocks → extract shared function
-   - Repeated validation patterns → centralize
-   - Copy-pasted error handling → extract helper
+1. **Dead code** — unused imports, commented-out blocks, unreachable branches,
+   uncalled functions. Delete them — git has history.
 
-3. **Complexity reduction**
-   - Functions over 30 lines → split by responsibility
-   - Nesting deeper than 3 levels → early returns, guard clauses
-   - Long parameter lists → group into option objects
+2. **Duplication** — identical or near-identical code blocks → extract shared
+   function. Repeated validation → centralize. Copy-pasted error handling →
+   extract helper.
 
-4. **Consistency fixes**
-   - Naming that doesn't match project conventions
-   - Mixed patterns in the same module
-   - Inconsistent error handling approaches
+3. **Complexity** — functions over 30 lines → split by responsibility. Nesting
+   deeper than 3 levels → early returns, guard clauses. Long parameter lists →
+   group into option objects.
+
+4. **Consistency** — naming that doesn't match project conventions. Mixed patterns
+   in the same module. Inconsistent error handling.
 
 ## Process
 
-1. Focus on recently changed files first: `git diff --name-only HEAD~5`
-2. Make one improvement at a time
-3. Run tests after EVERY change — if tests fail, revert
-4. Commit each improvement separately with `refactor:` prefix
+1. Identify changed files: `git diff --name-only` (unstaged) and
+   `git diff --cached --name-only` (staged). If no changes, check
+   `git diff --name-only HEAD~5` for recent commits.
+2. Read each changed file fully — understand context before changing
+3. Check CLAUDE.md for project-specific conventions
+4. Make one improvement at a time, smallest meaningful change first
+5. Run the full test suite after EVERY change
+6. If tests fail, revert immediately — your change broke behavior
+
+## Confidence Filtering
+
+- Only change if >80% confident it improves the code
+- Skip stylistic preferences unless they violate CLAUDE.md
+- Consolidate: "5 functions have duplicated validation" → one fix, not five
+- Prioritize changes that reduce complexity or eliminate bugs
 
 ## Rules
-- Never change behavior — only structure and readability
-- Never combine cleanup with feature work
-- If a file has low test coverage, do NOT refactor it — flag it instead
-- Skip stylistic preferences unless they violate CLAUDE.md conventions
+- Never change behavior — if tests break, you changed behavior, revert
+- Never combine cleanup with feature work in logic — only clean what exists
+- If a file has low test coverage, flag it but do NOT refactor it
+- Do not commit — leave changes uncommitted for /commit-push-pr
 
 ## When to Use
-- After completing a feature, before the PR
+- After implementing a feature, before /verify and /commit-push-pr
 - Weekly maintenance pass
-- When code-simplifier or review-changes flagged issues
-- Before a major release
+- When /review-changes flagged issues you want to fix

package/templates/commands/start.md

@@ -1,11 +1,71 @@
-Read docs/spec/PROGRESS.md to understand current state.
-Read .claude/skills/agent-routing.md for agent usage guidance.
+The SessionStart hook has already loaded CLAUDE.md, PROGRESS.md,
+and the most recent session summary into context.
+
+Your job is to supplement that with drift detection and additional context.
+
+## 1. Drift Detection
+
+Show what changed since the last session so there are no surprises.
+Present raw signals only — do NOT interpret or warn.
+
+Run these commands and report the output:
+
+```bash
+# How many commits since last session file?
+LAST_SESSION=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1)
+if [ -n "$LAST_SESSION" ]; then
+  SESSION_DATE=$(echo "$LAST_SESSION" | grep -oP '\d{4}-\d{2}-\d{2}')
+  echo "Commits since last session ($SESSION_DATE):"
+  git log --oneline --since="$SESSION_DATE" 2>/dev/null | head -15
+else
+  echo "No previous session found. Recent commits:"
+  git log --oneline -10 2>/dev/null
+fi
+```
+
+Report as:
+
+```
+## Drift Since Last Session
+- **X commits** since {date}
+- {one-liner per commit, max 15}
+
+Current branch: {branch name}
+```
+
+If there are 0 commits since the last session, just say:
+
+```
+## Drift Since Last Session
+No new commits since last session ({date}). Branch: {branch name}
+```
 
-Check for handoff files from previous sessions:
-- Look in docs/handoffs/ for any HANDOFF*.md files
-  (both HANDOFF-{branch}-{date}.md and legacy HANDOFF_{date}.md)
+Do NOT add commentary like "you should review these" or "there may be
+conflicts." Just the facts.
+
+## 2. Check for Handoff Files
+
+Look in docs/handoffs/ for any HANDOFF*.md files:
+
+- Both HANDOFF-{branch}-{date}.md and legacy HANDOFF_{date}.md
 - Prioritize files matching the current branch name
 - If found, read them for context and report what was handed off
 
-If an active implementation prompt exists, read it.
-Report: what was last completed, what's next, any blockers.
+## 3. Load Agent Routing
+
+Read .claude/skills/agent-routing.md for agent usage guidance.
+
+## 4. Check for Active Prompt Files
+
+If any PHASE-*-PROMPT.md or implementation prompt file exists in the
+project root, read it and note it.
+
+## 5. Report
+
+Summarize:
+
+- Drift status (from step 1)
+- Any handoffs found (from step 2)
+- What was last completed (from session summary loaded by hook)
+- What's next (from PROGRESS.md loaded by hook)
+- Any blockers or notes

package/templates/core/claude-md.md

@@ -23,6 +23,7 @@ See `.claude/skills/` — load only what's relevant:
 - verification.md — How to verify work
 - testing.md — Test philosophy and patterns
 - subagent-usage.md — When and how to use subagents
+- security-checklist.md — Security review checklist
 - agent-routing.md — When and how to use each installed agent (READ EVERY SESSION)
 {project_specific_skills}
 

package/templates/settings/base.json

@@ -43,14 +43,21 @@
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "{formatter_command}"
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {formatter_command}"
         }]
       },
       {
         "matcher": "Stop",
         "hooks": [{
           "type": "command",
-          "command": "{notification_command}"
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {notification_command}"
+        }]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in strict) ;; *) exit 0;; esac; npx tsc --noEmit 2>/dev/null || echo '[Hook] TypeScript errors detected' >&2"
         }]
       }
     ],
@@ -62,6 +69,15 @@
           "command": "cat CLAUDE.md && cat docs/spec/PROGRESS.md 2>/dev/null || true"
         }]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "echo '=== CLAUDE.md ==='; cat CLAUDE.md 2>/dev/null; echo; echo '=== PROGRESS ==='; cat docs/spec/PROGRESS.md 2>/dev/null; echo; echo '=== LAST SESSION ==='; f=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1); if [ -n \"$f\" ]; then cat \"$f\"; else echo 'No previous session found'; fi; echo; echo '=== BRANCH ==='; git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'not a git repo'"
+        }]
+      }
     ]
   }
 }

package/templates/skills/universal/context-management.md

@@ -61,6 +61,61 @@ cat CLAUDE.md && cat docs/spec/PROGRESS.md 2>/dev/null || true
 This ensures you never lose your bearings after compaction. The hook fires
 automatically — you don't need to re-read these files manually.
 
+## Session Persistence
+
+The workflow automatically maintains session continuity:
+
+### SessionStart Hook (automatic)
+When a new Claude Code session opens, a hook automatically injects:
+- CLAUDE.md — project conventions and rules
+- PROGRESS.md — current project state
+- The most recent session summary from `.claude/sessions/`
+
+You don't need to manually re-read these. The hook handles it.
+Use /start for additional context (handoff files, agent routing).
+
+### Session Summaries
+Session summaries are written to `.claude/sessions/` by:
+- `/commit-push-pr` — writes a summary before committing (completed work)
+- `/end` — writes a summary before the handoff commit (in-progress work)
+
+These are local files (gitignored) that bridge the gap between sessions.
+They're automatically picked up by the next session's SessionStart hook.
+
+### The Continuity Chain
+```
+Session 1: work → /commit-push-pr → writes session summary → push
+Session 2: SessionStart hook → reads summary → knows what happened → /start for extras
+```
+
+If the session summary is missing or stale, /start still reads PROGRESS.md
+and handoff files as fallback. The system degrades gracefully.
+
+## Hook Profiles
+
+Control which hooks fire via the `WORCLAUDE_HOOK_PROFILE` environment variable:
+
+| Profile | Hooks Active | Use When |
+|---------|-------------|----------|
+| `minimal` | SessionStart, PostCompact only | Exploring, learning, minimal overhead |
+| `standard` | All hooks (default) | Normal development |
+| `strict` | All hooks + TypeScript checking | Pre-release, team CI, maximum safety |
+
+Set in your shell:
+```bash
+export WORCLAUDE_HOOK_PROFILE=minimal   # lightweight
+export WORCLAUDE_HOOK_PROFILE=standard  # default (same as unset)
+export WORCLAUDE_HOOK_PROFILE=strict    # maximum enforcement
+```
+
+Or per-session:
+```bash
+WORCLAUDE_HOOK_PROFILE=strict claude
+```
+
+The default is `standard` if the variable is not set. You don't need to do
+anything for normal development — the default just works.
+
 ## Gotchas
 
 - Compacting doesn't free as much context as you think. If you've read 20 large files,