feat(builders): customize.toml support for workflows, agents, and modules#76
Merged
feat(builders): customize.toml support for workflows, agents, and modules#76
Conversation
…ules
Teach the three builders to emit skills that participate in BMad's
customize.toml override model (per-skill deep behavior customization)
and the module.yaml agents roster contract.
## Workflow Builder
- New Phase 3.5 "Configurability Discovery" with opt-in gate during
build. Opting in emits a customize.toml with activation hooks,
persistent_facts (default globs project-context), on_complete, and
any workflow-specific scalars the author lifts (templates, output
paths, hook points).
- New assets: customize-template.toml, sample-customize-product-brief.toml
(verbatim copy of bmm's product-brief as ground-truth reference).
- SKILL-template.md now wraps resolver activation steps in
{if-customizable} conditional; non-customizable workflows emit no
customize.toml and no resolver wiring.
- Updated standard-fields.md with [workflow] field catalog and naming
conventions (*_template, *_output_path, on_<event>).
## Agent Builder
- [agent] metadata block always emitted (install-time roster contract:
code, name, title, icon, description, agent_type). Override surface
(persistent_facts, activation hooks) is opt-in, default no for memory
and autonomous archetypes whose sanctum owns behavior.
- First-Breath-named agents: name field ships empty; owner fills via
_bmad/custom/config.toml [agents.<code>] after activation. Installer
and UIs tolerate empty name and fall back to title.
- New assets: customize-template.toml, sample-customize-analyst.toml.
- SKILL-template.md and SKILL-template-bootloader.md wrap resolver
activation in {if-customizable}.
- Updated build-process.md, standard-fields.md, agent-type-guidance.md,
template-substitution-rules.md with metadata gathering, opt-in flow,
archetype-specific defaults, and sanctum-first guidance for memory
agents.
## Module Builder
- create-module.md reads each skill's customize.toml during discovery
and populates module.yaml:agents[] from the [agent] metadata block.
Empty name carried through for First-Breath-named agents.
- validate-module.md checks agent roster validity: required fields
present, roster agrees with each agent's own customize.toml, drift
detection.
## Quality Scanners
- New quality-scan-customization-surface.md in both builders
(workflow-builder L7, agent-builder L8). Covers opportunities
(hardcoded templates that should be lifted, missing persistent_facts
defaults, missing hooks, workflows not opted in despite obvious
variance) and abuse (boolean toggle farms, identity overrides leaking
into workflow blocks, arrays-of-tables without code/id keys, over-
named scalars, duplication between customize.toml and SKILL.md). The
agent variant adds archetype-specific rules: metadata drift detection
and sanctum-conflict flagging for memory/autonomous agents.
- Wired into quality-analysis.md as an LLM scanner.
- report-quality-scan-creator.md adds a "Customization Surface"
section in the Detailed Analysis template.
- quality-dimensions.md gains a new Customization Surface dimension
as a build-time mental checklist.
## Docs
- New explanation: docs/explanation/customization-for-authors.md
The "when and why" decision guide for module authors, including a
full bmad-session-prep worked example (tabletop RPG GM workflow)
that walks field-by-field through customization decisions and
reasoning.
- New how-to: docs/how-to/make-a-skill-customizable.md
Procedural companion: opt-in moment, scalar naming, default setup,
override testing.
- Cross-links added to five existing explanation docs:
what-are-bmad-agents.md, what-are-workflows.md,
agent-memory-and-personalization.md (sanctum as customization
surface note), module-configuration.md (config vs customization
distinction), skill-authoring-best-practices.md.
Note: The customization-for-authors and make-a-skill-customizable docs
are author-facing companions to bmm's end-user-facing
docs/how-to/customize-bmad.md.
WalkthroughIntroduces an opt-in Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Builder
participant FileSystem as Fs
participant Resolver as resolve_customization.py
participant AgentRuntime as Agent
Builder->>Fs: Emit SKILL.md + customize.toml (if {customizable})
Note right of Fs: Files at `{skill-root}` and `_bmad/custom/` (team/user)
AgentRuntime->>Fs: Start activation -> invoke resolver step in SKILL.md
AgentRuntime->>Resolver: run resolve_customization.py --key (agent|workflow)
Resolver->>Fs: Read base `{skill-root}/customize.toml`
Resolver->>Fs: Read team `_bmad/custom/{skill}.toml`
Resolver->>Fs: Read user `_bmad/custom/{skill}.user.toml`
Resolver->>Resolver: Merge using rules (scalar override, table deep-merge, arrays-of-tables replace-by-code/id, others append)
Resolver-->>AgentRuntime: Emit resolved `{agent.|workflow.}` block
AgentRuntime->>AgentRuntime: Execute activation_steps_prepend -> load persistent_facts -> execute activation_steps_append
AgentRuntime->>Agent: Begin interaction with resolved config
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🤖 Augment PR SummarySummary: Adds per-skill Changes:
Technical notes: Customization opt-in defaults to “no” in headless mode unless 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
|
|
||
| ## Configuration vs Customization | ||
|
|
||
| Module configuration (this doc) and per-skill customization (`customize.toml`) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers. It lives in `_bmad/config.toml` and `config.user.toml` at the project root and is consumed by many skills. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in `_bmad/custom/{skill-name}.toml` and is scoped to one skill. |
There was a problem hiding this comment.
In docs/explanation/module-configuration.md:26, this says module configuration lives in _bmad/config.toml / config.user.toml, but later in the same doc (and the setup skills) use _bmad/config.yaml / config.user.yaml, so readers may edit the wrong files.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
|
|
||
| **This is purely advisory.** Nothing here is broken. Everything is either an opportunity to expose or a risk to trim. | ||
|
|
||
| Load `/Users/brianmadison/bmad-code/bmad-bmb/custom-support/docs/explanation/customization-for-authors.md` if it's accessible for the decision framework; otherwise apply the principles below directly. |
There was a problem hiding this comment.
In skills/bmad-agent-builder/references/quality-scan-customization-surface.md:18, the hardcoded /Users/... path looks like an absolute-path leak that won’t exist for most installs and is likely to be flagged by the repo’s absolute-path leak checks.
Severity: high
Other Locations
skills/bmad-workflow-builder/references/quality-scan-customization-surface.md:16
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| {if-customizable} | ||
| ### Step 1: Resolve the Workflow Block | ||
|
|
||
| Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` |
There was a problem hiding this comment.
In skills/bmad-workflow-builder/assets/SKILL-template.md:17, the resolver invocation relies on a {skill-root} runtime token; this repo’s own guidance/tools call out {skill-root} as unsupported, so generated skills may end up with an unresolved placeholder at runtime.
Severity: medium
Other Locations
skills/bmad-agent-builder/assets/SKILL-template.md:38skills/bmad-agent-builder/assets/SKILL-template-bootloader.md:29skills/bmad-workflow-builder/references/build-process.md:182skills/bmad-agent-builder/references/build-process.md:229
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
|
|
||
| ## On Activation | ||
|
|
||
| {if-customizable} |
There was a problem hiding this comment.
In skills/bmad-workflow-builder/assets/SKILL-template.md:14, the new {if-customizable} / {/if-customizable} markers are introduced, but the deterministic prepass scripts’ TEMPLATE_ARTIFACTS lists don’t include these markers, so orphaned conditionals could slip through integrity scans.
Severity: low
Other Locations
skills/bmad-agent-builder/assets/SKILL-template.md:35skills/bmad-agent-builder/assets/SKILL-template-bootloader.md:26
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/bmad-workflow-builder/references/quality-dimensions.md (1)
3-3:⚠️ Potential issue | 🟡 MinorUpdate the dimension count.
The heading still says "Seven dimensions" but the document now contains eight: (1) Outcome-Driven Design, (2) Informed Autonomy, (3) Intelligence Placement, (4) Progressive Disclosure, (5) Description Format, (6) Path Construction, (7) Customization Surface, (8) Token Efficiency.
🔢 Proposed fix
-Seven dimensions to keep in mind when building skills. The quality scanners check these automatically during quality analysis — this is a mental checklist for the build phase. +Eight dimensions to keep in mind when building skills. The quality scanners check these automatically during quality analysis — this is a mental checklist for the build phase.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/bmad-workflow-builder/references/quality-dimensions.md` at line 3, Update the heading text that currently reads "Seven dimensions to keep in mind when building skills." to reflect the actual number of items (change "Seven" to "Eight"); confirm the introductory sentence still matches the enumerated list (Outcome-Driven Design, Informed Autonomy, Intelligence Placement, Progressive Disclosure, Description Format, Path Construction, Customization Surface, Token Efficiency) and adjust any surrounding phrasing if necessary so the header and content remain consistent.
🧹 Nitpick comments (3)
docs/explanation/what-are-workflows.md (1)
67-68: Clarify the “three-layer model” by naming all three layers.Line 67 references a three-layer model but lists only the two project override files. Please also mention the base layer (
{skill-root}/customize.toml) to avoid confusion.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/explanation/what-are-workflows.md` around lines 67 - 68, The description mentions a "three-layer model" but only lists the two override files; update the text to explicitly name all three layers: the base layer (customize.toml located at the skill root, e.g., {skill-root}/customize.toml), the project-level override (_bmad/custom/{skill-name}.toml), and the user-level override (.user.toml), and adjust the sentence around "three-layer model" so it enumerates these three by name (customize.toml, _bmad/custom/{skill-name}.toml, .user.toml).skills/bmad-agent-builder/assets/SKILL-template.md (1)
48-48: Consider clarifying thefile:prefix loading behavior.Line 48 states "Entries prefixed
file:are paths or globs — load the referenced contents as facts" but doesn't specify:
- How glob patterns are expanded (e.g., does
file:{project-root}/**/project-context.mdfind all matching files recursively?)- How multiple files from a glob are handled (concatenated? separate facts?)
- What to do if a referenced file is missing (fail activation? warn? skip?)
Adding a brief note about error handling would help the executing agent handle edge cases gracefully.
📋 Proposed clarification
-Treat every entry in `{agent.persistent_facts}` as foundational context for the session. Entries prefixed `file:` are paths or globs — load the referenced contents as facts. All other entries are facts verbatim. +Treat every entry in `{agent.persistent_facts}` as foundational context for the session. Entries prefixed `file:` are paths or globs — expand globs and load the contents of each matching file as facts (if a file is missing, log a warning and continue). All other entries are facts verbatim.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/bmad-agent-builder/assets/SKILL-template.md` at line 48, Clarify the `file:` prefix behavior for agent.persistent_facts: state that `file:` accepts paths or glob patterns which are expanded using recursive globbing (e.g., ** matches recursively), that all matching files are treated as separate facts (do not silently concatenate; add each file's content as its own fact entry) and include how duplicates are handled (preserve order of matches), and specify error handling behavior for missing or unreadable files (log a warning and skip the missing file rather than failing activation). Reference the `agent.persistent_facts` entries and the `file:` prefix so the loader logic can implement recursive glob expansion, per-file fact creation, ordered matching, and non-fatal warning on missing files.skills/bmad-agent-builder/assets/sample-customize-analyst.toml (1)
1-12: Consider adding an explicit “not roster-contract compliant” note.Given this sample omits the builder’s required install-time metadata shape, a stronger warning here would reduce copy-paste misuse in new skills.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/bmad-agent-builder/assets/sample-customize-analyst.toml` around lines 1 - 12, Add a clear, explicit warning at the top of this sample (e.g., a comment block) stating that this file is NOT roster-contract compliant and omits the builder’s required install-time metadata shape; reference the [agent] override surface and the fact that persona/menu overrides are example-only so authors must not copy this into production installs without adding the required install-time metadata. Mention "not roster-contract compliant" verbatim and call out the missing install-time metadata shape so readers know this is a reference-only file for bmad-agent-analyst.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/explanation/agent-memory-and-personalization.md`:
- Around line 44-46: The paragraph under "Sanctum Is the Customization Surface"
uses contradictory phrasing around customize.toml; change the confusing "opt-out
by default for memory archetypes" line to explicitly state "disabled by default
for memory archetypes" (or "opt-in by default") so it's clear customize.toml is
rare, and split the long sentence that begins "Opt in only when you have a
narrow org-level need..." into two shorter sentences that first state
customize.toml is off by default and then give the narrow opt-in example
(pre-sanctum compliance acknowledgment) to improve readability; update the text
around the customize.toml reference and the "Sanctum Is the Customization
Surface" heading accordingly.
In `@docs/explanation/module-configuration.md`:
- Around line 26-27: The "Module configuration" section incorrectly references
TOML filenames; update the text so the config files use the YAML extensions used
elsewhere: change mentions of `_bmad/config.toml` and `config.user.toml` to the
canonical `config.yaml` and `config.user.yaml` (and ensure any adjacent
references to "toml" in this paragraph are updated to "yaml") so the doc's
module-configuration section matches the canonical config format.
In `@docs/explanation/what-are-bmad-agents.md`:
- Line 92: Update the sentence that currently reads "the default for those
archetypes is opt-out" to avoid confusion: replace it with a clear phrasing such
as "the customize.toml override surface is disabled by default for memory and
autonomous agents" or "the override surface is opt-in for memory/autonomous
agents," referencing the existing mention of the "customize.toml override
surface" and the sanctum/persona context so the intent (sanctum is primary and
overrides aren’t enabled by default) is unambiguous.
In `@docs/how-to/make-a-skill-customizable.md`:
- Line 46: The doc text uses the non-canonical example name "campaign-context"
while workflow customization defaults use project-context.md; update the example
to match the canonical default by replacing the phrase "campaign-context" with
"project-context.md" so examples align with the workflow customization defaults
and avoid author confusion.
In `@skills/bmad-agent-builder/assets/SKILL-template-bootloader.md`:
- Line 33: The phrase "after the routing below dispatches" is ambiguous; update
the bootloader text to use an explicit timing description: replace that phrase
with something like "after configuration and sanctum are loaded, and after the
routing step completes, but before accepting user input" so it's clear when to
run {agent.activation_steps_append}; keep the surrounding references to
{agent.activation_steps_prepend}, {agent.persistent_facts}, and
{agent.activation_steps_append} unchanged.
In `@skills/bmad-agent-builder/references/quality-analysis.md`:
- Line 59: Step 2's scanner configuration erroneously omits L8 from the
"no-prepass scanner set" despite L8 being defined as non-prepass and required
for all archetypes; update Step 2 to include L8 in the no-prepass scanner set so
"quality-scan-customization-surface.md" (L8) is not excluded, and mirror this
same inclusion wherever the exclusion appears (references around the existing
Step 2 and the blocks affecting lines noted with L8/L63/L85-L86) to restore
internal consistency between required archetypes and scanner exclusions.
In `@skills/bmad-agent-builder/references/quality-dimensions.md`:
- Line 60: The line under "Metadata validity (all archetypes)" conflicts with
the canonical metadata spec by requiring `name`; update it to follow the
canonical/standard-fields rule: list required fields as `code`, `title`, `icon`,
`description`, `agent_type` and state that `name` is optional (empty string
allowed) with the First-Breath naming guidance for memory/autonomous agents, and
add a note that SKILL.md must agree with customize.toml on identity fields so
validator/author guidance is consistent. Ensure the doc text uses the same
wording as the standard-fields metadata table and references the canonical spec
rather than imposing a different rule.
In `@skills/bmad-agent-builder/references/quality-scan-customization-surface.md`:
- Line 18: The document contains a hardcoded absolute path string
"/Users/brianmadison/bmad-code/bmad-bmb/custom-support/docs/explanation/customization-for-authors.md"
which leaks a host-specific identifier; replace that literal with a
repo-relative reference (for example
"custom-support/docs/explanation/customization-for-authors.md" or a canonical
doc ID/URL) or load via a configurable path variable so the decision framework
reads a portable path instead of the absolute user path.
In `@skills/bmad-agent-builder/references/standard-fields.md`:
- Line 68: The TOML example in standard-fields.md incorrectly places the table
header and key assignment on one line (`[agents.<code>] name = "..."`); update
the example so the table header `[agents.<code>]` is on its own line followed by
`name = "..."` on the next line (and ensure the example is shown in a toml code
block), referencing the exact snippet `[agents.<code>] name = "..."` to locate
and replace.
In `@skills/bmad-module-builder/references/create-module.md`:
- Line 96: The current legacy-agent detection that only checks for an `agent-`
prefix is too narrow; update the logic that scans skill names (the code that
decides whether to add entries under the `agents:` key in module.yaml) to treat
any skill name containing the substring `agent-` (e.g., using a contains or
regex check) as a legacy agent in addition to detecting a `[agent]` block in the
skill's customize.toml; keep the existing `[agent]` block detection unchanged,
and ensure the updated check is used where module.yaml roster entries are built
so names like `cis-agent-analyst` are included.
In `@skills/bmad-workflow-builder/references/quality-analysis.md`:
- Line 64: The execution instructions section that lists scanners to run
"without pre-pass" must include L7 so it matches the table entry added in L64;
update the text (the sentence that currently lists only L4/L5/L6 around the
"without pre-pass" instruction) to include L7 and any corresponding phrasing in
the same paragraph that references "L4/L5/L6" (lines around where the
non-prepass scanners are enumerated) so the doc consistently reflects that `L7`
(the `quality-scan-customization-surface.md` scanner) runs without a pre-pass.
In
`@skills/bmad-workflow-builder/references/quality-scan-customization-surface.md`:
- Line 16: The diff contains a machine-local absolute path string
"/Users/brianmadison/bmad-code/bmad-bmb/custom-support/docs/explanation/customization-for-authors.md"
which leaks a personal environment; update the reference to a
repository-relative path (e.g.,
"custom-support/docs/explanation/customization-for-authors.md" or
"docs/explanation/customization-for-authors.md") wherever it appears in this
file, ensuring any loader/decision-framework that reads the path uses the
repo-relative form; verify the path resolves in CI by using the same relative
root as other docs in skills/bmad-workflow-builder and remove any remaining
absolute paths.
---
Outside diff comments:
In `@skills/bmad-workflow-builder/references/quality-dimensions.md`:
- Line 3: Update the heading text that currently reads "Seven dimensions to keep
in mind when building skills." to reflect the actual number of items (change
"Seven" to "Eight"); confirm the introductory sentence still matches the
enumerated list (Outcome-Driven Design, Informed Autonomy, Intelligence
Placement, Progressive Disclosure, Description Format, Path Construction,
Customization Surface, Token Efficiency) and adjust any surrounding phrasing if
necessary so the header and content remain consistent.
---
Nitpick comments:
In `@docs/explanation/what-are-workflows.md`:
- Around line 67-68: The description mentions a "three-layer model" but only
lists the two override files; update the text to explicitly name all three
layers: the base layer (customize.toml located at the skill root, e.g.,
{skill-root}/customize.toml), the project-level override
(_bmad/custom/{skill-name}.toml), and the user-level override (.user.toml), and
adjust the sentence around "three-layer model" so it enumerates these three by
name (customize.toml, _bmad/custom/{skill-name}.toml, .user.toml).
In `@skills/bmad-agent-builder/assets/sample-customize-analyst.toml`:
- Around line 1-12: Add a clear, explicit warning at the top of this sample
(e.g., a comment block) stating that this file is NOT roster-contract compliant
and omits the builder’s required install-time metadata shape; reference the
[agent] override surface and the fact that persona/menu overrides are
example-only so authors must not copy this into production installs without
adding the required install-time metadata. Mention "not roster-contract
compliant" verbatim and call out the missing install-time metadata shape so
readers know this is a reference-only file for bmad-agent-analyst.
In `@skills/bmad-agent-builder/assets/SKILL-template.md`:
- Line 48: Clarify the `file:` prefix behavior for agent.persistent_facts: state
that `file:` accepts paths or glob patterns which are expanded using recursive
globbing (e.g., ** matches recursively), that all matching files are treated as
separate facts (do not silently concatenate; add each file's content as its own
fact entry) and include how duplicates are handled (preserve order of matches),
and specify error handling behavior for missing or unreadable files (log a
warning and skip the missing file rather than failing activation). Reference the
`agent.persistent_facts` entries and the `file:` prefix so the loader logic can
implement recursive glob expansion, per-file fact creation, ordered matching,
and non-fatal warning on missing files.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f7f6b237-f139-44b2-a37c-4cd96d58df66
📒 Files selected for processing (31)
docs/explanation/agent-memory-and-personalization.mddocs/explanation/customization-for-authors.mddocs/explanation/module-configuration.mddocs/explanation/skill-authoring-best-practices.mddocs/explanation/what-are-bmad-agents.mddocs/explanation/what-are-workflows.mddocs/how-to/make-a-skill-customizable.mdskills/bmad-agent-builder/assets/SKILL-template-bootloader.mdskills/bmad-agent-builder/assets/SKILL-template.mdskills/bmad-agent-builder/assets/customize-template.tomlskills/bmad-agent-builder/assets/sample-customize-analyst.tomlskills/bmad-agent-builder/references/agent-type-guidance.mdskills/bmad-agent-builder/references/build-process.mdskills/bmad-agent-builder/references/quality-analysis.mdskills/bmad-agent-builder/references/quality-dimensions.mdskills/bmad-agent-builder/references/quality-scan-customization-surface.mdskills/bmad-agent-builder/references/report-quality-scan-creator.mdskills/bmad-agent-builder/references/standard-fields.mdskills/bmad-agent-builder/references/template-substitution-rules.mdskills/bmad-module-builder/references/create-module.mdskills/bmad-module-builder/references/validate-module.mdskills/bmad-workflow-builder/assets/SKILL-template.mdskills/bmad-workflow-builder/assets/customize-template.tomlskills/bmad-workflow-builder/assets/sample-customize-product-brief.tomlskills/bmad-workflow-builder/references/build-process.mdskills/bmad-workflow-builder/references/quality-analysis.mdskills/bmad-workflow-builder/references/quality-dimensions.mdskills/bmad-workflow-builder/references/quality-scan-customization-surface.mdskills/bmad-workflow-builder/references/report-quality-scan-creator.mdskills/bmad-workflow-builder/references/standard-fields.mdskills/bmad-workflow-builder/references/template-substitution-rules.md
Comment on lines
+26
to
+27
| Module configuration (this doc) and per-skill customization (`customize.toml`) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers. It lives in `_bmad/config.toml` and `config.user.toml` at the project root and is consumed by many skills. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in `_bmad/custom/{skill-name}.toml` and is scoped to one skill. | ||
|
|
There was a problem hiding this comment.
Fix incorrect config file extensions in this new section.
Line 26 says module config lives in _bmad/config.toml and config.user.toml, but this doc’s own canonical section uses YAML files (config.yaml, config.user.yaml). This is likely to send users to the wrong files.
Suggested doc fix
-... It lives in `_bmad/config.toml` and `config.user.toml` at the project root ...
+... It lives in `_bmad/config.yaml` and `config.user.yaml` at the project root ...🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/explanation/module-configuration.md` around lines 26 - 27, The "Module
configuration" section incorrectly references TOML filenames; update the text so
the config files use the YAML extensions used elsewhere: change mentions of
`_bmad/config.toml` and `config.user.toml` to the canonical `config.yaml` and
`config.user.yaml` (and ensure any adjacent references to "toml" in this
paragraph are updated to "yaml") so the doc's module-configuration section
matches the canonical config format.
…nment Scanners: - Remove absolute-path `Load` directive from both quality-scan-customization-surface.md files. The hardcoded /Users/brianmadison/... path would never resolve in consumer environments. Scanners now rely solely on their embedded Opportunity and Abuse lens tables, matching the self-contained convention of every other quality-scan-*.md in the codebase. Docs route convention: - Append `.md` to 12 internal cross-links to match the site convention (/explanation/foo.md, /how-to/foo.md form). Touches make-a-skill-customizable.md (4), what-are-bmad-agents.md (1), what-are-workflows.md (2), skill-authoring-best-practices.md (2), module-configuration.md (1), agent-memory-and-personalization.md (1). Docs external host: - Swap 3 end-user-guide links from bmadcode.github.io/bmad to docs.bmad-method.org/how-to/customize-bmad/ to point at the correct published docs site for BMAD-METHOD. Docs style: - Rewrite how-to hook from "Use this guide when..." to "This guide walks through..." matching the convention used by distribute-your-module.md. - Remove first-person voice from the bmad-session-prep worked example in customization-for-authors.md. "Here's how I'd customize it" -> "Here's how to think about its customization surface"; "I'm not trying to catalog every RPG; I ship one default" -> "The skill isn't trying to catalog every RPG; it ships one default"; "### What I'd NOT expose" -> "### What Not to Expose".
…root} ban
Bot findings addressed
- quality-analysis.md (agent/workflow): add L8/L7 to the "without
pre-pass" scanner lists so the new customization-surface scanner
actually runs.
- quality-dimensions.md (agent/workflow): update dimension counts
(Seven -> Eight; agent-side: Eight plus a ninth memory-only
Sanctum Architecture).
- quality-dimensions.md (agent): realign the Metadata validity rule
with standard-fields.md -- name is optional (empty string valid),
not required for stateless agents.
- standard-fields.md (agent): fix invalid TOML in the
first-breath-name example; split `[agents.<code>]` and
`name = "..."` across two lines in a fenced toml block.
- create-module.md (module): legacy-agent detection now accepts
`agent-` as a segment anywhere in the skill name, not just a
prefix (so `cis-agent-analyst` is picked up).
Terminology
- agent-memory-and-personalization.md, what-are-bmad-agents.md:
replace confusing "opt-out by default" phrasing with "disabled by
default" for the memory/autonomous customize.toml override surface.
Polish
- make-a-skill-customizable.md: align example glob name with the
canonical `project-context.md` (was `campaign-context`).
- SKILL-template-bootloader.md: replace ambiguous "after the routing
below dispatches" with explicit timing ("after config and sanctum
load, after routing dispatches, before user input"); also clarify
`file:` prefix glob expansion and missing-file handling.
- SKILL-template.md (agent): same `file:` prefix clarification.
- what-are-workflows.md: name all three override layers explicitly
(skill-root customize.toml + team + user) instead of the ambiguous
"three-layer model" phrasing that only listed two.
Docs accurate to bmm
- module-configuration.md: clarify that authors still write
module.yaml as source of truth, and the installer flows module-level
answers and the `agents:` roster into `_bmad/config.toml`
(+ config.user.toml) at the project root. Keeps alignment with bmm
PR #2285 central config.
Remove {skill-root} restriction
- skill-authoring-best-practices.md, builder-commands.md: drop the
"Never use {skill-root}" language. The token is supported and
resolves to the skill's installed directory; whether to use it is
up to the author.
New Conventions section in emitted skills
- SKILL-template.md (agent/workflow), SKILL-template-bootloader.md
(agent): add a `## Conventions` block listing the path tokens the
emitted skill uses: bare paths, {skill-root}, {project-root},
{skill-name}. Mirrors the bmm stateless-skill convention so readers
hit the vocabulary before it appears under On Activation.
Contributor
Author
Follow-up commits addressing reviewTwo commits on top of the original, both on
Bot findings addressedReal bugs
Terminology
Polish
Absolute-path leak
Intentionally not following bot advice
Not addressed this round
New in
|
Three pre-existing CI failures on main were gating PR #76. Fixing in this branch rather than a separate PR per reviewer direction. prettier - Run `prettier --write` on .claude-plugin/marketplace.json and website/astro.config.mjs to restore formatting consistency. markdownlint - README.md: wrap the `contact@bmadcode.com` bare URL as <contact@bmadcode.com> (MD034/no-bare-urls). docs:validate-links - tools/validate-doc-links.cjs: tighten LINK_REGEX with a (?!\w+://) negative lookahead so external URLs ending in .md (e.g. https://github.com/.../CONTRIBUTING.md) are no longer incorrectly classified as local doc paths. The validator only knows how to resolve site-relative and bare .md paths; protocol URLs should be ignored entirely. Previously, `distribute-your-module.md`'s valid cross-repo marketplace CONTRIBUTING.md link was flagged as "File not found anywhere" and failing CI. All three checks pass locally (npm run format:check / lint:md / docs:validate-links).
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/bmad-agent-builder/references/quality-dimensions.md`:
- Around line 68-70: Update the sentence under the "Sanctum Architecture (memory
agents only)" section that currently reads "beyond the general seven" to "beyond
the general eight" so it matches the eight general dimensions defined earlier
(Sections 1–8); edit the text in the header block for "Sanctum Architecture
(memory agents only)" to replace "seven" with "eight".
In `@tools/validate-doc-links.cjs`:
- Around line 25-30: The LINK_REGEX currently only rejects patterns with
"scheme://", allowing links like "mailto:foo.md" or "file:README.md" to be
treated as local .md paths; update the regex used in LINK_REGEX so the bare-.md
alternative uses a negative lookahead that excludes any URI scheme (e.g.
(?![A-Za-z][\w+.-]*:)) before the filename instead of just (?!\w+:\/\/),
ensuring any "scheme:" or "scheme://..." is excluded from matching as a local
docs path.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e63e0519-dedf-4136-b376-8bb5db76c32e
📒 Files selected for processing (23)
.claude-plugin/marketplace.jsonREADME.mddocs/explanation/agent-memory-and-personalization.mddocs/explanation/customization-for-authors.mddocs/explanation/module-configuration.mddocs/explanation/skill-authoring-best-practices.mddocs/explanation/what-are-bmad-agents.mddocs/explanation/what-are-workflows.mddocs/how-to/make-a-skill-customizable.mddocs/reference/builder-commands.mdskills/bmad-agent-builder/assets/SKILL-template-bootloader.mdskills/bmad-agent-builder/assets/SKILL-template.mdskills/bmad-agent-builder/references/quality-analysis.mdskills/bmad-agent-builder/references/quality-dimensions.mdskills/bmad-agent-builder/references/quality-scan-customization-surface.mdskills/bmad-agent-builder/references/standard-fields.mdskills/bmad-module-builder/references/create-module.mdskills/bmad-workflow-builder/assets/SKILL-template.mdskills/bmad-workflow-builder/references/quality-analysis.mdskills/bmad-workflow-builder/references/quality-dimensions.mdskills/bmad-workflow-builder/references/quality-scan-customization-surface.mdtools/validate-doc-links.cjswebsite/astro.config.mjs
✅ Files skipped from review due to trivial changes (14)
- README.md
- website/astro.config.mjs
- skills/bmad-workflow-builder/references/quality-analysis.md
- docs/reference/builder-commands.md
- docs/explanation/what-are-workflows.md
- .claude-plugin/marketplace.json
- skills/bmad-agent-builder/references/quality-analysis.md
- docs/explanation/what-are-bmad-agents.md
- docs/explanation/module-configuration.md
- skills/bmad-workflow-builder/assets/SKILL-template.md
- docs/how-to/make-a-skill-customizable.md
- docs/explanation/agent-memory-and-personalization.md
- skills/bmad-agent-builder/references/quality-scan-customization-surface.md
- skills/bmad-workflow-builder/references/quality-scan-customization-surface.md
🚧 Files skipped from review as they are similar to previous changes (5)
- skills/bmad-workflow-builder/references/quality-dimensions.md
- docs/explanation/skill-authoring-best-practices.md
- skills/bmad-module-builder/references/create-module.md
- skills/bmad-agent-builder/assets/SKILL-template-bootloader.md
- skills/bmad-agent-builder/assets/SKILL-template.md
Comment on lines
+68
to
70
| ## 9. Sanctum Architecture (memory agents only) | ||
|
|
||
| Memory agents have additional quality dimensions beyond the general seven: |
There was a problem hiding this comment.
Fix stale dimension count wording in Sanctum section.
Line 70 says “beyond the general seven,” but this doc now defines eight general dimensions (Line 3 and Sections 1–8). Please update that sentence to “beyond the general eight” to keep the checklist internally consistent.
Suggested doc fix
-Memory agents have additional quality dimensions beyond the general seven:
+Memory agents have additional quality dimensions beyond the general eight:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/bmad-agent-builder/references/quality-dimensions.md` around lines 68 -
70, Update the sentence under the "Sanctum Architecture (memory agents only)"
section that currently reads "beyond the general seven" to "beyond the general
eight" so it matches the eight general dimensions defined earlier (Sections
1–8); edit the text in the header block for "Sanctum Architecture (memory agents
only)" to replace "seven" with "eight".
Comment on lines
+25
to
+30
| // Matches markdown links whose target is either a relative/site-relative path | ||
| // (starts with ./ ../ or /) or a bare .md reference. The negative lookahead | ||
| // (?!\w+:\/\/) keeps external URLs (https://..., mailto:..., ftp:...) out of | ||
| // the bare-.md alternative so a cross-repo link to a README.md isn't treated | ||
| // as a local docs path. | ||
| const LINK_REGEX = /\[([^\]]*)\]\(((?:\.{1,2}\/|\/)[^)]+|(?!\w+:\/\/)[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g; |
There was a problem hiding this comment.
Exclude all URI schemes from local .md matching.
Line 30 only filters scheme://, so links like mailto:foo.md, file:README.md, or vscode:README.md can still be treated as local docs paths and fail validation. Consider excluding any URI scheme before the bare .md alternative.
Proposed regex tightening
-const LINK_REGEX = /\[([^\]]*)\]\(((?:\.{1,2}\/|\/)[^)]+|(?!\w+:\/\/)[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g;
+const LINK_REGEX =
+ /\[([^\]]*)\]\(((?:\.{1,2}\/|(?!\/\/)\/)[^)]+|(?!(?:[A-Za-z][A-Za-z0-9+.-]*:|\/\/))[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| // Matches markdown links whose target is either a relative/site-relative path | |
| // (starts with ./ ../ or /) or a bare .md reference. The negative lookahead | |
| // (?!\w+:\/\/) keeps external URLs (https://..., mailto:..., ftp:...) out of | |
| // the bare-.md alternative so a cross-repo link to a README.md isn't treated | |
| // as a local docs path. | |
| const LINK_REGEX = /\[([^\]]*)\]\(((?:\.{1,2}\/|\/)[^)]+|(?!\w+:\/\/)[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g; | |
| // Matches markdown links whose target is either a relative/site-relative path | |
| // (starts with ./ ../ or /) or a bare .md reference. The negative lookahead | |
| // (?!\w+:\/\/) keeps external URLs (https://..., mailto:..., ftp:...) out of | |
| // the bare-.md alternative so a cross-repo link to a README.md isn't treated | |
| // as a local docs path. | |
| const LINK_REGEX = | |
| /\[([^\]]*)\]\(((?:\.{1,2}\/|(?!\/\/)\/)[^)]+|(?!(?:[A-Za-z][A-Za-z0-9+.-]*:|\/\/))[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g; |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/validate-doc-links.cjs` around lines 25 - 30, The LINK_REGEX currently
only rejects patterns with "scheme://", allowing links like "mailto:foo.md" or
"file:README.md" to be treated as local .md paths; update the regex used in
LINK_REGEX so the bare-.md alternative uses a negative lookahead that excludes
any URI scheme (e.g. (?![A-Za-z][\w+.-]*:)) before the filename instead of just
(?!\w+:\/\/), ensuring any "scheme:" or "scheme://..." is excluded from matching
as a local docs path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Teach the three builders to emit skills that participate in BMad's
customize.tomloverride model (per-skill deep behavior customization) and themodule.yamlagents roster contract.customize.tomlwith[workflow]blocks, and wires SKILL.md to use{workflow.X}indirection when opted in.[agent]metadata block (install-time roster contract) and gains an opt-in override surface. Memory and autonomous agents default to metadata-only because their sanctum already owns behavior. First-Breath-named agents ship emptyname, filled by the owner post-activation via_bmad/custom/config.toml.customize.tomlduring create-module and populatesmodule.yaml:agents[]from it.validate-modulechecks the resulting roster against the on-disk metadata.quality-scan-customization-surface.mdin both agent- and workflow-builder. Surfaces opportunities (hardcoded templates that should be lifted, missing defaults, workflows not opted in despite obvious variance) and abuse (boolean toggle farms, arrays withoutcode/id, override surfaces that duplicate sanctum concepts on memory agents).docs/explanation/customization-for-authors.md) with a fullbmad-session-prepworked example for tabletop RPG GMs, plus a companion how-to (docs/how-to/make-a-skill-customizable.md) and cross-links in five existing explanation docs.Align with bmm's #2284 and #2285 (the three-layer resolver, central config, and agent roster). No changes to
_bmad/scripts/resolve_customization.pyneeded; builders assume it's installed and ship SKILL.md with a manual-merge fallback in the resolver step.Test plan
bmad-workflow-builderwith a sample workflow that loads a template. Verify: opt-in question appears, answering yes producescustomize.toml, answering no produces none.bmad-workflow-builderwith--headlessand no--customizable. Verify: nocustomize.tomlemitted.bmad-agent-builderfor a stateless agent. Verify:customize.tomlemitted with[agent]metadata; override surface present only when opted in.bmad-agent-builderfor a memory agent. Verify: metadata-onlycustomize.tomlby default; SKILL-template-bootloader.md preserved with sanctum-routing activation.bmad-agent-builderfor a First-Breath-named agent. Verify:name = ""in emittedcustomize.toml.bmad-module-builder(CM) against a folder containing at least one agent built via the agent-builder. Verify:module.yaml:agents[]populated from each agent's[agent]block.bmad-module-builder(VM) against a module whose agent has drifted metadata (e.g. icon mismatch between roster and agent's owncustomize.toml). Verify: drift flagged.customization-surface-analysis.mdproduced, opportunities listed with*_templatenaming suggestions.[agent].identityoverride. Verify: flagged as high-abuse sanctum conflict.customization-for-authors.md,make-a-skill-customizable.md, and all five updated explanation docs render and internal links resolve.Summary by CodeRabbit