169 lines
8.8 KiB
Markdown
169 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
|
|
|
|
Every Phase 4 implementation workflow declares:
|
|
|
|
```yaml
|
|
project_context: "**/project-context.md"
|
|
```
|
|
|
|
But there's no clear documentation on what this file is, when to create it, or how. The `generate-project-context` workflow exists but:
|
|
|
|
- It's not mentioned in the Quick Start path in the README
|
|
- The Getting Started tutorial doesn't flag it as a prerequisite before Phase 4
|
|
- The Quick Flow path (`/quick-spec` → `/dev-story` → `/code-review`) doesn't mention it either
|
|
|
|
**Impact:** Developers hit Phase 4 workflows and get confusing results because the project context file doesn't exist yet.
|
|
|
|
**Recommendation:** Either auto-generate `project-context.md` during installation (even a minimal scaffold), or add a prominent step in the README's workflow paths and in the Quick Flow docs. Alternatively, make it optional in workflow configs with a graceful fallback.
|
|
|
|
---
|
|
|
|
## 4. HIGH: Artifact Storage Strategy Is Confusing
|
|
|
|
Three layers of configuration overlap:
|
|
|
|
- `core/module.yaml` defines `output_folder` (default: `_bmad-output`)
|
|
- `bmm/module.yaml` defines `planning_artifacts`, `implementation_artifacts`, `project_knowledge` (nested under output_folder)
|
|
- Individual workflows use different variable names (`{sprint_status}`, `{sprint_artifacts}`, `{output_folder}`)
|
|
- `.gitignore` ignores both `_bmad/` and `_bmad-output/`
|
|
|
|
**The confusion for real projects:**
|
|
|
|
1. Are artifacts meant to be version-controlled? The `.gitignore` says no, but `project_knowledge` defaults to `docs/` which *is* typically committed.
|
|
2. Some workflows reference `sprint_artifacts` which isn't defined in any `module.yaml` config.
|
|
3. A developer doesn't know where to look for generated PRDs, architecture docs, or sprint tracking files.
|
|
|
|
**Recommendation:**
|
|
|
|
- Add a clear section in the README or a post-install message explaining the folder structure and which folders to commit
|
|
- Standardize variable names across all workflows (audit `sprint_artifacts` vs `sprint_status`)
|
|
- Consider generating a `_bmad-output/README.md` during installation that explains the folder layout
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
After running `npx bmad-method install`, developers get agents and workflows but no example of what a successful project looks like. There's no:
|
|
|
|
- Example `project-context.md`
|
|
- Sample PRD or architecture doc showing expected output format
|
|
- Starter `.claude/commands/` or equivalent showing what commands were generated
|
|
- Post-install "what to do next" guide in the terminal
|
|
|
|
**Recommendation:** Consider adding:
|
|
|
|
- A `_bmad-output/GETTING-STARTED.md` generated at install time with next steps specific to the chosen modules/IDE
|
|
- Example outputs in the docs site showing what a completed PRD, architecture doc, or sprint plan looks like
|
|
- A `bmad status` CLI command that shows what phase the project is in and what the next recommended workflow is (the `status` command exists but appears minimal)
|
|
|
|
---
|
|
|
|
## 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 | Unblocks Phase 4 workflows for new users |
|
|
| **4** | Standardize artifact folder strategy with clear commit guidance | Developers understand where outputs go and what to version control |
|
|
| **5** | Add post-install guidance with example outputs | Reduces time-to-first-workflow from "confused" to "productive" |
|