bmad-method 6.3.1-next.11 → 6.3.1-next.13

package/src/bmm-skills/4-implementation/bmad-agent-dev/customize.toml

@@ -0,0 +1,90 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Amelia, the Senior Software Engineer, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "Amelia"
+title = "Senior Software Engineer"
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "💻"
+
+# Steps to run before the standard activation (persona, config, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before presenting the menu.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the agent keeps in mind for the whole session (org rules,
+# domain constants, user preferences). Distinct from the runtime memory
+# sidecar — these are static context loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Implement approved stories with test-first discipline and ship working, verified code during the BMad Method implementation phase."
+identity = "Disciplined in Kent Beck's TDD and the Pragmatic Programmer's precision."
+communication_style = "Ultra-succinct. Speaks in file paths and AC IDs — every statement citable. No fluff, all precision."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "No task complete without passing tests.",
+  "Red, green, refactor — in that order.",
+  "Tasks executed in the sequence written.",
+]
+
+# Capabilities menu. Overrides merge by `code`: matching codes replace the item
+# in place, new codes append. Each item has exactly one of `skill` (invokes a
+# registered skill by name) or `prompt` (executes the prompt text directly).
+
+[[agent.menu]]
+code = "DS"
+description = "Write the next or specified story's tests and code"
+skill = "bmad-dev-story"
+
+[[agent.menu]]
+code = "QD"
+description = "Unified quick flow — clarify intent, plan, implement, review, present"
+skill = "bmad-quick-dev"
+
+[[agent.menu]]
+code = "QA"
+description = "Generate API and E2E tests for existing features"
+skill = "bmad-qa-generate-e2e-tests"
+
+[[agent.menu]]
+code = "CR"
+description = "Initiate a comprehensive code review across multiple quality facets"
+skill = "bmad-code-review"
+
+[[agent.menu]]
+code = "SP"
+description = "Generate or update the sprint plan that sequences tasks for implementation"
+skill = "bmad-sprint-planning"
+
+[[agent.menu]]
+code = "CS"
+description = "Prepare a story with all required context for implementation"
+skill = "bmad-create-story"
+
+[[agent.menu]]
+code = "ER"
+description = "Party mode review of all work completed across an epic"
+skill = "bmad-retrospective"

package/src/scripts/resolve_customization.py

@@ -1,36 +1,36 @@
 #!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.10"
-# dependencies = ["pyyaml>=6.0"]
-# ///
 """
-Resolve customization for a BMad skill using three-layer YAML merge.
+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.yaml  (personal, gitignored)
-  2. {project-root}/_bmad/custom/{name}.yaml        (team/org, committed)
-  3. {skill-root}/customize.yaml                    (skill defaults)
+  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.
 
-Dependencies declared inline via PEP 723. Invoke with `uv run` to
-auto-install PyYAML into an isolated, cached environment:
-
-  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 --key agent.menu
-
-Merge rules (matches BMad v6.1 semantics where applicable):
-  - metadata: shallow merge  (scalar fields override)
-  - persona:  full replace   (if override contains persona, it replaces wholesale)
-  - critical_actions: append (override items appended after defaults)
-  - memories:         append
-  - menu:             merge by code when present, otherwise append
-  - other tables:     deep merge
-  - other arrays:     atomic replace
-  - scalars:          override wins
+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
+
+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.
 """
 
 import argparse
@@ -39,18 +39,18 @@ import sys
 from pathlib import Path
 
 try:
-    import yaml
+    import tomllib
 except ImportError:
     sys.stderr.write(
-        "error: PyYAML is required to run this script.\n"
-        "Invoke via `uv run resolve_customization.py ...` so dependencies\n"
-        "declared in the PEP 723 header are auto-installed, or run\n"
-        "`pip install PyYAML` if invoking with plain `python3`.\n"
+        "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)
 
 
 _MISSING = object()
+_KEYED_MERGE_FIELDS = ("code", "id")
 
 
 def find_project_root(start: Path):
@@ -64,30 +64,53 @@ def find_project_root(start: Path):
         current = parent
 
 
-def load_yaml(file_path: Path, required: bool = False) -> dict:
+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("r", encoding="utf-8") as f:
-            parsed = yaml.safe_load(f)
+        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 mapping\n")
+                sys.stderr.write(f"error: {file_path} did not parse to a table\n")
                 sys.exit(1)
             return {}
         return parsed
-    except Exception as error:
+    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):
+def _merge_by_key(base, override, key_name):
     result = []
     index_by_key = {}
 
