bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md

@@ -3,21 +3,97 @@
 **Author:** {{user_name}}
 **Date:** {{date}}
 **Project Level:** {{project_level}}
-**Project Type:** {{project_type}}
+**Change Type:** {{change_type}}
 **Development Context:** {{development_context}}
 
 ---
 
-## Source Tree Structure
+## Context
 
-{{source_tree}}
+### Available Documents
+
+{{loaded_documents_summary}}
+
+### Project Stack
+
+{{project_stack_summary}}
+
+### Existing Codebase Structure
+
+{{existing_structure_summary}}
+
+---
+
+## The Change
+
+### Problem Statement
+
+{{problem_statement}}
+
+### Proposed Solution
+
+{{solution_overview}}
+
+### Scope
+
+**In Scope:**
+
+{{scope_in}}
+
+**Out of Scope:**
+
+{{scope_out}}
 
 ---
 
-## Technical Approach
+## Implementation Details
+
+### Source Tree Changes
+
+{{source_tree_changes}}
+
+### Technical Approach
 
 {{technical_approach}}
 
+### Existing Patterns to Follow
+
+{{existing_patterns}}
+
+### Integration Points
+
+{{integration_points}}
+
+---
+
+## Development Context
+
+### Relevant Existing Code
+
+{{existing_code_references}}
+
+### Dependencies
+
+**Framework/Libraries:**
+
+{{framework_dependencies}}
+
+**Internal Modules:**
+
+{{internal_dependencies}}
+
+### Configuration Changes
+
+{{configuration_changes}}
+
+### Existing Conventions (Brownfield)
+
+{{existing_conventions}}
+
+### Test Framework & Standards
+
+{{test_framework_info}}
+
 ---
 
 ## Implementation Stack
@@ -40,7 +116,47 @@
 
 ## Implementation Guide
 
