Agent identity (name, title) and the Overview prose are now baked into
each SKILL.md rather than resolved from customize.yaml. This anchors
skill-discovery (description keywords still match), protects brand
identity (Mary is Mary), and leaves the customize.yaml surface for
behavior changes only.
customize.yaml slimming:
- Dropped metadata.title (hardcoded in SKILL.md heading + Overview)
- Dropped metadata.capabilities (dead field; nothing downstream read it)
- Luminary-anchored identity strings (Porter+Minto, Evans+Tufte,
Cagan+Torres+Bezos, Norman+Cooper, Fowler+Vogels, Beck+Pragmatic
Programmer) — higher signal density, ~55% token savings per persona
- Preserved distinctive communication_style voice beats per agent
- Principles trimmed to 3-4 cite-worthy heuristics each
SKILL.md changes (all 6 agents):
- New top-of-body heading: `# Name — Title`
- New `## Overview` section with hardcoded capability prose
- Step 2 (Adopt Persona) rewritten to layer customized persona on top
of the Overview-established identity
- bmad-agent-dev gains an `## Operating Rules` section containing its
8 non-negotiable behavioral invariants (moved from customize.yaml
critical_actions, since they're brand-protected invariants, not
team-customizable startup steps)
customize.yaml now defines per-agent:
- icon (cosmetic)
- persona.{role, identity, communication_style, principles} (customizable)
- critical_actions (empty by default, extensibility hook for teams)
- memories (empty by default, extensibility hook for teams)
- menu (default items, mergeable by code)
manifest-generator.js: dropped `capabilities` column from
agent-manifest.csv header, write, and read paths (field was write-only
noise — no consumer ever read it back).
Docs: customize-bmad.md now notes agent names are fixed by design so
skills can be reliably invoked by role or default name.
BMB standard and Anthropic's Agent Skills spec both reference the
PEP 723 + uv pattern: declare dependencies in an inline script
header, invoke via `uv run` so deps auto-install into a cached
isolated environment on first run.
- resolve_customization.py: add PEP 723 header declaring pyyaml>=6.0
and requires-python>=3.10.
- Remove src/scripts/requirements.txt (superseded by inline metadata).
- Update 6 agent SKILL.md files to invoke `uv run` instead of `python3`.
- Update docs/how-to/customize-bmad.md to explain the uv requirement
and the PEP 723 pattern, with a plain-python3 fallback note.
- Refresh the script's ImportError message to point at uv run first.
Anthropic's Agent Skills ecosystem leans Python (official doc skills
use Python; the skills spec excludes node_modules from packaged
distributions). Using Python + PyYAML aligns with where the platform
is going, keeps the dependency declared via requirements.txt (scannable
by pip-audit/Dependabot), and eliminates the need to vendor or bundle
an npm package into the repo.
Changes:
- Rewrite src/scripts/resolve-customization.js as
src/scripts/resolve_customization.py with identical merge semantics.
- Drop vendored yaml@2.8.2 (~135 files, 800KB) from src/scripts/vendor/.
- Declare the dependency via src/scripts/requirements.txt (PyYAML>=6.0).
- Update all 6 agent SKILL.md files to invoke `python3` instead of `node`.
- Update docs/how-to/customize-bmad.md to reflect the Python runtime
and PyYAML install requirement.
- Remove src/scripts/vendor/** from eslint.config.mjs and .prettierignore.
- Refresh the _installSharedScripts comment (no more yaml bundling).
Shorter, cleaner path for user override files. Updates:
- resolver script path lookup + docstring
- all 6 agent SKILL.md fallback paths
- how-to doc examples
- .gitignore (also corrects stale .toml to .yaml)
- validator INSTALL_ONLY_PATHS entry
Extends ESLint CLI-script overrides to cover src/scripts/** and drops an
unused helper from the resolver to satisfy the pre-commit lint gate.
- Replace per-skill TOML defaults with customize.yaml using v6.1-compatible
schema (agent.metadata / agent.persona, snake_case fields)
- Port resolve-customization.py to resolve-customization.js (Node); one
shared copy at src/scripts/, invoked via --skill with three-layer merge
- Restore v6.1 fields: critical_actions, memories, menu; drop start_prompt
- Simplify menu items to {code, description, skill|prompt}; no action field
- Flatten SKILL.md to 8 atomic activation steps, boilerplate below frontmatter
- Tech-writer menu items reference skill-root prompt files via {skill-root}
- Dev agent Critical Actions moved from SKILL.md into customize.yaml
- Add {skill-name} path convention for portable fallback instructions
- Rewrite docs/how-to/customize-bmad.md for the new system
Add three-layer TOML customization system (defaults, team, user overrides)
for all six agent skills: analyst, tech-writer, PM, UX designer, architect,
and dev. Includes shared resolver script, updated activation flows, and
revised customization documentation.
* 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.
* 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>
* 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>
- 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
Brian Madison
Alex Verkhovsky
The Chef
Brian Madison