ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: cleaned up bad architecture file calls, legacy doc references, and case sensitivity issues to remove ambiguity (#718)

Browse Source
This commit is contained in:
PinkyD
2025-10-10 07:26:49 -07:00
committed by GitHub
parent 5977227efc
commit d76bcb5586
18 changed files with 59 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/modules/bmm/_module-installer/assets/technical-decisions-template.md
View File

@@ -4,7 +4,7 @@ _Auto-updated during discovery and planning sessions - you can also add informat
## Purpose
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for solution-architecture.md and solution design documents.
## Confirmed Decisions
@@ -26,5 +26,5 @@ This document captures technical decisions, preferences, and constraints discove
- This file is automatically updated when technical information is mentioned
- Decisions here are inputs, not final architecture
- Final technical decisions belong in architecture.md
- Final technical decisions belong in solution-architecture.md
- Implementation details belong in solutions/\*.md and story context or dev notes.

4
src/modules/bmm/agents/dev.agent.yaml
View File

@@ -10,10 +10,10 @@ agent:
persona:
role: Senior Implementation Engineer
identity: Executes approved stories with strict adherence to acceptance criteria, using the Story Context JSON and existing code to minimize rework and hallucinations.
identity: Executes approved stories with strict adherence to acceptance criteria, using the Story Context XML and existing code to minimize rework and hallucinations.
communication_style: Succinct, checklist-driven, cites paths and AC IDs; asks only when inputs are missing or ambiguous.
principles:
- I treat the Story Context JSON as the single source of truth, trusting it over any training priors while refusing to invent solutions when information is missing.
- I treat the Story Context XML as the single source of truth, trusting it over any training priors while refusing to invent solutions when information is missing.
- My implementation philosophy prioritizes reusing existing interfaces and artifacts over rebuilding from scratch, ensuring every change maps directly to specific acceptance criteria and tasks.
- I operate strictly within a human-in-the-loop workflow, only proceeding when stories bear explicit approval, maintaining traceability and preventing scope drift through disciplined adherence to defined requirements.

2
src/modules/bmm/agents/sm.agent.yaml
View File

@@ -18,7 +18,7 @@ agent:
- I never cross into implementation territory, focusing entirely on creating developer-ready specifications that eliminate ambiguity and enable efficient sprint execution.
critical_actions:
- "When running *create-story, run non-interactively: use HLA, PRD, Tech Spec, and epics to generate a complete draft without elicitation."
- "When running *create-story, run non-interactively: use solution-architecture, PRD, Tech Spec, and epics to generate a complete draft without elicitation."
menu:
- trigger: correct-course

2
src/modules/bmm/workflows/1-analysis/research/README.md
View File

@@ -104,7 +104,7 @@ workflow research --type domain
```bash
workflow research --type market --input product-brief.md --input competitor-list.md
workflow research --type technical --input requirements.md --input architecture.md
workflow research --type technical --input requirements.md --input solution-architecture.md
workflow research --type deep_prompt --input research-question.md
```

8
src/modules/bmm/workflows/2-plan/prd/instructions-lg.md
View File

@@ -189,7 +189,7 @@ Since this is a Level {{project_level}} project, you need architecture before st
- Run `architecture` workflow
- Consider reference architectures
- Generate solution fragments
- Create architecture.md
- Create solution-architecture.md
## Complete Next Steps Checklist
@@ -200,18 +200,18 @@ Since this is a Level {{project_level}} project, you need architecture before st
- [ ] **Run architecture workflow** (REQUIRED)
- Command: `workflow architecture`
- Input: PRD.md, epics.md
- Output: architecture.md
- Output: solution-architecture.md
<check if="project has significant UX/UI components (Level 3-4 typically does)">
- [ ] **Run UX specification workflow** (HIGHLY RECOMMENDED for user-facing systems) - Command: `workflow plan-project` then select "UX specification" - Or continue within this workflow if UI-heavy - Input: PRD.md, epics.md, architecture.md (once available) - Output: ux-specification.md - Optional: AI Frontend Prompt for rapid prototyping - Note: Creates comprehensive UX/UI spec including IA, user flows, components
- [ ] **Run UX specification workflow** (HIGHLY RECOMMENDED for user-facing systems) - Command: `workflow plan-project` then select "UX specification" - Or continue within this workflow if UI-heavy - Input: PRD.md, epics.md, solution-architecture.md (once available) - Output: ux-specification.md - Optional: AI Frontend Prompt for rapid prototyping - Note: Creates comprehensive UX/UI spec including IA, user flows, components
</check>
### Phase 2: Detailed Planning
- [ ] **Generate detailed user stories**
- Command: `workflow generate-stories`
- Input: epics.md + architecture.md
- Input: epics.md + solution-architecture.md
- Output: user-stories.md with full acceptance criteria
- [ ] **Create technical design documents**

2
src/modules/bmm/workflows/2-plan/ux/instructions-ux.md
View File

@@ -37,7 +37,7 @@ If no: We'll gather basic requirements to create the UX spec
- PRD.md (primary source for requirements and user journeys)
- epics.md or epic-stories.md (helps understand feature grouping)
- tech-spec.md (understand technical constraints)
- architecture.md (if Level 3-4 project)
- solution-architecture.md (if Level 3-4 project)
- project-workflow-analysis.md (understand project level and scope)
</check>

12
src/modules/bmm/workflows/3-solutioning/checklist.md
View File

@@ -53,7 +53,7 @@ Use this checklist during workflow execution and review.
- [ ] Template sections determined dynamically
- [ ] User approved section list
- [ ] architecture.md generated with ALL sections
- [ ] solution-architecture.md generated with ALL sections
- [ ] Technology and Library Decision Table included with specific versions
- [ ] Proposed Source Tree included
- [ ] Design-level only (no extensive code)
@@ -76,7 +76,7 @@ Use this checklist during workflow execution and review.
- [ ] DevOps assessed (simple inline or complex placeholder)
- [ ] Security assessed (simple inline or complex placeholder)
- [ ] Testing assessed (simple inline or complex placeholder)
- [ ] Specialist sections added to END of architecture.md
- [ ] Specialist sections added to END of solution-architecture.md
### Step 8: PRD Updates (Optional)
@@ -105,7 +105,7 @@ Use this checklist during workflow execution and review.
### Technology and Library Decision Table
- [ ] Table exists in architecture.md
- [ ] Table exists in solution-architecture.md
- [ ] ALL technologies have specific versions (e.g., "pino 8.17.0")
- [ ] NO vague entries ("a logging library", "appropriate caching")
- [ ] NO multi-option entries without decision ("Pino or Winston")
@@ -113,7 +113,7 @@ Use this checklist during workflow execution and review.
### Proposed Source Tree
- [ ] Section exists in architecture.md
- [ ] Section exists in solution-architecture.md
- [ ] Complete directory structure shown
- [ ] For polyrepo: ALL repo structures included
- [ ] Matches technology stack conventions
@@ -137,7 +137,7 @@ Use this checklist during workflow execution and review.
### Required Files
- [ ] /docs/architecture.md (or solution-architecture.md)
- [ ] /docs/solution-architecture.md (or architecture.md)
- [ ] /docs/cohesion-check-report.md
- [ ] /docs/epic-alignment-matrix.md
- [ ] /docs/tech-spec-epic-1.md
@@ -153,7 +153,7 @@ Use this checklist during workflow execution and review.
### Updated Files
- [ ] analysis-template.md (workflow status updated)
- [ ] prd.md (if architectural discoveries required updates)
- [ ] PRD.md (if architectural discoveries required updates)
## Next Steps After Workflow

18
src/modules/bmm/workflows/3-solutioning/instructions.md
View File

@@ -368,7 +368,7 @@ Sub-step 6.2: Fill Template Placeholders
- Ask user for any missing information
- Generate appropriate content based on user_skill_level
8. Generate final architecture.md document
8. Generate final solution-architecture.md document
CRITICAL REQUIREMENTS:
- MUST include "Technology and Library Decisions" section with table:
@@ -438,7 +438,7 @@ Run cohesion check validation inline (NO separate workflow for now):
5. Generate Epic Alignment Matrix:
| Epic | Stories | Components | Data Models | APIs | Integration Points | Status |
This matrix is SEPARATE OUTPUT (not in architecture.md)
This matrix is SEPARATE OUTPUT (not in solution-architecture.md)
6. Generate Cohesion Check Report with:
- Executive summary (READY vs GAPS)
@@ -464,7 +464,7 @@ Issues found:
{{list_critical_issues}}
Options:
1. I'll fix these issues now (update architecture.md)
1. I'll fix these issues now (update solution-architecture.md)
2. You'll fix them manually
3. Proceed anyway (not recommended)
@@ -478,7 +478,7 @@ Proceed? (y/n)
</ask>
<action if="user_chooses_option_1">
Update architecture.md to address critical issues, then re-validate.
Update solution-architecture.md to address critical issues, then re-validate.
</action>
</step>
@@ -498,7 +498,7 @@ Testing Assessment:
- Simple: Basic unit + E2E → Handle INLINE
- Complex: Mission-critical UI, comprehensive coverage needed → Create PLACEHOLDER
For INLINE: Add 1-3 paragraph sections to architecture.md
For INLINE: Add 1-3 paragraph sections to solution-architecture.md
For PLACEHOLDER: Add handoff section with specialist agent invocation instructions
</action>
@@ -522,7 +522,7 @@ I'll handle {{specialist_area}} inline with essentials.
</ask>
<action>
Update architecture.md with specialist sections (inline or placeholders) at the END of document.
Update solution-architecture.md with specialist sections (inline or placeholders) at the END of document.
</action>
<template-output>specialist_sections</template-output>
@@ -598,12 +598,12 @@ For polyrepo projects:
Example: frontend-repo, api-repo, worker-repo, mobile-repo
2. Strategy: Copy FULL documentation to ALL repos
- architecture.md → Copy to each repo
- solution-architecture.md → Copy to each repo
- tech-spec-epic-X.md → Copy to each repo (full set)
- cohesion-check-report.md → Copy to each repo
3. Add repo-specific README pointing to docs:
"See /docs/architecture.md for complete solution architecture"
"See /docs/solution-architecture.md for complete solution architecture"
4. Later phases extract per-epic and per-story contexts as needed
@@ -621,7 +621,7 @@ For monorepo projects:
<action>
Final validation checklist:
- [x] architecture.md exists and is complete
- [x] solution-architecture.md exists and is complete
- [x] Technology and Library Decision Table has specific versions
- [x] Proposed Source Tree section included
- [x] Cohesion check passed (or issues addressed)

10
src/modules/bmm/workflows/3-solutioning/tech-spec/README.md
View File

@@ -25,17 +25,17 @@ workflow tech-spec
```bash
# With specific PRD and architecture
workflow tech-spec --input prd.md --input architecture.md
workflow tech-spec --input PRD.md --input solution-architecture.md
# With comprehensive inputs
workflow tech-spec --input prd.md --input architecture.md --input front-end-spec.md
workflow tech-spec --input PRD.md --input solution-architecture.md --input front-end-spec.md
```
### Configuration
- **output_folder**: Location for generated technical specification
- **epic_id**: Used in output filename (extracted from PRD or prompted)
- **recommended_inputs**: PRD, architecture, front-end spec, brownfield notes
- **recommended_inputs**: PRD, solution-architecture, front-end spec, brownfield notes
## Workflow Structure
@@ -104,7 +104,7 @@ tech-spec/
### Output Structure
1. **Overview and Scope** - Project context and boundaries
2. **System Architecture Alignment** - Connection to high-level architecture
2. **System Architecture Alignment** - Connection to solution-architecture
3. **Detailed Design** - Services, data models, APIs, and workflows
4. **Non-Functional Requirements** - Performance, security, reliability, observability
5. **Dependencies and Integrations** - External systems and technical dependencies
@@ -116,7 +116,7 @@ tech-spec/
## Requirements
- **PRD Document**: Product Requirements Document with clear acceptance criteria
- **Architecture Document**: High-level architecture or technical design
- **Architecture Document**: solution-architecture or technical design
- **Repository Access**: For dependency analysis and framework detection
- **Epic Context**: Clear epic identification and scope definition

4
src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml
View File

@@ -11,8 +11,8 @@ date: system-generated
# Inputs expected (ask user if missing)
recommended_inputs:
- prd: "{project-root}/docs/prd.md"
- architecture: "{project-root}/docs/architecture.md"
- prd: "{project-root}/docs/PRD.md"
- architecture: "{project-root}/docs/solution-architecture.md"
- frontend_spec: "{project-root}/docs/front-end-spec.md"
- brownfield_notes: "{project-root}/docs/brownfield-notes.md"

2
src/modules/bmm/workflows/4-implementation/create-story/checklist.md
View File

@@ -4,7 +4,7 @@ validation-target: 'Newly generated story markdown file'
required-inputs:
- 'epics.md (preferred) or PRD'
optional-inputs:
- 'HLA document for architecture context'
- 'solution-architecture document for architecture context'
validation-rules:
- 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
- 'Dev Notes include Project Structure Notes and References subsections'

6
src/modules/bmm/workflows/4-implementation/create-story/instructions.md
View File

@@ -12,7 +12,7 @@
<action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
<action>Create {{story_dir}} if it does not exist</action>
<action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
<action>Resolve recommended inputs if present: epics_file, prd_file, hla_file</action>
<action>Resolve recommended inputs if present: epics_file, prd_file, solution-architecture_file</action>
</step>
<step n="2" goal="Discover and load source documents">
@@ -21,7 +21,7 @@
1) tech_spec_file (epic-scoped)
2) epics_file (acceptance criteria and breakdown)
3) prd_file (business requirements and constraints)
4) hla_file (architecture constraints)
4) solution-architecture_file (architecture constraints)
5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
</action>
<action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
@@ -42,7 +42,7 @@
<step n="4" goal="Extract requirements and derive story statement">
<action>From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story.</action>
<action>From hla and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
<action>From solution-architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
<action>Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts.</action>
<template-output file="{default_output_file}">requirements_context_summary</template-output>
</step>

2
src/modules/bmm/workflows/4-implementation/create-story/template.md
View File

@@ -38,7 +38,7 @@ so that {{benefit}}.
### Context Reference
<!-- Path(s) to story context XML/JSON will be added here by context workflow -->
<!-- Path(s) to story context XML will be added here by context workflow -->
### Agent Model Used

24
src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
View File

@@ -19,8 +19,8 @@ validation: "{installed_path}/checklist.md"
variables:
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
prd_file: "{output_folder}/prd.md" # Fallback for requirements
hla_file: "{output_folder}/high-level-architecture.md" # Optional architecture context
prd_file: "{output_folder}/PRD.md" # Fallback for requirements
solution-architecture_file: "{output_folder}/solution-architecture.md" # Optional architecture context
tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
tech_spec_search_dir: "{project-root}/docs"
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
@@ -28,16 +28,8 @@ variables:
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
- solution-architecture.md
- infrastructure-architecture.md
story_title: "" # Will be elicited if not derivable
epic_num: 1
story_num: 1
@@ -57,9 +49,9 @@ required_tools:
- glob
recommended_inputs:
- epics: "Epic breakdown (epic-list.md)"
- epics: "Epic breakdown (epics.md)"
- prd: "PRD document"
- hla: "High-Level Architecture (optional)"
- solution-architecture: "Solution Architecture (optional)"
tags:
- story-generation
@@ -67,8 +59,8 @@ tags:
- bmad-v6
execution_hints:
interactive: false
autonomous: true
interactive: false # Minimize prompts; intended to run to completion
autonomous: true # Proceed without user input unless blocked
iterative: true
web_bundle: false

4
src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
View File

@@ -24,8 +24,8 @@ variables:
strict: true # if true, halt on validation failures
story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
story_selection_limit: 10
run_until_complete: true # Continue through all tasks without pausing except on HALT conditions
force_yolo: true # Hint executor to activate #yolo: skip optional prompts and elicitation
run_until_complete: false # Continue through all tasks without pausing except on HALT conditions
force_yolo: false # Hint executor to activate #yolo: skip optional prompts and elicitation
# Recommended inputs
recommended_inputs:

21
src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
View File

@@ -34,24 +34,11 @@ variables:
- "{project-root}/docs"
- "{output_folder}"
arch_docs_file_names: |
- prd.md
- epics.md
- high-level-architecture.md
- tech-stack.md
- unified-project-structure.md
- coding-standards.md
- testing-strategy.md
- security-guidelines.md
- backend-architecture.md
- frontend-architecture.md
- data-models.md
- database-schema.md
- rest-api-spec.md
- external-apis.md
- solution-architecture.md
enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
enable_web_fallback: true # Fallback to web search/read-url if MCP not available
update_status_on_result: false # If true, update story Status based on review outcome
status_on_approve: "Done"
update_status_on_result: true # If true, update story Status based on review outcome
status_on_approve: "Review Passed"
status_on_changes_requested: "InProgress"
# Persistence controls for review action items and notes
persist_action_items: true
@@ -71,7 +58,7 @@ variables:
recommended_inputs:
- story_markdown: "Path to the story markdown file flagged Ready for Review"
- tech_spec: "Epic technical specification document (auto-discovered if omitted)"
- story_context: "Story Context XML/JSON path (auto-discovered if omitted)"
- story_context: "Story Context XML path (auto-discovered if omitted)"
# Required tools (conceptual; executor should provide equivalents)
required_tools:

