mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-19 08:11:52 +08:00
feat-set-flag-1663
1862 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Brian Madison
|
1ab4d5f93c |
refactor(installer): simplify --set to a post-install TOML patch
The original implementation tried to integrate `--set` with the prompt /
result-template / schema-strict-partition system: pre-seeding answers,
filtering questions, evaluating function defaults, tracking override
keys for partition exemption, mirroring carry-forward in two collection
helpers, threading state through Config + ui.js + collection helpers +
manifest writer. ~900 lines spawned across 4 review rounds, with bugs
the bots kept finding because every change touched a different layer.
The simpler model: `--set` is a post-install patch. The installer runs
its normal flow untouched, then `applySetOverrides` upserts each value
into `_bmad/config.toml` (team scope) or `_bmad/config.user.toml` (user
scope) AND into `_bmad/<module>/config.yaml` so declared keys carry
forward via the existingValue path on the next install.
What gets ripped out
- All `setOverrides` plumbing through OfficialModules (constructor
field, applyOverridesAfterSeeding, _trackUnknownKeysAsOverrides,
declaredResultKeys, override classification + pre-write +
question-filter + two-pass function-defaults + carry-forward in
collectModuleConfig, _trackUnknownKeysAsOverrides calls in
collectModuleConfigQuick, headless-branch additions in
Installer.build). official-modules.js reset to its pre-#1663 baseline
(commit
|
||
|
Brian Madison
|
8ab1de8501 |
fix(installer): forward-compat --set keys survive quick-update reinstalls
Found via end-to-end smoke test, not flagged by either bot review: `--set bmm.future_thing=x` was persisted to config.toml on install #1 but silently dropped on the next quick-update reinstall, even though the per-module _bmad/bmm/config.yaml retained it. The central manifest's schema-strict partition stripped it because collectModuleConfigQuick (the quick-update helper) never populated setOverrideKeys for carried-forward unknown keys, and quickUpdate's installConfig didn't thread setOverrideKeys into the install call. This is the same bug class as the round-1 fix to collectModuleConfig (CodeRabbit major #3155145084) but for the quick-update code path, which has a separate collection helper. Fix: - Add OfficialModules._trackUnknownKeysAsOverrides(moduleName, schema) helper that walks collectedConfig[moduleName] and adds any non-schema key to setOverrideKeys[moduleName]. Without a schema, every key is treated as unknown (safe fallback for modules with no module.yaml). - Call it from all four return paths in collectModuleConfigQuick: no-schema, parse-failed, hasNoConfig+subheader, silent+no-new-keys, and the regular end-of-method. - Mirror ui.collectModuleConfigs's setOverrideKeys conversion in installer.quickUpdate so the Set→array round-trip lands in Config.build, and writeCentralConfig sees the exemption list. Tests: +4 cases — collectModuleConfigQuick carry-forward of unknown key, declared-key non-tracking under quick-update, and _trackUnknownKeysAsOverrides no-schema fallback. Total 351 passing. E2E smoke verified: --set <unknown>=x survives install→quick-update, install→regular-update, and install→quick-update→regular-update with a new --set added. |
||
|
Brian Madison
|
7ad054f0e9 |
fix(installer): address fourth-round PR #2353 review comments
(1) Use process.exitCode instead of process.exit() after --list-options
write (CodeRabbit major). process.exit() forces immediate termination
even with pending I/O, which can truncate buffered writes when stdout
is piped or captured by CI. Await the write callback, set exitCode,
and return so the event loop drains naturally.
(2) Thread setOverrides through Config → OfficialModules.build for
headless callers (CodeRabbit major). Non-UI entry points (direct
installer.install({...}) without going through ui.collectModuleConfigs)
previously got an empty override map. Config now carries setOverrides
and the headless branch of OfficialModules.build also runs
loadExistingConfig + applyOverridesAfterSeeding('core') to mirror the
UI path's semantics. The UI path is unaffected because it takes the
moduleConfigs early-return.
(3) Evaluate function defaults under skipPrompts and accept-defaults
paths (CodeRabbit major). Both branches were dropping function defaults
silently, so any same-module dynamic default (`{other_key}` placeholder
in default:) disappeared under --yes. Two-pass: write non-function
defaults first so the answer bag is populated, then call function
defaults with that bag. Try/catch around the call surfaces resolution
failures as warnings instead of crashing the install.
(4) Track result-only schema keys as declared (Augment medium). A
schema entry with `result:` and no `prompt:` was being classified as
"unknown" when targeted by --set, producing a wrong warning and
overwriting the computed template output with the raw value. Added
declaredResultKeys parallel to declaredPromptKeys; an override on
either is now seeded as the answer so the result template still
renders ({value} substitution preserved). Carry-forward block
refactored to consume the same set.
(5) Diagnose non-object module.yaml under --list-options (Augment low).
The non-object branch silently flipped moduleScopedFailure with no
output. Now emits "module.yaml is not a valid object (got <type>)"
mirroring the catch branch, and the type guard also catches arrays
which typeof reports as 'object'.
(6) Reword --list-options doc cache scope (CodeRabbit minor).
"Installed at least once on this machine" → "currently cached official
modules" with a note that cache can be cleared or absent on ephemeral
CI workers — accurately reflects what the command can discover.
Tests: +4 cases — Config.build setOverrides threading and default,
formatOptionsList non-object yaml diagnostic and ok:false. Total 347
passing.
|
||
|
Brian Madison
|
fb57c81176 |
fix(installer): address third-round PR #2353 review comments
(J) Prototype pollution guard (CodeRabbit major).
`--set __proto__.x=1` previously mutated Object.prototype because
`overrides.__proto__` returned Object.prototype on a plain object,
and assigning `[key]=value` polluted every plain object in the process.
Verified the attack reproduces on
|
||
|
Brian Madison
|
ce12cc1a7f |
fix(installer): address second-round PR #2353 review comments
(A) Carry forward unknown core keys in applyOverridesAfterSeeding (CodeRabbit major). Mirrors collectModuleConfig's carry-forward so the skip-collection path used by core (when seeded by --yes / legacy shortcuts) doesn't drop unknown keys on subsequent installs. Without this, `--set core.future=x` on run #1 would silently disappear on the next install. (B) --list-options now exits non-zero on a single-module miss (CodeRabbit major). formatOptionsList returns { text, ok }; install.js exits 1 with text on stderr when ok=false, 0 with text on stdout otherwise. CI scripts catch typos like `--list-options bmn`. (C) Hermetic Suite 44 discovery tests (CodeRabbit minor). Point BMAD_EXTERNAL_MODULES_CACHE at a temp dir and restore in a finally block so test results don't depend on the developer / CI cache state. (D) Case-insensitive --list-options filter (Augment). Discovery already dedupes case-insensitively; the filter now matches the same way, so `--list-options BMM` and `--list-options bmm` both find the bmm built-in. Tests: +7 cases (uppercase listing, ok flag, core carry-forward). Total 340 passing. |
||
|
Brian Madison
|
f1c9e12618 |
fix(installer): address PR #2353 review comments
Carry forward unknown --set keys across upgrades (CodeRabbit major). Without this, an unknown key like --set bmm.future_thing=hello landed in config.toml on run #1 but was silently dropped on the next install because collectModuleConfig rebuilds collectedConfig from prompt answers only. collectModuleConfig now copies any non-declared keys from _existingConfig into collectedConfig and tracks them in setOverrideKeys so the manifest writer's schema-strict partition keeps them. Guard single-select rendering with Array.isArray (CodeRabbit major): a malformed truthy non-array would have aborted --list-options. Unify core override handling: move the inline post-collection block from ui.js into OfficialModules.applyOverridesAfterSeeding so core and non-core take a single validated path. Removes duplicated schema-load logic and inline requires from ui.js. Remove dead code: findOfficialModuleYaml and readDeclaredKeys in set-overrides.js were exported but never imported. Drop them and their path/fs/yaml/project-root imports — the module is now pure string-parsing with zero deps. Doc fix: change "silently ignored" to "ignored with a warning" for the --action quick-update note (Augment + CodeRabbit). Polish: clearer flag placeholder (--set <module.key=value> instead of the misleading <key=value>), trim-asymmetry rationale comment in parseSetEntry, dedupe rationale in list-options. Tests: +6 cases — collectModuleConfig --set application end-to-end (prompt-skip with template rendering), and carry-forward of unknown keys from _existingConfig. Total 333 passing. |
||
|
Brian Madison
|
f33d251790 |
feat(installer): add --set and --list-options for non-interactive config (#1663)
`--set <module>.<key>=<value>` (repeatable) sets any module config option non-interactively. Scales to every module without growing the CLI surface per option, and persists into _bmad/config.toml so values survive upgrades. `--list-options [module]` prints every available --set key for built-in and locally-cached official modules (community/custom users read their own module.yaml). Pass a module code to scope the listing. Validation rules, all non-fatal: - Module not in --modules → warn and drop the value. - Key not declared in module.yaml → warn but persist (forward-compat). The manifest writer's schema-strict partition exempts these so they survive into config.toml even though the schema doesn't know them. - Malformed --set syntax → exit non-zero up front. The legacy core shortcuts (--user-name, --output-folder, etc.) remain supported as aliases for `--set core.<key>=<value>`. --set with --action quick-update is ignored with a warning since quick-update preserves the existing answers by design. Files: - tools/installer/set-overrides.js (new): parser - tools/installer/list-options.js (new): discovery + formatter - tools/installer/commands/install.js: flags + early validation - tools/installer/ui.js: parse, warn-on-unselected, thread to OfficialModules - tools/installer/modules/official-modules.js: pre-fill answers, persist unknowns - tools/installer/core/config.js + installer.js: carry setOverrideKeys through - tools/installer/core/manifest-generator.js: partition exempts override keys - test/test-installation-components.js: +15 cases (Suite 44) - docs/how-to/install-bmad.md, README.md: --set as preferred non-interactive path Closes #1663 |
||
|
Brian
|
48a7ec8bff |
fix: align bmad-help.csv with documented schema and clean up source rows (#2278) (#2349)
* 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). |
||
|
Brian
|
3da984a491 |
fix(config): promote project_name to core (closes #2279) (#2348)
* 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. |
||
|
Brian
|
815600e4ca |
fix(create-architecture): unprime step-07 validation checklist (#2292) (#2347)
step-07-validation template shipped with all 16 completeness checkboxes pre-checked and Overall Status hard-coded to READY FOR IMPLEMENTATION, defeating the gate. Reset checkboxes to unchecked, replace status with a templated choice tied to the checklist and gap analysis, and instruct the agent to only mark items the validation actually confirms. Closes #2292 |
||
|
Brian
|
7ee5fa313b |
fix(installer): require --tools for fresh --yes installs; remove --tools none (#2346)
* fix(installer): require --tools for fresh --yes installs; remove --tools none (closes #2326) Fresh non-interactive installs without --tools previously produced a config-only install (~35 files vs ~1400 in the manifest) with no warning and a "BMAD is ready to use" success card, leaving slash commands unreachable. --tools none was an explicit opt-in for the same broken state. Now: fresh install + -y without --tools throws a helpful error pointing at --list-tools. --tools none is rejected as an unknown ID. Empty and typo'd tool IDs are also rejected. Existing-install paths (--action update, quick-update, modify) are unchanged - they continue to reuse previously-configured tools when --tools is omitted. Adds --list-tools flag that prints all 42 supported tool IDs (id, name, target_dir, preferred star) sourced from platform-codes.yaml. English docs updated; localized docs (vi-vn, fr, cs, etc.) will sync via the normal translation pass. * fix(installer): address review for #2326 — single source of truth, drop dead code, add tests - Refactor formatPlatformList to use IdeManager so --list-tools and --tools validation see the same set of platforms. Eliminates the drift where suspended platforms appeared in --list-tools but were rejected at validation. - Drop unused getValidPlatformIds export. - Flatten redundant block scope around the throw in the --yes-without-tools branch (refactor leftover). - Drop dead String() defensive cast (Commander always passes a string). - Add Test Suite 42: 8 unit tests covering _parseToolsFlag empty/whitespace/ unknown/typo cases plus an integration check that --list-tools output and --tools validation agree on the ID set. * fix(installer): close --tools "" bypass and drop hardcoded tool count - Replace truthy `if (options.tools)` guard with `!== undefined` in both upgrade and fresh-install branches. Empty string now reaches _parseToolsFlag and produces the specific "passed empty" error instead of falling through to a generic message (fresh-install) or being silently ignored (existing-install). - Drop the hardcoded "42 supported tools" count from the prereqs in install-bmad.md so the doc doesn't drift as platform-codes.yaml changes. Addresses augment / coderabbit review on #2346. |
||
|
Jérôme Revillard
|
3e89b30b3c |
fix: use full update path when --custom-source is passed with --yes (#2336)
* fix: use full update path when --custom-source is passed with --yes When --yes is used on an existing install, the installer auto-selects quick-update. However, quick-update never re-clones custom module repos — it only reads whatever is already in the cache. This means --custom-source with a new version tag (e.g. @1.1.0) is silently ignored and the previously cached version (e.g. 1.0.1) is reported as "already up to date". Default to the full update path when --custom-source is present, so the custom repo gets re-cloned at the requested version. Also ensure all installed modules are included in the selection when --yes is combined with --custom-source, preventing previously installed modules from being removed. * fix: address review feedback on choices.find() and comment clarity * style: prettier fix for empty-body methods in custom-module-manager --------- Co-authored-by: Brian <bmadcode@gmail.com> |
||
|
LanyGuan
|
b4d73b7daf |
Fix installer custom modules http (#2344)
* fix(installer): preserve http protocol in custom module clone URLs Previously, parseSource() hardcoded 'https://' when building cloneUrl, forcing http:// Git URLs (e.g., internal LAN hosts) to upgrade to https. This broke cloning for self-hosted Git servers that only serve over HTTP. - Capture the protocol from the regex match instead of discarding it - Update JSDoc and inline comments to document HTTP support - Update install-custom-modules docs (EN, ZH, VN) to list HTTP URL type Fixes the --custom-source flag for http:// addresses. * docs(installer): update JSDoc to mention HTTP support in cloneRepo Add HTTP to the cloneRepo method's JSDoc param description. Also fixes minor spacing in empty arrow functions (formatting). * docs(installer): fix JSDoc annotation for cloneRepo param Correct @param backtick escaping in cloneRepo JSDoc. Also documents HTTP as a supported protocol alongside HTTPS and SSH. --------- Co-authored-by: 关惠民 <9155544@qq.com> |
||
|
Brian
|
6ff74ba662 |
fix(installer): route community installs through PluginResolver when marketplace.json ships (#2331)
* fix(installer): route community installs through PluginResolver when marketplace.json ships Community-catalog installs ignored .claude-plugin/marketplace.json, so modules that nest module.yaml inside a setup skill's assets/ directory (e.g. Strategy 2 in PluginResolver) ended up half-installed: only module-help.csv and the generated config.yaml landed in _bmad/<code>/, while the actual skill source trees and module.yaml never got copied. The install would silently emit "could not locate module.yaml" warnings and leave .agents/skills/ without the module's skills. The fix wires the existing PluginResolver onto the community path: - CommunityModuleManager.cloneModule now detects marketplace.json after the clone+ref-checkout completes and runs PluginResolver. The resolution is stamped with channel/sha/registryApprovedTag/registryApprovedSha and cached in _pluginResolutions, mirroring the existing _resolutions cache. - OfficialModules.install consults the community plugin resolution and delegates to installFromResolution (the same code path custom-source installs already use). installFromResolution branches on communitySource to write source: 'community' with the registry's approved tag/sha and channel. - resolveInstalledModuleYaml now searches the community-modules cache root in addition to the external-modules cache, and the BMB setup-skill detector walks src/skills/ and skills/ (not just the repo root) so collectAgents FromModuleYaml and writeCentralConfig can find module.yaml in nested marketplace-plugin layouts. Backward compatibility: repos without marketplace.json (e.g. WDS, which declares module_definition: src/module.yaml at the root) continue through the legacy findModuleSource path with no behavior change. Verified against the live zarlor/suno-band-manager community module and a 23-check fixture suite covering Suno-shape, WDS-shape, and bare-repo layouts. * fix(installer): harden community marketplace.json resolution path Address review feedback on the community marketplace.json install path: - Wrap PluginResolver.resolve() in try/catch so a malformed plugin entry falls through to the legacy install path with a warn instead of crashing cloneModule. - Stop mutating the resolver's return object; shallow-clone before stamping community provenance so install state cannot leak back into resolver-owned objects. - Warn when _selectPluginForModule lands on the single-plugin fallback with a name that doesn't match the registry code or module_definition hint, so a misconfigured marketplace.json can't silently install the wrong plugin. - Add CommunityModuleManager.resolveFromCache() and call it from OfficialModules.install() when the in-process plugin cache is empty, so callers that reach install() without pre-cloning still get the marketplace-aware path. Reuses an existing channel resolution when present, otherwise synthesizes a stable-channel stub from the registry entry plus the cached repo's HEAD. - Align installFromResolution()'s returned versionInfo.version with manifestEntry.version precedence (communityVersion || cloneRef || ...) so downstream summaries match what was written to the manifest. Tests: lint, format:check, lint:md, test:install (290), test:channels (83), test:refs (7) all green. |
||
|
AJ Côté
|
1ad1f91e38 |
feat(workflows): add brownfield epic scoping to detect file churn (#1823) (#1826)
Add design completeness gate, file overlap check, and validation to prevent unnecessary file churn when epics target the same component. |
||
|
Brian
|
350688df67 |
fix(installer): resolve url-source custom modules from custom-modules cache (#2323)
* fix(installer): resolve url-source custom modules from custom-modules cache resolveInstalledModuleYaml previously only searched ~/.bmad/cache/external-modules/, so modules installed via --custom-source <git-url> (cached at ~/.bmad/cache/custom-modules/<host>/<owner>/<repo>/) could not be located on re-install runs. This caused warnings during npx bmad-method install: [warn] collectAgentsFromModuleYaml: could not locate module.yaml for '<name>' [warn] writeCentralConfig: could not locate module.yaml for '<name>' Adds a fallback that walks the custom-modules cache via _findCacheRepoRoots (identifying repo roots by .bmad-source.json or .claude-plugin/, not marketplace.json, so direct-mode modules are also covered), reuses the same searchRoot candidate-path logic, and matches by the discovered yaml's code or name field. Works without needing _resolutionCache to be populated, which fixes the re-install scenario where no --custom-source flag is passed. Closes #2312 * fix(installer): enumerate all module.yamls when walking custom-modules cache A url-source custom-modules repo can host multiple plugins in discovery mode (e.g. skills/module-a/module.yaml and skills/module-b/module.yaml). The previous walk used searchRoot which returned only the first match, so asking for module-b would surface module-a's yaml, fail the code/name check, and skip the repo entirely — never inspecting module-b. Splits the candidate-path traversal into searchRootAll (returns every module.yaml in priority order) and a thin searchRoot wrapper for the existing single-module fallbacks. The custom-modules walk now iterates every yaml per repo and matches each against code or name. |
||
|
Curtis Ide
|
be85e5b4a0 |
fix(installer): support local custom-source modules in resolveInstalledModuleYaml and TOML key (#2316)
- resolveInstalledModuleYaml: fall back to CustomModuleManager._resolutionCache for local custom-source modules (external cache path doesn't exist for these); refactor candidate-path search into shared searchRoot() helper; add *-setup/assets/module.yaml BMB standard path - manifest-generator: use module code field (not display name) as TOML section key [modules.X] Co-authored-by: cidemaxio <cidemaxio@users.noreply.github.com> |
||
|
Brian
|
04cfde1454 |
fix(installer): mirror launch channel as default for external modules (#2321)
* fix(installer): mirror launch channel as default for external modules When the user runs `npx bmad-method@next install`, the installer itself runs from a prerelease, but the interactive channel gate previously hardcoded "(all stable)" — defaulting tea/community modules to stable while bmad-method itself was on next. The bleeding-edge launch did not flow through. Detect the installer's own version via semver.prerelease() and default the gate (and per-module picker) to match — "all next" for prerelease launches, "all stable" for stable. Users keep full control: hit "n" to customize per module, or pass explicit --channel / --pin / --next flags to override. * fix(installer): seed channelOptions before module picker, not gate CodeRabbit caught a label/install mismatch in the previous approach: the module picker resolves version labels via decideChannelForModule, which runs before _interactiveChannelGate. With channelOptions.global still null at picker time, labels rendered from stable tags — then the gate flipped global to 'next' and externals installed from main HEAD. Net effect on @next launches: "tea (v1.6.0)" in the picker, but install pulled HEAD. Move the launch detection up into promptInstall, immediately after parseChannelOptions. Seeding channelOptions.global = 'next' before the picker makes labels resolve from main HEAD (matching the install) and lets the existing gate's haveFlagIntent check skip cleanly — the @next user already declared their intent by typing it. Per-module customization remains available via --pin / --next / --channel flags, same as for any pre-set global. |
||
|
Brian
|
7baa30c567 |
fix(publish): advance @next dist-tag after stable release (#2320)
* fix(publish): advance @next dist-tag after stable release When a stable release publishes via workflow_dispatch, @latest can leapfrog the existing @next prerelease (e.g. latest=6.5.0 while next=6.4.1-next.0), turning `npx bmad-method@next install` into a silent downgrade until the next qualifying push to main republishes a fresh -next.0. - publish.yaml: after stable publish, repoint @next at the just-published stable version. The existing derive-prerelease step picks max(latest, next) as its base, so subsequent push-driven prereleases bump from there. - bmad-cli.js: checkForUpdate was querying the @beta dist-tag (which this package does not use). Replace string-matching with semver.prerelease() and query @next for prerelease users. * fix(publish): harden next-tag advance step and broaden path filter - continue-on-error on the dist-tag advance: failure leaves @next stale until the next push-driven prerelease, which is recoverable; failing the job after a successful publish + git tag + GH release is not. - Status echo so release-log triage can confirm the advance ran. - Add removals.txt to the push-trigger path filter. Installer-affecting changes outside src/** (like the post-6.5.0 removals.txt fix) should still trigger a fresh -next.0 publish. |
||
|
Brian
|
88b9a1c842 |
fix(installer): remove pre-v6.2.0 wrapper skills on update (closes #2309) (#2315)
Adds 32 entries to removals.txt covering the module-prefixed wrapper skill names used pre-v6.2.0 (bmad-bmm-* and bmad-agent-bmm-*). Users upgrading from v6.0.x / v6.1.x had these installed in their IDE skill directories, but the v6.2.0 architecture switch dropped the module prefix and the cleanup never knew the old names. Stale wrappers stayed behind alongside the new self-contained skills, causing duplicates and broken-file errors when invoked (referenced files no longer exist). The removals.txt entries get added to the cleanup removalSet on every install/update, so the next install run for an upgrading user removes the stale wrappers automatically. |
||
|
github-actions[bot]
|
69cbeb4d07 | chore(release): v6.5.0 [skip ci] v6.5.0 | ||
|
Brian
|
1d35acfd84 | docs: add v6.5.0 changelog entry (#2314) | ||
|
Brian
|
01cc32540b |
feat(installer): expand to 42 platforms with shared target_dir coordination (#2313)
* refactor(installer): replace legacy_targets auto-cleanup with upgrade warnings Removes the legacy_targets YAML field and its install-time auto-migration of pre-v6.1.0 directories (.claude/commands, .opencode/agents, etc.). On install, surface a warning instead: read manifest version and scan 24 known legacy paths, then print rm -rf commands the user can run themselves. Also deletes orphan tools/platform-codes.yaml (never loaded by any code) and fixes a stale URL in the cs translation. * feat(installer): consolidate to .agents/skills and add global_target_dir for all platforms Updates platform-codes.yaml against verified primary docs for all 24 supported platforms. 14 platforms (auggie, codex, crush, cursor, gemini, github-copilot, kilo, kimi-code, opencode, pi, roo, rovo-dev, windsurf) move their project target_dir to the cross-tool .agents/skills/ standard. Junie moves from the broken .agents/skills/ to its own .junie/skills/ per JetBrains docs. Adds global_target_dir to every platform: 11 share ~/.agents/skills/, Crush uses XDG ~/.config/agents/skills/, Codex global stays ~/.codex/skills/, the rest are tool-specific. Ona and Trae omit global (no documented home path). Note: installer logic does not yet dedupe writes for platforms sharing a target_dir — users installing multiple .agents/skills/ tools together will overwrite the same files (harmless on install, but uninstalling one clears the dir for the others). Coordination logic is the next step. * feat(installer): add 18 new platforms, dedup shared target_dir, ownership-aware cleanup Adds 18 platforms from the verified Vercel list (adal, amp, bob, command-code, cortex, droid, firebender, goose, kode, mistral-vibe, mux, neovate, openclaw, openhands, pochi, replit, warp, zencoder). Marks codex and github-copilot as preferred alongside claude-code and cursor. Coordination for platforms sharing a target_dir: - IdeManager.setupBatch dedups skill writes when multiple selected platforms point at the same target_dir (e.g. .agents/skills/). The first platform writes, peers skip the redundant wipe-and-rewrite. Result reports the same count and target dir for every member so the install summary is consistent. - IdeManager.cleanupByList accepts remainingIdes; when removing one platform from a shared dir while another co-installed platform still owns it, the target_dir wipe is skipped. Platform-specific hooks (copilot markers, kilo modes, rovodev prompts) still run. - _setupIdes uses setupBatch; _removeDeselectedIdes passes remainingIdes so partial reconfigure preserves shared skills. Skill ownership now uses skill-manifest.csv canonicalIds, not the bmad- prefix. This unblocks custom modules that ship skills with non-bmad names (e.g. fred-cool-skill). Affected sites: - _config-driven.detect: reads canonicalIds from the project's bmadDir - _config-driven.findAncestorConflict: reads canonicalIds from the ancestor's own bmadDir, falling back to the prefix only when no manifest exists - legacy-warnings.findStaleLegacyDirs: same canonicalId-based detection Migration warnings: LEGACY_SKILL_PATHS adds 12 skill dirs that moved to the .agents/skills/ standard (cursor, gemini, github-copilot, kimi, opencode, pi, roo, rovodev, windsurf, plus their globals). Users with stale skills in those locations get a one-line warning with the rm command per dir. New shared helper tools/installer/ide/shared/installed-skills.js exposes getInstalledCanonicalIds(bmadDir) and isBmadOwnedEntry(entry, canonicalIds). Tests: 9 new assertions across two suites covering dedup, partial uninstall preservation, and custom-module skill detection. All 286 tests pass. * fix(installer): setupBatch must not claim a shared target_dir on failure If the first platform's setup throws or returns success: false, the dedup map previously still recorded the claim with skillCount: 0, causing every peer sharing the target_dir to skip its install — leaving the dir empty/broken behind a cascade of misleading "shares with X" rows. Now the claim is only recorded when the install succeeded and wrote skills. On failure, the next peer becomes the new first writer and recovers. Adds Suite 40b regression test that monkey-patches cursor.setup to throw and verifies gemini still populates the shared dir. * fix(installer): address PR #2313 review findings Three issues raised by augmentcode and coderabbit bot reviewers: 1. _removeDeselectedIdes silently swallowed cleanup failures after the refactor to cleanupByList. The old per-IDE try/catch logged a warning; the new path discarded the result array. Now logs a warning per failed ide so failures stay visible. 2. The legacy-dir cleanup hint printed `rm -rf "<path>"/bmad*` which both matched bmad-os-* utility skills the user should keep AND missed the custom-module skills (e.g. fred-cool-skill) that the new canonical-id detection now finds. Findings now carry the exact entry names from the scan, and the warning prints one precise rm line per entry. 3. warnPreNativeSkillsLegacy did unguarded fs reads at install start. A permission/IO error would have aborted the whole install. Wrapped the call site in try/catch so legacy-scan failures only emit a warning. |
||
|
github-actions[bot]
|
1197122001 | chore(release): v6.4.0 [skip ci] v6.4.0 | ||
|
Brian
|
314fe69d14 | docs: add v6.4.0 changelog entry (#2310) | ||
|
Yahya Bin Naveed
|
9ff9d6f8f3 |
feat: add Kimi Code CLI support (#2302)
Adds kimi-code to both platform-codes.yaml files so Kimi Code CLI is available as an install target via the config-driven installer. Skills are installed to .kimi/skills/, which is the project-level skills directory per the official Kimi Code CLI documentation. Closes #1630 Co-authored-by: Brian <bmadcode@gmail.com> |
||
|
Pablo Ontiveros
|
c29b72ecc0 |
fix(create-story): read UPDATE files before generating dev notes (#2274)
When a story modifies existing files, create-story must read those files before generating dev notes. Without this, dev agents improvise design decisions without knowing the current state of the code, leading to regressions caught only at review time. Adds a step at the end of Step 3 (Architecture analysis) that reads every file marked UPDATE in the architecture directory structure and documents its current state, what the story changes, and what must be preserved. Fixes #2273 Co-authored-by: Brian Madison <bmadcode@gmail.com> |
||
|
Jérôme Revillard
|
e7a213ed07 |
feat: uniform customize.toml support across all BMM workflows (#2308)
* feat: extend customize.toml to all 6 developer-execution workflows (#2303) Add uniform customization support to dev-story, code-review, sprint-planning, sprint-status, quick-dev, and checkpoint-preview, matching the same 4 extension points (activation_steps_prepend, activation_steps_append, persistent_facts, on_complete) already available on 17 BMM workflows from PR #2287. - Create customize.toml for each workflow - Add 6-step activation block to SKILL.md (merge workflow.md content in, delete workflow.md per PR #2287 pattern) - Wire on_complete at terminal steps (inline <action> for XML workflows, ## On Complete section for step-file workflows) - Fix pre-existing step number reference in dev-story (Step 6 → 9) * fix: correct goto step="6" → step="9" in dev-story The XML goto at line 203 still pointed to step 6 ("Author comprehensive tests") instead of step 9 ("Story completion and mark for review"), which is the actual completion gate. This was the same class of pre-existing bug fixed in the text (M-1) but missed in the XML action. --------- Co-authored-by: Brian <bmadcode@gmail.com> |
||
|
Murat K Ozcan
|
0533976753 |
fix: installer live version for external modules (#2307)
* resolved merge conflict * fix: addressed PR comments * fix: use git tags for installer module versions |
||
|
Brian
|
3d824d4c0f |
feat(installer): channel-based version resolution + interactive channel management (#2305)
* feat(installer): channel-based version resolution for external modules Adds stable/next/pinned channel resolution so external/community modules install at released git tags by default instead of tracking main HEAD. Manifest now records channel, resolved version, and SHA per module for reproducible installs. CLI flags: --channel, --all-stable, --all-next, --next=CODE (repeatable), --pin CODE=TAG (repeatable). Precedence: pin > next > channel > registry default > stable. --yes accepts patch/minor upgrades but refuses majors. Interactive "Ready to install (all stable)?" gate with a per-module picker (stable/next/pin) when declined. Re-install prompts classify tag diffs as patch/minor/major with semver-class-dependent defaults. Legacy version:null manifests get a one-time migration prompt. Custom modules gain an optional @<ref> URL suffix for pinning (https, ssh, /tree/<ref>/subdir forms supported; local paths rejected). Community modules honor --next/--pin overrides with a curator-bypass warning; default path still enforces the approved SHA. Quick-update now reads the manifest's recorded channel per module so pinned installs don't silently roll forward. * feat(installer): interactive channel switch, upgrade refusal, unified docs Builds on the channel-resolution foundation. The installer now lets users flip a module between stable, next, and pinned after install — either interactively via a "Review channel assignments?" gate, or by flag. Quick and modify re-installs classify stable upgrades; under non-interactive flows, patches and minors apply automatically but majors are refused with a pointer to --pin. Fallback behavior for GitHub rate-limit / network failures is now cache- aware: re-installs reuse the recorded ref silently; fresh installs abort with actionable guidance (set GITHUB_TOKEN or use --next/--pin). Bundled modules (core, bmm) warn when targeted by --pin or --next so users aren't left wondering why the flag had no effect. Install summary labels no longer mangle "main" into "vmain"; next-channel entries render as "main @ <short-sha>" instead. Bundled modules are now correctly skipped from all channel prompts and tag-API lookups. Docs consolidated into a single how-to. install-bmad.md now covers the interactive flow, the channel model (stable/next/pinned plus the npm dist-tag axis for core/bmm), the re-install upgrade prompts, the full flag reference, copy-paste recipes, and troubleshooting. The old non-interactive-installation.md is reduced to a redirect stub. * fix(installer): review fixes + unit tests for channel resolution - ui.js: import parseGitHubRepo; fixes ReferenceError in the interactive channel picker's stable-tag pre-resolve path. - community-manager: pinned modules now fetch+checkout the pin tag on cache refresh instead of resetting to origin/HEAD (was silently drifting to main on re-install). - channel-plan: parseChannelOptions returns acceptBypass so --yes auto-confirms the curator-bypass prompt; headless --next/--pin installs of community modules no longer hang. - community-manager: simplify recordedVersion (dead ternary branch). - custom-module-manager: drop "or sha" from the @<ref> comment (git clone --branch rejects raw SHAs); update-path fetches origin <ref> so /tree/<branch>/ URLs work too. - install-bmad.md: rename "Headless / CI installs" to "Headless CI installs" so the stub's #headless-ci-installs anchor resolves. - test/test-installer-channels.js: 83 unit tests for channel-plan and channel-resolver pure modules; wired into npm test as test:channels. * fix(installer): address CodeRabbit review findings - ui.js: skip stable-channel upgrade classification when the user has already declared intent via --pin/--next=/--channel or the review gate. Prevents the decline / major-refused / fetch-error branches from silently overwriting an explicit pin with prev.version. - external-manager.js: short-circuit cloneExternalModule when the requested plan matches an existing in-process resolution and the cache is valid. Avoids redundant resolveChannel() + git fetch on every same-plan lookup in a single install. - installer.js: fall back to CommunityModuleManager.getResolution() when no external resolution exists, so community module result rows carry newChannel/newSha instead of null under --next/--pin. - installer.js: don't label a module as "no change" when its version string is 'main'/'HEAD' — the SHA may have moved and preVersions doesn't track the prior SHA. Show "(refreshed)" instead. - official-modules.js: match versionInfo.version to the manifest's cloneRef || (hasGitClone ? 'main' : version) expression so summary lines report the cloned ref for git-backed custom installs. - install-bmad.md: clarify that sha is only written for git-backed modules and that rerunning the same --modules on another machine does not reproduce stable-channel installs — convert recorded tags into explicit --pin flags for cross-machine reproducibility. |
||
|
Murat K Ozcan
|
2395b0e2ed |
fix: bmad tea instal version (#2298)
* fix: bmad tea instal version * fix: addressed review comments |
||
|
Brian
|
914c4edd6b |
fix(installer): resolve external-module agents from cache during manifest write (#2295)
External official modules (bmb, cis, gds, tea, wds) are cloned to ~/.bmad/cache/external-modules/<name>/ and never copied into src/modules/, so collectAgentsFromModuleYaml silently skipped them and their agents never reached config.toml. Swap the hardcoded src/modules lookup for a resolveInstalledModuleYaml() helper that also searches the external cache (handling src/, skills/, nested, and root layouts) and warns instead of silently skipping when a module.yaml can't be found. |
||
|
miendinh
|
16c9976d7e |
docs(vi-vn): sync and update Vietnamese documentation (#2291)
Co-authored-by: miendinh <miendinh@users.noreply.github.com> |
||
|
Brian
|
87292cd86a |
feat(skills): wire on_complete into terminal steps; add full customize.toml comments (#2290)
All 16 bare workflow customize.toml files now have the same thorough comment block as the well-documented ones, with skill-specific on_complete descriptions that name the exact terminal step and exit condition. on_complete is now executed at the true end of each workflow's terminal step rather than lazily referenced in SKILL.md: - Linear workflows: ## On Complete block appended to the final step file (create-prd step-12, create-ux-design step-14, create-architecture step-08, generate-project-context step-03, check-implementation-readiness step-06, epics-and-stories step-04, all three research step-06 files, prfaq verdict, document-project both sub-workflow instruction files) - Multi-path workflows: on_complete inline on each true exit path only (edit-prd fires on [S] Summary and [X] Exit, not on [V] Validate or [E] Edit; validate-prd fires on [X] Exit only, not on [R], [E], or [F]) - Inline XML workflows: <action> tag at the close of the final step (correct-course step-6, create-story step-6, retrospective step-12, qa-generate-e2e-tests appended to SKILL.md) |
||
|
Brian
|
b63086f22e |
feat(core-skills): add bmad-customize — guided authoring for _bmad/custom overrides (#2289)
* 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. |
||
|
Brian
|
ffdd9bc69e |
feat(skills): add TOML workflow customization to 17 bmm-skills (#2287)
* feat(skills): add TOML workflow customization to 17 bmm-skills
Flattens each skill's workflow.md into SKILL.md and adds a customize.toml
surface with a 6-step activation block (resolve_customization, prepend,
persistent_facts, config, greet, append). Core-skills and developer
execution skills (dev-story, code-review, sprint-planning, sprint-status,
quick-dev, checkpoint-preview) are intentionally excluded.
Customized: document-project, prfaq, domain/market/technical-research,
create-prd, create-ux-design, edit-prd, validate-prd,
check-implementation-readiness, create-architecture,
create-epics-and-stories, generate-project-context, correct-course,
create-story, qa-generate-e2e-tests, retrospective.
* fix(skills): address PR review findings on workflow customization
- bmad-create-story: drop stale {project_context} variable reference
from step 2 note; content is already loaded via persistent_facts
- research skills (market/domain/technical): derive research_topic_slug
before writing output filename to prevent path injection and invalid
filesystem characters
- bmad-correct-course: reconcile step 1 verify list and HALT with the
"Missing documents" rule — Architecture and UI/UX are optional, HALT
only fires when PRD or Epics are missing
- fix grammar in Micro-file Design bullets across 5 migrated skills
(self contained → self-contained, adhere too 1 file → adhere to one
file at a time)
- docs/how-to/customize-bmad.md: document workflow activation order
and frame the baseline fields as a stable initial pass with targeted
per-workflow customization points coming later
|
||
|
Brian
|
1251458173 |
feat(agents): set team to software-development on BMM agents (#2286)
* feat(agents): set team to software-development on BMM agents All six BMM agents (analyst, tech-writer, PM, UX designer, architect, dev) now explicitly declare `team: software-development` in the module.yaml roster instead of falling back to the module-code default of `bmm`. This matches the BMad-wide team convention where agents across modules that collaborate on software delivery share one named team. Tea's Murat joins the same team via a parallel PR in bmad-method-test-architecture- enterprise so party-mode, help catalog, and retrospective skills can route the full software-delivery roster as a single unit. * test: update team assertions for explicit software-development |
||
|
Brian
|
4405b817a9 |
refactor(skills): remove bmad-skill-manifest yaml; introduce central config.toml (#2285)
* 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.
|
||
|
Brian
|
0dbfae675b |
feat(skills): TOML-based agent and workflow customization (#2284)
* feat(skills): TOML-based agent customization with stdlib Python resolver Re-applies PR #2282's three-layer customization model (skill defaults → team → user) but swaps YAML for TOML and uv for stdlib tomllib. Users no longer need uv, pip, or a virtualenv — plain python3 (3.11+) is sufficient, since tomllib shipped in the standard library. ## Schema changes vs PR #2282 - Flat agent schema: fields live directly under [agent], no nested metadata/persona sub-tables. Easier to author, less indentation. - Non-configurable identity: name and title are declared in customize.toml as source-of-truth metadata (for future skill-manifest generation) but SKILL.md ignores overrides there — identity is hardcoded to preserve brand recognition. - role redefined: now describes what the skill does for the user within its module phase, not a restatement of the title. - persistent_facts replaces the activation-time file-context load AND the old memories concept. Entries can be literal sentences or file: prefixed paths/globs; avoids collision with the upcoming runtime memory sidecar. - activation_steps_prepend / activation_steps_append harmonized across agents and workflows (replaces agent-specific critical_actions). - [workflow] namespace mirrors [agent] for workflow customization. Same four structural rules, same field vocabulary. ## Resolver (src/scripts/resolve_customization.py) Four purely structural merge rules, zero field-name hardcoding: - Scalars: override wins - Tables: deep merge - Arrays of tables where every item has `code` or `id`: merge by that key (matching keys replace, new keys append) - Any other array: append No removal mechanism — overrides cannot delete base items. Fork the skill or override by code with a no-op value to suppress defaults. ## Agents ported (6) All six BMad agents now ship customize.toml + rewritten SKILL.md: analyst (Mary), tech-writer (Paige), pm (John), ux-designer (Sally), architect (Winston), dev (Amelia). Each uses the same 8-step activation template: resolve → execute prepend → adopt persona → load persistent facts → load config → greet (with {agent.icon}) → execute append → dispatch or present menu. Step 8 supports fast-path invocation: "hey Mary, let's brainstorm" dispatches the matching menu item directly after greeting, skipping the menu render when intent is clear. Chat, clarifying questions, and bmad-help remain available when nothing on the menu fits. ## Installer + tooling - _bmad/scripts/ provisioned on install (copies src/scripts/) - _bmad/custom/ seeded with .gitignore for *.user.toml on fresh install - Non-module-dir filter extended to skip _memory, memory, docs, scripts, and custom when scanning for modules - Dead _config/agents/ directory no longer created - metadata.capabilities removed from agent-manifest.csv and schema - eslint config extended to cover src/scripts/** - validate-file-refs.js knows about custom/ as install-only ## Deferred for follow-up - bmad-product-brief workflow port (the pilot that demonstrates [workflow] + on_complete) - Translated docs (cs/fr/vi-vn/zh-cn) — regenerate from English * feat(skills): port bmad-product-brief to TOML workflow customization Completes the customization surface rollout by giving the product-brief workflow the same override model as the six BMad agents, under the [workflow] namespace instead of [agent]. ## customize.toml Mirrors the agent shape under [workflow] with: - activation_steps_prepend / activation_steps_append (harmonized across agents and workflows — same field names, same append semantics) - persistent_facts with the file: convention, seeded with file:{project-root}/**/project-context.md - on_complete scalar (renamed from PR #2282's skill_end for clarity — reads cleaner as "what runs when the workflow completes") ## SKILL.md 7-step workflow activation: 1. Resolve workflow block 2. Execute prepend steps 3. Load persistent facts (file: or literal) 4. Load config 5. Greet if not already 6. Execute append steps 7. Stage 1 — Understand Intent python3 + stdlib tomllib invocation; no uv required. ## Prompt file changes - Path normalization: ../agents/ → agents/, ../resources/ → resources/, bare foo.md → prompts/foo.md. All references now resolve from the skill root (matches the convention documented in SKILL.md). - Paths: meta-line added to each of the 4 prompt files that reference other files, reinforcing "bare paths resolve from skill root" so the LLM doesn't lose the convention when operating two hops into a prompt chain. - finalize.md terminal stage now calls the resolver for workflow.on_complete — non-empty values run as the final step. ## Validation - Resolver output verified: 4 workflow fields returned cleanly. - validate-file-refs.js: 254 files scanned, 139 refs checked, 0 broken. - test:refs: passing. * docs(skills): enterprise customization recipes + workflow template variable Three independent improvements bundled because they share the same surface (workflow/agent customization) and landed from the same design discussion: ## Fallback sentence disambiguated (7 SKILL.md files) The "if the script fails" fallback used to say `{project-root}/_bmad/ custom/{skill-name}.toml` for the team override and then just `{skill- name}.user.toml` for the user override, leaving the user file's location implicit. LLMs could reasonably guess skill root or project root instead. Replaced with an unambiguous numbered list that spells out the full path for every file in the merge chain. ## Product-brief: stage promotion + brief_template variable - Promoted `## Stage 1: Understand Intent` from a nested step inside "On Activation" to a top-level section. The previous "Step 7: Stage 1 — Understand Intent → Proceed to Stage 1 below" was mechanical numbering pretending to be a step. Activation now ends cleanly at Step 6; Stage 1 is a peer section. - Added `brief_template` as a workflow-level scalar customization defaulting to `resources/brief-template.md`. Stage 4 reads `{workflow.brief_template}` instead of the hardcoded path, so orgs can point at their own template under `{project-root}/...` without forking the skill. ## New doc: docs/how-to/extend-bmad-for-your-org.md Four worked recipes that together cover most enterprise scenarios: 1. Shape an agent across every workflow it dispatches (dev agent + Context7 MCP + Linear search — the highest-leverage pattern) 2. Enforce org conventions inside a specific workflow (product-brief + compliance-field persistent_facts) 3. Publish completed outputs to external systems (product-brief + Confluence + Jira via MCP, gated on user confirmation for Jira) 4. Swap in your own output template (product-brief + brief_template variable swap) Opens with the two-layer mental model (agent spans workflows, workflow is local) so readers pick the right granularity before reading any recipe. Closes with a "Combining Recipes" section showing all four composed. Cross-linked from customize-bmad.md. ## Validation - Resolver: workflow.brief_template returns the default cleanly. - validate-file-refs.js: 254 files scanned, 146 refs checked (+7 from this commit), 0 broken. * docs(skills): encourage CLAUDE.md/AGENTS.md reinforcement of critical rules Added a "Reinforce Global Rules in Your IDE's Session File" section to extend-bmad-for-your-org.md. BMad customizations only load when a skill activates, but IDE session files (CLAUDE.md, AGENTS.md, cursor rules, copilot-instructions) load every turn — worth restating the most critical rules there too so they survive ad-hoc chat outside a BMad skill. Includes a one-line example reinforcing the Recipe 1 Context7 rule, plus a scope table that clarifies what each layer is for: - IDE session file: universal, every session, keep succinct - Agent customization: persona-specific, every dispatched workflow - Workflow customization: one workflow run Emphasizes brevity — noise in the session file crowds out signal. * docs(skills): add Named Agents explanation doc New docs/explanation/named-agents.md walking through the three-legged stool (skills + named agents + customization) with the "Hey Mary, let's brainstorm" activation flow as the narrative thread. Covers: - Why named agents vs menu-driven or prompt-driven alternatives - The 8-step activation flow and what each step contributes - How customization scales the model beyond a single developer - Cross-links to the how-to docs for implementation details Sits alongside brainstorming.md, quick-dev.md, party-mode.md in the explanation folder — feature narratives for users who want to understand why BMad is designed the way it is, not just how to use it. * docs(skills): clarify that keyed-merge requires a single identifier key per array Review feedback (PR #2284) flagged that the merge-rules wording was ambiguous: "every item has a `code` or `id` field" could reasonably be read as "each item individually has at least one of the two", allowing arrays to mix `code` and `id` across items. The resolver has always required all items share the *same* identifier key (all `code`, or all `id`). Mixed arrays fall through to append — intentional, because mixing identifier keys within one array is a schema smell and any guess about which key should merge creates a worse trap than the append-fallback. Clarified in three places: - Merge-rules table in customize-bmad.md: "every item shares the **same** identifier field" - `code`/`id` convention paragraph: "pick **one** convention ... and stick with it across the whole array" - Resolver docstring and `_detect_keyed_merge_field` docstring: explicit note that mixed arrays fall through with rationale No behavior change. * docs(skills): address CodeRabbit review — fallback rules, OS claim, headless greeting 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: rename Extend to Expand throughout customization docs |
||
|
Brian
|
e550df2474 |
Revert "feat(skills): YAML-based agent customization with Python resolver (#2282)" (#2283)
This reverts commit
|
||
|
Brian
|
bd1c0053d5 |
feat(skills): YAML-based agent customization with Python resolver (#2282)
Three-layer customization (skill defaults → team → user) for BMad agents
and any skill that opts in. Users edit `_bmad/custom/{skill-name}.yaml`
(team, committed) or `{skill-name}.user.yaml` (personal, gitignored);
customizations survive updates.
Resolver is a Python script using PEP 723 inline metadata, invoked via
`uv run` so deps auto-install into a cached isolated env on first call.
This aligns with Anthropic's Agent Skills spec and BMB conventions, and
keeps the dependency declared (scannable by pip-audit/Dependabot) rather
than vendored.
## Design choices
- **Agent identity is hardcoded** in SKILL.md (name, title, Overview prose)
so skills can be invoked reliably by role *or* default name. Brand
recognition is preserved; customization shapes behavior, not identity.
- **Luminary-anchored personas** (e.g. "Channels Martin Fowler's
pragmatism and Werner Vogels's cloud-scale realism") deliver ~55%
token savings per agent while preserving distinctive voice beats.
- **Universal per-field merge rules** with v6.1-compatible agent
semantics: metadata shallow-merge, persona replace, critical_actions
and memories append, menu merge-by-code, all else deep-merge.
- **Workflow customization** shares the same surface — `bmad-product-brief`
pilots `activation_steps_prepend`, `activation_steps_append`, and
`skill_end` hooks that any workflow-style skill can adopt.
## Infrastructure
- `_bmad/scripts/` houses shared Python scripts (resolver + future).
- `_bmad/custom/` is provisioned empty with a seeded `.gitignore` for
`*.user.yaml` on fresh installs.
- Installer filters ensure `scripts/`, `custom/`, and sidecar-generated
`memory/` directories are never treated as modules.
- Dead v6.1 code cleaned up: `_config/agents/` no longer created,
`metadata.capabilities` removed from schema and CSV manifest.
|
||
|
Alex Verkhovsky
|
d09363b1b2 |
feat(installer): use GitHub API as primary fetch with raw CDN fallback (#2248)
* feat(installer): use GitHub API as primary fetch with raw CDN fallback Corporate proxies commonly block raw.githubusercontent.com while allowing api.github.com. Add fetchGitHubFile() to RegistryClient that tries the GitHub Contents API first, falling back to the raw CDN transparently. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(installer): cap redirect depth and preserve dual-fallback errors Add maxRedirects parameter to fetch() and _fetchWithHeaders() to prevent unbounded redirect recursion. Wrap CDN fallback in try/catch and throw AggregateError with both API and CDN errors for better diagnostics. Extract marketplace repo coordinates into named constants in external-manager. * chore(installer): drop unused fetchJson and fetchGitHubJson Neither method has any callers. Also drop the corresponding test. * refactor(test): fold registry tests into test-installation-components No reason for RegistryClient tests to be a separate runner — the same file already tests the registry consumers in Suite 33. Drop test:registry from package.json scripts and quality gate. * fix(installer): include URL, API message, and rate-limit info in HTTP errors Non-2xx responses previously yielded bare `HTTP 403`. Now surface the request URL, GitHub's JSON error message (or body snippet), X-RateLimit-Reset when quota is exhausted, and Retry-After. Turns a mystery 403 into 'rate limit exhausted; resets at 2026-04-15T18:00:00Z' — the difference between 'try GITHUB_TOKEN' and a wild goose chase. --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Brian
|
6b964acd56 |
Merge pull request #2254 from lrliang/docs/zh-cn-missing-translations
docs(zh-cn): add missing Chinese translations |
||
|
Brian
|
723bca4e38 | Merge branch 'main' into docs/zh-cn-missing-translations | ||
|
Brian
|
262fa882ef |
Merge pull request #2257 from bmad-code-org/issue-fixes
fix(installer): add missing fs-native exports |
||
|
Brian Madison
|
0f958cf713 |
fix(installer): add missing sync and async methods to fs-native wrapper
Closes #2256 |
||
|
Brian
|
b336cd0987 |
Merge pull request #2255 from bmad-code-org/fix-skill-scanner-recursion
fix(installer): stop skill scanner from recursing into discovered skills |
||
|
Brian Madison
|
9ffb5b80ab |
fix(installer): stop skill scanner from recursing into discovered skills
Skills don't nest. Once the manifest generator finds a valid SKILL.md in a directory, it should not recurse into that skill's subdirectories looking for more skills. Template files (like bmb's setup-skill-template) inside a skill's assets/ would be incorrectly scanned and produce spurious errors. |
||
|
梁山河
|
8ee35aaea3 | Merge branch 'main' into docs/zh-cn-missing-translations | ||
|
Brian
|
5456b26ab7 |
Merge pull request #2253 from bmad-code-org/fix-fs-extra-graceful-fs
fix(installer): replace fs-extra with native node:fs to prevent file loss |