bmad-method 6.10.1-next.9 → 6.11.0

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/ide/_config-driven.js

@@ -434,7 +434,7 @@ class ConfigDrivenIdeSetup {
       if (!canonicalId) continue;
 
       // Derive source directory from path column
-      // path is like "_bmad/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md"
+      // path is like "_bmad/bmm/workflows/bmad-quick-flow/bmad-build-new-preview/SKILL.md"
       // Strip bmadFolderName prefix and join with bmadDir, then get dirname
       const relativePath = record.path.startsWith(bmadPrefix) ? record.path.slice(bmadPrefix.length) : record.path;
       const sourceFile = path.join(bmadDir, relativePath);

package/tools/installer/ide/platform-codes.yaml

@@ -35,6 +35,13 @@ platforms:
       target_dir: .agent/skills
       global_target_dir: ~/.gemini/antigravity/skills
 
+  antigravity-cli:
+    name: "Antigravity CLI (AGY)"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.gemini/antigravity-cli/skills
+
   auggie:
     name: "Auggie"
     preferred: false

package/tools/installer/ide/shared/path-utils.js

@@ -53,7 +53,7 @@ function toDashName(module, type, name) {
 /**
  * Convert relative path to flat dash-separated name
  * Converts: 'bmm/agents/pm.md' → 'bmad-agent-bmm-pm.md'
- * Converts: 'bmm/agents/tech-writer/tech-writer.md' → 'bmad-agent-bmm-tech-writer.md' (uses folder name)
+ * Converts: 'bmm/agents/analyst/analyst.md' → 'bmad-agent-bmm-analyst.md' (uses folder name)
  * Converts: 'bmm/workflows/correct-course.md' → 'bmad-bmm-correct-course.md'
  * Converts: 'core/agents/brainstorming.md' → 'bmad-agent-brainstorming.md' (core agents skip module name)
  *
@@ -76,7 +76,7 @@ function toDashPath(relativePath) {
   let name;
 
   // For agents, if nested in a folder (more than 3 parts), use the folder name only
-  // e.g., 'bmm/agents/tech-writer/tech-writer' → 'tech-writer' (not 'tech-writer-tech-writer')
+  // e.g., 'bmm/agents/analyst/analyst' → 'analyst' (not 'analyst-analyst')
   if (type === 'agents' && parts.length > 3) {
     // Use the folder name (parts[2]) as the name, ignore the file name
     name = parts[2];

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/modules/custom-module-manager.js

@@ -3,6 +3,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { execSync } = require('node:child_process');
 const prompts = require('../prompts');
+const { gitEnv } = require('./git-env');
 
 function quoteCustomRef(ref) {
   if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
@@ -418,7 +419,7 @@ class CustomModuleManager {
         execSync('git fetch origin --depth 1', {
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
         });
         if (effectiveVersion) {
           // Fetch the ref as either a tag or a branch — `origin <ref>` works
@@ -427,11 +428,12 @@ class CustomModuleManager {
           execSync(`git fetch --depth 1 origin ${quoteCustomRef(effectiveVersion)} --no-tags`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git checkout --quiet FETCH_HEAD`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         } else {
           // Resolve the default branch (origin/HEAD) and fetch it explicitly.
@@ -442,6 +444,7 @@ class CustomModuleManager {
             defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD --short', {
               cwd: repoCacheDir,
               stdio: 'pipe',
+              env: gitEnv(),
             })
               .toString()
               .trim()
@@ -452,11 +455,12 @@ class CustomModuleManager {
           execSync(`git fetch --depth 1 origin ${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git reset --hard origin/${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         }
         fetchSpinner.stop(`Updated ${displayName}`);
@@ -477,12 +481,12 @@ class CustomModuleManager {
         if (effectiveVersion) {
           execSync(`git clone --depth 1 --branch ${quoteCustomRef(effectiveVersion)} "${parsed.cloneUrl}" "${repoCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         }
         fetchSpinner.stop(`Cloned ${displayName}`);
@@ -496,7 +500,7 @@ class CustomModuleManager {
     // Record the resolved SHA for the manifest writer.
     let resolvedSha = null;
     try {
-      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe' }).toString().trim();
+      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
     } catch {
       // swallow — a non-git repo (local path) wouldn't reach here anyway
     }
@@ -508,6 +512,7 @@ class CustomModuleManager {
         const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
           cwd: repoCacheDir,
           stdio: 'pipe',
+          env: gitEnv(),
         })
           .toString()
           .trim();
@@ -558,6 +563,7 @@ class CustomModuleManager {
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
           timeout: 120_000,
+          env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
         });
         installSpinner.stop(`Installed dependencies for ${displayName}`);
       } catch (error_) {

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

@@ -5,6 +5,7 @@ const { execSync } = require('node:child_process');
 const yaml = require('yaml');
 const prompts = require('../prompts');
 const { resolveChannel, tagExists, parseGitHubRepo } = require('./channel-resolver');
+const { gitEnv } = require('./git-env');
 const { decideChannelForModule } = require('./channel-plan');
 const { getProjectRoot } = require('../project-root');
 
@@ -370,33 +371,34 @@ class ExternalModuleManager {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
-        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
 
         if (resolved.channel === 'next') {
           execSync('git fetch origin --depth 1', {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync('git reset --hard origin/HEAD', {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           // stable or pinned — fetch the specific tag and check it out.
           execSync(`git fetch --depth 1 origin tag ${quoteShell(resolved.ref)} --no-tags`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git checkout --quiet FETCH_HEAD`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         }
 
-        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
         if (currentSha !== newSha) needsDependencyInstall = true;
       } catch {
@@ -415,12 +417,12 @@ class ExternalModuleManager {
         if (resolved.channel === 'next') {
           execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           execSync(`git clone --depth 1 --branch ${quoteShell(resolved.ref)} "${moduleInfo.url}" "${moduleCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         }
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
@@ -431,7 +433,7 @@ class ExternalModuleManager {
     }
 
     // Record resolution (channel + tag + SHA) for the manifest writer to pick up.
-    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
     ExternalModuleManager._resolutions.set(moduleCode, {
       channel: resolved.channel,
       version: resolved.version,
@@ -459,6 +461,7 @@ class ExternalModuleManager {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: 120_000, // 2 minute timeout
+            env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
           });
           installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
         } catch (error) {
@@ -485,6 +488,7 @@ class ExternalModuleManager {
               cwd: moduleCacheDir,
               stdio: ['ignore', 'pipe', 'pipe'],
               timeout: 120_000, // 2 minute timeout
+              env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
             });
             installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
           } catch (error) {

package/tools/installer/modules/git-env.js

@@ -0,0 +1,47 @@
+/**
+ * Sanitized environment for spawning git subprocesses.
+ *
+ * When the installer runs inside a git hook (e.g. `npm test` from a
+ * pre-commit hook), git exports repo-targeting variables — GIT_DIR,
+ * GIT_INDEX_FILE, GIT_WORK_TREE, etc. — into the hook's environment. A
+ * spawned `git` inherits them and silently operates on the hook's repository
+ * instead of the cwd passed to execSync (GIT_DIR overrides directory
+ * discovery, and the cwd then becomes its work tree). In a worktree checkout
+ * this let a cache refresh shallow-fetch and hard-reset the developer's own
+ * repo. Strip these variables so cache-directory git commands can only ever
+ * act on the repository at their cwd.
+ */
+
+const REPO_TARGETING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_PREFIX',
+  'GIT_NAMESPACE',
+  // `git -c key=val` exports its overrides to hook subprocesses through these;
+  // a core.worktree override can retarget the work tree just like GIT_WORK_TREE.
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_CONFIG_COUNT',
+];
+
+// GIT_CONFIG_KEY_0 / GIT_CONFIG_VALUE_0 ... — the enumerated form of the same mechanism.
+const CONFIG_PAIR_VAR = /^GIT_CONFIG_(KEY|VALUE)_\d+$/;
+
+/**
+ * Build the environment for a git child process.
+ * @param {Object} [extra] - Additional variables to set (e.g. GIT_TERMINAL_PROMPT)
+ * @returns {Object} process.env minus repo-targeting GIT_* vars, plus extras
+ */
+function gitEnv(extra = {}) {
+  const env = { ...process.env, ...extra };
+  for (const name of REPO_TARGETING_VARS) delete env[name];
+  for (const name of Object.keys(env)) {
+    if (CONFIG_PAIR_VAR.test(name)) delete env[name];
+  }
+  return env;
+}
+
+module.exports = { gitEnv };

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

@@ -922,7 +922,7 @@ class OfficialModules {
 
     // Fallback: legacy per-module config.yaml files (pre-v6 installations).
     const entries = await fs.readdir(bmadDir, { withFileTypes: true });
-    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom']);
+    const nonModuleDirs = new Set(['_config', '_memory', 'memory', 'docs', 'scripts', 'custom', 'render']);
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (nonModuleDirs.has(entry.name)) {