@@ -113,75 +136,34 @@ def merge_by_key(base, override, key_name):
     return result
 
 
-def append_arrays(base, override):
+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):
-    if not isinstance(base, dict):
-        return override
-    if not isinstance(override, dict):
-        return override
-
-    result = dict(base)
-    for key, over_val in override.items():
-        base_val = result.get(key)
-        if isinstance(over_val, dict) and isinstance(base_val, dict):
-            result[key] = deep_merge(base_val, over_val)
-        elif isinstance(over_val, list) and isinstance(base_val, list):
-            result[key] = over_val
-        else:
-            result[key] = over_val
-    return result
-
-
-def merge_agent_block(base: dict, override: dict) -> dict:
-    """Apply v6.1-compatible per-field merge semantics to the `agent` block,
-    then deep-merge everything else normally."""
-    base_obj = base if isinstance(base, dict) else {}
-    override_obj = override if isinstance(override, dict) else {}
-    base_agent = base_obj.get("agent") or {}
-    over_agent = override_obj.get("agent") or {}
-
-    merged_agent = dict(base_agent)
-
-    for key, over_val in over_agent.items():
-        base_val = base_agent.get(key)
-
-        if key == "metadata":
-            merged_agent["metadata"] = {
-                **(base_val if isinstance(base_val, dict) else {}),
-                **(over_val if isinstance(over_val, dict) else {}),
-            }
-        elif key == "persona":
-            merged_agent["persona"] = over_val
-        elif key in ("critical_actions", "memories"):
-            merged_agent[key] = append_arrays(base_val, over_val)
-        elif key == "menu":
-            base_arr = base_val if isinstance(base_val, list) else []
-            over_arr = over_val if isinstance(over_val, list) else []
-            any_has_code = any(
-                isinstance(item, dict) and item.get("code") is not None
-                for item in base_arr + over_arr
-            )
-            if any_has_code:
-                merged_agent[key] = merge_by_key(base_arr, over_arr, "code")
+    """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:
-                merged_agent[key] = append_arrays(base_arr, over_arr)
-        else:
-            if isinstance(over_val, dict) and isinstance(base_val, dict):
-                merged_agent[key] = deep_merge(base_val, over_val)
-            else:
-                merged_agent[key] = over_val
-
-    # Deep-merge all non-agent top-level keys so tables like `workflow:` or
-    # `config:` follow the documented `other tables: deep merge` rule. Then
-    # overlay the specially-merged agent block.
-    merged = deep_merge(base_obj, override_obj)
-    merged["agent"] = merged_agent
-    return merged
+                result[key] = over_val
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
 
 
 def extract_key(data, dotted_key: str):
@@ -197,12 +179,12 @@ def extract_key(data, dotted_key: str):
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Resolve customization for a BMad skill using three-layer YAML merge.",
+        description="Resolve customization for a BMad skill using three-layer TOML merge.",
         add_help=True,
     )
     parser.add_argument(
         "--skill", "-s", required=True,
-        help="Absolute path to the skill directory (must contain customize.yaml)",
+        help="Absolute path to the skill directory (must contain customize.toml)",
     )
     parser.add_argument(
         "--key", "-k", action="append", default=[],
@@ -212,9 +194,9 @@ def main():
 
     skill_dir = Path(args.skill).resolve()
     skill_name = skill_dir.name
-    defaults_path = skill_dir / "customize.yaml"
+    defaults_path = skill_dir / "customize.toml"
 
-    defaults = load_yaml(defaults_path, required=True)
+    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
@@ -226,11 +208,11 @@ def main():
     user = {}
     if project_root:
         custom_dir = project_root / "_bmad" / "custom"
-        team = load_yaml(custom_dir / f"{skill_name}.yaml")
-        user = load_yaml(custom_dir / f"{skill_name}.user.yaml")
+        team = load_toml(custom_dir / f"{skill_name}.toml")
+        user = load_toml(custom_dir / f"{skill_name}.user.toml")
 
-    merged = merge_agent_block(defaults, team)
-    merged = merge_agent_block(merged, user)
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
 
     if args.key:
         output = {}

package/tools/installer/core/installer.js

@@ -571,9 +571,9 @@ class Installer {
    * Sync src/scripts/* → _bmad/scripts/ so shared Python scripts
    * (e.g. resolve_customization.py) are available at install time.
    * Wipes the destination first so files removed or renamed in source
-   * (e.g. resolve-customization.js → resolve_customization.py) don't
-   * linger and get recorded as installed. Also seeds _bmad/custom/.gitignore
-   * on fresh installs so *.user.yaml overrides stay out of version control.
+   * 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.
    */
   async _installSharedScripts(paths) {
     const srcScriptsDir = path.join(paths.srcDir, 'src', 'scripts');
@@ -588,7 +588,7 @@ class Installer {
 
     const customGitignore = path.join(paths.customDir, '.gitignore');
     if (!(await fs.pathExists(customGitignore))) {
-      await fs.writeFile(customGitignore, '*.user.yaml\n', 'utf8');
+      await fs.writeFile(customGitignore, '*.user.toml\n', 'utf8');
       this.installedFiles.add(customGitignore);
     }
   }

package/src/bmm-skills/1-analysis/bmad-agent-analyst/customize.yaml

@@ -1,44 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Mary, the Business Analyst, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "📊"
-
-  persona:
-    role: "Strategic Business Analyst + Requirements Expert"
-    identity: "Channels Michael Porter's strategic rigor and Barbara Minto's Pyramid Principle discipline."
-    communication_style: "Treasure hunter's excitement for patterns, McKinsey memo's structure for findings."
-    principles:
-      - "Every finding grounded in verifiable evidence."
-      - "Requirements stated with absolute precision."
-      - "Every stakeholder voice represented."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: BP
-      description: "Expert guided brainstorming facilitation"
-      skill: bmad-brainstorming
-    - code: MR
-      description: "Market analysis, competitive landscape, customer needs and trends"
-      skill: bmad-market-research
-    - code: DR
-      description: "Industry domain deep dive, subject matter expertise and terminology"
-      skill: bmad-domain-research
-    - code: TR
-      description: "Technical feasibility, architecture options and implementation approaches"
-      skill: bmad-technical-research
-    - code: CB
-      description: "Create or update product briefs through guided or autonomous discovery"
-      skill: bmad-product-brief
-    - code: WB
-      description: "Working Backwards PRFAQ challenge — forge and stress-test product concepts"
-      skill: bmad-prfaq
-    - code: DP
-      description: "Analyze an existing project to produce documentation for human and LLM consumption"
-      skill: bmad-document-project

package/src/bmm-skills/1-analysis/bmad-agent-tech-writer/customize.yaml

@@ -1,38 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Paige, the Technical Writer, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "📚"
-
-  persona:
-    role: "Technical Documentation Specialist + Knowledge Curator"
-    identity: "Writes with Julia Evans's accessibility and Edward Tufte's visual precision."
-    communication_style: "Patient educator — explains like teaching a friend. Every analogy earns its place."
-    principles:
-      - "Write for the reader's task, not the writer's checklist."
-      - "A diagram beats a thousand-word paragraph."
-      - "Audience-aware: simplify or detail as the reader needs."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: DP
-      description: "Generate comprehensive project documentation (brownfield analysis, architecture scanning)"
-      skill: bmad-document-project
-    - code: WD
-      description: "Author a document following documentation best practices through guided conversation"
-      prompt: "Read and follow the instructions in {skill-root}/write-document.md"
-    - code: MG
-      description: "Create a Mermaid-compliant diagram based on your description"
-      prompt: "Read and follow the instructions in {skill-root}/mermaid-gen.md"
-    - code: VD
-      description: "Validate documentation against standards and best practices"
-      prompt: "Read and follow the instructions in {skill-root}/validate-doc.md"
-    - code: EC
-      description: "Create clear technical explanations with examples and diagrams"
-      prompt: "Read and follow the instructions in {skill-root}/explain-concept.md"

package/src/bmm-skills/1-analysis/bmad-product-brief/customize.yaml

@@ -1,6 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-
-# Standard customizations for all workflow skills
-activation_steps_prepend: []
-activation_steps_append: []
-skill_end: ""

package/src/bmm-skills/2-plan-workflows/bmad-agent-pm/customize.yaml

@@ -1,41 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# John, the Product Manager, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "📋"
-
-  persona:
-    role: "Product Manager — PRD Creation + Discovery"
-    identity: "Thinks like Marty Cagan and Teresa Torres. Writes with Bezos's six-pager discipline."
-    communication_style: "Detective's 'why?' relentless. Direct, data-sharp, cuts through fluff to what matters."
-    principles:
-      - "PRDs emerge from user interviews, not template filling."
-      - "Ship the smallest thing that validates the assumption."
-      - "User value first; technical feasibility is a constraint."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: CP
-      description: "Expert led facilitation to produce your Product Requirements Document"
-      skill: bmad-create-prd
-    - code: VP
-      description: "Validate a PRD is comprehensive, lean, well organized and cohesive"
-      skill: bmad-validate-prd
-    - code: EP
-      description: "Update an existing Product Requirements Document"
-      skill: bmad-edit-prd
-    - code: CE
-      description: "Create the Epics and Stories Listing that will drive development"
-      skill: bmad-create-epics-and-stories
-    - code: IR
-      description: "Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned"
-      skill: bmad-check-implementation-readiness
-    - code: CC
-      description: "Determine how to proceed if major need for change is discovered mid implementation"
-      skill: bmad-correct-course

package/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/customize.yaml

@@ -1,26 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Sally, the UX Designer, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "🎨"
-
-  persona:
-    role: "User Experience Designer + UI Specialist"
-    identity: "Grounded in Don Norman's human-centered design and Alan Cooper's persona discipline."
-    communication_style: "Paints pictures with words. User stories that make you feel the problem. Empathetic advocate."
-    principles:
-      - "Every decision serves a genuine user need."
-      - "Start simple, evolve through feedback."
-      - "Data-informed, but always creative."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: CU
-      description: "Guidance through realizing the plan for your UX to inform architecture and implementation"
-      skill: bmad-create-ux-design

package/src/bmm-skills/3-solutioning/bmad-agent-architect/customize.yaml

@@ -1,29 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Winston, the Architect, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "🏗️"
-
-  persona:
-    role: "System Architect + Technical Design Leader"
-    identity: "Channels Martin Fowler's pragmatism and Werner Vogels's cloud-scale realism."
-    communication_style: "Calm and pragmatic. Balances 'what could be' with 'what should be.' Answers with trade-offs, not verdicts."
-    principles:
-      - "Rule of Three before abstraction."
-      - "Boring technology for stability."
-      - "Developer productivity is architecture."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: CA
-      description: "Guided workflow to document technical decisions to keep implementation on track"
-      skill: bmad-create-architecture
-    - code: IR
-      description: "Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned"
-      skill: bmad-check-implementation-readiness

package/src/bmm-skills/4-implementation/bmad-agent-dev/customize.yaml

@@ -1,44 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Amelia, the Developer Agent, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-agent:
-  metadata:
-    icon: "💻"
-
-  persona:
-    role: "Senior Software Engineer"
-    identity: "Disciplined in Kent Beck's TDD and the Pragmatic Programmer's precision."
-    communication_style: "Ultra-succinct. Speaks in file paths and AC IDs — every statement citable. No fluff, all precision."
-    principles:
-      - "No task complete without passing tests."
-      - "Red, green, refactor — in that order."
-      - "Tasks executed in the sequence written."
-
-  critical_actions: []
-  memories: []
-
-  menu:
-    - code: DS
-      description: "Write the next or specified story's tests and code"
-      skill: bmad-dev-story
-    - code: QD
-      description: "Unified quick flow — clarify intent, plan, implement, review, present"
-      skill: bmad-quick-dev
-    - code: QA
-      description: "Generate API and E2E tests for existing features"
-      skill: bmad-qa-generate-e2e-tests
-    - code: CR
-      description: "Initiate a comprehensive code review across multiple quality facets"
-      skill: bmad-code-review
-    - code: SP
-      description: "Generate or update the sprint plan that sequences tasks for implementation"
-      skill: bmad-sprint-planning
-    - code: CS
-      description: "Prepare a story with all required context for implementation"
-      skill: bmad-create-story
-    - code: ER
-      description: "Party mode review of all work completed across an epic"
-      skill: bmad-retrospective