mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-19 08:11:52 +08:00
feat-set-flag-1663
272 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
|
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
|
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
|
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. |
||
|
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
|
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. |
||
|
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. |
||
|
miendinh
|
16c9976d7e |
docs(vi-vn): sync and update Vietnamese documentation (#2291)
Co-authored-by: miendinh <miendinh@users.noreply.github.com> |
||
|
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
|
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.
|
||
|
leon
|
10c194c2a6 |
docs(zh-cn): add missing Chinese translations for 3 documents
Translate the remaining untranslated English docs to Chinese: - explanation/analysis-phase.md - explanation/checkpoint-preview.md - how-to/install-custom-modules.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
JakubStejskalCZ
|
a0705af9be |
docs(cs): groom analysis-phase.md translation (#2242)
* docs(cs): groom analysis-phase.md translation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(cs): fix AI term and ideation phrasing in analysis-phase.md Replace "UI" with "AI" (DeepL mistranslation of the AI acronym as user interface) and rephrase "techniky idealizace" to "techniky generování nápadů" so the meaning matches the English source. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
daa7137623 |
fix(docs): normalize Czech typographic quotes in analysis-phase.md (#2241)
Close pairs with U+201C instead of straight U+0022. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
14fc7b2517 |
docs(cs): add missing analysis-phase.md translation (#2240)
The PRFAQ link added in #2238 points to ../explanation/analysis-phase.md which exists in en, vi-vn, and fr but was missing from the Czech translation, breaking both CI doc checks. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
edfb405e27 |
fix(docs): update stale Analyst triggers and add PRFAQ link (#2238)
Analyst (Mary) triggers were listed as BP, RS, CB, WB, DP but the actual agent source defines BP, MR, DR, TR, CB, WB, DP. Update all locale agents.md files. Also add PRFAQ Working Backwards hyperlink to commands.md in en, cs, and vi-vn. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Emmanuel Atsé
|
128b252c32 |
docs(fr): sync translations with upstream and fix sidebar ordering (#2231)
* docs(fr): fix noun gender typo * docs(fr): translation of new bmad-prfaq skill Translation of commit |
||
|
miendinh
|
b018c7ad7c |
docs(vi-vn): sync translations and add missing checkpoint-preview page (#2222)
Co-authored-by: miendinh <miendinh@users.noreply.github.com> |
||
|
Brian
|
97d32405d0 |
feat(installer): universal source support for custom module installs (#2233)
* feat(installer): add plugin resolution strategies for custom URL installs When installing from a custom GitHub URL, the installer now analyzes marketplace.json plugin structures to determine how to locate module registration files (module.yaml, module-help.csv). Five strategies are tried in cascade: 1. Root module files at the common parent of listed skills 2. A -setup skill with registration files in its assets/ 3. Single standalone skill with registration files in assets/ 4. Multiple standalone skills, each with their own registration files 5. Fallback: synthesize registration from marketplace.json metadata and SKILL.md frontmatter Also changes the custom URL flow from confirm-all to multiselect, letting users pick which plugins to install. Already-installed modules are pre-checked for update; new modules are unchecked for opt-in. New file: tools/installer/modules/plugin-resolver.js Modified: custom-module-manager.js, official-modules.js, ui.js * fix(installer): address PR review findings for plugin resolver - Guard against path traversal in plugin-resolver.js: skill paths from unverified marketplace.json are now constrained to the repo root using path.resolve() + startsWith check - Skip npm install during browsing phase: cloneRepo() accepts skipInstall option, used in ui.js before user confirms selection, preventing arbitrary lifecycle script execution from untrusted repos - Add createModuleDirectories() call to installFromResolution() so modules with declarative directory config are fully set up - Fix ESLint: use replaceAll instead of replace with global regex * fix(installer): pass version and repoUrl to manifest for custom plugins installFromResolution was passing empty strings for version and repoUrl, which the manifest stores as null. Now threads the repo URL from ui.js through resolvePlugin into each ResolvedModule, and passes the plugin version and URL to the manifest correctly. * fix(installer): manifest-generator overwrites custom module version/repoUrl ManifestGenerator rebuilds the entire manifest via getModuleVersionInfo for every module. For custom modules, this returned null for version and repoUrl because it only checked _readMarketplaceVersion (which searches for marketplace.json on disk) and hardcoded repoUrl to null. Now checks the resolution cache first to get the correct version and repo URL. * fix(installer): resolve custom modules from disk cache on quick update When the resolution cache is empty (fresh CLI process, e.g. quick update), findModuleSourceByCode only matched plugin.name against the module code. This failed for modules like "sam" and "dw" where the code comes from module.yaml inside a setup/standalone skill, not from the plugin name in marketplace.json. Now runs the PluginResolver on cached repos when the direct name match fails, finding the correct module source and re-populating the cache for the install pipeline. * feat(installer): universal source support for custom modules Replace GitHub-only custom module installation with support for any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths. - Add parseSource() universal input parser (local paths, SSH, HTTPS with deep path/subdir extraction for GitHub, GitLab, Gitea) - Add resolveSource() coordinator: parse -> clone if URL -> detect discovery vs direct mode (marketplace.json present or not) - Clone-first approach eliminates host-specific raw URL fetching - 3-level cache structure (host/owner/repo) with .bmad-source.json metadata for URL reconstruction - Local paths install directly without caching; localPath persisted in manifest for quick-update source lookup - Direct mode scans target directory for SKILL.md when no marketplace.json - Fix version display bug where walk-up found parent repo marketplace.json and reported wrong version for custom modules * fix(installer): harden readMarketplaceJsonFromDisk and hoist require - Add try/catch to readMarketplaceJsonFromDisk so malformed JSON returns null instead of throwing an unhandled parse error - Hoist CustomModuleManager require outside the per-module loop in _installOfficialModules * fix(installer): restore validateGitHubUrl strictness and fix prettier - Restore original GitHub-only regex in deprecated validateGitHubUrl wrapper so existing tests pass (rejects non-GitHub URLs, trailing slashes) - Run prettier to fix formatting in custom-module-manager.js * feat(installer): add --custom-source CLI flag for non-interactive installs Allows installing custom modules from Git URLs or local paths directly from the command line without interactive prompts: npx bmad-method install --custom-source /path/to/module npx bmad-method install --custom-source https://gitlab.com/org/repo npx bmad-method install --custom-source /path/one,https://host/org/repo Works alongside --modules and --yes flags. All discovered modules from each source are auto-selected. * docs: add custom and community module installation guide New how-to page covering community module browsing, custom sources (any Git host, local paths), discovery vs direct mode, local development workflow, and the --custom-source CLI flag. Clarifies that .claude-plugin/ is a cross-tool convention, not Claude-specific. Also updates non-interactive installation docs with the new flag and examples, bumps sidebar ordering, and fixes --custom-source to install only core + custom modules when --modules is not specified. |
||
|
Brian
|
5dbfb588ee |
refactor(installer): remove custom content installation feature (#2227)
* refactor(installer): remove custom content installation feature Remove the entire local filesystem custom content feature from the installer to make way for marketplace-based plugin installation. Deleted: custom-handler.js, custom-module-cache.js, custom-modules.js Removed: --custom-content CLI flag, interactive custom content prompts, custom module caching, manifest tracking, missing-source resolution, and related test suites. Updated docs across all translations. * fix: address review findings from Augment Fix admonition syntax (remove accidental space in :::note) across 4 translated docs files, and update stale JSDoc on listAvailable(). |
||
|
Alex Verkhovsky
|
aa48f83a65 |
docs: rewrite get-answers-about-bmad for flow and accuracy (#2213)
Restructure from two glued-together documents into a single escalation flow (bmad-help → source → community). Remove references to deprecated _bmad folder and closed Discord channels. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
JakubStejskalCZ
|
ac18b195e9 |
docs(cs): add Czech (Čeština) documentation translation (#2134)
* docs(cs): add Czech (Čeština) documentation translation Add complete Czech translation of all 29 documentation files mirroring the English source structure. Register cs-CZ locale in Starlight config with sidebar label translations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(cs): repair corrupted characters and table formatting in Czech docs Fix UTF-8 encoding artifacts in customize-bmad.md and upgrade-to-v6.md, align markdown table formatting, and correct Czech grammar in project-context.md heading. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(cs): address CodeRabbit review feedback - Normalize 64 Czech quotation marks to proper „…" pairs across 14 files - Fix corrupted UTF-8 box-drawing character in upgrade-to-v6.md - Use relative roadmap link (./roadmap) in index.md for locale consistency - Fix typo: Podníková → Podniková in modules.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(cs): sync Czech translation with upstream agent consolidation and PRFAQ addition Agents: remove Barry/Quinn/Bob (merged into Developer), add WB trigger and PRFAQ to Analyst. Tutorials/commands/workflow-map: fix SM→DEV references, add PRFAQ workflow entries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
Alex Verkhovsky
|
0edcd0571f |
fix(docs): correct translation fidelity issues in Vietnamese docs (#2192)
Sync Vietnamese translations with current English source: - Update agent table to consolidated Developer agent architecture - Fix bmad-dev -> bmad-agent-dev skill ID references - Replace Quinn/QA agent framing with built-in QA workflow - Fix SM agent -> Developer agent in getting-started - Fix broken platform-codes.yaml URL - Add missing Validation Commands section to style guide - Fix malformed table row in style guide - Remove unsourced content additions in project-context - Fix roadmap section heading and index link format - Fix accountability softening in party-mode dialogue |
||
|
miendinh
|
072de34450 |
docs(vi-vn): add Vietnamese translation for BMAD documentation (#2110)
* docs(vi-VN): add Vietnamese translation for BMAD documentation * feat(i18n): add Vietnamese website locale * docs(vi-VN): refine translated documentation * docs(vi-VN): sync terminology with latest upstream docs * fix(docs): normalize Vietnamese locale path casing * docs(vi): update non-interactive installation translation * docs(vi): translate analysis phase explanation * docs(vi): sync updated reference and tutorial pages --------- Co-authored-by: miendinh <miendinh@users.noreply.github.com> |
||
|
Alex Verkhovsky
|
003c979dbc |
chore: remove SM agent (Bob) and migrate to Developer agent (#2186)
* 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> |
||
|
Alex Verkhovsky
|
48c2324b28 |
chore: remove QA agent (Quinn) and migrate capability to Developer agent (#2179)
Delete the Quinn (bmad-agent-qa) agent wrapper and add QA test-generation capability to Amelia (bmad-agent-dev). Update agent tables, testing docs (EN/ZH-CN/FR), marketplace.json, party-mode, and checklist references. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
7ef45d472c |
docs(checkpoint): add explainer page and workflow diagram (#2183)
* docs(checkpoint): add explainer page and workflow diagram Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(checkpoint): replace excalidraw source with exported PNG diagram Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
1aa0903e79 |
chore(agents): remove Barry quick-flow-solo-dev agent (#2177)
Delete the Barry agent persona and migrate its QD (quick-dev) capability to the Amelia dev agent. Update EN, ZH, and FR docs, marketplace JSON, and workflow diagrams. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Emmanuel Atsé
|
2302d9cdc5 |
docs(fr): translate output folder path resolution section (#2140)
Syncs French translation with commit
|
||
|
Brian
|
abfc56bd2c |
feat: add bmad-prfaq skill as alternative analysis path (#2157)
* feat: add bmad-prfaq skill as alternative to product brief Add Working Backwards PRFAQ challenge skill for stress-testing product concepts through Amazon's PRFAQ methodology. Includes press release drafting, customer FAQ, internal FAQ, and verdict stages with subagent support for artifact scanning and web research. - New bmad-prfaq skill with 5-stage interactive gauntlet and headless mode - Subagents for artifact analysis and web research (graceful degradation) - Research-grounded output directive for current market/competitive data - Always produces distillate for downstream PRD consumption - Fix manifest array syntax in both prfaq and product-brief manifests - Drop number prefixes from reference files - Update docs: getting-started, workflow-map, agents, skills reference - Add analysis-phase explainer doc with comparison table and decision guide - Update workflow-map-diagram.html with prfaq card - Add -H and -A args to CSV for both skills - Add unist-util-visit as devDependency (was imported but undeclared) * fix: harden bmad-prfaq for compaction resilience and context efficiency Add coaching persona re-anchors to all stage prompts so the behavioral directive survives context compaction. Add do-not-read guards at resume detection, headless mode, and input gathering to prevent parent agent context bloat. Add Stage 1 coaching notes capture. Adapt template and press release stage for non-commercial concept types. Cap subagent response token budgets. * fix: add config.user.yaml to file-ref validator allowlist Also update PRFAQ config path to use correct _config/bmm/ prefix. |
||
|
Alex Verkhovsky
|
513f440a23 |
refactor(installer): restructure installer with clean separation of concerns (#2129)
* 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. |
||
|
Akhilesh Tyagi
|
1040c3c306 |
fix: correctly resolve output_folder paths outside project root (#2132)
* 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>
|
||
|
梁山河
|
090bfea9b2 |
docs(zh-cn): close explanation gap relinks (#2102)
我补齐 explanation 目录在本轮审校中确认的中文缺口，统一关键命令名为当前 `bmad-*` 形式，并修正 Party Mode 示例里的半翻角色标签。此前这些页面缺少回连到中文目标的入口且术语混用旧名，导致查阅路径容易断层；现在每页都补了中文回链并对齐命名，降低理解和跳转成本。 Feishu: https://feishu.cn/wiki/TODO Made-with: Cursor Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
梁山河
|
c350e5b9d8 |
docs(zh-cn): refresh reference and roadmap docs (#2101)
我统一修订中文模块与测试参考、路线图和文档风格指南，确保模块边界、测试能力、术语和跳转在中文站点内一致。此前这些页面存在命名过时、语气不统一和提示块语法不稳定的问题；现在我改为当前 skills/workflow 语义，并明确英文外部资源边界与 `:::` 提示块规范，以降低查阅和贡献时的歧义成本。 Feishu: https://feishu.cn/wiki/TODO Made-with: Cursor Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
梁山河
|
0d7d7dae04 |
docs(zh-cn-reference): refresh workflow and skill references (#2100)
我统一修订中文 reference 中 workflow-map、commands、agents、core-tools 四页，改正过时命名与调用方式，并将术语切换到当前 skills 体系。此前这些页面混用了旧版前缀和命令语义，容易让用户在查阅阶段误用流程；现在页面结构与英文源和现行实现保持一致，同时优先串联中文路径以提升检索效率。 Feishu: https://feishu.cn/wiki/TODO Made-with: Cursor Co-authored-by: leon <leon.liang@hairobotics.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
梁山河
|
94831cbb1e |
docs(zh-cn): refine Epic3 story 3.3 and 3.4 explanations (#2099)
* docs(zh-cn-explanation): refine epic3 stories 3.3-3.4 我重写头脑风暴、高级启发与 Party Mode 的中文说明，明确三者在适用场景、价值和边界上的差异，避免字面对译带来的误用。 我同步收敛 Quick Dev 与对抗性评审文案，强调各自定位与配合关系，并补齐中文优先链路和当前 workflow 命名。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor * docs(zh-cn-explanation): 统一提示块围栏语法 我将五篇 explanation 文档里的四冒号提示块语法统一为三冒号，确保与当前文档渲染规则一致。 此前这些文档混用不同围栏写法，容易在审阅和渲染中引入不必要差异；现在统一后可减少维护噪音。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
梁山河
|
8b0754106d |
docs(zh-cn): refine Epic3 story 3.1 and 3.2 explanations (#2098)
* docs(zh-cn-explanation): refine epic3 stories 3.1-3.2 我统一 solutioning、project context 与 established projects 的中文术语和叙述边界，避免 explanation 页面混入 how-to 语气导致误判。 我补齐中文优先跳转并更新关键 workflow 命名，使多智能体协作与既有项目 FAQ 的说明更可执行。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor * docs(zh-cn-explanation): normalize admonition syntax 我将 3 篇中文 explanation 文档中的提示块语法统一为仓库约定的 `:::...:::` 形式。 此前使用 `::::...::::` 会导致与现有文档规范不一致；现在统一后可减少渲染歧义与后续维护成本。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
梁山河
|
90d9d880b6 |
docs(zh-cn): refine story 2.5 and 2.6 how-to guides (#2097)
* docs(zh-cn-how-to): refine stories 2.5 and 2.6 docs 我澄清中文自定义与文档分片指南，保留命令、路径和配置键名的技术准确性，降低高级操作误解。 我同步修正 v4 到 v6 升级步骤中的旧新路径与工作流命名，帮助迁移时按当前约定执行。 feishu: https://feishu.cn/wiki/TODO Made-with: Cursor * docs(zh-cn-how-to): clarify shard output precedence 我在“你将获得”中补充完整文档与分片文档并存时的读取优先级说明。 此前“可保留”表述容易让用户误以为分片会自动生效；现在明确并存不建议且默认优先读取完整文档。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
Alex Verkhovsky
|
b3cf338118 |
refactor(quick-dev): rename tech-spec prefix to spec (#2109)
* refactor(quick-dev): rename tech-spec prefix to spec * docs: update tech-spec references to spec |
||
|
梁山河
|
76fb7e067b |
docs(zh-cn): refine established project guides (#2096)
* docs(zh-cn): refine established project guides clarify the boundary between new-project and established-project usage so zh-cn readers can choose the right workflow path. align project context terminology and command references with current conventions while keeping guidance concise and executable. Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix project-context syntax and wording 我将 project-context 文档中的提示块语法统一回项目规范的 `:::...:::` 形式，避免与文档风格约定不一致。 我同时把“在不同用户故事（story）间决策不一致”调整为“之间决策不一致”，提升中文表达的自然度与可读性。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
梁山河
|
ad2eb0e127 |
docs(zh-cn): refine install and non-interactive guides (#2094)
* docs(zh-cn): refine install and non-interactive guides 我统一中文安装文档中的术语和参数说明，补齐预发布安装与 skills 启用提示， 并保持交互式与非交互式安装路径和英文源文一致，减少安装场景下的理解偏差。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align install guide review wording 我在安装指南中补充目录结构示例说明，明确工具相关目录会随所选平台变化，避免读者误以为 .claude/.cursor 一定同时存在。 我同时统一非交互式安装文档里残留的“标志”表述为“参数”，让术语在全文保持一致并降低理解成本。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
Alex Verkhovsky
|
7e97b7e7f3 |
fix(docs): correct skill names in getting-started tutorials (#2103)
Agent skills referenced with shortened names (bmad-pm, bmad-architect, etc.) that don't match installed skill names. Fixed to use actual names (bmad-agent-pm, bmad-agent-architect, etc.) across EN, ZH-CN, and FR. Also fixed bmad-research to three specific research skills (EN, FR) and bmad-product-brief to bmad-create-product-brief (ZH-CN). Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
梁山河
|
ba2a5cc6a0 |
docs(zh-cn): align getting-started tutorial workflows (#2093)
* docs(zh-cn): align getting-started tutorial workflows 我按英文源文更新中文入门教程中的命令、工作流和智能体调用方式， 并统一步骤叙述与导航语义，减少术语漂移和旧命令误导。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): fix tutorial skill names 我将入门教程阶段 1 中过时或不可用的技能名替换为当前可调用的技能名。 此前 `bmad-research` 与 `bmad-create-product-brief` 可能导致新用户执行受阻；现在改为具体研究技能与 `bmad-product-brief`，提升教程可执行性。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
梁山河
|
347f459d5d |
docs(zh-cn): refine entry copy and navigation (#2092)
* docs(zh-cn): refine entry copy and navigation 我统一中文入口层文案语气，减少机翻腔并保持与英文语义一致， 让读者从 README、首页到 404 与界面文案都保持同一术语和导航预期。 Feishu: https://www.feishu.cn/ Made-with: Cursor * docs(zh-cn): align non-interactive install link label 我把 README_CN 中“查看完整安装选项”改为“查看非交互式安装选项”。 此前文案范围大于目标页面内容，容易让读者误以为是安装总览；现在文案与链接目标保持一致，减少理解偏差。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
梁山河
|
eb72361720 |
docs(zh-cn): refine help and quick-fixes guides (#2095)
* docs(zh-cn): refine help and quick-fixes guides improve zh-cn troubleshooting guidance so users can quickly choose the right support path and self-recover from common issues. align bmad-help and quick-dev usage wording with current invocation conventions and remove glossary-style appendices to keep the pages action-oriented. Feishu: N/A Made-with: Cursor * docs(zh-cn): fix tip admonition fence syntax 我把 get-answers-about-bmad 文档中的 `::::tip` 语法改为仓库统一使用的 `:::tip`。 此前四冒号写法与项目文档约定不一致，可能导致提示块渲染异常；现在与现有 Starlight 写法保持一致。 Feishu: <https://www.feishu.cn/> Made-with: Cursor --------- Co-authored-by: leon <leon.liang@hairobotics.com> |
||
|
Alex Verkhovsky
|
e3f935fd6d |
fix(docs): community feedback — typo, locale 404s, llms-full (#2091)
* fix(docs): correct Hasselhoff spelling, add locale-aware 404 redirect Fix "Hasslehoff" → "Hasselhoff" typo in customize-bmad.md across all three locales (en, zh-cn, fr). Add client-side locale detection to 404.astro so GitHub Pages serves the correct localized 404 page instead of always showing English. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(build): exclude translated locales from llms-full.txt llms-full.txt was including zh-cn and fr docs, tripling the content with duplicate information in different languages. Restrict to English only — translations add no value for LLM context consumption. Reduces output from ~393K to ~114K chars (~29k tokens). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(i18n): extract locale config to shared module Move locale definitions from astro.config.mjs into a shared website/src/lib/locales.mjs consumed by astro config, build-docs, and 404.astro. Adding a new locale is now a single-file change. --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |