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

pbean · web-flow · commit d76bcb5586fb · 2025-10-10T09:26:49.000-05:00
diff --git a/src/modules/bmm/_module-installer/assets/technical-decisions-template.md b/src/modules/bmm/_module-installer/assets/technical-decisions-template.md
@@ -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.
diff --git a/src/modules/bmm/agents/dev.agent.yaml b/src/modules/bmm/agents/dev.agent.yaml
@@ -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.
 
diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml
@@ -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
diff --git a/src/modules/bmm/workflows/1-analysis/research/README.md b/src/modules/bmm/workflows/1-analysis/research/README.md
@@ -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
 ```
 
diff --git a/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md b/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md
@@ -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**
diff --git a/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md b/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md
@@ -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>
diff --git a/src/modules/bmm/workflows/3-solutioning/checklist.md b/src/modules/bmm/workflows/3-solutioning/checklist.md
@@ -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,15 +105,15 @@ 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")
 - [ ] Grouped logically (core stack, libraries, devops)
 
 ### 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
 
diff --git a/src/modules/bmm/workflows/3-solutioning/instructions.md b/src/modules/bmm/workflows/3-solutioning/instructions.md
@@ -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)
diff --git a/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md b/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md
@@ -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
 
diff --git a/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml
@@ -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"
 
diff --git a/src/modules/bmm/workflows/4-implementation/create-story/checklist.md b/src/modules/bmm/workflows/4-implementation/create-story/checklist.md
@@ -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'
diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
@@ -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>
diff --git a/src/modules/bmm/workflows/4-implementation/create-story/template.md b/src/modules/bmm/workflows/4-implementation/create-story/template.md
@@ -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
 
diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
@@ -19,25 +19,17 @@ 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"
   arch_docs_search_dirs: |
     - "{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,18 +49,18 @@ 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
   - planning
   - 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
diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
@@ -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:
diff --git a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
diff --git a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md
