bmad-method 6.0.0-alpha.11 → 6.0.0-alpha.13

package/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md

@@ -0,0 +1,194 @@
+# Step 1: Architecture Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## YOUR TASK:
+
+Initialize the Architecture workflow by detecting continuation state, discovering input documents, and setting up the document for collaborative architectural decision making.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/architecture.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery:
+
+**PRD Document (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check analysis folder: `{output_folder}/*prd*.md`
+2. If no main files: Check for sharded PRD folder: `{output_folder}/*prd*/**/*.md`
+3. If sharded folder exists: Load EVERY file in that folder completely
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Epics/Stories Document (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check analysis folder: `{output_folder}/analysis/*epic*.md`
+2. If no analysis files: Try main folder: `{output_folder}/*epic*.md`
+3. If no main files: Check for sharded epics folder: `{output_folder}/*epic*/**/*.md`
+4. If sharded folder exists: Load EVERY file in that folder completely
+5. Add discovered files to `inputDocuments` frontmatter
+
+**UX Design Specification (Priority: Analysis → Main → Sharded → Whole):**
+
+1. Check folder: `{output_folder}/*ux*.md`
+2. If no main files: Check for sharded UX folder: `{output_folder}/*ux*/**/*.md`
+3. If sharded folder exists: Load EVERY file in that folder completely
+4. Add discovered files to `inputDocuments` frontmatter
+
+**Research Documents (Priority: Analysis → Main):**
+
+1. Check folder: `{output_folder}/research/*research*.md`
+2. If no files: Try folder: `{output_folder}/*research*.md`
+3. Add discovered files to `inputDocuments` frontmatter
+
+**Project Documentation (Existing Projects):**
+
+1. Look for index file: `{output_folder/index.md`
+2. CRITICAL: Load index.md to understand what project files are available
+3. Read available files from index to understand existing project context
+4. This provides essential context for extending existing project with new architecture
+5. Add discovered files to `inputDocuments` frontmatter
+
+**Project Context Rules (Critical for AI Agents):**
+
+1. Check for project context file: `**/project_context.md`
+2. If exists: Load COMPLETE file contents - this contains critical rules for AI agents
+3. Add to frontmatter `hasProjectContext: true` and track file path
+4. Report to user: "Found existing project context with {number_of_rules} agent rules"
+5. This file contains language-specific patterns, testing rules, and implementation guidelines that must be followed
+
+**Loading Rules:**
+
+- Load ALL discovered files completely (no offset/limit)
+- For sharded folders, load ALL files to get complete picture
+- For existing projects, use index.md as guide to what's relevant
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Validate Required Inputs
+
+Before proceeding, verify we have the essential inputs:
+
+**PRD Validation:**
+
+- If no PRD found: "Architecture requires a PRD to work from. Please run the PRD workflow first or provide the PRD file path."
+- Do NOT proceed without PRD
+
+**Other Inputs:**
+
+- UX Spec: "Provides UI/UX architectural requirements" (Optional)
+
+#### C. Create Initial Document
+
+Copy the template from `{installed_path}/architecture-decision-template.md` to `{output_folder}/architecture.md`
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'architecture'
+lastStep: 0
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+```
+
+#### D. Complete Initialization and Report
+
+Complete setup and report to user:
+
+**Document Setup:**
+
+- Created: `{output_folder}/architecture.md` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+Report what was found:
+"Welcome {{user_name}}! I've set up your Architecture workspace for {{project_name}}.
+
+**Documents Found:**
+
+- PRD: {number of PRD files loaded or "None found - REQUIRED"}
+- Epics/Stories: {number of epic files loaded or "None found"}
+- UX Design: {number of UX files loaded or "None found"}
+- Research: {number of research files loaded or "None found"}
+- Project docs: {number of project files loaded or "None found"}
+- Project context: {project_context_rules count of rules for AI agents found}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Ready to begin architectural decision making. Do you have any other documents you'd like me to include?
+
+[C] Continue to project context analysis
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with template and frontmatter
+✅ Input documents discovered and loaded using sharded-first logic
+✅ All discovered files tracked in frontmatter `inputDocuments`
+✅ PRD requirement validated and communicated
+✅ User confirmed document setup and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when existing workflow exists
+❌ Not updating frontmatter with discovered input documents
+❌ Creating document without proper template
+❌ Not checking sharded folders first before whole files
+❌ Not reporting what documents were found to user
+❌ Proceeding without validating PRD requirement
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects [C] to continue, load `./step-02-context.md` to analyze the project context and begin architectural decision making.
+
+Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!

package/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01b-continue.md

@@ -0,0 +1,163 @@
+# Step 1b: Workflow Continuation Handler
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding current state and getting user confirmation
+- 🚪 HANDLE workflow resumption smoothly and transparently
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📖 Read existing document completely to understand current state
+- 💾 Update frontmatter to reflect continuation
+- 🚫 FORBIDDEN to proceed to next step without user confirmation
+
+## CONTEXT BOUNDARIES:
+
+- Existing document and frontmatter are available
+- Input documents already loaded should be in frontmatter `inputDocuments`
+- Steps already completed are in `stepsCompleted` array
+- Focus on understanding where we left off
+
+## YOUR TASK:
+
+Handle workflow continuation by analyzing existing work and guiding the user to resume at the appropriate step.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current Document State
+
+Read the existing architecture document completely and analyze:
+
+**Frontmatter Analysis:**
+
+- `stepsCompleted`: What steps have been done
+- `inputDocuments`: What documents were loaded
+- `lastStep`: Last step that was executed
+- `project_name`, `user_name`, `date`: Basic context
+
+**Content Analysis:**
+
+- What sections exist in the document
+- What architectural decisions have been made
+- What appears incomplete or in progress
+- Any TODOs or placeholders remaining
+
+### 2. Present Continuation Summary
+
+Show the user their current progress:
+
+"Welcome back {{user_name}}! I found your Architecture work for {{project_name}}.
+
+**Current Progress:**
+
+- Steps completed: {{stepsCompleted list}}
+- Last step worked on: Step {{lastStep}}
+- Input documents loaded: {{number of inputDocuments}} files
+
+**Document Sections Found:**
+{list all H2/H3 sections found in the document}
+
+{if_incomplete_sections}
+**Incomplete Areas:**
+
+- {areas that appear incomplete or have placeholders}
+  {/if_incomplete_sections}
+
+**What would you like to do?**
+[R] Resume from where we left off
+[C] Continue to next logical step
+[O] Overview of all remaining steps
+[X] Start over (will overwrite existing work)
+"
+
+### 3. Handle User Choice
+
+#### If 'R' (Resume from where we left off):
+
+- Identify the next step based on `stepsCompleted`
+- Load the appropriate step file to continue
+- Example: If `stepsCompleted: [1, 2, 3]`, load `step-04-decisions.md`
+
+#### If 'C' (Continue to next logical step):
+
+- Analyze the document content to determine logical next step
+- May need to review content quality and completeness
+- If content seems complete for current step, advance to next
+- If content seems incomplete, suggest staying on current step
+
+#### If 'O' (Overview of all remaining steps):
+
+- Provide brief description of all remaining steps
+- Let user choose which step to work on
+- Don't assume sequential progression is always best
+
+#### If 'X' (Start over):
+
+- Confirm: "This will delete all existing architectural decisions. Are you sure? (y/n)"
+- If confirmed: Delete existing document and return to step-01-init.md
+- If not confirmed: Return to continuation menu
+
+### 4. Navigate to Selected Step
+
+After user makes choice:
+
+**Load the selected step file:**
+
+- Update frontmatter `lastStep` to reflect current navigation
+- Execute the selected step file
+- Let that step handle the detailed continuation logic
+
+**State Preservation:**
+
+- Maintain all existing content in the document
+- Keep `stepsCompleted` accurate
+- Track the resumption in workflow status
+
+### 5. Special Continuation Cases
+
+#### If `stepsCompleted` is empty but document has content:
+
+- This suggests an interrupted workflow
+- Ask user: "I see the document has content but no steps are marked as complete. Should I analyze what's here and set the appropriate step status?"
+
+#### If document appears corrupted or incomplete:
+
+- Ask user: "The document seems incomplete. Would you like me to try to recover what's here, or would you prefer to start fresh?"
+
+#### If document is complete but workflow not marked as done:
+
+- Ask user: "The architecture looks complete! Should I mark this workflow as finished, or is there more you'd like to work on?"
+
+## SUCCESS METRICS:
+
+✅ Existing document state properly analyzed and understood
+✅ User presented with clear continuation options
+✅ User choice handled appropriately and transparently
+✅ Workflow state preserved and updated correctly
+✅ Navigation to appropriate step handled smoothly
+
+## FAILURE MODES:
+
+❌ Not reading the complete existing document before making suggestions
+❌ Losing track of what steps were actually completed
+❌ Automatically proceeding without user confirmation of next steps
+❌ Not checking for incomplete or placeholder content
+❌ Losing existing document content during resumption
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects their continuation option, load the appropriate step file based on their choice. The step file will handle the detailed work from that point forward.
+
+Remember: The goal is smooth, transparent resumption that respects the work already done while giving the user control over how to proceed.

package/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-02-context.md

@@ -0,0 +1,223 @@
+# Step 2: Project Context Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding project scope and requirements for architecture
+- 🎯 ANALYZE loaded documents, don't assume or generate requirements
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating project context analysis
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper insights about project context and architectural implications
+- **P (Party Mode)**: Bring multiple perspectives to analyze project requirements from different architectural angles
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Execute {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml
+- When 'P' selected: Execute {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step 1 are available
+- Input documents already loaded are in memory (PRD, epics, UX spec, etc.)
+- Focus on architectural implications of requirements
+- No technology decisions yet - pure analysis phase
+
+## YOUR TASK:
+
+Fully read and Analyze the loaded project documents to understand architectural scope, requirements, and constraints before beginning decision making.
+
+## CONTEXT ANALYSIS SEQUENCE:
+
+### 1. Review Project Requirements
+
+**From PRD Analysis:**
+
+- Extract and analyze Functional Requirements (FRs)
+- Identify Non-Functional Requirements (NFRs) like performance, security, compliance
+- Note any technical constraints or dependencies mentioned
+- Count and categorize requirements to understand project scale
+
+**From Epics/Stories (if available):**
+
+- Map epic structure and user stories to architectural components
+- Extract acceptance criteria for technical implications
+- Identify cross-cutting concerns that span multiple epics
+- Estimate story complexity for architectural planning
+
+**From UX Design (if available):**
+
+- Extract architectural implications from UX requirements:
+  - Component complexity (simple forms vs rich interactions)
+  - Animation/transition requirements
+  - Real-time update needs (live data, collaborative features)
+  - Platform-specific UI requirements
+  - Accessibility standards (WCAG compliance level)
+  - Responsive design breakpoints
+  - Offline capability requirements
+  - Performance expectations (load times, interaction responsiveness)
+
+### 2. Project Scale Assessment
+
+Calculate and present project complexity:
+
+**Complexity Indicators:**
+
+- Real-time features requirements
+- Multi-tenancy needs
+- Regulatory compliance requirements
+- Integration complexity
+- User interaction complexity
+- Data complexity and volume
+
+### 3. Reflect Understanding
+
+Present your analysis back to user for validation:
+
+"I'm reviewing your project documentation for {{project_name}}.
+
+{if_epics_loaded}I see {{epic_count}} epics with {{story_count}} total stories.{/if_epics_loaded}
+{if_no_epics}I found {{fr_count}} functional requirements organized into {{fr_category_list}}.{/if_no_epics}
+{if_ux_loaded}I also found your UX specification which defines the user experience requirements.{/if_ux_loaded}
+
+**Key architectural aspects I notice:**
+
+- [Summarize core functionality from FRs]
+- [Note critical NFRs that will shape architecture]
+- {if_ux_loaded}[Note UX complexity and technical requirements]{/if_ux_loaded}
+- [Identify unique technical challenges or constraints]
+- [Highlight any regulatory or compliance requirements]
+
+**Scale indicators:**
+
+- Project complexity appears to be: [low/medium/high/enterprise]
+- Primary technical domain: [web/mobile/api/backend/full-stack/etc]
+- Cross-cutting concerns identified: [list major ones]
+
+This analysis will help me guide you through the architectural decisions needed to ensure AI agents implement this consistently.
+
+Does this match your understanding of the project scope and requirements?"
+
+### 4. Generate Project Context Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Project Context Analysis
+
+### Requirements Overview
+
+**Functional Requirements:**
+{{analysis of FRs and what they mean architecturally}}
+
+**Non-Functional Requirements:**
+{{NFRs that will drive architectural decisions}}
+
+**Scale & Complexity:**
+{{project_scale_assessment}}
+
+- Primary domain: {{technical_domain}}
+- Complexity level: {{complexity_level}}
+- Estimated architectural components: {{component_count}}
+
+### Technical Constraints & Dependencies
+
+{{known_constraints_dependencies}}
+
+### Cross-Cutting Concerns Identified
+
+{{concerns_that_will_affect_multiple_components}}
+```
+
+### 5. Present Content and Menu
+
+Show the generated content and present choices:
+
+"I've drafted the Project Context Analysis based on your requirements. This sets the foundation for our architectural decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 4]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's dive deeper into architectural implications
+[P] Party Mode - Bring different perspectives to analyze requirements
+[C] Continue - Save this analysis and begin architectural decisions"
+
+### 6. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Execute {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml with the current context analysis
+- Process the enhanced architectural insights that come back
+- Ask user: "Accept these enhancements to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Execute {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md with the current project context
+- Process the collaborative improvements to architectural understanding
+- Ask user: "Accept these changes to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{output_folder}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load `./step-03-starter.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 4.
+
+## SUCCESS METRICS:
+
+✅ All input documents thoroughly analyzed for architectural implications
+✅ Project scope and complexity clearly assessed and validated
+✅ Technical constraints and dependencies identified
+✅ Cross-cutting concerns mapped for architectural planning
+✅ User confirmation of project understanding
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Skimming documents without deep architectural analysis
+❌ Missing or misinterpreting critical NFRs
+❌ Not validating project understanding with user
+❌ Underestimating complexity indicators
+❌ Generating content without real analysis of loaded documents
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-03-starter.md` to evaluate starter template options.
+
+Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved!