bmad-method 6.8.1-next.9 → 6.9.0

package/src/core-skills/bmad-party-mode/scripts/resolve_party.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve the party-mode roster, lazily.
+
+Merges the installed BMAD agents with the user's custom `party_members`
+into one collective, then projects only what the moment needs:
+
+  * default (no flag) — the active roster to load on entry: the
+    `default_party` group if one is configured, else the whole collective.
+    Other groups come back as names only, so nothing you aren't using is
+    loaded into the party.
+  * --list-groups — just id + name + size for every configured group. The
+    cheap menu for "which room?", with no member detail.
+  * --party <id> — full member detail for one chosen group, on demand
+    (e.g. when the user switches rooms). Unknown id returns the available
+    names instead of an error wall.
+
+The merge is deterministic (a keyed union; a custom member whose code
+matches an installed agent overrides it), so the orchestrator consumes a
+resolved roster instead of re-deriving it every session.
+
+Stdlib only (Python 3.11+ for tomllib). Shells out to the project's
+resolve_config.py and resolve_customization.py; falls back to reading
+customize.toml directly if the customization resolver is unavailable.
+
+  resolve_party.py --project-root P --skill S
+  resolve_party.py --project-root P --skill S --list-groups
+  resolve_party.py --project-root P --skill S --party writers-room
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover - guarded for <3.11
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib`).\n")
+    sys.exit(3)
+
+
+def _run_json(cmd):
+    """Run a resolver script and parse its JSON stdout. None on any failure."""
+    try:
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0 or not out.stdout.strip():
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def load_agents(project_root: Path):
+    """Installed agents as {code: entry}. Empty dict (with a flag) on failure."""
+    script = project_root / "_bmad" / "scripts" / "resolve_config.py"
+    data = _run_json([sys.executable, str(script), "--project-root", str(project_root), "--key", "agents"])
+    if data is None:
+        return {}, False
+    return data.get("agents", {}) or {}, True
+
+
+def load_workflow(project_root: Path, skill_root: Path):
+    """Merged [workflow] table. Falls back to the skill's base customize.toml."""
+    script = project_root / "_bmad" / "scripts" / "resolve_customization.py"
+    data = _run_json([sys.executable, str(script), "--skill", str(skill_root), "--key", "workflow"])
+    if data is not None and "workflow" in data:
+        return data["workflow"]
+    # Fallback: read the skill's base customize.toml directly (no override merge).
+    toml_path = skill_root / "customize.toml"
+    if toml_path.exists():
+        try:
+            with toml_path.open("rb") as f:
+                return tomllib.load(f).get("workflow", {})
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+    return {}
+
+
+def _alias(code: str) -> str:
+    """Short alias for an installed agent code: bmad-agent-analyst -> analyst."""
+    for prefix in ("bmad-agent-", "bmad-"):
+        if code.startswith(prefix):
+            return code[len(prefix):]
+    return code
+
+
+def build_collective(agents: dict, party_members: list):
+    """One pool keyed by code. Custom members override matching installed agents.
+
+    Returns (collective, index, installed_codes):
+      * collective — every member (installed + custom), the pool groups draw
+        from and the orchestrator can summon by name.
+      * index — maps every resolvable token (code, prefix-stripped alias,
+        lower-cased name) to a canonical code.
+      * installed_codes — the codes occupying an installed-agent slot, in
+        order. This is the DEFAULT room: installed agents (with any custom
+        override applied in place), and NOT the pure-custom additions. So
+        shipping or defining custom members grows the pool without crowding
+        the default party.
+    """
+    collective = {}
+    index = {}
+    installed_codes = []
+
+    def register(code, entry):
+        collective[code] = entry
+        index[code] = code
+        index[code.lower()] = code
+        index[_alias(code).lower()] = code
+        name = entry.get("name")
+        if name:
+            index[name.lower()] = code
+
+    for code, info in agents.items():
+        register(code, {
+            "code": code,
+            "name": info.get("name", code),
+            "icon": info.get("icon", ""),
+            "title": info.get("title", ""),
+            "description": info.get("description", ""),
+            "module": info.get("module", ""),
+            "team": info.get("team", ""),
+            "source": "installed",
+        })
+        installed_codes.append(code)
+
+    for m in party_members or []:
+        code = m.get("code")
+        if not code:
+            continue
+        # A custom member overrides an installed agent it matches by code/alias/name.
+        canonical = index.get(code) or index.get(code.lower()) or code
+        entry = {"code": canonical, "source": "custom"}
+        for field in ("name", "icon", "title", "persona", "capabilities", "model"):
+            if m.get(field) is not None:
+                entry[field] = m[field]
+        entry.setdefault("name", canonical)
+        register(canonical, entry)
+        # An override keeps the installed slot; a brand-new custom does not join it.
+
+    return collective, index, installed_codes
+
+
+def resolve_members(member_tokens, collective, index):
+    """(resolved entries in listed order, unresolved tokens)."""
+    resolved, unresolved = [], []
+    for token in member_tokens or []:
+        code = index.get(token) or index.get(str(token).lower())
+        if code and code in collective:
+            resolved.append(collective[code])
+        else:
+            unresolved.append(token)
+    return resolved, unresolved
+
+
+def group_menu(groups):
+    """Names only — the cheap menu. Open-cast groups (no roster) are flagged."""
+    out = []
+    for g in groups or []:
+        if not isinstance(g, dict) or not g.get("id"):
+            continue
+        members = g.get("members", []) or []
+        entry = {"id": g["id"], "name": g.get("name", g["id"]),
+                 "member_count": len(members)}
+        if not members:
+            entry["open_cast"] = True
+        out.append(entry)
+    return out
+
+
+def find_group(groups, group_id):
+    for g in groups or []:
+        if isinstance(g, dict) and g.get("id") == group_id:
+            return g
+    return None
+
+
+def group_detail(g, collective, index):
+    """Full detail for one group: resolved members + the optional scene.
+
+    `scene` is a freeform line the orchestrator plays — setting, what's
+    happening, room dynamics, in-the-moment character notes. Surfaced only
+    here (when a group is the active/chosen roster), never in the menu.
+
+    `members` is optional. With none, the group is open-cast: `open_cast`
+    is flagged and the scene describes the pool the orchestrator casts from
+    on the fly (e.g. "figures from the Star Wars Rebels universe"). A few
+    listed members anchor the room; the scene can still invite more.
+    """
+    raw_members = g.get("members", []) or []
+    members, unresolved = resolve_members(raw_members, collective, index)
+    detail = {"active": g["id"], "name": g.get("name", g["id"]),
+              "members": members, "unresolved": unresolved,
+              "memory_enabled": bool(g.get("memory", False))}
+    if g.get("scene"):
+        detail["scene"] = g["scene"]
+    if not raw_members:
+        detail["open_cast"] = True
+    return detail
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Resolve the party-mode roster, lazily.")
+    ap.add_argument("--project-root", required=True)
+    ap.add_argument("--skill", required=True, help="Path to the bmad-party-mode skill dir")
+    ap.add_argument("--party", help="Resolve full detail for this group id")
+    ap.add_argument("--list-groups", action="store_true", help="Group names only")
+    args = ap.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    skill_root = Path(args.skill).resolve()
+
+    workflow = load_workflow(project_root, skill_root)
+    groups = workflow.get("party_groups", []) or []
+    default_party = workflow.get("default_party", "") or ""
+    party_mode = workflow.get("party_mode", "session") or "session"
+    # The global party_memory flag governs only the DEFAULT installed-agent room;
+    # a named group carries its own `memory` flag (resolved in group_detail).
+    party_memory = bool(workflow.get("party_memory", True))
+
+    # Group menu never needs the (more expensive) installed-agent resolve.
+    if args.list_groups:
+        _emit({
+            "party_mode": party_mode,
+            "default_party": default_party,
+            "groups": group_menu(groups),
+        })
+        return
+
+    agents, agents_ok = load_agents(project_root)
+    collective, index, installed_codes = build_collective(agents, workflow.get("party_members", []))
+
+    if args.party:
+        g = find_group(groups, args.party)
+        if g is None:
+            _emit({"error": "unknown_group", "requested": args.party,
+                   "available": group_menu(groups)})
+            return
+        _emit({**group_detail(g, collective, index), "party_mode": party_mode})
+        return
+
+    # Default: the active roster to load on entry.
+    result = {"party_mode": party_mode, "groups": group_menu(groups),
+              "installed_agents_resolved": agents_ok}
+    g = find_group(groups, default_party) if default_party else None
+    if g is not None:
+        result.update(group_detail(g, collective, index))
+    else:
+        # No default group: the installed agents (custom additions stay in the
+        # pool but don't crowd the default room), exactly like a plain install.
+        result.update({"active": "installed",
+                       "members": [collective[c] for c in installed_codes],
+                       "memory_enabled": party_memory})
+    _emit(result)
+
+
+def _emit(obj):
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/core-skills/bmad-party-mode/scripts/tests/test-resolve_party.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Unit tests for resolve_party.py — merge, alias, override, group resolution."""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+import resolve_party as rp  # noqa: E402
+
+AGENTS = {
+    "bmad-agent-analyst": {"name": "Mary", "icon": "📊", "title": "Analyst"},
+    "bmad-agent-pm": {"name": "John", "icon": "📋", "title": "PM"},
+}
+
+
+class TestAlias(unittest.TestCase):
+    def test_strips_known_prefixes(self):
+        self.assertEqual(rp._alias("bmad-agent-analyst"), "analyst")
+        self.assertEqual(rp._alias("bmad-foo"), "foo")
+
+    def test_passes_through_unprefixed(self):
+        self.assertEqual(rp._alias("morpheus"), "morpheus")
+
+
+class TestBuildCollective(unittest.TestCase):
+    def test_installed_agents_indexed_by_code_alias_and_name(self):
+        col, idx, _ = rp.build_collective(AGENTS, [])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+        self.assertEqual(idx["analyst"], "bmad-agent-analyst")      # alias
+        self.assertEqual(idx["mary"], "bmad-agent-analyst")         # name (ci)
+        self.assertEqual(idx["bmad-agent-pm"], "bmad-agent-pm")     # full code
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "installed")
+
+    def test_custom_member_appends(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus", "persona": "riddles"}])
+        self.assertIn("morpheus", col)
+        self.assertEqual(col["morpheus"]["source"], "custom")
+        self.assertEqual(col["morpheus"]["persona"], "riddles")
+
+    def test_custom_overrides_installed_by_alias(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"code": "analyst", "name": "Mary-Custom", "persona": "p"}])
+        # Override lands on the canonical installed code, not a new "analyst" entry.
+        self.assertNotIn("analyst", col)
+        self.assertEqual(col["bmad-agent-analyst"]["source"], "custom")
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+    def test_member_without_code_skipped(self):
+        col, _, _ = rp.build_collective(AGENTS, [{"name": "Nameless"}])
+        self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
+
+
+class TestResolveMembers(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_resolves_in_listed_order_and_flags_unknowns(self):
+        resolved, unresolved = rp.resolve_members(["morpheus", "analyst", "ghost"], self.col, self.idx)
+        self.assertEqual([m["code"] for m in resolved], ["morpheus", "bmad-agent-analyst"])
+        self.assertEqual(unresolved, ["ghost"])
+
+    def test_empty(self):
+        self.assertEqual(rp.resolve_members([], self.col, self.idx), ([], []))
+
+
+class TestGroups(unittest.TestCase):
+    GROUPS = [
+        {"id": "wr", "name": "Writers", "members": ["analyst", "morpheus"]},
+        {"id": "bad"},  # no name -> falls back to id; no members -> count 0
+        {"name": "no-id"},  # dropped from menu
+    ]
+
+    def test_menu_is_names_only_with_counts_and_open_cast_flag(self):
+        menu = rp.group_menu(self.GROUPS)
+        self.assertEqual(menu, [
+            {"id": "wr", "name": "Writers", "member_count": 2},
+            {"id": "bad", "name": "bad", "member_count": 0, "open_cast": True},
+        ])
+
+    def test_find_group(self):
+        self.assertEqual(rp.find_group(self.GROUPS, "wr")["name"], "Writers")
+        self.assertIsNone(rp.find_group(self.GROUPS, "missing"))
+
+
+class TestGroupDetail(unittest.TestCase):
+    def setUp(self):
+        self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
+
+    def test_scene_passes_through_when_present(self):
+        g = {"id": "tos-10-forward", "name": "Ten Forward", "members": ["morpheus"],
+             "scene": "Late evening, a few rounds in."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertEqual(d["scene"], "Late evening, a few rounds in.")
+        self.assertEqual([m["code"] for m in d["members"]], ["morpheus"])
+
+    def test_scene_omitted_when_absent_or_empty(self):
+        for g in ({"id": "g", "members": ["morpheus"]},
+                  {"id": "g", "members": ["morpheus"], "scene": ""}):
+            self.assertNotIn("scene", rp.group_detail(g, self.col, self.idx))
+
+    def test_anchored_group_is_not_open_cast(self):
+        g = {"id": "g", "members": ["morpheus"]}
+        self.assertNotIn("open_cast", rp.group_detail(g, self.col, self.idx))
+
+    def test_open_cast_group_flagged_with_empty_members(self):
+        g = {"id": "rebels", "name": "Star Wars Rebels",
+             "scene": "Figures from the Rebels universe drop in as the topic calls for them."}
+        d = rp.group_detail(g, self.col, self.idx)
+        self.assertTrue(d["open_cast"])
+        self.assertEqual(d["members"], [])
+        self.assertEqual(d["scene"][:7], "Figures")
+
+    def test_memory_enabled_follows_group_flag_and_defaults_off(self):
+        on = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": True}, self.col, self.idx)
+        self.assertTrue(on["memory_enabled"])
+        off = rp.group_detail({"id": "g", "members": ["morpheus"], "memory": False}, self.col, self.idx)
+        self.assertFalse(off["memory_enabled"])
+        absent = rp.group_detail({"id": "g", "members": ["morpheus"]}, self.col, self.idx)
+        self.assertFalse(absent["memory_enabled"])  # opt-in per named group
+
+
+class TestInstalledCodesIsDefaultRoom(unittest.TestCase):
+    """The default room is installed agents only; pure customs stay in the pool."""
+
+    def test_pure_custom_excluded_override_kept_in_default_room(self):
+        col, _, installed = rp.build_collective(AGENTS, [
+            {"code": "morpheus", "name": "Morpheus"},                 # pure custom
+            {"code": "analyst", "name": "Mary-Custom", "persona": "p"},  # override
+            {"code": "sec-hawk", "name": "Vex"},                      # shipped crew member
+        ])
+        # Pure customs are in the pool...
+        self.assertIn("morpheus", col)
+        self.assertIn("sec-hawk", col)
+        # ...but NOT in the default room.
+        self.assertEqual(installed, ["bmad-agent-analyst", "bmad-agent-pm"])
+        default_room = [col[c]["code"] for c in installed]
+        self.assertEqual(default_room, ["bmad-agent-analyst", "bmad-agent-pm"])
+        # An override keeps its installed slot (and its custom content).
+        self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -18,7 +18,7 @@ Multiple skills may call to update the same spec over time.
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
+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.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
@@ -57,8 +57,8 @@ Deriving the contract from a living log instead of editing the contract in place
 
 Writes go through the shared script — `{project-root}/_bmad/scripts/memlog.py`, the same location as `resolve_customization.py` (atomic; never read it back except to resume):
 
-- `python3 {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"` — once, at create.
-- `python3 {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>"` — as each lands.
+- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>"` — once, at create.
+- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>"` — as each lands.
 - Terminal moments (a validation verdict, "spec finalized") are `--type event` entries; the memlog carries no status field.
 
 ## The Operation
@@ -69,6 +69,8 @@ When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a br
 
 Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
 
+A recognized domain implication the input leaves unaddressed *is* such a gap — name it as an `open_questions[]` entry (healthcare input silent on PHI/HIPAA, payments silent on PCI, control systems silent on fail-safe) and move on. Flag it; never invent the answer or coach toward it. If these dominate, the input is too thin — suggest `bmad-prd`.
+
 Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
 
 Log each decision, capability, constraint, and accepted change to `.memlog.md` as it is made — that running record is what the render reads. Because the log is append-only, a later entry supersedes an earlier one on the same point while the history stays intact. When two currently-live sources or companions disagree on the same field, or an either/or never got resolved, surface it to the user rather than silently choosing — the resolution is itself a new memlog entry.

package/src/core-skills/bmad-spec/assets/spec-template.md

@@ -20,9 +20,9 @@ Name which (or which combination) applies, who is affected, and the backdrop tha
 
 ## Capabilities
 
-- id: CAP-1
-  intent: {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
-  success: {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
+- **CAP-1**
+  - **intent:** {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
+  - **success:** {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
 
 ## Constraints
 

package/src/core-skills/module-help.csv

@@ -11,3 +11,4 @@ Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assu
 Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
 Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
+Core,bmad-forge-idea,Forge Idea,FI,"Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev.",,,anytime,,,false,{output_folder}/forge,refined-idea brief (optional)

package/src/scripts/resolve_config.py

@@ -10,12 +10,14 @@ Reads from four layers (highest priority last):
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-no virtualenv — plain `python3` is sufficient.
-
-  python3 resolve_config.py --project-root /abs/path/to/project
-  python3 resolve_config.py --project-root ... --key core
-  python3 resolve_config.py --project-root ... --key agents
+Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
+BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
+interpreter for you); a plain `python3` on PATH still works during the
+transition. Either runner needs Python 3.11+ for `tomllib`.
+
+  uv run resolve_config.py --project-root /abs/path/to/project
+  uv run resolve_config.py --project-root ... --key core
+  uv run resolve_config.py --project-root ... --key agents
 
 Merge rules (same as resolve_customization.py):
   - Scalars: override wins

package/src/scripts/resolve_customization.py

@@ -11,12 +11,14 @@ Skill name is derived from the basename of the skill directory.
 
 Outputs merged JSON to stdout. Errors go to stderr.
 
-Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
-no virtualenv — plain `python3` is sufficient.
-
-  python3 resolve_customization.py --skill /abs/path/to/skill-dir
-  python3 resolve_customization.py --skill ... --key agent
-  python3 resolve_customization.py --skill ... --key agent.menu
+Uses only the Python stdlib (`tomllib`) — no third-party dependencies.
+BMad is standardizing on `uv run` to invoke scripts (uv provisions a suitable
+interpreter for you); a plain `python3` on PATH still works during the
+transition. Either runner needs Python 3.11+ for `tomllib`.
+
+  uv run resolve_customization.py --skill /abs/path/to/skill-dir
+  uv run resolve_customization.py --skill ... --key agent
+  uv run resolve_customization.py --skill ... --key agent.menu
 
 Merge rules (purely structural — no field-name special-casing):
   - Scalars (string, int, bool, float): override wins

package/tools/installer/commands/install.js

@@ -75,6 +75,9 @@ module.exports = {
         return;
       }
 
+      const { checkWindowsNodeFromWsl } = require('../core/wsl-node-check');
+      await checkWindowsNodeFromWsl();
+
       // Set debug flag as environment variable for all components
       if (options.debug) {
         process.env.BMAD_DEBUG_MANIFEST = 'true';

package/tools/installer/core/installer.js

@@ -1233,6 +1233,9 @@ class Installer {
       `    1. Launch your AI agent from your project folder`,
       `    2. Not sure what to do? Invoke the ${color.cyan('bmad-help')} skill and ask it what to do!`,
       '',
+      `    ${color.cyan('Tip:')} BMAD workflows increasingly run Python scripts via ${color.cyan('uv run')} — uv is`,
+      `    becoming the de facto standard. If you don't have it yet, ask your agent to set it up.`,
+      '',
       `    Blog, Docs and Guides: ${color.blue('https://bmadcode.com/')}`,
       `    Community: ${color.blue('https://discord.gg/gk8jAdXWmj')}`,
     );

package/tools/installer/core/uv-check.js

@@ -0,0 +1,97 @@
+const { spawnSync } = require('node:child_process');
+const prompts = require('../prompts');
+
+// `uv` (https://docs.astral.sh/uv/) is becoming the de facto standard for
+// running the Python scripts BMAD workflows shell out to: `uv run <script>`
+// resolves the interpreter and any dependencies on demand, so skills don't
+// have to assume a particular `python3` is on PATH. The ecosystem is mid-
+// migration — some skills still call `python3` directly — so a missing `uv`
+// is a warning, not a blocker: BMAD installs and runs either way.
+const RUNTIME_COMMAND = 'uv';
+
+/**
+ * Parse `uv --version` output into version parts.
+ * Example outputs: "uv 0.5.31", "uv 0.5.31 (Homebrew 2025-02-12)".
+ * @param {string} output - stdout/stderr from `uv --version`
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function parseUvVersion(output) {
+  if (!output) return null;
+  const match = output.match(/uv\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] || 0),
+    raw: `${match[1]}.${match[2]}.${match[3] || 0}`,
+  };
+}
+
+/**
+ * Probe the local environment for `uv`.
+ * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
+ */
+function detectUv() {
+  let result;
+  try {
+    result = spawnSync(RUNTIME_COMMAND, ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      windowsHide: true,
+    });
+  } catch {
+    return null;
+  }
+  if (!result || result.error) return null;
+  const version = parseUvVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
+  return version ? { version } : null;
+}
+
+function setupHints() {
+  return [
+    'BMAD workflows increasingly run Python scripts via `uv run`, which manages',
+    'the interpreter and dependencies for you — no manual venv or pip needed.',
+    '',
+    'Easiest path: ask your AI agent to "install and set up uv for me".',
+    '',
+    'Or install it yourself:',
+    '  macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh',
+    '  Windows:      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
+    '  Homebrew:     brew install uv',
+    '  Docs:         https://docs.astral.sh/uv/getting-started/installation/',
+  ].join('\n');
+}
+
+/**
+ * Check whether `uv` is available and inform the user.
+ *
+ * Warn-don't-block, and no acknowledgement prompt: `uv` is on its way to being
+ * the standard runner for BMAD's Python scripts, but the migration is still in
+ * progress, so the install never stops on its account. The note tells the user
+ * how to set it up (preferably by asking their agent).
+ *
+ * @returns {Promise<{status: 'found'|'missing', detected: Object|null}>}
+ */
+async function checkUvEnvironment() {
+  // Called via module.exports so tests can stub detection.
+  const detected = module.exports.detectUv();
+
+  if (detected) {
+    await prompts.log.success(`uv ${detected.version.raw} detected — ready to run BMAD's Python-powered scripts via \`uv run\`.`);
+    return { status: 'found', detected };
+  }
+
+  await prompts.log.warn(
+    "uv not found on PATH. uv is becoming the de facto standard for running BMAD's Python\n" +
+      'scripts (`uv run <script>`), and it provisions the interpreter for you. BMAD installs\n' +
+      'fine without it, but setting up uv now keeps you ahead as workflows adopt it.',
+  );
+  await prompts.note(setupHints(), 'uv recommended');
+  return { status: 'missing', detected: null };
+}
+
+module.exports = {
+  checkUvEnvironment,
+  detectUv,
+  parseUvVersion,
+};