worclaude 1.3.9 → 1.5.0

package/package.json

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

package/src/commands/delete.js

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import { workflowMetaExists, readWorkflowMeta } from '../core/config.js';
+import { createBackup } from '../core/backup.js';
+import {
+  classifyClaudeFiles,
+  detectRootFiles,
+  removeTrackedFiles,
+  removeRootFiles,
+  cleanGitignore,
+} from '../core/remover.js';
+import * as display from '../utils/display.js';
+
+export async function deleteCommand() {
+  const projectRoot = process.cwd();
+
+  // Pre-flight: ensure worclaude is installed
+  if (!(await workflowMetaExists(projectRoot))) {
+    display.error('No worclaude workflow found in this project.');
+    display.info('Run `worclaude init` to set up a workflow first.');
+    return;
+  }
+
+  const meta = await readWorkflowMeta(projectRoot);
+  if (!meta) {
+    display.error('workflow-meta.json is corrupted or unreadable.');
+    display.info('You may need to manually remove the .claude/ directory.');
+    return;
+  }
+
+  display.sectionHeader('DELETE WORKFLOW');
+  display.newline();
+
+  // Step 1: Mode selection
+  const { mode } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'mode',
+      message: 'What would you like to do?',
+      choices: [
+        { name: 'Remove workflow from this project', value: 'project' },
+        { name: 'Remove workflow and uninstall worclaude globally', value: 'global' },
+        new inquirer.Separator(),
+        { name: '← Cancel', value: 'cancel' },
+      ],
+    },
+  ]);
+
+  if (mode === 'cancel') {
+    display.info('Delete cancelled.');
+    return;
+  }
+
+  // Step 2: Classify files
+  const classification = await classifyClaudeFiles(projectRoot, meta);
+  const rootFiles = await detectRootFiles(projectRoot);
+
+  // Step 3: Show preview
+  display.newline();
+  display.barLine('Workflow files in .claude/:');
+  if (classification.safeToDelete.length > 0) {
+    display.barLine(
+      `  ${display.green('✓')} ${classification.safeToDelete.length} unmodified files (safe to remove)`
+    );
+  }
+  if (classification.modified.length > 0) {
+    display.barLine(
+      `  ${display.yellow('~')} ${classification.modified.length} files you've customized`
+    );
+    for (const key of classification.modified) {
+      display.barLine(`      ${display.yellow('~')} .claude/${key}`);
+    }
+  }
+  if (classification.userOwned.length > 0) {
+    display.barLine(
+      `  ${display.blue('●')} ${classification.userOwned.length} user-added files (will NOT be touched)`
+    );
+  }
+
+  // Step 4: Handle modified files
+  let filesToDelete = [...classification.safeToDelete];
+
+  if (classification.modified.length > 0) {
+    display.newline();
+    const { modifiedAction } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'modifiedAction',
+        message: `${classification.modified.length} file(s) have been customized. What should we do?`,
+        choices: [
+          { name: "Delete them too (they'll be in the backup)", value: 'delete' },
+          { name: 'Keep them in .claude/', value: 'keep' },
+        ],
+      },
+    ]);
+
+    if (modifiedAction === 'delete') {
+      filesToDelete.push(...classification.modified);
+    }
+  }
+
+  // Step 5: Handle root-level files (settings.json + project root files)
+  let rootFilesToDelete = [];
+
+  if (rootFiles.length > 0) {
+    display.newline();
+    display.info('These files were created or modified by worclaude but may contain your work:');
+    for (const f of rootFiles) {
+      display.dim(`    ${f.label}`);
+    }
+    display.newline();
+
+    const { rootAction } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'rootAction',
+        message: 'What would you like to do with these files?',
+        choices: [
+          { name: 'Keep all (recommended)', value: 'keep' },
+          { name: 'Let me choose which to remove', value: 'choose' },
+          { name: 'Remove all', value: 'remove' },
+        ],
+        default: 0,
+      },
+    ]);
+
+    if (rootAction === 'remove') {
+      rootFilesToDelete = rootFiles.map((f) => f.path);
+    } else if (rootAction === 'choose') {
+      const { selected } = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'selected',
+          message: 'Select files to remove:',
+          choices: rootFiles.map((f) => ({ name: f.label, value: f.path })),
+        },
+      ]);
+      rootFilesToDelete = selected;
+    }
+  }
+
+  // Step 6: Final confirmation
+  const totalDeletions = filesToDelete.length + rootFilesToDelete.length;
+
+  if (totalDeletions === 0) {
+    display.newline();
+    display.info('No files selected for removal.');
+    return;
+  }
+
+  display.newline();
+  display.warn(`This will permanently delete ${totalDeletions} file(s).`);
+  display.dim('  A backup will be created first.');
+  display.newline();
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'confirm',
+      message: 'Confirm deletion?',
+      choices: [
+        { name: 'Yes, delete', value: true },
+        { name: 'No, cancel', value: false },
+      ],
+      default: 1,
+    },
+  ]);
+
+  if (!confirm) {
+    display.info('Delete cancelled.');
+    return;
+  }
+
+  // Step 7: Execute
+  const spinner = ora('Creating backup...').start();
+
+  try {
+    const backupDir = await createBackup(projectRoot);
+    spinner.text = 'Removing workflow files...';
+
+    // Remove .claude/ tracked files
+    const claudeRemoved = await removeTrackedFiles(projectRoot, filesToDelete);
+
+    // Remove root files
+    let rootRemoved = 0;
+    if (rootFilesToDelete.length > 0) {
+      rootRemoved = await removeRootFiles(projectRoot, rootFilesToDelete);
+    }
+
+    // Clean .gitignore
+    const gitignoreCleaned = await cleanGitignore(projectRoot);
+
+    spinner.succeed('Workflow removed!');
+
+    // Step 8: Report
+    display.newline();
+    if (claudeRemoved > 0) {
+      display.success(`Removed ${claudeRemoved} workflow files from .claude/`);
+    }
+    if (rootRemoved > 0) {
+      display.success(`Removed ${rootRemoved} root-level file(s)`);
+    }
+    if (gitignoreCleaned) {
+      display.success('Cleaned up .gitignore');
+    }
+
+    const keptModified = classification.modified.filter((f) => !filesToDelete.includes(f));
+    if (keptModified.length > 0) {
+      display.info(`Kept ${keptModified.length} customized file(s) in .claude/`);
+    }
+    if (classification.userOwned.length > 0) {
+      display.info(`Kept ${classification.userOwned.length} user-added file(s) in .claude/`);
+    }
+
+    const keptRootFiles = rootFiles.filter((f) => !rootFilesToDelete.includes(f.path));
+    if (keptRootFiles.length > 0) {
+      display.info(`Kept: ${keptRootFiles.map((f) => f.label).join(', ')}`);
+    }
+
+    display.newline();
+    display.dim(`  Backup: ${path.basename(backupDir)}/`);
+
+    // Step 9: Global uninstall hint
+    if (mode === 'global') {
+      display.newline();
+      display.info('To uninstall worclaude CLI globally, run:');
+      display.dim('  npm uninstall -g worclaude');
+    }
+  } catch (err) {
+    spinner.fail('Delete failed.');
+    display.error(err.message);
+  }
+}

package/src/commands/init.js

@@ -676,6 +676,14 @@ export async function initCommand() {
   const version = await getPackageVersion();
   display.banner(version);
 
+  // Windows guidance: hooks require Git Bash
+  if (process.platform === 'win32') {
+    display.info(
+      'Windows detected \u2014 hooks require Git for Windows (Git Bash). See: https://gitforwindows.org'
+    );
+    display.newline();
+  }
+
   // Step 3: If existing project, show detection report and confirm
   let existingScan = null;
   let backupPath = null;

package/src/core/backup.js

@@ -37,6 +37,16 @@ export async function createBackup(projectRoot) {
     await copyFile(mcpPath, path.join(backupDir, '.mcp.json'));
   }
 
+  const progressPath = path.join(projectRoot, 'docs', 'spec', 'PROGRESS.md');
+  if (await fileExists(progressPath)) {
+    await copyFile(progressPath, path.join(backupDir, 'docs', 'spec', 'PROGRESS.md'));
+  }
+
+  const specPath = path.join(projectRoot, 'docs', 'spec', 'SPEC.md');
+  if (await fileExists(specPath)) {
+    await copyFile(specPath, path.join(backupDir, 'docs', 'spec', 'SPEC.md'));
+  }
+
   return backupDir;
 }
 

package/src/core/remover.js

@@ -0,0 +1,213 @@
+import path from 'node:path';
+import { hashFile } from '../utils/hash.js';
+import {
+  fileExists,
+  dirExists,
+  readFile,
+  writeFile,
+  listFiles,
+  listFilesRecursive,
+  removeDirectory,
+} from '../utils/file.js';
+
+/**
+ * Classify .claude/ files into safe-to-delete, modified, missing, and user-owned.
+ * Uses only on-disk hash vs. stored hash (no template hash comparison).
+ */
+export async function classifyClaudeFiles(projectRoot, meta) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const fileHashes = meta.fileHashes || {};
+
+  const safeToDelete = [];
+  const modified = [];
+  const missing = [];
+  const userOwned = [];
+
+  // Classify tracked files by comparing on-disk hash to stored hash
+  for (const [key, storedHash] of Object.entries(fileHashes)) {
+    const filePath = path.join(claudeDir, ...key.split('/'));
+    if (!(await fileExists(filePath))) {
+      missing.push(key);
+      continue;
+    }
+    const currentHash = await hashFile(filePath);
+    if (currentHash === storedHash) {
+      safeToDelete.push(key);
+    } else {
+      modified.push(key);
+    }
+  }
+
+  // workflow-meta.json is always worclaude's — safe to delete
+  if (await fileExists(path.join(claudeDir, 'workflow-meta.json'))) {
+    safeToDelete.push('workflow-meta.json');
+  }
+
+  // Scan disk for files not in fileHashes
+  const allTrackedKeys = new Set([
+    ...Object.keys(fileHashes),
+    'workflow-meta.json',
+    'settings.json',
+  ]);
+  const allDiskFiles = await listFilesRecursive(claudeDir);
+
+  for (const fp of allDiskFiles) {
+    const relKey = path.relative(claudeDir, fp).split(path.sep).join('/');
+    if (allTrackedKeys.has(relKey)) continue;
+
+    // .workflow-ref.md files are upgrade artifacts — safe to delete
+    if (relKey.endsWith('.workflow-ref.md')) {
+      safeToDelete.push(relKey);
+    } else {
+      userOwned.push(relKey);
+    }
+  }
+
+  return { safeToDelete, modified, missing, userOwned };
+}
+
+/**
+ * Detect root-level files that worclaude creates or modifies.
+ * settings.json is included here since it may contain user customizations.
+ */
+export async function detectRootFiles(projectRoot) {
+  const candidates = [
+    {
+      path: path.join('.claude', 'settings.json'),
+      label: '.claude/settings.json (permissions & hooks)',
+    },
+    { path: 'CLAUDE.md', label: 'CLAUDE.md' },
+    { path: '.mcp.json', label: '.mcp.json' },
+    { path: path.join('docs', 'spec', 'PROGRESS.md'), label: 'docs/spec/PROGRESS.md' },
+    { path: path.join('docs', 'spec', 'SPEC.md'), label: 'docs/spec/SPEC.md' },
+  ];
+
+  const found = [];
+  for (const c of candidates) {
+    if (await fileExists(path.join(projectRoot, c.path))) {
+      found.push(c);
+    }
+  }
+
+  // CLAUDE.md.workflow-suggestions is an upgrade artifact
+  const suggestionsPath = 'CLAUDE.md.workflow-suggestions';
+  if (await fileExists(path.join(projectRoot, suggestionsPath))) {
+    found.push({ path: suggestionsPath, label: suggestionsPath });
+  }
+
+  return found;
+}
+
+/**
+ * Delete specified files from .claude/ and clean up empty directories.
+ * Uses fs.remove (via removeDirectory) which handles both files and directories.
+ */
+export async function removeTrackedFiles(projectRoot, fileKeys) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  let removedCount = 0;
+
+  for (const key of fileKeys) {
+    const filePath = path.join(claudeDir, ...key.split('/'));
+    if (await fileExists(filePath)) {
+      await removeDirectory(filePath);
+      removedCount++;
+    }
+  }
+
+  // Clean up empty subdirectories
+  for (const subdir of ['agents', 'commands', 'skills']) {
+    const dirPath = path.join(claudeDir, subdir);
+    if (await dirExists(dirPath)) {
+      const remaining = await listFiles(dirPath);
+      if (remaining.length === 0) {
+        await removeDirectory(dirPath);
+      }
+    }
+  }
+
+  // Remove .claude/ itself only if completely empty
+  if (await dirExists(claudeDir)) {
+    const remaining = await listFilesRecursive(claudeDir);
+    if (remaining.length === 0) {
+      await removeDirectory(claudeDir);
+    }
+  }
+
+  return removedCount;
+}
+
+/**
+ * Delete specified root-level files and clean up empty docs directories.
+ */
+export async function removeRootFiles(projectRoot, filePaths) {
+  let removedCount = 0;
+
+  for (const relPath of filePaths) {
+    const fullPath = path.join(projectRoot, relPath);
+    if (await fileExists(fullPath)) {
+      await removeDirectory(fullPath);
+      removedCount++;
+    }
+  }
+
+  // Clean up empty docs/spec/ then docs/
+  const specDir = path.join(projectRoot, 'docs', 'spec');
+  if (await dirExists(specDir)) {
+    const remaining = await listFiles(specDir);
+    if (remaining.length === 0) {
+      await removeDirectory(specDir);
+
+      const docsDir = path.join(projectRoot, 'docs');
+      if (await dirExists(docsDir)) {
+        const docsRemaining = await listFilesRecursive(docsDir);
+        if (docsRemaining.length === 0) {
+          await removeDirectory(docsDir);
+        }
+      }
+    }
+  }
+
+  return removedCount;
+}
+
+/**
+ * Remove worclaude entries from .gitignore.
+ * Matches lines individually. Keeps .claude-backup-* / so backups stay git-ignored.
+ */
+export async function cleanGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  if (!(await fileExists(gitignorePath))) return false;
+
+  const content = await readFile(gitignorePath);
+  const lines = content.split('\n');
+
+  const REMOVE_LINES = new Set(['# Worclaude (generated workflow files)', '.claude/']);
+
+  const filtered = lines.filter((line) => !REMOVE_LINES.has(line.trim()));
+
+  // Collapse consecutive blank lines (max 2 in a row)
+  const cleaned = [];
+  let blankCount = 0;
+  for (const line of filtered) {
+    if (line.trim() === '') {
+      blankCount++;
+      if (blankCount <= 2) cleaned.push(line);
+    } else {
+      blankCount = 0;
+      cleaned.push(line);
+    }
+  }
+
+  // Trim trailing blank lines
+  while (cleaned.length > 0 && cleaned[cleaned.length - 1].trim() === '') {
+    cleaned.pop();
+  }
+  // Ensure file ends with newline if non-empty
+  const newContent = cleaned.length > 0 ? cleaned.join('\n') + '\n' : '';
+
+  if (newContent !== content) {
+    await writeFile(gitignorePath, newContent);
+    return true;
+  }
+  return false;
+}

