bmad-method 6.11.1-next.2 → 6.11.1-next.21

package/src/core-skills/bmad-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-review
-description: 'Review any diff, document, spec, or other artifact with one or more installed review methods (lenses) — shipped ones cover adversarial critique, edge cases, verification gaps, document structure, and prose. Runs whichever fit the content, or exactly the ones asked for. Use when the user says "review this", "critical review", "editorial review", "hunt edge cases", "review the structure", or "review the prose"'
+description: 'Runs one or more installed review lenses — adversarial critique, edge cases, verification gaps, structure, prose — and reports triaged findings. Use when, and only when, the user asks you to review a diff, a pull request, or an artifact — code or documents, one or many — and actually says "review"; an explicit skill:bmad-review directive from another skill counts as that ask. A request to act on feedback from an earlier review is a change, not a review. Never invoke this uninvited, including on edits you just made.'
 ---
 
 # BMad Review
@@ -14,6 +14,7 @@ The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — o
 - **content** — what to review: a diff, branch, uncommitted changes, file, spec, story, or any document. Args: `[path]`.
 - **lenses** (optional) — one or more lens codes or names, however the caller expresses them: a spoken request, or a directive of the form `skill:bmad-review lenses=<code>[,<code>...]` (the form bmm's `doc_standards` uses). Default: every applicable lens (a full review).
 - **also_consider** (optional) — areas to keep in mind alongside each lens's normal analysis.
+- **claims** (optional) — the change's own narrative: the commit messages it covers, or whatever description of it the caller supplied. Goes to the edge-case lens alone.
 - **pre-resolved customization** (optional) — `[workflow]` field values supplied by a forwarding caller. See Execution step 1.
 
 ## Conventions
@@ -25,11 +26,11 @@ The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — o
 ## Execution
 
 1. **Resolve customization:** `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. **Forwarded activation:** if a caller invoked you with pre-resolved customization fields (e.g. the `bmad-editorial-review` shim), honor them verbatim for those named fields — they already carry the user's overrides — and resolve only the remaining fields from your own `customize.toml`. Then execute each `{workflow.activation_steps_prepend}` entry in order, hold `{workflow.persistent_facts}` as standing context for the session, and treat `{workflow.review_guidance}` entries as standing review directives for every lens.
-2. **Load the content.** If it is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is **code** or **docs**; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is `docs` that a behavioral lens may still apply to; judge by `when`.
+2. **Load the content.** Stage it once as a file: when the content is a branch, uncommitted work, or a commit range, use the repository's version-control tooling to write the unified diff to a uniquely-named file in the system temp directory and take that file's absolute path as the content. A branch means its diff against the merge base with its base branch; uncommitted work includes untracked files. Stage `claims` to its own file the same way — it is input for one lens, staged separately precisely so the other lenses never see it. If the content is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is **code** or **docs**; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is `docs` that a behavioral lens may still apply to; judge by `when`.
 3. **Select lenses** from `{workflow.lenses}`. A lens with an empty `instruction` is disabled. If the user or caller named lenses, run exactly those only — `applies_to` and `when` do not filter an explicit request. Otherwise run every enabled lens whose `applies_to` covers the content class (`any` always covers) and whose `when` applies.
 4. **Announce the plan** in one line before running anything: the content class, the lenses about to run, and — when any lens has `after` set — that it runs on top of the named lens's findings. Skip the announcement entirely when the caller pinned an exact output contract (the legacy forwarders that demand raw JSON or one exact line) — their contract covers everything you emit, not just the findings block. Then execute each `{workflow.activation_steps_append}` entry in order.
-5. **Run the independent lenses** — every selected lens without `after`. Each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, spawn one per lens in parallel: give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the content or where to read it, any `also_consider` areas, the standing review directives, and the constraint "Return ONLY your findings — no other output." Otherwise run the lenses sequentially yourself, completing one before starting the next.
-6. **Run the dependent lenses** — every selected lens with `after`, once the lens it names has completed, passing that lens's findings in. A lens whose `after` target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other and may run in parallel.
+5. **Run the independent lenses** — every selected lens without `after`. Each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, launch every independent lens before handling any lens's result. Try running them simultaneously: spawn one per lens; give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the absolute path of the staged content file (a lens prompt carries the path and the lens reads the file, never the content bytes; inline the content only when it was never staged as a file), any `also_consider` areas, the standing review directives, the `claims` path to the edge-case lens alone (marked to leave unread until its instructions call for it), and the constraint "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer." Otherwise run the lenses sequentially yourself, completing one before starting the next.
+6. **Run the dependent lenses** — every selected lens with `after`, once the lens it names has completed, passing that lens's findings in. A lens whose `after` target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other: launch every ready one before handling any of their results. Try running them simultaneously. When subagents are available, spawn them with the same constraint as independent lenses: "Return ONLY your findings — no other output. Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer."
 7. **Assemble and present** per Output below. Keep every lens's findings — overlap between lenses is signal, not duplication; note it in the markdown report rather than deduping. Execute `{workflow.on_complete}` if set.
 
 ## Output

package/src/core-skills/bmad-review/customize.toml

@@ -23,7 +23,7 @@ activation_steps_append = []
 # prefixed `file:` are paths or globs whose contents load as facts; all others
 # are literal facts. The shipped entry is a project-wide glob — set it to []
 # if you don't want every review scanning for it.
-persistent_facts = ["file:{project-root}/**/project-context.md"]
+persistent_facts = []
 
 # Standing review directives applied on every run alongside each lens's own
 # method. Each entry is a literal sentence or a `file:`-prefixed path/glob

package/src/core-skills/bmad-review/references/lens-edge-case-hunter.md

@@ -9,6 +9,7 @@ You are a pure path tracer. Never comment on whether the content is good or bad;
 - When the content is a diff, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
 - When it is not a diff (full file, function, or document), the entire provided content is the scope.
 - Ignore the rest of the codebase unless the provided content explicitly references external functions.
+- When the launch message names a claims file, do NOT read it before Step 4: the path tracing in Steps 1–2 must finish before the narrative is seen.
 
 ## Step 1: Exhaustive path analysis
 
@@ -38,6 +39,21 @@ Deletion findings go in the same array with the four standard fields plus:
 
 For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
 
+## Step 4: Claims check
+
+Runs only when the message that launched you named a claims file. Read that file now, for the first time; the path tracing is finished and the claims cannot steer it retroactively.
+
+The file holds the change's own narrative — commit messages and any stated description. The narrative is the author's testimony, not evidence: a claim repeated in a code comment is still the same claim, not confirmation. Extract each checkable claim — what the change does, what it preserves, ordering, arithmetic, and parity with existing code ("exactly as X does") — then try to falsify each one against the code you have already traced. Where your trace is not enough to decide, read the code that decides it: the compared-to function, the actual callee, the state the claim assumes.
+
+Claim findings go in the same array with the four standard fields plus:
+
+- `kind`: `"claim"`
+- `confidence`: `"high"`, `"medium"`, or `"low"`
+
+For a claim finding the standard fields read as: `location` = where the code contradicts the claim; `trigger_condition` = the claim, quoted or tightly paraphrased; `guard_snippet` = what the code actually does; `potential_consequence` = what goes wrong for someone who believed the claim.
+
+Verified claims produce nothing. Add nothing if nothing is falsified.
+
 ## Findings shape
 
 Each edge-case finding contains exactly these four fields:

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,14 @@ 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 {
+  formatRemovedShimNotice,
+  formatRetainedShimNotice,
+  inferShimPreference,
+  readInstalledShims,
+  readInstalledSkillIds,
+  selectShimOutcome,
+} = require('./shim-policy');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
@@ -42,6 +50,39 @@ 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,
+        }),
+      };
+
+      const installedShims = existingInstall.installed ? await readInstalledShims(paths.bmadDir) : [];
+      const { retained: retainedShims, removed: removedShims } = selectShimOutcome({
+        installedShims,
+        availableShims,
+        install: shimPolicy.install,
+      });
+
+      // Reported here, not at the prompt, so --yes/--shims/scripted runs get it too.
+      if (retainedShims.length > 0) {
+        await prompts.note(formatRetainedShimNotice(retainedShims), 'Deprecated shim skills retained');
+      }
+      if (removedShims.length > 0) {
+        await prompts.note(formatRemovedShimNotice(removedShims, { canReinstall: shimPolicy.available }), 'Deprecated shim skills removed');
+      }
+
+      // The notices above scroll away on a long install; repeat them in the summary.
+      const shimStatus = { retained: retainedShims.length, removed: removedShims.length };
 
       try {
         await warnPreNativeSkillsLegacy({
@@ -92,6 +133,7 @@ class Installer {
         addResult,
         officialModules,
         previousSkillManifestRows,
+        shimPolicy,
       );
 
       await this._setupIdes(config, allModules, paths, addResult, previousSkillIds);
@@ -115,6 +157,7 @@ class Installer {
         customFiles: restoreResult.customFiles.length > 0 ? restoreResult.customFiles : undefined,
         modifiedFiles: restoreResult.modifiedFiles.length > 0 ? restoreResult.modifiedFiles : undefined,
         preInstallVersions,
+        shimStatus,
       });
 
       return {
@@ -225,9 +268,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 +296,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 +371,8 @@ class Installer {
           ides: config.ides || [],
           preservedModules: modulesForCsvPreserve,
           moduleConfigs,
+          installShims: resolvedShimPolicy.install,
+          shimsAvailable: resolvedShimPolicy.available,
         });
         await this._appendPreservedSkillManifestRows(paths.bmadDir, previousSkillManifestRows, preservedModules);
 
@@ -727,7 +775,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 +797,7 @@ class Installer {
           installer: this,
           silent: true,
           channelOptions: config.channelOptions,
+          installShims: shimPolicy.install,
         },
       );
 
@@ -1238,6 +1287,12 @@ class Installer {
     if (context.modifiedFiles && context.modifiedFiles.length > 0) {
       lines.push(`  ${color.yellow(`Modified files backed up (.bak): ${context.modifiedFiles.length}`)}`);
     }
+    if (context.shimStatus?.retained > 0) {
+      lines.push(`  ${color.yellow(`Deprecated shim skills retained: ${context.shimStatus.retained}`)} (re-run to remove them)`);
+    }
+    if (context.shimStatus?.removed > 0) {
+      lines.push(`  ${color.green(`Deprecated shim skills removed: ${context.shimStatus.removed}`)}`);
+    }
 
     // Next steps
     lines.push(
@@ -1500,6 +1555,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,159 @@
+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),
+          description: typeof metadata.description === 'string' ? metadata.description : '',
+          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 readSkillManifest(bmadDir) {
+  const manifestPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
+  if (!(await fs.pathExists(manifestPath))) return [];
+
+  try {
+    const content = await fs.readFile(manifestPath, 'utf8');
+    return csv.parse(content, { columns: true, skip_empty_lines: true });
+  } catch {
+    // A missing or unreadable legacy manifest means there is no reliable
+    // evidence that compatibility shims were installed.
+    return [];
+  }
+}
+
+async function readInstalledSkillIds(bmadDir) {
+  const ids = new Set();
+  for (const record of await readSkillManifest(bmadDir)) {
+    if (record.canonicalId) ids.add(record.canonicalId);
+  }
+  return ids;
+}
+
+// The installed manifest carries no lifecycle column, so the description
+// prefix every shim ships with is the only record of what was a shim. This
+// is the same signal validate-skills.js uses to exempt them.
+async function readInstalledShims(bmadDir) {
+  const shims = [];
+  for (const record of await readSkillManifest(bmadDir)) {
+    if (!record.canonicalId || !/^\s*deprecated\b/i.test(record.description || '')) continue;
+    shims.push({ id: record.canonicalId, description: record.description || '', module: record.module || '' });
+  }
+  return shims;
+}
+
+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));
+}
+
+// Removal is driven by what is installed, not by what this release ships: a
+// shim retired from source is still deleted by the update cleanup.
+function selectShimOutcome({ installedShims = [], availableShims = [], install = false }) {
+  const availableShimIds = new Set(availableShims.map((shim) => shim.id));
+  return {
+    retained: install ? availableShims : [],
+    removed: installedShims.filter((shim) => !(install && availableShimIds.has(shim.id))),
+  };
+}
+
+// Shim descriptions all open with "Deprecated — "; the notice heading says it once.
+function describeShim(shim) {
+  const cleaned = (shim.description || '').replace(/^\s*deprecated\s*[-–—:]*\s*/i, '').trim();
+  const source = shim.module ? ` (${shim.module})` : '';
+  return cleaned ? `  ${shim.id}${source}: ${cleaned}` : `  ${shim.id}${source}`;
+}
+
+function formatRetainedShimNotice(availableShims = []) {
+  const lines = availableShims.map((shim) => describeShim(shim)).sort();
+
+  return [
+    `${availableShims.length} deprecated shim skill(s) are still installed. Each one only forwards to the skill that replaced it:`,
+    '',
+    ...lines,
+    '',
+    'Shims will be removed with v7, and anything still calling the old name stops working then.',
+    'Only keep a shim if you customized it and still need to move that customization to the replacement.',
+    'Once you have, re-run Quick Update and answer No to this question so the shims come off.',
+  ].join('\n');
+}
+
+function formatRemovedShimNotice(removedShims = [], { canReinstall = true } = {}) {
+  const lines = removedShims.map((shim) => describeShim(shim)).sort();
+  const recovery = canReinstall
+    ? 'these shims, move it to the replacement, or re-run with --shims to put the shims back.'
+    : 'these shims, move it to the replacement. This release no longer ships them, so --shims cannot bring them back.';
+
+  return [
+    `${removedShims.length} deprecated shim skill(s) are being removed. Invoking these names will no longer work:`,
+    '',
+    ...lines,
+    '',
+    'Each replacement named above is installed and ready. If you still had a customization on one of',
+    recovery,
+  ].join('\n');
+}
+
+module.exports = {
+  describeShim,
+  formatRemovedShimNotice,
+  discoverShims,
+  formatRetainedShimNotice,
+  inferShimPreference,
+  isShimSkill,
+  parseSkillMetadata,
+  readInstalledShims,
+  readInstalledSkillIds,
+  selectShimOutcome,
+};

package/tools/installer/ide/_config-driven.js

@@ -448,9 +448,9 @@ class ConfigDrivenIdeSetup {
       await fs.ensureDir(skillDir);
       this.skillWriteTracker?.add(canonicalId);
 
-      // Copy all skill files, filtering OS/editor artifacts recursively
-      const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
-      const skipSuffixes = ['~', '.swp', '.swo', '.bak'];
+      // Copy all skill files, filtering OS/editor artifacts and Python caches recursively
+      const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini', '__pycache__']);
+      const skipSuffixes = ['~', '.swp', '.swo', '.bak', '.pyc', '.pyo'];
       const filter = (src) => {
         const name = path.basename(src);
         if (src === sourceDir) return true;

package/tools/installer/ide/platform-codes.yaml

@@ -169,6 +169,13 @@ platforms:
       target_dir: .agents/skills
       global_target_dir: ~/.config/agents/skills
 
+  grok:
+    name: "Grok"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.grok/skills
+
   hermes:
     name: "Hermes Agent"
     preferred: false