2
src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
View File

@@ -27,7 +27,7 @@ variables:
non_interactive: true
# Output configuration
default_output_file: "{output_folder}/story-context-{{epic_id}}.{{story_id}}.xml"
default_output_file: "{story_dir}/story-context-{{epic_id}}.{{story_id}}.xml"
# Recommended inputs
recommended_inputs:

12
src/modules/bmm/workflows/README.md
View File

@@ -43,7 +43,7 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
│ PHASE 3: SOLUTIONING │
│ (Levels 3-4 Only) │
├──────────────────────────────────────────────────────────────┤
│ 3-solutioning ──→ Architecture.md │
│ 3-solutioning ──→ solution-architecture.md │
│ ↓ │
│ tech-spec (per epic, JIT during implementation) │
└────────────────────────────────────────────────────────────┬─┘
@@ -126,10 +126,10 @@ Architecture and technical design phase for complex projects.
### Workflows
| Workflow | Owner | Purpose | Output | Timing |
| ----------------- | --------- | ------------------------------ | ------------------------- | ----------------- |
| **3-solutioning** | Architect | Create overall architecture | Architecture.md with ADRs | Once per project |
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT |
| Workflow | Owner | Purpose | Output | Timing |
| ----------------- | --------- | ------------------------------ | ---------------------------------- | ----------------- |
| **3-solutioning** | Architect | Create overall architecture | solution-architecture.md with ADRs | Once per project |
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT |
### Just-In-Time Tech Specs
@@ -258,7 +258,7 @@ plan-project (Phase 2)
- **Phase 1**: Briefs and research documents
- **Phase 2**: PRD, Epics, or tech-spec based on level
- **Phase 3**: Architecture.md, epic-specific tech specs
- **Phase 3**: solution-architecture.md, epic-specific tech specs
- **Phase 4**: Story files, context XMLs, implemented code
## Best Practices