* 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.
* 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().
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>
* docs(cs): add Czech (Čeština) documentation translation
Add complete Czech translation of all 29 documentation files mirroring
the English source structure. Register cs-CZ locale in Starlight config
with sidebar label translations.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cs): repair corrupted characters and table formatting in Czech docs
Fix UTF-8 encoding artifacts in customize-bmad.md and upgrade-to-v6.md,
align markdown table formatting, and correct Czech grammar in
project-context.md heading.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cs): address CodeRabbit review feedback
- Normalize 64 Czech quotation marks to proper „…" pairs across 14 files
- Fix corrupted UTF-8 box-drawing character in upgrade-to-v6.md
- Use relative roadmap link (./roadmap) in index.md for locale consistency
- Fix typo: Podníková → Podniková in modules.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cs): sync Czech translation with upstream agent consolidation and PRFAQ addition
Agents: remove Barry/Quinn/Bob (merged into Developer), add WB trigger and PRFAQ to Analyst.
Tutorials/commands/workflow-map: fix SM→DEV references, add PRFAQ workflow entries.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
* 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(checkpoint): add explainer page and workflow diagram
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(checkpoint): replace excalidraw source with exported PNG diagram
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Delete the Barry agent persona and migrate its QD (quick-dev)
capability to the Amelia dev agent. Update EN, ZH, and FR docs,
marketplace JSON, and workflow diagrams.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add bmad-prfaq skill as alternative to product brief
Add Working Backwards PRFAQ challenge skill for stress-testing product
concepts through Amazon's PRFAQ methodology. Includes press release
drafting, customer FAQ, internal FAQ, and verdict stages with subagent
support for artifact scanning and web research.
- New bmad-prfaq skill with 5-stage interactive gauntlet and headless mode
- Subagents for artifact analysis and web research (graceful degradation)
- Research-grounded output directive for current market/competitive data
- Always produces distillate for downstream PRD consumption
- Fix manifest array syntax in both prfaq and product-brief manifests
- Drop number prefixes from reference files
- Update docs: getting-started, workflow-map, agents, skills reference
- Add analysis-phase explainer doc with comparison table and decision guide
- Update workflow-map-diagram.html with prfaq card
- Add -H and -A args to CSV for both skills
- Add unist-util-visit as devDependency (was imported but undeclared)
* fix: harden bmad-prfaq for compaction resilience and context efficiency
Add coaching persona re-anchors to all stage prompts so the behavioral
directive survives context compaction. Add do-not-read guards at resume
detection, headless mode, and input gathering to prevent parent agent
context bloat. Add Stage 1 coaching notes capture. Adapt template and
press release stage for non-commercial concept types. Cap subagent
response token budgets.
* fix: add config.user.yaml to file-ref validator allowlist
Also update PRFAQ config path to use correct _config/bmm/ prefix.
* refactor(installer): restructure installer with clean separation of concerns
Move tools/cli/ to tools/installer/ with major structural cleanup:
- InstallPaths async factory for path resolution and directory creation
- Config value object (frozen) replaces mutable config bag
- ExistingInstall value object replaces stateful Detector class
- OfficialModules + CustomModules + ExternalModuleManager replace monolithic ModuleManager
- install() is prompt-free; all user interaction in ui.js
- Update state returned explicitly instead of mutating customConfig
- Delete dead code: dependency-resolver, _base-ide, IdeConfigManager,
platform-codes helpers, npx wrapper, xml-utils
- Flatten directory structure: custom/handler → custom-handler,
tools/cli/ → tools/installer/, lib/ directories removed
- Update all path references in package.json, tests, CI, and docs
* fix(installer): guard ExistingInstall.version and surface module.yaml errors
Guard ExistingInstall.version access with .installed check in
uninstall.js, ui.js, and installer.js to prevent throwing on
empty/partial _bmad dirs. Surface invalid module.yaml parse errors
as warnings instead of silently returning empty results.
* fix(bmad-init): correctly resolve output_folder paths outside project root
When output_folder was set to an absolute path (e.g. /Users/me/outputs),
the {project-root}/{value} result template stored it as
{project-root}//absolute/path. resolve_project_root_placeholder then did
a naive string replace, producing /project//absolute/path — a broken path
that workflows could not resolve.
For relative paths outside the root (e.g. ../../sibling), the same naive
replace left un-normalized paths like /project/../../sibling in the
resolved config, which some tools mishandled.
Fix resolve_project_root_placeholder to strip the {project-root} token,
detect whether the remainder is absolute (returning it directly) or
relative (joining with project root and normalizing via os.path.normpath).
Fix apply_result_template to skip the template entirely when raw_value is
already an absolute path, and to normalize the result for relative-but-
outside paths. This covers the bmad-init SKILL write path, which bakes
the resolved path directly into config.yaml.
Add 7 tests covering all three path cases (absolute, relative-with-
traversal, normal in-project) for both functions.
* Address review comments
---------
Co-authored-by: Akhilesh Tyagi <akhilesh.t@nextiva.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* docs(zh-cn): refine established project guides
clarify the boundary between new-project and established-project usage so zh-cn readers can choose the right workflow path.
align project context terminology and command references with current conventions while keeping guidance concise and executable.
Feishu: https://www.feishu.cn/
Made-with: Cursor
* docs(zh-cn): fix project-context syntax and wording
我将 project-context 文档中的提示块语法统一回项目规范的 `:::...:::` 形式，避免与文档风格约定不一致。
我同时把“在不同用户故事（story）间决策不一致”调整为“之间决策不一致”，提升中文表达的自然度与可读性。
Feishu: <https://www.feishu.cn/>
Made-with: Cursor
---------
Co-authored-by: leon <leon.liang@hairobotics.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
Agent skills referenced with shortened names (bmad-pm, bmad-architect,
etc.) that don't match installed skill names. Fixed to use actual names
(bmad-agent-pm, bmad-agent-architect, etc.) across EN, ZH-CN, and FR.
Also fixed bmad-research to three specific research skills (EN, FR) and
bmad-product-brief to bmad-create-product-brief (ZH-CN).
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(zh-cn): refine help and quick-fixes guides
improve zh-cn troubleshooting guidance so users can quickly choose the right support path and self-recover from common issues.
align bmad-help and quick-dev usage wording with current invocation conventions and remove glossary-style appendices to keep the pages action-oriented.
Feishu: N/A
Made-with: Cursor
* docs(zh-cn): fix tip admonition fence syntax
我把 get-answers-about-bmad 文档中的 `::::tip` 语法改为仓库统一使用的 `:::tip`。
此前四冒号写法与项目文档约定不一致，可能导致提示块渲染异常；现在与现有 Starlight 写法保持一致。
Feishu: <https://www.feishu.cn/>
Made-with: Cursor
---------
Co-authored-by: leon <leon.liang@hairobotics.com>
* 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>
* refactor(installer): remove dead agent compilation pipeline
Delete 9 files (~2,600 lines) that compiled .agent.yaml to .md.
No .agent.yaml files exist in the source tree — agents now ship
as pre-built SKILL.md. Clean up all references in installer,
module manager, custom handler, base IDE, UI, and tests.
* refactor(custom-handler): remove dead install/copy/find methods
CustomHandler.install(), copyDirectory(), and findFilesRecursively()
are never called — custom modules are installed via moduleManager.install()
since Dec 2025. Also removes unused FileOps import and constructor.
Verified with before/after clean-installer comparison (codex + custom
modules with custom.yaml): output is identical.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(installer): remove dead compilation refs from docs and module manager
Address review findings from PR #2080 triage:
- Remove compile-agents from CLI action docs (en, fr, zh-cn)
- Remove dead vendorCrossModuleWorkflows() and .agent.yaml skip logic
- Clean stale compilation-era comments in manifest-generator
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove DEV agent references and simplify to Quick Dev as the single
entry point. Show free-form intent examples, add deferred work section,
clarify that Quick Dev commits for you.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Quick Flow was an umbrella for quick-spec + quick-dev. Quick Spec is
gone and the new preview was promoted to bmad-quick-dev, so the explainer
should be about quick-dev directly. Replaces quick-flow.md with the
original quick-dev-new-preview.md content (renamed), including the
diagram reference. zh-cn uses the original hand-written Chinese
translation. Also removes stale Quick Spec references from agents.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: consolidate agents into phase-based skill directories
Remove separate agent/workflow/skill directories (src/bmm/agents,
src/bmm/workflows, src/core/skills, src/utility/agent-components) and
reorganize all content into phase-based structures under src/bmm-skills
(1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) and
src/core-skills. Eliminates the agent/skill distinction by treating
agents as skills within their workflow phase.
* fix: update broken file references to use new bmm-skills paths
* docs: update all references for unified bmad-quick-dev workflow
Remove all references to the old separate bmad-quick-spec and
bmad-quick-dev-new-preview workflows. The new bmad-quick-dev is a
unified workflow that handles intent clarification, planning,
implementation, review, and presentation in a single run.
Updated files across English docs, Chinese translations, source
skill manifests, website diagram, and build tooling.
* prototype preview of new version of product brief skill
* chore: re-enable bmad-builder external module
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* config loading with existing location
* refactor: rename bmad-bmm-product-brief-preview to bmad-product-brief-preview
Drop the redundant bmm prefix from the product brief preview skill folder
to align with the standard naming convention.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add core tools reference and apply Diataxis style fixes
Add comprehensive reference doc for all 11 built-in core tools (tasks
and workflows) that ship with every BMad installation — bmad-help,
brainstorming, party-mode, distillator, advanced-elicitation, both
review tools, both editorial tools, shard-doc, and index-docs. Each
entry follows the Configuration Reference structure with purpose,
use cases, how it works, inputs, and outputs.
Style fixes across existing docs:
- reference/commands.md: convert #### headers to bold text, replace
sparse task table with link to new core-tools reference
- how-to/get-answers-about-bmad.md: remove horizontal rule between
sections (Diataxis violation)
- how-to/project-context.md: consolidate 4 consecutive tip admonitions
into single admonition with bullet list, add AGENTS.md reference
Also includes:
- Add bmad-distillator task to core module with compression agents,
format reference, splitting strategy, and analysis scripts
- Add Distillator entry to module-help.csv
- Rename supports-autonomous to supports-headless in product-brief
manifest
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* core items to skills folder
* fix calls to invoke party mode
* fix calls to invoke party mode and AE as skills
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Translate docs/explanation/quick-dev-new-preview.md to Chinese.
This document explains the experimental Quick Flow improvement
that reduces human-in-the-loop friction while maintaining quality.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a "Trigger Types" section to the agents reference page
explaining the difference between workflow triggers (no arguments)
and conversational triggers (arguments required). Lists all
Technical Writer triggers that expect user-provided input with
examples of proper usage.
Fixes#1682
The testing reference page incorrectly described Quinn's Automate
workflow as running per-story before Code Review, contradicting the
workflow map which positions it after epic completion. Align the testing
page with the workflow map: Quinn runs after all stories in an epic are
implemented and code-reviewed.
* 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>
* refactor(augment): remove legacy YAML/XML workflow rules from code review guidelines
All workflows have been converted to markdown. Remove workflow.yaml,
workflow.xml, and config_source references from Augment review rules.
Drop the entire xml_workflows section (5 rules) and the YAML-specific
standard_workflow_instructions rule.
* refactor: extract discover_inputs protocol from workflow.xml into co-located markdown
Convert the discover_inputs XML protocol (FULL_LOAD, SELECTIVE_LOAD,
INDEX_GUIDED strategies) into standalone markdown files placed alongside
the two workflows that use it (create-story, code-review). Replace
<invoke-protocol> tags with explicit file references. This decouples
the workflows from workflow.xml, enabling its deletion in a follow-up.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: delete dead YAML/XML workflow engine files
Remove 5 files made obsolete by the workflow.yaml → workflow.md migration:
- workflow.xml (the YAML workflow interpreter engine)
- dev-story/instructions.xml (superseded by workflow.md)
- 3 installer templates for YAML workflow command generation
References in CLI code will be cleaned up in follow-up commits.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: delete obsolete workflow handler fragments
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: remove YAML workflow code paths from CLI installer pipeline
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: remove workflow.xml references from manifests and checklists
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: remove workflow.xml references from English command docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: update fixtures to remove workflow.yaml references
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update workflow.yaml example path to workflow.md in handler-multi
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: stop tracking workflow/validate-workflow as handler attributes
These handler fragments were deleted — the exec handler already covers
loading .md workflow files directly.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: rename workflow attribute to exec in agent menu items
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address PR review findings from triage
- Fix regex capture group index in module manager workflow path parsing
- Remove stale workflow handler references from handler-multi.txt
- Replace workflow with multi in activation-steps dispatch contract
- Remove dead validate-workflow emission from compiler and xml-builder
- Align commands.md wording to remove engine references
- Fix relativePath anchoring in _base-ide.js recursive directory scans
- Remove dead code from workflow-command-generator (unused template,
generateCommandContent, writeColonArtifacts, writeDashArtifacts)
- Delete unused workflow-commander.md template
- Add regression test for workflow path regex
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Align documentation with the skills-based architecture migration by
replacing references to "commands", "slash commands", and legacy command
names with the new "skills" terminology and skill names.
* feat(i18n): add zh-cn locale support with Starlight routing
Reorganize Chinese translations from docs_cn/ into docs/zh-cn/
following Starlight's i18n content structure. Configure Starlight
with root locale (en, unprefixed) and zh-cn (/zh-cn/ prefix).
- Move 28 files from docs_cn/*_cn.md to docs/zh-cn/*.md
- Fix 21 internal links to remove _cn suffixes
- Add defaultLocale + locales config to astro.config.mjs
- Add .gitignore exception for docs/zh-cn/ (overrides z*/ rule)
- Language switcher activates automatically via existing Header
- hreflang tags auto-generated by Starlight on all pages
* feat(i18n): add zh-CN UI translations and sidebar labels
- Add website/src/content/i18n/zh-CN.json with Starlight UI strings
- Add sidebar group label translations (欢迎, 路线图, 教程, etc.)
- Register i18n collection in content config to fix deprecation warning
* fix(i18n): exclude 404 pages from sitemap
Custom 404 pages (root and zh-cn) were indexed as regular content in
the sitemap. Add a filter to the @astrojs/sitemap integration that
matches the /404 path segment precisely via regex on the URL pathname.
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
BMad-Help is one of V6's flagship features but was undersold in docs.
This update positions it properly as the intelligent guide that:
- Inspects project state and detects what's completed
- Understands natural language queries
- Varies options based on installed modules
- Auto-invokes after every workflow
- Recommends first required tasks
Changes:
- Add dedicated "Meet BMad-Help" section to getting-started
- Expand commands.md with full BMad-Help subsection and examples
- Reposition get-answers-about-bmad.md to start with BMad-Help
- Enhance install-bmad.md and established-projects.md with query examples
- Add index.md tip box promoting /bmad-help as quickest way to dive in
Adds a new "Extend and Customize" section with a link to the BMad Builder documentation for users interested in creating custom agents, workflows, or modules.
* 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>
The downloads page offered bmad-sources.zip and bmad-prompts.zip, both
redundant: GitHub provides source archives for every tag natively, and
npx bmad-method install is the supported path for compiled prompts.
Remove the downloads page, all bundle generation code, the archiver
dependency, and nav links. The llms.txt and llms-full.txt files (the
genuinely useful artifacts) continue to be generated as before.
* docs: add official external modules reference page
* chore: remove obsolete docs and basement files
* fix: update robots.txt URLs to docs.bmad-method.org
* fix: generate robots.txt dynamically from site base URL
Replace static robots.txt with an Astro endpoint that uses the
configured site URL, so sitemap references are correct on both
fork deployments and production.
* fix: unify site URL resolution in build-docs.js
build-docs.js had its own hardcoded fallback URL
(bmad-code-org.github.io) instead of using the shared
getSiteUrl() function, causing URL mismatches between
robots.txt, llms.txt, and sitemaps. Now all components
resolve the site URL through the same function. Renamed
site-url.js to .mjs to avoid Node ESM detection warnings.
* fix: correct module names and relocate prompt file
- CIS: "Creative Innovation Suite" → "Creative Intelligence Suite"
- GDS: "Game Dev Suite" → "Game Dev Studio"
- Move _prompt-external-modules-page.md from docs/ to tools/docs/
* refactor: convert build-docs to ESM, eliminate mutable globals
- Convert build-docs.js to build-docs.mjs (CJS → ESM)
- Import getSiteUrl directly, remove async import workaround
- Kill mutable SITE_URL global, call getSiteUrl() where needed
- Clean up Banner.astro variable naming
- Update package.json and CI workflow for .mjs extension
* 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>
* docs: rename brownfield to established projects
Flatten how-to/brownfield/ subdirectory and replace jargon term
"brownfield" with more accessible "established projects" throughout.
- brownfield/index.md → established-projects.md
- brownfield/quick-fix-in-brownfield.md → quick-fixes.md
- brownfield-faq.md → established-projects-faq.md
- Update all internal links and references
* docs: remove redundant phrase from quick-fixes description
* docs: restore natural language in established-projects body
The getting-started tutorial referenced agents and workflows by name
(e.g., "Load the PM agent", "Run the prd workflow") without providing
the actual commands to type. This adds the exact slash commands inline
alongside the existing prose so new users know precisely what to run.
Apply Diataxis documentation framework to BMGD docs:
game-types.md:
- Convert to Reference format (austere, consistent structure)
- Add Examples field to all 24 game types
- Remove redundant Overview, GDD Section Mapping, Next Steps
- Condense Hybrid Game Types to reference table
- Remove Tags (no functional purpose for human readers)
quick-flow-workflows.md:
- Convert to How-to guide format
- Remove conceptual content (Step-File Architecture, Integration)
- Remove tutorial content (Examples section)
- Cut redundant Reference tables (steps already in how-to)
- Merge Self-Check and Adversarial Review into Validation Criteria
index.md:
- Fix broken link to Quick-Flow documentation
Both main files:
- Apply prose editorial fixes for clarity
- Reduce word count while preserving comprehension
Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.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 CSS to break workflow diagram iframe out of content container
- iframe now spans full viewport width instead of max-width constraint
- Adjust iframe height to 700px for better fit
- Remove border/border-radius for seamless full-width look
Co-authored-by: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
* docs: radical reduction of documentation scope for v6 beta
Archive and basement unreviewed content to ship a focused, minimal doc set.
Changes:
- Archive stale how-to workflow guides (will rewrite for v6)
- Archive outdated explanation and reference content
- Move unreviewed content to basement for later review
- Reorganize TEA docs into dedicated /tea/ section
- Add workflow-map visual reference page
- Simplify getting-started tutorial and sidebar navigation
- Add explanation pages: brainstorming, adversarial-review, party-mode,
quick-flow, advanced-elicitation
- Fix base URL handling for subdirectory deployments (GitHub Pages forks)
The goal is a minimal, accurate doc set for beta rather than
comprehensive but potentially misleading content.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* refactor: restructure BMM and agents documentation by consolidating and flattening index files.
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* 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>
* 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>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Murat K Ozcan <34237651+muratkeremozcan@users.noreply.github.com>
Updated 2 additional files to use the correct /dist/ path:
- docs/how-to/workflows/run-automate.md: Standalone mode example
- docs/reference/tea/configuration.md: Playwright BASE_URL example
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: optimize style guide for LLM readers
Restructure documentation style guide with dependency-first ordering
and LLM-optimized content based on editorial-review-structure analysis.
Key changes:
- Add Universal Formatting Rules section at top (consolidated anti-patterns)
- Move Visual Hierarchy and formatting rules before document types
- Add Document Types decision table for type selection
- Move Before/After example to follow Visual Hierarchy
- Merge Links/Images into single Assets table
- Move tutorial-specific checklist into Tutorial Structure section
- Move Validation Steps to end (submission workflow)
- Cut abstract Quick Principles (no execution value for LLMs)
- Remove emotional/orientation language throughout
- Condense FAQ Sections structure
Result: ~35% reduction (539 deletions, 383 insertions) with improved
parseability for AI agents writing documentation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: clarify explanation checklist admonition limit
Disambiguate 2-3 admonitions max to explicitly show it is a per-document
limit that still respects the universal per-section rule.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: clarify header budget vs structure template relationship
Add note explaining that structure templates show content flow, not 1:1
header mapping. Admonitions and inline elements are within sections.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: remove horizontal rules to follow own guidelines
Remove all --- section separators to comply with Universal Formatting
Rules. The ## headers provide sufficient visual separation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: address PR review findings for style guide
- Fix forward reference in Header Budget section
- Clarify descriptions rule scope (tables and 5+ item lists)
- Restore realistic FAQ examples
- Add qualifier to admonition content length guideline
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: further optimize style guide as delta-only document
- Add opener declaring adherence to Google Style Guide and Diataxis
- Remove generic Google style guide sections (Visual Hierarchy patterns,
Tables constraints, Code Blocks, Lists, Assets)
- Remove Diataxis explainer content (Document Types table, "X documents
do Y" explanatory sentences, Before/After example)
- Keep all project-specific structure templates and checklists
- Consolidate rules into single Project-Specific Rules table
Result: 367 lines (down from 597), pure delta document assuming
LLM training knowledge of baseline standards.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
miendinh
Brian
Alex Verkhovsky
JakubStejskalCZ
Emmanuel Atsé
Akhilesh Tyagi
梁山河
leon
lone
Nikolas Hor
cccczl
Brian Madison
Vladimir Hrusovsky
murat
Murat K Ozcan
Chad Woolley
sjennings
The Chef
forcetrainer
jheyworth