worclaude 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.5.1] — 2026-04-21
+
+Patch release fixing a user-visible bug found while dogfooding the v2.5.0 upgrade: reference-copy template files (the copies worclaude writes when your customized file and the shipped template both change) were being placed as `.workflow-ref.md` siblings next to the live file — including inside `.claude/commands/`, where Claude Code's command loader discovered them as phantom slash commands like `/sync.workflow-ref`, and inside `.claude/agents/`, where they could shadow live agents. Reference copies now live in a dedicated `.claude/workflow-ref/` tree that Claude Code does not scan. Installs upgrading from pre-v2.5.1 have their legacy reference files automatically relocated on the next `worclaude upgrade`.
+
+### Fixed
+
+- **Phantom slash commands from reference-copy siblings** (PR #101) — ref files are now written under `.claude/workflow-ref/<original-path>/` with the original filename preserved, instead of as `<name>.workflow-ref.md` siblings next to the live file. `.claude/commands/` and `.claude/agents/` are no longer polluted by `.workflow-ref` artifacts, so Claude Code's command and subagent loaders don't register them as live. `diff .claude/workflow-ref/commands/sync.md .claude/commands/sync.md` now reads cleanly.
+
+### Added
+
+- **`migrateWorkflowRefLocation()` in `src/core/migration.js`** (PR #101) — runs unconditionally at the start of every `worclaude upgrade`. Sweeps legacy `*.workflow-ref.md` siblings under `.claude/{commands,agents,skills}/` (plus root-level `CLAUDE.md.workflow-ref.md` and `AGENTS.md.workflow-ref`) into the new `.claude/workflow-ref/<original-path>/` tree. Idempotent (skips when target already exists, never overwrites). Scoped scan avoids re-stat'ing `.claude/sessions/` on every upgrade. Deliberately not version-gated — semver-gating this kind of cleanup migration creates a new bug class for users who downgrade then re-upgrade.
+- **Shared helpers in `src/core/file-categorizer.js`** (PR #101) — `WORKFLOW_REF_DIR` constant, `workflowRefRelPath(keyOrRelPath)` returning project-root-relative paths for `scaffoldFile`, `resolveRefPath(keyOrRelPath, projectRoot)` for absolute writes, and `isWorkflowRefFile(absPath, claudeDir)` predicate that unifies new-location-or-legacy-suffix detection so `status`, `doctor`, and `remover` stay in sync across the transition window.
+
+### Changed
+
+- **`worclaude upgrade` report output** (PR #101) — "Conflicts: N files (saved as .workflow-ref.md)" → "Conflicts: N files (saved under .claude/workflow-ref/)". New "Relocated: N legacy ref file(s) → .claude/workflow-ref/" line surfaces the one-time migration when it fires. Final hint reads "Review files under .claude/workflow-ref/ and merge what's useful."
+- **`worclaude init` and `worclaude status` output** (PR #101) — Scenario B conflict block, Next Steps, and Pending Review list all updated to reference the new location. Status continues to surface legacy `*.workflow-ref.md` siblings anywhere under `.claude/` so users upgrading from pre-v2.5.1 still see what they need to resolve before the next upgrade migrates them.
+- **`src/core/remover.js`** (PR #101) — the entire `.claude/workflow-ref/` subtree is classified as safe-to-delete on `worclaude delete`; the empty-subdir cleanup list extended to include `workflow-ref`.
+
+### Docs
+
+- **Upgrading guide** (PR #101) — 7 inline references updated plus a new "Upgrading from pre-v2.5.1 installs" subsection explaining what the automatic relocation does and how the skip-on-collision rule works.
+- **Existing-projects guide** (PR #101) — Tier 2 "Safe Alongside" section rewritten to describe the new `.claude/workflow-ref/` layout; post-merge report sample updated; the "Reviewing reference files" section now shows the clean `diff workflow-ref/commands/sync.md commands/sync.md` idiom.
+- **Commands reference, agents reference, SPEC.md, project-patterns skill** (PR #101) — all references to `.workflow-ref.md` sibling layout updated; `docs/spec/SPEC.md` edited on the feature branch as a shared-state override (PR #79 precedent: the SPEC update describes the very behavior the PR adds).
+
+### Tests
+
+- **Relocation migration coverage** (PR #101) — 8 new cases in `tests/core/migration.test.js` covering command/agent/skill subdir sweeps, root-level `CLAUDE.md.workflow-ref.md` / `AGENTS.md.workflow-ref` handling, target-collision skip behavior, idempotency on repeated runs, no-op on projects with files already at the new location, and clean-project no-ops. Regression assertions in `tests/commands/upgrade.test.js`, `tests/commands/init.test.js`, and `tests/core/merger.test.js` explicitly verify that `.workflow-ref.md` siblings are NEVER created inside `.claude/commands/` or `.claude/agents/`, so the phantom-command class of bug cannot silently return. 575/575 pass (567 prior + 8 new).
+
 ## [2.5.0] — 2026-04-21
 
 First release under the new per-PR bump declaration workflow. Shifts release mechanism from "every `/sync` publishes" to "every PR declares a bump, `/sync` aggregates, and only user-visible work ships." PR authors now declare `Version bump: {major|minor|patch|none}` in their PR body; `/sync` picks the highest declared bump since the last tag using precedence `major > minor > patch > none`. All-`none` batches update shared-state files on develop but never cut a release — internal-only work (docs, CI, tests) accumulates without triggering noisy publishes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -11,7 +11,7 @@ import {
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
 import { hasClaudeMdMemoryGuidance, readClaudeMd } from '../core/drift-checks.js';
-import { resolveKeyPath } from '../core/file-categorizer.js';
+import { resolveKeyPath, isWorkflowRefFile } from '../core/file-categorizer.js';
 import * as display from '../utils/display.js';
 
 // Check categories
@@ -202,7 +202,7 @@ async function checkClaudeMdMemoryGuidance(projectRoot) {
     result(
       WARN,
       'CLAUDE.md memory guidance',
-      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a CLAUDE.md.workflow-ref.md sidecar with suggested additions.'
+      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a sidecar under .claude/workflow-ref/CLAUDE.md with suggested additions.'
     ),
   ];
 }
@@ -828,10 +828,8 @@ async function checkPendingReviewFiles(projectRoot) {
     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);
-      }
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
+      pending.push(path.relative(claudeDir, fp).split(path.sep).join('/'));
     }
   } catch {
     // .claude dir might not exist

package/src/commands/init.js

@@ -528,7 +528,7 @@ function displayMergeReport(report, backupPath) {
     }
     if (report.added.skills.length > 0) {
       display.barLine(
-        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved as .workflow-ref.md)` : ''}`
+        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved under .claude/workflow-ref/)` : ''}`
       );
     }
     if (report.added.permissions > 0) {
@@ -549,10 +549,11 @@ function displayMergeReport(report, backupPath) {
     ...report.conflicts.commands,
   ];
   if (allConflicts.length > 0) {
-    display.barLine(`${display.yellow('~')} Conflicts (saved alongside for review):`);
+    display.barLine(
+      `${display.yellow('~')} Conflicts (template copy saved under .claude/workflow-ref/):`
+    );
     for (const file of allConflicts) {
-      const refName = file.replace('.md', '.workflow-ref.md');
-      display.barLine(`  ${display.yellow('⚠')} ${file} → ${refName}`);
+      display.barLine(`  ${display.yellow('⚠')} ${file}`);
     }
     display.newline();
   }
@@ -606,12 +607,14 @@ function displayMergeReport(report, backupPath) {
   display.divider('NEXT');
   display.newline();
   if (allConflicts.length > 0) {
-    console.log(`  ${display.white('1.')} Review .workflow-ref.md files and merge what's useful`);
+    console.log(
+      `  ${display.white('1.')} Review files under .claude/workflow-ref/ and merge what's useful`
+    );
   }
   if (report.claudeMdHandling === 'suggestions-generated') {
     console.log(`  ${display.white('2.')} Review CLAUDE.md.workflow-suggestions`);
     console.log(
-      `  ${display.white('3.')} Delete .workflow-ref.md and .workflow-suggestions files when done`
+      `  ${display.white('3.')} Delete .claude/workflow-ref/ and .workflow-suggestions when done`
     );
   }
   console.log(

package/src/commands/status.js

@@ -3,6 +3,7 @@ import { requireWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
 import { fileExists, readFile, listFilesRecursive } from '../utils/file.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
+import { isWorkflowRefFile } from '../core/file-categorizer.js';
 import { TECH_STACKS } from '../data/agents.js';
 import * as display from '../utils/display.js';
 
@@ -99,16 +100,17 @@ export async function statusCommand() {
     display.newline();
   }
 
-  // Pending review files
+  // Pending review files — anything isWorkflowRefFile() recognizes. That
+  // covers the v2.5.1+ .claude/workflow-ref/ tree plus legacy .workflow-ref.md
+  // siblings, so users mid-migration still see what they need to resolve.
   const pendingReview = [];
   try {
     const claudeDir = path.join(projectRoot, '.claude');
     const allFiles = await listFilesRecursive(claudeDir);
     for (const fp of allFiles) {
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
       const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
-      if (rel.endsWith('.workflow-ref.md')) {
-        pendingReview.push(`.claude/${rel}`);
-      }
+      pendingReview.push(`.claude/${rel}`);
     }
   } catch {
     // .claude dir might not exist

package/src/commands/upgrade.js

@@ -5,7 +5,7 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import { requireWorkflowMeta, writeWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { createBackup } from '../core/backup.js';
-import { categorizeFiles, resolveKeyPath } from '../core/file-categorizer.js';
+import { categorizeFiles, resolveKeyPath, resolveRefPath } from '../core/file-categorizer.js';
 import { buildSettingsJson, mergeSettingsPermissionsAndHooks } from '../core/merger.js';
 import { readTemplate, substituteVariables, updateGitignore } from '../core/scaffolder.js';
 import { buildAgentsMdVariables } from '../core/variables.js';
@@ -19,7 +19,12 @@ import { writeFile, readFile, fileExists } from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
 import * as display from '../utils/display.js';
-import { semverLessThan, migrateSkillFormat, patchAgentDescriptions } from '../core/migration.js';
+import {
+  semverLessThan,
+  migrateSkillFormat,
+  patchAgentDescriptions,
+  migrateWorkflowRefLocation,
+} from '../core/migration.js';
 
 const CONFLICT_CHECK_TYPES = new Set(['hook', 'root-file']);
 
@@ -41,12 +46,6 @@ function selfUpdate(latestVersion) {
   }
 }
 
-function sidecarPathFor(dest) {
-  const ext = path.extname(dest);
-  const base = ext ? dest.slice(0, dest.length - ext.length) : dest;
-  return `${base}.workflow-ref${ext}`;
-}
-
 async function renderTemplate({ templatePath, type }, variables) {
   const templateContent = await readTemplate(templatePath);
   return type === 'root-file' ? substituteVariables(templateContent, variables) : templateContent;
@@ -57,8 +56,8 @@ async function writeTemplateToDest(entry, dest, variables) {
   await writeFile(dest, await renderTemplate(entry, variables));
 }
 
-async function writeSidecarFor(entry, dest, variables) {
-  const sidecarPath = sidecarPathFor(dest);
+async function writeSidecarFor(entry, projectRoot, variables) {
+  const sidecarPath = resolveRefPath(entry.key, projectRoot);
   await writeFile(sidecarPath, await renderTemplate(entry, variables));
   return sidecarPath;
 }
@@ -122,7 +121,7 @@ function renderRepairPreview(plan) {
   }
   if (plan.claudeMdNeedsSidecar) {
     sidecarLines.push(
-      '  ~ CLAUDE.md memory guidance missing (will write CLAUDE.md.workflow-ref.md)'
+      '  ~ CLAUDE.md memory guidance missing (will write .claude/workflow-ref/CLAUDE.md sidecar)'
     );
   }
   if (sidecarLines.length > 0) {
@@ -197,7 +196,7 @@ async function applyRepairPass(projectRoot, plan, variables) {
     if (await fileExists(dest)) {
       const matches = await diskContentMatchesTemplate(entry, dest, variables);
       if (!matches) {
-        const sidecarPath = await writeSidecarFor(entry, dest, variables);
+        const sidecarPath = await writeSidecarFor(entry, projectRoot, variables);
         result.migrationConflicts.push({ key: entry.key, dest, sidecarPath });
         continue;
       }
@@ -282,7 +281,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
     }
     if (result.migrationConflicts.length > 0) {
       display.barLine(
-        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved as .workflow-ref)')}`
+        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (result.createdDirs.length > 0) {
@@ -295,7 +294,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
 
     if (result.migrationConflicts.length > 0 || result.sidecars.length > 0) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Repair failed.');
@@ -440,17 +439,25 @@ export async function upgradeCommand(options = {}) {
       spinner.start('Applying updates...');
     }
 
+    // v2.5.1 migration: relocate legacy ref files out of Claude-Code-scanned
+    // dirs. Runs unconditionally since it's idempotent and the fix applies
+    // to any project with legacy refs, regardless of source version.
+    const refRelocationReport = await migrateWorkflowRefLocation(projectRoot);
+    if (refRelocationReport.moved > 0) {
+      spinner.text = `Relocated ${refRelocationReport.moved} legacy ref file(s)...`;
+    }
+
     // Auto-update files
     for (const { key, templatePath } of categories.autoUpdate) {
       const content = await readTemplate(templatePath);
       await writeFile(resolveKeyPath(key, projectRoot), content);
     }
 
-    // Conflict files: save as .workflow-ref.md
+    // Conflict files: save under .claude/workflow-ref/ so they never collide
+    // with Claude Code's command/agent discovery.
     for (const { key, templatePath } of categories.conflict) {
       const content = await readTemplate(templatePath);
-      const refKey = key.replace(/\.md$/, '.workflow-ref.md');
-      await writeFile(resolveKeyPath(refKey, projectRoot), content);
+      await writeFile(resolveRefPath(key, projectRoot), content);
     }
 
     // New files (non-migration types handled here; migration types were
@@ -510,7 +517,7 @@ export async function upgradeCommand(options = {}) {
     }
     if (repairResult.migrationConflicts.length > 0) {
       display.barLine(
-        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved as .workflow-ref)')}`
+        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (categories.autoUpdate.length > 0) {
@@ -518,7 +525,12 @@ export async function upgradeCommand(options = {}) {
     }
     if (categories.conflict.length > 0) {
       display.barLine(
-        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved as .workflow-ref.md)')}`
+        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
+      );
+    }
+    if (refRelocationReport.moved > 0) {
+      display.barLine(
+        `Relocated:   ${refRelocationReport.moved} legacy ref file(s) ${display.dimColor('→ .claude/workflow-ref/')}`
       );
     }
     if (plan.templateNewFiles.length > 0) {
@@ -558,7 +570,7 @@ export async function upgradeCommand(options = {}) {
       repairResult.sidecars.length > 0
     ) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Upgrade failed.');

package/src/core/drift-checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { fileExists, readFile, writeFile } from '../utils/file.js';
+import { resolveRefPath } from './file-categorizer.js';
 
 export const MEMORY_GUIDANCE_KEYWORDS = [
   'memory architecture',
@@ -47,7 +48,7 @@ export function buildMemoryGuidanceSidecar() {
 }
 
 export async function writeMemoryGuidanceSidecar(projectRoot) {
-  const dest = path.join(projectRoot, 'CLAUDE.md.workflow-ref.md');
+  const dest = resolveRefPath('root/CLAUDE.md', projectRoot);
   await writeFile(dest, buildMemoryGuidanceSidecar());
   return dest;
 }

package/src/core/file-categorizer.js

@@ -36,6 +36,7 @@ export function isAlwaysScaffolded(entry, meta) {
 }
 
 export const ROOT_KEY_PREFIX = 'root/';
+export const WORKFLOW_REF_DIR = 'workflow-ref';
 
 export function resolveKeyPath(key, projectRoot) {
   if (key.startsWith(ROOT_KEY_PREFIX)) {
@@ -45,6 +46,43 @@ export function resolveKeyPath(key, projectRoot) {
   return path.join(projectRoot, '.claude', ...key.split('/'));
 }
 
+/**
+ * Project-root-relative path for a ref file. Useful for scaffoldFile() which
+ * takes a destRelativePath. Returns e.g. ".claude/workflow-ref/commands/sync.md".
+ * Accepts a workflow key ("commands/sync.md", "root/CLAUDE.md") or a plain
+ * relative path. Root-level files (CLAUDE.md, AGENTS.md) land directly
+ * under workflow-ref/, not under workflow-ref/root/.
+ */
+export function workflowRefRelPath(keyOrRelPath) {
+  const rel = keyOrRelPath.startsWith(ROOT_KEY_PREFIX)
+    ? keyOrRelPath.slice(ROOT_KEY_PREFIX.length)
+    : keyOrRelPath;
+  return path.join('.claude', WORKFLOW_REF_DIR, ...rel.split('/'));
+}
+
+/**
+ * Resolve an absolute ref file destination for a given relative path.
+ * Wraps workflowRefRelPath with projectRoot.
+ */
+export function resolveRefPath(keyOrRelPath, projectRoot) {
+  return path.join(projectRoot, workflowRefRelPath(keyOrRelPath));
+}
+
+/**
+ * Predicate for "is this file a reference copy?". Matches both the v2.5.1+
+ * layout (anywhere under .claude/workflow-ref/) and the legacy sibling
+ * convention (.workflow-ref.md suffix). Used by status, doctor, and remover
+ * so they stay in sync across the two location schemes.
+ *
+ * @param {string} absPath — absolute path on disk
+ * @param {string} claudeDir — absolute path to the project's .claude/ directory
+ */
+export function isWorkflowRefFile(absPath, claudeDir) {
+  const refDirPrefix = path.join(claudeDir, WORKFLOW_REF_DIR) + path.sep;
+  if (absPath.startsWith(refDirPrefix)) return true;
+  return absPath.endsWith('.workflow-ref.md');
+}
+
 /**
  * Build a map of all workflow template files to their hash keys, template paths, and hashes.
  * Hash keys match the format stored in workflow-meta.json (relative to .claude/).

package/src/core/merger.js

@@ -10,6 +10,7 @@ import {
   scaffoldPluginJson,
   scaffoldMemoryDocs,
 } from './scaffolder.js';
+import { workflowRefRelPath } from './file-categorizer.js';
 import { promptHookConflict } from '../prompts/conflict-resolution.js';
 import {
   detectMissingSections,
@@ -124,10 +125,11 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
     const existsAsFlat = existingScan.existingSkills.includes(`${skill.name}.md`);
 
     if (existsAsDir || existsAsFlat) {
-      // Tier 2: conflict — save as .workflow-ref.md
+      // Tier 2: conflict — save under .claude/workflow-ref/ so the live
+      // SKILL.md stays authoritative and the ref cannot shadow it.
       await scaffoldFile(
         skill.templatePath,
-        path.join('.claude', 'skills', skill.name, 'SKILL.workflow-ref.md'),
+        workflowRefRelPath(`skills/${skill.name}/SKILL.md`),
         skill.vars,
         projectRoot
       );
@@ -147,7 +149,7 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
 
   if (routingExistsAsDir || routingExistsAsFlat) {
     await writeFile(
-      path.join(projectRoot, skillsDir, 'agent-routing', 'SKILL.workflow-ref.md'),
+      path.join(projectRoot, workflowRefRelPath('skills/agent-routing/SKILL.md')),
       routingContent
     );
     report.conflicts.skills.push('agent-routing');
@@ -166,7 +168,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/universal/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -191,7 +193,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/optional/${category}/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -216,7 +218,7 @@ async function mergeCommands(projectRoot, existingScan, report) {
     if (existingScan.existingCommands.includes(filename)) {
       await scaffoldFile(
         `commands/${cmd}.md`,
-        path.join(destDir, `${cmd}.workflow-ref.md`),
+        workflowRefRelPath(`commands/${filename}`),
         {},
         projectRoot
       );
@@ -431,7 +433,12 @@ async function mergeAgentsMd(projectRoot, existingScan, variables, report) {
     await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
     report.agentsMdHandling = 'created';
   } else {
-    await scaffoldFile('core/agents-md.md', 'AGENTS.md.workflow-ref', variables, projectRoot);
+    await scaffoldFile(
+      'core/agents-md.md',
+      workflowRefRelPath('root/AGENTS.md'),
+      variables,
+      projectRoot
+    );
     report.agentsMdHandling = 'saved-alongside';
   }
 }

package/src/core/migration.js

@@ -1,7 +1,16 @@
 import path from 'node:path';
 import { AGENT_CATALOG } from '../data/agents.js';
-import { readFile, writeFile, dirExists, moveFile, listFiles } from '../utils/file.js';
+import {
+  fileExists,
+  readFile,
+  writeFile,
+  dirExists,
+  moveFile,
+  listFiles,
+  listFilesRecursive,
+} from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 // --- Version comparison ---
 
@@ -142,3 +151,70 @@ export async function patchAgentDescriptions(projectRoot, meta, promptFn) {
 
   return report;
 }
+
+// --- Workflow-ref relocation (v2.5.1) ---
+
+const LEGACY_ROOT_REFS = ['CLAUDE.md.workflow-ref.md', 'AGENTS.md.workflow-ref'];
+
+// Legacy ref files could only live inside these subdirs. Scoping the scan
+// here instead of walking all of .claude/ matters because `sessions/` and
+// `learnings/` can accumulate hundreds of files that will never be refs.
+const LEGACY_REF_SUBDIRS = ['commands', 'agents', 'skills'];
+
+function legacyClaudeRefTarget(relKey) {
+  // relKey is relative to .claude/, e.g. "commands/sync.workflow-ref.md".
+  // Lookahead `(?=\.[^.]+$)` ensures ".workflow-ref" is stripped only when
+  // followed by a final extension — so "sync.workflow-ref.md" → "sync.md",
+  // but a hypothetical "sync.workflow-ref" (no final ext) wouldn't match.
+  const parts = relKey.split('/');
+  const name = parts.pop();
+  parts.push(name.replace(/\.workflow-ref(?=\.[^.]+$)/, ''));
+  return path.join(WORKFLOW_REF_DIR, ...parts);
+}
+
+export async function migrateWorkflowRefLocation(projectRoot) {
+  const report = { moved: 0, names: [], skipped: [] };
+  const claudeDir = path.join(projectRoot, '.claude');
+  const refDir = path.join(claudeDir, WORKFLOW_REF_DIR);
+
+  // 1. Scan only the subdirs where legacy `.workflow-ref.md` siblings could
+  //    live. Walking all of .claude/ would re-stat hundreds of session files
+  //    on every upgrade for no benefit.
+  for (const subdir of LEGACY_REF_SUBDIRS) {
+    const scanRoot = path.join(claudeDir, subdir);
+    if (!(await dirExists(scanRoot))) continue;
+
+    const allFiles = await listFilesRecursive(scanRoot);
+    for (const fp of allFiles) {
+      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
+      if (!rel.endsWith('.workflow-ref.md')) continue;
+
+      const target = path.join(claudeDir, legacyClaudeRefTarget(rel));
+      if (await fileExists(target)) {
+        report.skipped.push(rel);
+        continue;
+      }
+      await moveFile(fp, target);
+      report.moved++;
+      report.names.push(rel);
+    }
+  }
+
+  // 2. Legacy root-level refs (CLAUDE.md.workflow-ref.md, AGENTS.md.workflow-ref).
+  for (const legacyName of LEGACY_ROOT_REFS) {
+    const src = path.join(projectRoot, legacyName);
+    if (!(await fileExists(src))) continue;
+
+    const original = legacyName.replace(/\.workflow-ref(?:\.md)?$/, '');
+    const target = path.join(refDir, original);
+    if (await fileExists(target)) {
+      report.skipped.push(legacyName);
+      continue;
+    }
+    await moveFile(src, target);
+    report.moved++;
+    report.names.push(legacyName);
+  }
+
+  return report;
+}

package/src/core/remover.js

@@ -9,6 +9,7 @@ import {
   listFilesRecursive,
   removeDirectory,
 } from '../utils/file.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 /**
  * Classify .claude/ files into safe-to-delete, modified, missing, and user-owned.
@@ -55,8 +56,9 @@ export async function classifyClaudeFiles(projectRoot, meta) {
     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')) {
+    // Upgrade artifacts — safe to delete: anything under workflow-ref/ (new
+    // location) or the legacy `.workflow-ref.md` sibling suffix.
+    if (relKey.startsWith(`${WORKFLOW_REF_DIR}/`) || relKey.endsWith('.workflow-ref.md')) {
       safeToDelete.push(relKey);
     } else {
       userOwned.push(relKey);
@@ -115,7 +117,7 @@ export async function removeTrackedFiles(projectRoot, fileKeys) {
   }
 
   // Clean up empty subdirectories
-  for (const subdir of ['agents', 'commands', 'skills']) {
+  for (const subdir of ['agents', 'commands', 'skills', WORKFLOW_REF_DIR]) {
     const dirPath = path.join(claudeDir, subdir);
     if (await dirExists(dirPath)) {
       const remaining = await listFilesRecursive(dirPath);