bmad-method 6.11.1-next.14 → 6.11.1-next.16

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.11.1-next.14",
+  "version": "6.11.1-next.16",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/ship/bmad-build/customize.toml

@@ -105,7 +105,7 @@ If you have zero findings, re-check and keep thinking; do not stop with an empty
 CONTENT:
 {diff_output}
 
-Do not invoke any skill. Return only the review result.
+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.
 
 """
 
@@ -121,7 +121,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -137,7 +137,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -159,6 +159,6 @@ If you have zero findings, re-check and keep thinking; do not stop with an empty
 CONTENT:
 The changed files in the current worktree. Inspect them directly before reviewing.
 
-Do not invoke any skill. Return only the review result.
+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.
 
 """

package/src/bmm-skills/ship/bmad-build-auto/customize.toml

@@ -67,7 +67,7 @@ If you have zero findings, re-check and keep thinking; do not stop with an empty
 CONTENT:
 {diff_output}
 
-Do not invoke any skill. Return only the review result.
+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.
 
 """
 
@@ -83,7 +83,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -99,7 +99,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -118,4 +118,7 @@ Here is the diff:
 {diff_output}
 
 Your task is strictly descriptive — do not prescribe additional work. Report: (1) the defensible readings of the intent, enumerated; (2) which reading this diff implements; (3) where the readings and the diff diverge — specifically, which surface the intent's expectations live at versus which surface the diff's changes and its tests exercise.
+
+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.
+
 """

package/src/bmm-skills/ship/bmad-code-review/customize.toml

@@ -62,7 +62,7 @@ If you have zero findings, re-check and keep thinking; do not stop with an empty
 CONTENT:
 {diff_output}
 
-Do not invoke any skill. Return only the review result.
+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.
 
 """
 
@@ -78,7 +78,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -94,7 +94,7 @@ Review content:
 
 {diff_output}
 
-Do not invoke any skill. If the instruction file is unreadable, report that exact failure and stop. Return only the review result.
+Do not invoke any skill, and do not spawn subagents of your own — you are the reviewer. If the instruction file is unreadable, report that exact failure and stop. Return your findings as text in your final message; do not route them through any findings-reporting tool the host may offer.
 
 """
 
