mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-19 08:11:52 +08:00
config-improvements
13 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Emmanuel Atsé
|
cede485217 |
feat(docs): Add sidebar order validator for doc frontmatter (#2409)
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
|
||
|
Brian
|
c52c9b5b0e |
feat(bmad-prd): new PRD skill + product-brief updates (#2378)
* feat(bmm): add bmad-prd skill and extend product-brief with external integrations
Consolidates the legacy create-prd/edit-prd/validate-prd trio into a single
lean facilitator with create/update/validate intent modes, following the
bmad-product-brief pattern. Both skills gain external_sources and
external_handoffs customize.toml fields for routing through corporate MCP
tools (Confluence, Jira, etc.) with graceful degradation, plus a File roles
constraint clarifying decision-log (audit trail) vs addendum (preserved
depth for downstream docs).
* refactor(bmad-prd): tighten SKILL.md and operationalize source-extractor pattern
- Compress Overview to remove coaching prose duplicated in Discovery
- Operationalize "Extract, don't ingest" with explicit subagent return contract; reference from Update, Validate, and Finalize input reconciliation instead of inline "read N documents"
- Fix Overview H1 -> H2 (was breaking pre-pass tooling)
- Move full headless JSON schemas to assets/headless-schemas.md; keep minimal example inline
- Compress File roles bullet; tighten Finalize step 1
SKILL.md: 124 -> 105 lines, ~4729 -> ~4467 tokens
* feat(bmad-prd): open-items gate, drop distillate, persona discipline, decision-log metadata
- Add Finalize "Open-items review" step (new step 4): counts OQs / [ASSUMPTION] / [NOTE FOR PM], walks them with user, flags high density as red flag against agreed stakes
- Validate now treats open-items density as a first-class finding category
- Resume / continuity surfaces open items deterministically as the first orientation step
- Drop the PRD's own distillate output and the bmad-distillator finalize step. Downstream workflows (UX, architecture, story creation) source-extract from prd.md directly via the canonical source-extractor pattern. Headless schemas, customize.toml comments, and template updated accordingly.
- Drop "status: draft" from PRD frontmatter and template; version/state transitions logged to decision-log.md instead. Finalize step 7 records the version transition entry.
- Add PRD Discipline bullet: personas must be research-grounded or marked [ILLUSTRATIVE]; must drive decisions; 2-4 personas max. Discipline pass enforces.
- Expand File roles bullet: competitive-analysis detail beyond a one-line landscape and operational/cost mechanics (rate-limiting, compression) belong in addendum
* feat(bmad-prd): outcome-driven trim, swappable validation checklist, HTML report
SKILL.md trim (4.7K -> ~3.2K tokens, 124 -> 93 lines):
- Cut anchor enumerations (HIPAA/PCI/NIST list, API/Mobile/Web list, hobby->regulated list, "fast/easy/scalable/intuitive", input enumerations, etc.) the LLM already knows
- Cut derivable reasoning (synonyms-cause-drift explanation, hobby-vs-enterprise examples, etc.)
- Cut good/bad examples that anchor LLM attention (password/SendGrid example, persona quote, "let me also add this nearby thing")
- Drop SMART-ceremony language from Measurable bullet (keep judgment-not-ritual; SMART principles fine)
Progressive disclosure to references/:
- Headless mode rules + JSON minimal example moved to references/headless.md (loaded only when invoked headless)
- On Activation step 6 gates mode detection: headless -> read references/headless.md and follow
Swappable validation checklist:
- New assets/prd-validation-checklist.md (15 items: Quality / Discipline / Structural / Stakes-gated, each one line)
- New customize.toml field validation_checklist (override per org)
- Used by Validate intent AND Finalize Step 3 -- same subagent, same checklist, two moments
- Replaces bmad-validate-prd's 13-step micro-file architecture; kept the valuable check dimensions (density, measurability, traceability, implementation leakage, etc.) and dropped the ceremony
HTML validation report:
- New scripts/render-validation-html.py (PEP 723, stdlib only, ~175 lines) renders structured findings JSON into a styled HTML report with pass/warn/fail grade, inline SVG score bar, category grouping
- New assets/validation-report-template.html (inline CSS, native <details>, no JS, no external deps) -- swappable via customize.toml validation_report_template
- New references/validation-render.md documents the subagent output contract and renderer invocation; loaded only when validate flow runs
- Auto-opens browser on interactive runs; headless skips the open
Mode flow consistency:
- Create and Update both now explicitly "proceed to ## Finalize"
- Validate / analyze is standalone -- explicit "does NOT enter ## Finalize"; renderer auto-opens the HTML
- analyze is a synonym for validate; intent detection routes both
- Update mode no longer has its own light-close validation step (Finalize Step 3 covers it)
* refactor(product-brief,bmad-prd): remove distillation from brief and PRD workflows
Drop bmad-distillator integration from bmad-product-brief (finalize step,
update mode, headless JSON, constraints) and clean up customize.toml comments.
Distillation is the wrong layer — story self-containment via epic solution
design docs is the right answer for downstream context.
Also commit pending bmad-prd changes: working mode selector (Express vs
Facilitative), open-items triage into phase-blocking/resolvable/deferred
buckets, persistence wording fix, and facilitation-guide reference.
* refactor(bmad-prd): aggressive SKILL.md compression, remove LLM-obvious content
* feat(bmad-prd,bmad-product-brief): surface party-mode and advanced-elicitation at opening
* refactor(bmm): retire bmad-create-prd/edit/validate, point docs and PM agent at bmad-prd
Removes the three separate PRD skills (create, edit, validate) in favor of the
unified bmad-prd skill. Updates module-help.csv, PM agent menu, workflow map,
getting-started tutorial, commands reference, customize/help SKILL.md examples,
and the website workflow-map diagram. Adds Recipe 6 (Advanced Integration
Patterns) to expand-bmad-for-your-org.md covering external_sources,
external_handoffs, doc_standards, and swappable templates.
* test(bmad-product-brief): drop distillate from evals
Distillate was removed from the product-brief workflow in
|
||
|
Alex Verkhovsky
|
edfb405e27 |
fix(docs): update stale Analyst triggers and add PRFAQ link (#2238)
Analyst (Mary) triggers were listed as BP, RS, CB, WB, DP but the actual agent source defines BP, MR, DR, TR, CB, WB, DP. Update all locale agents.md files. Also add PRFAQ Working Backwards hyperlink to commands.md in en, cs, and vi-vn. Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
003c979dbc |
chore: remove SM agent (Bob) and migrate to Developer agent (#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> |
||
|
Brian
|
abfc56bd2c |
feat: add bmad-prfaq skill as alternative analysis path (#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. |
||
|
Brian
|
0380656de6 |
refactor: consolidate agents into phase-based skill directories (#2050)
* 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. |
||
|
Brian
|
9fa51d996b |
prototype preview of new version of product brief skill (#1959)
* 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> |
||
|
Alex Verkhovsky
|
ee25fcca6f |
refactor: remove legacy YAML/XML workflow engine plumbing (#1864)
* 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> |
||
|
Alex Verkhovsky
|
db8f856fce |
docs: update terminology from commands to skills across all documentation (#1850)
Align documentation with the skills-based architecture migration by replacing references to "commands", "slash commands", and legacy command names with the new "skills" terminology and skill names. |
||
|
Brian Madison
|
1782e97731 |
docs: elevate bmad-help as primary on-ramp across all documentation
BMad-Help is one of V6's flagship features but was undersold in docs. This update positions it properly as the intelligent guide that: - Inspects project state and detects what's completed - Understands natural language queries - Varies options based on installed modules - Auto-invokes after every workflow - Recommends first required tasks Changes: - Add dedicated "Meet BMad-Help" section to getting-started - Expand commands.md with full BMad-Help subsection and examples - Reposition get-answers-about-bmad.md to start with BMad-Help - Enhance install-bmad.md and established-projects.md with query examples - Add index.md tip box promoting /bmad-help as quickest way to dive in |
||
|
Alex Verkhovsky
|
a1101534b2 |
fix(docs): comprehensive documentation site review fixes (#1578)
* fix(docs): comprehensive documentation site review fixes Rehype plugins: - Rewrite rehype-markdown-links for correct relative .md resolution - Handle raw HTML base paths and bare .md links in rehype-base-paths - Guard protocol-relative URLs (//...) in all link processors - Use file.path instead of file.history[0] for vfile compatibility - Fail build when content directory cannot be detected - Export helpers for testability; add 107 unit tests Build & CI: - Revert cancel-in-progress to false to avoid mid-deploy cancellation - Remove redundant link-validation CI step (build validates internally) - Remove unnecessary fetch-depth:0 from docs deploy workflow - Refuse docs build on Windows (platform guard) - Remove dead build scripts and stale references Tooling: - Add DOCS_ROOT boundary check in validate-doc-links.js - Handle directory paths and prefix stripping in link validator - Remove dead regex and add // guard in fix-doc-links.js Accessibility & CSS: - Darken caution/danger aside title colors for WCAG AA 4.5:1 contrast - Fix 100vw scrollbar overflow (banner width:100%, html overflow-x:clip) - Add :focus-visible ring to banner link for keyboard navigation - Remove dead CSS declaration and add missing code block lang Documentation content: - Convert /docs/ absolute links to relative paths and fix llms.txt URLs - Correct command file paths and naming in commands reference - Update stale shard-doc command to current /bmad-shard-doc format - Fix incomplete sentence in install-bmad.md - Add Quick Flow next steps and fix 404 link path - Expand thin content pages with substantive detail - Add sidebar ordering frontmatter to all content pages - Remove BMGD docs (moved to dedicated repo) - Remove unused assets and misleading diagram caption - Add non-iframe fallback link to workflow map diagram - Remove dead noscript block from workflow-map - Standardize BMAD to BMad, fix spelling/grammar, normalize headings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides - Move non-interactive-installation.md into how-to/ directory so it appears in the sidebar navigation (was orphaned at docs root) - Rewrite the page based on editorial review: consolidate redundant sections, add missing how-to structure (prerequisites, "What You Get"), condense installation modes from 5 subsections to a table, cut speculative examples - Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3), then the rest following user journey order - Fix README link to point to docs site instead of repo-internal markdown path Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): address documentation review findings Fix broken directory tree, grammar errors, inconsistent naming, missing admonition/headings, enable lastUpdated timestamps in CI, and remove footer CSS that misapplied to the content footer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): move bleeding-edge install command out of Verify Installation The alternative npx command for installing from main was misplaced inside the "Verify Installation" section. Move it to a tip admonition under Step 1 where users look for install options. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
fc5ef57a5a |
feat: add Kiro IDE support via config-driven installer (#1589)
Replace broken kiro-cli.js custom installer with config-driven approach using platform-codes.yaml. Creates Kiro-specific templates with inclusion: manual frontmatter and #[[file:...]] reference syntax. |
||
|
murat
|
006a1f707e | fix: docs llms order, bmgd draft, tea link |