worclaude 1.4.0 → 1.6.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 [53 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, 10 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 [53 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.
 
 ---
 
@@ -23,8 +23,8 @@ Worclaude scaffolds a complete Claude Code workflow into any project in seconds.
 - 5 universal: plan-reviewer, code-simplifier, test-writer, build-validator, verify-app
 - 18 optional across 6 categories: Backend, Frontend, DevOps, Quality, Documentation, Data/AI
 
-**Slash Commands (10)**
-`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup`
+**Slash Commands (12)**
+`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup` `/sync` `/conflict-resolver`
 
 **Skills (13)**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "1.4.0",
+  "version": "1.6.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(/\r?\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

@@ -168,6 +168,8 @@ export const COMMAND_FILES = [
   'status',
   'update-claude-md',
   'setup',
+  'sync',
+  'conflict-resolver',
 ];
 
 export const UNIVERSAL_SKILLS = [
@@ -217,24 +219,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/commands/commit-push-pr.md

@@ -1,23 +1,27 @@
-1. Update docs/spec/PROGRESS.md with what was completed this session
-2. **Version bump (only when on `develop` targeting `main`):**
-   - Check what changed since last version using the versioning policy in git-conventions.md
-   - Template or CLI behavior changes → patch bump
-   - New command/feature → minor bump
-   - Breaking change → major bump
-   - Only docs/CI/tests/PROGRESS.md → no bump needed
-   - If bump needed: update `version` in package.json
-3. Stage all changes: git add -A
-4. Write a clear, conventional commit message
-5. Push to the current branch
-6. Create a PR with:
-   - Clear title matching conventional commit format
-   - Description of changes
-   - Testing done
-   - Any notes for reviewers
-
-Branch targeting rules:
-
-- Feature/bugfix branches → PR targets `develop` (`gh pr create --base develop`)
-- When on `develop` → PR targets `main` (`gh pr create --base main`) — release merges only
-
-Use `gh pr create` for PR creation.
+Determine which branch you're on, then follow the appropriate flow.
+
+## On a feature branch (feature/*, fix/*, chore/*, refactor/*)
+
+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
+
+## 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
+
+## On any other branch
+
+Ask the user which base branch to target before creating a PR.
+
+Use gh pr create for PR creation.

package/templates/commands/conflict-resolver.md

@@ -0,0 +1,40 @@
+You are resolving merge conflicts. ONLY resolve conflicts — do not
+update PROGRESS.md, SPEC.md, or bump versions. That is /sync's job.
+
+## Step 1: Detect
+
+Run: git status
+Identify all files with merge conflicts (listed as "both modified").
+If no conflicts found, report "No conflicts detected" and stop.
+
+## Step 2: Understand
+
+For each conflicted file:
+- Read the file and find all <<<<<<< / ======= / >>>>>>> markers
+- Understand what EACH side was trying to do
+- Check git log for both branches to understand the intent
+
+## Step 3: Resolve
+
+For each conflict:
+- Changes in DIFFERENT parts of the code → keep both
+- Changes modify the SAME lines → combine intelligently based on intent
+- Changes truly contradict → ask the user which to keep
+- NEVER silently drop changes from either side
+
+## Step 4: Verify clean
+
+Search ALL tracked files for remaining conflict markers
+(<<<<<<, =======, >>>>>>>). If any remain, resolve them.
+
+## Step 5: Test
+
+Run /verify (or the project's test and lint commands).
+If anything fails, fix it.
+
+## Step 6: Commit resolution only
+
+- git add -A
+- git commit -m "merge: resolve conflicts on develop"
+
+Do NOT push. Do NOT create a PR. The user will run /sync next.

package/templates/commands/end.md

@@ -1,11 +1,16 @@
-Use this command ONLY when stopping mid-task (unfinished work).
-If the task is complete, use /commit-push-pr instead — it handles PROGRESS.md updates.
+Use this ONLY when stopping work mid-task without committing.
 
-When stopping mid-task:
-1. Update docs/spec/PROGRESS.md with:
-   - What's in progress
-   - Any blockers or decisions needed
-   - Next steps to resume
-2. Write a handoff document at docs/handoffs/HANDOFF_{date}.md
-   with enough context for a fresh session to continue seamlessly.
-3. Stage and commit the progress update: git add -A && git commit
+Do NOT update PROGRESS.md — /sync handles that on develop after merging.
+
+## Mid-task handoff
+
+1. Create docs/handoffs/HANDOFF-{branch-name}-{date}.md
+2. Include:
+   - What was being worked on
+   - What is done so far
+   - 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]"
+5. git push

package/templates/commands/start.md

@@ -1,3 +1,11 @@
 Read docs/spec/PROGRESS.md to understand current state.
+Read .claude/skills/agent-routing.md for agent usage guidance.
+
+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)
+- 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.

package/templates/commands/sync.md

@@ -0,0 +1,49 @@
+Update shared-state files after merging feature PRs into develop.
+Run this on the develop branch AFTER all PRs are merged and any
+conflicts are resolved.
+
+ONLY update shared-state files — do not resolve conflicts. That is
+/conflict-resolver's job. If you detect unresolved conflicts, stop
+and tell the user to run /conflict-resolver first.
+
+## Pre-check
+
+1. Confirm you are on the develop branch. If not, stop and warn.
+2. Check for unresolved conflict markers in tracked files.
+   If found, stop: "Run /conflict-resolver first."
+3. Read git log to understand what was merged since the last sync
+   or version tag. If nothing was merged, report "Nothing to sync"
+   and stop.
+
+## Update PROGRESS.md
+
+4. Update docs/spec/PROGRESS.md:
+   - Mark completed items based on merged work
+   - Update "Last Updated" date to today
+   - Update Stats section by checking actual project values
+     (run the test suite, count source files, etc.)
+   - Move "In Progress" items to "Completed" if their PRs merged
+   - Update "Next Steps" if needed
+
+## Update SPEC.md
+
+5. If any merged PRs added features or changed behavior, update
+   docs/spec/SPEC.md to reflect the current state.
+   If nothing changed spec-wise, leave it alone.
+
+## Version bump
+
+6. Determine version bump using the Versioning Policy in
+   git-conventions.md. If bump needed: update version in package.json.
+
+## Verify
+
+7. Run /verify to confirm tests and lint pass.
+   If anything fails, fix it before proceeding.
+
+## Commit, push, and PR
+
+8. git add -A
+9. git commit -m "chore: sync progress, spec, and version to [new version]"
+10. git push origin develop
+11. gh pr create --base main with description of what was merged

package/templates/core/claude-md.md

@@ -29,7 +29,9 @@ See `.claude/skills/` — load only what's relevant:
 ## Session Protocol
 **Start:** Read PROGRESS.md → Read `.claude/skills/agent-routing.md` → Read active implementation prompt if any.
 **During:** One task at a time. Commit after each. Use subagents per routing guide.
-**End:** Use /commit-push-pr (updates PROGRESS.md, commits, pushes, creates PR). Use /end only if stopping mid-task.
+**Feature branch:** /start → work → /verify → /commit-push-pr
+**After merging PRs:** git checkout develop → git pull → /conflict-resolver (if needed) → /sync
+**Mid-task stop:** /end (writes handoff file)
 
 ## Critical Rules
 1. SPEC.md is source of truth. Do not invent features.
@@ -39,6 +41,7 @@ See `.claude/skills/` — load only what's relevant:
 5. Self-healing: same mistake twice → update CLAUDE.md.
 6. Use subagents to keep main context clean.
 7. Mediocre fix → scrap it, implement elegantly.
+8. Feature branches NEVER modify shared-state files. Those are updated only on develop via /sync after merging PRs. See git-conventions.md Shared-State Files for the canonical list.
 
 ## Gotchas
 [Grows during development]

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

@@ -97,6 +97,17 @@ 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.
 
+## Shared-State Files
+
+These files are modified ONLY on the develop branch (via /sync), never on feature branches:
+
+- `docs/spec/PROGRESS.md` — project progress tracker
+- `docs/spec/SPEC.md` — feature specification
+- `README.md` — project documentation
+- `package.json` version field — release versioning
+
+This prevents merge conflicts when running parallel feature branches.
+
 ## Versioning Policy
 
 Follow [semver](https://semver.org/) when the project publishes releases: