bmad-method 6.10.1-next.53 → 6.10.1-next.55

package/package.json

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

package/src/bmm-skills/agents/bmad-agent-analyst/SKILL.md

@@ -20,7 +20,7 @@ You are Mary, the Business Analyst. You bring deep expertise in market research,
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-architect/SKILL.md

@@ -20,7 +20,7 @@ You are Winston, the System Architect. You turn product requirements and UX into
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-dev/SKILL.md

@@ -20,7 +20,7 @@ You are Amelia, the Senior Software Engineer. You execute approved stories with
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-pm/SKILL.md

@@ -20,7 +20,7 @@ You are John, the Product Manager. You drive PRD creation through user interview
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-ux-designer/SKILL.md

@@ -20,7 +20,7 @@ You are Sally, the UX Designer. You translate user needs into interaction design
 
 ### Step 1: Resolve the Agent Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/plan/bmad-create-epics-and-stories/SKILL.md

@@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/plan/bmad-create-epics-and-stories/steps/step-04-final-validation.md

@@ -138,6 +138,6 @@ Upon Completion of task output: offer to answer any questions about the Epics an
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/plan/bmad-prd/references/validate.md

@@ -41,11 +41,11 @@ Once every selected reviewer has returned, the parent synthesizes one consolidat
    - **Footer.** Rubric path, ISO timestamp.
 3. Write the filled HTML to `{doc_workspace}/validation-report.html`.
 4. Write the markdown twin to `{doc_workspace}/validation-report.md` (same content, grouped by severity rather than by dimension — see format below; this is the canonical form for downstream re-reading).
-5. Open the HTML in the default browser:
+5. Open the HTML in the default browser with the platform opener — `open` on macOS, `xdg-open` on Linux, `start ""` on Windows — double-quoting the path:
    ```bash
-   python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"
+   open "{doc_workspace}/validation-report.html"
    ```
-   Skip the open step in headless mode (see `references/headless.md`).
+   If the command fails, don't retry with another opener: tell the user the file path and move on. Skip the open step in headless mode (see `references/headless.md`).
 
 ### Markdown twin format
 

package/src/bmm-skills/plan/bmad-prfaq/SKILL.md

@@ -30,7 +30,7 @@ The PRFAQ forces customer-first clarity: write the press release announcing the
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/plan/bmad-prfaq/references/verdict.md

@@ -78,6 +78,6 @@ purpose: "Token-efficient context for downstream PRD creation"
 
 This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/plan/bmad-project-context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-project-context
-description: 'Set up or refresh agent instructions so AI agents work well in it. Use when the user says "project context", "set up AGENTS.md", "document this project", "refresh context", "audit context", wants to apply coding standards or governance to a repo, or wants to record a mistake agents keep making'
+description: 'Set up, refresh, or audit a repository''s agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfall lines. Must be invoked by name.'
 ---
 
 # Overview

package/src/bmm-skills/plan/bmad-ux/assets/color-themes.md

@@ -6,4 +6,4 @@ Each variation: header (name + one-line emotional register), token chips for eve
 
 Inline CSS only, system font stack, no JS, no network. Document concrete hex values in `<style>` comments per variation so the user can lift them if they pick that theme. The spine itself stays semantic.
 
-Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file with `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`.
+Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file with the platform opener — `open "PATH"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead.

package/src/bmm-skills/plan/bmad-ux/references/creative-tools.md

@@ -16,4 +16,4 @@ Every renderer writes to `{doc_workspace}/.working/` with a descriptive filename
 
 The parent passes the subagent: current `.memlog.md`, relevant prior `.working/` captures, the user's stated intent for this pass, the output path. The subagent writes its artifact under `.working/` and returns ONLY a compact summary (file path, one line per variant, mode coverage). Parent never holds the full payload.
 
-For HTML, open in browser when interactive: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`. Skip in headless.
+For HTML, open in the browser when interactive with the platform opener — `open "PATH"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead. Skip in headless.

package/src/bmm-skills/plan/bmad-ux/references/validate.md

@@ -69,7 +69,7 @@ Under Validate intent, after every reviewer returns, render one consolidated rep
 2. Fill `{workflow.validation_report_template}`. No overall grade — the per-category verdicts and severity counts already say what's true. Synthesis paragraph lifts the rubric's overall verdict; add a second if extra reviewers shift the picture. One section per rubric category (open if thin / broken), one per extra reviewer (closed, adversarial voice preserved).
 3. Write `{doc_workspace}/validation-report.html`.
 4. Write the Markdown twin `{doc_workspace}/validation-report.md` — same content grouped by severity.
-5. Open HTML: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"`. Skip headless.
+5. Open HTML with the platform opener — `open "{doc_workspace}/validation-report.html"` on macOS, `xdg-open` on Linux, `start ""` on Windows, path always double-quoted. On failure, give the user the path instead. Skip headless.
 
 Re-running overwrites the consolidated report; individual `review-*.md` files persist.
 

package/src/bmm-skills/ship/bmad-checkpoint-preview/SKILL.md

@@ -20,7 +20,7 @@ description: 'LLM-assisted human-in-the-loop review. Make sense of a change, foc
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/ship/bmad-checkpoint-preview/step-05-wrapup.md

@@ -25,6 +25,6 @@ HALT — do not proceed until the user makes their choice.
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/ship/bmad-code-review/SKILL.md

@@ -21,7 +21,7 @@ If you need an explicit user instruction to run them, ask once now for the whole
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/ship/bmad-code-review/steps/step-04-present.md

@@ -127,6 +127,6 @@ Present the user with follow-up options:
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

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

@@ -20,7 +20,7 @@ description: 'Manage significant changes during sprint execution. Use when the u
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
@@ -294,7 +294,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
 <action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action>
 <action>Remind user of success criteria and next steps for Developer agent</action>
-<action>Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
+<action>Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
 </step>
 
 </workflow>

package/src/bmm-skills/ship/bmad-qa-generate-e2e-tests/SKILL.md

@@ -20,7 +20,7 @@ description: 'Generate end to end automated tests for existing features. Use whe
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
@@ -171,6 +171,6 @@ Save summary to: `{default_output_file}`
 
 ## On Complete
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/v6-shims/bmad-create-architecture/SKILL.md

@@ -9,7 +9,7 @@ This skill was consolidated into `bmad-architecture`. It is retained as a thin c
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-create-architecture.toml` and `bmad-create-architecture.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-create-architecture.toml` and `bmad-create-architecture.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
 
 2. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
 

package/src/bmm-skills/v6-shims/bmad-create-prd/SKILL.md

@@ -9,7 +9,7 @@ This skill was consolidated into `bmad-prd`. It is retained as a thin compatibil
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-create-prd.toml` and `bmad-create-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-create-prd.toml` and `bmad-create-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
 
 2. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
 

package/src/bmm-skills/v6-shims/bmad-create-story/SKILL.md

@@ -30,7 +30,7 @@ If you need an explicit user instruction to run them, ask once now for the whole
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
@@ -428,7 +428,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
     **The developer now has everything needed for flawless implementation!**
   </output>
-  <action>Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
+  <action>Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
 </step>
 
 </workflow>

package/src/bmm-skills/v6-shims/bmad-dev-story/SKILL.md

@@ -27,7 +27,7 @@ description: "Deprecated: `bmad-build` is now the official implementation method
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
@@ -496,7 +496,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
       <action>Suggest checking {sprint_status} to see project progress</action>
     </check>
     <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
-  <action>Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
+  <action>Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
   </step>
 
 </workflow>

package/src/bmm-skills/v6-shims/bmad-edit-prd/SKILL.md

@@ -9,7 +9,7 @@ This skill was consolidated into `bmad-prd`. It is retained as a thin compatibil
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-edit-prd.toml` and `bmad-edit-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-edit-prd.toml` and `bmad-edit-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
 
 2. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
 

package/src/bmm-skills/v6-shims/bmad-validate-prd/SKILL.md

@@ -9,7 +9,7 @@ This skill was consolidated into `bmad-prd`. It is retained as a thin compatibil
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-validate-prd.toml` and `bmad-validate-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. This picks up any `{project-root}/_bmad/custom/bmad-validate-prd.toml` and `bmad-validate-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
 
 2. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
 

package/tools/installer/core/installer.js

@@ -1245,9 +1245,23 @@ class Installer {
       '  Get started:',
       `    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.`,
+    );
+
+    // Repeat the uv warning here when it applies. The pre-install probe fires
+    // before every prompt in the run, so by now it is far up the scrollback —
+    // and this box is titled "BMAD is ready to use!", which is only true if
+    // the rendered skills can actually start.
+    const { detectUv } = require('./uv-check');
+    if (!detectUv()) {
+      lines.push(
+        '',
+        `    ${color.yellow('⚠ uv is not installed.')} ${color.cyan('bmad-build')} and ${color.cyan('bmad-build-auto')} render through`,
+        `    ${color.cyan('uv run')} and will halt on activation until you set it up — ask your agent to`,
+        `    "install and set up uv for me", or see https://docs.astral.sh/uv/`,
+      );
+    }
+
+    lines.push(
       '',
       `    Blog, Docs and Guides: ${color.blue('https://bmadcode.com/')}`,
       `    Community: ${color.blue('https://discord.gg/gk8jAdXWmj')}`,

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

@@ -1,14 +1,30 @@
 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.
+// `uv` (https://docs.astral.sh/uv/) is how BMAD runs the Python scripts its
+// skills shell out to: `uv run <script>` resolves the interpreter and any
+// dependencies on demand from the script's own `requires-python` metadata, so
+// skills don't have to assume a particular `python3` is on PATH.
+//
+// As of v6.11.0 this is a requirement, not a preference: the rendered skills
+// (`bmad-build`, `bmad-build-auto`) render through `render_skill.py` and HALT
+// on activation if `uv` is unavailable — there is no interpreter fallback.
+//
+// The check still never blocks the install. Core-only, docs-only, and CI
+// installs are legitimate and never touch a rendered skill, so a missing `uv`
+// must not fail the run. What it does is tell the truth about what will and
+// will not work afterwards, here and again in the post-install summary.
 const RUNTIME_COMMAND = 'uv';
 
+// Probed only when `uv` is absent. Some skills still invoke the interpreter
+// directly (`python3 .../resolve_customization.py`), and those scripts declare
+// `requires-python = ">=3.11"` — `resolve_config.py` hard-exits below it
+// because `tomllib` is a 3.11 stdlib addition. When `uv` is present it
+// provisions its own interpreter and whatever `python3` resolves to on PATH is
+// irrelevant, so probing it then would report a problem that doesn't exist.
+const PYTHON_COMMAND = 'python3';
+const MIN_PYTHON = { major: 3, minor: 11 };
+
 /**
  * Parse `uv --version` output into version parts.
  * Example outputs: "uv 0.5.31", "uv 0.5.31 (Homebrew 2025-02-12)".
@@ -28,13 +44,44 @@ function parseUvVersion(output) {
 }
 
 /**
- * Probe the local environment for `uv`.
- * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
+ * Parse `python3 --version` output into version parts.
+ * Example outputs: "Python 3.11.7", "Python 3.13.0rc1".
+ * @param {string} output - stdout/stderr from `python3 --version`
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
  */
-function detectUv() {
+function parsePythonVersion(output) {
+  if (!output) return null;
+  const match = output.match(/Python\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}`,
+  };
+}
+
+/**
+ * Whether a parsed Python version satisfies the 3.11+ floor the scripts declare.
+ * @param {{major: number, minor: number}|null} version
+ * @returns {boolean}
+ */
+function pythonMeetsMinimum(version) {
+  if (!version) return false;
+  if (version.major !== MIN_PYTHON.major) return version.major > MIN_PYTHON.major;
+  return version.minor >= MIN_PYTHON.minor;
+}
+
+/**
+ * Run `<command> --version` and hand the combined output to a parser.
+ * @param {string} command
+ * @param {(output: string) => Object|null} parse
+ * @returns {{version: Object}|null}
+ */
+function probeVersion(command, parse) {
   let result;
   try {
-    result = spawnSync(RUNTIME_COMMAND, ['--version'], {
+    result = spawnSync(command, ['--version'], {
       encoding: 'utf8',
       timeout: 5000,
       windowsHide: true,
@@ -43,14 +90,30 @@ function detectUv() {
     return null;
   }
   if (!result || result.error) return null;
-  const version = parseUvVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
+  const version = parse(`${result.stdout || ''}\n${result.stderr || ''}`);
   return version ? { version } : null;
 }
 
+/**
+ * Probe the local environment for `uv`.
+ * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
+ */
+function detectUv() {
+  return probeVersion(RUNTIME_COMMAND, parseUvVersion);
+}
+
+/**
+ * Probe the local environment for `python3`.
+ * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
+ */
+function detectPython3() {
+  return probeVersion(PYTHON_COMMAND, parsePythonVersion);
+}
+
 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.',
+    '`uv run` provisions the interpreter and dependencies for you — no manual',
+    'venv or pip, and no need for a particular python3 on PATH.',
     '',
     'Easiest path: ask your AI agent to "install and set up uv for me".',
     '',
@@ -62,15 +125,42 @@ function setupHints() {
   ].join('\n');
 }
 
+/**
+ * Describe what a missing `uv` leaves working, based on the `python3` fallback.
+ *
+ * With `uv` gone the rendered skills are lost either way; the only question is
+ * whether the skills that invoke the interpreter directly still run, and that
+ * turns on `python3` being 3.11+.
+ *
+ * @param {{version: Object}|null} python - result of detectPython3()
+ * @returns {string}
+ */
+function pythonFallbackNote(python) {
+  if (!python) {
+    return 'No python3 on PATH either, so no Python-backed skill will run.';
+  }
+  if (pythonMeetsMinimum(python.version)) {
+    return (
+      `python3 ${python.version.raw} is present, so skills that call the interpreter ` +
+      'directly still work — but the rendered skills above stay unavailable.'
+    );
+  }
+  return (
+    `python3 ${python.version.raw} is present but below the required ` +
+    `${MIN_PYTHON.major}.${MIN_PYTHON.minor}, so no Python-backed skill will run.`
+  );
+}
+
 /**
  * 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).
+ * Warn-don't-block: a missing `uv` never stops or fails the install, because
+ * core-only and CI installs are legitimate and never render a skill. But the
+ * warning names the concrete consequence — `bmad-build` and `bmad-build-auto`
+ * halt — rather than describing `uv` as a nice-to-have, and `installer.js`
+ * repeats it in the post-install summary so it isn't lost in the scrollback.
  *
- * @returns {Promise<{status: 'found'|'missing', detected: Object|null}>}
+ * @returns {Promise<{status: 'found'|'missing', detected: Object|null, python: Object|null}>}
  */
 async function checkUvEnvironment() {
   // Called via module.exports so tests can stub detection.
@@ -78,20 +168,28 @@ async function checkUvEnvironment() {
 
   if (detected) {
     await prompts.log.success(`✅ Python UV check pass (uv ${detected.version.raw} detected).`);
-    return { status: 'found', detected };
+    return { status: 'found', detected, python: null };
   }
 
+  const python = module.exports.detectPython3();
+
   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.',
+    'uv not found on PATH. BMAD requires it to run the Python scripts its skills\n' +
+      'shell out to: bmad-build and bmad-build-auto render through `uv run` and will\n' +
+      'HALT on activation without it — there is no interpreter fallback.\n' +
+      `${pythonFallbackNote(python)}\n` +
+      'The install itself completes either way.',
   );
-  await prompts.note(setupHints(), 'uv recommended');
-  return { status: 'missing', detected: null };
+  await prompts.note(setupHints(), 'uv required');
+  return { status: 'missing', detected: null, python };
 }
 
 module.exports = {
   checkUvEnvironment,
   detectUv,
+  detectPython3,
   parseUvVersion,
+  parsePythonVersion,
+  pythonMeetsMinimum,
+  MIN_PYTHON,
 };

package/tools/installer/install-messages.yaml

@@ -12,8 +12,9 @@ startMessage: |
   🌟 100% free. 100% open source. Always.
      No paywalls. No gated content. Knowledge shared, not sold.
 
-  🐍 HEADS UP: uv (https://docs.astral.sh/uv/) is becoming the de facto standard
-     for running the Python scripts BMAD workflows rely on (`uv run <script>`).
+  🐍 REQUIRED: uv (https://docs.astral.sh/uv/) runs the Python scripts BMAD
+     skills rely on (`uv run <script>`) and provisions the interpreter itself.
+     Without it, bmad-build and bmad-build-auto halt on activation.
      If it's not set up yet, ask your AI agent to "install and set up uv for me".
 
   🌐 CONNECT:

package/tools/installer/ui.js

@@ -204,13 +204,15 @@ class UI {
     const messageLoader = new MessageLoader();
     await messageLoader.displayStartMessage();
 
-    // Probe for `uv` before any other prompts: it's becoming the de facto
-    // runner for the Python scripts BMAD workflows shell out to
-    // (`uv run <script>`), and uv provisions the interpreter itself, so it's
-    // the single thing worth checking for. The migration is still in progress
-    // (some skills still call `python3` directly), so this is informational —
-    // warn-don't-block, no ack prompt — and just points the user at setup
-    // (ideally "ask your agent to set up uv"). The installer runs in the
+    // Probe for `uv` before any other prompts: it's the runner for the Python
+    // scripts BMAD skills shell out to (`uv run <script>`), and uv provisions
+    // the interpreter itself, so it's the single thing worth checking for.
+    // As of v6.11.0 `bmad-build` and `bmad-build-auto` HALT without it.
+    //
+    // Still warn-don't-block, with no ack prompt: core-only, docs-only, and
+    // CI installs never touch a rendered skill, so a missing `uv` must not
+    // fail the run. `installer.js` repeats the warning in the post-install
+    // summary so it survives the scrollback. The installer runs in the
     // destination environment, so probing PATH here tests the right machine.
     const { checkUvEnvironment } = require('./core/uv-check');
     await checkUvEnvironment();