@brunosps00/dev-workflow 2.5.0 → 2.7.0

package/lib/migrate-skills.js

@@ -3,44 +3,88 @@ const path = require('path');
 const { COMMANDS } = require('./constants');
 const removedSkills = require('./removed-bundled-skills');
 const removedCommands = require('./removed-commands');
+const { BUNDLED_SKILLS_REL, LEGACY_BUNDLED_SKILLS_REL } = require('./skill-registry');
+
+const MIGRATED_REL = path.join('.dw', '.migrated');
 
 /**
  * Cleanup-on-update for dev-workflow.
  *
- * Two complementary scans:
+ * Nothing is deleted outright: every path this module retires is MOVED to
+ * `.dw/.migrated/<timestamp>/<original relative path>`, and the destination is
+ * printed. A direct `npx … update` from a terminal takes no snapshot (only the
+ * `/dw-update` agent command does), so this move is the only copy those users get.
+ *
+ * Scans:
  *
  * 1. Removed bundled skills (data-driven from `removed-bundled-skills.js`):
- *    Detects `.agents/skills/<name>/` directories that match the manifest of
- *    skills removed in past releases. Removes them and notes the replacement.
+ *    `.dw/skills/<name>/` and legacy `.agents/skills/<name>/` directories named in
+ *    the manifest of skills removed in past releases. Matched by name only: a
+ *    same-named skill from elsewhere is moved too, which is why it is a move.
  *
- * 2. Orphan command wrappers (state-comparison vs `constants.js`):
- *    Lists `.claude/skills/dw-*`, `.agents/skills/dw-*`, and
- *    `.opencode/commands/dw-*.md` wrappers on disk. Any `dw-*` wrapper whose
- *    base name is NOT present in the current `COMMANDS[lang]` is removed.
+ * 1.5. Relocated bundled skills: releases up to 2.6.0 installed the bundled
+ *    skills under `.agents/skills/`, where Codex, Copilot and OpenCode list them
+ *    as model-invocable. They now live in `.dw/skills/`. A legacy copy is retired
+ *    only when `classifyLegacySkill` says it is ours; otherwise it is kept and
+ *    reported. Files in an ours-copy that dev-workflow never installed are named
+ *    in the output so the team can bring them back from the move destination.
  *
- * Only touches names with prefix `dw-` (or names explicitly listed in the
- * manifest). Never touches third-party skills/commands.
+ * 2. Orphan command wrappers (state-comparison vs `constants.js`):
+ *    `.claude/skills/dw-*`, `.agents/skills/dw-*` and `.opencode/commands/dw-*.md`
+ *    whose base name is NOT a current command or bundled skill. `dw-` is this
+ *    package's namespace; a user skill named `dw-*` is moved, not lost.
  *
  * Idempotent: silent when nothing to clean.
  *
- * Run automatically from lib/init.js when mode === 'update'.
+ * Run from lib/init.js on update/repair/re-init, AFTER the bundled skills were
+ * copied to `.dw/skills/`, so an interrupted update never leaves a project with
+ * neither copy.
  */
-function migrate(projectRoot) {
+function migrate(projectRoot, { priorState = null, stamp = timestamp() } = {}) {
+  const managed = managedSet(priorState);
   const removed = scanRemovedBundledSkills(projectRoot);
+  const relocated = scanRelocatedBundledSkills(projectRoot, managed);
   const orphans = scanOrphanCommandWrappers(projectRoot);
   const commandSources = scanRemovedCommandSources(projectRoot);
 
-  if (removed.length === 0 && orphans.length === 0 && commandSources.length === 0) {
+  if (
+    removed.length === 0 &&
+    relocated.length === 0 &&
+    orphans.length === 0 &&
+    commandSources.length === 0
+  ) {
     return null; // silent — nothing to clean
   }
 
   console.log('\n  Skill migration:');
+  let moved = 0;
+  const retire = (target) => {
+    moveToBackup(projectRoot, target, stamp);
+    moved += 1;
+  };
 
   for (const entry of removed) {
     console.log(
-      `    \x1b[33m-\x1b[0m [v${entry.removedIn}] Removing legacy skill ${entry.name} (replaced by ${entry.replacedBy})`
+      `    \x1b[33m-\x1b[0m [v${entry.removedIn}] Retiring legacy skill ${path.relative(projectRoot, entry.path)} (replaced by ${entry.replacedBy})`
     );
-    rmRecursive(entry.path);
+    retire(entry.path);
+  }
+
+  let relocatedCount = 0;
+  for (const entry of relocated) {
+    const rel = path.relative(projectRoot, entry.path);
+    if (entry.ours) {
+      console.log(`    \x1b[33m-\x1b[0m [moved] Retiring ${rel} (bundled skills now live in ${BUNDLED_SKILLS_REL}/)`);
+      for (const file of entry.foreign) {
+        console.log(`        ! ${path.join(rel, file)} was not installed by dev-workflow; it is in the backup below`);
+      }
+      retire(entry.path);
+      relocatedCount += 1;
+    } else {
+      console.log(
+        `    \x1b[36m!\x1b[0m [kept] ${rel} has a bundled skill's name but is not a dev-workflow copy (${entry.reason}); left in place`
+      );
+    }
   }
 
   // Pre-build a map { commandName -> { removedIn, replacedBy } } for friendly messaging.
@@ -53,58 +97,143 @@ function migrate(projectRoot) {
     const suffix = known
       ? `(replaced in v${known.removedIn} by \`${known.replacedBy}\`)`
       : `(command no longer exists)`;
-    console.log(`    \x1b[33m-\x1b[0m [orphan] Removing wrapper ${rel} ${suffix}`);
-    rmRecursive(entry.path);
+    console.log(`    \x1b[33m-\x1b[0m [orphan] Retiring wrapper ${rel} ${suffix}`);
+    retire(entry.path);
   }
 
   for (const entry of commandSources) {
     const rel = path.relative(projectRoot, entry.path);
     console.log(
-      `    \x1b[33m-\x1b[0m [legacy] Removing command source ${rel} (replaced in v${entry.removedIn} by \`${entry.replacedBy}\`)`
+      `    \x1b[33m-\x1b[0m [legacy] Retiring command source ${rel} (replaced in v${entry.removedIn} by \`${entry.replacedBy}\`)`
     );
-    rmRecursive(entry.path);
+    retire(entry.path);
   }
 
+  if (moved > 0) {
+    console.log(`    Moved ${moved} path(s) to ${path.join(MIGRATED_REL, stamp)}/ — copy back anything you want to keep.`);
+  }
   console.log();
-  return { removed: removed.length, orphans: orphans.length, commandSources: commandSources.length };
+  return {
+    removed: removed.length,
+    relocated: relocatedCount,
+    orphans: orphans.length,
+    commandSources: commandSources.length,
+    backup: moved > 0 ? path.join(projectRoot, MIGRATED_REL, stamp) : null,
+  };
 }
 
 function scanRemovedBundledSkills(projectRoot) {
   const matches = [];
-  const agentsSkillsDir = path.join(projectRoot, '.agents', 'skills');
+  for (const rel of [BUNDLED_SKILLS_REL, LEGACY_BUNDLED_SKILLS_REL]) {
+    const skillsDir = path.join(projectRoot, rel);
+    if (!fs.existsSync(skillsDir)) continue;
+    for (const entry of removedSkills) {
+      const target = path.join(skillsDir, entry.name);
+      if (fs.existsSync(target)) {
+        matches.push({ ...entry, path: target });
+      }
+    }
+  }
+  return matches;
+}
 
-  if (!fs.existsSync(agentsSkillsDir)) return matches;
+function scanRelocatedBundledSkills(projectRoot, managed) {
+  const matches = [];
+  const legacyDir = path.join(projectRoot, LEGACY_BUNDLED_SKILLS_REL);
+  if (!fs.existsSync(legacyDir)) return matches;
 
-  for (const entry of removedSkills) {
-    const target = path.join(agentsSkillsDir, entry.name);
-    if (fs.existsSync(target)) {
-      matches.push({ ...entry, path: target });
+  for (const name of listScaffoldSkillDirs()) {
+    const target = path.join(legacyDir, name);
+    let stat;
+    try {
+      stat = fs.statSync(target);
+    } catch {
+      continue;
     }
+    if (!stat.isDirectory()) continue;
+    matches.push({ name, path: target, ...classifyLegacySkill(projectRoot, name, managed) });
   }
   return matches;
 }
 
+/**
+ * Is `.agents/skills/<name>/` the copy a release up to 2.6.0 installed?
+ *
+ * - Its SKILL.md must carry the Structured Return contract every bundled skill
+ *   has (`**Status:**` and `**Next Step:**`). Without it: not ours.
+ * - When the prior install state tracked files, its SKILL.md must be one of
+ *   them. A same-named skill installed after the last update is not, even if its
+ *   SKILL.md happens to use the same two labels.
+ * - With no tracked files (installs older than install-state), the contract
+ *   check alone decides.
+ *
+ * For an ours-copy, `foreign` lists files dev-workflow neither tracked nor ships
+ * (a team's addition, or a file from an older release), relative to the dir.
+ */
+function classifyLegacySkill(projectRoot, name, managed = new Set()) {
+  const dir = path.join(projectRoot, LEGACY_BUNDLED_SKILLS_REL, name);
+  if (!isDevWorkflowSkillCopy(dir)) return { ours: false, reason: 'no Structured Return contract', foreign: [] };
+  const relDir = path.join(LEGACY_BUNDLED_SKILLS_REL, name);
+  if (managed.size > 0 && !managed.has(path.join(relDir, 'SKILL.md'))) {
+    return { ours: false, reason: 'not in the previous install state', foreign: [] };
+  }
+  const scaffoldDir = path.join(__dirname, '..', 'scaffold', 'skills', name);
+  const foreign = listFiles(dir).filter(
+    (file) => !managed.has(path.join(relDir, file)) && !fs.existsSync(path.join(scaffoldDir, file))
+  );
+  return { ours: true, reason: null, foreign };
+}
+
+// Every bundled SKILL.md carries the Structured Return contract (enforced by
+// lib/skill-registry.js). Necessary, not sufficient: see classifyLegacySkill.
+function isDevWorkflowSkillCopy(skillDir) {
+  let content;
+  try {
+    content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
+  } catch {
+    return false;
+  }
+  return content.includes('**Status:**') && content.includes('**Next Step:**');
+}
+
+function managedSet(state) {
+  return new Set(state && Array.isArray(state.managed_files) ? state.managed_files : []);
+}
+
+function listFiles(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(full, base));
+    else out.push(path.relative(base, full));
+  }
+  return out;
+}
+
+function listScaffoldSkillDirs() {
+  const scaffoldSkillsDir = path.join(__dirname, '..', 'scaffold', 'skills');
+  if (!fs.existsSync(scaffoldSkillsDir)) return [];
+  return fs
+    .readdirSync(scaffoldSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
 function scanOrphanCommandWrappers(projectRoot) {
   const orphans = [];
 
   // Build the canonical "known names" set:
   //  - Commands from constants.js (en + pt-br union) — these become wrappers.
-  //  - Bundled skills from scaffold/skills/ — these are copied verbatim into
-  //    .agents/skills/ and .claude/skills/ alongside wrappers. They're NOT
-  //    orphans even though they share the .agents/skills/ directory with
-  //    command wrappers.
+  //  - Bundled skill names from scaffold/skills/ — they now live in .dw/skills/,
+  //    and a legacy copy under .agents/skills/ is handled by the relocation
+  //    scan, not reported here as an orphan wrapper.
   const canonical = new Set();
   for (const lang of Object.keys(COMMANDS)) {
     for (const cmd of COMMANDS[lang]) {
       canonical.add(cmd.name);
     }
   }
-  const scaffoldSkillsDir = path.join(__dirname, '..', 'scaffold', 'skills');
-  if (fs.existsSync(scaffoldSkillsDir)) {
-    for (const entry of fs.readdirSync(scaffoldSkillsDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) canonical.add(entry.name);
-    }
-  }
+  for (const name of listScaffoldSkillDirs()) canonical.add(name);
 
   // Scan locations
   const locations = [
@@ -152,9 +281,30 @@ function scanRemovedCommandSources(projectRoot) {
   return matches;
 }
 
-function rmRecursive(target) {
-  if (!fs.existsSync(target)) return;
-  fs.rmSync(target, { recursive: true, force: true });
+function timestamp() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+// Move a retired path under .dw/.migrated/<stamp>/, keeping its relative path.
+function moveToBackup(projectRoot, target, stamp = timestamp()) {
+  if (!fs.existsSync(target)) return null;
+  const dest = path.join(projectRoot, MIGRATED_REL, stamp, path.relative(projectRoot, target));
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  try {
+    fs.renameSync(target, dest);
+  } catch {
+    fs.cpSync(target, dest, { recursive: true });
+    fs.rmSync(target, { recursive: true, force: true });
+  }
+  return dest;
 }
 
-module.exports = { migrate };
+module.exports = {
+  migrate,
+  isDevWorkflowSkillCopy,
+  classifyLegacySkill,
+  managedSet,
+  moveToBackup,
+  timestamp,
+  MIGRATED_REL,
+};

package/lib/removed-bundled-skills.js

@@ -5,8 +5,10 @@
  * this manifest forever so old installs still get cleaned up when the
  * user runs `dev-workflow update`.
  *
- * Each entry triggers `.agents/skills/<name>/` removal during update
- * (see lib/migrate-skills.js).
+ * Each entry retires `.dw/skills/<name>/` and `.agents/skills/<name>/` during
+ * update by moving them to `.dw/.migrated/<timestamp>/` (see lib/migrate-skills.js).
+ * The match is by name only, so the move is what keeps a same-named skill from
+ * elsewhere recoverable.
  */
 module.exports = [
   // v0.13.0 — replaced TASTE catalog (161 palettes) with discipline (hard-gate + anti-slop + WCAG floor)

package/lib/skill-registry.js

@@ -6,11 +6,19 @@ const { readJson } = require('./utils');
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 const REGISTRY_PATH = path.join(SCAFFOLD_DIR, 'skill-registry.json');
 const SKILLS_DIR = path.join(SCAFFOLD_DIR, 'skills');
+// Where a consumer project receives the bundled skills. Deliberately outside every
+// directory an agent CLI scans for model-invocable skills (`.claude/skills`,
+// `.agents/skills`, `.github/skills`, `.opencode/skills`): commands load these by
+// path, so listing them in each tool's skill index only crowded the choice the
+// model makes there. Releases up to 2.6.0 installed them under `.agents/skills/`;
+// `migrate-skills.js` moves those out on update.
+const BUNDLED_SKILLS_REL = path.join('.dw', 'skills');
+const LEGACY_BUNDLED_SKILLS_REL = path.join('.agents', 'skills');
 
 const VALID_KINDS = new Set(['protocol', 'domain-pack', 'recipe-pack', 'asset-pack']);
 const VALID_LOAD_POLICIES = new Set(['always-small', 'lazy-references', 'opt-in-runtime']);
 // Optional invocation control (mattpocock/skills). Bundled skills live under
-// .agents/skills/ (read by path from command prose), so this is documental for
+// .dw/skills/ (read by path from command prose), so this is documental for
 // them and feeds the à-la-carte plugin manifest. Default when absent: 'model'.
 const VALID_INVOCATIONS = new Set(['model', 'explicit']);
 const REQUIRED_STRUCTURED_RETURN_FIELDS = [
@@ -150,7 +158,7 @@ function validateSkillStructuredReturn(skillName, skillPath, issues, label = `Sk
 }
 
 function listInstalledSkillNames(projectRoot) {
-  const installedDir = path.join(projectRoot, '.agents', 'skills');
+  const installedDir = path.join(projectRoot, BUNDLED_SKILLS_REL);
   if (!fs.existsSync(installedDir)) return [];
   return fs
     .readdirSync(installedDir, { withFileTypes: true })
@@ -161,6 +169,8 @@ function listInstalledSkillNames(projectRoot) {
 
 module.exports = {
   REGISTRY_PATH,
+  BUNDLED_SKILLS_REL,
+  LEGACY_BUNDLED_SKILLS_REL,
   readSkillRegistry,
   validateSkillRegistry,
   validateSkillStructuredReturn,

package/lib/uninstall.js

@@ -3,6 +3,9 @@ const path = require('path');
 const { COMMANDS, PLATFORMS, MCP_SERVERS } = require('./constants');
 const { AGENT_TARGETS, LEGACY_AGENT_TARGETS, readAgentRegistry } = require('./agents');
 const { removeHooks } = require('./hooks');
+const { BUNDLED_SKILLS_REL, LEGACY_BUNDLED_SKILLS_REL } = require('./skill-registry');
+const { classifyLegacySkill, isDevWorkflowSkillCopy, managedSet, moveToBackup, timestamp, MIGRATED_REL } = require('./migrate-skills');
+const { readInstallState } = require('./install-state');
 
 function run() {
   const projectRoot = process.cwd();
@@ -36,7 +39,19 @@ function run() {
   // 1. Remove .dw/commands/, .dw/templates/, .dw/references/, .dw/scripts/
   console.log('  Managed files:');
   removeDir(path.join(projectRoot, '.dw', 'commands'), '.dw/commands/');
-  removeDir(path.join(projectRoot, '.dw', 'templates'), '.dw/templates/');
+  // .dw/templates/overrides/ is the owner's (it wins over the managed templates): keep it.
+  const templatesDir = path.join(projectRoot, '.dw', 'templates');
+  if (fs.existsSync(templatesDir)) {
+    for (const entry of fs.readdirSync(templatesDir)) {
+      if (entry === 'overrides') continue;
+      fs.rmSync(path.join(templatesDir, entry), { recursive: true, force: true });
+    }
+    if (fs.readdirSync(templatesDir).length === 0) fs.rmdirSync(templatesDir);
+    console.log(`  \x1b[31m-\x1b[0m .dw/templates [removed${fs.existsSync(templatesDir) ? ', overrides/ kept' : ''}]`);
+    removed++;
+  } else {
+    skipped++;
+  }
   removeDir(path.join(projectRoot, '.dw', 'references'), '.dw/references/');
   removeDir(path.join(projectRoot, '.dw', 'scripts'), '.dw/scripts/');
   removeFile(path.join(projectRoot, '.dw', 'agent-registry.json'));
@@ -57,14 +72,39 @@ function run() {
   }
   console.log();
 
-  // 3. Remove bundled skills from .agents/skills/
+  // 3. Remove bundled skills from .dw/skills/ (managed by this package). A legacy
+  //    copy left under .agents/skills/ by a release up to 2.6.0 is moved to
+  //    .dw/.migrated/<ts>/ — only when it is ours (classifyLegacySkill); a
+  //    same-named skill installed from elsewhere is kept and reported.
   console.log('  Bundled skills:');
   const skillsDir = path.join(__dirname, '..', 'scaffold', 'skills');
   const bundledSkills = fs.existsSync(skillsDir)
     ? fs.readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
     : [];
+  const managed = managedSet(readInstallState(projectRoot));
+  const stamp = timestamp();
+  let movedLegacy = 0;
   for (const skill of bundledSkills) {
-    removeDir(path.join(projectRoot, '.agents', 'skills', skill));
+    removeDir(path.join(projectRoot, BUNDLED_SKILLS_REL, skill));
+    const legacy = path.join(projectRoot, LEGACY_BUNDLED_SKILLS_REL, skill);
+    if (!fs.existsSync(legacy)) continue;
+    const verdict = classifyLegacySkill(projectRoot, skill, managed);
+    const rel = path.relative(projectRoot, legacy);
+    if (verdict.ours) {
+      moveToBackup(projectRoot, legacy, stamp);
+      console.log(`  \x1b[31m-\x1b[0m ${rel} [moved to ${path.join(MIGRATED_REL, stamp)}/]`);
+      removed++;
+      movedLegacy++;
+    } else {
+      console.log(`  \x1b[36m!\x1b[0m ${rel} [kept: not a dev-workflow copy (${verdict.reason})]`);
+    }
+  }
+  if (movedLegacy > 0) {
+    console.log(`    Legacy copies are in ${path.join(MIGRATED_REL, stamp)}/; delete that folder when you no longer need them.`);
+  }
+  const bundledRoot = path.join(projectRoot, BUNDLED_SKILLS_REL);
+  if (fs.existsSync(bundledRoot) && fs.readdirSync(bundledRoot).length === 0) {
+    fs.rmdirSync(bundledRoot);
   }
   console.log();
 
@@ -104,8 +144,8 @@ function run() {
   }
   console.log();
 
-  // 4.5. Remove dev-workflow hooks + statusline from .claude/settings.json
-  // (marker-based; user-defined hooks/statusLine are left intact). The hook
+  // 4.5. Remove dev-workflow hooks + statusline from .claude/settings.json and
+  // .codex/hooks.json (marker-based; user-defined hooks/statusLine are left intact). The hook
   // scripts themselves were removed with .dw/scripts/ above.
   console.log('  Hooks & statusline:');
   try {
@@ -125,8 +165,22 @@ function run() {
   removeFile(path.join(projectRoot, '.opencode', 'package.json'));
   removeFile(path.join(projectRoot, '.dw', 'install-state.json'));
 
-  // 6. Remove legacy .codex/skills/
-  removeDir(path.join(projectRoot, '.codex', 'skills'));
+  // 6. Retire dev-workflow entries from legacy .codex/skills/ (dw-* wrappers and
+  //    bundled-skill copies that pass the contract check) by moving them to
+  //    .dw/.migrated/<ts>/; anything else there belongs to the user or another tool.
+  const codexSkills = path.join(projectRoot, '.codex', 'skills');
+  if (fs.existsSync(codexSkills)) {
+    for (const entry of fs.readdirSync(codexSkills, { withFileTypes: true })) {
+      const target = path.join(codexSkills, entry.name);
+      const isBundledCopy = bundledSkills.includes(entry.name) && isDevWorkflowSkillCopy(target);
+      if (entry.name.startsWith('dw-') || isBundledCopy) {
+        moveToBackup(projectRoot, target, stamp);
+        console.log(`  \x1b[31m-\x1b[0m ${path.relative(projectRoot, target)} [moved to ${path.join(MIGRATED_REL, stamp)}/]`);
+        removed++;
+      }
+    }
+    if (fs.readdirSync(codexSkills).length === 0) fs.rmdirSync(codexSkills);
+  }
 
   // Note: .dw/rules/, .dw/spec/, .dw/intel/ are USER DATA — never removed
   console.log(`\n  ${'='.repeat(40)}`);
@@ -137,6 +191,8 @@ function run() {
   console.log('    .dw/spec/            (PRDs and specs)');
   console.log('    .dw/intel/           (codebase index from /dw-intel --build)');
   console.log('    .dw/minimalism.json  (dw-minimalism intensity preference)');
+  console.log('    .dw/templates/overrides/ (your template overrides)');
+  console.log('    .dw/.migrated/       (anything uninstall or update retired; delete when no longer needed)');
   console.log();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/agent-instructions.md

@@ -27,7 +27,7 @@ During task breakdown, propose local or cross-tool development and a model, effo
 
 Claude can delegate implementation through `/dw-codex-run`; Codex can use `/dw-claude-run`. The parent owns review, corrections, and continuation. Local agents inherit the session model unless the approved task overrides it. Delegate bounded independent work when it improves quality or time; keep tightly coupled or small work local. At most 3 workers per workstream, and never concurrent writers in the same worktree.
 
-Read relevant files first. Use `.dw/intel/` or a code-explorer for broad or unfamiliar flows when useful, checking index claims against current source. Load skill entrypoints only for matching tasks, and references only for the selected mode. Subagents receive a compact packet and return evidence and decisions, not full logs.
+Read relevant files first. Use `.dw/intel/` or a code-explorer for broad or unfamiliar flows when useful, checking index claims against current source. Load skill entrypoints only for matching tasks, and references only for the selected mode. dev-workflow skills live in `.dw/skills/<name>/`; when a command names one, read it from there. `.agents/skills/` and `.claude/skills/` also hold the user's and other tools' skills: outside `update`, delete nothing there without listing it and asking first. Subagents receive a compact packet and return evidence and decisions, not full logs.
 
 ## Completion and boundaries
 

package/scaffold/en/commands/dw-brainstorm.md

@@ -61,7 +61,7 @@ digraph brainstorm_decision {
 
 ## Complementary Skills
 
-When available in the project under `./.agents/skills/`, use these skills to enrich ideation:
+When available in the project under `./.dw/skills/`, use these skills to enrich ideation:
 
 - `dw-council`: invoked by the dispatcher's **council** mode — multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. The dispatcher fires it when 2+ paths tie OR consensus forms too quickly (false-consensus signal). Not invoked on every brainstorm — only when signals justify it.
 - `dw-simplification`: invoked by the dispatcher's **refactor-audit** mode — applies Chesterton's Fence + complexity metrics + the new **deep-modules** reference (deletion test, locality, leverage, interface depth) to every flagged smell.
@@ -345,7 +345,7 @@ turns and it writes files. Because it is stateful and mutating, it starts **only
 
 <critical>Ask exactly ONE unresolved decision per interaction, then wait. Never dump a list of questions.</critical>
 
-Grill is powered by two internal skills (loaded by path from `./.agents/skills/`, never exported):
+Grill is powered by two internal skills (loaded by path from `./.dw/skills/`, never exported):
 - **`dw-grilling`** — the decision-tree interview engine (dependency ordering, one decision per turn, a
   recommended answer for every question, facts discovered rather than asked, the shared-understanding gate).
 - **`dw-domain-modeling`** — the vocabulary engine (canonical terms, fuzzy/overloaded-term challenge, code

package/scaffold/en/commands/dw-bugfix.md

@@ -36,7 +36,7 @@
 
     ## Complementary Skills
 
-    When available in the project at `./.agents/skills/`, use these skills as contextual support without replacing this command:
+    When available in the project at `./.dw/skills/`, use these skills as contextual support without replacing this command:
 
     - `dw-debug-protocol`: **ALWAYS** — runs the bug through the six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Stop-the-line discipline; root-cause over symptom; regression test committed in the same atomic commit. For non-trivial bugs, or after a first fix fails, Step 1 must establish a red-capable feedback loop before theorizing. Non-reproducible bugs follow the instrument-first sub-protocol — no guess fixes without explicit acknowledgement.
     - `dw-verify`: **ALWAYS** — in Direct mode, invoked before committing the fix. The VERIFICATION REPORT must show the original bug symptom no longer reproduces (not just that tests pass).

package/scaffold/en/commands/dw-commit.md

@@ -11,7 +11,7 @@
 
     ## Complementary Skills
 
-    When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
+    When available in the project under `./.dw/skills/`, use these skills as operational support without replacing this command:
 
     - `dw-git-discipline`: **ALWAYS** — enforces atomic commits (one logical intent per commit; refactor separate from feature), Conventional Commits format, lint+tests+build green BEFORE the commit, and bans bypassing pre-commit hooks (`--no-verify`) or amending pushed commits. When mixed changes are detected, splits via `git add -p`.
 

package/scaffold/en/commands/dw-dockerize.md

@@ -44,7 +44,7 @@ This command is **complementary** to `/dw-new-project`:
 - Audit/dockerize report: `.dw/audit/dockerize-<YYYY-MM-DD>.md` (PRD scope: `.dw/spec/prd-<slug>/dockerize.md`)
 - Generated dev artifacts: `<SCOPE>/docker-compose.dev.yml`, `<SCOPE>/Dockerfile.dev`, `<SCOPE>/.dockerignore`
 - Generated prod artifacts: `<SCOPE>/Dockerfile`, `<SCOPE>/docker-compose.prod.yml` (optional), `<SCOPE>/.dockerignore`
-- Recipe source: `.agents/skills/docker-compose-recipes/services/*.yml`
+- Recipe source: `.dw/skills/docker-compose-recipes/services/*.yml`
 
 ## Required Behavior — Pipeline
 
@@ -163,7 +163,7 @@ Without approval: write report (Phase 3 with `status: PLANNED`) and stop.
 #### 2.1 `--dev` artifacts
 
 **`docker-compose.dev.yml`**:
-- Compose service blocks from `.agents/skills/docker-compose-recipes/services/*.yml` per `references/compose-composition.md`.
+- Compose service blocks from `.dw/skills/docker-compose-recipes/services/*.yml` per `references/compose-composition.md`.
 - Add app service(s) at the end: `build: { context: ., dockerfile: Dockerfile.dev }`, `volumes` for hot reload (bind mount source, anonymous volume for `node_modules`/`__pycache__`), `env_file: .env`, `depends_on` with `condition: service_healthy` per `references/healthcheck-patterns.md`.
 - Preserve each recipe's image tag (do NOT convert any of them to a digest — a digest freezes the base and never picks up a security rebuild), the required credential vars, and the `127.0.0.1` binds. The loopback ports intentionally keep the `apps on host` topology working.
 - Header comment: `# Generated by /dw-dockerize on YYYY-MM-DD`.

package/scaffold/en/commands/dw-functional-doc.md

@@ -53,7 +53,7 @@ Works best with project analyzed by `/dw-analyze-project`
 
 ## Complementary Skills
 
-When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command as source of truth:
+When available in the project under `./.dw/skills/`, use these skills as operational support without replacing this command as source of truth:
 
 - `dw-testing-discipline`: support for structuring E2E flows (`references/playwright-recipes.md`), evidence collection patterns, and applying core rules + selector hierarchy to any test the doc references
 - `remotion-best-practices`: mandatory support when there is a final human video, captions, composition, transitions, FFmpeg, or Remotion

package/scaffold/en/commands/dw-harness-audit.md

@@ -29,7 +29,7 @@ You are the dev-workflow harness auditor.
 5. Recommend the top 3 fixes.
 
 ## Runtime degradation triage (on-demand)
-The scorecard above is deterministic **install** health. If instead the *agent* is misbehaving at runtime (loops, objective drift, hallucinated edits, degraded reasoning), that is a different diagnosis: point the user to `.agents/skills/dw-debug-protocol/references/agent-degradation.md` (symptom→cause table + ordered recovery). Advisory only — it does not affect the scorecard.
+The scorecard above is deterministic **install** health. If instead the *agent* is misbehaving at runtime (loops, objective drift, hallucinated edits, degraded reasoning), that is a different diagnosis: point the user to `.dw/skills/dw-debug-protocol/references/agent-degradation.md` (symptom→cause table + ordered recovery). Advisory only — it does not affect the scorecard.
 
 ## Output
 Return a scorecard and do not mutate files. Tell the user to run `dev-workflow repair` for managed-file drift.

package/scaffold/en/commands/dw-intel.md

@@ -64,7 +64,7 @@ Don't refuse to answer — return the best info available.
 
 ### 2. Query shape detection
 
-Classify the user's `{{QUERY}}` into one of the shapes documented in `.agents/skills/dw-codebase-intel/references/query-patterns.md`:
+Classify the user's `{{QUERY}}` into one of the shapes documented in `.dw/skills/dw-codebase-intel/references/query-patterns.md`:
 
 - **where-is** — primary: `files.json`, secondary: `apis.json`
 - **what-uses** — primary: `deps.json` (libs) or `files.json` (symbols)

package/scaffold/en/commands/dw-learn.md

@@ -23,7 +23,7 @@ Gather signals only from what is already persisted:
 4. **Present** candidates in chat as a markdown list — id, trigger, action, confidence, evidence. Do NOT write yet.
 5. **Ask**: "Approve which to store? (ids, or 'all', or 'none'). Any to promote to a constitution principle?"
 6. On approval:
-   - Write each approved instinct to `.dw/memory/instincts/<slug>.md` in the format from `.agents/skills/dw-memory/references/instincts.md` (create or update; never duplicate an existing id).
+   - Write each approved instinct to `.dw/memory/instincts/<slug>.md` in the format from `.dw/skills/dw-memory/references/instincts.md` (create or update; never duplicate an existing id).
    - For any the user chooses to promote, hand off to the constitution flow — propose a `P-NNN` principle at `severity: info` for `/dw-analyze-project` Step 8. Do NOT edit `.dw/constitution.md` directly without the user re-confirming.
 7. Update confidence on existing instincts that new evidence reconfirms or contradicts.
 

package/scaffold/en/commands/dw-new-project.md

@@ -39,7 +39,7 @@ You are a workspace bootstrap lead for the dev-workflow ecosystem. Your job is t
 - Project one-pager: `.dw/spec/projects/{{PROJECT_NAME}}.md` (uses `.dw/templates/project-onepager.md`)
 - Final report: `.dw/spec/projects/{{PROJECT_NAME}}-bootstrap.md`
 - Seeded rules: `.dw/rules/index.md` (minimal, replaceable later by `/dw-analyze-project`)
-- Compose recipes: `.agents/skills/docker-compose-recipes/services/*.yml`
+- Compose recipes: `.dw/skills/docker-compose-recipes/services/*.yml`
 
 ## Required Behavior — Pipeline
 
@@ -157,7 +157,7 @@ If fullstack:
 
 #### 3.3 Generate `docker-compose.dev.yml`
 
-1. Read `.agents/skills/docker-compose-recipes/SKILL.md` and the relevant `services/<name>.yml` files.
+1. Read `.dw/skills/docker-compose-recipes/SKILL.md` and the relevant `services/<name>.yml` files.
 2. Apply the merge algorithm in `references/compose-composition.md`:
    - Concatenate selected service blocks under `services:`.
    - Aggregate named volumes under `volumes:`.
@@ -300,7 +300,7 @@ monorepo: <pnpm-workspaces|turborepo|nx|none>
 | ... | ... | ... |
 
 ## Services Composed
-<table of services with port + UI URL + credential requirements, sourced from .agents/skills/docker-compose-recipes/>
+<table of services with port + UI URL + credential requirements, sourced from .dw/skills/docker-compose-recipes/>
 
 ## Next Steps
 1. `cp .env.example .env`, generate unique local secrets, and set every required value such as `POSTGRES_PASSWORD`.

package/scaffold/en/commands/dw-plan.md

@@ -30,7 +30,7 @@ You are a planning orchestrator that takes an idea through the full PRD → Tech
 
 ## Complementary Skills
 
-When available under `./.agents/skills/`, use these as planning support:
+When available under `./.dw/skills/`, use these as planning support:
 
 - `dw-source-grounding`: **ALWAYS** in TechSpec stage — every framework/library decision must cite official docs with version + retrieval date.
 - `dw-ui-discipline`: **REQUIRED** when the PRD has UI surfaces — runs the 4 grounding questions before any visual design lands in the TechSpec.
@@ -169,7 +169,7 @@ Runs when default mode (after TechSpec approval) OR `plan tasks`.
 3. **End-to-end coverage:** every user-facing flow has backend + frontend + functional UI subtasks if applicable.
 4. **Test placement (`dw-testing-discipline`):** every test-adding subtask names its invariant per the placement doctrine. Owning layer specified.
 5. **Constitution alignment:** every task lists `Constitution: respects P-NNN` or `Constitution: deviates P-NNN — ADR planned: <slug>` or `Constitution: n/a — reason: <one-liner>`.
-6. **LLM-eval subtask (when applicable):** if the PRD has an AI feature, one task must include an Eval Plan subtask (reference dataset path, oracle rungs, judge calibration, target metrics).
+6. **LLM-eval subtask (when applicable):** if the PRD has an AI feature, one task must include an Eval Plan subtask (reference dataset path, oracle rungs, judge calibration, target metrics), ordered before the implementation subtasks: behavior spec (when / does / must not / keeps working), cases, and a baseline run on the current code where the new-behavior cases fail.
 7. **Dependency declaration:** each task explicitly lists which previous tasks it depends on. Write the field as `Depends on: none` or `Depends on: 1.0, 2.0` in `tasks.md` and each `<N>_task.md`. Validation rejects cycles.
 8. **Output locations:**
    - Summary: `.dw/spec/prd-<feature-slug>/tasks.md`