bmad-method 6.11.1-next.5 → 6.11.1-next.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.11.1-next.5",
+  "version": "6.11.1-next.7",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -44,7 +44,7 @@
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
     "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:site-url && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
-    "test:install": "node test/test-installation-components.js",
+    "test:install": "node test/test-installation-components.js && node test/test-shim-policy.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-build-auto-renderer.js",
     "test:retrospective": "uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_git_evidence.py && uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_sprint_status.py",

package/src/bmm-skills/plan/bmad-generate-project-context/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-generate-project-context
 description: 'Deprecated — forwards to bmad-project-context. Use when the user says "generate project context" or "create project context"'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-project-context

package/src/bmm-skills/ship/bmad-build/step-oneshot.md

@@ -25,18 +25,17 @@ If a layer's instruction requires subagents and none are available, for each suc
 
 ### Classify
 
-Deduplicate all review findings. Three categories only:
+Deduplicate all review findings, then route each finding in this order:
 
-- **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
+- **patch** — Patch every finding caused or exposed by this change that shows a defect that actually occurs, missing coverage for a specific case, or a broken gate or convention — not a state nothing reaches — and whose smallest fix is trivial, adds no public surface, and guards no state the finding did not demonstrate. Apply that smallest fix immediately.
+- **HALT** — HALT on every finding caused or exposed by this change that shows the same evidence but whose smallest fix fails any of those conditions. Present it to the human for decision before proceeding.
+- **defer** — Defer every other real finding, including pre-existing issues and improvement ideas. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
   ```markdown
   - source_spec: `{spec_file}`
     summary: <one sentence>
     evidence: <why this is real>
   ```
-- **reject** — noise. Drop silently.
-
-If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+- **reject** — Reject only noise. Drop silently.
 
 ### Generate Spec Trace
 

package/src/bmm-skills/v6-shims/bmad-create-architecture/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-architecture
 description: 'Deprecated — forwards to bmad-architecture (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-architecture (create intent)

package/src/bmm-skills/v6-shims/bmad-create-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-prd
 description: 'Deprecated — forwards to bmad-prd (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (create intent)

package/src/bmm-skills/v6-shims/bmad-create-story/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-story
 description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Create Story Workflow

package/src/bmm-skills/v6-shims/bmad-dev-auto/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-dev-auto
 description: "Deprecated: forwards to bmad-build-auto. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Deprecated Build Auto Alias

package/src/bmm-skills/v6-shims/bmad-dev-story/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-dev-story
 description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Dev Story Workflow

package/src/bmm-skills/v6-shims/bmad-document-project/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-document-project
 description: 'Deprecated — forwards to bmad-project-context. Use when the user says "document this project" or "generate project docs"'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-project-context

package/src/bmm-skills/v6-shims/bmad-domain-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-domain-research
 description: 'Deprecated — forwards to bmad-deep-recon (domain type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (domain type)

package/src/bmm-skills/v6-shims/bmad-edit-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-edit-prd
 description: 'Deprecated — forwards to bmad-prd (update intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (update intent)

package/src/bmm-skills/v6-shims/bmad-market-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-market-research
 description: 'Deprecated — forwards to bmad-deep-recon (market type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (market type)

package/src/bmm-skills/v6-shims/bmad-quick-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-quick-dev
 description: "Deprecated: forwards to bmad-build. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Deprecated Build Alias

package/src/bmm-skills/v6-shims/bmad-sprint-status/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-sprint-status
 description: 'Deprecated — forwards to bmad-sprint-planning (status view)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-sprint-planning (status view)

package/src/bmm-skills/v6-shims/bmad-technical-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-technical-research
 description: 'Deprecated — forwards to bmad-deep-recon (technical type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (technical type)

package/src/bmm-skills/v6-shims/bmad-validate-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-validate-prd
 description: 'Deprecated — forwards to bmad-prd (validate intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (validate intent)

package/src/core-skills/v6-shims/bmad-editorial-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-editorial-review
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with the `structure` and `prose` lenses — both, structure first, so prose runs on top of the structure findings — unless the caller asked for a structure-only or prose-only review, in which case pass only that lens. Pass through any `also_consider` areas, and forward this skill's resolved `[workflow]` fields as pre-resolved values — but only those that resolved to something, since an empty value here means no legacy override exists and bmad-review's own default should stand: `reader_type`, `style_guide`, `review_guidance`, `output_preferences`, `persistent_facts`, `activation_steps_prepend`, `activation_steps_append`, `on_complete`, and `review_output_path` as the report path. Present the findings in the legacy shape: the two-pass findings table `| Pass | Original Text | Revised Text | Changes |` with the purpose/audience read above it and, when the structure pass ran, the reduction summary below it — and no other lens's output.

package/src/core-skills/v6-shims/bmad-editorial-review-prose/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-editorial-review-prose
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `prose` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy shape: a three-column markdown table `| Original Text | Revised Text | Changes |` — no Pass column, no preamble above the table. If no issues are found, output exactly: `No editorial issues identified`.

package/src/core-skills/v6-shims/bmad-editorial-review-structure/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-editorial-review-structure
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `structure` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy report shape: a `## Document Summary` block (purpose, audience, reader type, structure model, current length), a `## Recommendations` list of numbered `[CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE]` entries each with rationale and word impact, and a closing `## Summary` (total recommendations, estimated reduction) — not the findings table. If no structural issues are found, output exactly: `No substantive changes recommended`.

package/src/core-skills/v6-shims/bmad-review-adversarial-general/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-review-adversarial-general
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `adversarial` lens, passing through any `also_consider` areas. Present the findings as a Markdown list — descriptions only, no severity, priority, or ranking; no JSON block.

package/src/core-skills/v6-shims/bmad-review-edge-case-hunter/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-review-edge-case-hunter
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `edge-case-hunter` lens, passing through any `also_consider` areas. Output ONLY the raw findings JSON array in the legacy shape: the four standard fields (plus `kind`/`confidence` on deletion findings), no `lens` field, no markdown wrapping, no extra text. `[]` is valid when nothing is found.

package/src/core-skills/v6-shims/bmad-review-verification-gap/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-review-verification-gap
 description: 'Deprecated — forwards to bmad-review'
+metadata:
+  lifecycle: shim
 ---
 
 Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `verification-gap` lens. Present the markdown rendering only (no JSON block), listing any `gap_shape: "other"` findings under an `## Other findings` heading. When there are no findings at all, output exactly this single line: `No verification gaps found.`

package/tools/installer/commands/install.js

@@ -34,6 +34,8 @@ module.exports = {
     ['--document-output-language <lang>', 'Language for document output (default: English)'],
     ['--output-folder <path>', 'Output folder path relative to project root (default: _bmad-output)'],
     ['--custom-source <sources>', 'Comma-separated Git URLs or local paths to install custom modules from'],
+    ['--shims', 'Install deprecated compatibility shim skills when the selected modules provide them'],
+    ['--no-shims', 'Do not install deprecated compatibility shim skills'],
     ['-y, --yes', 'Accept all defaults and skip prompts where possible'],
     [
       '--channel <channel>',

package/tools/installer/core/config.js

@@ -15,6 +15,7 @@ class Config {
     quickUpdate,
     channelOptions,
     setOverrides,
+    installShims,
   }) {
     this.directory = directory;
     this.modules = Object.freeze([...modules]);
@@ -32,6 +33,7 @@ class Config {
     // Intentionally NOT integrated with the prompt/template/schema flow; see
     // `tools/installer/set-overrides.js` for the rationale and tradeoffs.
     this.setOverrides = setOverrides || {};
+    this.installShims = typeof installShims === 'boolean' ? installShims : undefined;
     Object.freeze(this);
   }
 
@@ -58,6 +60,7 @@ class Config {
       quickUpdate: userInput._quickUpdate || false,
       channelOptions: userInput.channelOptions || null,
       setOverrides: userInput.setOverrides || {},
+      installShims: userInput.installShims,
     });
   }
 

package/tools/installer/core/installer.js

@@ -13,6 +13,7 @@ const { InstallPaths } = require('./install-paths');
 const { ExternalModuleManager } = require('../modules/external-manager');
 const { resolveModuleVersion } = require('../modules/version-resolver');
 const { MODULE_HELP_CSV_HEADER } = require('../modules/module-help-schema');
+const { inferShimPreference, readInstalledSkillIds } = require('./shim-policy');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
@@ -42,6 +43,21 @@ class Installer {
       const paths = await InstallPaths.create(config);
       const officialModules = await OfficialModules.build(config, paths);
       const existingInstall = await ExistingInstall.detect(paths.bmadDir);
+      const availableShims = await officialModules.discoverShims(config.modules, {
+        channelOptions: config.channelOptions,
+      });
+      const previousManifest = existingInstall.installed ? await this.manifest.read(paths.bmadDir) : null;
+      const installedSkillIds = existingInstall.installed ? await readInstalledSkillIds(paths.bmadDir) : new Set();
+      const shimPolicy = {
+        available: availableShims.length > 0,
+        install: inferShimPreference({
+          requested: config.installShims,
+          persisted: previousManifest?.installShims,
+          availableShims,
+          installedSkillIds,
+          existing: existingInstall.installed,
+        }),
+      };
 
       try {
         await warnPreNativeSkillsLegacy({
@@ -92,6 +108,7 @@ class Installer {
         addResult,
         officialModules,
         previousSkillManifestRows,
+        shimPolicy,
       );
 
       await this._setupIdes(config, allModules, paths, addResult, previousSkillIds);
@@ -225,9 +242,11 @@ class Installer {
     addResult,
     officialModules,
     previousSkillManifestRows = [],
+    shimPolicy = null,
   ) {
     const isQuickUpdate = config.isQuickUpdate();
     const moduleConfigs = officialModules.moduleConfigs;
+    const resolvedShimPolicy = shimPolicy || { available: false, install: false };
 
     const dirResults = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
 
@@ -251,6 +270,7 @@ class Installer {
           await this._installOfficialModules(config, paths, officialModuleIds, addResult, isQuickUpdate, officialModules, {
             message,
             installedModuleNames,
+            shimPolicy: resolvedShimPolicy,
           });
 
           return `${allModules.length} module(s) ${isQuickUpdate ? 'updated' : 'installed'}`;
@@ -325,6 +345,8 @@ class Installer {
           ides: config.ides || [],
           preservedModules: modulesForCsvPreserve,
           moduleConfigs,
+          installShims: resolvedShimPolicy.install,
+          shimsAvailable: resolvedShimPolicy.available,
         });
         await this._appendPreservedSkillManifestRows(paths.bmadDir, previousSkillManifestRows, preservedModules);
 
@@ -727,7 +749,7 @@ class Installer {
    * @param {Object} ctx - Shared context: { message, installedModuleNames }
    */
   async _installOfficialModules(config, paths, officialModuleIds, addResult, isQuickUpdate, officialModules, ctx) {
-    const { message, installedModuleNames } = ctx;
+    const { message, installedModuleNames, shimPolicy } = ctx;
     const { CustomModuleManager } = require('../modules/custom-module-manager');
 
     for (const moduleName of officialModuleIds) {
@@ -749,6 +771,7 @@ class Installer {
           installer: this,
           silent: true,
           channelOptions: config.channelOptions,
+          installShims: shimPolicy.install,
         },
       );
 
@@ -1500,6 +1523,7 @@ class Installer {
       // (`applySetOverrides`) runs at the end of quick-update too. The
       // installer.install path applies them after writeCentralConfig.
       setOverrides: config.setOverrides || {},
+      installShims: config.installShims,
       actionType: 'install',
       _quickUpdate: true,
       _preserveModules: skippedModules,

package/tools/installer/core/manifest-generator.js

@@ -58,6 +58,8 @@ class ManifestGenerator {
     this.bmadDir = bmadDir;
     this.bmadFolderName = path.basename(bmadDir); // Get the actual folder name (e.g., '_bmad' or 'bmad')
     this.allInstalledFiles = installedFiles;
+    this.installShims = options.installShims === true;
+    this.shimsAvailable = options.shimsAvailable === true;
 
     if (!Object.prototype.hasOwnProperty.call(options, 'ides')) {
       throw new Error('ManifestGenerator requires `options.ides` to be provided – installer should supply the selected IDEs array.');
@@ -378,6 +380,10 @@ class ManifestGenerator {
       ides: this.selectedIdes,
     };
 
+    if (this.shimsAvailable) {
+      manifest.installation.installShims = this.installShims;
+    }
+
     // Clean the manifest to remove any non-serializable values
     const cleanManifest = structuredClone(manifest);
 

package/tools/installer/core/manifest.js

@@ -61,6 +61,10 @@ class Manifest {
       ides: data.ides || [],
     };
 
+    if (typeof data.installShims === 'boolean') {
+      manifestData.installation.installShims = data.installShims;
+    }
+
     // Write YAML manifest
     // Clean the manifest data to remove any non-serializable values
     const cleanManifestData = structuredClone(manifestData);
@@ -106,6 +110,7 @@ class Manifest {
           version: manifestData.installation?.version,
           installDate: manifestData.installation?.installDate,
           lastUpdated: manifestData.installation?.lastUpdated,
+          installShims: manifestData.installation?.installShims,
           modules: moduleNames, // Simple array of module names for backward compatibility
           modulesDetailed: hasDetailedModules ? modules : null, // New detailed format
           ides: manifestData.ides || [],
@@ -153,6 +158,7 @@ class Manifest {
       version: manifest.installation?.version,
       installDate: manifest.installation?.installDate,
       lastUpdated: manifest.installation?.lastUpdated,
+      installShims: manifest.installation?.installShims,
       modules: moduleNames,
       modulesDetailed: hasDetailedModules ? modules : null,
       ides: manifest.ides || [],

package/tools/installer/core/shim-policy.js

@@ -0,0 +1,91 @@
+const path = require('node:path');
+const fs = require('../fs-native');
+const yaml = require('yaml');
+const csv = require('csv-parse/sync');
+
+function parseSkillMetadata(content) {
+  const normalized = content.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  try {
+    const frontmatter = yaml.parse(match[1]);
+    return frontmatter && typeof frontmatter === 'object' ? frontmatter : null;
+  } catch {
+    return null;
+  }
+}
+
+function isShimSkill(metadata) {
+  return metadata?.metadata?.lifecycle === 'shim';
+}
+
+async function discoverShims(modulePath) {
+  const shims = [];
+
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    const skillFile = path.join(dir, 'SKILL.md');
+    if (await fs.pathExists(skillFile)) {
+      const metadata = parseSkillMetadata(await fs.readFile(skillFile, 'utf8'));
+      if (isShimSkill(metadata)) {
+        shims.push({
+          id: metadata.name || path.basename(dir),
+          directory: dir,
+          relativeDirectory: path.relative(modulePath, dir),
+        });
+      }
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+      await walk(path.join(dir, entry.name));
+    }
+  };
+
+  await walk(modulePath);
+  return shims;
+}
+
+async function readInstalledSkillIds(bmadDir) {
+  const ids = new Set();
+  const manifestPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
+  if (!(await fs.pathExists(manifestPath))) return ids;
+
+  try {
+    const content = await fs.readFile(manifestPath, 'utf8');
+    const records = csv.parse(content, { columns: true, skip_empty_lines: true });
+    for (const record of records) {
+      if (record.canonicalId) ids.add(record.canonicalId);
+    }
+  } catch {
+    // A missing or unreadable legacy manifest means there is no reliable
+    // evidence that compatibility shims were installed.
+  }
+
+  return ids;
+}
+
+function inferShimPreference({ requested, persisted, availableShims = [], installedSkillIds = new Set(), existing = false }) {
+  if (availableShims.length === 0) return false;
+  if (typeof requested === 'boolean') return requested;
+  if (typeof persisted === 'boolean') return persisted;
+  if (!existing) return false;
+
+  return availableShims.some((shim) => installedSkillIds.has(shim.id));
+}
+
+module.exports = {
+  discoverShims,
+  inferShimPreference,
+  isShimSkill,
+  parseSkillMetadata,
+  readInstalledSkillIds,
+};

package/tools/installer/modules/official-modules.js

@@ -5,6 +5,7 @@ const prompts = require('../prompts');
 const { getProjectRoot, getSourcePath, getModulePath } = require('../project-root');
 const { CLIUtils } = require('../cli-utils');
 const { ExternalModuleManager } = require('./external-manager');
+const { discoverShims } = require('../core/shim-policy');
 
 class OfficialModules {
   constructor(options = {}) {
@@ -131,6 +132,23 @@ class OfficialModules {
     return { modules };
   }
 
+  async discoverShims(moduleNames = [], options = {}) {
+    const shims = [];
+
+    for (const moduleName of moduleNames) {
+      const sourcePath = await this.findModuleSource(moduleName, {
+        silent: true,
+        channelOptions: options.channelOptions,
+      });
+      if (!sourcePath) continue;
+
+      const moduleShims = await discoverShims(sourcePath);
+      for (const shim of moduleShims) shims.push({ ...shim, module: moduleName });
+    }
+
+    return shims;
+  }
+
   /**
    * Get module information from a module path
    * @param {string} modulePath - Path to the module directory
@@ -296,9 +314,13 @@ class OfficialModules {
             `Aborting to avoid a partial install with no skills.`,
         );
       }
-      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig, {
+        installShims: options.installShims,
+      });
     } else {
-      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig, {
+        installShims: options.installShims,
+      });
     }
 
     if (!options.skipModuleInstaller) {
@@ -336,7 +358,7 @@ class OfficialModules {
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
    * @param {Object} moduleConfig - Module configuration passed to copy filtering
    */
-  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}, installOptions = {}) {
     await fs.ensureDir(targetPath);
 
     // Copy each skill directory, flattened by leaf name. Leaf names must be
@@ -354,7 +376,7 @@ class OfficialModules {
       }
       seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig, installOptions);
     }
 
     // Place module-help.csv at the module root.
@@ -385,7 +407,9 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig, {
+      installShims: options.installShims,
+    });
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {
@@ -522,11 +546,19 @@ class OfficialModules {
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
    * @param {Object} moduleConfig - Module configuration with conditional flags
    */
-  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
+  async copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback = null, moduleConfig = {}, installOptions = {}) {
     // Get all files in source
     const sourceFiles = await this.getFileList(sourcePath);
+    const shimDirectories =
+      installOptions.installShims === false
+        ? (await discoverShims(sourcePath)).map((shim) => shim.relativeDirectory.split(path.sep).join('/'))
+        : [];
 
     for (const file of sourceFiles) {
+      const normalizedFile = file.split(path.sep).join('/');
+      if (shimDirectories.some((shimDir) => shimDir === '' || normalizedFile === shimDir || normalizedFile.startsWith(`${shimDir}/`))) {
+        continue;
+      }
       // Skip sub-modules directory - these are IDE-specific and handled separately
       if (file.startsWith('sub-modules/')) {
         continue;

package/tools/installer/ui.js

@@ -17,6 +17,7 @@ const {
 const channelResolver = require('./modules/channel-resolver');
 const prompts = require('./prompts');
 const { parseSetEntries } = require('./set-overrides');
+const { inferShimPreference, readInstalledSkillIds } = require('./core/shim-policy');
 
 const manifest = new Manifest();
 
@@ -110,6 +111,33 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
+  async _selectShimPreference({ selectedModules, bmadDir, existing, options, channelOptions }) {
+    const { OfficialModules } = require('./modules/official-modules');
+    const officialModules = new OfficialModules({ channelOptions });
+    const availableShims = await officialModules.discoverShims(selectedModules, { channelOptions });
+
+    // The prompt is capability-driven. Once the last shim leaves the incoming
+    // release this becomes an ordinary empty set, regardless of old state.
+    if (availableShims.length === 0) return;
+
+    const previousManifest = existing ? await manifest.read(bmadDir) : null;
+    const installedSkillIds = existing ? await readInstalledSkillIds(bmadDir) : new Set();
+    const currentValue = inferShimPreference({
+      requested: options.shims,
+      persisted: previousManifest?.installShims,
+      availableShims,
+      installedSkillIds,
+      existing,
+    });
+
+    if (typeof options.shims === 'boolean' || options.yes) return currentValue;
+
+    return prompts.confirm({
+      message: `Install ${availableShims.length} deprecated compatibility shim skill(s)?`,
+      default: currentValue,
+    });
+  }
+
   /**
    * Warn once for each selected module the registry marks deprecated.
    *
@@ -302,7 +330,7 @@ class UI {
           throw new Error('No valid actions available for this installation');
         }
         const hasQuickUpdate = choices.some((c) => c.value === 'quick-update');
-        const needsFullUpdate = !!options.customSource;
+        const needsFullUpdate = !!options.customSource || typeof options.shims === 'boolean';
         actionType = hasQuickUpdate && !needsFullUpdate ? 'quick-update' : (choices.find((c) => c.value === 'update') || choices[0]).value;
         await prompts.log.info(`Non-interactive mode (--yes): defaulting to ${actionType}`);
       } else {
@@ -322,6 +350,7 @@ class UI {
           actionType: 'quick-update',
           directory: confirmedDirectory,
           skipPrompts: options.yes || false,
+          installShims: options.shims,
         };
       }
 
@@ -406,6 +435,13 @@ class UI {
           ...options,
           channelOptions,
         });
+        const installShims = await this._selectShimPreference({
+          selectedModules,
+          bmadDir,
+          existing: true,
+          options,
+          channelOptions,
+        });
 
         // Warn about --pin/--next flags that refer to modules the user didn't
         // select, or that target bundled modules (core/bmm) where channel
@@ -432,6 +468,7 @@ class UI {
           skipPrompts: options.yes || false,
           channelOptions,
           _preserveModules: preservedModules,
+          installShims,
         };
       }
     }
@@ -487,6 +524,13 @@ class UI {
       ...options,
       channelOptions,
     });
+    const installShims = await this._selectShimPreference({
+      selectedModules,
+      bmadDir,
+      existing: false,
+      options,
+      channelOptions,
+    });
 
     // Warn about --pin/--next flags that refer to modules the user didn't
     // select, or that target bundled modules (core/bmm) where channel
@@ -512,6 +556,7 @@ class UI {
       setOverrides,
       skipPrompts: options.yes || false,
       channelOptions,
+      installShims,
     };
   }