External official modules (bmb, cis, gds, tea, wds) are cloned to
~/.bmad/cache/external-modules/<name>/ and never copied into src/modules/,
so collectAgentsFromModuleYaml silently skipped them and their agents
never reached config.toml. Swap the hardcoded src/modules lookup for a
resolveInstalledModuleYaml() helper that also searches the external cache
(handling src/, skills/, nested, and root layouts) and warns instead of
silently skipping when a module.yaml can't be found.
* refactor: remove bmad-skill-manifest yaml; introduce four-layer central config.toml
- Agent essence moves from per-skill bmad-skill-manifest.yaml files
into each module.yaml's `agents:` block (code, name, title, icon,
description). Per-agent customize.toml remains the deep-behavior
source of truth.
- Installer emits four TOML files:
_bmad/config.toml team install answers + agent roster
_bmad/config.user.toml user install answers
_bmad/custom/config.toml team overrides stub
_bmad/custom/config.user.toml personal overrides stub
Prompts declare scope: user to route answers to config.user.toml.
- resolve_config.py merges four layers: base-team -> base-user ->
custom-team -> custom-user.
- Three consumer skills (party-mode, advanced-elicitation,
retrospective) switched from agent-manifest.csv to the resolver.
- installer.js mergeModuleHelpCatalogs now takes the in-memory
agent list from ManifestGenerator -- no CSV roundtrip.
- Deleted: 6 bmad-skill-manifest.yaml files, agent-manifest.csv
emission, collectAgents/getAgentsFromDirRecursive,
paths.agentManifest().
* fix(installer): strip core-key pollution from [modules.*]; soften config headers
- writeCentralConfig now always strips core-module keys from every
[modules.<code>] bucket, even when the module's schema is not
available in src/ (external / marketplace modules like cis, bmb).
Core values belong in [core] only; workflows read them directly.
- When the module's own schema IS available (built-in modules),
also drop any key it does not declare as a prompt — same
spread-pollution filter as before, now layered on top.
- Section-aware headers on both _bmad/config.toml and
_bmad/config.user.toml: [core] / [modules.*] values are
editable (installer reads them as defaults on next install);
[agents.*] is regenerated from module.yaml and will be wiped —
overrides for agents go in _bmad/custom/config*.toml instead.
* docs: cover central config.toml + Diataxis prose pass across three files
Document the new four-file central configuration surface (_bmad/config.toml,
config.user.toml, and custom/ overrides) alongside the existing per-skill
customize.toml. Make editing rules, scope partitioning, and when-to-use-which
guidance explicit.
- customize-bmad.md: new "Central Configuration" section with editing rules,
three worked examples (rebrand, fictional agent, module settings override),
and a "when to use which surface" table. Converted five h4 headers to
bold paragraph intros per style guide.
- expand-bmad-for-your-org.md: two-layer mental model extended to three;
new Recipe 5 with three variants (rebrand, custom crew, pinned team
settings); reinforcement table extended.
- named-agents.md: noted the dual customization surface — per-skill shapes
behavior, central config shapes roster identity.
Diataxis prose pass applied across all three files: banned vocabulary
check, em-dash cap, hypophora / metanoia / amplificatio / stakes-inflation
cleanup, rhythm and burstiness fixes. Structural conformance verified;
markdownlint and prettier clean.
* test+docs: add central config unit tests; fix stale recipe count
- test: two new suites (35 + 36) covering writeCentralConfig and
ensureCustomConfigStubs. Verifies scope partitioning (user_name
lands only in config.user.toml), core-key pollution stripping
from [modules.*], unknown-schema fallthrough (external modules
survive without schema), agent roster baked into config.toml
[agents.*] only, stub-preservation on re-install. 44 new
assertions.
- docs: fixed four stale "four recipes" references to say "five"
after Recipe 5 (Customize the Agent Roster) was added. Touches
frontmatter, opening paragraph, Combining Recipes paragraph,
and the named-agents cross-link blurb.
* fix: address PR review feedback on central config
- resolve_config.py argparse: three-layer → four-layer description
- SKILL/workflow/explanation docs: document all four layers including
_bmad/config.user.toml (was missing from merge-stack descriptions)
- customize-bmad.md + installer headers: drop the false "direct edits to
config.toml persist" claim; installer reads from per-module config.yaml,
not central TOML, so direct edits get clobbered. Route users to
_bmad/custom/config.toml for durable overrides
- writeCentralConfig: warn loudly when a module.yaml can't be parsed
(previously silent — user-scoped keys could mis-file into team config)
- writeCentralConfig: preserve [agents.*] blocks for modules that didn't
contribute fresh agents this run (e.g. quickUpdate skipping modules
whose source is unavailable) so the roster doesn't silently shrink
- add extractAgentBlocks helper + Test Suite 37 covering preservation
Addresses comments from augmentcode and coderabbitai on PR #2285.
* feat(skills): TOML-based agent customization with stdlib Python resolver
Re-applies PR #2282's three-layer customization model (skill defaults →
team → user) but swaps YAML for TOML and uv for stdlib tomllib. Users
no longer need uv, pip, or a virtualenv — plain python3 (3.11+) is
sufficient, since tomllib shipped in the standard library.
## Schema changes vs PR #2282
- Flat agent schema: fields live directly under [agent], no nested
metadata/persona sub-tables. Easier to author, less indentation.
- Non-configurable identity: name and title are declared in
customize.toml as source-of-truth metadata (for future skill-manifest
generation) but SKILL.md ignores overrides there — identity is
hardcoded to preserve brand recognition.
- role redefined: now describes what the skill does for the user
within its module phase, not a restatement of the title.
- persistent_facts replaces the activation-time file-context load AND
the old memories concept. Entries can be literal sentences or
file: prefixed paths/globs; avoids collision with the upcoming
runtime memory sidecar.
- activation_steps_prepend / activation_steps_append harmonized across
agents and workflows (replaces agent-specific critical_actions).
- [workflow] namespace mirrors [agent] for workflow customization.
Same four structural rules, same field vocabulary.
## Resolver (src/scripts/resolve_customization.py)
Four purely structural merge rules, zero field-name hardcoding:
- Scalars: override wins
- Tables: deep merge
- Arrays of tables where every item has `code` or `id`: merge by
that key (matching keys replace, new keys append)
- Any other array: append
No removal mechanism — overrides cannot delete base items. Fork the
skill or override by code with a no-op value to suppress defaults.
## Agents ported (6)
All six BMad agents now ship customize.toml + rewritten SKILL.md:
analyst (Mary), tech-writer (Paige), pm (John), ux-designer (Sally),
architect (Winston), dev (Amelia). Each uses the same 8-step
activation template: resolve → execute prepend → adopt persona →
load persistent facts → load config → greet (with {agent.icon}) →
execute append → dispatch or present menu.
Step 8 supports fast-path invocation: "hey Mary, let's brainstorm"
dispatches the matching menu item directly after greeting, skipping
the menu render when intent is clear. Chat, clarifying questions,
and bmad-help remain available when nothing on the menu fits.
## Installer + tooling
- _bmad/scripts/ provisioned on install (copies src/scripts/)
- _bmad/custom/ seeded with .gitignore for *.user.toml on fresh install
- Non-module-dir filter extended to skip _memory, memory, docs,
scripts, and custom when scanning for modules
- Dead _config/agents/ directory no longer created
- metadata.capabilities removed from agent-manifest.csv and schema
- eslint config extended to cover src/scripts/**
- validate-file-refs.js knows about custom/ as install-only
## Deferred for follow-up
- bmad-product-brief workflow port (the pilot that demonstrates
[workflow] + on_complete)
- Translated docs (cs/fr/vi-vn/zh-cn) — regenerate from English
* feat(skills): port bmad-product-brief to TOML workflow customization
Completes the customization surface rollout by giving the product-brief
workflow the same override model as the six BMad agents, under the
[workflow] namespace instead of [agent].
## customize.toml
Mirrors the agent shape under [workflow] with:
- activation_steps_prepend / activation_steps_append (harmonized across
agents and workflows — same field names, same append semantics)
- persistent_facts with the file: convention, seeded with
file:{project-root}/**/project-context.md
- on_complete scalar (renamed from PR #2282's skill_end for clarity —
reads cleaner as "what runs when the workflow completes")
## SKILL.md
7-step workflow activation:
1. Resolve workflow block
2. Execute prepend steps
3. Load persistent facts (file: or literal)
4. Load config
5. Greet if not already
6. Execute append steps
7. Stage 1 — Understand Intent
python3 + stdlib tomllib invocation; no uv required.
## Prompt file changes
- Path normalization: ../agents/ → agents/, ../resources/ → resources/,
bare foo.md → prompts/foo.md. All references now resolve from the
skill root (matches the convention documented in SKILL.md).
- Paths: meta-line added to each of the 4 prompt files that reference
other files, reinforcing "bare paths resolve from skill root" so the
LLM doesn't lose the convention when operating two hops into a
prompt chain.
- finalize.md terminal stage now calls the resolver for
workflow.on_complete — non-empty values run as the final step.
## Validation
- Resolver output verified: 4 workflow fields returned cleanly.
- validate-file-refs.js: 254 files scanned, 139 refs checked, 0 broken.
- test:refs: passing.
* docs(skills): enterprise customization recipes + workflow template variable
Three independent improvements bundled because they share the same
surface (workflow/agent customization) and landed from the same design
discussion:
## Fallback sentence disambiguated (7 SKILL.md files)
The "if the script fails" fallback used to say `{project-root}/_bmad/
custom/{skill-name}.toml` for the team override and then just `{skill-
name}.user.toml` for the user override, leaving the user file's
location implicit. LLMs could reasonably guess skill root or project
root instead. Replaced with an unambiguous numbered list that spells
out the full path for every file in the merge chain.
## Product-brief: stage promotion + brief_template variable
- Promoted `## Stage 1: Understand Intent` from a nested step inside
"On Activation" to a top-level section. The previous "Step 7: Stage
1 — Understand Intent → Proceed to Stage 1 below" was mechanical
numbering pretending to be a step. Activation now ends cleanly at
Step 6; Stage 1 is a peer section.
- Added `brief_template` as a workflow-level scalar customization
defaulting to `resources/brief-template.md`. Stage 4 reads
`{workflow.brief_template}` instead of the hardcoded path, so orgs
can point at their own template under `{project-root}/...` without
forking the skill.
## New doc: docs/how-to/extend-bmad-for-your-org.md
Four worked recipes that together cover most enterprise scenarios:
1. Shape an agent across every workflow it dispatches (dev agent +
Context7 MCP + Linear search — the highest-leverage pattern)
2. Enforce org conventions inside a specific workflow (product-brief
+ compliance-field persistent_facts)
3. Publish completed outputs to external systems (product-brief +
Confluence + Jira via MCP, gated on user confirmation for Jira)
4. Swap in your own output template (product-brief + brief_template
variable swap)
Opens with the two-layer mental model (agent spans workflows,
workflow is local) so readers pick the right granularity before
reading any recipe. Closes with a "Combining Recipes" section
showing all four composed. Cross-linked from customize-bmad.md.
## Validation
- Resolver: workflow.brief_template returns the default cleanly.
- validate-file-refs.js: 254 files scanned, 146 refs checked
(+7 from this commit), 0 broken.
* docs(skills): encourage CLAUDE.md/AGENTS.md reinforcement of critical rules
Added a "Reinforce Global Rules in Your IDE's Session File" section to
extend-bmad-for-your-org.md. BMad customizations only load when a
skill activates, but IDE session files (CLAUDE.md, AGENTS.md, cursor
rules, copilot-instructions) load every turn — worth restating the
most critical rules there too so they survive ad-hoc chat outside a
BMad skill.
Includes a one-line example reinforcing the Recipe 1 Context7 rule,
plus a scope table that clarifies what each layer is for:
- IDE session file: universal, every session, keep succinct
- Agent customization: persona-specific, every dispatched workflow
- Workflow customization: one workflow run
Emphasizes brevity — noise in the session file crowds out signal.
* docs(skills): add Named Agents explanation doc
New docs/explanation/named-agents.md walking through the three-legged
stool (skills + named agents + customization) with the "Hey Mary,
let's brainstorm" activation flow as the narrative thread.
Covers:
- Why named agents vs menu-driven or prompt-driven alternatives
- The 8-step activation flow and what each step contributes
- How customization scales the model beyond a single developer
- Cross-links to the how-to docs for implementation details
Sits alongside brainstorming.md, quick-dev.md, party-mode.md in the
explanation folder — feature narratives for users who want to
understand why BMad is designed the way it is, not just how to use it.
* docs(skills): clarify that keyed-merge requires a single identifier key per array
Review feedback (PR #2284) flagged that the merge-rules wording was
ambiguous: "every item has a `code` or `id` field" could reasonably
be read as "each item individually has at least one of the two",
allowing arrays to mix `code` and `id` across items.
The resolver has always required all items share the *same* identifier
key (all `code`, or all `id`). Mixed arrays fall through to append —
intentional, because mixing identifier keys within one array is a
schema smell and any guess about which key should merge creates a
worse trap than the append-fallback.
Clarified in three places:
- Merge-rules table in customize-bmad.md: "every item shares the
**same** identifier field"
- `code`/`id` convention paragraph: "pick **one** convention ... and
stick with it across the whole array"
- Resolver docstring and `_detect_keyed_merge_field` docstring:
explicit note that mixed arrays fall through with rationale
No behavior change.
* docs(skills): address CodeRabbit review — fallback rules, OS claim, headless greeting
Three fixes from PR #2284 review feedback:
## 1. Fallback merge wording (7 SKILL.md files)
Every SKILL.md told the LLM to merge the three customization files
"in priority order (later wins)" when the resolver fails. That reads
as shallow last-write-wins — but the resolver does structural merge
(scalars override, tables deep-merge, code/id-keyed arrays merge by
key, other arrays append). Following the old wording manually would
have silently stripped base `principles`, `persistent_facts`, and
`menu` items whenever a team override was present.
Expanded the fallback sentence to restate the four structural rules
explicitly, matching the resolver's behavior.
Applied to all 6 agents + bmad-product-brief workflow.
## 2. Python 3.11 / OS shipping claim (customize-bmad.md)
The docs claimed "macOS 13+, Ubuntu 22.04+, Debian 12+, Fedora 37+
all ship 3.11 or newer." Inaccurate — Ubuntu 22.04 defaults `python3`
to 3.10.6 (3.11 is a separate package), and macOS doesn't really
ship Python by default anymore.
Replaced with honest guidance: check `python3 --version` and note
that macOS without Homebrew and Ubuntu 22.04 default to 3.10 or
earlier.
## 3. Autonomous mode greeting gate (bmad-product-brief)
Product-brief's activation-mode detection documents autonomous mode
as "produce complete brief without interaction" — but Step 5 greeted
unconditionally, adding conversational output before the headless
artifact. Gated the greeting on `{mode}` != `autonomous`.
## Dismissed (replied on thread)
- `.gitignore` migration from *.user.yaml to *.user.toml: YAML
installer code was in reverted #2282, never released. No users
affected. Same rationale as Augment's earlier thread.
Validated: 254 files, 146 refs, 0 broken. test:refs 7/7,
test:install 242/242.
* docs: rename Extend to Expand throughout customization docs
Three-layer customization (skill defaults → team → user) for BMad agents
and any skill that opts in. Users edit `_bmad/custom/{skill-name}.yaml`
(team, committed) or `{skill-name}.user.yaml` (personal, gitignored);
customizations survive updates.
Resolver is a Python script using PEP 723 inline metadata, invoked via
`uv run` so deps auto-install into a cached isolated env on first call.
This aligns with Anthropic's Agent Skills spec and BMB conventions, and
keeps the dependency declared (scannable by pip-audit/Dependabot) rather
than vendored.
## Design choices
- **Agent identity is hardcoded** in SKILL.md (name, title, Overview prose)
so skills can be invoked reliably by role *or* default name. Brand
recognition is preserved; customization shapes behavior, not identity.
- **Luminary-anchored personas** (e.g. "Channels Martin Fowler's
pragmatism and Werner Vogels's cloud-scale realism") deliver ~55%
token savings per agent while preserving distinctive voice beats.
- **Universal per-field merge rules** with v6.1-compatible agent
semantics: metadata shallow-merge, persona replace, critical_actions
and memories append, menu merge-by-code, all else deep-merge.
- **Workflow customization** shares the same surface — `bmad-product-brief`
pilots `activation_steps_prepend`, `activation_steps_append`, and
`skill_end` hooks that any workflow-style skill can adopt.
## Infrastructure
- `_bmad/scripts/` houses shared Python scripts (resolver + future).
- `_bmad/custom/` is provisioned empty with a seeded `.gitignore` for
`*.user.yaml` on fresh installs.
- Installer filters ensure `scripts/`, `custom/`, and sidecar-generated
`memory/` directories are never treated as modules.
- Dead v6.1 code cleaned up: `_config/agents/` no longer created,
`metadata.capabilities` removed from schema and CSV manifest.
* feat(installer): use GitHub API as primary fetch with raw CDN fallback
Corporate proxies commonly block raw.githubusercontent.com while allowing
api.github.com. Add fetchGitHubFile() to RegistryClient that tries the
GitHub Contents API first, falling back to the raw CDN transparently.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(installer): cap redirect depth and preserve dual-fallback errors
Add maxRedirects parameter to fetch() and _fetchWithHeaders() to prevent
unbounded redirect recursion. Wrap CDN fallback in try/catch and throw
AggregateError with both API and CDN errors for better diagnostics.
Extract marketplace repo coordinates into named constants in
external-manager.
* chore(installer): drop unused fetchJson and fetchGitHubJson
Neither method has any callers. Also drop the corresponding test.
* refactor(test): fold registry tests into test-installation-components
No reason for RegistryClient tests to be a separate runner — the same
file already tests the registry consumers in Suite 33. Drop test:registry
from package.json scripts and quality gate.
* fix(installer): include URL, API message, and rate-limit info in HTTP errors
Non-2xx responses previously yielded bare `HTTP 403`. Now surface the
request URL, GitHub's JSON error message (or body snippet), X-RateLimit-Reset
when quota is exhausted, and Retry-After. Turns a mystery 403 into
'rate limit exhausted; resets at 2026-04-15T18:00:00Z' — the difference
between 'try GITHUB_TOKEN' and a wild goose chase.
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Skills don't nest. Once the manifest generator finds a valid SKILL.md
in a directory, it should not recurse into that skill's subdirectories
looking for more skills. Template files (like bmb's setup-skill-template)
inside a skill's assets/ would be incorrectly scanned and produce
spurious errors.
Add missing move() with cross-device fallback (rename → copy+rm on
EXDEV), needed by OfficialModules.createModuleDirectories for directory
migrations during upgrades.
Honor overwrite/errorOnExist options in copy() to match fs-extra
behavior for callers that pass these flags.
fs-extra routes all operations through graceful-fs, which globally
monkey-patches node:fs with a deferred retry queue. During multi-module
installs (~500+ file ops), retried unlink operations from one module's
remove phase can fire after the next module's copy phase has written
files, silently deleting them non-deterministically.
Replace fs-extra with a thin fs-native.js wrapper over node:fs/promises
and node:fs. All 21 consumers now use native APIs with no global
monkey-patching, eliminating the retry-queue race condition entirely.
Closes#1779
Core and BMM modules live in this repo (src/core-skills, src/bmm-skills)
but the installer UI sourced them from the remote registry. When the
registry was unreachable (VPN, proxy, firewall), the fallback YAML only
had the 4 external modules, so core and bmm disappeared from the install
list entirely.
Now _selectOfficialModules and getDefaultModules always read built-in
modules from the local source via OfficialModules.listAvailable(), then
append external modules from the registry. Network failures only affect
external modules.
Closes#2239
* chore(installer): remove dead code across installer modules
Delete 3 entirely dead files (agent-command-generator, bmad-artifacts,
module-injections) and remove ~50 unused exports from manifest.js,
cli-utils.js, prompts.js, path-utils.js, official-modules.js,
external-manager.js, custom-module-manager.js, and registry-client.js.
Removes corresponding dead tests.
* fix(installer): restore currentProjectDir writes for placeholder expansion
The previous commit removed the three assignments to
OfficialModules.currentProjectDir as dead code, but buildQuestion()
still reads the property to resolve {directory_name} placeholders in
module config defaults during interactive collection. Without the
writes, any module default containing {directory_name} would surface
the literal placeholder to users.
The legacy agent-command-generator, bmad-artifacts helpers, and all 26
IDE template files (combined/ and split/) are unreachable dead code.
The installer now uses verbatim SKILL.md directory copying -- no template
rendering occurs. The files own TODO comments confirm retirement.
* 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.
* feat(bmad-help): add _meta rows and llms.txt support for general questions
Register llms.txt URLs in module-help.csv via _meta rows so bmad-help
can fetch module documentation when users ask questions that don't map
to a specific skill.
* refactor(bmad-help): streamline llms.txt docs into existing skill sections
* feat(installer): add community module browser and custom URL support
Three-tier module selection: official, community (category drill-down
with featured/search), and custom GitHub URL.
- Add RegistryClient shared fetch utility
- Add CommunityModuleManager with SHA-pinned cloning (refuses install
if approved SHA cannot be reached; uses HEAD when no SHA set)
- Add CustomModuleManager for arbitrary GitHub repo installation
- Extend findModuleSource chain with community and custom fallthrough
- Extend manifest to detect community and custom source types
- Add Config.customModulesMeta for custom module metadata
* fix: resolve review findings for community/custom module support
- Remove redundant CommunityModuleManager instantiation in UI display
- Remove dead customModulesMeta field from Config (never populated)
- Add 35 unit tests for CustomModuleManager and CommunityModuleManager
pure functions: URL validation, normalization, search, featured, categories
* fix: preserve installed community/custom modules in modify flow
When a user does "Modify Installation" and declines to browse community
modules, previously installed community/custom modules are now auto-kept.
If the user does browse, their selections are trusted (they can deselect).
Also fix stale docs: class doc for SHA pinning, JSDoc return type.
* fix: include community and custom modules in quick update
Quick update now checks community registry and custom cache so installed
community/custom modules are updated instead of skipped.
* fix: use defaults for new config fields during quick update
When quick update encounters new config fields (e.g., from a newly
supported community module), use schema defaults silently instead of
prompting the user. Quick update should be non-interactive.
* test: add unit tests for SHA pinning, category filtering, and URL edge cases
Cover SHA normalization (set vs null/trusted), listByCategory,
getModuleByCode, and URL validation edge cases (HTTP, trailing slash,
SSH without .git). Total: 243 tests.
* 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().
* feat(installer): fetch module list from marketplace registry
Switch module list source of truth from bundled
external-official-modules.yaml to the remote marketplace registry
(registry/official.yaml) fetched via raw.githubusercontent.com.
- Rewrite ExternalModuleManager to fetch from GitHub with local fallback
- Simplify selectAllModules/getDefaultModules to use registry as single source
- Registry order controls display order; built_in flag prevents cloning
- Rename fallback file to registry-fallback.yaml in modules/
- Only show legacy migration message when legacy dirs actually exist
* 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().
* chore(install): stop copying skill prompts to _bmad by default
Flip install_to_bmad default from true to false so skill directories
are cleaned from _bmad/ after IDE install. Skills are self-contained
in their IDE directories (.claude/skills/, etc.) and no longer need
duplicate copies in _bmad/.
Two skills (bmad-create-prd, bmad-validate-prd) opt back in via
explicit manifests because bmad-edit-prd cross-references their data
files. Also fixes broken bmm-skills/ path references and corrects
the file-ref validator module-to-source mapping.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(install): make edit-prd self-contained and remove install_to_bmad
Give bmad-edit-prd its own copy of prd-purpose.md and replace the
cross-skill validation workflow reference with a skill invocation, so
all three PRD skills are fully self-contained. With no remaining
consumers, remove the install_to_bmad flag from manifests, CSV output,
the post-install cleanup loop, and the dedicated test file.
* feat(install): clean up skill directories from _bmad after IDE install
Skills are self-contained in IDE directories, so _bmad/ only needs
module-level files (config.yaml, _config/). After all IDE setups
complete, remove skill directories from _bmad/ via skill-manifest.csv.
Also cleans up skill dirs left by older installer versions.
* test(install): drop stale install_to_bmad column from suite 27 CSV row
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(installer): overhaul branding, versioning, and skill cleanup
Logo and branding:
- Responsive logo: full "BMAD METHOD" at >=95 cols, "BMAD" for narrower terminals
- Color scheme updated from yellow to blue (matching bmadcode.com brand)
- Added copyright notice and tagline in white for contrast
- Removed version number from logo (individual module versions shown in summary)
- Added ™ to both wide and narrow logo variants
Installer start message:
- Replaced outdated V6 launch announcement with clean welcome
- Consolidated redundant module/platform messaging into single intro
- Tightened open source manifesto (same spirit, fewer words)
- Merged speaking/media into support section with contact email
- Added full social links: Website, Discord, YouTube, X, Facebook
- Replaced docs.bmad-method.org and changelog links with bmadcode.com hub
Install summary improvements:
- Module names now show full display names from module.yaml (not abbreviations)
- All module versions sourced from .claude-plugin/marketplace.json exclusively
- Summary shows version transitions: "v6.2.2 -> v6.3.0", "v6.3.0, no change",
or "v6.3.0, installed" for fresh installs
- Switched summary from clack note() to box() for full-brightness text
- Removed dim/gray styling that was hard to read on dark terminals
- Links styled with color.blue instead of color.dim
- Get started section leads with actionable steps (launch agent, run bmad-help)
- Removed redundant social links (already shown in start message)
Version source unification:
- All module versions now come from .claude-plugin/marketplace.json only
- Removed package.json as version source for core/bmm modules
- Updated manifest.js getModuleVersionInfo() to use marketplace.json
- Updated installer.js _getMarketplaceVersion() helper
- Updated ui.js getMarketplaceVersion() for module selection display
- Quick Update menu no longer shows misleading version (was using package.json)
- Module selection list now shows versions next to each module name
Skill cleanup overhaul:
- Replaced blunt-force bmad-* prefix deletion with surgical removal system
- Added removals.txt support: optional per-project file listing skills to remove
- Created initial removals.txt with all skills removed since v6.2.0
- Install/update: captures previously installed skill IDs from skill-manifest.csv
before manifest regeneration, then removes those + removals.txt entries
- Uninstall: removes all installed skills via skill-manifest.csv + removals.txt
- Deselecting modules now correctly removes their skills from IDE directories
- User-created bmad-* skills in IDE directories are no longer destroyed
- Legacy directory cleanup retains prefix matching (those dirs are abandoned)
Bug fixes:
- Fixed duplicate "CORE module already up to date" during quick update
- Fixed version display showing package.json version instead of actual module version
- Updated test fixture for bmad-os-* preservation test to use skill-manifest.csv
* fix(installer): address Augment review findings
- Fix plugins[0] fragility: extract highest version across all plugins
in marketplace.json instead of assuming first entry (ui.js, installer.js,
manifest.js)
- Fix _readMarketplaceVersion ignoring moduleSourcePath: custom modules
can now source their own marketplace.json by walking up from source path
- Hard-exclude bmad-os-* utility skills in both surgical and legacy cleanup
modes, preventing accidental deletion if tracked in manifests
- Distinguish missing file vs parse error in skill-manifest.csv reading:
warn on corrupt CSV instead of silently skipping cleanup
* fix(installer): resolve module source before reading marketplace version
Move _readMarketplaceVersion call after source type resolution so custom
modules use their own source path instead of falling back to the external
module cache, which could match a different module with the same code.
* fix: preserve local custom module sources during quick update
Keep customModules in the generated main manifest so local custom
module source paths survive update runs. Load those preserved source
paths during stock quick update before falling back to the custom
cache directory.
This fixes the case where BMAD would drop customModules, lose the
original source path for a local module, and then skip the module or
try to re-cache from _bmad/_config/custom/<module>, which could fail
with ENOENT after the cache directory was removed.
Also adds an installation component regression test to verify
customModules and sourcePath are preserved in manifest generation.
Fixes#1582
* fix: ensure consistent formatting
* refactor: extract quick update custom source assembly
Move quick-update custom module source collection out of Installer and into
CustomModules as assembleQuickUpdateSources(). This keeps discoverPaths() focused on consuming prepared install inputs while
making the quick-update source assembly step explicit and easier to evolve.
Also:
- preserve customModules metadata in manifest regeneration for installed modules
- drop stale customModules entries when modules are no longer installed
- cover manifest preservation and manifest-backed quick-update sources in tests
Kilo Code now supports Agent Skills. Remove the suspended flag,
restore it in the IDE picker, and replace the suspended test suite
with a full native-skills installation test.
- Remove suspended message from platform-codes.yaml
- Rewrite test suite 22: config, IDE picker, install, skill output,
legacy cleanup, and reinstall assertions
- Update migration checklist to reflect active status
Co-authored-by: Junie <junie@jetbrains.com>
Co-authored-by: Brian <bmadcode@gmail.com>
The ancestor directory walk was based on the false premise that IDEs
like Claude Code inherit skills from parent directories — they do not.
The check blocked legitimate installations when unrelated BMAD skills
existed anywhere up the directory tree.
* 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.
* feat: add Junie platform support with .agents/skills target
Co-authored-by: Junie <junie@jetbrains.com>
* fix: disable ancestor_conflict_check for Junie platform
Junie does not traverse ancestor directories looking for skills,
so ancestor_conflict_check should be false.
Co-authored-by: Junie <junie@jetbrains.com>
---------
Co-authored-by: Junie <junie@jetbrains.com>
The installer now finds module.yaml in both skills/ and src/ directories,
including one level deep in subfolders. Updates bmb module-definition to
skills/module.yaml to match its actual structure.
bmad-builder reverted its skills/ directory back to src/ for installer
compatibility (bmad-code-org/bmad-builder#40). Update the external
modules manifest to match.
* 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.
Two bugs combined to produce an empty agent-manifest.csv:
1. collectAgents() only scanned {module}/agents/ directories, but agents
live at various paths (bmm/1-analysis/bmad-agent-analyst/,
cis/skills/bmad-cis-agent-*, etc.). Now walks the full module tree.
2. All 9 BMM agent manifests declared type: skill instead of type: agent.
The manifest generator requires type: agent to include a directory in
agent-manifest.csv. CIS, GDS, TEA, and WDS already had the correct type.
Changes:
- Fix 9 BMM bmad-skill-manifest.yaml files: type: skill → type: agent
- Replace collectAgents/getAgentsFromDir with full-tree recursive scan
- Module field from manifest file always takes precedence over directory
- Remove dead skillManifest load (legacy .md agent support removed)
- Add TODO in bmad-artifacts.js documenting legacy agent pipeline as dead code
- Add 10 regression tests covering BMM, CIS, and GDS directory layouts
Replace execSync with execFileSync in npx wrapper so that
argument values containing spaces (e.g. --user-name "CI Bot")
are passed as discrete array elements instead of being split
by the shell.
Fixes#2066
Signed-off-by: majiayu000 <1835304752@qq.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.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): discover skills by SKILL.md instead of manifest YAML
Switch skill discovery gate from requiring bmad-skill-manifest.yaml with
type: skill to detecting any directory with a valid SKILL.md (frontmatter
name + description, name matches directory name). Delete 34 stub manifests
that carried no data beyond type: skill. Agent manifests (9) are retained
for persona metadata consumed by agent-manifest.csv.
* refactor(installer): remove dead task/tool/workflow manifest code
The remove-skill-manifest-yaml branch deleted the scanners that
discover tasks, tools, and workflows but left behind the code that
writes their manifest CSVs. Remove collectTasks/Tools/Workflows,
writeTaskManifest/ToolManifest/WorkflowManifest, their helpers, and
the now-unreachable getPreservedCsvRows/upgradeRowToSchema methods.
Update installer pre-registration and test assertions accordingly.
Switch skill discovery gate from requiring bmad-skill-manifest.yaml with
type: skill to detecting any directory with a valid SKILL.md (frontmatter
name + description, name matches directory name). Delete 34 stub manifests
that carried no data beyond type: skill. Agent manifests (9) are retained
for persona metadata consumed by agent-manifest.csv.
* 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>
* refactor(installer): remove legacy workflow, task, and agent IDE generators
All platforms now use skill_format exclusively. The old
WorkflowCommandGenerator, TaskToolCommandGenerator, and
AgentCommandGenerator code paths in _config-driven.js were
no-ops — collectSkills claims every directory before the
legacy collectors run, making their manifests empty.
Removed:
- workflow-command-generator.js (deleted)
- task-tool-command-generator.js (deleted)
- writeAgentArtifacts, writeWorkflowArtifacts, writeTaskToolArtifacts
- AgentCommandGenerator import from _config-driven.js
- Legacy artifact_types/agents/workflows/tasks result fields
Simplified installToTarget, installToMultipleTargets, printSummary,
and IDE manager detail builder to skills-only.
Updated test fixture to use SKILL.md format instead of old agent format.
* fix(installer): address PR review findings from #2078
- Fix temp dir leak in test fixture cleanup (use path.dirname)
- Fail loudly when skill_format missing instead of silent success
- Add workflow.md to test fixture for verbatim-copy coverage
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
The v6.2.0 release renamed src/core to src/core-skills and src/bmm to
src/bmm-skills, but the installer CLI code still referenced the old
directory names, causing ENOENT crashes during installation.
Updated all path references across 7 files in tools/cli/ including
path.join() calls, string comparisons, regex patterns, and comments.
Fixes#2052
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
- Guard against YAML comment lines in parseFrontmatterMultiline
- Broaden PATH-02 to detect any installed_path mention, not just variable refs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- SKILL-04: require bmad- prefix, enforce single dashes via regex
^bmad-[a-z0-9]+(-[a-z0-9]+)*$, drop FORBIDDEN_NAME_SUBSTRINGS
- WF-01/WF-02: check all .md files (not just workflow.md) for stray
name/description frontmatter, with tech-writer exception
- Update skill-validator.md prompt to match all rule changes
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Require \n---\n (not just \n---) for closing frontmatter delimiter
in both parseFrontmatter and parseFrontmatterMultiline, with fallback
for files ending in \n---
- Add SKILL-07: SKILL.md must have non-empty body content after
frontmatter (L2 instructions are required)
- Update rule count to 14
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace SKILL_LOCATIONS array and AGENT_LOCATION constant with a single
walk from SRC_DIR. Any directory under src/ containing SKILL.md is a
skill — no need to enumerate locations.
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.
Add tools/validate-skills.js — a Node CLI that checks 13 deterministic
rules (SKILL-01–06, WF-01–02, PATH-02, STEP-01/06/07, SEQ-02) across
all skill directories. Runs in under a second, exits non-zero on HIGH+
findings in strict mode, and outputs JSON for the inference validator.
- Add validate:skills npm script to quality chain
- Update skill-validator.md with first-pass integration instructions
- Update AGENTS.md push gate documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The *.agent.yaml format was replaced by SKILL.md-based agents.
Zero agent YAML files remain in src/, so remove the Zod schema,
validator CLI, fixture-based test suite (52 fixtures), unit tests,
CLI integration tests, and the CI steps that invoked them.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(agents): convert all BMM agents to conformant skill structure
Replace legacy XML-based .agent.yaml files with new SKILL.md + bmad-manifest.json
format for all 9 BMM agents (analyst, architect, dev, pm, qa, sm,
quick-flow-solo-dev, ux-designer, tech-writer). Each agent now has:
- SKILL.md with persona, activation flow (bmad-init, project context, dynamic menu)
- bmad-manifest.json with capabilities referencing external skills
- bmad-skill-manifest.yaml for party-mode agent-manifest.csv generation
Tech-writer includes internal prompt files for write-document, mermaid-gen,
validate-doc, and explain-concept capabilities.
Also includes core bmad-init skill and removes legacy agent compilation tests
that referenced the old .agent.yaml format.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(installer): support new SKILL.md agent format in manifest generation
Update getAgentsFromDir to detect directories with bmad-skill-manifest.yaml
where type=agent and extract metadata directly from the YAML fields. This
allows the agent-manifest.csv to be populated from both old-format compiled
.md agents (XML parsing) and new-format SKILL.md agents (YAML manifest).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(installer): install type:agent skills to IDE native skills directory
The collectSkills scanner only recognized type:skill manifests, causing
new-format agents (type:agent in bmad-skill-manifest.yaml) to be added
to agent-manifest.csv but not installed to .claude/skills/. Now both
type:skill and type:agent are recognized as installable skills, while
collectAgents still processes type:agent dirs for the agent manifest
even when claimed by the skill scanner.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(installer): suppress canonicalId warning for type:agent skills
Agent-type skill manifests legitimately use canonicalId for agent-manifest
mapping (e.g., bmad-analyst). Only warn for regular type:skill manifests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(skills): update analyst manifest and simplify bmad-init instructions
Switch analyst's create-brief menu entry to the new product-brief-preview
skill. Simplify bmad-init SKILL.md by removing hardcoded code fences and
making the script path relative to the skill directory.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(bmm): update tech-writer CSV refs to new skill path
The module-help.csv still referenced the old agent YAML path for
tech-writer entries. Update to skill:bmad-agent-tech-writer to match
the conformant skill structure.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace duplicated workflow-era rules in .augment/code_review_guidelines.yaml
with a single reference to tools/skill-validator.md. Append the skill spec
cheatsheet to the validator with a link to the Agent Skills specification.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace `[workflow.md](workflow.md)` with bare `workflow.md` in all 34
SKILL.md files. Redundant markdown link syntax adds noise for LLM
consumers. Also update the validator example to match.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Run skill-validator against all 36 skills on HEAD (42b1d0f6). Fixes:
- PATH-01: relative path corrections in product-brief-preview, brainstorming,
distillator, generate-project-context, edit-prd, quick-dev-new-preview
- PATH-04: remove 5 intra-skill path variables from edit-prd
- REF-01: single-curly template vars → double-curly in create-architecture,
create-epics-and-stories, create-story
- REF-02: fix dangling file refs in advanced-elicitation, validate-prd, edit-prd
- REF-03: update rule to prefer natural language `Invoke the skill` form;
fix stale persona ref in qa-generate-e2e-tests
- SEQ-01: "skip to" → "proceed to" in quick-dev-new-preview
- SEQ-02: remove time estimates from document-project, quick-spec
- SKILL-06: add "Use when" trigger to review-edge-case-hunter
- STEP numbering: renumber step n="0.5" to integer sequence in retrospective
Also updates REF-03 rule in tools/skill-validator.md to clarify that
natural language invocation is canonical — no skill: prefix required.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Skills must be invoked with "invoke" language, not file-oriented verbs
like "read fully and follow", "execute", "run", or "load". These imply
document-level operations and are incorrect for skill references.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add PATH-05: no file path references into another skill directory.
Skills are encapsulated — external consumers must use skill:name syntax,
not reach into internal files. Also tighten WF-03 to cross-reference
PATH-05 so vague "legitimate external path" no longer permits
cross-skill file paths.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* 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>
SKILL-05 checks that SKILL.md name matches the directory name.
REF-01 checks that every {variable} traces to frontmatter, config,
or runtime — exempts {{double-curly}} template placeholders.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add Ona (ona.com) to the BMAD installer so users can select it during
`npx bmad-method install` or via `--tools ona`. Skills are installed to
`.ona/skills/<name>/SKILL.md` using the default templates.
Fixes#1967
Co-authored-by: Ona <no-reply@ona.com>
Subtract agents from total skill directories so the summary shows
non-agent skills and agents as distinct counts (e.g. 34 skills, 10
agents) instead of double-counting agents in the skill total.
* fix(installer): simplify install summary
* style: fix prettier formatting in test file
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(installer): clean up temp dir leak and conditional IDE footer
- Return fixture root from createSkillCollisionFixture so cleanup
removes the parent temp directory, not just the _bmad child
- Only show bmad-help next-step line when IDEs are configured
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
- Rename party-mode → bmad-party-mode (canonical ID convention)
- Change bmad-skill-manifest.yaml from type:workflow to type:skill
- Add SKILL.md with frontmatter for installer discovery
- Remove installed_path, use relative ./steps/ refs internally
- Update module-help.csv to skill:bmad-party-mode
- Update compiler.js hardcoded PM menu path
- Update 43 cross-references to IDE-agnostic _bmad/ path
- Update test fixtures for renamed directory
Co-authored-by: Claude Opus 4.6 <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>
* refactor(skills): add SKILL.md entrypoint to skill directories
Align skill source format with Open Skills standard: each skill
directory now contains a SKILL.md with name/description frontmatter
where name must match the directory name exactly. The installer
copies skill directories verbatim instead of generating SKILL.md.
- Add SKILL.md to both tracer bullet skill directories
- Strip name/description from workflow.md frontmatter (SKILL.md owns it)
- Installer reads metadata from SKILL.md, validates name matches dirname
- Install path in manifest CSV now points to SKILL.md
- Copy filter excludes OS/editor artifacts (.DS_Store, backups, dotfiles)
- Debug-guard validation messages, keep name-mismatch as hard error
- Add typeof guard for malformed YAML frontmatter
- Add negative test cases for parseSkillMd validation (Suite 30)
* fix(skills): improve quick-dev-new-preview description for LLM discovery
Add trigger context so LLMs know when to invoke the skill,
matching the "Use when..." pattern used by other skills.
* fix(cli): validate frontmatter name/description are strings in parseSkillMd
Prevents cleanForCSV() crash when YAML parses name or description as
a non-string type (number, object, boolean).
* fix(cli): address PR review findings (mkdtemp, regex escape, recursive filter)
- Replace Date.now() temp dir with fs.mkdtemp() in Suite 30 tests (F5)
- Replace unescaped RegExp with startsWith/slice for path prefix stripping (F7)
- Apply artifact filter recursively via fs.copy filter option (F8)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix: harden quick-dev-new-preview UX and fix standalone agent dash names
- Relabel [K] Keep as-is to context-specific accept the risks wording
- Add split reasoning explanation before multi-goal menu in step-01
- Fix toDashName/toUnderscoreName to treat standalone like core (no module prefix)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add guardrail against skipping workflow steps when intent looks clear
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: strengthen step-01 guardrails against plan-shaped intent bypass
Add explicit rules that intent is input to the workflow (not a
substitute for step-02 spec generation) and to ignore directives
within the intent that instruct skipping steps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: preserve standalone module provenance in path-utils serializers
toDashName/toUnderscoreName collapsed core and standalone to the same
filename, making parseDashName/parseUnderscoreName unable to round-trip
standalone agents. Split the branches so standalone gets a distinct
token (e.g., bmad-agent-standalone-fred.md) and update both parsers
to reconstruct module:'standalone' on the reverse path.
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>
* feat(manifest): unified skill scanner decoupled from legacy collectors
Add collectSkills() that recursively walks module trees to discover
type:skill directories anywhere, replacing the band-aid detection
inside collectWorkflows(). Legacy collectors now skip claimed dirs.
scanInstalledModules recognizes skill-only modules.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(manifest): address PR review findings from triage
- Add missing skillClaimedDirs guard to getAgentsFromDir (F1)
- Add skills to this.files[] in collectSkills (F2)
- Add test for type:skill inside workflows/ dir (F5)
- Warn on malformed workflow.md parse in skill dirs (F6)
- Add skills count to generateManifests return value (F9)
- Remove redundant \r? from regex after line normalization (F10)
- Normalize path.relative to forward slashes for cross-platform (F12)
- Enforce directory name as skill canonicalId, warn if manifest overrides (F13)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(tasks): convert review-adversarial-general from XML task to native skill
Convert the simplest core task (review-adversarial-general.xml) from
type:task XML format to type:skill markdown format. This establishes
the pattern for converting remaining XML tasks to self-contained skills.
- Convert XML task to workflow.md with frontmatter, role, execution steps
- Add type:skill manifest for verbatim directory copying
- Extend manifest-generator getTasksFromDir to recurse into subdirectories
and detect type:skill entries (mirrors existing workflow skill detection)
- Update cross-references in quick-dev-new-preview, quick-dev, quick-spec
- Update module-help.csv to use skill: prefix
* refactor: replace file path references with skill name invocations
Consumers of review-adversarial-general now invoke by skill name
instead of loading via _bmad/ file path. Removes the indirection
variable from frontmatter and inlines the skill name directly.
* refactor(installer): scan tasks/ for type:skill entries
Teach collectWorkflows to also scan the tasks/ subdirectory for
type:skill entries. Skills can live anywhere in the source tree —
the workflow scanner just needs to look in more places.
* fix: update stale task terminology to skill after format conversion
Address review findings from PR #1857: replace remaining "task"
references with "skill" in workflow steps and test documentation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): add type:skill manifest for verbatim skill directory copying
Introduce `type: skill` in bmad-skill-manifest.yaml to signal the
installer to copy entire skill directories verbatim into IDE skill
directories, replacing the launcher-based approach.
Changes:
- skill-manifest.js: fix single-entry detection for type-only manifests,
add getArtifactType export
- manifest-generator.js: collect type:skill entries separately, write
skill-manifest.csv, derive canonicalId from directory name
- _config-driven.js: add installVerbatimSkills with YAML-safe SKILL.md
generation, stale file cleanup, and warning on parse failures
- Rename quick-dev-new-preview to bmad-quick-dev-new-preview so
directory name is the canonical ID
- Update workflow.md installed_path to reference IDE skill base directory
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: replace {installed_path} with relative paths in quick-dev skill
Skills resolve paths relative to the skill root directory per the
open agent standard, so the installed_path variable is unnecessary.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): add install_to_bmad flag and skill: help catalog reference
Add install_to_bmad flag to skill manifests (default true) enabling
skills to opt out of _bmad/ copy while retaining .claude/skills/
installation. Support skill:<canonicalId> references in module-help.csv
workflow-file column. Fix stale quick-dev-new-preview directory
references in agent YAML and help catalog.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test: add install_to_bmad design contract tests
Unit tests against getInstallToBmad and loadSkillManifest that nail
down the 4 core design decisions for the install_to_bmad flag.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: reset skills array between runs and allow skill-only targets
- Reset this.skills and this.files in ManifestGenerator to prevent stale
data when instance is reused across multiple manifest runs
- Allow targets with empty artifact_types to still install verbatim
skills by checking skill_format before short-circuiting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: resolve broken file references in quick-dev-new-preview workflow
- Fix step-02-plan.md templateFile path (./tech-spec-template.md → ../tech-spec-template.md)
- Teach validate-file-refs.js to skip skill: prefixed references in CSV
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add pi coding agent as supported platform
Add pi (provider-agnostic terminal-native AI coding agent) to
platform-codes.yaml with native skills format output to .pi/skills/.
Pi follows the open Agent Skills specification and uses the same
subdirectory/SKILL.md structure that BMAD already generates for
other platforms.
Fixes#1853
* fix: address PR review comments for Pi test suite
- Assert template_type === 'default' to pin config contract
- Verify Pi appears in getAvailableIdes() list
- Test detect() returns false before install, true after
- Parse frontmatter between --- delimiters instead of regex on full file
- Assert description is present and non-empty
- Assert frontmatter contains only name and description keys
- Validate body content is non-empty with expected activation instructions
- Add reinstall/upgrade coverage (rerun setup over existing output)
- Move temp directory cleanup to finally block
* feat(skills): migrate Roo Code installer to native skills format
Move Roo Code from legacy `.roo/commands/` flat files to native
`.roo/skills/{skill-name}/SKILL.md` directory output. Verified
skill discovery in Roo Code v3.51 with 43 skills installed.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test(skills): add native skills tests for Claude Code, Codex, and Cursor
Add dedicated test suites covering config validation, fresh install,
legacy cleanup, and ancestor conflict detection for Claude Code, Codex
CLI, and Cursor. Updates migration checklist to reflect verified status.
84 assertions now pass (up from 50).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* test(skills): add Roo Code reinstall/upgrade test
Verify that running Roo setup over existing skills output succeeds
and preserves SKILL.md output. Checks off the last Roo checklist item.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): migrate GitHub Copilot to config-driven native skills
Replace 699-line custom installer with config-driven skill_format.
Output moves from .github/agents/ + .github/prompts/ to
.github/skills/{skill-name}/SKILL.md. Legacy cleanup strips BMAD
markers from copilot-instructions.md and removes old directories.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: update migration checklist with Copilot and Roo verified results
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): migrate Cline to config-driven native skills
Move Cline installer from .clinerules/workflows to .cline/skills with
SKILL.md directory output. Add legacy cleanup and 9 test assertions.
* feat(skills): migrate CodeBuddy to config-driven native skills
Move CodeBuddy installer from .codebuddy/commands to .codebuddy/skills
with SKILL.md directory output. Add legacy cleanup and 9 test assertions.
* feat(skills): migrate Crush to config-driven native skills
Move Crush installer from .crush/commands to .crush/skills with
SKILL.md directory output. Add legacy cleanup and 9 test assertions.
* feat(skills): migrate Trae to config-driven native skills
Move Trae installer from .trae/rules to .trae/skills with SKILL.md
directory output. Add legacy cleanup and 9 test assertions.
* feat(skills): migrate KiloCoder to config-driven native skills
Replace 269-line custom kilo.js installer with config-driven entry in
platform-codes.yaml targeting .kilocode/skills/ with skill_format: true.
- Add installer config: target_dir, skill_format, template_type, legacy_targets
- Add cleanupKiloModes() to strip BMAD modes from .kilocodemodes on cleanup
- Remove kilo.js from manager.js customFiles and Kilo-specific result handling
- Delete tools/cli/installers/lib/ide/kilo.js
- Add test Suite 22: 11 assertions (config, install, legacy cleanup, modes, reinstall)
- Update migration checklist with verified results
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): migrate Gemini CLI to config-driven native skills
Replace TOML-based .gemini/commands output with native SKILL.md output
in .gemini/skills/. Gemini CLI confirms native skills support per
geminicli.com/docs/cli/skills/.
- Update platform-codes.yaml: target_dir, skill_format, legacy_targets
- Add test Suite 23: 9 assertions (config, install, legacy, reinstall)
- Add Gemini CLI section to migration checklist
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): migrate iFlow, QwenCoder, and Rovo Dev to native skills
Complete the native skills migration for all remaining platforms:
- iFlow: .iflow/commands → .iflow/skills (config change)
- QwenCoder: .qwen/commands → .qwen/skills (config change)
- Rovo Dev: replace 257-line custom rovodev.js with config-driven
.rovodev/skills, add cleanupRovoDevPrompts() for prompts.yml cleanup
All platforms now use config-driven native skills. No custom installer
files remain. Manager.js customFiles array is now empty.
- Add test suites 24-26: 20 new assertions (173 total)
- Update migration checklist: all summary gates passed
- Delete tools/cli/installers/lib/ide/rovodev.js
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(installer): preserve bmad-os-* skills during cleanup
The cleanupTarget method removed all entries starting with "bmad" from
IDE skills directories, which would also wipe version-controlled
bmad-os-* skills from the BMAD-METHOD repo. Add exclusion for the
bmad-os- prefix so those skills survive reinstalls.
* docs: flag all unverified platforms for manual IDE testing
Add NEEDS MANUAL IDE VERIFICATION to KiloCoder, Gemini CLI, iFlow,
QwenCoder, and Rovo Dev checklists. CodeBuddy, Crush, and Trae already
had the flag.
* fix(installer): suspend Kilo Code and add verified Gemini/Crush results
Kilo Code does not support the Agent Skills standard — the migration
from modes+workflows to skills was based on a false fork assumption.
- Add suspended field to platform-codes.yaml, hiding Kilo from the IDE
picker and blocking setup with a clear message
- Fail the installer early (before writing _bmad/) if all selected IDEs
are suspended, protecting existing installations from being corrupted
- Still clean up legacy Kilo artifacts (.kilocodemodes, .kilocode/workflows)
when users switch to a different IDE
- Mark Crush and Gemini CLI as manually verified (both work end-to-end)
- Replace Suite 22 install tests with suspended-behavior tests (7 assertions)
* docs: update KiloCoder checklist to reflect suspended status
* fix(skills): add canonicalIds for BMM research and PRD workflows
Drop the bmm module prefix from 6 workflow skill names so they
install as bmad-create-prd, bmad-domain-research, etc. instead of
bmad-bmm-create-prd, bmad-bmm-domain-research, etc.
* fix(installer): address PR review findings from automated reviewers
Triage of 18 findings from Augment and CodeRabbit reviews on PR #1841:
Source code fixes:
- Exclude bmad-os-* from findAncestorConflict to match cleanupTarget
- Wrap cleanupCopilotInstructions in try/catch (best-effort, not fatal)
- Wrap suspended-platform cleanup in try/catch (failure boundary)
- Clean up temp backup dirs in catch block when install aborts
- Normalize IDE keys to lowercase before suspended lookup
- Delete dead loadCustomInstallerFiles method and stale references
- Rename "Roo Cline" to "Roo Code" in both platform-codes.yaml files
- Fix Gemini CLI package name (@google/gemini-cli, not @anthropic-ai)
Test improvements:
- Add name/frontmatter invariant check to 6 missing platform suites
- Assert stale bmad-architect skill is removed after cleanup
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): add canonical bmad- naming via skill manifests
Add bmad-skill-manifest.yaml sidecars to all 38 capabilities (tasks,
agents, workflows) declaring canonicalId as the single source of truth
for skill names. Update Claude Code and Codex installers to prefer
canonicalId over path-derived names, with graceful fallback.
- 24 manifest files covering 38 capabilities
- New shared skill-manifest.js utility for manifest loading
- resolveSkillName() in path-utils.js bridges manifest → installer
- All command generators propagate canonicalId through CSV manifests
- Drops bmm module prefix from all user-facing skill names
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(skills): claude-code installer outputs .claude/skills/<name>/SKILL.md
Refactor the config-driven installer to emit Agent Skills Open Standard
format for Claude Code: directory-per-skill with SKILL.md entrypoint,
unquoted YAML frontmatter, and full canonical names.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(installer): migrate codex to config-driven pipeline
Delete the custom codex.js installer (441 lines) and route Codex
through the config-driven pipeline via platform-codes.yaml. This
fixes 7 task/tool descriptions that were generic due to bypassing
manifests, and eliminates duplicate transformToSkillFormat code.
Key changes:
- Add codex entry to platform-codes.yaml with skill_format + legacy_targets
- Remove codex from custom installer list in manager.js
- Add installCustomAgentLauncher() to config-driven for custom agent support
- Add detect() override for skill_format platforms (bmad-prefix check)
- Set configDir from target_dir for base-class detect() compatibility
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(installer): guard codex skill installs in nested directories
* fix(installer): warn on stale global legacy skill dirs
* feat(installer): migrate cursor to native skills
* Migrate Windsurf installer to native skills
* Clarify Windsurf skill invocation in checklist
* feat(installer): migrate kiro to native skills
* docs: record kiro skill visibility verification
* Migrate Antigravity installer to native skills
* Document Antigravity ancestor skill verification
* Synchronize native skills migration checklist
* Migrate Auggie installer to native skills
* Migrate OpenCode installer to native skills
* Document live skill verification for Auggie and OpenCode
* fix(test): replace _bmad filesystem dependency with self-contained fixture
The installation component tests walked up the filesystem looking for a
pre-installed _bmad directory, which exists locally but not in CI. Replace
findInstalledBmadDir() with createTestBmadFixture() that creates a minimal
temp directory with fake compiled agents, making tests fully self-contained.
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* fix(installer): refuse install when ancestor dir has BMAD commands
Claude Code inherits slash commands from parent directories, so
installing into a nested project when a parent already has .claude/commands
with bmad-* files causes duplicate entries in the autocomplete.
Add ancestor_conflict_check flag (enabled for claude-code) that walks
up the directory tree before install. If BMAD files are found in an
ancestor target_dir, the installer refuses with an actionable error.
Also fix IdeManager.setup() to propagate handler success status instead
of unconditionally returning success: true.
* Address code review feedback from CodeRabbit and Augment
- Move "Setting up..." log after conflict check so it only shows when
install will proceed
- Fix rm command: add -rf flags and correct quoting for glob outside quotes
- Improve error wording: "ancestor installation" instead of misleading
"ancestor directory"
- Use case-insensitive startsWith for bmad file detection (macOS/Windows)
- Document ancestor_conflict_check in the installer config schema
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(installer): resolve symlinks before ancestor conflict walk
Use fs.realpath() instead of path.resolve() so the ancestor directory
walk follows the physical filesystem path, not the logical symlink path.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* fix(opencode): use mode: all in agent template, remove name frontmatter, fix directory names
- Replace name: '{{name}}' with mode: all in opencode-agent.md
mode: all enables both Tab-key agent switching in the TUI and @subagent
invocation via the Task tool (mode: primary blocked subagent use)
- Remove name: '{{name}}' from opencode-task/tool/workflow/workflow-yaml templates
OpenCode derives command name from filename, not from a name frontmatter field;
the bare {{name}} value was overriding the bmad- prefixed filename causing
name collisions with built-in OpenCode commands (fixes#1762)
- Fix deprecated singular directory names in platform-codes.yaml:
.opencode/agent -> .opencode/agents, .opencode/command -> .opencode/commands
- Add legacy_targets migration: cleanup() now removes stale bmad-* files from
old singular directories on reinstall so existing users don't get duplicates
- Fix removeEmptyParents to continue walking up to parent when starting dir is
already absent instead of breaking early
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(opencode): address code review findings for cleanup and schema docs
- Add project boundary guard to removeEmptyParents() using path.resolve
and startsWith check to prevent traversal outside projectDir (Augment)
- Fix JSDoc: "Recursively remove" -> "Walk up ancestor directories"
- Add user-visible migration log message when processing legacy_targets
- Document legacy_targets field in Installer Config Schema comment block
in platform-codes.yaml (CodeRabbit + Augment)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(opencode): improve removeEmptyParents error handling and loop clarity
- Distinguish recoverable errors (ENOTEMPTY, ENOENT) from fatal errors in
removeEmptyParents() catch block — skip level and continue upward on
TOCTOU races or concurrent removal, break only on fatal errors (EACCES)
- Add comment clarifying loop invariant for missing-path continue branch
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* fix(installer): remove double-escaping of quotes in CSV manifest pipeline
cleanForCSV() pre-escaped " to "" before storing in memory, then
escapeCsv() escaped again at CSV write time. After csv-parse round-trip
(which only un-escapes once), descriptions retained doubled quotes
instead of originals, corrupting generated output files.
Fix: remove the redundant quote escaping from cleanForCSV() since
escapeCsv() already handles CSV quoting correctly at write time.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(installer): use single quotes for description in Gemini workflow templates
Replace triple-quoted """{{description}}""" with single-quoted '{{description}}'
to avoid TOML escaping issues in Gemini workflow templates.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.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
This change removes the disable-model-invocation flag from all IDE installer
templates. By allowing model invocation, bmad help can now properly invoke
suggested workflows as direct skill calls, improving the user experience by
enabling automatic workflow execution when desired.
* feat: migrate Codex installer from .codex/prompts to .agents/skills format
Switch CodexSetup to write BMAD artifacts as Agent Skills (agentskills.io
format) in .agents/skills/<name>/SKILL.md instead of flat files in
.codex/prompts. Remove global/project location prompt. Add legacy cleanup
of old .codex/prompts directories during install and uninstall.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ignore .agents for codex
* fix: normalize line endings and use platform-native EOL in SKILL.md output
Normalize all content to LF in transformToSkillFormat, then convert to
os.EOL (CRLF on Windows, LF on Linux/macOS) before writing SKILL.md
files in both writeSkillArtifacts and installCustomAgentLauncher.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ignore .agents directory
* use description from metadata in custom agent launcher
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Move Raven PR review and file-ref audit from tools/ into
.claude/skills/ as proper bmad-os skills with SKILL.md + prompts/
instructions.md split pattern. Strip XML tags from Raven content,
promote sections to H2 headings. Delete originals from tools/.
Co-authored-by: Brian <bmadcode@gmail.com>
tools/audit-file-refs.md — a repeatable prompt that spawns parallel
Haiku subagents to semantically audit new-format source files for
non-conforming file references. Includes a self-check that verifies
all files are accounted for before producing the final report.
Replaces the planned regex extension (Item 1 of the master plan) with
an approach that can handle the full surface area of reference patterns
without exhaustive pattern enumeration.
Also excludes .junie/ from Prettier checks (IDE integration folder,
user-specific, not in repo).
Refs #1718
Co-authored-by: Brian <bmadcode@gmail.com>
Add CodeBuddy (Tencent Cloud Code Assistant) as a supported IDE platform:
- Add platform config to tools/platform-codes.yaml
- Add installer config to tools/cli/installers/lib/ide/platform-codes.yaml
- Add .codebuddy to .gitignore
CodeBuddy uses the default template type with target directory .codebuddy/commands
Co-authored-by: wison <wisonlin@tencent.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* fix(installer): add custom Rovo Dev installer with prompts.yml generation
Rovo Dev CLI requires a .rovodev/prompts.yml manifest to register prompts
for /prompts access. The config-driven installer was writing .md files but
never generating this manifest, so /prompts showed nothing.
- Create custom rovodev.js installer extending BaseIdeSetup
- Generate prompts.yml indexing all written workflow files
- Merge with existing user entries (only touch bmad- prefixed entries)
- Remove stale rovo entry from tools/platform-codes.yaml
Closes#1466
* fix(installer): prefix prompts.yml descriptions with entry name
The /prompts list in Rovo Dev only shows descriptions, making it hard
to identify entries. Prefix each description with the bmad entry name
so users see e.g. "bmad-bmm-create-prd - PRD workflow..." instead of
just the description text.
* refactor(installer): address review findings in Rovo Dev installer
- Hoist toDashPath import to module top level
- Extract _collectPromptEntries helper replacing 3 duplicated loops
- Remove unused detectionPaths (detect() is overridden)
- Guard generatePromptsYml when writtenFiles is empty
- Align cleanup() with detect() predicate (remove any bmad-*, not just .md)
- Use BaseIdeSetup abstractions (this.pathExists/readFile/writeFile) in cleanup()
- Update loadHandlers() JSDoc to include rovodev.js
---------
Co-authored-by: Brian <bmadcode@gmail.com>
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
- 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
Brian
Alex Verkhovsky
Taras Romaniv
lif
Murat K Ozcan
Frank
JasonYe
Moritz Eysholdt
Gani Mohamed Parakadhullah
Dicky Moore
Chris Chen
Davor Racic
PinkyD
Wendy Smoak
wison