158 lines
8.8 KiB
Markdown
158 lines
8.8 KiB
Markdown
# 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) |
|