From c084ed226e48eb553386c279f72f282a7c800e55 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 19 Apr 2026 14:47:46 -0500 Subject: [PATCH] =?UTF-8?q?docs(skills):=20address=20CodeRabbit=20review?= =?UTF-8?q?=20=E2=80=94=20fallback=20rules,=20OS=20claim,=20headless=20gre?= =?UTF-8?q?eting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three fixes from PR #2284 review feedback: ## 1. Fallback merge wording (7 SKILL.md files) Every SKILL.md told the LLM to merge the three customization files "in priority order (later wins)" when the resolver fails. That reads as shallow last-write-wins — but the resolver does structural merge (scalars override, tables deep-merge, code/id-keyed arrays merge by key, other arrays append). Following the old wording manually would have silently stripped base `principles`, `persistent_facts`, and `menu` items whenever a team override was present. Expanded the fallback sentence to restate the four structural rules explicitly, matching the resolver's behavior. Applied to all 6 agents + bmad-product-brief workflow. ## 2. Python 3.11 / OS shipping claim (customize-bmad.md) The docs claimed "macOS 13+, Ubuntu 22.04+, Debian 12+, Fedora 37+ all ship 3.11 or newer." Inaccurate — Ubuntu 22.04 defaults `python3` to 3.10.6 (3.11 is a separate package), and macOS doesn't really ship Python by default anymore. Replaced with honest guidance: check `python3 --version` and note that macOS without Homebrew and Ubuntu 22.04 default to 3.10 or earlier. ## 3. Autonomous mode greeting gate (bmad-product-brief) Product-brief's activation-mode detection documents autonomous mode as "produce complete brief without interaction" — but Step 5 greeted unconditionally, adding conversational output before the headless artifact. Gated the greeting on `{mode}` != `autonomous`. ## Dismissed (replied on thread) - `.gitignore` migration from *.user.yaml to *.user.toml: YAML installer code was in reverted #2282, never released. No users affected. Same rationale as Augment's earlier thread. Validated: 254 files, 146 refs, 0 broken. test:refs 7/7, test:install 242/242. --- docs/how-to/customize-bmad.md | 2 +- src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md | 4 ++-- src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md | 4 ++-- src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md | 6 +++--- src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md | 4 ++-- .../2-plan-workflows/bmad-agent-ux-designer/SKILL.md | 4 ++-- src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md | 4 ++-- src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md | 4 ++-- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index ea05ba7ca..d0986e4e0 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -215,7 +215,7 @@ python3 {project-root}/_bmad/scripts/resolve_customization.py \ --key agent ``` -**Requirements**: Python 3.11+ (earlier versions don't include `tomllib`). No `pip install`, no `uv`, no virtualenv. macOS 13+, Ubuntu 22.04+, Debian 12+, and Fedora 37+ all ship 3.11 or newer. +**Requirements**: Python 3.11+ (earlier versions don't include `tomllib`). No `pip install`, no `uv`, no virtualenv. Check with `python3 --version` — some common platforms (macOS without Homebrew, Ubuntu 22.04) default `python3` to 3.10 or earlier even when 3.11+ is available to install separately. `--skill` points at the skill's installed directory (where `customize.toml` lives). The skill name is derived from the directory's basename, and the script looks up `_bmad/custom/{skill-name}.toml` and `{skill-name}.user.toml` automatically. diff --git a/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md b/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md index 2eba1b18f..4653171df 100644 --- a/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md @@ -22,13 +22,13 @@ You are Mary, the Business Analyst. You bring deep expertise in market research, Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md b/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md index ea642c3a2..ff6430d93 100644 --- a/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md @@ -22,13 +22,13 @@ You are Paige, the Technical Writer. You transform complex concepts into accessi Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index 8ae6c2be4..8d697259e 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -41,13 +41,13 @@ Check activation context immediately: Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` -**If the script fails**, resolve the `workflow` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps @@ -68,7 +68,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: ### Step 5: Greet the User -Greet `{user_name}` if you have not already, speaking in `{communication_language}`. +If `{mode}` is not `autonomous`, greet `{user_name}` (if you have not already), speaking in `{communication_language}`. In autonomous mode, skip the greeting — no conversational output should precede the generated artifact. ### Step 6: Execute Append Steps diff --git a/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md index a4ef415af..693072603 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md @@ -22,13 +22,13 @@ You are John, the Product Manager. You drive PRD creation through user interview Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md index 56902d3e9..cb261c3fb 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md @@ -22,13 +22,13 @@ You are Sally, the UX Designer. You translate user needs into interaction design Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md b/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md index 07bd26ca4..1650aee09 100644 --- a/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md @@ -22,13 +22,13 @@ You are Winston, the System Architect. You turn product requirements and UX into Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md b/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md index 59e5bf8a5..95a3b9594 100644 --- a/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md +++ b/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md @@ -22,13 +22,13 @@ You are Amelia, the Senior Software Engineer. You execute approved stories with Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): +**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: 1. `{skill-root}/customize.toml` — defaults 2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides 3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides -Any missing file is skipped. +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. ### Step 2: Execute Prepend Steps