ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/repo-structure-review.md

8.8 KiB
Raw Blame History

Repository Structure Review: Enhancements for Real-World Coding Projects

After a thorough review of the entire repo, here are the structural issues and enhancement opportunities, organized by impact level.

1. CRITICAL: Dual Module Location Creates Broken References RESOLVED

Status: Fixed.

The repo had two overlapping locations for BMM content (src/bmm/ and src/modules/bmm/), causing 6 broken file references across 2 agent files. Agents referenced workflows that only existed in src/modules/bmm/, so the SM and UAT Validator agents would fail at runtime.

What was done:

  • Moved epic-execute/, epic-chain/, and uat-validate/ from src/modules/bmm/ into src/bmm/workflows/ (their correct locations)
  • Created src/bmm/workflows/5-validation/ for the UAT validation phase
  • Fixed .bmad/ → _bmad/ path inconsistencies in the moved epic-chain and epic-execute files
  • Removed the uat-report menu entry from uat-validator.agent.yaml (workflow never existed anywhere)
  • Removed the uat-automation-patterns knowledge reference from uat-validator.agent.yaml (data file never existed)
  • Deleted the now-empty src/modules/bmm/ directory
  • All tests pass (schema validation, file refs, installation components, lint, markdown lint, formatting)

2. HIGH: No Guardrail for Broken File References in CI RESOLVED

Status: Fixed.

The repo already had a comprehensive file reference validator (tools/validate-file-refs.js) that catches broken references, but it ran in warning mode (exit 0) so issues were never blocking. There were also 6 pre-existing broken references preventing strict mode from being enabled.

What was done:

  • Fixed 6 broken file references across 3 workflow files:
    • create-architecture/workflow.md — wrong directory name (architecture → create-architecture)
    • create-story/checklist.md — wrong filename (validate-workflow.xml → workflow.xml)
    • document-project/instructions.md — removed 3 references to non-existent workflow-status workflow
  • Switched validate:refs to strict mode (--strict flag) so broken references now fail with exit code 1
  • Added validate:refs to the npm test script chain, so it runs in both pre-commit hooks and CI
  • CI workflow (.github/workflows/quality.yaml) already ran validate:refs — the --strict flag now makes it a blocking check
  • All 471 file references across 242 source files now validate cleanly

3. HIGH: project-context.md Is a Hidden Prerequisite RESOLVED

Status: Fixed.

project-context.md is now surfaced as a recommended step across all user-facing documentation:

  • README.md — Added a tip after Quick Flow's 3-command list for existing codebases, and inserted /generate-project-context as step 6 in the Full Planning Path before the build cycle
  • Getting Started tutorial — Added a "Project Context (Recommended for Existing Codebases)" subsection between Phase 3 and the build step, with Analyst agent instructions. Also added generate-project-context to the Quick Reference table
  • Established Projects guide — Inserted a new Step 3: "Generate Project Context" explaining both generate-project-context (lean rules) and document-project (comprehensive docs) options
  • Workflow Map — Replaced the dense Context Management paragraph with a scannable "Creating Project Context" sub-heading and a comparison table of both workflows

4. HIGH: Artifact Storage Strategy Is Confusing RESOLVED

Status: Fixed.

Two sub-problems were addressed:

A) Orphaned sprint_artifacts variable (code fix):

  • sprint_artifacts was referenced in epic-chain/workflow.yaml, uat-validate/workflow.yaml, and 3 supporting markdown files but was never defined in any module.yaml — causing those workflows to break at runtime
  • All references replaced with implementation_artifacts, which is properly defined in bmm/module.yaml and serves the same purpose

B) Documentation gap (folder strategy):

  • Getting Started tutorial — Expanded the installation section to explain all three output areas (_bmad/, _bmad-output/, docs/), their purposes, and version control strategy
  • Workflow Map — Added an "Artifact Locations" reference table showing default paths, contents, and version control guidance for each folder category