-{{implementation_guide}}
+### Setup Steps
+
+{{setup_steps}}
+
+### Implementation Steps
+
+{{implementation_steps}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+### Acceptance Criteria
+
+{{acceptance_criteria}}
+
+---
+
+## Developer Resources
+
+### File Paths Reference
+
+{{file_paths_complete}}
+
+### Key Code Locations
+
+{{key_code_locations}}
+
+### Testing Locations
+
+{{testing_locations}}
+
+### Documentation to Update
+
+{{documentation_updates}}
+
+---
+
+## UX/UI Considerations
+
+{{ux_ui_considerations}}
 
 ---
 
@@ -52,4 +168,14 @@
 
 ## Deployment Strategy
 
-{{deployment_strategy}}
+### Deployment Steps
+
+{{deployment_steps}}
+
+### Rollback Plan
+
+{{rollback_plan}}
+
+### Monitoring
+
+{{monitoring_approach}}

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md

@@ -22,22 +22,43 @@ so that {{benefit}}.
 
 {{technical_summary}}
 
+### Tech-Spec Reference
+
+**Full details:** See [tech-spec.md](../tech-spec.md)
+
+The tech-spec contains comprehensive context including:
+
+- Brownfield codebase analysis (if applicable)
+- Framework and library details with versions
+- Existing patterns to follow
+- Integration points and dependencies
+- Complete implementation guidance
+
 ### Project Structure Notes
 
-- Files to modify: {{files_to_modify}}
-- Expected test locations: {{test_locations}}
-- Estimated effort: {{story_points}} story points ({{time_estimate}})
+- **Files to modify:** {{files_to_modify}}
+- **Expected test locations:** {{test_locations}}
+- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
+- **Dependencies:** {{dependencies}}
+
+### Key Code References
+
+{{existing_code_references}}
 
 ### References
 
-- **Tech Spec:** See tech-spec.md for detailed implementation
+- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
 - **Architecture:** {{architecture_references}}
 
+---
+
 ## Dev Agent Record
 
 ### Context Reference
 
-<!-- Path(s) to story context XML will be added here by context workflow -->
+**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
+
+<!-- Additional context XML paths will be added here if story-context workflow is run -->
 
 ### Agent Model Used
 
@@ -54,3 +75,13 @@ so that {{benefit}}.
 ### File List
 
 <!-- Will be populated during dev-story execution -->
+
+### Test Results
+
+<!-- Will be populated during dev-story execution -->
+
+---
+
+## Review Notes
+
+<!-- Will be populated during code review -->

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml

@@ -13,6 +13,13 @@ document_output_language: "{config_source}:document_output_language"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 
+# Runtime variables (captured during workflow execution)
+project_level: runtime-captured
+project_type: runtime-captured
+development_context: runtime-captured
+change_type: runtime-captured
+field_type: runtime-captured
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
 instructions: "{installed_path}/instructions.md"
@@ -36,6 +43,20 @@ recommended_inputs:
   - bug_report: "Bug description or issue ticket"
   - feature_request: "Brief feature description"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:

package/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -1,4 +1,4 @@
-# Decision Architecture
+# Architecture
 
 ## Executive Summary
 

package/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -10,63 +10,74 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow replaces architecture with a conversation-driven approach</critical>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+## 📚 Input Document Discovery
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
+This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation.
 
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
+**Discovery Process** (execute for each referenced document):
 
-The Decision Architecture workflow can run standalone or as part of the BMM workflow path.
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
 
-**Recommended:** Run `workflow-init` first for:
+**Priority**: If both whole and sharded versions exist, use the whole document.
 
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
 
-**Or continue standalone** without progress tracking.
-</output>
-<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
-<check if="continue">
-<action>Set standalone_mode = true</action>
-</check>
-<check if="exit">
-<action>Exit workflow</action>
-</check>
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
+
+<check if="status file not found">
+  <output>No workflow status file found. Decision Architecture can run standalone or as part of BMM workflow path.</output>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
+  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
+  <check if="continue">
+    <action>Set standalone_mode = true</action>
+  </check>
+  <check if="exit">
+    <action>Exit workflow</action>
+  </check>
 </check>
 
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "create-architecture" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 3">
     <output>**Note: Level {{project_level}} Project**
 
-Decision Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
+The Detailed Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
 
 For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 </output>
 </check>
-</check>
-</step>
-
-<step n="0.5" goal="Validate workflow sequencing">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: validate</param>
-  <param>calling_workflow: architecture</param>
-</invoke-workflow>
+  <check if="create-architecture status is file path (already completed)">
+    <output>⚠️ Architecture already completed: {{create-architecture status}}</output>
+    <ask>Re-running will overwrite the existing architecture. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-<check if="warning != ''">
-  <output>{{warning}}</output>
-  <ask>Continue with Decision Architecture anyway? (y/n)</ask>
-  <check if="n">
-    <output>{{suggestion}}</output>
-    <action>Exit workflow</action>
+  <check if="create-architecture is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Architecture is out of sequence.</output>
+    <ask>Continue with Architecture anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
   </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 
 <action>Check for existing PRD and epics files using fuzzy matching</action>
@@ -77,11 +88,11 @@ For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 
 Decision Architecture works from your Product Requirements Document (PRD).
 
-Looking for: bmm-PRD.md, PRD.md, or product-requirements.md in {output_folder}
+Looking for: _PRD_, PRD.md, or prd/index.md + files in {output_folder}
 
 Please run the PRD workflow first to define your requirements.
 
-Run: `workflow prd`
+Architect: `create-prd`
 </output>
 <action>Exit workflow - PRD required</action>
 </check>
@@ -89,7 +100,7 @@ Run: `workflow prd`
 </step>
 
 <step n="1" goal="Load and understand project context">
-  <action>Load the PRD using fuzzy matching: {prd_file}</action>
+  <action>Load the PRD using fuzzy matching: {prd_file}, if the PRD is mulitple files in a folder, load the index file and all files associated with the PRD</action>
   <action>Load epics file using fuzzy matching: {epics_file}</action>
 
 <action>Check for UX specification using fuzzy matching:
@@ -103,7 +114,7 @@ Run: `workflow prd`
 <action>Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned
 </action>
 
-<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists)
+<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features
 </action>
 
 <action>Reflect understanding back to {user_name}:
@@ -142,8 +153,8 @@ I see {{epic_count}} epics with {{story_count}} total stories.
     </action>
   </check>
 
-<action>Search for relevant starter templates:
-<WebSearch>{{primary_technology}} starter template CLI create command latest 2024</WebSearch>
+<action>Search for relevant starter templates with websearch, examples:
+<WebSearch>{{primary_technology}} starter template CLI create command latest {date}</WebSearch>
 <WebSearch>{{primary_technology}} boilerplate generator latest options</WebSearch>
 </action>
 
@@ -213,7 +224,7 @@ I see {{epic_count}} epics with {{story_count}} total stories.
 
   <check if="no_starter_found_or_applicable">
     <action>Note: No standard starter template found for this project type.
-            Will need to make all architectural decisions explicitly.</action>
+            We will make all architectural decisions explicitly.</action>
   </check>
 
 <template-output>starter_template_decision</template-output>
@@ -292,34 +303,39 @@ Let's work through the remaining {{remaining_count}} decisions."
 <action>Present the decision based on mode:
 <check if="mode == 'EXPERT'">
 "{{Decision_Category}}: {{Specific_Decision}}
-Options: {{concise_option_list_with_tradeoffs}}
-Recommendation: {{recommendation}} for {{reason}}"
-</check>
 
-    <check if="mode == 'INTERMEDIATE'">
-      "Next decision: {{Human_Friendly_Category}}
+    Options: {{concise_option_list_with_tradeoffs}}
 
-       We need to choose {{Specific_Decision}}.
+    Recommendation: {{recommendation}} for {{reason}}"
 
-       Common options:
-       {{option_list_with_brief_explanations}}
+  </check>
 
-       For your project, {{recommendation}} would work well because {{reason}}."
-    </check>
+  <check if="mode == 'INTERMEDIATE'">
+    "Next decision: {{Human_Friendly_Category}}
 
-    <check if="mode == 'BEGINNER'">
-      "Let's talk about {{Human_Friendly_Category}}.
+      We need to choose {{Specific_Decision}}.
+
+      Common options:
+      {{option_list_with_brief_explanations}}
 
-       {{Educational_Context_About_Why_This_Matters}}
+      For your project, {{recommendation}} would work well because {{reason}}."
 
-       Think of it like {{real_world_analogy}}.
+  </check>
 
-       Your main options:
-       {{friendly_options_with_pros_cons}}
+  <check if="mode == 'BEGINNER'">
+    "Let's talk about {{Human_Friendly_Category}}.
 
-       My suggestion: {{recommendation}}
-       This is good for you because {{beginner_friendly_reason}}."
-    </check>
+      {{Educational_Context_About_Why_This_Matters}}
+
+      Think of it like {{real_world_analogy}}.
+
+      Your main options:
+      {{friendly_options_with_pros_cons}}
+
+      My suggestion: {{recommendation}}
+      This is good for you because {{beginner_friendly_reason}}."
+
+  </check>
 
   </action>
 
@@ -372,11 +388,7 @@ Provided by Starter: {{yes_if_from_starter}}
 </action>
 
   <check if="{user_skill_level} == 'beginner'">
-    <action>Explain why these matter:
-      "These are rules that EVERY part of your app must follow.
-       If we don't decide now, each AI agent will do it differently,
-       and your app won't work properly when the pieces come together."
-    </action>
+    <action>Explain why these matter why its critical to go through and decide these things now.</action>
   </check>
 
 <template-output>cross_cutting_decisions</template-output>
@@ -663,20 +675,20 @@ Enforcement: "All agents MUST follow this pattern"
 
 <action>Save document to {output_folder}/architecture.md</action>
 
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: architecture</param>
-  </invoke-workflow>
+  <check if="standalone_mode != true">
+    <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+    <action>Find workflow_status key "create-architecture"</action>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+    <action>Update workflow_status["create-architecture"] = "{output_folder}/bmm-architecture-{{date}}.md"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
-    <output>✅ Decision Architecture workflow complete!
-
-Status updated.
-</output>
+    <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+    <action>Determine next agent from path file based on next workflow</action>
 
   </check>
 
+<output>✅ Decision Architecture workflow complete!</output>
+
 <output>**Deliverables Created:**
 
 - ✅ architecture.md - Complete architectural decisions document

package/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml

@@ -18,10 +18,23 @@ recommended_inputs:
   - epics: "Epic definitions with user stories and acceptance criteria"
   - ux_spec: "UX specification with interface designs and interaction patterns (optional)"
 
-# Input file references (fuzzy matched from output folder)
-prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
-epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md"
-ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md"
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
 
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture"