@brunosps00/dev-workflow 2.6.0 → 2.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,78 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.7.0] — 2026-11-09
+
+### Added
+
+- **Content stress in `dw-ui-discipline`.** New `references/content-stress.md`: a catalog of
+  realistic worst-case values (long and one-letter names, unbreakable emails, `1 members`,
+  1,000+ rows, RTL, emoji-first names), failure signatures with their CSS cause and fix, and
+  a per-field truncate/wrap/clamp rule. `/dw-qa` runs it in UI mode — worst-case data injected
+  at the data boundary (the project's mocks, or `page.route()`, never by editing the
+  component), checked at the real container width, 320px, 200% zoom and dark/RTL — and
+  `/dw-redesign-ui` runs it at validation. Adapted from `break-ui` in
+  [`emilkowalski/skills`](https://github.com/emilkowalski/skills) (MIT).
+- **Mobile platform fixes** in `responsive.md`: hover gated by `(hover: hover) and
+  (pointer: fine)`, `100dvh`/`100svh`, 16px inputs instead of disabling zoom,
+  `touch-action: manipulation`, `overscroll-behavior`, `viewport-fit=cover` for safe areas,
+  `theme-color` per scheme, and the rule that none of it is verified in device emulation.
+- **Command usage telemetry.** The `session-cost` hook records a `commands` object (reads of
+  `.dw/commands/<name>.md`, or a Skill call naming a command) beside `skills`.
+  `/dw-skill-health` reports per-command usage and classifies five command families as
+  `MERGE CANDIDATE`, `KEEP SEPARATE` or `TOO EARLY` (20 sessions or 30 days of window).
+- `/dw-review` checks motion changes against the escalation triggers in `motion.md` and
+  data-rendering changes against the content-stress static signals.
+- `/dw-redesign-ui` directions must diverge on a named axis (layout, density, personality,
+  motion, interaction model) and are named for it, never "Option A/B".
+- **Eval-first in `dw-llm-eval`**, from LangChain's eval-driven development post: a four-line
+  behavior spec (when / does / must not / keeps working) and a baseline run on the current code
+  before the change, where new-behavior cases must fail; a `holdout` split (~20%) never tuned
+  against; and drift compared case by case — a case that passed and now fails blocks, whatever
+  the average says. `/dw-plan` orders the Eval Plan subtask before implementation; `/dw-qa --ai`
+  lists pass → fail flips and reports `holdout` apart from `dev`.
+- **Eval runs are recorded** in `evals/runs/` and compared scenario by scenario; a change that
+  adds a dangerous surface adds its eval in the same change. New eval 7 covers deletion in
+  `update` and `uninstall`.
+
+### Changed
+
+- **Bundled skills install to `.dw/skills/`** instead of `.agents/skills/`. Codex, Copilot and
+  OpenCode all scan `.agents/skills/`, so each listed the 27 bundled skills as model-invocable
+  next to the command wrappers; commands load them by path, and the tool indexes now hold only
+  the `dw-*` entry points. `update` retires a legacy copy from `.agents/skills/` only when it is
+  a dev-workflow copy — its `SKILL.md` carries the Structured Return contract and, when the
+  previous install state tracked files, is one of them — and leaves a same-named skill
+  installed from elsewhere in place, printed as `[kept]`; `uninstall` follows the same rule and
+  `doctor` warns about leftovers. Commands, agent instructions and the `/dw-update` snapshot
+  point at the new location.
+- **`update` and `uninstall` no longer delete what they retire.** Legacy skill copies, removed
+  skills, orphan `dw-*` wrappers and removed command sources are moved to
+  `.dw/.migrated/<timestamp>/` with their relative paths, and files the team added inside a
+  retired copy are named in the output. A terminal `npx … update` takes no snapshot, so this is
+  the copy those users keep. The migration now runs after the new skills are copied, so an
+  interrupted update leaves the old copies in place.
+- **`motion.md` rewritten.** Frequency decides before easing (keyboard-triggered and 100+/day
+  actions do not animate); `ease-in` is never used on UI, exits included (the previous rule
+  said exits ease in); no `scale(0)`, no `transition: all`; trigger-anchored
+  `transform-origin`; transitions over keyframes for rapid triggers; property cost tiers;
+  `will-change` only after a measured problem; a removal gate with its hazards. Springs are
+  allowed only for gesture-driven motion. Adapted from `emilkowalski/skills` (MIT).
+- Reduced motion means fewer and gentler animations, not zero; the accessibility floor adds
+  item 11 (zoom is never disabled; content survives 200% zoom).
+
+### Fixed
+
+- `/dw-update --rollback` copied the `.agents/skills` snapshot into the existing folder,
+  nesting it as `.agents/skills/agents-skills` instead of restoring it.
+- A command wrapper under `.claude/skills/` was counted as a skill use in `costs.jsonl`.
+- `/dw-update --rollback` merged the snapshot over the current files, so files added by the
+  newer release survived it; managed `.dw/` folders are now replaced, and the snapshot also
+  saves and restores `.dw/install-state.json`. `/dw-update` checks the installed version
+  against the CLI's `Installed version` line instead of accepting the old state file.
+- `uninstall` removed `.codex/skills/` wholesale; it now removes only `dw-*` entries and
+  dev-workflow skill copies there.
+
 ## [2.6.0] — 2026-10-07
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@ This will:
 2. Create `.dw/commands/` with workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
 4. Create `.dw/rules/` (populated by `/dw-analyze-project`) + a curated `.dw/rules-library/` declarative baseline per stack (loaded lazily via `.dw/config/stack-mappings.json`)
-5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
+5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.dw/skills/` — outside every agent's skill index; commands load them by path
 6. Generate skill wrappers and project agents for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
 8. Install enforcement hooks (git guardrails + a `SessionEnd` token-cost tracker → `.dw/metrics/costs.jsonl`) + a statusline (branch · active spec · minimalism mode · today's estimated spend) into `.claude/settings.json`, and the git guardrails into `.codex/hooks.json` for Codex (merge-aware — your own hooks/statusline are never overwritten; Codex runs project hooks only after you trust them)
@@ -226,6 +226,7 @@ your-project/
 │   │   └── concerns.md    # Risk map: hot spots, fragile integrations, bug history (Step 9 of /dw-analyze-project)
 │   ├── constitution.md    # Declarative principles (auto-installed when missing)
 │   ├── skill-registry.json # Local skill taxonomy, triggers, owners, load policy, and context limits
+│   ├── skills/            # Bundled skills, loaded by path from commands (not listed in any agent's skill index)
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
 │   ├── spec/              # PRD directories — each contains tasks-validation.md
@@ -241,7 +242,7 @@ your-project/
 │   ├── skills/            # Claude Code wrappers
 │   ├── agents/            # Claude Code project agents
 │   └── settings.json      # MCP servers (Context7, Playwright)
-├── .agents/skills/        # Codex/Copilot wrappers + bundled skills
+├── .agents/skills/        # Codex/Copilot wrappers (bundled skills live in .dw/skills/)
 ├── .agents/agents/        # Codex/Copilot fallback agent definitions
 ├── .github/agents/        # GitHub Copilot custom agents
 ├── .opencode/commands/    # OpenCode wrappers
@@ -274,7 +275,7 @@ npx @brunosps00/dev-workflow subtask list
 
 ## Bundled Skills
 
-Skills installed to `.agents/skills/` for use by all commands. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, context limit, invocation control (`model` vs `explicit`), and à-la-carte `exportable` flag.
+Skills installed to `.dw/skills/` for use by all commands. They sit outside the directories Codex, Copilot, OpenCode and Claude Code scan for model-invocable skills (`.agents/skills/`, `.claude/skills/`, `.github/skills/`, `.opencode/skills/`), so each tool's skill index lists only the `dw-*` command entry points; commands read the skills they need by path. Releases up to 2.6.0 installed them under `.agents/skills/`; `update` retires those copies once the new ones are in place, moving them to `.dw/.migrated/<timestamp>/` rather than deleting them, and leaves a same-named skill you installed from elsewhere where it is. The bundle is governed by `scaffold/skill-registry.json`, which records each skill's kind, tier, owner, trigger, expected output, load policy, context limit, invocation control (`model` vs `explicit`), and à-la-carte `exportable` flag.
 
 Skill kinds:
 
@@ -378,6 +379,8 @@ Spec-Driven Development patterns — declarative constitution (`.dw/constitution
 
 UI discipline (`dw-ui-discipline`) and testing doctrine (`dw-testing-discipline`) are original works in this repository. Earlier dev-workflow versions (≤0.13.x) drew on `pedronauck/skills` `ui-craft` and `testing-boss` as inspiration, but in v0.14.0 those skills were rewritten clean-room after a license audit confirmed that the upstream repo has no explicit LICENSE file at root — the README's MIT claim is unverified. The underlying ideas (grounding before design; behavior over mocks; mutation over coverage) are widely-documented general software engineering principles available in many sources (Beck, Fowler, Meszaros, Feathers, Google SRE Book, WCAG specifications). Browser-DevTools patterns from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) (MIT) live inside `dw-testing-discipline/references/` (`security-boundary.md`, `three-workflow-patterns.md`).
 
+The motion, mobile-web and content-stress references in `dw-ui-discipline` (`motion.md`, the "Mobile platform fixes" section of `responsive.md`, `content-stress.md`) adapt rules from [`emilkowalski/skills`](https://github.com/emilkowalski/skills) by Emil Kowalski (MIT): `emil-design-eng`, `review-animations`, `animation-performance`, `remove-animations`, `mobile-native` and `break-ui`. See [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md), section 15.
+
 Minimalism discipline (`dw-minimalism`), per-skill invocation control (`disable-model-invocation` on hidden/internal command wrappers), the git-guardrails enforcement hook, and à-la-carte plugin distribution were adapted from [`DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail) (MIT — the "lazy senior" decision ladder, intensity modes, and statusline) and [`mattpocock/skills`](https://github.com/mattpocock/skills) (MIT — user-vs-model invocation and `git-guardrails-claude-code`). See [docs/skills-ecosystem-comparison.md](docs/skills-ecosystem-comparison.md) for the full gap analysis and what was and was not adopted.
 
 Incident response (`dw-incident-response`) adapted from [`wilsto/claude-code-starter-kit/incident-response`](https://github.com/wilsto/claude-code-starter-kit) (MIT). The 5-phase workflow structure and runbook templates come from there. wilsto credits the upstream `wshobson/agents` plugin `incident-response` (v1.3.0); attribution chain preserved. Additional reading cited in the skill: Google SRE Book, Etsy Debriefing Facilitation Guide, PagerDuty Incident Response Documentation.
@@ -431,7 +434,7 @@ v1.0.0 consolidated the legacy command surface into the current `dw-*` pipeline.
 On the next `npx @brunosps00/dev-workflow update`, the following happens automatically:
 
 1. The 15 renamed commands' wrappers are detected as orphans (their names no longer exist in `lib/constants.js`) and removed from `.claude/skills/`, `.agents/skills/`, and `.opencode/commands/`.
-2. The migrator prints each removal with the friendly "old → new" mapping (e.g., `[orphan] Removing wrapper .agents/skills/dw-create-prd (replaced in v1.0.0 by 'dw-plan prd')`).
+2. The migrator prints each removal with the friendly "old → new" mapping (e.g., `[orphan] Retiring wrapper .agents/skills/dw-create-prd (replaced in v1.0.0 by 'dw-plan prd')`).
 3. The current command wrappers are installed for the consolidated commands.
 4. The bundled skills are refreshed.
 

package/lib/doctor.js

@@ -9,7 +9,14 @@ const {
   AGENT_TARGETS,
 } = require('./agents');
 const { readInstallState, STATE_RELATIVE_PATH } = require('./install-state');
-const { validateSkillRegistry, readSkillRegistry, validateSkillStructuredReturn } = require('./skill-registry');
+const {
+  validateSkillRegistry,
+  readSkillRegistry,
+  validateSkillStructuredReturn,
+  BUNDLED_SKILLS_REL,
+  LEGACY_BUNDLED_SKILLS_REL,
+} = require('./skill-registry');
+const { isDevWorkflowSkillCopy } = require('./migrate-skills');
 const { GIT_GUARDRAILS_SCRIPT, GIT_GUARDRAILS_CMD, STATUSLINE_CMD, HOOKS_DIR_MARKER, CODEX_HOOKS_FILE } = require('./hooks');
 const removedCommands = require('./removed-commands');
 
@@ -177,12 +184,20 @@ function checkSkillRegistry(projectRoot, issues, warnings) {
   const registry = readSkillRegistry();
   for (const entry of registry.skills) {
     if (!entry.bundled) continue;
-    const skillPath = path.join(projectRoot, '.agents', 'skills', entry.name, 'SKILL.md');
+    const skillPath = path.join(projectRoot, BUNDLED_SKILLS_REL, entry.name, 'SKILL.md');
     if (!fs.existsSync(skillPath)) {
       issues.push(`Missing bundled skill: ${path.relative(projectRoot, skillPath)}`);
     } else {
       validateSkillStructuredReturn(entry.name, skillPath, issues, `Installed bundled skill ${entry.name}`);
     }
+    // A copy left under .agents/skills/ by a release up to 2.6.0 is still listed
+    // as model-invocable by Codex, Copilot and OpenCode. `update` removes it.
+    const legacySkillPath = path.join(projectRoot, LEGACY_BUNDLED_SKILLS_REL, entry.name, 'SKILL.md');
+    if (isDevWorkflowSkillCopy(path.dirname(legacySkillPath))) {
+      warnings.push(
+        `Legacy bundled skill copy at ${path.relative(projectRoot, path.dirname(legacySkillPath))} is still in agent skill indexes; run update to move it to ${BUNDLED_SKILLS_REL}/`
+      );
+    }
   }
 }
 

package/lib/init.js

@@ -12,6 +12,7 @@ const { hasExistingInstall, readInstallState, writeInstallState, listManagedFile
 const { resolveInstallSelection } = require('./profiles');
 const { ensureSubtaskLayout } = require('./subtasks');
 const { printPostUpdateActions } = require('./post-update');
+const { BUNDLED_SKILLS_REL } = require('./skill-registry');
 
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
@@ -33,11 +34,10 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     console.log('  Existing dev-workflow install detected; reconciling managed files.\n');
   }
 
-  // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected)
-  // 0.1. Skill migration: removed bundled skills + orphan dw-* wrappers (idempotent)
+  // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected).
+  // The skill migration runs later (5.55), once the new copies exist.
   if (shouldReconcile) {
     migrateGsd(projectRoot);
-    migrateSkills(projectRoot);
   }
 
   // 1. Select language
@@ -332,22 +332,32 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
   ensureSubtaskLayout(projectRoot);
   touchedFiles.push(path.join(projectRoot, '.dw', 'subtasks', '.gitignore'));
 
-  // 5.5. Copy bundled skills to .agents/skills/
+  // 5.5. Copy bundled skills to .dw/skills/ — outside every agent CLI's skill
+  // index; commands load them by path. Legacy copies under .agents/skills/ are
+  // retired by migrateSkills() (step 5.55) on update/repair/re-init.
   const skillsSrcDir = path.join(SCAFFOLD_DIR, 'skills');
   if (require('fs').existsSync(skillsSrcDir)) {
     console.log('  Bundled skills:');
     const skillsResults = copyDir(
       skillsSrcDir,
-      path.join(projectRoot, '.agents', 'skills'),
+      path.join(projectRoot, BUNDLED_SKILLS_REL),
       managedForce
     );
     totalCreated += skillsResults.created;
     totalSkipped += skillsResults.skipped;
     totalOverwritten += skillsResults.overwritten;
-    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, '.agents', 'skills')));
+    touchedFiles.push(...listFilesRecursive(path.join(projectRoot, BUNDLED_SKILLS_REL)));
     console.log(`    ${skillsResults.created} created, ${skillsResults.skipped} skipped, ${skillsResults.overwritten} overwritten\n`);
   }
 
+  // 5.55. Skill migration: removed bundled skills, legacy .agents/skills copies,
+  // orphan dw-* wrappers and removed command sources. Runs after the copy above
+  // so an interrupted update never leaves neither copy, and moves what it retires
+  // to .dw/.migrated/<ts>/ instead of deleting it (idempotent).
+  if (shouldReconcile) {
+    migrateSkills(projectRoot, { priorState });
+  }
+
   // 5.6. Generate platform-native/fallback agents from the selected modules.
   console.log('  Agents:');
   const agentResults = generateAgents(projectRoot, selection.modules, managedForce);

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,