@@ -110,4 +110,7 @@ You are an Acceptance Auditor. Review the provided diff against `{spec_file}` an
 Diff:
 
 {diff_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.
+
 """

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

@@ -28,8 +28,8 @@ The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — o
 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`.
 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, 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. 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 and may run in parallel. 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/tools/installer/core/installer.js

@@ -13,7 +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 { inferShimPreference, readInstalledSkillIds } = require('./shim-policy');
+const {
+  formatRemovedShimNotice,
+  formatRetainedShimNotice,
+  inferShimPreference,
+  readInstalledShims,
+  readInstalledSkillIds,
+  selectShimOutcome,
+} = require('./shim-policy');
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
@@ -59,6 +66,24 @@ class Installer {
         }),
       };
 
+      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({
           projectRoot: paths.projectRoot,
@@ -132,6 +157,7 @@ class Installer {
         customFiles: restoreResult.customFiles.length > 0 ? restoreResult.customFiles : undefined,
         modifiedFiles: restoreResult.modifiedFiles.length > 0 ? restoreResult.modifiedFiles : undefined,
         preInstallVersions,
+        shimStatus,
       });
 
       return {
@@ -1261,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(

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

@@ -37,6 +37,7 @@ async function discoverShims(modulePath) {
       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),
         });
@@ -54,25 +55,40 @@ async function discoverShims(modulePath) {
   return shims;
 }
 
-async function readInstalledSkillIds(bmadDir) {
-  const ids = new Set();
+async function readSkillManifest(bmadDir) {
   const manifestPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
-  if (!(await fs.pathExists(manifestPath))) return ids;
+  if (!(await fs.pathExists(manifestPath))) return [];
 
   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);
-    }
+    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;
@@ -82,10 +98,62 @@ function inferShimPreference({ requested, persisted, availableShims = [], instal
   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/prompts.js

@@ -316,7 +316,9 @@ async function autocompleteMultiselect(options) {
 
       switch (this.state) {
         case 'submit': {
-          return `${title}${color.gray(clack.S_BAR)}  ${color.dim(`${this.selectedValues.length} items selected`)}`;
+          const count = this.selectedValues.length;
+          const emptyHint = count === 0 && options.emptyLabel ? ` (${options.emptyLabel})` : '';
+          return `${title}${color.gray(clack.S_BAR)}  ${color.dim(`${count} item${count === 1 ? '' : 's'} selected${emptyHint}`)}`;
         }
 
         case 'cancel': {
@@ -331,7 +333,18 @@ async function autocompleteMultiselect(options) {
 
           const errorLine = this.state === 'error' ? [`${bar}  ${color.yellow(this.error)}`] : [];
 
-          const headerLines = [...`${title}${bar}`.split('\n'), `${bar}  ${searchDisplay}${matchCount}`, ...noMatchesLine, ...errorLine];
+          const emptyLine =
+            this.selectedValues.length === 0 && options.emptyLabel
+              ? [`${bar}  ${color.dim(`Nothing selected: installs ${options.emptyLabel}`)}`]
+              : [];
+
+          const headerLines = [
+            ...`${title}${bar}`.split('\n'),
+            `${bar}  ${searchDisplay}${matchCount}`,
+            ...noMatchesLine,
+            ...errorLine,
+            ...emptyLine,
+          ];
 
           const footerLines = [`${bar}  ${color.dim(hints.join(' • '))}`, `${barEnd}`];
 

package/tools/installer/ui.js

@@ -111,7 +111,7 @@ async function getModuleVersion(moduleCode, { repoUrl = null, registryDefault =
  * UI utilities for the installer
  */
 class UI {
-  async _selectShimPreference({ selectedModules, bmadDir, existing, options, channelOptions }) {
+  async _selectShimPreference({ selectedModules, bmadDir, existing, options, channelOptions, quickUpdate = false }) {
     const { OfficialModules } = require('./modules/official-modules');
     const officialModules = new OfficialModules({ channelOptions });
     const availableShims = await officialModules.discoverShims(selectedModules, { channelOptions });
@@ -132,10 +132,20 @@ class UI {
 
     if (typeof options.shims === 'boolean' || options.yes) return currentValue;
 
-    return prompts.confirm({
-      message: `Install ${availableShims.length} deprecated compatibility shim skill(s)?`,
-      default: currentValue,
-    });
+    // clack's confirm never resolves without a TTY: a scripted run would exit mid-install.
+    if (!process.stdin.isTTY) return currentValue;
+
+    // Nothing to give up, so nothing to ask on every single update.
+    if (quickUpdate && !currentValue) return currentValue;
+
+    const verb = currentValue ? 'Keep' : 'Install';
+    const message =
+      `${verb} ${availableShims.length} deprecated compatibility shim skill(s)? Recommended: No. ` +
+      `If you say yes, the deprecated skills will exist as a skill that forwards to its replacement skill. ` +
+      `Shims will be removed with v7. You should only retain if you customized a shimmed skill and need to ` +
+      `still transition it to the replacement.`;
+
+    return prompts.confirm({ message, default: currentValue });
   }
 
   /**
@@ -346,11 +356,21 @@ class UI {
         // Quick update never shows the module picker, so this is the only
         // place an existing install of a deprecated module hears about it.
         await this._warnDeprecatedModules(existingInstall.moduleIds || []);
+
+        const installShims = await this._selectShimPreference({
+          selectedModules: existingInstall.moduleIds || [],
+          bmadDir,
+          existing: true,
+          options,
+          channelOptions,
+          quickUpdate: true,
+        });
+
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
           skipPrompts: options.yes || false,
-          installShims: options.shims,
+          installShims: installShims === undefined ? options.shims : installShims,
         };
       }
 
@@ -1116,9 +1136,9 @@ class UI {
       message: 'Select official modules to install:',
       options: allOptions,
       initialValues: initialValues.length > 0 ? initialValues : undefined,
-      // Not required: core is installed either way, so an empty selection is a
-      // legitimate "core only" install rather than a mistake to block on.
+      // Core installs either way and is not a row here, so empty is a valid core-only install.
       required: false,
+      emptyLabel: 'core only',
       maxItems: allOptions.length,
     });