bmad-method 6.10.1-next.8 → 6.11.0

package/src/scripts/resolve_customization.py

@@ -1,177 +1,42 @@
 #!/usr/bin/env python3
-"""
-Resolve customization for a BMad skill using three-layer TOML merge.
-
-Reads customization from three layers (highest priority first):
-  1. {project-root}/_bmad/custom/{name}.user.toml  (personal, gitignored)
-  2. {project-root}/_bmad/custom/{name}.toml        (team/org, committed)
-  3. {skill-root}/customize.toml                    (skill defaults)
-
-Skill name is derived from the basename of the skill directory.
-
-Outputs merged JSON to stdout. Errors go to stderr.
-
-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
-  - Tables: deep merge (recursively apply these rules)
-  - Arrays of tables where every item shares the *same* identifier
-    field (every item has `code`, or every item has `id`):
-    merge by that key (matching keys replace, new keys append)
-  - All other arrays — including arrays where only some items have
-    `code` or `id`, or where items mix the two keys:
-    append (base items followed by override items)
-
-No removal mechanism — overrides cannot delete base items. To suppress
-a default, fork the skill or override the item by code with a no-op
-description/prompt.
-"""
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve a skill's default, team, and user TOML customization layers."""
 
 import argparse
 import json
 import sys
 from pathlib import Path
 
+# Installed scripts are consumer files, not a location for interpreter caches.
+sys.dont_write_bytecode = True
+
 try:
