Skip to content

feat(installer): add BMad Automator module - #1

Open
bma-d wants to merge 132 commits into
mainfrom
bma-d/add-automator
Open

feat(installer): add BMad Automator module#1
bma-d wants to merge 132 commits into
mainfrom
bma-d/add-automator

Conversation

@bma-d

@bma-d bma-d commented Apr 28, 2026

Copy link
Copy Markdown
Owner

What

Adds BMad Automator as an experimental external module available from the installer. The module is sourced from the upstream Automator repo as a pure skill bundle and documented as Claude Code entrypoint only.

Why

Automator lives in a separate maintained repository, but should be selectable from the BMad installer without vendoring generated payloads into BMAD-METHOD.

How

  • Registers bma in external-official-modules.yaml with source-root: payload/.claude/skills, experimental metadata, install targets, worker targets, requirements, and install note.
  • Extends external module resolution and IDE setup to support source-root skill-only modules and skip Claude Code-only skills for unsupported IDE targets.
  • Adds installer/docs coverage for Automator plus tests for Claude Code install and Codex skip behavior.

Testing

Ran npm run test:install successfully. Commit hooks also ran npm test, including refs tests, install tests, eslint, markdownlint, and prettier format check.

sunilp and others added 30 commits March 27, 2026 18:13
step-08-scoping.md:
- Neutral title replacing hard-coded "MVP & Future Features"
- Task statement no longer mandates phase-based prioritization
- Confirmation gate now covers artifact creation, not just de-scoping
- Phased delivery uses user-defined phase labels/count instead of fixed 3
- "wants phased" phrasing replaced with "requests/chooses"
- Development sequence question branches by release mode
- Menu text conditional on delivery mode (no "phased roadmap" for single-release)
- Handoff to step-09 now persists releaseMode in frontmatter
- New failure mode for unapproved phase artifact creation

step-11-polish.md:
- Preservation rule now includes consent-critical evidence from step 8
…2149)

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.
* 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>
…g#2157)

* 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.
…#2158)

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.
…rg#2151)

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>
…de-org#2159)

* refactor: remove bmad-init skill and standardize config loading across all skills

Remove the bmad-init core skill entirely — all agents and workflow skills now
load config directly from their module's config.yaml instead of delegating to
bmad-init as an intermediary. This eliminates the Python script dependency and
simplifies the activation path for every skill.

Changes across all skill types:

- Agents (9 skills): Replace "Load config via bmad-init skill" block with
  direct config loading from `{project-root}/_bmad/bmm/config.yaml`, resolving
  user_name, communication_language, document_output_language,
  planning_artifacts, and project_knowledge

- Workflow skills (12 skills): Standardize INITIALIZATION/Configuration Loading
  sections to a consistent Activation format matching the agent pattern

- bmad-prfaq: Align activation to standard config pattern, convert scripted
  dialogue to outcome-focused instructions (no direct quotes)

- bmad-product-brief: Remove External Skills section referencing bmad-init

- bmad-party-mode: Standardize initialization to Activation format

- bmad-advanced-elicitation: Inline agent_party path instead of config var

- bmad-distillator: Remove unused argument-hint frontmatter

- Delete legacy create-prd/ directory (superseded by bmad-create-prd)

- Delete bmad-init skill entirely: SKILL.md, bmad_init.py, core-module.yaml,
  and test suite

* fix: remove remaining bmad-init references from marketplace.json and distillate examples

Clean up missed references: remove bmad-init from marketplace.json skills
list, replace bmad-init examples in distillate-format-reference.md with
bmad-help/bmad-setup to keep examples valid without referencing a removed skill.

* fix: update broken file references in bmad-edit-prd after create-prd deletion

Point prdPurpose refs from deleted create-prd/data/ to bmad-create-prd/data/
and validationWorkflow ref from create-prd/steps-v/ to bmad-validate-prd/steps-v/.
…gents (bmad-code-org#2160)

Replace the multi-file workflow architecture (workflow.md + 3 step files)
with a self-contained SKILL.md that spawns each agent as an independent
subagent via the Agent tool. This produces genuinely diverse perspectives
instead of one LLM roleplaying multiple characters. Adds --model and
--solo flags for flexibility.
…mad-code-org#2164)

* clear up contradiction and config mispath

* fix(party-mode): clarify solo mode behavior and improve response presentation rules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…org#2121)

* feat(quick-dev): generate spec trace file for one-shot route

One-shot changes now leave a lightweight spec file with frontmatter,
intent summary, and suggested review order — eliminating numbering
gaps when quick-dev is used as the primary dev loop.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(quick-dev): reference spec template instead of inlining structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(quick-dev): deduplicate slug derivation and clarify title variable

Extract shared slug derivation logic above the route fork in step-01 so
both one-shot and plan-code-review routes use a single instruction block.
Add explicit title variable assignment in step-oneshot before it is
referenced in the Generate Spec Trace section.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…org#2140)

Syncs French translation with commit 1040c3c (fix: correctly resolve
output_folder paths outside project root bmad-code-org#2132).

Co-authored-by: Brian <bmadcode@gmail.com>
…ode-org#2172)

* 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 bmad-code-org#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
…org#2176)

Replace purple/electric blue accent with Ghost blog design tokens:
- Background #0a0a0a, surface #1a1a1a, borders #262626
- Accent blue #3b82f6, text #fafafa/#a1a1a1/#666666
- Inter body, Space Grotesk headings, JetBrains Mono code
- Remove logo images, use text title
…2177)

Delete the Barry agent persona and migrate its QD (quick-dev)
capability to the Amelia dev agent. Update EN, ZH, and FR docs,
marketplace JSON, and workflow diagrams.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add bmad-checkpoint skill for guided human change review

Copies the av-human-review experiment skill into BMAD-METHOD as
bmad-checkpoint, following established multi-step skill conventions
(SKILL.md → workflow.md → step chain). Registered in module-help.csv
under 4-implementation phase.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: rename bmad-checkpoint to bmad-checkpoint-preview

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(checkpoint): inline workflow into SKILL.md and add global step rules

Remove separate workflow.md — its content now lives directly in SKILL.md
with merged frontmatter. Replace scattered standing rules with a structured
Global Step Rules section (path:line format, front-load output, comm style).

* refactor(checkpoint): reference global step rules from SKILL.md in step-01

* refactor(checkpoint): deduplicate step rules against global step rules

Steps 2–4 now reference Global Step Rules in SKILL.md instead of
restating path:line format, front-load, and silence rules locally.
Step-specific rules (concern-based org, design judgment, risk
awareness, experiential testing) are preserved.

* fix(checkpoint): move main_config out of SKILL.md frontmatter

SKILL.md frontmatter should only contain name and description.
Hardcode the config path inline in the INITIALIZATION section.

* docs(checkpoint): update skill description and trigger phrases

Rewrite description to reflect the skills purpose as an LLM-assisted
human-in-the-loop review. Add checkpoint trigger, drop stale triggers.

* fix(checkpoint): align trail format with global step rules and add token budget

Use CWD-relative path:line in fallback trail (not markdown links),
cap full-file reads at ~50k tokens, remove over-prompted empty-tree SHA.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* refactor(checkpoint): rewrite FIND THE CHANGE as numbered priority cascade

Replace the ad-hoc change-finding logic with a clean 1-5 cascade
modeled after quick-dev Intent Check: explicit argument, recent
conversation, sprint tracking, current git state, ask. Extract
spec/commit pairing into a separate ENRICH step that runs after
any cascade level resolves. Add planning_artifacts to SKILL.md
initialization.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): clarify review_mode and terse-commit instructions in step-01

