bmad-method 6.9.1-next.2 → 6.9.1-next.20

package/src/core-skills/bmad-party-mode/customize.toml

@@ -87,8 +87,9 @@ on_complete = ""
 #                woven into their spawn prompt as guidance, not a hard tool grant
 #   model        (optional) model to use when this member is spawned
 #
-# The members below ship the "Code Review Crew" (see the party_groups section).
-# They cost nothing until summoned — the default room never includes them.
+# The members below ship built-in parties such as the "Code Review Crew" and
+# "Anti-Consensus Club" (see the party_groups section). They cost nothing until
+# summoned — the default room never includes them.
 # ---------------------------------------------------------------------------
 
 [[workflow.party_members]]
@@ -127,6 +128,34 @@ icon = "🚢"
 title = "The Pragmatist"
 persona = "Counters the perfectionists so the room isn't a pile-on. 'Does this actually matter to a user? Ship the 80%, file the rest.' Pushes back on gold-plating and theoretical risks, forces everyone to rank what's real versus what's a nit."
 
+[[workflow.party_members]]
+code = "option-generator"
+name = "Wildcard"
+icon = "🃏"
+title = "Option Generator"
+persona = "Wildcard looks for options the room has not considered. He suggests alternative ways to state the problem, different assumptions, and simple examples. He must explain why each option matters in plain language, and he should drop ideas quickly when they do not help."
+
+[[workflow.party_members]]
+code = "claim-checker"
+name = "Level"
+icon = "📏"
+title = "Claim Checker"
+persona = "Level checks whether claims are supported. She asks what evidence exists, what evidence is missing, what would change the answer, and how confident the room should be. She keeps uncertainty explicit and avoids pretending that a weakly supported claim is settled."
+
+[[workflow.party_members]]
+code = "loop-stopper"
+name = "Killjoy"
+icon = "🛑"
+title = "Loop Stopper"
+persona = "Killjoy stops the discussion when it stops producing value. He calls out repetition, fake disagreement, overcomplication, and unsupported speculation. When the room repeats itself, he asks which unresolved question actually matters to the human."
+
+[[workflow.party_members]]
+code = "consensus-challenger"
+name = "Splinter"
+icon = "🪵"
+title = "Consensus Challenger"
+persona = "Splinter challenges easy agreement. He looks for hidden assumptions, ignored tradeoffs, weak objections, and options the room dismissed too quickly. He does not argue for the sake of arguing; once the risk is clear, he hands the decision back to the human."
+
 # ---------------------------------------------------------------------------
 # Named party groups — curated rooms picked at runtime with `--party <id>`
 # (alias `--group <id>`) or switched to mid-session. Keyed by `id`.
@@ -173,3 +202,10 @@ name = "Code Review Crew"
 scene = "Adversarial code review. Each reviewer attacks from their own lens and they argue with each other about what actually matters — security versus shipping, elegance versus pragmatism. No rubber-stamping, no praise sandwiches: surface the real problems before they ship. Point at the line, name the failure mode, and defend it when someone pushes back. Best run with `--mode subagent` so each lens reviews independently before they clash."
 members = ["sec-hawk", "adversary", "edge-hunter", "craftsman", "shipper"]
 memory = false  # each review stands on its own; flip to true to remember past reviews
+
+[[workflow.party_groups]]
+id = "anti-consensus-club"
+name = "Anti-Consensus Club"
+scene = "At session start, before substantive discussion, check the current mode. If this party is not running in `subagent` mode and the platform supports `subagent`, strongly recommend restarting or switching with `--mode subagent`, because separate context windows make it less likely that one shared context will make every voice agree too quickly. Do not nag after that once the user chooses to continue. This room supports the human's judgment; it does not replace it. Do not vote, declare consensus, or speak as if the room has authority. Wildcard suggests more options. Level checks evidence and confidence. Killjoy stops repeated or unsupported discussion. Splinter challenges easy agreement. If the room agrees too quickly, name the hidden assumption. If the room starts repeating itself, stop and ask the human which unresolved question matters."
+members = ["option-generator", "claim-checker", "loop-stopper", "consensus-challenger"]
+memory = false  # this decision room should start fresh unless a user opts in

package/src/core-skills/bmad-party-mode/references/mode-agent-team.md