Remaining (out of scope): The epic-execute/ workflow has hardcoded docs/ paths in its own config system (default-config.yaml) rather than using module variables — this is a separate issue

5. HIGH: Inconsistent Workflow File Format

Workflows use two different formats with no documented rationale:

Format Examples
workflow.yaml (structured) dev-story, code-review, sprint-planning, correct-course
workflow.md (markdown) quick-spec, quick-dev, create-architecture, create-prd
Custom names workflow-create-prd.md, workflow-validate-prd.md

Some workflows have both a workflow.yaml and a separate instructions.md, while others put everything in a single workflow.md.

Impact: IDE integrations, the manifest generator, and agent command generators all need to handle multiple formats. Contributors don't know which format to use when adding workflows.

Recommendation: Document the rationale (e.g., .yaml for machine-parseable configs with input_file_patterns, .md for pure instructional workflows). Consider standardizing on .yaml as the entry point with .md for instructions only.

6. MEDIUM: Missing Data Files Referenced by Agents RESOLVED

Status: Fixed as part of item #1. The uat-automation-patterns.yaml reference and the uat-report menu entry were removed from uat-validator.agent.yaml since neither resource existed anywhere in the repo.

7. MEDIUM: No Example Project or Post-Install Scaffold PARTIALLY RESOLVED

Status: Documentation improvements applied. Installer code enhancements remain as a future improvement.

What was done:

  • README.md — Improved the post-install section to explain what folders were created (_bmad/, _bmad-output/) and direct users to /bmad-help
  • Getting Started tutorial — Fixed the project folder tree to show the actual subfolder structure (planning-artifacts/, implementation-artifacts/, docs/) instead of a flat layout. Added a "How do I verify my installation?" FAQ entry

Remaining (future enhancements):

  • Generate a _bmad-output/GETTING-STARTED.md at install time with module-specific next steps
  • Enhance installer renderInstallSummary() with module-aware guidance
  • Add sample PRD, architecture, and project-context outputs to the docs site
  • Enhance bmad status to show project phase and recommend next workflow

8. MEDIUM: Test Suite Doesn't Use a Standard Test Runner

Tests in test/ use raw node:assert and node:test with custom scripts rather than a standard test framework. While Jest is in devDependencies, the actual tests don't use it. The test runner is bare node test/test-agent-schema.js.

Impact for contributors: No test watch mode, no standard patterns for adding tests, no IDE test integration. The Jest dependency appears unused.

Recommendation: Either migrate to Jest (since it's already a dependency) or remove Jest and document the node:test approach. Either way, add test watch capabilities for contributor DX.

9. MEDIUM: src/utility/agent-components/ Is Undocumented

The src/utility/ directory contains shared agent components but isn't mentioned in the README, CLAUDE.md, or CONTRIBUTING.md. Its relationship to the module system is unclear.

Recommendation: Document this directory's purpose and how components are shared across modules.

10. LOW: CONTRIBUTING.md References Non-Existent Scripts

The contribution workflow likely references npm run validate:refs which doesn't exist as a standalone script in package.json. The actual ref validation is test:refs (which runs test-file-refs-csv.js).

Recommendation: Audit CONTRIBUTING.md to ensure all referenced commands exist.

11. LOW: Workflow Phase Numbering Gap RESOLVED

Status: Fixed as part of item #1. Phase 5 (5-validation/uat-validate/) has been moved into src/bmm/workflows/, completing the phase 1-5 progression in the main module.

Summary: Top 5 Actionable Improvements

Priority Enhancement User Impact
1 Consolidate src/bmm/ and src/modules/bmm/ RESOLVED
2 Add file reference validation to CI pipeline RESOLVED
3 Document and scaffold project-context.md in onboarding flow RESOLVED
4 Standardize artifact folder strategy with clear commit guidance RESOLVED
5 Add post-install guidance with example outputs PARTIALLY RESOLVED (docs improved; installer enhancements remain)