mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-01 15:09:07 +08:00
main
90 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Alex Verkhovsky
|
a0d04f7e34 |
docs: consolidate Reference and retire the Diátaxis groups (#2798)
Move Get Answers About BMad under Start and Autonomous Development Loops under Build. Split the Workflow Map into a planning-skills section on Choose a Planning Path (with a new planning-skills.svg) and an implementation-skills section on Build a Change. Consolidate Agents, Skills, Core Tools, and Advanced Elicitation into one Skills and Agents page whose agent codes and skill list match the shipped sources. Retire the v4 upgrade guide and the external-modules prompt, remove the How-To Guides and Explanation sidebar groups, and redirect every retired route. |
||
|
Alex Verkhovsky
|
3bc2271260 |
docs: add Customize and Extend chapter (#2797)
Create the Customize and Extend chapter after Existing Codebases with five pages under docs/customize/: Customize BMad, Adopt BMad Across a Team, Add Modules, Use Web Bundles, Run Multi-Agent Discussions. Retire eight English pages with redirects: how-to/customize-bmad, explanation/named-agents, how-to/expand-bmad-for-your-org, how-to/install-custom-modules, reference/modules, how-to/use-web-bundles, explanation/web-bundles, explanation/party-mode. Corrections against shipped sources: the installer has no community catalog browser (one custom/community prompt with an unverified-module warning); bmad-prd's checklist key is validation_checklist_template; the brief template ships under assets/; doc_standards passes run in declared order; the web-bundle shelf personas now match web-bundles/bundles.json. |
||
|
Alex Verkhovsky
|
c16dc729a9 |
docs: add Existing Codebases chapter (#2793)
Add a four-page chapter after Plan Larger Work: Start in an Existing Codebase (the repo is the knowledge; size the work from the source), Set and Maintain Project Context, Getting Deeper as the worked example, and The Theory of Project Context as optional last reading. Retire six English pages with redirects, drop the empty English Tutorials sidebar group, collapse Plan Larger Work and Existing Codebases in the sidebar, reflow how-to and explanation orders, and retarget Welcome, README, Plan, Reference, and style-guide links. Localized copies stay as deferred translation work. |
||
|
Alex Verkhovsky
|
191219eadb |
docs: add Plan Larger Work chapter (#2790)
Introduce a Plan chapter of eight pages under docs/plan/: Choose a Planning Path, Plan Inside an Organization, Explore and Validate an Idea, Research a Decision, Define Requirements and a Specification, Design UX and Architecture, Break Work into Stories and Track It, and Finish an Epic. Content is written from the current skill sources and describes what each skill takes in, what it produces, and how to steer it. Retire ten English pages from how-to and explanation with redirects to their new homes, renumber the remaining sidebar orders, migrate English links, shrink the Welcome router bullet, and add a Plan Larger Work sidebar group after Build. Localized copies of the retired pages are recorded in deferred work. |
||
|
Alex Verkhovsky
|
b023b5c9fc |
docs: add Review a Change page (#2786)
* docs: add Review a Change page Add the Build-chapter how-to for bmad-code-review, list it after Build a Change, redirect the deleted adversarial-review explanation, and point the existing disclaimers, catalog rows, and a review_layers customize example at the new page. * docs: rewrite Review a Change around extra passes, cost, and /code-review |
||
|
Alex Verkhovsky
|
6b83751711 |
chore(docs): drop llms.txt generation and site banners (#2785)
Stop generating llms.txt and llms-full.txt, remove the header banners, and point help/docs at the live site. |
||
|
Alex Verkhovsky
|
cf0d98f030 |
docs: integrate the Build chapter (#2784)
Retarget remaining English first-party links to the canonical Build pages, list the chapter in llms.txt, order Start and Build first in llms-full, and reject superseded English routes in the published-model check. |
||
|
Alex Verkhovsky
|
922c86d2c5 |
docs: add Build a Change page in plain English (#2780)
* docs: create Build a Change page and retire Quick Fixes and Build Consolidate how-to/quick-fixes and explanation/build into the canonical build/build-a-change page, opening with the sizing model and Where Build Fits table and preserving the Build diagram and intent examples. Add the Build sidebar group after Start, redirect both old routes, retarget first-party English links and the llms.txt entry, and close the resulting sidebar-order gaps. * fix(docs): track Build a Change page by scoping Astro build ignore The bare build/ gitignore rule also matched docs/build/, so the new canonical page never entered the prior commit. * docs: rewrite Build a Change page in plain English Name the skill as bmad-build instead of Build, drop the duplicated routing tables, and explain why it spends human attention on a few checkpoints instead of a Continue slog. |
||
|
Alex Verkhovsky
|
4d8dec79b9 |
docs: clarify BMad development paths (#2669)
* docs: clarify BMad development paths * docs: add development path diagrams |
||
|
Alex Verkhovsky
|
22c76e8ba2 | docs: add Start documentation section (#2777) | ||
|
Alex Verkhovsky
|
9376e1f9e5 |
docs: rewrite installation guide (#2775)
* docs: rewrite installation guide * docs: refine installation outputs and CI example |
||
|
Alex Verkhovsky
|
86beb06547 |
docs: restore the ladder shape of the closing poem (#2757)
The Mayakovsky-style envoi at the end of get-answers-about-bmad was written as indented lines in one paragraph, so every renderer collapsed it: the leading spaces were dropped and the lines were soft-wrapped into running prose glued onto the GitHub Issues link above it. Use hard line breaks and em-space entities so the staircase survives Markdown rendering and Prettier, and put a blank line back between the link and the poem. Same fix applied to the fr and zh-cn translations. |
||
|
Brian
|
568365e7ff |
chore: default persistent_facts to an empty array (#2750)
* chore: default persistent_facts to an empty array
Every customize.toml shipped with a skill seeded persistent_facts with
file:{project-root}/**/project-context.md. That made project-context an
opt-out default rather than an opt-in customization. Ship the arrays empty
so nothing is loaded unless the user adds it.
* docs: correct the persistent_facts default in comments and docs
Comments and docs still described project-context.md as loading by default.
They were wrong twice over: the array now ships empty, and bmad-project-context
no longer produces a project-context.md at all — it writes a verified block into
AGENTS.md and treats project-context.md as a legacy artifact.
Replace those claims with the actual model: repo-wide context belongs in
AGENTS.md, which every skill already sees; persistent_facts carries context only
one skill needs, loaded on demand instead of as constant memory. Each site shows
the file: entry users can add to opt back in.
|
||
|
Brian
|
825099b2cb |
fix(installer): ask about deprecated shims during Quick Update, and report the outcome (#2746)
* feat(installer): ask about shims during Quick Update Quick Update returned before the shim prompt, so anyone who only ever runs it carried their compatibility shims forward release after release without once being offered the chance to drop them. Quick Update now asks, defaulting to keeping the shims so pressing enter never removes a skill in active use. It stays quiet for an installation that already dropped its shims rather than re-asking every update. The prompt carries the recommendation to remove them and names the one case that justifies keeping them: a customized shim not yet migrated. Whenever an install retains shims, it now lists every one of them and what it forwards to. That notice is emitted where the policy is resolved rather than at the prompt, so it also reaches the paths that never prompt: --yes, --shims, and scripted quick updates. * fix(installer): never prompt for shims without a TTY, and report removal Two gaps in the Quick Update shim prompt. The prompt could be reached by a scripted run. `--action quick-update` is a documented scripting flag and is not tied to `--yes`, so a headless invocation on an install that still had shims fell through to a confirm. clack's confirm never resolves without a TTY: the process drained its event loop and exited silently, mid-install, with status 0. It now keeps the standing answer whenever stdin is not a TTY, leaving --shims and --no-shims as the way to change it from a script. Removing shims was also completely silent. Source filtering just skips the directories, and the IDE cleanup that deletes the stale skill dirs suppresses its logging on purpose, so nothing anywhere told the user that a skill they may still invoke had just gone. Any run that removes shims now lists them and says how to put them back, mirroring the retained notice. Between the two, every run that has shims either way reports which way it went, on interactive and headless paths alike. * feat(installer): carry the shim outcome into the final summary Both shim notices print before the install tasks start, so a long run buries them well above the fold. The summary box already repeats the uv warning for exactly this reason; the shim outcome now rides along the same way, as a single line next to the preserved/backed-up file counts. Retained reads "Deprecated shim skills retained: N (re-run to remove them)" in yellow, removed reads "Deprecated shim skills removed: N" in green, and an install with no shims either way adds no line at all. * fix(installer): say what an empty module selection installs The official module picker allows an empty selection on purpose: core is always installed and is not a row in the list, so selecting nothing is a valid core-only install. The prompt did not say so, and collapsed to a bare "0 items selected", which reads as though the install is about to do nothing. autocompleteMultiselect takes an optional emptyLabel, shown while selecting as "Nothing selected: installs core only" and on submit as "0 items selected (core only)". Pickers that pass no emptyLabel are unchanged. Also fixes the count to say "1 item" rather than "1 items". * refactor(installer): trim explanatory comments to what the code cannot say Cuts 35 comment lines added across this branch down to seven, keeping only the non-obvious constraints: clack's confirm hanging without a TTY, core not being a row in the module picker, and why the shim notices are emitted where they are. * fix(installer): report shims removed after they are retired from source Removal reporting was derived from the shims the incoming release ships, so a shim retired from source fell out of the report entirely: it was absent from discovery, yet the update cleanup still deleted its installed target using the previous manifest. The v7 cut is exactly that case, and it would have removed every shim in silence. Removal is now derived from what is installed, read back from skill-manifest.csv, and the retained/removed split moves into selectShimOutcome. This also covers the mixed run where one shim is retired while the rest stay enabled: both notices fire, and the summary carries both counts. The recovery line no longer offers --shims when the release cannot reinstall them. Raised by greptile and coderabbit on #2746. |
||
|
Alex Verkhovsky
|
c4ec1837b8 |
feat(project-context): adopt handwritten instructions via a ledger (#2715)
* feat(project-context): adopt handwritten instructions via a ledger A non-empty instruction file without a managed block now routes to a new adopt intent — the migration form of refresh — never to setup. Every existing instruction enters a retention ledger (retain, rewrite, relocate, automate, delete) presented in full before anything is written; a deletion needs one of four grounds, and one without hard grounds is held for line-item approval that block approval never grants. Best practices replace the derivability test with a retrieval-cost test, admit compact architecture and toolchain pins, and gate nested AGENTS.md files on loading verified for every harness in use, falling back to path-qualified root lines. The explanation and how-to docs follow the same reframing. * fix(project-context): scope splice preservation to the block itself Step 5's byte-identical clause read as forbidding any change outside the markers, which contradicted the ledger's approved rewrites, relocations, and deletions of handwritten instructions there. The splice still touches nothing outside the markers; outside text changes only through a settled ledger entry or a proposed fix the user has seen. Also from review: the how-to routing sentence now distinguishes adopt from refresh, template section 4 includes pyproject.toml, and the theory doc qualifies the source-recovery claim to implementation behavior. * docs(project-context): plain-language pass on how-to and explanation The reader-facing pages had absorbed the skill's internal vocabulary — the disposition taxonomy, approval tiers, harness loading mechanics — and metaphors that mean nothing to a casual reader. Replace them with the user-level promise: you see what happens to every existing instruction before anything is written, and nothing is deleted without your sign-off. The theory page keeps its technical depth by design. * docs(project-context): drop behavior sentence from skill description The description is a routing trigger; the adopt verb already carries the cue, and the preservation behavior is documented where it runs. * refactor(project-context): move intent-conflict rule from Args to detection The Args line declares the interface; the guard against silently obeying a supplied intent that contradicts the detected state belongs in step 4, where detection happens. * docs(project-context): trim Args platitude, mark conflict case as example * docs(project-context): replace canonical/toolchain-pin jargon with plain terms Right commands to use, required tool versions, cross-component rules - same meaning, readable by anyone. * docs(project-context): plain-language the cross-component admission rule * docs(project-context): rewrite the adopted-content budget paragraph readably |
||
|
Alex Verkhovsky
|
db7f96dd93 | feat(installer): make compatibility shims optional (#2728) | ||
|
Alex Verkhovsky
|
890fcda760 |
docs(project-context): update stale "pitfall line" wording to "pitfall" (#2710)
Aligns the how-to and theory docs with the skill terminology change from #2709. |
||
|
Brian
|
ade7a966e9 |
fix(installer,skills): make uv a real requirement and stop assuming a system Python (#2704)
The installer told users uv was optional while bmad-build had already made it mandatory. uv-check.js called it "becoming the de facto standard", install-messages.yaml led with HEADS UP, and installer.js printed a Tip inside a box titled "BMAD is ready to use!" — while bmad-build and bmad-build-auto HALT on activation without `uv run`. The probe's result was discarded (`await checkUvEnvironment();`), so nothing branched on it. Messaging now names the consequence, and the post-install summary repeats the warning when it applies — the pre-install probe fires before every prompt, so by then it is far up the scrollback. Still warn-don't-block: core-only, docs-only, and CI installs never render a skill, so a missing uv must not fail the run. Adds a python3 probe used only when uv is absent, since that is the only case where the interpreter on PATH matters. It reports whether the direct-interpreter skills still work (3.11+) or nothing Python-backed will (below 3.11, or no python3 at all). Separately, 25 call sites still ran resolve_customization.py under a bare `python3`. That script requires 3.11+ for tomllib, so on macOS without Homebrew or Ubuntu 22.04 they fell through to their "if the script fails" path and hand-merged the TOML in-context — no error surfaced. All 25 now use `uv run`, which provisions a matching interpreter from the script's own requires-python. Four more spawned Python purely to open an HTML file: python3 -c "import webbrowser, pathlib; webbrowser.open(...)" Replaced with the platform opener bmad-brainstorming already uses — open / xdg-open / start. src/ now contains no bare Python invocation at all, so "Python 3.11+" leaves the user contract: uv provisions its own. docs/how-to/customize-bmad.md described a transition that this ends. Test suite 46 grows from 12 to 29 assertions: Python parsing, the 3.11 boundary in both directions, that uv-present skips the python3 probe, and all three missing-uv sub-branches. |
||
|
Brian
|
47bab7d15c |
refactor(project-context): conversational skill, no script, AGENTS.md block (#2698)
* feat(project-context): rewrite as prescriptive AGENTS.md generator Replace the kernel+bundle context system with a single product: a short verified agent guide (AGENTS.md). A field trial of the first version showed repo scanning produces polished-but-useless factoids; the rewrite fills a fixed section plan from ranked evidence channels (executable config and CI, targeted git history, session logs, human interview) and uses the repository only to verify claims, never as the source of knowledge. - Intents: bootstrap, refresh, record (capture an observed agent mistake), audit; query is gone with the bundle - Per-fact entry files, trust frontmatter, index, placement machinery, and the skill's context.py mechanics script are removed; accountability moves to one plain ledger file recording every candidate claim and its disposition - Skill directory only; docs, forwarding husks, and shared scripts untouched * refactor(project-context): per-section admission rules, two-tier guide Revisions from two end-to-end trials plus review: - Replace the global non-derivable test with per-section admission rules: brevity (orientation), authority (policy), universal need verified by execution (commands, verification), wrong-default-assumption (conventions), localization value (pointers), observed failure only (pitfalls) - Two-tier output: AGENTS.md (orientation + policy + pointer) for every session, AGENTS-dev.md for coding sessions; single file when tiny - Pitfalls can never be nominated by scans: sources are recorded lessons, maintainer recall, session evidence, and the writing session's own caught mistakes; retirement only when the guarded thing is gone or the human says so, since a working rule erases its own evidence - Interview ergonomics: recall questions, never review lists; testimony the repo contradicts is surfaced with evidence, never written or dropped - Trial-driven fixes: guide-to-filesystem link check, mutating-command go-ahead as the interview's first question, plain-English rewrite throughout * fix(project-context): bidirectional coverage trace, history-evidenced pitfalls Round-3 trial findings: an unsourced pitfall entered the guide at composition time because coverage only checked ledger-to-guide; and repeat-fix git history, the strongest pitfall evidence observed, was not an explicitly admitted source. * refactor(project-context): move Where-things-are to AGENTS.md, imperative lines Where-things-are pointers serve planning sessions as much as coding ones, so they belong in the always-loaded file. Shape rules now require every line to state an action (bare facts only as justification clauses) and stable contract headings across runs. * docs(project-context): session-kind guides as a third structural axis A maintainer-named frequent session kind (UX, manual testing, data work) may earn its own AGENTS-<kind>.md behind a pointer; module-level differences stay with scoped guides. * refactor(project-context): action-gated dev-guide pointer, two-file example The AGENTS-dev.md hop is the most common progressive-discovery trigger, so it is now gated on the first hands-on action rather than session self-classification, names its payoff, and names the exemption. The contract's worked example shows the two-file form with the pointer in situ. Scoped-guide discovery no longer assumes harness nearest-file loading: the root-guide pointer is the mechanism. * refactor(project-context): adopt shared memlog, drop unearned claims The run record is now a standard memlog kept with the shared memlog.py script — append-only typed entries, latest entry wins — replacing the bespoke ledger format; stale-disposition notes become structurally impossible. Two appeal-to-measurement assertions cut: the operative admission and exclusion rules carry that load. * docs(project-context): guard handwritten guides The skill never commits — its output stays as working-tree changes for the user. Headless runs never rewrite a guide the memlog doesn't record writing; they leave an AGENTS.md.proposed for an interactive merge. * docs(project-context): fold in prior-art research findings Five adoptions from the generator prior-art survey: prohibitions name their permitted alternative; an emphasis-marker budget; a git-log --diff-filter=DR drift check on refresh; TODO placeholders over guessed greenfield commands; commit and branch conventions mined from history. * docs(project-context): route candidates to enforcement before prose Compose now asks, per accepted candidate, whether a hook, lint rule, or CI check enforces it better than a guide line; the line is the fallback and a landed check deletes it. * docs(project-context): narrow refresh interview and contradiction flagging Refresh interviews shrink to one recall question — what changed since the last run. Cross-file contradictions are flagged only when they change behavior; rewording and overlap are not contradictions. * refactor(project-context): conversational skill, no script, AGENTS.md block Refine the skill into an implementation-layer capability: a conversation that produces one small verified block inside the repo's AGENTS.md. The human is in the loop for every write; there is no autonomous mode. - Drop src/scripts/context.py and its tests. Nothing it did is needed once the output is a single spliced block rather than a bundle of files. - Replace guide-contract.md and evidence.md with best-practices.md (admission, exclusion, retirement, retrieval, maintenance) and template.md (section list plus a worked example, no placeholders). - Collapse the two-file AGENTS.md/AGENTS-dev.md split into one block. A pointer the agent must choose to follow gets skipped; anything load-bearing goes in the always-loaded file. - Replace per-section admission rules with one test: anything derivable from source is read live, never stored. Commands stated in package.json, a Makefile, or CI config no longer earn a line; their caveats do. - Ask up front whether a run covers the root only or named sub-projects, gated on observable evidence (a workspace manifest, per-directory build manifests). - Husk bmad-document-project and bmad-generate-project-context onto setup intent, and say plainly that the deeper system-explanation altitude is a separate capability rather than shipping a thin substitute. - Align module-help.csv, bmad-correct-course, the analyst menu, and the docs set with the block as the output. --------- Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
Brian
|
57e70562e3 |
feat: bmad-project-context skill — verified kernel + bundle context system (#2674)
* Add bmad-project-context skill; husk document-project and generate-project-context - New bmad-project-context: one engine, three intents (ingest/query/audit) building a verified kernel + bundle context system; interactive default, auto/headless mode; works with a BMad install or standalone via bootstrap - context.py core runtime script (validate/index/map/sweep/resolve/compass/ sync/bootstrap/config) with 52 tests; config resolution delegates to the installed BMad resolver so script and session never disagree - bmad-document-project and bmad-generate-project-context reduced to 10-line deprecation shims forwarding to the new skill - Docs updated: project-context explanation/how-to rewritten, established projects guide + FAQ, agents references, workflow map; deprecation notes kept for old-name searches - module-help.csv single PC row; analyst menu DP -> PC - validate-file-refs: context.yaml is runtime-generated * refactor: remove map command from context.py — discovery is the model's job Real-repo testing showed map's descriptor pass grinding through large asset trees. Discovery is judgment work the model does better with its own tools; the script keeps only measurement, mutation, and resolution (validate/index/sweep/resolve/compass/sync/bootstrap/config). SKILL.md brownfield flow de-prescribed to outcome-driven wording; added a bounding-question rule for huge external sources. * feat: closing message when the harness may not load AGENTS.md 43+ harnesses make per-harness load verification impractical. Whenever AGENTS.md carries the kernel, the run now closes by telling the user: if your harness doesn't auto-load AGENTS.md, make the context file it does load pull this one in (e.g. a CLAUDE.md containing @AGENTS.md). Found in real-repo testing: the kernel sat unloaded under Claude Code until a CLAUDE.md pointer was hand-made. * docs: add The Theory of Project Context explanation Why the skill captures so little: the evidence against generated docs, the pruning test and what earns a place, the deliberate exclusions with their reasons, context-as-liability, and an honest comparison with the two replaced skills. * fix: address PR review findings - Force-add eval fixture files the repo gitignore silently dropped (pnpm-lock.yaml, _bmad/context.yaml, context/.memlog.md) - docs/reference/agents.md Analyst row: DP/Document Project -> PC/Project Context - context.py: cmd_index no longer crashes on an empty index.md (and allows overwriting one); inline # comments in frontmatter values are only stripped when preceded by whitespace (C#-style values survive); cache_lookup tolerates corrupt pointer files; pointer writes are atomic - triggers.json: positive trigger for the query intent |
||
|
Alex Verkhovsky
|
d25a307e71 | docs: remove non-interactive installation pages (#2670) | ||
|
Alex Verkhovsky
|
9b672e1e6b |
Allow configuring the Build spec editor handoff (#2652)
* fix: respect preferred app for Build review specs * fix: restore Build VS Code handoff default * fix: allow disabling Build spec opener * docs: document Build editor opener options * fix: use established Build path placeholders * fix: address Build opener review findings * docs: tighten Build opener explanation * docs: simplify Build review handoff wording |
||
|
Alex Verkhovsky
|
022bcbc66d |
Rename Quick Dev to Build (#2651)
* feat(bmm): rename quick dev to build * fix: address build rename review findings * fix: clarify deprecated build shims * fix: offer legacy customization migration |
||
|
Alex Verkhovsky
|
029ba287bc |
docs: make Quick Dev the canonical implementation workflow (#2643)
Rewrite published documentation and maintained translations around variable planning depth with one Phase 4 implementation loop. Update diagrams and AI indexes, and reject obsolete workflow terminology in deployable output. |
||
|
Alex Verkhovsky
|
116d52f5e0 |
feat: promote quick-dev to the official Phase 4 loop (#2637)
* feat(bmm): promote quick-dev to the official Phase 4 loop
- module-help.csv: bmad-quick-dev becomes the required Phase 4 item
(sprint-planning -> quick-dev -> code-review); the deprecated
create-story/dev-story rows leave the catalog; code-review and
qa-generate-e2e-tests chain after quick-dev.
- Dev agent menu drops its DS/CS entries.
- Docs and skill recommendations point at bmad-quick-dev instead of the
legacy split (architecture, ux, sprint-status, sprint-planning,
retrospective, named-agents, project-context,
expand-bmad-for-your-org, commands, workflow-map, getting-started).
The legacy skills themselves are untouched; deprecating them in place
is a follow-up PR.
- Quick-dev's user-facing descriptions (commands, workflow-map,
getting-started, help catalog, dev menu) drop the interactive-session
phrasing ("canonical implementation loop") for plain documentation
wording.
- bmad-retrospective: story-record scan also matches
spec-{epic}-{story}-*.md and quick-dev's section names, so retros see
quick-dev output.
- bmad-quick-dev: preserve an existing baseline_commit on resumed runs
instead of overwriting it with current HEAD.
* fix(bmm): address quick-dev review findings
|
||
|
Brian
|
c23f23400d |
feat: streamline core to an 8-skill set with merged review and editorial skills (#2603)
* feat: streamline core to a 5-skill kernel with standalone skill modules
Core installs 14 -> 5 catalog-visible skills; atoms exit to standalone
modules; installer gains real dependency resolution; zero npm deps.
- Merge bmad-editorial-review-prose/-structure into bmad-editorial-review
(structure models JIT-loaded, new customize.toml)
- Merge bmad-review-adversarial-general/-edge-case-hunter/-verification-gap
into bmad-review as selectable lenses; hidden husk-forwarders remain at
the old IDs (no catalog rows) so gds/loop/os-utils keep working
- Move bmad-brainstorming, bmad-party-mode, bmad-forge-idea out of core to
src/standalone-skills/ as single-skill modules; add bmad-analysis bundle
module (curated dependency list over the atoms)
- Move bmad-spec into bmm (2-plan-workflows)
- Modernize bmad-advanced-elicitation: uv run, customize.toml, methods
pick offloaded to scripts/pick_methods.py (with tests)
- Delete bmad-index-docs, bmad-shard-doc (removes the tree's only external
npm dependency), and the four deprecation shims (bmad-create-prd,
bmad-edit-prd, bmad-validate-prd, bmad-create-architecture); all added
to removals.txt
- Installer: activate the dependencies field (recursive union into
selectedModules, cycle-guarded, warn on unknown), config-driven picker
visibility; core stays force-installed
- bmm module.yaml declares deps on the three atoms
- Docs updated across all locales; new reference/standalone-skills.md;
shard-doc how-tos removed
* Restore original critical wording lost in the review/editorial merges
The merges into bmad-review and bmad-editorial-review were meant to keep
the source skills' critical wording behind progressive disclosure, not
paraphrase it away. Restore what was lost:
- lens-adversarial: clueless-weasel framing, extreme-skepticism wording,
the at-least-ten-issues quota, and zero-findings-is-suspicious (the
merge had inverted this to zero-is-valid)
- bmad-review SKILL: zero-findings stance is now per-lens
- lens-edge-case: mandatory exact-order step enforcement
- lens-verification-gap: exact 'No verification gaps found.' clean line
- editorial-review: full Human/LLM reader principles restored to new
references/reader-principles.md; structure-pass HIGH-VALUE DENSITY
role, front-load-value, anti-patterns, pacing check, and length_target
assessment; prose-pass role sentence, analyze-style-first step, and
merge-overlapping-fixes rule; output summary block and min-3-words HALT
* feat(installer): promote bmad-analysis bundle to src/bmad-analysis-skills
Move the bmad-analysis bundle module out of src/standalone-skills/ into its
own src/bmad-analysis-skills root, teach the installer to resolve it there
(getModulePath, official-modules listing, isBuiltInModule helper), and
update the marketplace manifest and standalone-skills docs to match.
* refactor(bmad-review): rename edge-case lens to edge-case-hunter
Rename the lens code and reference file (lens-edge-case.md ->
lens-edge-case-hunter.md), add explicit when = "always" to the shipped
lenses, and tighten the lens-selection wording in SKILL.md.
* feat(bmad-editorial-review): configurable style guide + analysis-driven rework
Apply the workflow-builder analysis recommendations:
- Make the baseline style guide configurable: style_guide in customize.toml
now IS the baseline (default "Microsoft Writing Style Guide") instead of
an empty override slot; SKILL.md no longer hardcodes the guide.
- Inline reader-principles.md into SKILL.md and delete the reference (it
loaded on every run and was half-duplicated inline).
- Complete the customization surface: activation_steps_prepend/append,
persistent_facts (project-context glob), on_complete, and a
review_output_path scalar split out of output_preferences; add a
file:-load fallback convention.
- Ground word metrics: new scripts/word_metrics.py (stdlib, PEP 723, tests)
emits total/per-section word counts so impact estimates and the reduction
summary use exact numbers.
- Cross-pass dedup: prose pass skips CUT-tagged passages and re-attaches
fixes in MERGE'd ones; output ranks by impact with a long-tail rollup.
- Polish: HALT threshold replaced with plain outcome, duplicate LLM-reader
bullets merged, all-caps lowered, literal Overview heading added.
* fix(installer): stop cache-refresh git commands from escaping to the parent repo
Two compounding bugs let a pre-commit test run shallow-fetch and hard-reset
the developer's own repository:
1. Git spawns in custom-module-manager and external-manager inherited the
hook environment. Git exports GIT_DIR (absolute, in worktree checkouts)
into pre-commit hooks; a child git then targets the hook's repo regardless
of cwd, and treats its cwd — the module cache dir — as the work tree. The
cache refresh's 'git fetch --depth 1' + 'git reset --hard origin/main'
therefore shallowed the shared .bare and moved the checked-out branch.
New git-env.js strips repo-targeting GIT_* vars from every git spawn in
both managers, including calls that previously inherited process.env
implicitly.
2. Test suite 51 (quickUpdate dependency expansion) ran the real
CustomModuleManager lookup, which scans ~/.bmad/cache/custom-modules and
network-refreshes every cached clone — real user state. The suite now
stubs findModuleSourceByCode.
Verified by rerunning the suite with GIT_DIR pointed at the repo and a PATH
shim blocking fetch/reset/clone: 432 passing, zero blocked calls.
* De-scope standalone-skills mechanism: atoms return to core, shims reinstated
Shrink the PR to its heart — the skill merges — and defer the module
mechanics to a follow-up where all skills become module-driven:
- bmad-brainstorming, bmad-party-mode, bmad-forge-idea move back to
src/core-skills/ as ordinary core skills with their catalog rows
restored; src/standalone-skills/ and the bmad-analysis bundle module
are removed
- Installer reverted to main: standalone discovery, hidden-module
filtering, dependency resolution, manifest changes (test suites 49-51
removed with the code); the cache-refresh git fix is retained
- The four bmm deprecation shims (create/edit/validate-prd,
create-architecture) are reinstated so enterprise installs that
invoke the old IDs or carry _bmad/custom overrides keep working;
descriptions trimmed to the short husk style; their removals.txt
entries dropped (removal rides the v7 cut as their frontmatter
promises)
- marketplace.json keeps the five plugin entries with atom paths
pointing at src/core-skills/
- Docs (en/cs/fr/vi/zh) reframe the three skills as core thinking
skills; standalone-skills.md reference page removed
* Fix all findings from the max-effort adversarial review
Correctness:
- Finish the edge-case -> edge-case-hunter lens rename at every caller:
the forwarder husk, the code-review/dev-auto/quick-dev review layers,
the renderer test assertion, and the stale example path in
bmad-review/SKILL.md
- marketplace.json: ship the five core kernel skills with
bmad-method-lifecycle so its skills' bmad-review/bmad-editorial-review/
bmad-help/bmad-advanced-elicitation invocations resolve in a
marketplace install
- pick_methods.py / word_metrics.py: force UTF-8 stdout (Windows locale
code pages crashed on the catalog's arrows and CJK headings)
- word_metrics.py: pair fences CommonMark-style so 4-backtick fences can
embed 3-backtick examples without corrupting sections; count CJK
characters as words
- pick_methods.py: validate --extra entries are JSON objects (was an
uncaught AttributeError); read catalogs with utf-8-sig (BOM'd CSVs
silently blanked every num)
- bmad-spec: activation now resolves {output_folder} (which the
Workspace uses) instead of the unused {planning_artifacts}; drop the
stale core-only-installs comment
- Editorial husks: pin the legacy output contracts (three-column table /
Document Summary report and exact empty-state lines) like the review
husks do
- PRD shims: advertise the real bmad-prd customize keys
(validation_checklist_template, prd_output_path, run_folder_pattern,
finalize_reviewers) instead of three that don't exist
- bmad-prd: add the forwarded-activation clause its shims rely on
(ported from bmad-architecture)
- Locale workflow-maps (fr/cs/vi/zh): add the bmad-spec Phase-2 row the
English map gained, which every locale's core-tools note points at
- git-env.js: also strip GIT_CONFIG_PARAMETERS and the
GIT_CONFIG_COUNT/KEY_n/VALUE_n family; pass gitEnv() to the three npm
install spawns whose transitive git calls inherited hook vars
Consistency:
- brain.py --extra overlay now replaces-by-name like pick_methods.py
(same customize.toml additional_* semantics across sibling skills),
with a regression test
* Fix prettier formatting in marketplace.json
* Apply valid CodeRabbit findings
- brain.py: catch malformed --extra overlays (bad JSON, non-array root,
non-object entries) into the clean error path instead of a raw
traceback, with a regression test; read catalogs and overlays with
utf-8-sig; normalize ALL CSV fields (required ones were unstripped and
could arrive as None from short rows)
- brain-selector: clamp the random-technique count to what the pool can
supply so the Total badge matches the actual draw (template +
regenerated assets/brain-selector.html)
- bmad-editorial-review: word_metrics command now uses the explicit
{skill-root}/ prefix
- resolve_party.py / resolve_personas.py: custom member overrides now
start from the installed entry, so omitted fields (icon, title,
description, module, team) survive; non-string member tokens land in
unresolved instead of raising TypeError; party's member loop gains the
isinstance guards its personas twin already had
- bmad-brainstorming: fix the SKILL.md claim that headless is the only
context for self-generated ideas (autonomous mode is interactive);
autonomous mode honors user-supplied techniques before self-selecting
- Docs: drop duplicate 'only' in the spec template; align zh-cn
forge-idea's bmad-review description with the English wording
* Create only the output folder at install time
bmm no longer pre-creates planning_artifacts, implementation_artifacts,
and project_knowledge — the last of which put an empty docs/ at every
project root. Skills create those lazily on first write. core now
declares {output_folder} in its directories block, which was previously
created only as a side effect of the artifact folders nesting under it.
|
||
|
Brian
|
02739932bc |
feat(installer): check for uv and standardize messaging on uv run (#2495)
Replace the standalone python3 environment check with a uv check, since uv is becoming the de facto standard for running BMad's Python scripts (`uv run <script>`) and uv provisions the interpreter itself. Installer: - Remove tools/installer/core/python-check.js and its wiring in ui.js - Add tools/installer/core/uv-check.js: warn-don't-block, no ack prompt (the migration is in progress, so a missing uv never blocks install). Missing uv warns and points the user at setup, preferring "ask your agent to set up uv" - Add a uv heads-up to the install intro (install-messages.yaml) and a uv tip line to the final "BMAD is ready" summary box - Swap test Suite 46 from python-check to uv-check coverage Docs and script comments (no functional skill invocations changed): - resolve_config.py / resolve_customization.py docstrings: drop the "No uv ... plain python3 is sufficient" claims; frame uv run as the standard, python3 as the transition fallback; examples use uv run - customize-bmad.md (en/fr/vi-vn): same reframing; example commands use uv run - Update uv run hints in brain.py / list_customizable test comments |
||
|
Brian
|
005ef1104a |
feat(core): add bmad-forge-idea skill + docs (#2492)
* feat(core): add bmad-forge-idea skill
Domain-agnostic idea-forging skill for BMad core. Takes a half-formed idea
and pressure-tests it in conversation until it hardens, proves out, or dies
cheaply — the quality of thinking is the product, not an artifact. One
question at a time with an always-on anti-sycophancy stance; two opt-in gears
(adversarial attack; a persona room resolved from the installed roster,
voiced by default and spawned when a branch needs independent minds); a
memlog as durable, resumable residue. Honest exits (hardened / killed /
clearer); optional brief distilled from the memlog that can feed bmad-spec or
bmad-quick-dev. Interactive and socratic; no headless mode.
Registered in core-skills/module-help.csv (menu code FI).
* Add forge-idea documentation and finalize skill scripts/conventions
Docs (Diátaxis):
- New explanation/forge-idea.md and how-to/pressure-test-an-idea.md
- core-tools.md: catalog entry + item section for bmad-forge-idea
- workflow-map.md and getting-started.md: Phase 1 (Analysis) listing
- De-collide the "forge" verb from bmad-prfaq positioning across docs
Skill:
- forge-idea SKILL.md: add term-sharpening axis, operationalize the
existing-project ground-truth rule, and add graceful degradation
- bmad-prfaq: description de-collision; Stage 1 now redirects upstream
to bmad-forge-idea for an unsound idea
- Unbundle the core memlog.py copy (skill references the core script at
{project-root}/_bmad/scripts); keep skill-local resolve_personas.py + tests
- customize.toml: comment refresh; on_complete as array
* Fix review findings: resolve_personas crash + doc accuracy
- resolve_parties: resolve token once + coerce non-strings (fixes KeyError
on mixed-case members and TypeError on unhashable members)
- Guard malformed party-mode config shapes so discovery stays best-effort
- _brief: pass through model/capabilities; register: no name-lookup hijack
- 5 new regression tests (case-insensitivity, malformed input, rename collision)
- Docs: correct bmad-review-adversarial-general name, bmad-prfaq handoff,
recursive resume glob, broken table row, and Produces filenames across
forge-idea/brainstorming/product-brief/architecture rows
|
||
|
Brian
|
7729ad461d |
docs: route all web-bundles install traffic to bmadcode.com/web-bundles (#2425)
Make bmadcode.com/web-bundles/ the single supported install path. The site keeps install steps current as Gemini and ChatGPT evolve, always points at the newest tagged release, and turns one signup into the notification channel for new bundles. - README.md: drop direct-folder install reference, point to the site - web-bundles/README.md: lead with Install (site), reframe folder as source for the shelf rather than install target - docs/explanation/web-bundles.md: replace the per-bundle INSTRUCTIONS.md steer with the site, replace the dead how-to link - docs/how-to/use-web-bundles.md: rewrite as a short pointer to the site (kept the file so existing inbound links resolve), retain prerequisites, persona customization, and build-your-own sections |
||
|
Emmanuel Atsé
|
cede485217 |
feat(docs): Add sidebar order validator for doc frontmatter (#2409)
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
|
||
|
Brian
|
3bc2ad30a3 |
feat(web-bundles): bring back V4 web bundles for V6 (#2421)
* feat(web-bundles): bring back V4 web bundles for V6 Restores the V4 web bundle pattern for V6. BMad planning skills are repackaged as one-click installs for Google Gemini Gems and ChatGPT Custom GPTs, so users can run analysis and planning conversations in flat-rate web LLM subscriptions instead of metered IDE tokens. Current shelf (6 bundles): brainstorming, product brief, PRFAQ, PRD, UX, market and industry research. Each bundle ships a SKILL.md protocol, an INSTRUCTIONS.md with a default persona and a contrasting swap example, and any required data files. New in this commit: - Market & Industry Research bundle merging market and domain research with Porter and Christensen anchors, Mary persona inherited from the BMad analyst agent, Geoffrey Moore swap example, Deep Research mode integrated as the default research path - web-bundles/README.md folder index listing all 6 bundles - README.md section announcing the V6 web bundle shelf - docs/explanation/web-bundles.md concept page (what, why, when) - docs/how-to/use-web-bundles.md install steps for Gemini Gems and ChatGPT Custom GPTs * docs(web-bundles): unindent admonition closer in use-web-bundles.md The :::note[Prerequisites] closer was indented under the last bullet, which can prevent the admonition from closing and break Starlight rendering for the rest of the page. Flush left now. |
||
|
Davor Racic
|
0f852a38ac |
feat(prompts): add directory prompt with updated Clack runtime (#2387)
* chore(deps): update @clack/core and @clack/prompts to latest versions and adjust Node.js engine requirement * feat(prompts): add directory prompt with autocomplete and create-directory support * chore(docs): update Node.js version requirement to 20.12+ across multiple documentation files * fix(prompts): code review fixes |
||
|
Brian
|
c52c9b5b0e |
feat(bmad-prd): new PRD skill + product-brief updates (#2378)
* feat(bmm): add bmad-prd skill and extend product-brief with external integrations
Consolidates the legacy create-prd/edit-prd/validate-prd trio into a single
lean facilitator with create/update/validate intent modes, following the
bmad-product-brief pattern. Both skills gain external_sources and
external_handoffs customize.toml fields for routing through corporate MCP
tools (Confluence, Jira, etc.) with graceful degradation, plus a File roles
constraint clarifying decision-log (audit trail) vs addendum (preserved
depth for downstream docs).
* refactor(bmad-prd): tighten SKILL.md and operationalize source-extractor pattern
- Compress Overview to remove coaching prose duplicated in Discovery
- Operationalize "Extract, don't ingest" with explicit subagent return contract; reference from Update, Validate, and Finalize input reconciliation instead of inline "read N documents"
- Fix Overview H1 -> H2 (was breaking pre-pass tooling)
- Move full headless JSON schemas to assets/headless-schemas.md; keep minimal example inline
- Compress File roles bullet; tighten Finalize step 1
SKILL.md: 124 -> 105 lines, ~4729 -> ~4467 tokens
* feat(bmad-prd): open-items gate, drop distillate, persona discipline, decision-log metadata
- Add Finalize "Open-items review" step (new step 4): counts OQs / [ASSUMPTION] / [NOTE FOR PM], walks them with user, flags high density as red flag against agreed stakes
- Validate now treats open-items density as a first-class finding category
- Resume / continuity surfaces open items deterministically as the first orientation step
- Drop the PRD's own distillate output and the bmad-distillator finalize step. Downstream workflows (UX, architecture, story creation) source-extract from prd.md directly via the canonical source-extractor pattern. Headless schemas, customize.toml comments, and template updated accordingly.
- Drop "status: draft" from PRD frontmatter and template; version/state transitions logged to decision-log.md instead. Finalize step 7 records the version transition entry.
- Add PRD Discipline bullet: personas must be research-grounded or marked [ILLUSTRATIVE]; must drive decisions; 2-4 personas max. Discipline pass enforces.
- Expand File roles bullet: competitive-analysis detail beyond a one-line landscape and operational/cost mechanics (rate-limiting, compression) belong in addendum
* feat(bmad-prd): outcome-driven trim, swappable validation checklist, HTML report
SKILL.md trim (4.7K -> ~3.2K tokens, 124 -> 93 lines):
- Cut anchor enumerations (HIPAA/PCI/NIST list, API/Mobile/Web list, hobby->regulated list, "fast/easy/scalable/intuitive", input enumerations, etc.) the LLM already knows
- Cut derivable reasoning (synonyms-cause-drift explanation, hobby-vs-enterprise examples, etc.)
- Cut good/bad examples that anchor LLM attention (password/SendGrid example, persona quote, "let me also add this nearby thing")
- Drop SMART-ceremony language from Measurable bullet (keep judgment-not-ritual; SMART principles fine)
Progressive disclosure to references/:
- Headless mode rules + JSON minimal example moved to references/headless.md (loaded only when invoked headless)
- On Activation step 6 gates mode detection: headless -> read references/headless.md and follow
Swappable validation checklist:
- New assets/prd-validation-checklist.md (15 items: Quality / Discipline / Structural / Stakes-gated, each one line)
- New customize.toml field validation_checklist (override per org)
- Used by Validate intent AND Finalize Step 3 -- same subagent, same checklist, two moments
- Replaces bmad-validate-prd's 13-step micro-file architecture; kept the valuable check dimensions (density, measurability, traceability, implementation leakage, etc.) and dropped the ceremony
HTML validation report:
- New scripts/render-validation-html.py (PEP 723, stdlib only, ~175 lines) renders structured findings JSON into a styled HTML report with pass/warn/fail grade, inline SVG score bar, category grouping
- New assets/validation-report-template.html (inline CSS, native <details>, no JS, no external deps) -- swappable via customize.toml validation_report_template
- New references/validation-render.md documents the subagent output contract and renderer invocation; loaded only when validate flow runs
- Auto-opens browser on interactive runs; headless skips the open
Mode flow consistency:
- Create and Update both now explicitly "proceed to ## Finalize"
- Validate / analyze is standalone -- explicit "does NOT enter ## Finalize"; renderer auto-opens the HTML
- analyze is a synonym for validate; intent detection routes both
- Update mode no longer has its own light-close validation step (Finalize Step 3 covers it)
* refactor(product-brief,bmad-prd): remove distillation from brief and PRD workflows
Drop bmad-distillator integration from bmad-product-brief (finalize step,
update mode, headless JSON, constraints) and clean up customize.toml comments.
Distillation is the wrong layer — story self-containment via epic solution
design docs is the right answer for downstream context.
Also commit pending bmad-prd changes: working mode selector (Express vs
Facilitative), open-items triage into phase-blocking/resolvable/deferred
buckets, persistence wording fix, and facilitation-guide reference.
* refactor(bmad-prd): aggressive SKILL.md compression, remove LLM-obvious content
* feat(bmad-prd,bmad-product-brief): surface party-mode and advanced-elicitation at opening
* refactor(bmm): retire bmad-create-prd/edit/validate, point docs and PM agent at bmad-prd
Removes the three separate PRD skills (create, edit, validate) in favor of the
unified bmad-prd skill. Updates module-help.csv, PM agent menu, workflow map,
getting-started tutorial, commands reference, customize/help SKILL.md examples,
and the website workflow-map diagram. Adds Recipe 6 (Advanced Integration
Patterns) to expand-bmad-for-your-org.md covering external_sources,
external_handoffs, doc_standards, and swappable templates.
* test(bmad-product-brief): drop distillate from evals
Distillate was removed from the product-brief workflow in
|
||
|
Brian
|
91a57499e9 |
feat(installer): add --set and --list-options for non-interactive config (#2354)
Closes #1663. Adds two installer flags so module config options can be set without interactive prompts. Designed for CI scripts, Dockerfiles, and enterprise rollouts where the user wants to bake answers into the install command rather than answer prompts. `--set <module>.<key>=<value>` (repeatable) sets any module config option. `--list-options [module]` lists every key the installer can discover locally — built-in modules (`core`, `bmm`) plus any cached official modules. One flag scales to every module without growing the CLI surface per option. ```bash npx bmad-method install --yes \ --modules bmm --tools claude-code \ --set bmm.project_knowledge=research \ --set bmm.user_skill_level=expert \ --set core.user_name=Brian ``` ## How it works `--set` is a post-install patch. The installer runs its normal flow untouched, then `applySetOverrides` upserts each value into the relevant config files: - `_bmad/config.toml` (team scope, default) - `_bmad/config.user.toml` (user scope, when the key already lives there — so user-scope keys like `core.user_name` and `bmm.user_skill_level` keep their proper file) - `_bmad/<module>/config.yaml` (so declared schema keys carry forward via the existingValue path on the next install) A module without `_bmad/<module>/config.yaml` is skipped silently — no orphan sections in `config.toml` for uninstalled modules. ## Tradeoffs documented in install-bmad.md - **Verbatim values.** `--set bmm.project_knowledge=research` writes `"research"`, not `"{project-root}/research"`. The `result:` template is not applied. Pass it explicitly if you want the rendered form: `--set bmm.project_knowledge='{project-root}/research'`. - **Carry-forward, declared keys.** Free — values land in the per-module `config.yaml`, so the next install reads them as `existingValue` and they become the prompt default (accepted under `--yes`). - **Carry-forward, undeclared keys.** Best-effort. The value lives in `config.toml` for the current install but won't be re-emitted on the next install (the manifest writer's schema-strict partition drops unknown keys). Re-pass `--set` if needed. - **No "key not in schema" validation.** Whatever you assert is written. ## Security Prototype-pollution defense: `--set __proto__.x=1` would otherwise reach `overrides.__proto__[x] = 1` and pollute `Object.prototype`, cascading into every plain-object lookup in the process. Defense-in- depth via parser-level reserved-name rejection (`__proto__`, `prototype`, `constructor`) AND `Object.create(null)` for the override maps. Verified the attack reproduces without the guard and is blocked with it. ## What's intentionally NOT integrated `--set` deliberately does not touch the prompt / template / schema collection flow. No pre-seeding answers, no question filtering, no function-default evaluation, no schema-strict partition exemption. That earlier integration approach was tried and scrapped: it spread state across `Config`, `OfficialModules`, `manifest-generator`, both collection helpers, and required parallel plumbing for quick-update — every bug fix touched a different layer. The post-install patch model covers the actual user need (set a config value from CI) in ~330 lines of `set-overrides.js` without the schema gymnastics. ## Files - `tools/installer/set-overrides.js` (new): parser, prototype-pollution guard, `applySetOverrides` post-install patch, `upsertTomlKey` / `tomlString` / `tomlHasKey` line-based TOML helpers - `tools/installer/list-options.js` (new): module.yaml discovery + formatter for `--list-options` - `tools/installer/commands/install.js`: register `--set` / `--list-options` flags, early validation, `--list-options` exit-code handling (await `stream.write` callback then `process.exitCode` to avoid truncating piped output), thread `setOverrides` through to quick-update - `tools/installer/core/config.js`: carry `setOverrides` field for the post-install patch step - `tools/installer/core/installer.js`: invoke `applySetOverrides` after `writeCentralConfig` (covers regular install + quick-update via the shared install path) - `tools/installer/ui.js`: parse `--set` for early validation, warn about overrides targeting modules not in `--modules`, drop those entries before threading - `docs/how-to/install-bmad.md`, `README.md`: usage, routing rules, carry-forward semantics, tradeoffs ## Test plan Suite 44 (24 cases): parser, prototype-pollution guard, `tomlString` escaping, `upsertTomlKey` across insert/replace/missing-section/ empty-file/preserved-newline cases, `applySetOverrides` happy path + uninstalled-module skip + missing-user-toml-creation + empty-input no-op, `discoverOfficialModuleYamls` / `formatOptionsList` sanity (hermetic via `BMAD_EXTERNAL_MODULES_CACHE` temp dir). 355 total passing. Lint + prettier + markdownlint clean. E2E smoke verified across: - [x] `--set` writes correct files (team toml / user toml / per-module yaml) for declared and undeclared keys - [x] Quick-update without `--set` carries forward declared keys via `existingValue` path - [x] Quick-update WITH `--set` applies cleanly (uniform behavior across action types) - [x] `--set` for unselected module: warned, no orphan section - [x] Prototype pollution: rejected with non-zero exit - [x] `--list-options bmm` exit 0 with full output through pipe; `--list-options nope` exit 1 - [x] Translated docs (`docs/{cs,fr,vi-vn,zh-cn}/`) intentionally not touched — they'll lag behind English until the translation pipeline runs |
||
|
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
|
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. |
||
|
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.
|
||
|
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> |
||
|
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
|
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>
|
||
|
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> |