* fix(installer): preserve module-help.csv schema in merged bmad-help.csv (#2278)
The installer's mergeModuleHelpCatalogs was rewriting the merged catalog
under a different schema (module,phase,name,code,sequence,workflow-file,...)
than the documented source schema in every module's module-help.csv
(module,skill,display-name,menu-code,description,action,args,phase,...).
Worse, the parsing assumed the wrong source column order, so column data
was scrambled in the merged output. SKILL.md docs the source schema, so
the bmad-help skill was navigating a catalog whose actual columns no
longer matched its mental model.
Drop the transformation and the agent enrichment columns (which had no
consumers anywhere in the codebase). Emit rows verbatim in the source
schema, padding short rows and filling empty module fields. Sort by
module then phase, stable within phase to preserve authored order.
Closes#2278
* fix(catalog): normalize module-help.csv rows to documented 13-column schema
Many rows in core-skills/module-help.csv and bmm-skills/module-help.csv
were missing one column between description and phase, leaving them at
12 fields instead of 13. CSV consumers that read by header position
were silently mapping data into the wrong columns (description into
action, phase into args, required into before, etc).
Inserted an empty cell at column index 5 across all 31 affected rows
to restore alignment with the documented header
(module,skill,display-name,menu-code,description,action,args,phase,
after,before,required,output-location,outputs).
* fix(config): promote project_name to core, fixes#2279
project_name was a bmm-specific prompt despite being a universal
project-level concept used by every module — including core skills like
bmad-brainstorming, which loads from _bmad/core/config.yaml and was
silently broken because project_name lived under bmm. Users without bmm
installed could not run brainstorming at all.
Move:
- src/core-skills/module.yaml: declare project_name with prompt
"What is your project called?" and default {directory_name}, matching
what bmm previously had.
- src/bmm-skills/module.yaml: remove the bmm definition; add project_name
to the "Variables from Core Config inserted" header comment so
contributors can see what's inherited.
Migration for existing installs:
- tools/installer/modules/official-modules.js: after loadExistingConfig
reads each per-module config.yaml, hoist any keys that are now declared
in core but appear under non-core modules. Without this, the partition
logic in writeCentralConfig (which strips core keys from non-core
buckets) would silently drop the user's prior project_name on the next
quick-update. Generic — handles project_name today and any future
module→core promotions.
- The hoist preserves precedence: an existing core value beats a stale
module-side copy.
--yes seed:
- tools/installer/ui.js: add project_name to the hardcoded core seed
(using path.basename(directory) to match the {directory_name} default)
so non-interactive fresh installs populate it. Without this the seed
silently omits project_name and core skills fall back to literals.
Tests:
- test/test-installation-components.js Suite 43 (9 assertions) covers
the schema move, the loadExistingConfig hoist, and the precedence rule.
- Suite 35 fixture updated: project_name moved from bmm bucket to core,
with a stale bmm copy left in place to verify it gets stripped.
Verified manually:
- Fresh install -y: project_name lands in [core] of config.toml.
- Existing install with project_name in bmm/config.yaml: quick-update
hoists it to [core] and strips it from [modules.bmm].
* fix(installer): harden config-load against malformed config.yaml
Per augment review on #2348: loadExistingConfig stored any truthy
yaml.parse result (including scalars like '42'), which would later crash
_hoistCoreKeysFromLegacyModuleConfigs at \`key in cfg\` with
"Cannot use 'in' operator to search for ... in 42".
- loadExistingConfig: only keep parses that are plain objects (not
scalars or arrays). A corrupt config.yaml is now treated the same as
a parse error — skipped, not crashed-on.
- _hoistCoreKeysFromLegacyModuleConfigs: belt-and-suspenders type guards
on _existingConfig.core (in case it's populated by some other path)
and on each module cfg in the loop.
- Test Suite 43 adds 2 assertions covering a scalar core/config.yaml:
loadExistingConfig must not crash, and bmm.project_name must still
hoist into a clean core bucket.
* feat(core-skills): add bmad-customize for authoring _bmad/custom overrides
A conversational guide skill that helps users author or update TOML overrides
in _bmad/custom/ for customizable BMad agents and workflows. Covers per-skill
agent and workflow surfaces; central config is out of scope for v1.
- SKILL.md: six-step flow (intent, discover, route, compose, team-vs-user,
show-confirm-write-verify) with baked-in agent-vs-workflow routing heuristic
and a template-swap subroutine
- scripts/list_customizable_skills.py: stdlib-only scanner that enumerates
customizable skills across standard IDE install paths, reports surface type
and override status, PEP 723, 10 unit tests
- Reuses _bmad/scripts/resolve_customization.py for post-write verification
- Registered in core-skills/module-help.csv with menu code BC
* refactor(bmad-customize): apply QA pass (top 3 recommendations)
Applies the three highest-payoff themes from the quality analysis:
- Labeling + completion contracts: rename ## Purpose to ## Overview,
add domain framing (what customization means in BMad, typical user
arrival shapes), add an explicit Completion block with testable
conditions for "skill run is done"
- Hostile-environment robustness: add On-Activation preflight that
classifies no-BMad / BMad-without-resolver / full-install states,
instruct Step 2 to surface scanner errors[] and scanned_roots on
empty results, add resolver-missing fallback to Step 6.4, add a
re-enter-Step-4 recovery loop when verify shows the override didn't
take effect
- Returning-user and iteration experience: add "Audit / iterate"
intent class in Step 1, lead discovery with already-overridden
skills for that intent, read existing overrides in Step 3 before
composing, frame Step 4 as additive-on-top rather than fresh
authoring, give Cross-cutting intent an explicit Step 3 branch
that walks agent-vs-workflow with the user
Resolves 12 of 18 observations from the quality report. Lint clean
(scan-path-standards and scan-scripts both 0 findings). Unit tests
still 10/10.
* refactor(bmad-customize): derive skills root from install location
Previously the scanner hardcoded a list of IDE skill directories
(.claude/skills, .cursor/skills, .cline/skills, .continue/skills) and
scanned them relative to the project root. That was wrong: skills can
be installed either project-local or user-global, the IDE determines
the convention, and the set of valid locations is open-ended.
The scanner now derives its primary skills root from __file__ — the
running skill's own install directory is the authoritative location
for finding siblings. --skills-root overrides the default; --extra-root
(repeatable) adds additional locations for the rare mixed-install case.
Changes:
- list_customizable_skills.py: remove SKILL_ROOTS constant, add
default_skills_root() derived from __file__, rename scan_project
to scan_skills(skills_roots, project_root), add --skills-root and
--extra-root flags, de-dupe skills when the same name appears in
multiple roots (first wins)
- SKILL.md: update Step 2 to describe the scanner's derive-from-install
behavior and when to use --extra-root; drop the hardcoded IDE path
list from Notes
- tests: refactor setUp to place skills under a generic skills root
(not .claude/skills), add 3 new tests for multiple-roots merge,
duplicate-name precedence, and missing-root error reporting
* docs(customization): point users at bmad-customize as the guided path
Surface the new bmad-customize skill across the three customization
docs so users know they don't need to hand-author TOML to benefit
from the surface:
- customize-bmad.md: prominent tip at the top introducing the skill
as the guided authoring helper; updated the "Need to see what's
customizable?" troubleshooting tip to recommend the skill first
- expand-bmad-for-your-org.md: tip under prereqs noting every recipe
can be applied via the skill, with the recipes remaining the
reference for what to override
- named-agents.md: short paragraph in the customization section and a
link entry under the references list
Hand-authoring still works the same way; the skill is additive.
Central-config overrides are flagged as the current exception.
* docs(bmad-customize): steer users at bmad-builder instead of 'forking'
* fix(bmad-customize): reword description to pass file-ref validator
* refactor(bmad-customize): tighten description and expand module-help entry
- SKILL.md description: drop the catch-all 'or asks how to change the
behavior of a specific BMad skill' trigger clause that would fire in
casual discussion; keep the four explicit phrase triggers.
- module-help.csv: rewrite the description so bmad-help has real
routing material — names the concrete capabilities (persistent
facts, template swaps, activation hooks, menus), the scope routing,
and the value prop (no TOML hand-authoring). Matches the 'Use
when...' pattern other Core entries use.
* fix(module-help): quote bmad-customize description field that contains commas
* fix(bmad-customize): address PR #2289 review findings
- SKILL.md preflight: load root config from _bmad/config.toml and
config.user.toml (not .yaml) — the installer emits TOML; the YAML
references would have made the skill silently miss real user config
- SKILL.md resolver fallback (Step 6.4): read all three merge layers
when present (base / team / user) and describe the merge in
base → team → user order; the prior wording could describe the wrong
effective merge when the user wrote .user.toml on top of an existing
team .toml
- SKILL.md: replace bare 'docs/how-to/customize-bmad.md' references
(3 locations) with the public docs URL so users installing the skill
aren't pointed at a path they don't have locally
- list_customizable_skills.py: catch UnicodeDecodeError in
read_frontmatter_description so a non-UTF-8 SKILL.md can't abort
the whole scan
- list_customizable_skills.py: clarify exit-code contract in the
module docstring — errors[] is non-fatal by design, exit 2 is
reserved for invocation errors
- customize-bmad.md: tighten the tip to scope bmad-customize to the
per-skill surface; central-config is out of scope v1
- expand-bmad-for-your-org.md: same scoping — Recipes 1-4 can be
applied by the skill; Recipe 5 (central config) stays hand-authored
* fix(bmad-customize): markdownlint MD034 and validate-file-refs
- Wrap the three docs.bmad-method.org references as
[text](url) markdown links instead of bare URLs (MD034)
- Drop the {project-root}/ prefix on line 41's config.toml
references. validate-file-refs strips the template prefix and
tries to resolve 'config.toml' as 'src/config.toml'; sibling
skills (party-mode, retrospective, advanced-elicitation) all
reference '_bmad/config.toml' bare and pass CI — match that
pattern. The '(root level under {project-root}, installer-owned)'
parenthetical preserves the disambiguation.
* refactor(bmad-customize): cut token-wasting prose from SKILL.md
Down from 175 lines to 110. Removed:
- 'What customization means in BMad' architecture backgrounder — the
LLM reads the live customize.toml in Step 3; doesn't need the lore
- 'Desired Outcomes' section — retrospective narration of what the
6 steps already instruct
- 'Role' section — fluff; the flow itself defines the role
- 'Notes' section — sparse-override rule already in Step 4, IDE-path
note is commentary, docs link duplicates the out-of-scope section
- 'The scanner derives its skills directory from...' and 'returns JSON
with...' — commentary the LLM doesn't need; it runs the script and
sees the output
- 'that file IS the schema' and similar editorial asides throughout
- Explanatory clauses like 'silently drifts on every release' and
'trust the user's domain knowledge'
Kept everything that's load-bearing: preflight conditionals, intent
classification, routing heuristic, merge semantics, template-swap
subroutine, team-vs-user defaults, verify fallback and recovery loop,
completion conditions, out-of-scope list.
* refactor: remove bmad-skill-manifest yaml; introduce four-layer central config.toml
- Agent essence moves from per-skill bmad-skill-manifest.yaml files
into each module.yaml's `agents:` block (code, name, title, icon,
description). Per-agent customize.toml remains the deep-behavior
source of truth.
- Installer emits four TOML files:
_bmad/config.toml team install answers + agent roster
_bmad/config.user.toml user install answers
_bmad/custom/config.toml team overrides stub
_bmad/custom/config.user.toml personal overrides stub
Prompts declare scope: user to route answers to config.user.toml.
- resolve_config.py merges four layers: base-team -> base-user ->
custom-team -> custom-user.
- Three consumer skills (party-mode, advanced-elicitation,
retrospective) switched from agent-manifest.csv to the resolver.
- installer.js mergeModuleHelpCatalogs now takes the in-memory
agent list from ManifestGenerator -- no CSV roundtrip.
- Deleted: 6 bmad-skill-manifest.yaml files, agent-manifest.csv
emission, collectAgents/getAgentsFromDirRecursive,
paths.agentManifest().
* fix(installer): strip core-key pollution from [modules.*]; soften config headers
- writeCentralConfig now always strips core-module keys from every
[modules.<code>] bucket, even when the module's schema is not
available in src/ (external / marketplace modules like cis, bmb).
Core values belong in [core] only; workflows read them directly.
- When the module's own schema IS available (built-in modules),
also drop any key it does not declare as a prompt — same
spread-pollution filter as before, now layered on top.
- Section-aware headers on both _bmad/config.toml and
_bmad/config.user.toml: [core] / [modules.*] values are
editable (installer reads them as defaults on next install);
[agents.*] is regenerated from module.yaml and will be wiped —
overrides for agents go in _bmad/custom/config*.toml instead.
* docs: cover central config.toml + Diataxis prose pass across three files
Document the new four-file central configuration surface (_bmad/config.toml,
config.user.toml, and custom/ overrides) alongside the existing per-skill
customize.toml. Make editing rules, scope partitioning, and when-to-use-which
guidance explicit.
- customize-bmad.md: new "Central Configuration" section with editing rules,
three worked examples (rebrand, fictional agent, module settings override),
and a "when to use which surface" table. Converted five h4 headers to
bold paragraph intros per style guide.
- expand-bmad-for-your-org.md: two-layer mental model extended to three;
new Recipe 5 with three variants (rebrand, custom crew, pinned team
settings); reinforcement table extended.
- named-agents.md: noted the dual customization surface — per-skill shapes
behavior, central config shapes roster identity.
Diataxis prose pass applied across all three files: banned vocabulary
check, em-dash cap, hypophora / metanoia / amplificatio / stakes-inflation
cleanup, rhythm and burstiness fixes. Structural conformance verified;
markdownlint and prettier clean.
* test+docs: add central config unit tests; fix stale recipe count
- test: two new suites (35 + 36) covering writeCentralConfig and
ensureCustomConfigStubs. Verifies scope partitioning (user_name
lands only in config.user.toml), core-key pollution stripping
from [modules.*], unknown-schema fallthrough (external modules
survive without schema), agent roster baked into config.toml
[agents.*] only, stub-preservation on re-install. 44 new
assertions.
- docs: fixed four stale "four recipes" references to say "five"
after Recipe 5 (Customize the Agent Roster) was added. Touches
frontmatter, opening paragraph, Combining Recipes paragraph,
and the named-agents cross-link blurb.
* fix: address PR review feedback on central config
- resolve_config.py argparse: three-layer → four-layer description
- SKILL/workflow/explanation docs: document all four layers including
_bmad/config.user.toml (was missing from merge-stack descriptions)
- customize-bmad.md + installer headers: drop the false "direct edits to
config.toml persist" claim; installer reads from per-module config.yaml,
not central TOML, so direct edits get clobbered. Route users to
_bmad/custom/config.toml for durable overrides
- writeCentralConfig: warn loudly when a module.yaml can't be parsed
(previously silent — user-scoped keys could mis-file into team config)
- writeCentralConfig: preserve [agents.*] blocks for modules that didn't
contribute fresh agents this run (e.g. quickUpdate skipping modules
whose source is unavailable) so the roster doesn't silently shrink
- add extractAgentBlocks helper + Test Suite 37 covering preservation
Addresses comments from augmentcode and coderabbitai on PR #2285.
Core and BMM modules live in this repo (src/core-skills, src/bmm-skills)
but the installer UI sourced them from the remote registry. When the
registry was unreachable (VPN, proxy, firewall), the fallback YAML only
had the 4 external modules, so core and bmm disappeared from the install
list entirely.
Now _selectOfficialModules and getDefaultModules always read built-in
modules from the local source via OfficialModules.listAvailable(), then
append external modules from the registry. Network failures only affect
external modules.
Closes#2239
* feat(bmad-help): add _meta rows and llms.txt support for general questions
Register llms.txt URLs in module-help.csv via _meta rows so bmad-help
can fetch module documentation when users ask questions that don't map
to a specific skill.
* refactor(bmad-help): streamline llms.txt docs into existing skill sections
* chore: remove SM agent (Bob) and migrate capabilities to Developer agent
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(docs): correct agent naming and grammar from review triage
Standardize Developer agent references to bmad-agent-dev (matching
installed skill directory name) and fix possessive apostrophe in
implementation-readiness workflow.
* fix(skills): replace dev team references with Developer agent
No longer a multi-agent development team — just one Developer agent.
Remove residual Scrum Master search patterns from retrospective.
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* clear up contradiction and config mispath
* fix(party-mode): clarify solo mode behavior and improve response presentation rules
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace the multi-file workflow architecture (workflow.md + 3 step files)
with a self-contained SKILL.md that spawns each agent as an independent
subagent via the Agent tool. This produces genuinely diverse perspectives
instead of one LLM roleplaying multiple characters. Adds --model and
--solo flags for flexibility.
* refactor: remove bmad-init skill and standardize config loading across all skills
Remove the bmad-init core skill entirely — all agents and workflow skills now
load config directly from their module's config.yaml instead of delegating to
bmad-init as an intermediary. This eliminates the Python script dependency and
simplifies the activation path for every skill.
Changes across all skill types:
- Agents (9 skills): Replace "Load config via bmad-init skill" block with
direct config loading from `{project-root}/_bmad/bmm/config.yaml`, resolving
user_name, communication_language, document_output_language,
planning_artifacts, and project_knowledge
- Workflow skills (12 skills): Standardize INITIALIZATION/Configuration Loading
sections to a consistent Activation format matching the agent pattern
- bmad-prfaq: Align activation to standard config pattern, convert scripted
dialogue to outcome-focused instructions (no direct quotes)
- bmad-product-brief: Remove External Skills section referencing bmad-init
- bmad-party-mode: Standardize initialization to Activation format
- bmad-advanced-elicitation: Inline agent_party path instead of config var
- bmad-distillator: Remove unused argument-hint frontmatter
- Delete legacy create-prd/ directory (superseded by bmad-create-prd)
- Delete bmad-init skill entirely: SKILL.md, bmad_init.py, core-module.yaml,
and test suite
* fix: remove remaining bmad-init references from marketplace.json and distillate examples
Clean up missed references: remove bmad-init from marketplace.json skills
list, replace bmad-init examples in distillate-format-reference.md with
bmad-help/bmad-setup to keep examples valid without referencing a removed skill.
* fix: update broken file references in bmad-edit-prd after create-prd deletion
Point prdPurpose refs from deleted create-prd/data/ to bmad-create-prd/data/
and validationWorkflow ref from create-prd/steps-v/ to bmad-validate-prd/steps-v/.
* refactor(installer): restructure installer with clean separation of concerns
Move tools/cli/ to tools/installer/ with major structural cleanup:
- InstallPaths async factory for path resolution and directory creation
- Config value object (frozen) replaces mutable config bag
- ExistingInstall value object replaces stateful Detector class
- OfficialModules + CustomModules + ExternalModuleManager replace monolithic ModuleManager
- install() is prompt-free; all user interaction in ui.js
- Update state returned explicitly instead of mutating customConfig
- Delete dead code: dependency-resolver, _base-ide, IdeConfigManager,
platform-codes helpers, npx wrapper, xml-utils
- Flatten directory structure: custom/handler → custom-handler,
tools/cli/ → tools/installer/, lib/ directories removed
- Update all path references in package.json, tests, CI, and docs
* fix(installer): guard ExistingInstall.version and surface module.yaml errors
Guard ExistingInstall.version access with .installed check in
uninstall.js, ui.js, and installer.js to prevent throwing on
empty/partial _bmad dirs. Surface invalid module.yaml parse errors
as warnings instead of silently returning empty results.
* fix(bmad-init): correctly resolve output_folder paths outside project root
When output_folder was set to an absolute path (e.g. /Users/me/outputs),
the {project-root}/{value} result template stored it as
{project-root}//absolute/path. resolve_project_root_placeholder then did
a naive string replace, producing /project//absolute/path — a broken path
that workflows could not resolve.
For relative paths outside the root (e.g. ../../sibling), the same naive
replace left un-normalized paths like /project/../../sibling in the
resolved config, which some tools mishandled.
Fix resolve_project_root_placeholder to strip the {project-root} token,
detect whether the remainder is absolute (returning it directly) or
relative (joining with project root and normalizing via os.path.normpath).
Fix apply_result_template to skip the template entirely when raw_value is
already an absolute path, and to normalize the result for relative-but-
outside paths. This covers the bmad-init SKILL write path, which bakes
the resolved path directly into config.yaml.
Add 7 tests covering all three path cases (absolute, relative-with-
traversal, normal in-project) for both functions.
* Address review comments
---------
Co-authored-by: Akhilesh Tyagi <akhilesh.t@nextiva.com>
Co-authored-by: Brian <bmadcode@gmail.com>
Switch skill discovery gate from requiring bmad-skill-manifest.yaml with
type: skill to detecting any directory with a valid SKILL.md (frontmatter
name + description, name matches directory name). Delete 34 stub manifests
that carried no data beyond type: skill. Agent manifests (9) are retained
for persona metadata consumed by agent-manifest.csv.
Inline workflow.md content directly into SKILL.md for: editorial-review-prose,
editorial-review-structure, help, index-docs, review-adversarial-general,
review-edge-case-hunter, and shard-doc. Deletes the now-redundant workflow.md
files. No behavioral change — same pattern as advanced-elicitation in PR #2076.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Merge workflow.md content directly into SKILL.md and delete the
now-redundant workflow file. The frontmatter `agent_party` variable
moves into SKILL.md; all relative file references (`./methods.csv`)
remain valid.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: consolidate agents into phase-based skill directories
Remove separate agent/workflow/skill directories (src/bmm/agents,
src/bmm/workflows, src/core/skills, src/utility/agent-components) and
reorganize all content into phase-based structures under src/bmm-skills
(1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) and
src/core-skills. Eliminates the agent/skill distinction by treating
agents as skills within their workflow phase.
* fix: update broken file references to use new bmm-skills paths
* docs: update all references for unified bmad-quick-dev workflow
Remove all references to the old separate bmad-quick-spec and
bmad-quick-dev-new-preview workflows. The new bmad-quick-dev is a
unified workflow that handles intent clarification, planning,
implementation, review, and presentation in a single run.
Updated files across English docs, Chinese translations, source
skill manifests, website diagram, and build tooling.
Brian
Alex Verkhovsky
PinkyD
Akhilesh Tyagi