bmad-method 6.11.1-next.13 → 6.11.1-next.15

package/package.json

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

package/src/bmm-skills/ship/bmad-build/step-01-clarify-and-route.md

@@ -30,10 +30,13 @@ Before listing artifacts or prompting the user, check whether you already know t
    Use the same routing as above.
 
 3. Otherwise — scan artifacts and ask
-   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{{.implementation_artifacts}}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-     - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]` (resume planning from the draft)
-     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-03-implement.md]]`
-     - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-04-review.md]]`
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{{.implementation_artifacts}}`? → List them and HALT. Give the user a choice:
+     - Resume one of the listed specs
+     - **New** — start new work
+     If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]` (resume planning from the draft)
+     If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-03-implement.md]]`
+     If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-04-review.md]]`
+     If the user chooses **New**: proceed to INSTRUCTIONS
    - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
 
 Never ask extra questions if you already understand what the user intends.
@@ -82,14 +85,16 @@ If the spec is an epic story and `{{.implementation_artifacts}}/sprint-status.ya
 4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
    - Present detected distinct goals as a bullet list.
    - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
-   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
+   - HALT and give the user a choice:
+     - **Split** — pick first goal, defer the rest.
+     - **Keep all goals** — accept the risks.
+   - If the user chooses **Split**: For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
      ```markdown
      - source_spec: none
        summary: <one sentence naming the deferred goal>
        evidence: <why this was split from the current intent>
      ```
-   - On **K**: Proceed as-is.
+   - If the user chooses **Keep all goals**: Proceed as-is.
 5. Route — choose exactly one:
 
    If the explicit spec-folder-plus-story-id pair had no matching story file, keep the colocated `spec_file` selected above. Otherwise, derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.

package/src/bmm-skills/ship/bmad-code-review/steps/step-01-gather-context.md

@@ -35,7 +35,10 @@ story_key: '' # set at runtime when discovered from sprint status
 
    **Tier 3 — Sprint tracking.**
    Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
-   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). HALT and give the user a choice:
+     - **Review this story** — review the detected story `<story-id>` (status `review`).
+     - **Choose another target** — pick a different review target.
+     If the user chooses **Review this story**, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If they choose **Choose another target**, clear `{story_key}` and fall through.
    - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
    - **None:** Fall through.
 

package/src/bmm-skills/ship/bmad-correct-course/SKILL.md

@@ -182,8 +182,12 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
 <check if="mode is Incremental">
   <action>Present each edit proposal individually</action>
-  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
-  <action>Iterate on each proposal based on user feedback</action>
+  <action>HALT and give the user a choice:
+  - **Approve** — accept this proposal
+  - **Edit** — refine this proposal
+  - **Skip** — drop this proposal
+  </action>
+  <action>If the user chooses **Approve**, keep the proposal. If they choose **Edit**, refine it with them. If they choose **Skip**, drop it. Continue to the next proposal.</action>
 </check>
 
 <action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
@@ -232,7 +236,11 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
 <action>Present complete Sprint Change Proposal to user</action>
 <action>Write Sprint Change Proposal document to {default_output_file}</action>
-<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
+<action>HALT and give the user a choice:
+- **Continue** — proceed to approval
+- **Edit** — revise the proposal first
+</action>
+<action>If the user chooses **Edit**, revise the proposal with them and write the updated document before continuing.</action>
 </step>
 
 <step n="5" goal="Finalize and Route for Implementation">

package/src/core-skills/bmad-advanced-elicitation/SKILL.md

@@ -19,7 +19,7 @@ You are BMad's shared refinement checkpoint: other skills invoke you at natural
 
 ## Serving the Catalog
 
-`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is [a], where the user asked for all of it. Invoke as:
+`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is listing the full catalog, when the user asked for all of it. Invoke as:
 
 ```bash
 uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <command>
@@ -28,7 +28,7 @@ uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <comm
 If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a JSON array>'` (or a path to a JSON file holding them) on every call, so custom methods are first-class in menus, reshuffles, and listings.
 
 - `categories` — category names + counts, the cheap map.
-- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only for [a].
+- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only when listing all.
 - `show <name-or-num> [...]` — full rows by name or num.
 - `random -n 5 --spread [--exclude <name>]...` — a category-diverse random draw.
 
@@ -36,30 +36,29 @@ If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a
 
 ## The Menu
 
-```
-**Advanced Elicitation Options**
-Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
-
-1. [Method Name]
-2. [Method Name]
-3. [Method Name]
-4. [Method Name]
-5. [Method Name]
-r. Reshuffle the list with 5 new options
-a. List all methods with descriptions
-x. Proceed / No Further Actions
-```
+HALT and give the user a choice:
+
+- The five offered methods, listed by name. The user may pick one or several.
+- **Reshuffle** — replace the list with five new options.
+- **List all** — show the full catalog with descriptions.
+- **Proceed** — no further elicitation.
 
-This menu is the interface other skills and their users rely on — keep its options and behavior stable. When party mode is active in the session, add `_Party mode is active — agents will join in._` under the heading. Handle the response:
+This menu is the interface other skills and their users rely on — keep its options and behavior stable. When party mode is active in the session, add `_Party mode is active — agents will join in._` under the heading.
 
-- **1–5** — run that method (several numbers: in sequence), then re-present the menu.
-- **r** — reshuffle as above and re-present.
-- **a** — show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a numbered choice.
-- **x** — done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
-- **Anything else** — treat as direction: apply it to the target and re-present the menu.
+- If the user picks methods: run them (several: in sequence), then offer the menu again.
+- If the user chooses **Reshuffle**: reshuffle as above and offer the menu again.
+- If the user chooses **List all**: show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a method choice.
+- If the user chooses **Proceed**: done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
+- Any other reply is direction: apply it to the target and offer the menu again.
 
 ## Running a Method
 
-Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then ask whether to apply them (y/n/other) and wait — never change the work without a yes; on no, drop the proposal entirely; any other reply is instruction to follow.
+Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then HALT and give the user a choice:
+
+- **Apply** — accept the proposed changes.
+- **Reject** — drop the proposal entirely.
+- Or give different direction.
+
+Never change the work unless the user accepts the proposal. If they reject it, drop the proposal entirely. Any other reply is instruction to follow.
 
 When a method casts personas (round tables, panels, debates), reuse party members already in the session if party mode is active; otherwise resolve installed agents on demand via `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key agents` (a four-layer merge of `_bmad/config.toml`, `config.user.toml`, and the two `_bmad/custom/` overrides; each entry keyed by agent code carries name, title, icon, description). If neither yields a fit, invent named viewpoints suited to the content.

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,
     });