feat(installer): make compatibility shims optional (#2728)

Author: alexeyv

docs/how-to/install-bmad.md

@@ -28,16 +28,19 @@ Use `npx bmad-method install` to set up BMad in your project. One command handle
 npx bmad-method install
 ```
 
-The interactive flow asks you five things:
+The interactive flow asks you six things when the selected modules still ship deprecated compatibility shims:
 
 1. Installation directory (defaults to the current working directory)
 2. Which modules to install (checkboxes for core, bmm, bmb, cis, gds, tea)
 3. **"Ready to install (all stable)?"** — Yes accepts the latest released tag for every external module
 4. Which AI tools/IDEs to integrate with (claude-code, cursor, and others)
 5. Per-module config (name, language, output folder)
+6. Whether to install deprecated compatibility shim skills (defaults to No on a new installation)
 
 Accept the defaults and you land on the latest stable release of every module, configured for your chosen tool.
 
+Existing installations keep their current shim choice during Quick Update. Modify Install lets you change it explicitly. Once a release no longer contains any shims, the installer stops asking and removes previously installed shims through its normal update cleanup.
+
 :::tip[Just want the newest prerelease?]
 
 ```bash
@@ -126,6 +129,8 @@ Under `--yes`, patch and minor upgrades apply automatically. Majors stay frozen
 | `--list-tools`                                                                             | Print all supported tool/IDE IDs (with target directories) and exit.                                                              |
 | `--action <type>`                                                                          | `install`, `update`, or `quick-update`. Defaults based on existing install state.                                                 |
 | `--custom-source <urls>`                                                                   | Install custom modules from Git URLs or local paths                                                                               |
+| `--shims`                                                                                  | Install deprecated compatibility shim skills when selected modules still provide them                                             |
+| `--no-shims`                                                                               | Explicitly omit deprecated compatibility shim skills; on an existing install this removes them during update                      |
 | `--channel <stable\|next>`                                                                 | Apply to all externals (aliased as `--all-stable` / `--all-next`)                                                                 |
 | `--all-stable`                                                                             | Alias for `--channel=stable`                                                                                                      |
 | `--all-next`                                                                               | Alias for `--channel=next`                                                                                                        |

package.json

@@ -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",

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

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)

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)

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

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

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

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

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)