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
- Drop "one-click install" framing in README and explanation page; setup is
multi-step but consistent across the shelf.
- Drop "two files (sometimes three)" claim; honestly name SKILL.md,
INSTRUCTIONS.md, and any required data files (templates, CSVs,
validation checklists).
- Add explicit setup pattern in README (create Gem/GPT, upload knowledge,
paste instructions, save).
- Add "Updating and customizing" section to the explanation page covering
re-upload-the-attachments updates and the rule of thumb that custom
changes belong in the pasted instructions block, not the knowledge
files, so future updates don't clobber team customizations.
* 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.
* 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
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
* 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>
* docs: drop slash-command syntax from skill references (editorial)
Skill names like bmad-help are now shown without a / prefix since
invocation syntax varies across platforms. First-encounter locations
(README, getting-started, get-answers, installer message, bmad-help
display rules) get editorial framing so new users understand these
are skill names to invoke by name.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: mechanical removal of slash prefix from all remaining skill references
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Update the BMAD acronym expansion from "Breakthrough Method of
Agile AI Driven Development" to "Build More Architect Dreams"
across README, docs homepage, and package.json description.
Co-authored-by: Brian <bmadcode@gmail.com>
- Add comprehensive public roadmap with In Progress, Getting Started, and Community sections
- Add roadmap callout to README.md and docs welcome page
- Add roadmap-specific card grid styles with equal-height cards
- Fix rehype-markdown-links plugin to detect docs directory in various project structures
- Rename roadmap.md to roadmap.mdx for proper Astro/Starlight rendering
- Update doc link validator to support .mdx files
Windsurf is no longer a preferred IDE. Only Claude Code and Cursor
are now recommended. Windsurf remains a supported platform (installer
still works, templates stay, reference tables stay).
- Set preferred: false in both platform-codes.yaml files
- Move windsurf entry to "Other IDEs" section in tools/platform-codes.yaml
- Fix codex.js hardcoding preferred: true in constructor
- Remove stale "3 preferred tools" count from ui.js JSDoc
- Update docs to list only Claude Code and Cursor as recommended
- Update docs/index.md popular tools to Claude Code, Cursor, Codex CLI
Users running npx bmad-method install may get a stale beta version
due to npx caching. Added explicit version pin as a workaround.
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- Update README to reflect V6 stable release and platform positioning
- Emphasize BMad Method as a module within the Module Ecosystem
- Simplify quick start and module sections
- Add Discord, GitHub, and YouTube links to installer next steps
* fix(docs): comprehensive documentation site review fixes
Rehype plugins:
- Rewrite rehype-markdown-links for correct relative .md resolution
- Handle raw HTML base paths and bare .md links in rehype-base-paths
- Guard protocol-relative URLs (//...) in all link processors
- Use file.path instead of file.history[0] for vfile compatibility
- Fail build when content directory cannot be detected
- Export helpers for testability; add 107 unit tests
Build & CI:
- Revert cancel-in-progress to false to avoid mid-deploy cancellation
- Remove redundant link-validation CI step (build validates internally)
- Remove unnecessary fetch-depth:0 from docs deploy workflow
- Refuse docs build on Windows (platform guard)
- Remove dead build scripts and stale references
Tooling:
- Add DOCS_ROOT boundary check in validate-doc-links.js
- Handle directory paths and prefix stripping in link validator
- Remove dead regex and add // guard in fix-doc-links.js
Accessibility & CSS:
- Darken caution/danger aside title colors for WCAG AA 4.5:1 contrast
- Fix 100vw scrollbar overflow (banner width:100%, html overflow-x:clip)
- Add :focus-visible ring to banner link for keyboard navigation
- Remove dead CSS declaration and add missing code block lang
Documentation content:
- Convert /docs/ absolute links to relative paths and fix llms.txt URLs
- Correct command file paths and naming in commands reference
- Update stale shard-doc command to current /bmad-shard-doc format
- Fix incomplete sentence in install-bmad.md
- Add Quick Flow next steps and fix 404 link path
- Expand thin content pages with substantive detail
- Add sidebar ordering frontmatter to all content pages
- Remove BMGD docs (moved to dedicated repo)
- Remove unused assets and misleading diagram caption
- Add non-iframe fallback link to workflow map diagram
- Remove dead noscript block from workflow-map
- Standardize BMAD to BMad, fix spelling/grammar, normalize headings
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides
- Move non-interactive-installation.md into how-to/ directory so it appears
in the sidebar navigation (was orphaned at docs root)
- Rewrite the page based on editorial review: consolidate redundant sections,
add missing how-to structure (prerequisites, "What You Get"), condense
installation modes from 5 subsections to a table, cut speculative examples
- Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3),
then the rest following user journey order
- Fix README link to point to docs site instead of repo-internal markdown path
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(docs): address documentation review findings
Fix broken directory tree, grammar errors, inconsistent naming,
missing admonition/headings, enable lastUpdated timestamps in CI,
and remove footer CSS that misapplied to the content footer.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(docs): move bleeding-edge install command out of Verify Installation
The alternative npx command for installing from main was misplaced
inside the "Verify Installation" section. Move it to a tip admonition
under Step 1 where users look for install options.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add non-interactive installation support
Add command-line flags to support non-interactive installation for CI/CD
pipelines and automated deployments:
- --directory: Installation directory
- --modules: Comma-separated module IDs
- --tools: Tool/IDE IDs (use "none" to skip)
- --custom-content: Custom module paths
- --action: Action type for existing installations
- --user-name, --communication-language, --document-output-language, --output-folder: Core config
- -y, --yes: Accept all defaults
When flags are provided, prompts are skipped. Missing values gracefully
fall back to interactive prompts.
* fix: complete non-interactive installation support
- Fix validation checks using truthy instead of !== true
- Add skipPrompts flag to skip module config prompts with --yes
- Add getDefaultModules() for automatic module selection with --yes
- Fix IDE selection to use array check instead of length check
Co-Authored-By: AiderDesk <https://github.com/hotovo/aider-desk>
---------
Co-authored-by: Brian <bmadcode@gmail.com>
- Remove duplicate "for" in README example command
- Fix "this is" to "thing is" in README
- Remove extra "at" in "star project icon at near" in README
- Fix "MEthod" to "Method" in customize-bmad.md
* Add interactive workflow guide page
Replace confusing static SVG workflow diagram with an interactive
guide at /workflow-guide. Users select their track (Quick Flow,
BMad Method, Enterprise) and see relevant phases, agents, commands,
and outputs. Update link validator to recognize custom page routes.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add visual dev loop indicator to workflow guide
Wrap create-story, dev-story, and code-review in a dashed border
group with a "Repeat for each story" label to clearly communicate
the iterative development cycle in Phase 4.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Simplify workflow guide to vertical slash command flow
Replace expandable phase cards with a clean vertical flow showing
slash commands as the primary element, with down arrows between
steps, agent badges, required/optional status, and concise
descriptions. Add prominent /bmad-help callout and note that
agent loading is optional.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Simplify README Quick Start with numbered command flows
Replace wordy paragraphs and track table with two clear numbered
paths (Quick Flow: 3 commands, BMad Method: 6 steps) and a
prominent /bmad-help callout as the primary guidance mechanism.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add Party Mode to README, /bmad-help to getting-started
Add Party Mode bullet to Why BMad section, note about agent-based
usage as an alternative to direct workflows, and a /bmad-help
mention in the getting-started tutorial after installation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add link to getting-started tutorial in README Quick Start
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Add workflow guide link to docs index New Here section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Update README tagline and format modules table
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix workflow-guide links to use relative paths
The /workflow-guide absolute path breaks with non-root base paths.
Use relative paths since workflow-guide is a custom Astro page
outside the docs collection. Docs-to-docs links keep the /docs/
pattern which the rehype plugin handles.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Revert workflow-guide links to absolute paths
Use /workflow-guide to match the /docs/ convention used throughout.
Works correctly on the production site where base path is /.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* docs: apply style guide to TEA Lite quickstart
- Remove duplicate H1 header (frontmatter provides title)
- Remove horizontal rules throughout
- Convert Prerequisites to admonition
- Add Quick Path TL;DR admonition
- Convert Key Takeaway to tip admonition
- Convert TEA Workflows list to Quick Reference table
- Convert Troubleshooting to Common Questions FAQ format
- Rename Need Help to Getting Help section
- Remove redundant Feedback section
Also adds missing @clack/prompts dependency from upstream merge.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: spell out acronyms in TEA Lite quickstart
- MCP → Model Context Protocol
- E2E → End-to-end (also fix missing article)
- CI/CD → Continuous integration/continuous deployment
- ATDD → Acceptance Test-Driven Development
- TDD → Test-Driven Development
- NFR → non-functional requirements
- Remove inaccurate CRUD reference
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: spell out TDD in ATDD link text
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: update branding with new wordmark logo and banner
- Add banner image to README header
- Replace website logo with wordmark, hiding title text
- Left-align logo with sidebar by reducing header padding
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: update README banner to new design with waveform
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add banner to docs website welcome page
- Revert README to original banner
- Add waveform banner to docs site welcome page
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: use waveform banner as website header logo
- Remove banner from welcome page content
- Update header logo to use banner-bmad-method2.png
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add separate logo for dark mode
Use banner-bmad-method-dark.png in dark mode for better blending
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: update header logos for light and dark modes
- Light mode: bmad-light.png (dark blue background with lightning)
- Dark mode: bmad-dark.png (light background variant)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: clean up unused banner images and add readme2
- Remove unused banner-bmad-method2.png and bmad-wordmark.png
- Add readme2.md with upcoming features section
- Update banner-bmad-method-dark.png
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* chore: remove unused banner image variants
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: finalize header logo graphics
- Rename bmad-light2.png to bmad-light.png as final version
- Remove readme2.md draft
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
- Expand tagline: "No gated Discord", "empowering everyone"
- Add emojis and stronger CTAs to Support section
- Consolidate star/subscribe asks into Support section
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add "100% free and open source" tagline at top
- Update YouTube line with upcoming master class/podcast
- Add "Help us grow" CTA for stars and subs
- Add new "Support BMad" section with donation and speaking info
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: add link auditor tools and fix broken docs links
- Add audit-doc-links.js to scan docs for broken links with auto-resolution
- Add fix-doc-links.js to apply suggested fixes (dry-run by default)
- Remove stale "Back to Core Concepts" breadcrumb links
- Update BMad acronym to "Breakthrough Method of Agile AI Driven Development"
- Update README links to docs.bmad-method.org
- Simplify upgrade callout in getting-started tutorial
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: reorganize docs structure and archive v4 tutorial
- Remove unused section index files (tutorials, how-to, explanation, reference)
- Move getting-started-bmadv4.md to _archive
- Update quick-start-bmgd.md to remove archived file reference
- Update upgrade-to-v6.md
- Update astro.config.mjs for new structure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: ignore underscore directories in link checker
Update check-doc-links.js to skip _archive, _planning, and other
underscore-prefixed directories when validating links.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add v4 users section to README
Add links to v4 documentation archive and upgrade guide for users
migrating from previous versions.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* feat: convert docs to site-relative links and add validation tools
- Convert all relative links (./ ../) to site-relative paths (/path/)
- Strip .md extensions and use trailing slashes for Astro/Starlight
- Add fix-doc-links.js to convert relative links to site-relative
- Add validate-doc-links.js to check links point to existing files
- Remove old audit-doc-links.js and check-doc-links.js
- Update build-docs.js to use new validation script
- Add npm scripts: docs:fix-links, docs:validate-links
- Update style guide with validation steps
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize acronym to BMad across documentation
Replace incorrect "BMAD" with correct "BMad" in text and frontmatter
while preserving "BMAD-METHOD" in GitHub URLs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix BMad acronym and remove draft README
- Correct acronym to "Breakthrough Method of Agile AI Driven Development"
- Remove unused README-draft.md
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize BMad acronym in README
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: standardize FAQ format across all FAQ pages
- Add TOC with jump links under "## Questions"
- Use ### headers for questions (no Q: prefix)
- Direct answers without **A:** prefix
- Remove horizontal rules and "Related Documentation" sections
- End each FAQ with issue/Discord CTA
- Update style guide with new FAQ guidelines
- Delete redundant faq/index.md (sidebar handles navigation)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: use repo-relative links with .md for GitHub compatibility
Convert all documentation links to repo-relative format (/docs/path/file.md)
so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix
and converts .md to trailing slash at build time for Astro/Starlight.
- Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths
- Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension
- Convert 217 links across 64 files to new format
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: handle /docs/ prefix in link validator
Update resolveLink to strip /docs/ prefix from repo-relative links
before checking if files exist.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: restore FAQ index page
Re-add the FAQ index page that was accidentally deleted, with
updated repo-relative link format.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
* feat: add documentation website with Docusaurus build pipeline
* feat(docs): add AI discovery meta tags for llms.txt files
- Add global headTags with ai-terms, llms, llms-full meta tags
- Update landing page link to clarify AI context purpose
* fix(docs): restore accidentally deleted faq.md and glossary.md
Files were removed in 12dd97fe during path restructuring.
* fix(docs): update broken project-readme links to GitHub URL
* feat(schema): add compound trigger format validation
- Comprehensive alpha.11 changelog capturing all major features
- Condensed earlier alpha releases (0-10) to 5 key bullets each
- Reduced changelog from 1,744 to 609 lines for better readability
- Updated README status badges and installation instructions
## The Tale of the Frame Expert
Once upon a time, BMad Method had a specialized agent called Frame Expert.
This agent was the master of all visual artifacts - flowcharts, diagrams,
wireframes, data flows. Whenever anyone needed a diagram, they called upon
Frame Expert. The agent lived in its own isolated domain with four dedicated
workflows and a library of shared templates.
## The Awakening
But something felt wrong. Teams using BMad Method were meant to mirror real
agile teams - Product Managers, Architects, UX Designers, Tech Writers,
Developers. Each agent represented an authentic role you'd find in any
software team.
Except Frame Expert.
No real agile team has a "Frame Expert" or "Diagram Specialist" who creates
all visual artifacts. In real teams, Architects diagram system architecture.
PMs flowchart processes. UX Designers wireframe interfaces. Tech Writers
create documentation diagrams. The visuals emerge from the domain experts
who need them, not from a centralized diagram factory.
Frame Expert was an abstraction that made technical sense but violated the
very soul of BMad Method - authentic agile role modeling.
## The Transformation
And so Frame Expert was dissolved, its knowledge distributed to those who
truly needed it:
**The Architect** inherited system architecture diagrams and data flows -
the blueprints of technical systems they design.
**The Product Manager** received process flowcharts - the visual maps of
features and workflows they orchestrate.
**The UX Designer** claimed wireframes - the interface sketches that bring
their vision to life.
**The Tech Writer** gained all diagram types - the visual aids that clarify
their documentation.
Each agent now creates diagrams in their domain, using their expertise,
serving their purpose.
## The Shared Knowledge
But the wisdom of diagram creation itself - the Excalidraw templates, the
component libraries, the validation patterns - this knowledge was too
valuable to scatter. It was elevated to core resources, where both BMM
agents AND the new CIS presentation-master agent could draw upon it.
Shared infrastructure for common needs. Distributed execution for domain
expertise.
## The Ripple Effects
With diagrams now properly distributed, other misalignments became visible:
Epic creation was happening in Phase 2 (Planning), before Architecture
existed. But epics need architectural context - API contracts, data models,
technical decisions. So epic creation migrated to Phase 3 (Solutioning),
after Architecture provides that foundation.
Workflow paths were updated. Documentation gained visual flowcharts showing
the complete journey. Agent naming standards were clarified - filenames are
stable roles, persona names are user dreams.
## What Changed
**Removed:**
- frame-expert.agent.yaml (the centralized specialist)
- All frame-expert workflows and shared resources
- Phase 2 epic creation workflow (wrong timing)
- game-design workflow path (consolidated to method track)
- v6-open-items.md (planning doc, now complete)
**Distributed Diagram Capabilities:**
- Architect: create-excalidraw-diagram, create-excalidraw-dataflow
- PM: create-excalidraw-flowchart
- Tech Writer: create-excalidraw-{diagram,dataflow,flowchart}, generate-mermaid
- UX Designer: create-excalidraw-wireframe
**Created:**
- src/core/resources/ (shared diagram context for all modules)
- src/modules/cis/agents/presentation-master.agent.yaml (visual comms specialist)
- src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/ (epic creation's new home)
- src/modules/bmm/workflows/diagrams/ (distributed diagram implementations)
- src/modules/bmm/docs/images/ (workflow visualization assets)
**Enhanced:**
- All agent definitions with domain-appropriate diagram workflows
- Documentation with embedded workflow diagrams and visual guides
- Agent compilation docs with critical naming convention rules
- All 4 workflow paths (enterprise/method × brownfield/greenfield)
**Fixed:**
- Epic creation now in Phase 3 after Architecture
- Story context path variables in BMGD module
- PRD workflow descriptions (epics moved to Phase 3)
## For Users
The Frame Expert commands are gone. In their place:
- Need architecture diagrams? Ask `/architect`
- Need process flows? Ask `/pm`
- Need wireframes? Ask `/ux-designer`
- Need documentation visuals? Ask `/tech-writer`
Each expert creates diagrams in their domain, with their context, using
their judgment.
This is how real teams work.
## Overview
This commit represents a complete overhaul of the BMAD agent creation system, establishing clear standards for agent development, installation workflows, and persona design. The changes span documentation, tooling, reference implementations, and field-specific guidance.
## Key Components
### 1. Agent Installation Infrastructure
**New CLI Command: `agent-install`**
- Interactive agent installation with persona customization
- Supports Simple (single YAML), Expert (sidecar files), and Module agents
- Template variable processing with Handlebars-style syntax
- Automatic compilation from YAML to XML (.md) format
- Manifest tracking and IDE integration (Claude Code, Cursor, Windsurf, etc.)
- Source preservation in `_cfg/custom/agents/` for reinstallation
**Files Created:**
- `tools/cli/commands/agent-install.js` - Main CLI command
- `tools/cli/lib/agent/compiler.js` - YAML to XML compilation engine
- `tools/cli/lib/agent/installer.js` - Installation orchestration
- `tools/cli/lib/agent/template-engine.js` - Handlebars template processing
**Compiler Features:**
- Auto-injects frontmatter, activation, handlers, help/exit menu items
- Smart handler inclusion (only includes action/workflow/exec/tmpl handlers actually used)
- Proper XML escaping and formatting
- Persona name customization (e.g., "Fred the Commit Poet")
### 2. Documentation Overhaul
**Deleted Bloated/Outdated Docs (2,651 lines removed):**
- Old verbose architecture docs
- Redundant pattern files
- Outdated workflow guides
**Created Focused, Type-Specific Docs:**
- `src/modules/bmb/docs/understanding-agent-types.md` - Architecture vs capability distinction
- `src/modules/bmb/docs/simple-agent-architecture.md` - Self-contained agents
- `src/modules/bmb/docs/expert-agent-architecture.md` - Agents with sidecar files
- `src/modules/bmb/docs/module-agent-architecture.md` - Workflow-integrated agents
- `src/modules/bmb/docs/agent-compilation.md` - YAML → XML process
- `src/modules/bmb/docs/agent-menu-patterns.md` - Menu design patterns
- `src/modules/bmb/docs/index.md` - Documentation hub
**Net Result:** ~1,930 line reduction while adding MORE value through focused content
### 3. Create-Agent Workflow Enhancements
**Critical Persona Field Guidance Added to Step 4:**
Explains how the LLM interprets each persona field when the agent activates:
- **role** → "What knowledge, skills, and capabilities do I possess?"
- **identity** → "What background, experience, and context shape my responses?"
- **communication_style** → "What verbal patterns, word choice, quirks, and phrasing do I use?"
- **principles** → "What beliefs and operating philosophy drive my choices?"
**Key Insight:** `communication_style` should ONLY describe HOW the agent talks, not restate role/identity/principles. The `communication-presets.csv` provides 60 pure communication styles with NO role/identity/principles mixed in.
**Files Updated:**
- `src/modules/bmb/workflows/create-agent/instructions.md` - Added persona field interpretation guide
- `src/modules/bmb/workflows/create-agent/brainstorm-context.md` - Refined to 137 lines
- `src/modules/bmb/workflows/create-agent/communication-presets.csv` - 60 styles across 13 categories
### 4. Reference Agent Cleanup
**Removed install_config Personality Bloat:**
Understanding: Future installer will handle personality customization, so stripped all personality toggles from reference agents.
**commit-poet.agent.yaml** (Simple Agent):
- BEFORE: 36 personality combinations (3 enthusiasm × 3 depths × 4 styles) = decision fatigue
- AFTER: Single concise persona with pure communication style
- Changed from verbose conditionals to: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
- Reduction: 248 lines → 153 lines (38% reduction)
**journal-keeper.agent.yaml** (Expert Agent):
- Stripped install_config, simplified communication_style
- Shows proper Expert agent structure with sidecar files
**security-engineer.agent.yaml & trend-analyst.agent.yaml** (Module Agents):
- Added header comments explaining WHY Module Agent (design intent, not just location)
- Clarified: Module agents are designed FOR ecosystem integration, not capability-limited
**Files Updated:**
- `src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml`
- `src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml`
- `src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml`
### 5. BMM Agent Voice Enhancement
**Gave all 9 BMM agents distinct, memorable communication voices:**
**Mary (analyst)** - The favorite! Changed from generic "systematic and probing" to:
"Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
**Other Notable Voices:**
- **John (pm):** "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
- **Winston (architect):** "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
- **Amelia (dev):** "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
- **Bob (sm):** "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
- **Sally (ux-designer):** "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
**Pattern Applied:** Moved behaviors from communication_style to principles, keeping communication_style as PURE verbal patterns.
**Files Updated:**
- `src/modules/bmm/agents/analyst.agent.yaml`
- `src/modules/bmm/agents/pm.agent.yaml`
- `src/modules/bmm/agents/architect.agent.yaml`
- `src/modules/bmm/agents/dev.agent.yaml`
- `src/modules/bmm/agents/sm.agent.yaml`
- `src/modules/bmm/agents/tea.agent.yaml`
- `src/modules/bmm/agents/tech-writer.agent.yaml`
- `src/modules/bmm/agents/ux-designer.agent.yaml`
- `src/modules/bmm/agents/frame-expert.agent.yaml`
### 6. Linting Fixes
**ESLint Compliance:**
- Replaced all `'utf-8'` with `'utf8'` (unicorn/text-encoding-identifier-case)
- Changed `variables.hasOwnProperty(varName)` to `Object.hasOwn(variables, varName)` (unicorn/prefer-object-has-own)
- Replaced `JSON.parse(JSON.stringify(...))` with `structuredClone(...)` (unicorn/prefer-structured-clone)
- Fixed empty YAML mapping values in sample files
**Files Fixed:**
- 7 JavaScript files across agent tooling (compiler, installer, commands, IDE integration)
- 1 YAML sample file
## Architecture Decisions
### Agent Types Are About Architecture, Not Capability
- **Simple:** Self-contained in single YAML (NOT limited in capability)
- **Expert:** Includes sidecar files (templates, docs, etc.)
- **Module:** Designed for BMAD ecosystem integration (workflows, cross-agent coordination)
### Persona Field Separation Critical for LLM Interpretation
The LLM needs distinct fields to understand its role:
- Mixing role/identity/principles into communication_style confuses the persona
- Pure communication styles (from communication-presets.csv) have ZERO role/identity/principles content
- Example DON'T: "Experienced analyst who uses systematic approaches..." (mixing identity + style)
- Example DO: "Systematic and probing. Structures findings hierarchically." (pure style)
### Install-Time vs Runtime Configuration
- Template variables ({{var}}) resolve at compile-time
- Runtime variables ({user_name}, {bmad_folder}) resolve when agent activates
- Future installer will handle personality customization, so agents should ship with single default persona
## Testing
- All linting passes (ESLint with max-warnings=0)
- Agent compilation tested with commit-poet, journal-keeper examples
- Install workflow validated with Simple and Expert agent types
- Manifest tracking and IDE integration verified
## Impact
This establishes BMAD as having a complete, production-ready agent creation and installation system with:
- Clear documentation for all agent types
- Automated compilation and installation
- Strong persona design guidance
- Reference implementations showing best practices
- Distinct, memorable agent voices throughout BMM module
Co-Authored-By: BMad Builder <builder@bmad.dev>
Co-Authored-By: Mary the Analyst <analyst@bmad.dev>
Co-Authored-By: Paige the Tech Writer <tech-writer@bmad.dev>
Brian Madison
Davor Racic
Alex Verkhovsky
Chris Chen
Ssabae
jheyworth
Vladimir Hrusovsky
Brian Madison
Murat K Ozcan
The Chef
forcetrainer
forcetrainer