Replace opaque Review Mode table with explicit set-variable instructions.
Scope terse commit message handling to bare-commit mode only.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): make review_mode a numbered cascade, not independent bullets

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): simplify change_type from table to one-liner

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): make link-to-source conditional on source existing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): make surface area stats best-effort with baseline cascade

Replace rigid with-spec/bare-commit split with a 4-level fallback:
baseline_commit, merge-base, HEAD~1, skip. Omit metrics that
cannot be computed rather than failing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(checkpoint): extract fallback trail generation into generate-trail.md

Reduce step-01 bloat by moving the conditional trail generation
sub-routine into its own file, loaded only when review mode is
not full-trail.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(checkpoint): add early-exit routing and wrap-up step

Replace undefined "I've seen enough" exits with proper early-exit
handling across steps 02-04. Extract wrap-up logic into dedicated
step-05-wrapup.md. Fix step-02 menu text that incorrectly promised
"code review" when step-03 does risk surfacing.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…d-code-org#2180)

Clarify review_mode state transition intent in generate-trail, label
step-02 walkthrough branches as normal vs fallback, replace circular
communication style rule with config variable refs, swap confirm gate
for [inferred] flag, and clarify stats data source as full diff.
…org#2183)

* docs(checkpoint): add explainer page and workflow diagram

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(checkpoint): replace excalidraw source with exported PNG diagram

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
bmad-code-org#2184)