-    import tomllib
-except ImportError:
-    sys.stderr.write(
-        "error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
-        "Install a newer Python or run the resolution manually per the\n"
-        "fallback instructions in the skill's SKILL.md.\n"
-    )
-    sys.exit(3)
+    from config_utils import ConfigError, load_customization
+except ModuleNotFoundError as error:
+    if error.name != "tomllib":
+        raise
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib` not found).\n")
+    raise SystemExit(3) from None
 
 
 _MISSING = object()
-_KEYED_MERGE_FIELDS = ("code", "id")
 
 
-def find_project_root(start: Path):
+def find_project_root(start: Path) -> Path | None:
     current = start.resolve()
     while True:
         if (current / "_bmad").exists() or (current / ".git").exists():
             return current
-        parent = current.parent
-        if parent == current:
+        if current.parent == current:
             return None
-        current = parent
-
-
-def load_toml(file_path: Path, required: bool = False) -> dict:
-    if not file_path.exists():
-        if required:
-            sys.stderr.write(f"error: required customization file not found: {file_path}\n")
-            sys.exit(1)
-        return {}
-    try:
-        with file_path.open("rb") as f:
-            parsed = tomllib.load(f)
-        if not isinstance(parsed, dict):
-            if required:
-                sys.stderr.write(f"error: {file_path} did not parse to a table\n")
-                sys.exit(1)
-            return {}
-        return parsed
-    except tomllib.TOMLDecodeError as error:
-        level = "error" if required else "warning"
-        sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
-        if required:
-            sys.exit(1)
-        return {}
-    except OSError as error:
-        level = "error" if required else "warning"
-        sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
-        if required:
-            sys.exit(1)
-        return {}
-
-
-def _detect_keyed_merge_field(items):
-    """Return 'code' or 'id' if every table item carries that *same* field.
-
-    All items must share the same identifier (all `code`, or all `id`).
-    Mixed arrays — where some items use `code` and others use `id` —
-    return None and fall through to append semantics. This is intentional:
-    mixing identifier keys within one array is a schema smell, and
-    append-fallback is safer than guessing which key should merge.
-    """
-    if not items or not all(isinstance(item, dict) for item in items):
-        return None
-    for candidate in _KEYED_MERGE_FIELDS:
-        if all(item.get(candidate) is not None for item in items):
-            return candidate
-    return None
-
-
-def _merge_by_key(base, override, key_name):
-    result = []
-    index_by_key = {}
-
-    for item in base:
-        if not isinstance(item, dict):
-            continue
-        if item.get(key_name) is not None:
-            index_by_key[item[key_name]] = len(result)
-        result.append(dict(item))
-
-    for item in override:
-        if not isinstance(item, dict):
-            result.append(item)
-            continue
-        key = item.get(key_name)
-        if key is not None and key in index_by_key:
-            result[index_by_key[key]] = dict(item)
-        else:
-            if key is not None:
-                index_by_key[key] = len(result)
-            result.append(dict(item))
-
-    return result
-
-
-def _merge_arrays(base, override):
-    """Shape-aware array merge. Base + override combined tables may opt into
-    keyed merge if every item has `code` or `id`. Otherwise: append."""
-    base_arr = base if isinstance(base, list) else []
-    override_arr = override if isinstance(override, list) else []
-    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
-    if keyed_field:
-        return _merge_by_key(base_arr, override_arr, keyed_field)
-    return base_arr + override_arr
-
-
-def deep_merge(base, override):
-    """Recursively merge override into base using structural rules.
-    - Table + table: deep merge
-    - Array + array: shape-aware (keyed merge if all items have code/id, else append)
-    - Anything else: override wins
-    """
-    if isinstance(base, dict) and isinstance(override, dict):
-        result = dict(base)
-        for key, over_val in override.items():
-            if key in result:
-                result[key] = deep_merge(result[key], over_val)
-            else:
-                result[key] = over_val
-        return result
-    if isinstance(base, list) and isinstance(override, list):
-        return _merge_arrays(base, override)
-    return override
+        current = current.parent
 
 
 def extract_key(data, dotted_key: str):
-    parts = dotted_key.split(".")
     current = data
-    for part in parts:
+    for part in dotted_key.split("."):
         if isinstance(current, dict) and part in current:
             current = current[part]
         else:
@@ -179,62 +44,56 @@ def extract_key(data, dotted_key: str):
     return current
 
 
-def write_json_stdout(output):
-    """Write JSON as UTF-8 so Windows cp1252 stdout can carry emoji icons."""
+def write_json_stdout(output) -> None:
     reconfigure = getattr(sys.stdout, "reconfigure", None)
     if reconfigure is not None:
         reconfigure(encoding="utf-8")
     sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
 
 
-def main():
+def main() -> int:
     parser = argparse.ArgumentParser(
-        description="Resolve customization for a BMad skill using three-layer TOML merge.",
-        add_help=True,
+        description="Resolve skill customization using three-layer TOML merge."
+    )
+    parser.add_argument(
+        "--skill", "-s", required=True, help="Absolute path to the skill directory"
     )
     parser.add_argument(
-        "--skill", "-s", required=True,
-        help="Absolute path to the skill directory (must contain customize.toml)",
+        "--project-root",
+        "-p",
+        help="Explicit project root containing _bmad/ (recommended)",
     )
     parser.add_argument(
-        "--key", "-k", action="append", default=[],
+        "--key",
+        "-k",
+        action="append",
+        default=[],
         help="Dotted field path to resolve (repeatable). Omit for full dump.",
     )
     args = parser.parse_args()
 
     skill_dir = Path(args.skill).resolve()
-    skill_name = skill_dir.name
-    defaults_path = skill_dir / "customize.toml"
-
-    defaults = load_toml(defaults_path, required=True)
-
-    # Prefer the project that contains this skill. Only fall back to cwd if
-    # the skill isn't inside a recognizable project tree (unusual but possible
-    # for standalone skills invoked directly). Using cwd first is unsafe when
-    # an ancestor of cwd happens to have a stray _bmad/ from another project.
-    project_root = find_project_root(skill_dir) or find_project_root(Path.cwd())
-
-    team = {}
-    user = {}
-    if project_root:
-        custom_dir = project_root / "_bmad" / "custom"
-        team = load_toml(custom_dir / f"{skill_name}.toml")
-        user = load_toml(custom_dir / f"{skill_name}.user.toml")
-
-    merged = deep_merge(defaults, team)
-    merged = deep_merge(merged, user)
+    project_root = (
+        Path(args.project_root).resolve()
+        if args.project_root
+        else find_project_root(skill_dir) or find_project_root(Path.cwd())
+    )
+    try:
+        merged = load_customization(project_root, skill_dir)
+    except ConfigError as error:
+        sys.stderr.write(f"error: {error}\n")
+        return 1
 
+    output = merged
     if args.key:
         output = {}
         for key in args.key:
             value = extract_key(merged, key)
             if value is not _MISSING:
                 output[key] = value
-    else:
-        output = merged
-
     write_json_stdout(output)
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())

package/src/scripts/tests/test_config_utils.py

@@ -0,0 +1,85 @@
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from config_utils import (  # noqa: E402
+    ConfigError,
+    load_central_config,
+    load_customization,
+    load_toml,
+    structural_merge,
+)
+
+
+class ConfigUtilsTests(unittest.TestCase):
+    def test_structural_merge_recurses_appends_and_replaces_keyed_tables(self):
+        base = {
+            "nested": {"keep": True, "replace": "old"},
+            "plain": ["base"],
+            "items": [{"id": "one", "value": "old"}],
+        }
+        override = {
+            "nested": {"replace": "new"},
+            "plain": ["override"],
+            "items": [
+                {"id": "one", "value": "new"},
+                {"id": "two", "value": "added"},
+            ],
+        }
+
+        merged = structural_merge(base, override)
+
+        self.assertEqual(merged["nested"], {"keep": True, "replace": "new"})
+        self.assertEqual(merged["plain"], ["base", "override"])
+        self.assertEqual(
+            merged["items"],
+            [
+                {"id": "one", "value": "new"},
+                {"id": "two", "value": "added"},
+            ],
+        )
+
+    def test_non_string_keyed_identifier_is_rejected(self):
+        with self.assertRaisesRegex(ConfigError, "identifier `id` must be a string"):
+            structural_merge([{"id": "valid"}], [{"id": 42}])
+
+    def test_present_malformed_optional_layer_is_rejected(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "optional.toml"
+            path.write_text("[broken\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(ConfigError, "failed to parse"):
+                load_toml(path)
+
+    def test_missing_optional_layer_is_empty(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            path = Path(temp_dir) / "optional.toml"
+
+            self.assertEqual(load_toml(path), {})
+
+    def test_filesystem_layer_precedence(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            bmad = root / "_bmad"
+            custom = bmad / "custom"
+            skill = bmad / "bmm" / "sample-skill"
+            custom.mkdir(parents=True)
+            skill.mkdir(parents=True)
+            (bmad / "config.toml").write_text('[value]\norder = "base-team"\n', encoding="utf-8")
+            (bmad / "config.user.toml").write_text('[value]\norder = "base-user"\n', encoding="utf-8")
+            (custom / "config.toml").write_text('[value]\norder = "custom-team"\n', encoding="utf-8")
+            (custom / "config.user.toml").write_text('[value]\norder = "custom-user"\n', encoding="utf-8")
+            (skill / "customize.toml").write_text('[value]\norder = "default"\n', encoding="utf-8")
+            (custom / "sample-skill.toml").write_text('[value]\norder = "team"\n', encoding="utf-8")
+            (custom / "sample-skill.user.toml").write_text('[value]\norder = "user"\n', encoding="utf-8")
+
+            self.assertEqual(load_central_config(root)["value"]["order"], "custom-user")
+            self.assertEqual(load_customization(root, skill)["value"]["order"], "user")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/scripts/tests/test_resolve_config.py

@@ -0,0 +1,89 @@
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "resolve_config.py"
+
+
+class ResolveConfigCliTests(unittest.TestCase):
+    def test_missing_tomllib_exits_with_actionable_version_error(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            scripts = Path(temp_dir)
+            shutil.copy2(SCRIPT, scripts / SCRIPT.name)
+            shutil.copy2(SCRIPT.parent / "config_utils.py", scripts / "config_utils.py")
+            (scripts / "tomllib.py").write_text(
+                'raise ModuleNotFoundError("No module named tomllib", name="tomllib")\n',
+                encoding="utf-8",
+            )
+
+            result = subprocess.run(
+                [sys.executable, str(scripts / SCRIPT.name), "--help"],
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 3)
+            self.assertEqual(
+                result.stderr,
+                "error: Python 3.11+ is required (stdlib `tomllib` not found).\n",
+            )
+            self.assertNotIn("Traceback", result.stderr)
+
+    def test_full_and_repeated_key_output_follow_layer_precedence(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            custom = root / "_bmad" / "custom"
+            custom.mkdir(parents=True)
+            (root / "_bmad" / "config.toml").write_text(
+                '[core]\nname = "base"\nkeep = "yes"\n', encoding="utf-8"
+            )
+            (root / "_bmad" / "config.user.toml").write_text(
+                '[core]\nname = "base-user"\n', encoding="utf-8"
+            )
+            (custom / "config.toml").write_text(
+                '[core]\nname = "team"\n', encoding="utf-8"
+            )
+            (custom / "config.user.toml").write_text(
+                '[core]\nname = "user"\n', encoding="utf-8"
+            )
+
+            full = self._run(root)
+            self.assertEqual(full.returncode, 0, msg=full.stderr)
+            self.assertEqual(json.loads(full.stdout)["core"], {"name": "user", "keep": "yes"})
+
+            keyed = self._run(root, "--key", "core.name", "--key", "missing")
+            self.assertEqual(keyed.returncode, 0, msg=keyed.stderr)
+            self.assertEqual(json.loads(keyed.stdout), {"core.name": "user"})
+
+    def test_malformed_present_layer_fails(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            custom = root / "_bmad" / "custom"
+            custom.mkdir(parents=True)
+            (root / "_bmad" / "config.toml").write_text("[core]\nvalid = true\n", encoding="utf-8")
+            (custom / "config.toml").write_text("[broken\n", encoding="utf-8")
+
+            result = self._run(root)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("failed to parse", result.stderr)
+
+    @staticmethod
+    def _run(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [sys.executable, str(SCRIPT), "--project-root", str(root), *args],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/scripts/tests/test_resolve_customization.py

@@ -1,5 +1,6 @@
 import json
 import os
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -11,6 +12,31 @@ SCRIPT = Path(__file__).resolve().parents[1] / "resolve_customization.py"
 
 
 class ResolveCustomizationStdoutTests(unittest.TestCase):
+    def test_missing_tomllib_exits_with_actionable_version_error(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            scripts = Path(temp_dir)
+            shutil.copy2(SCRIPT, scripts / SCRIPT.name)
+            shutil.copy2(SCRIPT.parent / "config_utils.py", scripts / "config_utils.py")
+            (scripts / "tomllib.py").write_text(
+                'raise ModuleNotFoundError("No module named tomllib", name="tomllib")\n',
+                encoding="utf-8",
+            )
+
+            result = subprocess.run(
+                [sys.executable, str(scripts / SCRIPT.name), "--help"],
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 3)
+            self.assertEqual(
+                result.stderr,
+                "error: Python 3.11+ is required (stdlib `tomllib` not found).\n",
+            )
+            self.assertNotIn("Traceback", result.stderr)
+
     def test_writes_emoji_json_when_stdout_encoding_is_cp1252(self):
         with tempfile.TemporaryDirectory() as temp_dir:
             skill_dir = Path(temp_dir) / "emoji-agent"
@@ -33,6 +59,7 @@ class ResolveCustomizationStdoutTests(unittest.TestCase):
                 ],
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
+                cwd=temp_dir,
                 env=env,
                 check=False,
             )

package/tools/installer/cli-utils.js

@@ -29,9 +29,13 @@ const CLIUtils = {
 
     const logoLines = termWidth >= 95 ? logoWide : logoNarrow;
     const logo = logoLines.map((line) => color.blue(line)).join('\n');
-    const tagline = color.white('    Build More, Architect Dreams\n    © BMad Code');
+    // The wordmark supplies "BMad Method", so the lines below read as its
+    // tagline, then its positioning, then the company credit.
+    const tagline = color.white('    Agile Ai Driven Development');
+    const slogan = color.dim('    the agile way to do AiDD');
+    const credit = color.dim('    Build More, Architect Dreams · © BMad Code');
 
-    await prompts.box(`${logo}\n${tagline}`, '', {
+    await prompts.box(`${logo}\n${tagline}\n${slogan}\n${credit}`, '', {
       contentAlign: 'center',
       rounded: true,
       formatBorder: color.blue,

package/tools/installer/core/installer.js

@@ -663,8 +663,7 @@ class Installer {
    * Excludes dev-only tests and Python caches so they don't ship to users.
    * Wipes the destination first so files removed or renamed in source
    * don't linger and get recorded as installed. Also seeds
-   * _bmad/custom/.gitignore on fresh installs so *.user.toml overrides
-   * stay out of version control.
+   * gitignore files for personal overrides and generated render snapshots.
    */
   async _installSharedScripts(paths) {
     const srcScriptsDir = path.join(paths.srcDir, 'src', 'scripts');
@@ -687,6 +686,14 @@ class Installer {
       await fs.writeFile(customGitignore, '*.user.toml\n', 'utf8');
       this.installedFiles.add(customGitignore);
     }
+
+    const renderDir = path.join(paths.bmadDir, 'render');
+    const renderGitignore = path.join(renderDir, '.gitignore');
+    if (!(await fs.pathExists(renderGitignore))) {
+      await fs.ensureDir(renderDir);
+      await fs.writeFile(renderGitignore, '*\n!.gitignore\n', 'utf8');
+    }
+    this.installedFiles.add(renderGitignore);
   }
 
   async _trackFilesRecursive(dir) {
@@ -870,8 +877,9 @@ class Installer {
           const fullPath = path.join(dir, entry.name);
 
           if (entry.isDirectory()) {
-            // Skip certain directories
-            if (entry.name === 'node_modules' || entry.name === '.git') {
+            const relativeDir = path.relative(bmadDir, fullPath);
+            // Render snapshots are generated state, not user-authored customization.
+            if (entry.name === 'node_modules' || entry.name === '.git' || relativeDir === 'render') {
               continue;
             }
             await scanDirectory(fullPath);
@@ -959,7 +967,7 @@ class Installer {
 
     // Get all installed module directories
     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']);
     const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
 
     // Generate config.yaml for each installed module
@@ -1056,7 +1064,7 @@ class Installer {
 
     // Get all installed module directories
     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']);
     const installedModules = entries.filter((entry) => entry.isDirectory() && !nonModuleDirs.has(entry.name)).map((entry) => entry.name);
 
     // Add core module to scan (it's installed at root level as _config, but we check src/core-skills)
@@ -1237,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/manifest-generator.js

@@ -753,7 +753,7 @@ class ManifestGenerator {
 
       for (const entry of entries) {
         // Skip if not a directory or is a special directory
-        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '_config') {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '_config' || entry.name === 'render') {
           continue;
         }