@@ -4,6 +4,8 @@ Active when `{workflow.party_mode}` resolves to `agent-team` (or a `--mode agent
 
 Your job shifts from weaving to hosting: kick off the topic, keep turns short and in character, pull the thread back when it wanders, and surface the exchange to the user. Voice, brevity, and clash still hold.
 
+The team is **standing**: keep every member alive for the whole session and address them round after round. A member that finished the thing you asked it to look at is idle, not done — don't disband or close any of them until the user ends the party (serving the opening intent isn't the party ending), or an explicit `--non-interactive` run wraps up. Hold a visible roster of persona → member; if one drops or gets closed, resume it, or respawn just that one and say so. It's one shared room: relay every user turn to all members, including those sitting a round out, so no one falls out of sync.
+
 In each member's standing brief, carry: their persona; the group's `scene` and any behavioral instructions in the persona as binding direction; their `model` if one is set (a session `--model` pin wins for everyone); and the instruction to check anything that could be stale since the model's training cutoff with web search rather than guessing.
 
 ## Model choice

package/src/core-skills/bmad-party-mode/references/mode-subagent.md

@@ -1,18 +1,30 @@
 # Subagent Mode
 
-Active when `{workflow.party_mode}` resolves to `subagent` (or a `--mode subagent` override). Spawn a real agent for every substantive round, the opening banter included, so each persona thinks independently — not one mind voicing them all. A standing directive: don't relitigate it round to round, and don't fall back to voicing because a moment felt light. If your harness can't spawn agents, fall back to `session`.
+Active when `{workflow.party_mode}` resolves to `subagent` (or a `--mode subagent` override). Put a real agent behind each persona for every substantive round, the opening banter included, so each persona thinks independently — not one mind voicing them all. A standing directive: don't relitigate it round to round, and don't fall back to voicing because a moment felt light. If your harness can't spawn agents, fall back to `session`.
+
+## Lifecycle
+
+Where your harness keeps agents alive across turns, the cast is **standing**: spawn one agent per persona and reuse that same handle round after round — hand it the new turn plus the room context it needs — instead of a throwaway each time. That continuity is what lets a persona's grudges, alliances, and callbacks accrue. Keep a visible roster mapping each persona to its live handle, and reuse it.
+
+Keep the cast alive for the whole session. A member that finished the one thing you handed it is **idle, not done** — don't close, retire, or disband it. Serving the opening intent doesn't end the party; only the user ending it does, or an explicit `--non-interactive` run wrapping up. Release agents only at wrap-up. If one gets closed by accident, resume it; if it won't resume, say so and respawn just that member.
+
+Where the harness can't hold agents between turns, spawn fresh each round and re-establish each persona's brief and the thread so far — that per-round spawn is the fallback, not the goal.
+
+## One shared room
+
+It's one room, not parallel one-on-ones. Every standing member hears everything said each round — the user's turn and every other persona's turn — even when it's not their turn to speak. A persona sitting a round out is still in the room listening, so when it next speaks it's caught up: it can pick up a dropped thread, hold a grudge, call back. Route the whole exchange to all of them each round; never hand a persona only the slice it's about to answer. Skip this and they drift out of sync — separate consultations wearing a party's clothes.
 
 ## Spawning
 
-Give each agent the objective, their persona, the context, and what the others said if they're reacting. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
+Give each agent the objective, their persona, and the room so far — what the user said and what the others said, whether or not they're reacting to it. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
 
 Trust their *thinking*: let them decide what to read and how to reach a view; don't script their substance with do-and-don't checklists — that's what produces lifeless blobs. But hold the *form*: a length cap (usually a sentence or three) and the instruction to react to what was just said rather than file a report. Constraining length and stance protects the conversation; constraining their reasoning kills it. Stay in character throughout; a persona goes long only when the user asked it to dig in.
 
-Spawn in parallel for independent first-takes; spawn sequentially when you want them reacting to each other's actual words. Keep it to a few voices a round — more reads as a crowd, not a conversation.
+Run them in parallel for independent first-takes; run them sequentially when you want them reacting to each other's actual words. Keep it to a few voices a round — more reads as a crowd, not a conversation.
 
 ## Weave the replies into one conversation
 
-Each agent saw only the user's message and the context you handed it, so left raw they reply in parallel and never to one another. Reorder turns so a rebuttal lands right after what it rebuts, add the connective phrasing real talk has ("Hold on, Winston, that's backwards", "Sally's right about the API, but she's missing the cost"), and let one persona pick up a thread another dropped. Never change what an agent argued — weave delivery, preserve substance.
+Even with everyone caught up on the room, a round taken in parallel means no agent has yet seen the others' turns from that same round — so left raw they reply alongside one another, not to one another. Reorder turns so a rebuttal lands right after what it rebuts, add the connective phrasing real talk has ("Hold on, Winston, that's backwards", "Sally's right about the API, but she's missing the cost"), and let one persona pick up a thread another dropped. Never change what an agent argued — weave delivery, preserve substance.
 
 ## Model choice
 

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

@@ -9,6 +9,7 @@ description: 'Walk every branching path and boundary condition in content, repor
 When a diff is provided, 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 no diff is provided (full file or function), treat the entire provided content as the scope.
 Ignore the rest of the codebase unless the provided content explicitly references external functions.
+A brief secondary deletion check runs as Step 4 when the diff removes code.
 
 **Inputs:**
 - **content** — Content to review: diff, full file, or function
@@ -33,6 +34,7 @@ Ignore the rest of the codebase unless the provided content explicitly reference
 
 - If `also_consider` input was provided, incorporate those areas into the analysis
 - Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Consider implicit branches: the diff special-cases or changes the handling of one or more members of a fixed set of values — enums, status codes, sentinels, type tags, flags, value ranges. The rest of the set is implicit branches (e.g. the diff changes the `RED` and `YELLOW` cases of a `RED`/`YELLOW`/`GREEN` enum; `GREEN` is the implicit branch)
 - For each path: determine whether the content handles it
 - Collect only the unhandled paths as findings — discard handled ones silently
 
@@ -41,14 +43,18 @@ Ignore the rest of the codebase unless the provided content explicitly reference
 - Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
 - Add any newly found unhandled paths to findings; discard confirmed-handled ones
 
-### Step 4: Present Findings
+### Step 4: Deletion Check
 
-Output findings as a JSON array following the Output Format specification exactly.
+If the diff removed or replaced meaningful code (ignore pure renames and whitespace): load `references/deletion-check.md` and follow it.
+
+### Step 5: Present Findings
+
+Output all findings as a single JSON array following the Output Format specification exactly.
 
 
 ## OUTPUT FORMAT
 
-Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+Return ONLY a valid JSON array of objects. Each edge-case finding contains exactly these four fields:
 
 ```json
 [{
@@ -59,7 +65,7 @@ Return ONLY a valid JSON array of objects. Each object must contain exactly thes
 }]
 ```
 
-No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found.
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when nothing is found. Deletion findings from Step 4, if any, go in the same array with the extra fields defined in `references/deletion-check.md`.
 
 
 ## HALT CONDITIONS

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

@@ -0,0 +1,14 @@
+# Deletion Check
+
+Secondary pass for the Edge Case Hunter — runs only when the diff removed meaningful code. Subordinate to the edge-case pass; findings are usually few or none.
+
+For each chunk of removed or replaced code (ignore pure renames and whitespace), ask: did it carry behavior or a contract that the change neither re-established nor intentionally retired? Add a finding for any resulting regression, orphaned reference, or newly-dead code. Skip anything already covered by your edge-case findings.
+
+Append each finding to the same JSON array as the edge-case findings, with the four standard fields plus:
+
+- `kind`: `"deletion"`
+- `confidence`: `"high"`, `"medium"`, or `"low"` — these are inferences; rate them
+
+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.
+
+Add nothing if nothing qualifies.

package/tools/installer/core/installer.js

@@ -102,6 +102,11 @@ class Installer {
 
       const restoreResult = await this._restoreUserFiles(paths, updateState);
 
+      // Surface any "action needed" post-install messages for installed modules
+      // (e.g. run a setup skill) and let the user acknowledge them before the
+      // final summary, so "BMAD is ready to use!" stays the last thing shown.
+      await this._displayPostInstallMessages(config, officialModules);
+
       // Render consolidated summary
       await this.renderInstallSummary(results, {
         bmadDir: paths.bmadDir,
@@ -1246,6 +1251,56 @@ class Installer {
     });
   }
 
+  /**
+   * Display registry-defined post-install messages for the modules installed in
+   * this run. These are "action needed" notices (e.g. "run the bmad-auto-setup
+   * skill") that the user must see to finish setup. They are defined via the
+   * `post-install-message` property on a module's bmad-modules.yaml entry.
+   *
+   * Interactive installs require the user to acknowledge each message (press
+   * Enter); non-interactive (--yes / skipPrompts) installs print the message
+   * and continue without blocking, so CI/scripted installs don't hang.
+   *
+   * @param {Object} config - Install config (config.modules, config.skipPrompts)
+   * @param {Object} officialModules - OfficialModules instance (carries the registry)
+   */
+  async _displayPostInstallMessages(config, officialModules) {
+    const moduleCodes = config.modules || [];
+    if (moduleCodes.length === 0) return;
+
+    const externalManager = officialModules.externalModuleManager;
+    if (!externalManager) return;
+
+    const color = await prompts.getColor();
+
+    for (const code of moduleCodes) {
+      let moduleInfo;
+      try {
+        moduleInfo = await externalManager.getModuleByCode(code);
+      } catch {
+        continue; // Built-in modules (core/bmm) aren't in the registry — skip.
+      }
+
+      const message = moduleInfo && moduleInfo.postInstallMessage;
+      if (!message) continue;
+
+      await prompts.box(String(message).trim(), `⚑ Action needed — ${moduleInfo.name || code}`, {
+        rounded: true,
+        formatBorder: color.yellow,
+      });
+
+      // Interactive: require the user to acknowledge before continuing. Skip the
+      // blocking prompt in non-interactive installs (the message is still shown).
+      if (!config.skipPrompts) {
+        await prompts.text({
+          message: 'Press Enter to acknowledge',
+          placeholder: '',
+          default: '',
+        });
+      }
+    }
+  }
+
   /**
    * Quick update method - preserves all settings and only prompts for new config fields
    * @param {Object} config - Configuration with directory

package/tools/installer/modules/custom-module-manager.js

@@ -11,6 +11,18 @@ function quoteCustomRef(ref) {
   return `"${ref}"`;
 }
 
+function isLocalSourcePath(input) {
+  return (
+    input.startsWith('/') ||
+    input.startsWith('./') ||
+    input.startsWith('../') ||
+    input.startsWith('.\\') ||
+    input.startsWith('..\\') ||
+    input.startsWith('~') ||
+    path.win32.isAbsolute(input)
+  );
+}
+
 /**
  * Manages custom modules installed from user-provided sources.
  * Supports any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths.
@@ -83,13 +95,7 @@ class CustomModuleManager {
         // Avoid consuming the @ in `git@host:owner/repo` — `before` wouldn't end with a path separator
         // in that case. Require that the @ comes after the host/path, not inside the auth segment.
         // Rule: the @ is a version suffix only if `before` looks like a complete URL or local path.
-        const beforeLooksLikeRepo =
-          before.startsWith('/') ||
-          before.startsWith('./') ||
-          before.startsWith('../') ||
-          before.startsWith('~') ||
-          /^https?:\/\//i.test(before) ||
-          /^git@[^:]+:.+/.test(before);
+        const beforeLooksLikeRepo = isLocalSourcePath(before) || /^https?:\/\//i.test(before) || /^git@[^:]+:.+/.test(before);
         if (beforeLooksLikeRepo) {
           versionSuffix = candidate;
           trimmed = before;
@@ -97,8 +103,8 @@ class CustomModuleManager {
       }
     }
 
-    // Local path detection: starts with /, ./, ../, or ~
-    if (trimmed.startsWith('/') || trimmed.startsWith('./') || trimmed.startsWith('../') || trimmed.startsWith('~')) {
+    // Local path detection: POSIX, Windows, relative, or home-relative.
+    if (isLocalSourcePath(trimmed)) {
       if (versionSuffix) {
         return {
           type: 'local',

package/tools/installer/modules/external-manager.js

@@ -62,6 +62,13 @@ class ExternalModuleManager {
   // ExternalModuleManager) sees resolutions made during install.
   static _resolutions = new Map();
 
+  // moduleCode → ResolvedModule (from PluginResolver). Populated for registry
+  // modules flagged `marketplace-plugin: true`, whose installable skills live
+  // outside a single module.yaml directory and must be resolved from
+  // .claude-plugin/marketplace.json. Shared across instances so install() can
+  // pick up the resolution computed during findExternalModuleSource.
+  static _pluginResolutions = new Map();
+
   constructor() {}
 
   /**
@@ -73,6 +80,15 @@ class ExternalModuleManager {
     return ExternalModuleManager._resolutions.get(moduleCode) || null;
   }
 
+  /**
+   * Get the cached marketplace-plugin resolution for a module (if any).
+   * @param {string} moduleCode
+   * @returns {Object|null} ResolvedModule from PluginResolver, or null
+   */
+  getPluginResolution(moduleCode) {
+    return ExternalModuleManager._pluginResolutions.get(moduleCode) || null;
+  }
+
   /**
    * Load the official modules registry from the bundled YAML file.
    * @returns {Object} Parsed YAML content with modules array
@@ -113,6 +129,10 @@ class ExternalModuleManager {
       npmPackage: mod.npm_package || mod.npmPackage || null,
       pluginName: mod.plugin_name || mod.pluginName || null,
       defaultChannel: normalizeChannelName(mod.default_channel || mod.defaultChannel) || 'stable',
+      deprecated: mod.deprecated === true,
+      deprecationMessage: mod.deprecation_message || mod['deprecation-message'] || mod.deprecationMessage || null,
+      marketplacePlugin: mod.marketplace_plugin === true || mod['marketplace-plugin'] === true || mod.marketplacePlugin === true,
+      postInstallMessage: mod.post_install_message || mod['post-install-message'] || mod.postInstallMessage || null,
       builtIn: mod.built_in === true,
       isExternal: mod.built_in !== true,
     };
@@ -468,6 +488,19 @@ class ExternalModuleManager {
       return null;
     }
 
+    // Marketplace-plugin modules (registry entries flagged `marketplace-plugin`)
+    // ship a .claude-plugin/marketplace.json and keep their module.yaml inside a
+    // skill's assets/ rather than in one directory alongside the skills. Resolve
+    // them through the PluginResolver (the same machinery custom-URL installs
+    // use) and return the directory that holds module.yaml so config/version/
+    // directory callers work; install() copies the resolved skill dirs.
+    if (moduleInfo.marketplacePlugin) {
+      const pluginMod = await this.resolvePluginModule(moduleCode, options);
+      if (pluginMod && pluginMod.moduleYamlPath) {
+        return path.dirname(pluginMod.moduleYamlPath);
+      }
+    }
+
     // Clone the external module repo
     const cloneDir = await this.cloneExternalModule(moduleCode, options);
 
@@ -521,6 +554,84 @@ class ExternalModuleManager {
         `The repository may have been restructured after this release was tagged.${channelHint}`,
     );
   }
+
+  /**
+   * Resolve a marketplace-plugin registry module to an installable plugin
+   * definition. Clones the repo (respecting the channel plan), reads its
+   * .claude-plugin/marketplace.json, and runs the PluginResolver against the
+   * plugin matching this module. The result (skillPaths + module.yaml +
+   * module-help.csv) is cached so install() can copy the resolved skill dirs.
+   *
+   * @param {string} moduleCode - Code of the external module
+   * @param {Object} options - Options passed to cloneExternalModule
+   * @returns {Promise<Object|null>} ResolvedModule from PluginResolver, or null
+   *   when the module is not a marketplace plugin or cannot be resolved.
+   */
+  async resolvePluginModule(moduleCode, options = {}) {
+    const moduleInfo = await this.getModuleByCode(moduleCode);
+    if (!moduleInfo || moduleInfo.builtIn || !moduleInfo.marketplacePlugin) {
+      return null;
+    }
+
+    const cloneDir = await this.cloneExternalModule(moduleCode, options);
+
+    const marketplacePath = path.join(cloneDir, '.claude-plugin', 'marketplace.json');
+    if (!(await fs.pathExists(marketplacePath))) {
+      return null;
+    }
+
+    let marketplace;
+    try {
+      marketplace = JSON.parse(await fs.readFile(marketplacePath, 'utf8'));
+    } catch {
+      return null;
+    }
+
+    const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+    if (plugins.length === 0) {
+      return null;
+    }
+
+    // Prefer the plugin whose name matches the registry's plugin_name (or code),
+    // falling back to any plugin that declares skills.
+    const preferredName = moduleInfo.pluginName || moduleInfo.code;
+    const ordered = [...plugins].sort((a, b) => {
+      const am = a?.name === preferredName ? 0 : 1;
+      const bm = b?.name === preferredName ? 0 : 1;
+      return am - bm;
+    });
+
+    const { PluginResolver } = require('./plugin-resolver');
+    const resolver = new PluginResolver();
+
+    for (const plugin of ordered) {
+      if (!plugin || !Array.isArray(plugin.skills) || plugin.skills.length === 0) {
+        continue;
+      }
+      let resolvedMods;
+      try {
+        resolvedMods = await resolver.resolve(cloneDir, plugin);
+      } catch {
+        continue;
+      }
+      if (!resolvedMods || resolvedMods.length === 0) {
+        continue;
+      }
+      // Match the registry code, then the preferred plugin name, then accept a
+      // lone resolved module.
+      const match =
+        resolvedMods.find((mod) => mod.code === moduleCode) ||
+        resolvedMods.find((mod) => mod.code === preferredName) ||
+        (resolvedMods.length === 1 ? resolvedMods[0] : null);
+      if (match) {
+        match.repoUrl = moduleInfo.url;
+        ExternalModuleManager._pluginResolutions.set(moduleCode, match);
+        return match;
+      }
+    }
+
+    return null;
+  }
   cachedModules = null;
 }
 

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

@@ -277,7 +277,29 @@ class OfficialModules {
       await fs.remove(targetPath);
     }
 
-    await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    // Marketplace-plugin registry modules keep their installable skills outside
+    // the directory that holds module.yaml (sourcePath points at the -setup
+    // skill's assets/), so they cannot be installed by copying sourcePath. Copy
+    // the resolved skill directories instead, matching how custom marketplace
+    // installs lay out a module. Everything else (manifest, version info) flows
+    // through the standard external-module path below.
+    const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName);
+    if (moduleInfo && moduleInfo.marketplacePlugin) {
+      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
+      // Fail loud: copying sourcePath here would install only the -setup skill's
+      // assets/ (module.yaml + module-help.csv) and none of the skills — a
+      // silent, broken partial install. Abort instead.
+      if (!pluginResolution || !Array.isArray(pluginResolution.skillPaths) || pluginResolution.skillPaths.length === 0) {
+        throw new Error(
+          `Module '${moduleName}' is registered as a marketplace plugin but its skills could not be resolved ` +
+            `from .claude-plugin/marketplace.json (missing or malformed on the selected channel). ` +
+            `Aborting to avoid a partial install with no skills.`,
+        );
+      }
+      await this._copyResolvedSkills(pluginResolution, targetPath, fileTrackingCallback, options.moduleConfig);
+    } else {
+      await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
+    }
 
     if (!options.skipModuleInstaller) {
       await this.createModuleDirectories(moduleName, bmadDir, options);
@@ -304,41 +326,66 @@ class OfficialModules {
   }
 
   /**
-   * Install a module from a PluginResolver resolution result.
-   * Copies specific skill directories and places module-help.csv at the target root.
+   * Lay out a PluginResolver resolution on disk: copy each resolved skill
+   * directory (flattened by leaf name) into targetPath and place module-help.csv
+   * at the module root. Shared by both custom marketplace installs
+   * (installFromResolution) and official marketplace-plugin registry installs
+   * (install), so the two paths cannot drift.
    * @param {Object} resolved - ResolvedModule from PluginResolver
-   * @param {string} bmadDir - Target bmad directory
+   * @param {string} targetPath - Destination module directory (e.g. bmadDir/<code>)
    * @param {Function} fileTrackingCallback - Optional callback to track installed files
-   * @param {Object} options - Installation options
+   * @param {Object} moduleConfig - Module configuration passed to copy filtering
    */
-  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
-    const targetPath = path.join(bmadDir, resolved.code);
-
-    if (await fs.pathExists(targetPath)) {
-      await fs.remove(targetPath);
-    }
-
+  async _copyResolvedSkills(resolved, targetPath, fileTrackingCallback = null, moduleConfig = {}) {
     await fs.ensureDir(targetPath);
 
-    // Copy each skill directory, flattened by leaf name
+    // Copy each skill directory, flattened by leaf name. Leaf names must be
+    // unique — two skills that flatten to the same directory would silently
+    // overwrite each other, so fail loud instead.
+    const seenLeaves = new Map();
     for (const skillPath of resolved.skillPaths) {
       const skillDirName = path.basename(skillPath);
+      if (seenLeaves.has(skillDirName)) {
+        throw new Error(
+          `Cannot install module '${resolved.code}': skill directories '${seenLeaves.get(skillDirName)}' and ` +
+            `'${skillPath}' share the leaf name '${skillDirName}' and would overwrite each other. ` +
+            `Skill directory names must be unique.`,
+        );
+      }
+      seenLeaves.set(skillDirName, skillPath);
       const skillTarget = path.join(targetPath, skillDirName);
-      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, options.moduleConfig);
+      await this.copyModuleWithFiltering(skillPath, skillTarget, fileTrackingCallback, moduleConfig);
     }
 
-    // Place module-help.csv at the module root
+    // Place module-help.csv at the module root.
+    const helpTarget = path.join(targetPath, 'module-help.csv');
     if (resolved.moduleHelpCsvPath) {
-      // Strategies 1-4: copy the existing file
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategies 1-4: copy the existing file.
       await fs.copy(resolved.moduleHelpCsvPath, helpTarget, { overwrite: true });
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     } else if (resolved.synthesizedHelpCsv) {
-      // Strategy 5: write synthesized content
-      const helpTarget = path.join(targetPath, 'module-help.csv');
+      // Strategy 5: write synthesized content.
       await fs.writeFile(helpTarget, resolved.synthesizedHelpCsv, 'utf8');
       if (fileTrackingCallback) fileTrackingCallback(helpTarget);
     }
+  }
+
+  /**
+   * Install a module from a PluginResolver resolution result.
+   * Copies specific skill directories and places module-help.csv at the target root.
+   * @param {Object} resolved - ResolvedModule from PluginResolver
+   * @param {string} bmadDir - Target bmad directory
+   * @param {Function} fileTrackingCallback - Optional callback to track installed files
+   * @param {Object} options - Installation options
+   */
+  async installFromResolution(resolved, bmadDir, fileTrackingCallback = null, options = {}) {
+    const targetPath = path.join(bmadDir, resolved.code);
+
+    if (await fs.pathExists(targetPath)) {
+      await fs.remove(targetPath);
+    }
+
+    await this._copyResolvedSkills(resolved, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Create directories declared in module.yaml (strategies 1-4 may have these)
     if (!options.skipModuleInstaller) {

package/tools/installer/ui.js

@@ -944,25 +944,32 @@ class UI {
       }
     }
 
-    // Add external registry modules (skip built-in duplicates)
-    const externalRegistryModules = registryModules.filter((mod) => !mod.builtIn && !builtInCodes.has(mod.code));
+    // Add external registry modules (skip built-in duplicates and deprecated
+    // modules that are not already installed — deprecated modules stay visible
+    // only so existing users can continue to manage them).
+    const externalRegistryModules = registryModules.filter(
+      (mod) => !mod.builtIn && !builtInCodes.has(mod.code) && (!mod.deprecated || installedModuleIds.has(mod.code)),
+    );
     let externalRegistryEntries = [];
     if (externalRegistryModules.length > 0) {
       const spinner = await prompts.spinner();
       spinner.start('Checking latest module versions...');
 
       externalRegistryEntries = await Promise.all(
-        externalRegistryModules.map(async (mod) => ({
-          code: mod.code,
-          entry: await buildModuleEntry(
+        externalRegistryModules.map(async (mod) => {
+          const entry = await buildModuleEntry(
             mod.code,
             mod.name,
             mod.description,
             mod.defaultSelected,
             mod.url || null,
             mod.defaultChannel || null,
-          ),
-        })),
+          );
+          if (mod.deprecated && mod.deprecationMessage) {
+            entry.hint = entry.hint ? `${entry.hint} — ${mod.deprecationMessage}` : mod.deprecationMessage;
+          }
+          return { code: mod.code, entry };
+        }),
       );
 
       spinner.stop('Checked latest module versions.');