package/src/data/agents.js

@@ -217,24 +217,6 @@ export const TECH_STACKS = [
   { name: 'Other / None', value: 'other' },
 ];
 
-export const FORMATTER_COMMANDS = {
-  python: 'ruff format . || true',
-  node: 'npx prettier --write . || true',
-  java: "google-java-format -i $(find . -name '*.java' 2>/dev/null) || true",
-  csharp: 'dotnet format || true',
-  cpp: "find . -name '*.c' -o -name '*.cpp' -o -name '*.h' -o -name '*.hpp' | xargs clang-format -i || true",
-  go: 'gofmt -w . || true',
-  php: 'php-cs-fixer fix . || true',
-  ruby: 'rubocop -A || true',
-  kotlin: 'ktlint -F || true',
-  swift: 'swift-format format -r . -i || true',
-  rust: 'cargo fmt || true',
-  dart: 'dart format . || true',
-  scala: 'scalafmt || true',
-  elixir: 'mix format || true',
-  zig: 'zig fmt . || true',
-};
-
 export const PROJECT_TYPE_DESCRIPTIONS = {
   'Full-stack web application': 'Frontend + backend in one repo',
   'Backend / API': 'Server, REST/GraphQL, no frontend',

package/src/index.js

@@ -8,6 +8,7 @@ import { statusCommand } from './commands/status.js';
 import { backupCommand } from './commands/backup.js';
 import { restoreCommand } from './commands/restore.js';
 import { diffCommand } from './commands/diff.js';
+import { deleteCommand } from './commands/delete.js';
 
 const program = new Command();
 
@@ -46,4 +47,9 @@ program
   .description('Compare current setup against installed workflow version')
   .action(diffCommand);
 
+program
+  .command('delete')
+  .description('Remove worclaude workflow from project')
+  .action(deleteCommand);
+
 program.parse();

package/templates/core/claude-md.md

@@ -15,11 +15,14 @@
 ## Skills (read on demand, not upfront)
 See `.claude/skills/` — load only what's relevant:
 - context-management.md — Session lifecycle
-- git-conventions.md — Commits and branches
+- claude-md-maintenance.md — CLAUDE.md self-healing
+- git-conventions.md — Commits, branches, versioning
 - planning-with-files.md — Implementation planning
+- prompt-engineering.md — Prompting patterns and quality
 - review-and-handoff.md — Session endings
 - verification.md — How to verify work
 - testing.md — Test philosophy and patterns
+- subagent-usage.md — When and how to use subagents
 - agent-routing.md — When and how to use each installed agent (READ EVERY SESSION)
 {project_specific_skills}
 

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

@@ -56,6 +56,8 @@ The workflow installs a PostCompact hook that runs:
 cat CLAUDE.md && cat docs/spec/PROGRESS.md 2>/dev/null || true
 ```
 
+> On Windows, this command runs in Git Bash (installed with [Git for Windows](https://gitforwindows.org)).
+
 This ensures you never lose your bearings after compaction. The hook fires
 automatically — you don't need to re-read these files manually.
 

package/templates/skills/universal/git-conventions.md

@@ -1,5 +1,5 @@
 ---
-description: "Branch naming, commit message format, PR workflow, worktree conventions"
+description: "Branch naming, commit message format, PR workflow, worktree conventions, versioning policy"
 ---
 
 # Git Conventions
@@ -97,6 +97,29 @@ When using `git worktree` for parallel work:
 Agents that use worktree isolation (code-simplifier, test-writer, ci-fixer, etc.)
 create and clean up their own worktrees automatically.
 
+## Versioning Policy
+
+Follow [semver](https://semver.org/) when the project publishes releases:
+
+| What changed | Bump | Example |
+|---|---|---|
+| Bug fix, patch to existing behavior | **patch** | Fixed edge case in date parser |
+| New feature, command, or API surface | **minor** | Added CSV export option |
+| Breaking change to public API or CLI | **major** | Renamed config key, removed flag |
+| Only docs, CI, tests, internal refactor | **no bump** | Updated README, added test |
+
+**Publish from the primary branch (usually `main`),** not from feature or development branches. What is published must always match what is on the release branch.
+
+**When to bump:** Include the version change in the same PR as the work — no separate "bump version" commits after the fact.
+
+**How to publish:**
+1. Merge the release PR into `main`
+2. Pull locally: `git checkout main && git pull`
+3. Publish using your ecosystem's tool (`npm publish`, `cargo publish`, `twine upload`, etc.)
+4. Sync develop: `git checkout develop && git merge main && git push origin develop`
+
+**Rule of thumb:** If the change affects what users see, install, or depend on, it needs a version bump. If it only affects the project's internal development workflow, it does not.
+
 ## Gotchas
 
 - Never force-push to main/master. Force-push to feature branches only when you