Skill validator (STEP-04) flagged the decision menu in step-05 as
missing an explicit halt instruction between presenting the menu and
acting on the user's choice, risking LLM auto-advance.
…ent (bmad-code-org#2179)

Delete the Quinn (bmad-agent-qa) agent wrapper and add QA test-generation
capability to Amelia (bmad-agent-dev). Update agent tables, testing docs
(EN/ZH-CN/FR), marketplace.json, party-mode, and checklist references.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…e-org#2186)

* chore: remove SM agent (Bob) and migrate capabilities to Developer agent

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(docs): correct agent naming and grammar from review triage

Standardize Developer agent references to bmad-agent-dev (matching
installed skill directory name) and fix possessive apostrophe in
implementation-readiness workflow.

* fix(skills): replace dev team references with Developer agent

No longer a multi-agent development team — just one Developer agent.
Remove residual Scrum Master search patterns from retrospective.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…code-org#2110)

* docs(vi-VN): add Vietnamese translation for BMAD documentation

* feat(i18n): add Vietnamese website locale

* docs(vi-VN): refine translated documentation

* docs(vi-VN): sync terminology with latest upstream docs

* fix(docs): normalize Vietnamese locale path casing

* docs(vi): update non-interactive installation translation

* docs(vi): translate analysis phase explanation

* docs(vi): sync updated reference and tutorial pages

---------

Co-authored-by: miendinh <miendinh@users.noreply.github.com>
…ad-code-org#2192)

Sync Vietnamese translations with current English source:
- Update agent table to consolidated Developer agent architecture
- Fix bmad-dev -> bmad-agent-dev skill ID references
- Replace Quinn/QA agent framing with built-in QA workflow
- Fix SM agent -> Developer agent in getting-started
- Fix broken platform-codes.yaml URL
- Add missing Validation Commands section to style guide
- Fix malformed table row in style guide
- Remove unsourced content additions in project-context
- Fix roadmap section heading and index link format
- Fix accountability softening in party-mode dialogue
… specs (bmad-code-org#2185)

Teach quick-dev step-01 what BMAD phase 1-3 planning artifacts are (PRD,
architecture, UX, epics, product brief) so it can selectively load relevant
docs instead of guessing from code alone. Remove hard cap of 3 on spec
context field, replacing with judgment guidance. Instruct step-03 to
explicitly pass context files to the implementation sub-agent.
bmad-code-org#2200)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…2207)

Add Discord-first callout banner and AI-generated code curation policy.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…2210)

Starlight banner config doesn't render with custom Header. Added
announcement row to Banner.astro and removed unused config.
bmadcode and others added 3 commits April 26, 2026 22:50
…marketplace.json ships (bmad-code-org#2331)

* fix(installer): route community installs through PluginResolver when marketplace.json ships

Community-catalog installs ignored .claude-plugin/marketplace.json, so modules
that nest module.yaml inside a setup skill's assets/ directory (e.g. Strategy 2
in PluginResolver) ended up half-installed: only module-help.csv and the
generated config.yaml landed in _bmad/<code>/, while the actual skill source
trees and module.yaml never got copied. The install would silently emit
"could not locate module.yaml" warnings and leave .agents/skills/ without
the module's skills.

The fix wires the existing PluginResolver onto the community path:

- CommunityModuleManager.cloneModule now detects marketplace.json after the
  clone+ref-checkout completes and runs PluginResolver. The resolution is
  stamped with channel/sha/registryApprovedTag/registryApprovedSha and cached
  in _pluginResolutions, mirroring the existing _resolutions cache.
- OfficialModules.install consults the community plugin resolution and
  delegates to installFromResolution (the same code path custom-source
  installs already use). installFromResolution branches on communitySource
  to write source: 'community' with the registry's approved tag/sha and
  channel.
- resolveInstalledModuleYaml now searches the community-modules cache root
  in addition to the external-modules cache, and the BMB setup-skill detector
  walks src/skills/ and skills/ (not just the repo root) so collectAgents
  FromModuleYaml and writeCentralConfig can find module.yaml in nested
  marketplace-plugin layouts.

Backward compatibility: repos without marketplace.json (e.g. WDS, which
declares module_definition: src/module.yaml at the root) continue through
the legacy findModuleSource path with no behavior change. Verified against
the live zarlor/suno-band-manager community module and a 23-check fixture
suite covering Suno-shape, WDS-shape, and bare-repo layouts.

* fix(installer): harden community marketplace.json resolution path

Address review feedback on the community marketplace.json install path:

- Wrap PluginResolver.resolve() in try/catch so a malformed plugin entry
  falls through to the legacy install path with a warn instead of
  crashing cloneModule.
- Stop mutating the resolver's return object; shallow-clone before
  stamping community provenance so install state cannot leak back into
  resolver-owned objects.
- Warn when _selectPluginForModule lands on the single-plugin fallback
  with a name that doesn't match the registry code or module_definition
  hint, so a misconfigured marketplace.json can't silently install the
  wrong plugin.
- Add CommunityModuleManager.resolveFromCache() and call it from
  OfficialModules.install() when the in-process plugin cache is empty,
  so callers that reach install() without pre-cloning still get the
  marketplace-aware path. Reuses an existing channel resolution when
  present, otherwise synthesizes a stable-channel stub from the registry
  entry plus the cached repo's HEAD.
- Align installFromResolution()'s returned versionInfo.version with
  manifestEntry.version precedence (communityVersion || cloneRef || ...)
  so downstream summaries match what was written to the manifest.

Tests: lint, format:check, lint:md, test:install (290), test:channels
(83), test:refs (7) all green.
* fix(installer): preserve http protocol in custom module clone URLs

Previously, parseSource() hardcoded 'https://' when building cloneUrl,
forcing http:// Git URLs (e.g., internal LAN hosts) to upgrade to https.
This broke cloning for self-hosted Git servers that only serve over HTTP.

- Capture the protocol from the regex match instead of discarding it
- Update JSDoc and inline comments to document HTTP support
- Update install-custom-modules docs (EN, ZH, VN) to list HTTP URL type

Fixes the --custom-source flag for http:// addresses.

* docs(installer): update JSDoc to mention HTTP support in cloneRepo

Add HTTP to the cloneRepo method's JSDoc param description.
Also fixes minor spacing in empty arrow functions (formatting).

* docs(installer): fix JSDoc annotation for cloneRepo param

Correct @PARAM backtick escaping in cloneRepo JSDoc.
Also documents HTTP as a supported protocol alongside HTTPS and SSH.

---------

Co-authored-by: 关惠民 <9155544@qq.com>
…mad-code-org#2336)

* fix: use full update path when --custom-source is passed with --yes

When --yes is used on an existing install, the installer auto-selects
quick-update. However, quick-update never re-clones custom module repos
— it only reads whatever is already in the cache. This means
--custom-source with a new version tag (e.g. @1.1.0) is silently
ignored and the previously cached version (e.g. 1.0.1) is reported as
"already up to date".

Default to the full update path when --custom-source is present, so the
custom repo gets re-cloned at the requested version. Also ensure all
installed modules are included in the selection when --yes is combined
with --custom-source, preventing previously installed modules from being
removed.

* fix: address review feedback on choices.find() and comment clarity

* style: prettier fix for empty-body methods in custom-module-manager

---------

Co-authored-by: Brian <bmadcode@gmail.com>
@bma-d
bma-d force-pushed the bma-d/add-automator branch from 8561854 to adcffe6 Compare April 28, 2026 02:57
bmadcode and others added 9 commits April 27, 2026 23:01
…ols none (bmad-code-org#2346)

* fix(installer): require --tools for fresh --yes installs; remove --tools none (closes bmad-code-org#2326)

Fresh non-interactive installs without --tools previously produced a
config-only install (~35 files vs ~1400 in the manifest) with no warning
and a "BMAD is ready to use" success card, leaving slash commands
unreachable. --tools none was an explicit opt-in for the same broken
state.

Now: fresh install + -y without --tools throws a helpful error pointing
at --list-tools. --tools none is rejected as an unknown ID. Empty and
typo'd tool IDs are also rejected. Existing-install paths (--action
update, quick-update, modify) are unchanged - they continue to reuse
previously-configured tools when --tools is omitted.

Adds --list-tools flag that prints all 42 supported tool IDs (id, name,
target_dir, preferred star) sourced from platform-codes.yaml.

English docs updated; localized docs (vi-vn, fr, cs, etc.) will sync via
the normal translation pass.

* fix(installer): address review for bmad-code-org#2326 — single source of truth, drop dead code, add tests

- Refactor formatPlatformList to use IdeManager so --list-tools and --tools
  validation see the same set of platforms. Eliminates the drift where suspended
  platforms appeared in --list-tools but were rejected at validation.
- Drop unused getValidPlatformIds export.
- Flatten redundant block scope around the throw in the --yes-without-tools
  branch (refactor leftover).
- Drop dead String() defensive cast (Commander always passes a string).
- Add Test Suite 42: 8 unit tests covering _parseToolsFlag empty/whitespace/
  unknown/typo cases plus an integration check that --list-tools output and
  --tools validation agree on the ID set.

* fix(installer): close --tools "" bypass and drop hardcoded tool count

- Replace truthy `if (options.tools)` guard with `!== undefined` in both
  upgrade and fresh-install branches. Empty string now reaches
  _parseToolsFlag and produces the specific "passed empty" error
  instead of falling through to a generic message (fresh-install) or
  being silently ignored (existing-install).
- Drop the hardcoded "42 supported tools" count from the prereqs in
  install-bmad.md so the doc doesn't drift as platform-codes.yaml
  changes.

Addresses augment / coderabbit review on bmad-code-org#2346.
…code-org#2292) (bmad-code-org#2347)

step-07-validation template shipped with all 16 completeness checkboxes
pre-checked and Overall Status hard-coded to READY FOR IMPLEMENTATION,
defeating the gate. Reset checkboxes to unchecked, replace status with a
templated choice tied to the checklist and gap analysis, and instruct the
agent to only mark items the validation actually confirms.

Closes bmad-code-org#2292
…bmad-code-org#2348)

* fix(config): promote project_name to core, fixes bmad-code-org#2279

project_name was a bmm-specific prompt despite being a universal
project-level concept used by every module — including core skills like
bmad-brainstorming, which loads from _bmad/core/config.yaml and was
silently broken because project_name lived under bmm. Users without bmm
installed could not run brainstorming at all.

Move:
- src/core-skills/module.yaml: declare project_name with prompt
  "What is your project called?" and default {directory_name}, matching
  what bmm previously had.
- src/bmm-skills/module.yaml: remove the bmm definition; add project_name
  to the "Variables from Core Config inserted" header comment so
  contributors can see what's inherited.

Migration for existing installs:
- tools/installer/modules/official-modules.js: after loadExistingConfig
  reads each per-module config.yaml, hoist any keys that are now declared
  in core but appear under non-core modules. Without this, the partition
  logic in writeCentralConfig (which strips core keys from non-core
  buckets) would silently drop the user's prior project_name on the next
  quick-update. Generic — handles project_name today and any future
  module→core promotions.
- The hoist preserves precedence: an existing core value beats a stale
  module-side copy.

--yes seed:
- tools/installer/ui.js: add project_name to the hardcoded core seed
  (using path.basename(directory) to match the {directory_name} default)
  so non-interactive fresh installs populate it. Without this the seed
  silently omits project_name and core skills fall back to literals.

Tests:
- test/test-installation-components.js Suite 43 (9 assertions) covers
  the schema move, the loadExistingConfig hoist, and the precedence rule.
- Suite 35 fixture updated: project_name moved from bmm bucket to core,
  with a stale bmm copy left in place to verify it gets stripped.

Verified manually:
- Fresh install -y: project_name lands in [core] of config.toml.
- Existing install with project_name in bmm/config.yaml: quick-update
  hoists it to [core] and strips it from [modules.bmm].

* fix(installer): harden config-load against malformed config.yaml

Per augment review on bmad-code-org#2348: loadExistingConfig stored any truthy
yaml.parse result (including scalars like '42'), which would later crash
_hoistCoreKeysFromLegacyModuleConfigs at \`key in cfg\` with
"Cannot use 'in' operator to search for ... in 42".

- loadExistingConfig: only keep parses that are plain objects (not
  scalars or arrays). A corrupt config.yaml is now treated the same as
  a parse error — skipped, not crashed-on.
- _hoistCoreKeysFromLegacyModuleConfigs: belt-and-suspenders type guards
  on _existingConfig.core (in case it's populated by some other path)
  and on each module cfg in the loop.
- Test Suite 43 adds 2 assertions covering a scalar core/config.yaml:
  loadExistingConfig must not crash, and bmm.project_name must still
  hoist into a clean core bucket.
…ows (bmad-code-org#2278) (bmad-code-org#2349)

* fix(installer): preserve module-help.csv schema in merged bmad-help.csv (bmad-code-org#2278)

The installer's mergeModuleHelpCatalogs was rewriting the merged catalog
under a different schema (module,phase,name,code,sequence,workflow-file,...)
than the documented source schema in every module's module-help.csv
(module,skill,display-name,menu-code,description,action,args,phase,...).

Worse, the parsing assumed the wrong source column order, so column data
was scrambled in the merged output. SKILL.md docs the source schema, so
the bmad-help skill was navigating a catalog whose actual columns no
longer matched its mental model.

Drop the transformation and the agent enrichment columns (which had no
consumers anywhere in the codebase). Emit rows verbatim in the source
schema, padding short rows and filling empty module fields. Sort by
module then phase, stable within phase to preserve authored order.

Closes bmad-code-org#2278

* fix(catalog): normalize module-help.csv rows to documented 13-column schema

Many rows in core-skills/module-help.csv and bmm-skills/module-help.csv
were missing one column between description and phase, leaving them at
12 fields instead of 13. CSV consumers that read by header position
were silently mapping data into the wrong columns (description into
action, phase into args, required into before, etc).

Inserted an empty cell at column index 5 across all 31 affected rows
to restore alignment with the documented header
(module,skill,display-name,menu-code,description,action,args,phase,
after,before,required,output-location,outputs).
…fig (bmad-code-org#2354)

Closes bmad-code-org#1663.

Adds two installer flags so module config options can be set without
interactive prompts. Designed for CI scripts, Dockerfiles, and
enterprise rollouts where the user wants to bake answers into the
install command rather than answer prompts.

`--set <module>.<key>=<value>` (repeatable) sets any module config
option. `--list-options [module]` lists every key the installer can
discover locally — built-in modules (`core`, `bmm`) plus any cached
official modules. One flag scales to every module without growing the
CLI surface per option.

```bash
npx bmad-method install --yes \
  --modules bmm --tools claude-code \
  --set bmm.project_knowledge=research \
  --set bmm.user_skill_level=expert \
  --set core.user_name=Brian
```

## How it works

`--set` is a post-install patch. The installer runs its normal flow
untouched, then `applySetOverrides` upserts each value into the
relevant config files:

- `_bmad/config.toml` (team scope, default)
- `_bmad/config.user.toml` (user scope, when the key already lives
  there — so user-scope keys like `core.user_name` and
  `bmm.user_skill_level` keep their proper file)
- `_bmad/<module>/config.yaml` (so declared schema keys carry forward
  via the existingValue path on the next install)

A module without `_bmad/<module>/config.yaml` is skipped silently —
no orphan sections in `config.toml` for uninstalled modules.

## Tradeoffs documented in install-bmad.md

- **Verbatim values.** `--set bmm.project_knowledge=research` writes
  `"research"`, not `"{project-root}/research"`. The `result:`
  template is not applied. Pass it explicitly if you want the
  rendered form: `--set bmm.project_knowledge='{project-root}/research'`.
- **Carry-forward, declared keys.** Free — values land in the
  per-module `config.yaml`, so the next install reads them as
  `existingValue` and they become the prompt default (accepted under
  `--yes`).
- **Carry-forward, undeclared keys.** Best-effort. The value lives in
  `config.toml` for the current install but won't be re-emitted on
  the next install (the manifest writer's schema-strict partition
  drops unknown keys). Re-pass `--set` if needed.
- **No "key not in schema" validation.** Whatever you assert is
  written.

## Security

Prototype-pollution defense: `--set __proto__.x=1` would otherwise
reach `overrides.__proto__[x] = 1` and pollute `Object.prototype`,
cascading into every plain-object lookup in the process. Defense-in-
depth via parser-level reserved-name rejection (`__proto__`,
`prototype`, `constructor`) AND `Object.create(null)` for the
override maps. Verified the attack reproduces without the guard and
is blocked with it.

## What's intentionally NOT integrated

`--set` deliberately does not touch the prompt / template / schema
collection flow. No pre-seeding answers, no question filtering, no
function-default evaluation, no schema-strict partition exemption.
That earlier integration approach was tried and scrapped: it
spread state across `Config`, `OfficialModules`,
`manifest-generator`, both collection helpers, and required parallel
plumbing for quick-update — every bug fix touched a different layer.
The post-install patch model covers the actual user need (set a
config value from CI) in ~330 lines of `set-overrides.js` without
the schema gymnastics.

## Files

- `tools/installer/set-overrides.js` (new): parser, prototype-pollution
  guard, `applySetOverrides` post-install patch, `upsertTomlKey` /
  `tomlString` / `tomlHasKey` line-based TOML helpers
- `tools/installer/list-options.js` (new): module.yaml discovery +
  formatter for `--list-options`
- `tools/installer/commands/install.js`: register `--set` /
  `--list-options` flags, early validation, `--list-options` exit-code
  handling (await `stream.write` callback then `process.exitCode` to
  avoid truncating piped output), thread `setOverrides` through to
  quick-update
- `tools/installer/core/config.js`: carry `setOverrides` field for
  the post-install patch step
- `tools/installer/core/installer.js`: invoke `applySetOverrides`
  after `writeCentralConfig` (covers regular install + quick-update
  via the shared install path)
- `tools/installer/ui.js`: parse `--set` for early validation, warn
  about overrides targeting modules not in `--modules`, drop those
  entries before threading
- `docs/how-to/install-bmad.md`, `README.md`: usage, routing rules,
  carry-forward semantics, tradeoffs

## Test plan

Suite 44 (24 cases): parser, prototype-pollution guard, `tomlString`
escaping, `upsertTomlKey` across insert/replace/missing-section/
empty-file/preserved-newline cases, `applySetOverrides` happy path +
uninstalled-module skip + missing-user-toml-creation + empty-input
no-op, `discoverOfficialModuleYamls` / `formatOptionsList` sanity
(hermetic via `BMAD_EXTERNAL_MODULES_CACHE` temp dir). 355 total
passing. Lint + prettier + markdownlint clean.

E2E smoke verified across:

- [x] `--set` writes correct files (team toml / user toml / per-module
  yaml) for declared and undeclared keys
- [x] Quick-update without `--set` carries forward declared keys via
  `existingValue` path
- [x] Quick-update WITH `--set` applies cleanly (uniform behavior
  across action types)
- [x] `--set` for unselected module: warned, no orphan section
- [x] Prototype pollution: rejected with non-zero exit
- [x] `--list-options bmm` exit 0 with full output through pipe;
  `--list-options nope` exit 1
- [x] Translated docs (`docs/{cs,fr,vi-vn,zh-cn}/`) intentionally not
  touched — they'll lag behind English until the translation pipeline
  runs
…ebar (bmad-code-org#2355)

Add Chinese translations for the two remaining untranslated docs
(named-agents, expand-bmad-for-your-org) and add i18n translations
for the BMad Ecosystem sidebar group and its items across all locales.

Co-authored-by: leon <leon.liang@hairobotics.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(installer): handle deep-path URLs in custom module source parser

Rewrite parseSource() from host-specific regex to generic URL-based
parser so Azure DevOps _git paths and other multi-segment repo URLs
are preserved in cloneUrl and cacheKey.

Closes bmad-code-org#2268

* test(installer): add Azure DevOps URL tests and wire into CI

- Add 18 assertions for dev.azure.com and visualstudio.com URLs
- Cover modern ADO, legacy ADO, .git suffix, ?path= subdir variants
- Add test:urls script to test and quality npm chains

---------

Co-authored-by: Brian <bmadcode@gmail.com>
@bma-d
bma-d force-pushed the bma-d/add-automator branch from 2f328b3 to 6b60599 Compare April 29, 2026 04:29
jheyworth and others added 3 commits April 29, 2026 22:13
…ode + GitHub Copilot) (bmad-code-org#2324)

* fix(installer): generate OpenCode /<skill> slash commands

Adds .opencode/commands/<canonicalId>.md pointer files for each installed
skill so users can invoke skills directly (e.g. /bmad-quick-dev) instead
of going through the /skills menu.

- platform-codes.yaml: add commands_target_dir field for opencode
- _config-driven.js: installCommandPointers() with skip-if-exists default,
  reserved-name collision guard, YAML-safe description quoting
- _config-driven.js: cleanupCommandPointers() for symmetric uninstall
- test-installation-components.js: extend OpenCode suite with assertions
  covering pointer creation, content, and idempotency

OpenCode-only and opt-in via the new yaml field; other adapters unchanged.

Refs bmad-code-org#2267

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): address PR bmad-code-org#2324 review feedback

Six fixes from CodeRabbit + Augment review on the OpenCode command
pointer generation:

- skipTarget no longer suppresses installCommandPointers in multi-IDE
  shared-target_dir batches. Pointers live in a per-IDE directory and
  are not deduped across peers, so OpenCode must still generate them
  even when a peer (e.g. openhands) won the .agents/skills write race.
- skipTarget no longer suppresses cleanupCommandPointers either, so
  partial uninstalls leave no stale pointers when a peer remains.
- canonicalId is validated as a safe basename before being interpolated
  into a file path (defense in depth against a malformed manifest entry
  writing outside commands_target_dir).
- yamlSafeSingleLine now quotes descriptions starting with `[` or `{`
  so YAML doesn't parse them as a sequence/map.
- Per-record fs.writeFile failures are caught and counted (writeFailures)
  rather than aborting the whole IDE install — pointer files are a
  non-essential adjunct to the skill copy.
- Generator-shaped pointer files are refreshed when the manifest
  description changes; hand-modified files (body diverges from the
  generator pattern) are still preserved unless forceCommands is set.

Tests: extends Suite 8 with description-update propagation; adds new
Suite 40c covering OpenCode + openhands batches in both orderings plus
partial-IDE uninstall pointer cleanup. 308 tests pass (was 296).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): address PR bmad-code-org#2324 follow-up nitpicks

Four nitpicks from CodeRabbit's original review that were missed in the
first triage pass:

- Hand-edited pointers now survive the production install flow.
  cleanupCommandPointers spares pointers for canonicalIds that are still
  in the new manifest when called from the install/update flow (signal:
  options.previousSkillIds is set). Uninstall and partial-IDE removal
  flows still wipe pointers as before. The previous behavior wiped every
  pointer in removalSet before installCommandPointers could run, so its
  skip-if-exists guard never fired and hand edits were lost on every
  reinstall — contradicting the docstring's preservation claim.
- RESERVED_OPENCODE_COMMANDS is now gated on this.name === 'opencode'
  so future adapters opting into commands_target_dir don't silently
  inherit OpenCode's reserved-name set.
- printSummary now surfaces results.commands so users see how many
  pointers were created/refreshed/skipped per install, plus a warning
  for any per-file write failures.
- Dropped a dead `typeof entry !== 'string'` check; fs.readdir without
  withFileTypes always yields strings.

Tests: extends Suite 8 with a hand-edit-preservation regression that
calls setup with previousSkillIds (the production shape) and asserts a
sentinel byte sequence in the pointer body survives. 310 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): extend command-pointer generation to Copilot Custom Agents

Re-scopes bmad-code-org#2324 to cover the second user-facing pain: GitHub Copilot's
Custom Agents picker, where installed BMAD skills currently don't show up
even though slash commands work natively.

Generalizes the per-platform pointer-file mechanism so the same
installCommandPointers / cleanupCommandPointers code path serves both
OpenCode (slash commands palette) and Copilot (Custom Agents picker), with
all platform-specific shape pushed into platform-codes.yaml as data:

- commands_target_dir       — where pointer files live (existing)
- commands_extension        — file extension (default '.md'; Copilot uses
                              '.agent.md' per VS Code Custom Agents docs)
- commands_body_template    — pointer body, supports {canonicalId} and
                              {target_dir} placeholders. Default matches
                              OpenCode's `@skills/<id>` resolver. Copilot
                              has no such resolver, so its template uses
                              the {project-root}/<target_dir>/<id>/SKILL.md
                              LOAD pattern (consistent with PR bmad-code-org#1769).

OpenCode behavior is unchanged. Copilot users now get a per-skill
.github/agents/<canonicalId>.agent.md file that surfaces the skill in the
Custom Agents picker — addressing the "agents being gone" complaint
flagged by enterprise users.

Tests: extends Suite 17 with assertions for Copilot agent pointer
creation, body content (LOAD pattern with {project-root}-rooted path),
and idempotency. 318 tests pass (was 310).

Refs bmad-code-org#2267

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): filter Copilot Custom Agents picker to persona agents only

Earlier commit naively wrote a `.github/agents/<id>.agent.md` for every
installed skill, which would clutter the Custom Agents picker with 90+
workflow/tool entries that don't belong there.

Adds an `agents-only` filter that gates the per-skill emission on whether
the canonical id signals a persona agent:

- Primary rule: id contains `-agent-` (e.g. `bmad-agent-pm`,
  `gds-agent-game-dev`, `wds-agent-freya-ux`,
  `bmad-cis-agent-storyteller`).
- Allowlist: `bmad-tea` — TEA's Murat persona uses the bare module code
  rather than the `-agent-` convention. Listed explicitly so the rule
  still surfaces it.

Verified against the full installed manifest (114 skills): catches all
20 description-confirmed personas across BMM, CIS, GDS, WDS, TEA;
excludes all 94 workflows/tools.

Wired through a new yaml field on github-copilot:

  commands_filter: agents-only

OpenCode is unaffected — it has no `commands_filter` set, so the loop
behaves as before (every skill becomes a slash command).

Tests: extends Suite 17 with a multi-skill manifest fixture covering
persona/agent + bmad-tea + workflow cases; asserts persona agents and
bmad-tea get .agent.md files while workflows do not. 322 tests pass.

Refs bmad-code-org#2267

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): detect personas via customize.toml [agent] section

Per maintainer review on PR bmad-code-org#2324: the `-agent-` naming convention isn't
a load-bearing contract anywhere else in the codebase, and the bmad-tea
allowlist already shows it starting to break. A future persona that
doesn't follow the convention would silently disappear from the Copilot
Custom Agents picker.

Replaces the name-based filter with a behavior-based signal: read each
skill's source `customize.toml` and check for an `[agent]` section. This
is the actual configuration source of truth — every BMAD persona is
configured under `[agent]`, every workflow under `[workflow]`, every
standalone skill has no customize.toml.

Verified on disk against the full installed manifest (114 skills):

- 20 personas detected — exactly the description-confirmed count across
  BMM, CIS, GDS, WDS, TEA. bmad-tea is caught natively (no allowlist).
- 94 workflows/tools correctly excluded.
- `bmad-agent-builder` (meta-skill that builds agent skills) is now
  CORRECTLY excluded — its canonical id contains `-agent-` but its
  customize.toml has [workflow], not [agent], because it isn't a
  persona itself. The previous naming-based filter was including it in
  the agents picker, which would have been a silent UX bug.

`NON_CONVENTIONAL_AGENT_IDS` constant is removed entirely — the toml
signal subsumes it.

Tests: extends Suite 17 with a 4-skill fixture that covers persona +
non-conventional persona + workflow + meta-skill cases. 388 tests pass.

Refs bmad-code-org#2267

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(installer): always include bmad-help in Copilot agents picker

Adds a single, deliberate exception to the toml-based agents-only filter:
`bmad-help` is the structural meta-skill across BMAD — the orientation
helper that points users at every other skill. Users invoke it
persona-style ("ask the helper") even though it has no `[agent]`
customize.toml of its own (it isn't a configurable persona).

Implemented as a one-element ALWAYS_AGENT_IDS set rather than a hardcode
in the function body so the exception is named, documented, and
discoverable. The skill is structurally unique — there is no second
meta-help skill — so this is not the start of a growing allowlist; it's
a one-off for the one orientation surface BMAD ships.

Verified on disk: agents picker now shows 21 entries (20 personas via
[agent] in customize.toml + bmad-help). bmad-agent-builder stays
correctly excluded (its customize.toml has [workflow], not [agent]).

Tests: extends Suite 17 with a `bmad-help` fixture (no customize.toml,
must still appear in agents picker). 389 tests pass.

Refs bmad-code-org#2267

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
…mad-code-org#2359)

* fix(installer): remove bmad-help from Copilot Custom Agents picker

Per @bmadcode's feedback after bmad-code-org#2324 merged: every persona agent's
activation message already advertises bmad-help, so its picker entry is
redundant AND confusing (looks like a peer agent when it's actually the
meta-help). Removes the ALWAYS_AGENT_IDS allowlist exception that put it
there.

The toml-driven filter (the mechanism BMadCode endorsed in his PR review)
remains the sole signal: a skill is a persona iff its source
customize.toml has an [agent] section. bmad-help has no customize.toml,
so under the cleaned-up filter it's correctly excluded.

Tests: replaces the inclusion assertion in Suite 17 with an exclusion
assertion. Suite still covers persona / non-conventional persona /
workflow / meta-skill-with-`-agent-`-in-name cases.

Refs bmad-code-org#2324

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: clarify Suite 17 fixture comment per PR review

The fixture creates no customize.toml at all for bmad-help, so the
exclusion path being exercised is the missing-file branch — not the
file-without-[agent]-section branch. Reword the comment accordingly.

Per @augmentcode review on bmad-code-org#2359.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ad-code-org#2360)

* refactor(catalog): rename after/before columns to preceded-by/followed-by

The bare prepositions `after` and `before` had no subject anchor, leaving
the dependency direction ambiguous: "X has Y in its `after` column" reads
plausibly as either "Y comes after X" or "X comes after Y". An LLM
catalog consumer just got the direction wrong because of this.

`preceded-by` / `followed-by` are passive-voice participles whose grammar
locks the subject (the skill in this row) and forces a single reading:
"X is preceded by Y" can only mean Y comes first.

Rename applied to:
- module-help.csv headers (bmm-skills, core-skills)
- bmad-help SKILL.md schema doc + descriptions
- installer.js mergeModuleHelpCatalogs header string
- plugin-resolver.js _buildSynthesizedHelpCsv header string
- bmad-manifest.json keys (bmad-product-brief, bmad-prfaq)
- distillate-format-reference.md example manifest

The separate `required` column continues to carry hard-gate semantics;
the renamed columns are pure soft sequencing hints, as already documented
in bmad-help.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style(installer): wrap long header strings per prettier

* feat(installer): warn on non-canonical module-help.csv headers

mergeModuleHelpCatalogs now compares each per-module file's header
against the canonical schema and emits a one-shot prompts.log.warn per
module on drift, naming both the expected and actual header. Data
continues to load positionally so external modules built against the
old after/before schema still install cleanly — the warning is the
maintainer signal to rename their columns.

Centralize the canonical header in modules/module-help-schema.js so the
merger and the synthesizer (PluginResolver._buildSynthesizedHelpCsv)
read the same source of truth; future column renames are one edit.

Verified by installing all four bmad-org external modules
(bmb, cis, gds, tea) — every one ships the legacy after/before header
today and now fires an advisory warning while still merging cleanly
into _bmad/_config/bmad-help.csv with the canonical column names.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@bma-d
bma-d force-pushed the bma-d/add-automator branch 2 times, most recently from fc84357 to 550ea6a Compare May 8, 2026 10:37
anderewrey and others added 4 commits May 8, 2026 12:53
Forensic case investigation under Amelia's menu (IN). Evidence-graded
findings (Confirmed / Deduced / Hypothesized), hypothesis discipline,
structured case-file artifact. Single procedure that calibrates between
defect-chasing and area-exploration based on the input.

Wires bmad-create-prd discovery to pick up case files as PRD input.
Public explainer doc, workflow-map Phase 4 row, EN + FR.
Two PR review fixes:

- Strip the surrounding markdown code fence from case-file-template.md
  so initializing a case file doesn't nest the whole artifact inside a
  code block. The template is now the structure directly, with usage
  notes in an HTML comment that doesn't render. Matches the BMM idiom
  used by bmad-create-story/template.md.
- Drop the stale `*-archaeology.md` reference from bmad-create-prd
  step-01 discovery. The single-procedure restructure removed
  archaeology as a distinct mode, so case files only carry the
  `*-investigation.md` suffix. Tighten the glob accordingly.
Maintainer review (PR bmad-code-org#2364):
- shorten frontmatter description
- add customize.toml for case-file template, output subdir, filename,
  persistent_facts, prepend/append steps, on_complete
- subagent delegation discipline for context-heavy investigation steps
- replace ambiguous "Halt" closer at each outcome with self-documenting
  "Pause for user with the recap above; wait for direction."

Workflow-builder quality findings:
- move case-file-template.md to references/ (path standards)
- align activation with sibling 4-implementation skills (customize.toml
  resolution, persistent_facts, greet)
- operationalize promised flows: existing-case resume (Outcome 0),
  evidence-light branch (Outcome 1), refutation pass (Outcome 3),
  trivial-fix hand-off (Outcome 4)
- define High/Medium/Low confidence in Outcome 5
- name concrete next-step skills at Outcome 5 (bmad-quick-dev,
  bmad-correct-course, bmad-create-story, bmad-code-review)
- add Hand-off Brief and Side Findings to case-file template
@bma-d
bma-d force-pushed the bma-d/add-automator branch from 373badb to a3e0545 Compare May 8, 2026 21:10
bmadcode added 6 commits May 9, 2026 17:24
…mad-code-org#2370)

* refactor(bmm): streamline bmad-product-brief into lean facilitator

Rewrites bmad-product-brief as an outcome-driven, intent-routed
facilitator with a configurable reviewer panel.

- Replace scripted prompt files with a concise SKILL.md
- Add brief-shape detection and intent routing
- Make the reviewer panel config-driven via customize.toml
- Harden the required-reviewer gate
- Add helper scripts and tests for panel resolution
- Replace embedded resources with a single brief-template asset
- Register skill metadata in module.yaml

* refactor(bmm): tighten bmad-product-brief discovery and polish flow

- Discovery now invites a brain dump and source material upfront,
  followed by "anything else?" before drilling
- Create and Update modes explicitly invoke Discovery before drafting
- Calibrate "make them sweat" to ease as the brief firms up
- Update mode regenerates distillate.md when changes apply
- Replace polish_skills with polish_passes: polymorphic entries
  (skill:/file:/plain-text), parallel subagents, applied automatically
  so the user sees a polished draft, not a polish review
- Default persistent_facts to empty with opt-in examples instead of an
  unbounded project-context.md glob
- Remove research-librarian, field-researcher, and skeptic agents no
  longer needed with this rework

* refactor(bmm): make persistence and resume explicit in bmad-product-brief

- Replace "Hold a working memory" with "Persistence is real-time": the
  workspace exists on disk and the user knows the path the moment Create
  intent is confirmed; decision-log.md is canonical memory so walk-away
  leaves nothing in the conversation
- Add "Continuity across sessions": prior in-progress drafts for this
  project surface a resume offer

* test(bmm): scaffold evals for bmad-product-brief

Adds an eval suite for bmad-product-brief following the Anthropic skill-creator
schema, plus a new "Extract, don't ingest" constraint on the skill itself.

Skill change:
- New constraint: source artifacts (user-provided or run-discovered) enter the
  parent conversation as relevance-filtered extracts via subagents, not loaded
  wholesale. Keeps the parent context lean against transcripts, brainstorms,
  research reports, code, web results, and prior briefs.

Evals (evals/bmm-skills/bmad-product-brief/):
- evals.json: 8 artifact/behavioral evals covering Create one-shot,
  source-memo ingest, Update with contradiction surfacing, Validate inline,
  Headless mode, brainstorm filtering, research-report filtering, persona
  filtering. All scenarios use fictional entities (InsuLens, Branfield CC,
  Forkbird Kitchen, Mossridge Library, Sproutkeeper, Hatchet & Loop Studio,
  Brightway, Pantry Bridge).
- triggers.json: 15 description-firing checks (7 should-fire, 8 should-not-fire)
  to catch under-triggering and adjacent-skill poaching.
- files/: realistic fixtures including a brainstorm with the relevant idea
  buried at the end, a 3000-word market research report with the relevant
  section in the middle, and customer interviews with the target persona in
  position 3 of 4 — each shaped to test that filtering happens against the
  user's stated focus regardless of where the relevant material sits.

Eval directory placement: top-level evals/ outside src/, matching the convention
in anthropics/skills (zero of 17 production skills include an evals/ subdir;
their skill-creator places dev workspaces as siblings to skill folders). Keeps
evals out of any installer or marketplace.json distribution path.

* refactor(bmm): rename brief workflow knobs and resolve PR review

- polish_passes -> doc_standards (TOML key + SKILL.md reference). Name
  generalizes for every doc-producing skill: encodes standards applied at
  finalize, not options.
- {run_folder} -> {doc_workspace}. Bound in Create to
  {workflow.output_dir}/{workflow.output_folder_name}/; reused by Update,
  Validate, Headless, and Finalize as the active brief's folder.
- On Activation Step 4 now resolves {date} explicitly (used by
  output_folder_name default).
- Headless Mode: ambiguous-intent fallback is a `blocked` JSON status with
  a `reason` field, no prompting. Resolves the activation/headless
  contradiction flagged in review.

* test(bmm): overhaul product-brief evals into A/B/C pattern split

Refactor evals from 8 numbered single-shot tests into 16 typed evals:
- Pattern A (A1-A8): artifact-correctness tests with headless prompts and
  precise, falsifiable expectations (no invented facts, right-sized output,
  file boundary enforcement)
- Pattern B (B1-B8): process-discipline tests verifying decision-log fidelity,
  polish phase ordering, contradiction detection, and distillate generation
- Pattern C (C1): config-compliance test for custom output paths and
  document_output_language

Also tighten SKILL.md: add dependencies frontmatter, clarify headless override
autonomy in Update (proceed when intent is clear; block when ambiguous), and
make distillate skip explicit when bmad-distillator is not installed.
feat(bmm): add bmad-investigate skill
…tations

- Update: audit trail (decision-log + addendum) is now mandatory before
  modifying brief.md in headless mode; distillate regeneration is required
- Validate: always emits offer_to_update in headless JSON output
- Headless: added validate example to JSON status block docs
- Evals B8: add 900s timeout, replace hard 30%-smaller check with
  meaningful-condensation expectation
- Eval B9: sharpen right-sized expectation wording
fix(bmad-product-brief): tighten update/validate rules and eval expectations
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.