Major Enhancements:

- Installation path is now fully configurable, allowing users to specify custom installation directories during setup
  - Default installation location changed to .bmad (hidden directory) for cleaner project root organization

    Web Bundle Improvements:

    - All web bundles (single agent and team) now include party mode support for multi-agent collaboration!
    - Advanced elicitation capabilities integrated into standalone agents
    - All bundles enhanced with party mode agent manifests
    - Added default-party.csv files to bmm, bmgd, and cis module teams
    - The default party file is what will be used with single agent bundles. teams can customize for different party configurations before web bundling through a setting in the team yaml file
    - New web bundle outputs for all agents (analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer, game-*, creative-squad)

    Phase 4 Workflow Updates (In Progress):

    - Initiated shift to separate phase 4 implementation artifacts from documentation
        - Phase 4 implementation artifacts (stories, code review, sprint plan, context files) will move to dedicated location outside docs folder
        - Installer questions and configuration added for artifact path selection
        - Updated workflow.yaml files for code-review, sprint-planning, story-context, epic-tech-context, and retrospective workflows to support this, but still might require some udpates

    Additional Changes:

    - New agent and action command header models for standardization
    - Enhanced web-bundle-activation-steps fragment
    - Updated web-bundler.js to support new structure
    - VS Code settings updated for new .bmad directory
    - Party mode instructions and workflow enhanced for better orchestration

   IDE Installer Updates:

    - Show version number of installer in cli
    - improved Installer UX
    - Gemini TOML Improved to have clear loading instructions with @ commands
    - All tools agent launcher mds improved to use a central file template critical indication isntead of hardcoding in 2 different locations.

.bmad/bmm/workflows/1-analysis/brainstorm-project/instructions.md

@@ -0,0 +1,110 @@
+# Brainstorm Project - Workflow Instructions
+
+```xml
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+<critical>This is a meta-workflow that orchestrates the CIS brainstorming workflow with project-specific context</critical>
+
+<workflow>
+
+  <step n="1" 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. Brainstorming is optional - you can continue without status tracking.</output>
+      <action>Set standalone_mode = true</action>
+    </check>
+
+    <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 "brainstorm-project" workflow</action>
+      <action>Get project_level from YAML metadata</action>
+      <action>Find first non-completed workflow (next expected workflow)</action>
+
+      <check if="brainstorm-project status is file path (already completed)">
+        <output>⚠️ Brainstorming session already completed: {{brainstorm-project status}}</output>
+        <ask>Re-running will create a new session. 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="brainstorm-project is not the next expected workflow (anything after brainstorm-project is completed already)">
+        <output>⚠️ Next expected workflow: {{next_workflow}}. Brainstorming is out of sequence.</output>
+        <ask>Continue with brainstorming 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>
+  </step>
+
+  <step n="2" goal="Load project brainstorming context">
+    <action>Read the project context document from: {project_context}</action>
+    <action>This context provides project-specific guidance including:
+      - Focus areas for project ideation
+      - Key considerations for software/product projects
+      - Recommended techniques for project brainstorming
+      - Output structure guidance
+    </action>
+  </step>
+
+  <step n="3" goal="Invoke core brainstorming with project context">
+    <action>Execute the CIS brainstorming workflow with project context</action>
+    <invoke-workflow path="{core_brainstorming}" data="{project_context}">
+      The CIS brainstorming workflow will:
+      - Present interactive brainstorming techniques menu
+      - Guide the user through selected ideation methods
+      - Generate and capture brainstorming session results
+      - Save output to: {output_folder}/brainstorming-session-results-{{date}}.md
+    </invoke-workflow>
+  </step>
+
+  <step n="4" goal="Update status and complete" tag="workflow-status">
+    <check if="standalone_mode != true">
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+      <action>Find workflow_status key "brainstorm-project"</action>
+      <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+      <action>Update workflow_status["brainstorm-project"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+      <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>**✅ Brainstorming Session Complete, {user_name}!**
+
+**Session Results:**
+
+- Brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated
+
+**Next Steps:**
+
+- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** You can run other analysis workflows (research, product-brief) before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+**Next Steps:**
+
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+{{/if}}
+    </output>
+  </step>
+
+</workflow>
+```

.bmad/bmm/workflows/1-analysis/brainstorm-project/project-context.md

@@ -0,0 +1,25 @@
+# Project Brainstorming Context
+
+This context guide provides project-specific considerations for brainstorming sessions focused on software and product development.
+
+## Session Focus Areas
+
+When brainstorming for projects, consider exploring:
+
+- **User Problems and Pain Points** - What challenges do users face?
+- **Feature Ideas and Capabilities** - What could the product do?
+- **Technical Approaches** - How might we build it?
+- **User Experience** - How will users interact with it?
+- **Business Model and Value** - How does it create value?
+- **Market Differentiation** - What makes it unique?
+- **Technical Risks and Challenges** - What could go wrong?
+- **Success Metrics** - How will we measure success?
+
+## Integration with Project Workflow
+
+Brainstorming sessions typically feed into:
+
+- **Product Briefs** - Initial product vision and strategy
+- **PRDs** - Detailed requirements documents
+- **Technical Specifications** - Architecture and implementation plans
+- **Research Activities** - Areas requiring further investigation

.bmad/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml

@@ -0,0 +1,26 @@
+# Brainstorm Project Workflow Configuration
+name: "brainstorm-project"
+description: "Facilitate project brainstorming sessions by orchestrating the CIS brainstorming workflow with project-specific context and guidance."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm-project"
+template: false
+instructions: "{installed_path}/instructions.md"
+
+# Context document for project brainstorming
+project_context: "{installed_path}/project-context.md"
+
+# CORE brainstorming workflow to invoke
+core_brainstorming: "{project-root}/.bmad/core/workflows/brainstorming/workflow.yaml"
+
+standalone: true

.bmad/bmm/workflows/1-analysis/domain-research/instructions.md

@@ -0,0 +1,423 @@
+# Domain Research - Collaborative Domain Exploration
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This is COLLABORATIVE RESEARCH - engage the user as a partner, not just a data source</critical>
+<critical>The goal is PRACTICAL UNDERSTANDING that directly informs requirements and architecture</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to domain-brief.md continuously as you discover - never wait until the end</critical>
+
+<workflow>
+
+<step n="0" goal="Set research context">
+<action>Welcome {user_name} to collaborative domain research
+
+Check for context:
+
+- Was this triggered from PRD workflow?
+- Is there a workflow-status.yaml with project context?
+- Did user provide initial domain/project description?
+
+If context exists, reflect it back:
+"I understand you're building [description]. Let's explore the [domain] aspects together to ensure we capture all critical requirements."
+
+If no context:
+"Let's explore your project's domain together. Tell me about what you're building and what makes it unique or complex."</action>
+</step>
+
+<step n="1" goal="Domain detection and scoping">
+<action>Through conversation, identify the domain and its complexity
+
+Listen for domain signals and explore:
+
+- "Is this in a regulated industry?"
+- "Are there safety or compliance concerns?"
+- "What could go wrong if this fails?"
+- "Who are the stakeholders beyond direct users?"
+- "Are there industry standards we need to follow?"
+
+Based on responses, identify primary domain(s):
+
+- Healthcare/Medical
+- Financial Services
+- Government/Public Sector
+- Education
+- Aerospace/Defense
+- Automotive
+- Energy/Utilities
+- Legal
+- Insurance
+- Scientific/Research
+- Other specialized domain
+
+Share your understanding:
+"Based on our discussion, this appears to be a [domain] project with [key characteristics]. The main areas we should research are:
+
+- [Area 1]
+- [Area 2]
+- [Area 3]
+
+What concerns you most about building in this space?"</action>
+
+<template-output>domain_overview</template-output>
+</step>
+
+<step n="2" goal="Collaborative concern mapping">
+<action>Work WITH the user to identify critical concerns
+
+"Let's map out the important considerations together. I'll share what I typically see in [domain], and you tell me what applies to your case."
+
+For detected domain, explore relevant areas:
+
+HEALTHCARE:
+"In healthcare software, teams often worry about:
+
+- FDA approval pathways (510k, De Novo, PMA)
+- HIPAA compliance for patient data
+- Clinical validation requirements
+- Integration with hospital systems (HL7, FHIR, DICOM)
+- Patient safety and liability
+
+Which of these apply to you? What else concerns you?"
+
+FINTECH:
+"Financial software typically deals with:
+
+- KYC/AML requirements
+- Payment processing regulations (PCI DSS)
+- Regional compliance (US, EU, specific countries?)
+- Fraud prevention
+- Audit trails and reporting
+
+What's your situation with these? Any specific regions?"
+
+AEROSPACE:
+"Aerospace software often requires:
+
+- DO-178C certification levels
+- Safety analysis (FMEA, FTA)
+- Simulation validation
+- Real-time performance guarantees
+- Export control (ITAR)
+
+Which are relevant for your project?"
+
+[Continue for other domains...]
+
+Document concerns as the user shares them
+Ask follow-up questions to understand depth:
+
+- "How critical is this requirement?"
+- "Is this a must-have for launch or can it come later?"
+- "Do you have expertise here or need guidance?"</action>
+
+<template-output>concern_mapping</template-output>
+</step>
+
+<step n="3" goal="Research key requirements together">
+<action>Conduct research WITH the user watching and contributing
+
+"Let me research the current requirements for [specific concern]. You can guide me toward what's most relevant."
+
+<WebSearch>{specific_requirement} requirements {date}</WebSearch>
+
+Share findings immediately:
+"Here's what I found about [requirement]:
+
+- [Key point 1]
+- [Key point 2]
+- [Key point 3]
+
+Does this match your understanding? Anything surprising or concerning?"
+
+For each major concern:
+
+1. Research current standards/regulations
+2. Share findings with user
+3. Get their interpretation
+4. Note practical implications
+
+If user has expertise:
+"You seem knowledgeable about [area]. What should I know that might not be in public documentation?"
+
+If user is learning:
+"This might be new territory. Let me explain what this means practically for your development..."</action>
+
+<template-output>regulatory_requirements</template-output>
+<template-output>industry_standards</template-output>
+</step>
+
+<step n="4" goal="Identify practical implications">
+<action>Translate research into practical development impacts
+
+"Based on what we've learned, here's what this means for your project:
+
+ARCHITECTURE IMPLICATIONS:
+
+- [How this affects system design]
+- [Required components or patterns]
+- [Performance or security needs]
+
+DEVELOPMENT IMPLICATIONS:
+
+- [Additional development effort]
+- [Special expertise needed]
+- [Testing requirements]
+
+TIMELINE IMPLICATIONS:
+
+- [Certification/approval timelines]
+- [Validation requirements]
+- [Documentation needs]
+
+COST IMPLICATIONS:
+
+- [Compliance costs]
+- [Required tools or services]
+- [Ongoing maintenance]
+
+Does this align with your expectations? Any surprises we should dig into?"</action>
+
+<template-output>practical_implications</template-output>
+</step>
+
+<step n="5" goal="Discover domain-specific patterns">
+<action>Explore how others solve similar problems
+
+"Let's look at how successful [domain] products handle these challenges."
+
+<WebSearch>best {domain} software architecture patterns {date}</WebSearch>
+<WebSearch>{domain} software case studies {date}</WebSearch>
+
+Discuss patterns:
+"I found these common approaches in [domain]:
+
+Pattern 1: [Description]
+
+- Pros: [Benefits]
+- Cons: [Tradeoffs]
+- When to use: [Conditions]
+
+Pattern 2: [Description]
+
+- Pros: [Benefits]
+- Cons: [Tradeoffs]
+- When to use: [Conditions]
+
+Which resonates with your vision? Or are you thinking something different?"
+
+If user proposes novel approach:
+"That's interesting and different from the standard patterns. Let's explore:
+
+- What makes your approach unique?
+- What problem does it solve that existing patterns don't?
+- What are the risks?
+- How do we validate it?"</action>
+
+<template-output>domain_patterns</template-output>
+<template-output if="novel approach">innovation_notes</template-output>
+</step>
+
+<step n="6" goal="Risk assessment and mitigation">
+<action>Collaboratively identify and address risks
+
+"Every [domain] project has risks. Let's think through yours:
+
+REGULATORY RISKS:
+
+- What if regulations change during development?
+- What if approval/certification takes longer?
+- What if we misinterpret requirements?
+
+TECHNICAL RISKS:
+
+- What if the domain requirements conflict with user experience?
+- What if performance requirements are harder than expected?
+- What if integrations are more complex?
+
+MARKET RISKS:
+
+- What if competitors move faster?
+- What if domain experts are hard to find?
+- What if users resist domain-mandated workflows?
+
+For each risk you're concerned about, let's identify:
+
+1. How likely is it?
+2. What's the impact if it happens?
+3. How can we mitigate it?
+4. What's our plan B?"</action>
+
+<template-output>risk_assessment</template-output>
+</step>
+
+<step n="7" goal="Create validation strategy">
+<action>Plan how to ensure domain requirements are met
+
+"Let's plan how to validate that we're meeting [domain] requirements:
+
+COMPLIANCE VALIDATION:
+
+- How do we verify regulatory compliance?
+- Who needs to review/approve?
+- What documentation is required?
+
+TECHNICAL VALIDATION:
+
+- How do we prove the system works correctly?
+- What metrics matter?
+- What testing is required?
+
+DOMAIN EXPERT VALIDATION:
+
+- Who are the domain experts to involve?
+- When should they review?
+- What are their success criteria?
+
+USER VALIDATION:
+
+- How do we ensure it's still usable despite constraints?
+- What user testing is needed?
+- How do we balance domain requirements with UX?
+
+What validation is most critical for your confidence?"</action>
+
+<template-output>validation_strategy</template-output>
+</step>
+
+<step n="8" goal="Document decision points">
+<action>Capture key decisions and rationale
+
+"Let's document the important decisions we've made:
+
+DOMAIN APPROACH:
+
+- We're choosing [approach] because [rationale]
+- We're prioritizing [requirement] over [requirement] because [reason]
+- We're deferring [requirement] to Phase 2 because [justification]
+
+COMPLIANCE STRATEGY:
+
+- We'll pursue [pathway] for regulatory approval
+- We'll implement [standard] for industry compliance
+- We'll handle [requirement] by [approach]
+
+RISK DECISIONS:
+
+- We accept [risk] because [reason]
+- We'll mitigate [risk] through [approach]
+- We'll monitor [risk] by [method]
+
+Any decisions you want to revisit or rationale to add?"</action>
+
+<template-output>key_decisions</template-output>
+</step>
+
+<step n="9" goal="Create actionable recommendations">
+<action>Synthesize research into specific recommendations
+
+"Based on our research, here are my recommendations for your PRD and development:
+
+MUST HAVE (Domain Critical):
+
+1. [Specific requirement with why it's critical]
+2. [Specific requirement with why it's critical]
+3. [Specific requirement with why it's critical]
+
+SHOULD HAVE (Domain Important):
+
+1. [Requirement that's important but not blocking]
+2. [Requirement that's important but not blocking]
+
+CONSIDER (Domain Nice-to-Have):
+
+1. [Enhancement that would differentiate]
+2. [Enhancement that would differentiate]
+
+DEVELOPMENT SEQUENCE:
+
+1. First: [What to build first and why]
+2. Then: [What comes next and why]
+3. Later: [What can wait and why]
+
+EXPERTISE NEEDED:
+
+- [Domain expert role]: For [specific areas]
+- [Technical expert role]: For [specific requirements]
+
+TIMELINE CONSIDERATIONS:
+
+- Allow [time] for [process/approval]
+- Start [requirement] early because [reason]
+- [Requirement] can be parallel with development
+
+Do these recommendations feel right? What would you adjust?"</action>
+
+<template-output>recommendations</template-output>
+</step>
+
+<step n="10" goal="Package for PRD integration">
+<action>Create clear handoff to PRD workflow
+
+"I've captured everything in domain-brief.md. Here's the summary for your PRD:
+
+DOMAIN: {identified_domain}
+COMPLEXITY: {high|medium}
+
+KEY REQUIREMENTS TO INCORPORATE:
+
+- [Requirement 1 - critical for domain]
+- [Requirement 2 - critical for domain]
+- [Requirement 3 - important consideration]
+
+IMPACTS ON:
+
+- Functional Requirements: [How domain affects features]
+- Non-Functional Requirements: [Performance, security, etc.]
+- Architecture: [System design considerations]
+- Development: [Process and timeline impacts]
+
+REFERENCE DOCS:
+
+- Full domain analysis: domain-brief.md
+- Regulations researched: [List with links]
+- Standards referenced: [List with links]
+
+When you return to PRD, reference this brief for domain context.
+
+Any final questions before we wrap up the domain research?"</action>
+
+<template-output>summary_for_prd</template-output>
+</step>
+
+<step n="11" goal="Close with next steps">
+<output>**✅ Domain Research Complete, {user_name}!**
+
+We've explored the {domain} aspects of your project together and documented critical requirements.
+
+**Created:**
+
+- **domain-brief.md** - Complete domain analysis with requirements and recommendations
+
+**Key Findings:**
+
+- Primary domain: {domain}
+- Complexity level: {complexity}
+- Critical requirements: {count} identified
+- Risks identified: {count} with mitigation strategies
+
+**Next Steps:**
+
+1. Return to PRD workflow with this domain context
+2. Domain requirements will shape your functional requirements
+3. Reference domain-brief.md for detailed requirements
+
+**Remember:**
+{most_important_finding}
+
+The domain research will ensure your PRD captures not just what to build, but HOW to build it correctly for {domain}.
+</output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/domain-research/template.md

@@ -0,0 +1,180 @@
+# Domain Brief - {project_name}
+
+Generated: {date}
+Domain: {primary_domain}
+Complexity: {complexity_level}
+
+## Executive Summary
+
+{brief_overview_of_domain_research_findings}
+
+## Domain Overview
+
+### Industry Context
+
+{domain_overview}
+
+### Regulatory Landscape
+
+{regulatory_environment}
+
+### Key Stakeholders
+
+{stakeholder_analysis}
+
+## Critical Concerns
+
+### Compliance Requirements
+
+{concern_mapping}
+
+### Technical Constraints
+
+{technical_limitations_from_domain}
+
+### Safety/Risk Considerations
+
+{safety_risk_factors}
+
+## Regulatory Requirements
+
+{regulatory_requirements}
+
+## Industry Standards
+
+{industry_standards}
+
+## Practical Implications
+
+### Architecture Impact
+
+{architecture_implications}
+
+### Development Impact
+
+{development_implications}
+
+### Timeline Impact
+
+{timeline_implications}
+
+### Cost Impact
+
+{cost_implications}
+
+## Domain Patterns
+
+### Established Patterns
+
+{domain_patterns}
+
+### Innovation Opportunities
+
+{innovation_notes}
+
+## Risk Assessment
+
+### Identified Risks
+
+{risk_assessment}
+
+### Mitigation Strategies
+
+{mitigation_approaches}
+
+## Validation Strategy
+
+### Compliance Validation
+
+{compliance_validation_approach}
+
+### Technical Validation
+
+{technical_validation_approach}
+
+### Domain Expert Validation
+
+{expert_validation_approach}
+
+## Key Decisions
+
+{key_decisions}
+
+## Recommendations
+
+### Must Have (Critical)
+
+{critical_requirements}
+
+### Should Have (Important)
+
+{important_requirements}
+
+### Consider (Nice-to-Have)
+
+{optional_enhancements}
+
+### Development Sequence
+
+{recommended_sequence}
+
+### Required Expertise
+
+{expertise_needed}
+
+## PRD Integration Guide
+
+### Summary for PRD
+
+{summary_for_prd}
+
+### Requirements to Incorporate
+
+- {requirement_1}
+- {requirement_2}
+- {requirement_3}
+
+### Architecture Considerations
+
+- {architecture_consideration_1}
+- {architecture_consideration_2}
+
+### Development Considerations
+
+- {development_consideration_1}
+- {development_consideration_2}
+
+## References
+
+### Regulations Researched
+
+- {regulation_1_with_link}
+- {regulation_2_with_link}
+
+### Standards Referenced
+
+- {standard_1_with_link}
+- {standard_2_with_link}
+
+### Additional Resources
+
+- {resource_1}
+- {resource_2}
+
+## Appendix
+
+### Research Notes
+
+{detailed_research_notes}
+
+### Conversation Highlights
+
+{key_discussion_points_with_user}
+
+### Open Questions
+
+{questions_requiring_further_research}
+
+---
+
+_This domain brief was created through collaborative research between {user_name} and the AI facilitator. It should be referenced during PRD creation and updated as new domain insights emerge._

.bmad/bmm/workflows/1-analysis/domain-research/workflow.yaml

@@ -0,0 +1,40 @@
+# Domain Research Workflow Configuration
+name: domain-research
+description: "Collaborative exploration of domain-specific requirements, regulations, and patterns for complex projects"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/1-analysis/domain-research"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/template.md"
+
+# Optional knowledge base (if exists)
+domain_knowledge_base: "{installed_path}/domain-knowledge-base.md"
+
+# Output configuration
+default_output_file: "{output_folder}/domain-brief.md"
+
+# Workflow metadata
+version: "6.0.0-alpha"
+category: "analysis"
+complexity: "medium"
+execution_time: "30-45 minutes"
+prerequisites:
+  - "Basic project understanding"
+when_to_use:
+  - "Complex regulated domains (healthcare, finance, aerospace)"
+  - "Novel technical domains requiring deep understanding"
+  - "Before PRD when domain expertise needed"
+  - "When compliance and regulations matter"
+
+standalone: true
+# Web bundle configuration for standalone deployment

.bmad/bmm/workflows/1-analysis/product-brief/checklist.md

@@ -0,0 +1,115 @@
+# Product Brief Validation Checklist
+
+## Document Structure
+
+- [ ] All required sections are present (Executive Summary through Appendices)
+- [ ] No placeholder text remains (e.g., [TODO], [NEEDS CONFIRMATION], {{variable}})
+- [ ] Document follows the standard brief template format
+- [ ] Sections are properly numbered and formatted with headers
+- [ ] Cross-references between sections are accurate
+
+## Executive Summary Quality
+
+- [ ] Product concept is explained in 1-2 clear sentences
+- [ ] Primary problem is clearly identified
+- [ ] Target market is specifically named (not generic)
+- [ ] Value proposition is compelling and differentiated
+- [ ] Summary accurately reflects the full document content
+
+## Problem Statement
+
+- [ ] Current state pain points are specific and measurable
+- [ ] Impact is quantified where possible (time, money, opportunities)
+- [ ] Explanation of why existing solutions fall short is provided
+- [ ] Urgency for solving the problem now is justified
+- [ ] Problem is validated with evidence or data points
+
+## Solution Definition
+
+- [ ] Core approach is clearly explained without implementation details
+- [ ] Key differentiators from existing solutions are identified
+- [ ] Explanation of why this will succeed is compelling
+- [ ] Solution aligns directly with stated problems
+- [ ] Vision paints a clear picture of the user experience
+
+## Target Users
+
+- [ ] Primary user segment has specific demographic/firmographic profile
+- [ ] User behaviors and current workflows are documented
+- [ ] Specific pain points are tied to user segments
+- [ ] User goals are clearly articulated
+- [ ] Secondary segment (if applicable) is equally detailed
+- [ ] Avoids generic personas like "busy professionals"
+
+## Goals and Metrics
+
+- [ ] Business objectives include measurable outcomes with targets
+- [ ] User success metrics focus on behaviors, not features
+- [ ] 3-5 KPIs are defined with clear definitions
+- [ ] All goals follow SMART criteria (Specific, Measurable, Achievable, Relevant, Time-bound)
+- [ ] Success metrics align with problem statement
+
+## MVP Scope
+
+- [ ] Core features list contains only true must-haves
+- [ ] Each core feature includes rationale for why it's essential
+- [ ] Out of scope section explicitly lists deferred features
+- [ ] MVP success criteria are specific and measurable
+- [ ] Scope is genuinely minimal and viable
+- [ ] No feature creep evident in "must-have" list
+
+## Technical Considerations
+
+- [ ] Target platforms are specified (web/mobile/desktop)
+- [ ] Browser/OS support requirements are documented
+- [ ] Performance requirements are defined if applicable
+- [ ] Accessibility requirements are noted
+- [ ] Technology preferences are marked as preferences, not decisions
+- [ ] Integration requirements with existing systems are identified
+
+## Constraints and Assumptions
+
+- [ ] Budget constraints are documented if known
+- [ ] Timeline or deadline pressures are specified
+- [ ] Team/resource limitations are acknowledged
+- [ ] Technical constraints are clearly stated
+- [ ] Key assumptions are listed and testable
+- [ ] Assumptions will be validated during development
+
+## Risk Assessment (if included)
+
+- [ ] Key risks include potential impact descriptions
+- [ ] Open questions are specific and answerable
+- [ ] Research areas are identified with clear objectives
+- [ ] Risk mitigation strategies are suggested where applicable
+
+## Overall Quality
+
+- [ ] Language is clear and free of jargon
+- [ ] Terminology is used consistently throughout
+- [ ] Document is ready for handoff to Product Manager
+- [ ] All [PM-TODO] items are clearly marked if present
+- [ ] References and source documents are properly cited
+
+## Completeness Check
+
+- [ ] Document provides sufficient detail for PRD creation
+- [ ] All user inputs have been incorporated
+- [ ] Market research findings are reflected if provided
+- [ ] Competitive analysis insights are included if available
+- [ ] Brief aligns with overall product strategy
+
+## Final Validation
+
+### Critical Issues Found:
+
+- [ ] None identified
+
+### Minor Issues to Address:
+
+- [ ] List any minor issues here
+
+### Ready for PM Handoff:
+
+- [ ] Yes, brief is complete and validated
+- [ ] No, requires additional work (specify above)

.bmad/bmm/workflows/1-analysis/product-brief/instructions.md

@@ -0,0 +1,524 @@
+# Product Brief - Context-Adaptive Discovery Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses INTENT-DRIVEN FACILITATION - adapt organically to what emerges</critical>
+<critical>The goal is DISCOVERING WHAT MATTERS through natural conversation, not filling a template</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to the document continuously as you discover - never wait until the end</critical>
+
+## Input Document Discovery
+
+This workflow may reference: market research, brainstorming documents, user specified other inputs, or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+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`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
+<workflow>
+
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
+
+<action if="status file not found">Set standalone_mode = true</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 "product-brief" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="project_level < 2">
+    <output>**Note: Level {{project_level}} Project**
+
+Product Brief is most valuable for Level 2+ projects, but can help clarify vision for any project.</output>
+</check>
+
+  <check if="product-brief status is file path (already completed)">
+    <output>⚠️ Product Brief already completed: {{product-brief status}}</output>
+    <ask>Re-running will overwrite the existing brief. 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="product-brief is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Product Brief is out of sequence.</output>
+    <ask>Continue with Product Brief 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>
+</step>
+
+<step n="1" goal="Begin the journey and understand context">
+<action>Welcome {user_name} warmly in {communication_language}
+
+Adapt your tone to {user_skill_level}:
+
+- Expert: "Let's define your product vision. What are you building?"
+- Intermediate: "I'm here to help shape your product vision. Tell me about your idea."
+- Beginner: "Hi! I'm going to help you figure out exactly what you want to build. Let's start with your idea - what got you excited about this?"
+
+Start with open exploration:
+
+- What sparked this idea?
+- What are you hoping to build?
+- Who is this for - yourself, a business, users you know?
+
+CRITICAL: Listen for context clues that reveal their situation:
+
+- Personal/hobby project (fun, learning, small audience)
+- Startup/solopreneur (market opportunity, competition matters)
+- Enterprise/corporate (stakeholders, compliance, strategic alignment)
+- Technical enthusiasm (implementation focused)
+- Business opportunity (market/revenue focused)
+- Problem frustration (solution focused)
+
+Based on their initial response, sense:
+
+- How formal/casual they want to be
+- Whether they think in business or technical terms
+- If they have existing materials to share
+- Their confidence level with the domain</action>
+
+<ask>What's the project name, and what got you excited about building this?</ask>
+
+<action>From even this first exchange, create initial document sections</action>
+<template-output>project_name</template-output>
+<template-output>executive_summary</template-output>
+
+<action>If they mentioned existing documents (research, brainstorming, etc.):
+
+- Load and analyze these materials
+- Extract key themes and insights
+- Reference these naturally in conversation: "I see from your research that..."
+- Use these to accelerate discovery, not repeat questions</action>
+
+<template-output>initial_vision</template-output>
+</step>
+
+<step n="2" goal="Discover the problem worth solving">
+<action>Guide problem discovery through natural conversation
+
+DON'T ask: "What problem does this solve?"
+
+DO explore conversationally based on their context:
+
+For hobby projects:
+
+- "What's annoying you that this would fix?"
+- "What would this make easier or more fun?"
+- "Show me what the experience is like today without this"
+
+For business ventures:
+
+- "Walk me through the frustration your users face today"
+- "What's the cost of this problem - time, money, opportunities?"
+- "Who's suffering most from this? Tell me about them"
+- "What solutions have people tried? Why aren't they working?"
+
+For enterprise:
+
+- "What's driving the need for this internally?"
+- "Which teams/processes are most affected?"
+- "What's the business impact of not solving this?"
+- "Are there compliance or strategic drivers?"
+
+Listen for depth cues:
+
+- Brief answers → dig deeper with follow-ups
+- Detailed passion → let them flow, capture everything
+- Uncertainty → help them explore with examples
+- Multiple problems → help prioritize the core issue
+
+Adapt your response:
+
+- If they struggle: offer analogies, examples, frameworks
+- If they're clear: validate and push for specifics
+- If they're technical: explore implementation challenges
+- If they're business-focused: quantify impact</action>
+
+<action>Immediately capture what emerges - even if preliminary</action>
+<template-output>problem_statement</template-output>
+
+<check if="user mentioned metrics, costs, or business impact">
+  <action>Explore the measurable impact of the problem</action>
+  <template-output>problem_impact</template-output>
+</check>
+
+<check if="user mentioned current solutions or competitors">
+  <action>Understand why existing solutions fall short</action>
+  <template-output>existing_solutions_gaps</template-output>
+</check>
+
+<action>Reflect understanding: "So the core issue is {{problem_summary}}, and {{impact_if_mentioned}}. Let me capture that..."</action>
+</step>
+
+<step n="3" goal="Shape the solution vision">
+<action>Transition naturally from problem to solution
+
+Based on their energy and context, explore:
+
+For builders/makers:
+
+- "How do you envision this working?"
+- "Walk me through the experience you want to create"
+- "What's the 'magic moment' when someone uses this?"
+
+For business minds:
+
+- "What's your unique approach to solving this?"
+- "How is this different from what exists today?"
+- "What makes this the RIGHT solution now?"
+
+For enterprise:
+
+- "What would success look like for the organization?"
+- "How does this fit with existing systems/processes?"
+- "What's the transformation you're enabling?"
+
+Go deeper based on responses:
+
+- If innovative → explore the unique angle
+- If standard → focus on execution excellence
+- If technical → discuss key capabilities
+- If user-focused → paint the journey
+
+Web research when relevant:
+
+- If they mention competitors → research current solutions
+- If they claim innovation → verify uniqueness
+- If they reference trends → get current data</action>
+
+<action if="competitor or market mentioned">
+  <WebSearch>{{competitor/market}} latest features 2024</WebSearch>
+  <action>Use findings to sharpen differentiation discussion</action>
+</action>
+
+<template-output>proposed_solution</template-output>
+
+<check if="unique differentiation discussed">
+  <template-output>key_differentiators</template-output>
+</check>
+
+<action>Continue building the living document</action>
+</step>
+
+<step n="4" goal="Understand the people who need this">
+<action>Discover target users through storytelling, not demographics
+
+Facilitate based on project type:
+
+Personal/hobby:
+
+- "Who else would love this besides you?"
+- "Tell me about someone who would use this"
+- Keep it light and informal
+
+Startup/business:
+
+- "Describe your ideal first customer - not demographics, but their situation"
+- "What are they doing today without your solution?"
+- "What would make them say 'finally, someone gets it!'?"
+- "Are there different types of users with different needs?"
+
+Enterprise:
+
+- "Which roles/departments will use this?"
+- "Walk me through their current workflow"
+- "Who are the champions vs skeptics?"
+- "What about indirect stakeholders?"
+
+Push beyond generic personas:
+
+- Not: "busy professionals" → "Sales reps who waste 2 hours/day on data entry"
+- Not: "tech-savvy users" → "Developers who know Docker but hate configuring it"
+- Not: "small businesses" → "Shopify stores doing $10-50k/month wanting to scale"
+
+For each user type that emerges:
+
+- Current behavior/workflow
+- Specific frustrations
+- What they'd value most
+- Their technical comfort level</action>
+
+<template-output>primary_user_segment</template-output>
+
+<check if="multiple user types mentioned">
+  <action>Explore secondary users only if truly different needs</action>
+  <template-output>secondary_user_segment</template-output>
+</check>
+
+<check if="user journey or workflow discussed">
+  <template-output>user_journey</template-output>
+</check>
+</step>
+
+<step n="5" goal="Define what success looks like" repeat="adapt-to-context">
+<action>Explore success measures that match their context
+
+For personal projects:
+
+- "How will you know this is working well?"
+- "What would make you proud of this?"
+- Keep metrics simple and meaningful
+
+For startups:
+
+- "What metrics would convince you this is taking off?"
+- "What user behaviors show they love it?"
+- "What business metrics matter most - users, revenue, retention?"
+- Push for specific targets: "100 users" not "lots of users"
+
+For enterprise:
+
+- "How will the organization measure success?"
+- "What KPIs will stakeholders care about?"
+- "What are the must-hit metrics vs nice-to-haves?"
+
+Only dive deep into metrics if they show interest
+Skip entirely for pure hobby projects
+Focus on what THEY care about measuring</action>
+
+<check if="metrics or goals discussed">
+  <template-output>success_metrics</template-output>
+
+  <check if="business objectives mentioned">
+    <template-output>business_objectives</template-output>
+  </check>
+
+  <check if="KPIs matter to them">
+    <template-output>key_performance_indicators</template-output>
+  </check>
+</check>
+
+<action>Keep the document growing with each discovery</action>
+</step>
+
+<step n="6" goal="Discover the MVP scope">
+<critical>Focus on FEATURES not epics - that comes in Phase 2</critical>
+
+<action>Guide MVP scoping based on their maturity
+
+For experimental/hobby:
+
+- "What's the ONE thing this must do to be useful?"
+- "What would make a fun first version?"
+- Embrace simplicity
+
+For business ventures:
+
+- "What's the smallest version that proves your hypothesis?"
+- "What features would make early adopters say 'good enough'?"
+- "What's tempting to add but would slow you down?"
+- Be ruthless about scope creep
+
+For enterprise:
+
+- "What's the pilot scope that demonstrates value?"
+- "Which capabilities are must-have for initial rollout?"
+- "What can we defer to Phase 2?"
+
+Use this framing:
+
+- Core features: "Without this, the product doesn't work"
+- Nice-to-have: "This would be great, but we can launch without it"
+- Future vision: "This is where we're headed eventually"
+
+Challenge feature creep:
+
+- "Do we need that for launch, or could it come later?"
+- "What if we started without that - what breaks?"
+- "Is this core to proving the concept?"</action>
+
+<template-output>core_features</template-output>
+
+<check if="scope creep discussed">
+  <template-output>out_of_scope</template-output>
+</check>
+
+<check if="future features mentioned">
+  <template-output>future_vision_features</template-output>
+</check>
+
+<check if="success criteria for MVP mentioned">
+  <template-output>mvp_success_criteria</template-output>
+</check>
+</step>
+
+<step n="7" goal="Explore relevant context dimensions" repeat="until-natural-end">
+<critical>Only explore what emerges naturally - skip what doesn't matter</critical>
+
+<action>Based on the conversation so far, selectively explore:
+
+IF financial aspects emerged:
+
+- Development investment needed
+- Revenue potential or cost savings
+- ROI timeline
+- Budget constraints
+  <check if="discussed">
+  <template-output>financial_considerations</template-output>
+  </check>
+
+IF market competition mentioned:
+
+- Competitive landscape
+- Market opportunity size
+- Differentiation strategy
+- Market timing
+  <check if="discussed">
+  <WebSearch>{{market}} size trends 2024</WebSearch>
+  <template-output>market_analysis</template-output>
+  </check>
+
+IF technical preferences surfaced:
+
+- Platform choices (web/mobile/desktop)
+- Technology stack preferences
+- Integration needs
+- Performance requirements
+  <check if="discussed">
+  <template-output>technical_preferences</template-output>
+  </check>
+
+IF organizational context emerged:
+
+- Strategic alignment
+- Stakeholder buy-in needs
+- Change management considerations
+- Compliance requirements
+  <check if="discussed">
+  <template-output>organizational_context</template-output>
+  </check>
+
+IF risks or concerns raised:
+
+- Key risks and mitigation
+- Critical assumptions
+- Open questions needing research
+  <check if="discussed">
+  <template-output>risks_and_assumptions</template-output>
+  </check>
+
+IF timeline pressures mentioned:
+
+- Launch timeline
+- Critical milestones
+- Dependencies
+  <check if="discussed">
+  <template-output>timeline_constraints</template-output>
+  </check>
+
+Skip anything that hasn't naturally emerged
+Don't force sections that don't fit their context</action>
+</step>
+
+<step n="8" goal="Refine and complete the living document">
+<action>Review what's been captured with the user
+
+"Let me show you what we've built together..."
+
+Present the actual document sections created so far
+
+- Not a summary, but the real content
+- Shows the document has been growing throughout
+
+Ask:
+"Looking at this, what stands out as most important to you?"
+"Is there anything critical we haven't explored?"
+"Does this capture your vision?"
+
+Based on their response:
+
+- Refine sections that need more depth
+- Add any missing critical elements
+- Remove or simplify sections that don't matter
+- Ensure the document fits THEIR needs, not a template</action>
+
+<action>Make final refinements based on feedback</action>
+<template-output>final_refinements</template-output>
+
+<action>Create executive summary that captures the essence</action>
+<template-output>executive_summary</template-output>
+</step>
+<step n="9" goal="Complete and save the product brief">
+<action>The document has been building throughout our conversation
+Now ensure it's complete and well-organized</action>
+
+<check if="research documents were provided">
+  <action>Append summary of incorporated research</action>
+  <template-output>supporting_materials</template-output>
+</check>
+
+<action>Ensure the document structure makes sense for what was discovered:
+
+- Hobbyist projects might be 2-3 pages focused on problem/solution/features
+- Startup ventures might be 5-7 pages with market analysis and metrics
+- Enterprise briefs might be 10+ pages with full strategic context
+
+The document should reflect their world, not force their world into a template</action>
+
+<ask>Your product brief is ready! Would you like to:
+
+1. Review specific sections together
+2. Make any final adjustments
+3. Save and move forward
+
+What feels right?</ask>
+
+<action>Make any requested refinements</action>
+<template-output>final_document</template-output>
+</step>
+
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "product-brief"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["product-brief"] = "{output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<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>**✅ Product Brief Complete, {user_name}!**
+
+Your product vision has been captured in a document that reflects what matters most for your {{context_type}} project.
+
+**Document saved:** {output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**What's next:** {{next_workflow}} ({{next_agent}} agent)
+
+The next phase will take your brief and create the detailed planning artifacts needed for implementation.
+{{else}}
+**Next steps:**
+
+- Run `workflow-init` to set up guided workflow tracking
+- Or proceed directly to the PRD workflow if you know your path
+  {{/if}}
+
+Remember: This brief captures YOUR vision. It grew from our conversation, not from a rigid template. It's ready to guide the next phase of bringing your idea to life.
+</output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/product-brief/template.md

@@ -0,0 +1,181 @@
+# Product Brief: {{project_name}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Context:** {{context_type}}
+
+---
+
+## Executive Summary
+
+{{executive_summary}}
+
+---
+
+## Core Vision
+
+### Problem Statement
+
+{{problem_statement}}
+
+{{#if problem_impact}}
+
+### Problem Impact
+
+{{problem_impact}}
+{{/if}}
+
+{{#if existing_solutions_gaps}}
+
+### Why Existing Solutions Fall Short
+
+{{existing_solutions_gaps}}
+{{/if}}
+
+### Proposed Solution
+
+{{proposed_solution}}
+
+{{#if key_differentiators}}
+
+### Key Differentiators
+
+{{key_differentiators}}
+{{/if}}
+
+---
+
+## Target Users
+
+### Primary Users
+
+{{primary_user_segment}}
+
+{{#if secondary_user_segment}}
+
+### Secondary Users
+
+{{secondary_user_segment}}
+{{/if}}
+
+{{#if user_journey}}
+
+### User Journey
+
+{{user_journey}}
+{{/if}}
+
+---
+
+{{#if success_metrics}}
+
+## Success Metrics
+
+{{success_metrics}}
+
+{{#if business_objectives}}
+
+### Business Objectives
+
+{{business_objectives}}
+{{/if}}
+
+{{#if key_performance_indicators}}
+
+### Key Performance Indicators
+
+{{key_performance_indicators}}
+{{/if}}
+{{/if}}
+
+---
+
+## MVP Scope
+
+### Core Features
+
+{{core_features}}
+
+{{#if out_of_scope}}
+
+### Out of Scope for MVP
+
+{{out_of_scope}}
+{{/if}}
+
+{{#if mvp_success_criteria}}
+
+### MVP Success Criteria
+
+{{mvp_success_criteria}}
+{{/if}}
+
+{{#if future_vision_features}}
+
+### Future Vision
+
+{{future_vision_features}}
+{{/if}}
+
+---
+
+{{#if market_analysis}}
+
+## Market Context
+
+{{market_analysis}}
+{{/if}}
+
+{{#if financial_considerations}}
+
+## Financial Considerations
+
+{{financial_considerations}}
+{{/if}}
+
+{{#if technical_preferences}}
+
+## Technical Preferences
+
+{{technical_preferences}}
+{{/if}}
+
+{{#if organizational_context}}
+
+## Organizational Context
+
+{{organizational_context}}
+{{/if}}
+
+{{#if risks_and_assumptions}}
+
+## Risks and Assumptions
+
+{{risks_and_assumptions}}
+{{/if}}
+
+{{#if timeline_constraints}}
+
+## Timeline
+
+{{timeline_constraints}}
+{{/if}}
+
+{{#if supporting_materials}}
+
+## Supporting Materials
+
+{{supporting_materials}}
+{{/if}}
+
+---
+
+_This Product Brief captures the vision and requirements for {{project_name}}._
+
+_It was created through collaborative discovery and reflects the unique needs of this {{context_type}} project._
+
+{{#if next_workflow}}
+_Next: {{next_workflow}} will transform this brief into detailed planning artifacts._
+{{else}}
+_Next: Use the PRD workflow to create detailed product requirements from this brief._
+{{/if}}

.bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml

@@ -0,0 +1,45 @@
+# Product Brief - Interactive Workflow Configuration
+name: product-brief
+description: "Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Optional input documents
+recommended_inputs:
+  - market_research: "Market research document (optional)"
+  - brainstorming_results: "Brainstorming session outputs (optional)"
+  - competitive_analysis: "Competitive analysis (optional)"
+  - initial_ideas: "Initial product ideas or notes (optional)"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/1-analysis/product-brief"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/product-brief-{{project_name}}-{{date}}.md"
+
+standalone: true

.bmad/bmm/workflows/1-analysis/research/checklist-deep-prompt.md

@@ -0,0 +1,144 @@
+# Deep Research Prompt Validation Checklist
+
+## 🚨 CRITICAL: Anti-Hallucination Instructions (PRIORITY)
+
+### Citation Requirements Built Into Prompt
+
+- [ ] Prompt EXPLICITLY instructs: "Cite sources with URLs for ALL factual claims"
+- [ ] Prompt requires: "Include source name, date, and URL for every statistic"
+- [ ] Prompt mandates: "If you cannot find reliable data, state 'No verified data found for [X]'"
+- [ ] Prompt specifies inline citation format (e.g., "[Source: Company, Year, URL]")
+- [ ] Prompt requires References section at end with all sources listed
+
+### Multi-Source Verification Requirements
+
+- [ ] Prompt instructs: "Cross-reference critical claims with at least 2 independent sources"
+- [ ] Prompt requires: "Note when sources conflict and present all viewpoints"
+- [ ] Prompt specifies: "Verify version numbers and dates from official sources"
+- [ ] Prompt mandates: "Mark confidence levels: [Verified], [Single source], [Uncertain]"
+
+### Fact vs Analysis Distinction
+
+- [ ] Prompt requires clear labeling: "Distinguish FACTS (sourced), ANALYSIS (your interpretation), SPECULATION (projections)"
+- [ ] Prompt instructs: "Do not present assumptions or analysis as verified facts"
+- [ ] Prompt requires: "Label projections and forecasts clearly as such"
+- [ ] Prompt warns: "Avoid vague attributions like 'experts say' - name the expert/source"
+
+### Source Quality Guidance
+
+- [ ] Prompt specifies preferred sources (e.g., "Official docs > analyst reports > blog posts")
+- [ ] Prompt prioritizes recency: "Prioritize {{current_year}} sources for time-sensitive data"
+- [ ] Prompt requires credibility assessment: "Note source credibility for each citation"
+- [ ] Prompt warns against: "Do not rely on single blog posts for critical claims"
+
+### Anti-Hallucination Safeguards
+
+- [ ] Prompt warns: "If data seems convenient or too round, verify with additional sources"
+- [ ] Prompt instructs: "Flag suspicious claims that need third-party verification"
+- [ ] Prompt requires: "Provide date accessed for all web sources"
+- [ ] Prompt mandates: "Do NOT invent statistics - only use verified data"
+
+## Prompt Foundation
+
+### Topic and Scope
+
+- [ ] Research topic is specific and focused (not too broad)
+- [ ] Target platform is specified (ChatGPT, Gemini, Grok, Claude)
+- [ ] Temporal scope defined and includes "current {{current_year}}" requirement
+- [ ] Source recency requirement specified (e.g., "prioritize 2024-2025 sources")
+
+## Content Requirements
+
+### Information Specifications
+
+- [ ] Types of information needed are listed (quantitative, qualitative, trends, case studies, etc.)
+- [ ] Preferred sources are specified (academic, industry reports, news, etc.)
+- [ ] Recency requirements are stated (e.g., "prioritize {{current_year}} sources")
+- [ ] Keywords and technical terms are included for search optimization
+- [ ] Validation criteria are defined (how to verify findings)
+
+### Output Structure
+
+- [ ] Desired format is clear (executive summary, comparison table, timeline, SWOT, etc.)
+- [ ] Key sections or questions are outlined
+- [ ] Depth level is specified (overview, standard, comprehensive, exhaustive)
+- [ ] Citation requirements are stated
+- [ ] Any special formatting needs are mentioned
+
+## Platform Optimization
+
+### Platform-Specific Elements
+
+- [ ] Prompt is optimized for chosen platform's capabilities
+- [ ] Platform-specific tips are included
+- [ ] Query limit considerations are noted (if applicable)
+- [ ] Platform strengths are leveraged (e.g., ChatGPT's multi-step search, Gemini's plan modification)
+
+### Execution Guidance
+
+- [ ] Research persona/perspective is specified (if applicable)
+- [ ] Special requirements are stated (bias considerations, recency, etc.)
+- [ ] Follow-up strategy is outlined
+- [ ] Validation approach is defined
+
+## Quality and Usability
+
+### Clarity and Completeness
+
+- [ ] Prompt language is clear and unambiguous
+- [ ] All placeholders and variables are replaced with actual values
+- [ ] Prompt can be copy-pasted directly into platform
+- [ ] No contradictory instructions exist
+- [ ] Prompt is self-contained (doesn't assume unstated context)
+
+### Practical Utility
+
+- [ ] Execution checklist is provided (before, during, after research)
+- [ ] Platform usage tips are included
+- [ ] Follow-up questions are anticipated
+- [ ] Success criteria are defined
+- [ ] Output file format is specified
+
+## Research Depth
+
+### Scope Appropriateness
+
+- [ ] Scope matches user's available time and resources
+- [ ] Depth is appropriate for decision at hand
+- [ ] Key questions that MUST be answered are identified
+- [ ] Nice-to-have vs. critical information is distinguished
+
+## Validation Criteria
+
+### Quality Standards
+
+- [ ] Method for cross-referencing sources is specified
+- [ ] Approach to handling conflicting information is defined
+- [ ] Confidence level indicators are requested
+- [ ] Gap identification is included
+- [ ] Fact vs. opinion distinction is required
+
+---
+
+## Issues Found
+
+### Critical Issues
+
+_List any critical gaps or errors that must be addressed:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Minor Improvements
+
+_List minor improvements that would enhance the prompt:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+---
+
+**Validation Complete:** ☐ Yes ☐ No
+**Ready to Execute:** ☐ Yes ☐ No
+**Reviewer:** \***\*\_\*\***
+**Date:** \***\*\_\*\***

.bmad/bmm/workflows/1-analysis/research/checklist-technical.md

@@ -0,0 +1,249 @@
+# Technical/Architecture Research Validation Checklist
+
+## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
+
+### Version Number Verification (MANDATORY)
+
+- [ ] **EVERY** technology version number has cited source with URL
+- [ ] Version numbers verified via WebSearch from {{current_year}} (NOT from training data!)
+- [ ] Official documentation/release pages cited for each version
+- [ ] Release dates included with version numbers
+- [ ] LTS status verified from official sources (with URL)
+- [ ] No "assumed" or "remembered" version numbers - ALL must be verified
+
+### Technical Claim Source Verification
+
+- [ ] **EVERY** feature claim has source (official docs, release notes, website)
+- [ ] Performance benchmarks cite source (official benchmarks, third-party tests with URLs)
+- [ ] Compatibility claims verified (official compatibility matrix, documentation)
+- [ ] Community size/popularity backed by sources (GitHub stars, npm downloads, official stats)
+- [ ] "Supports X" claims verified via official documentation with URL
+- [ ] No invented capabilities or features
+
+### Source Quality for Technical Data
+
+- [ ] Official documentation prioritized (docs.technology.com > blog posts)
+- [ ] Version info from official release pages (highest credibility)
+- [ ] Benchmarks from official sources or reputable third-parties (not random blogs)
+- [ ] Community data from verified sources (GitHub, npm, official registries)
+- [ ] Pricing from official pricing pages (with URL and date verified)
+
+### Multi-Source Verification (Critical Technical Claims)
+
+- [ ] Major technical claims (performance, scalability) verified by 2+ sources
+- [ ] Technology comparisons cite multiple independent sources
+- [ ] "Best for X" claims backed by comparative analysis with sources
+- [ ] Production experience claims cite real case studies or articles with URLs
+- [ ] No single-source critical decisions without flagging need for verification
+
+### Anti-Hallucination for Technical Data
+
+- [ ] No invented version numbers or release dates
+- [ ] No assumed feature availability without verification
+- [ ] If current data not found, explicitly states "Could not verify {{current_year}} information"
+- [ ] Speculation clearly labeled (e.g., "Based on trends, technology may...")
+- [ ] No "probably supports" or "likely compatible" without verification
+
+## Technology Evaluation
+
+### Comprehensive Profiling
+
+For each evaluated technology:
+
+- [ ] Core capabilities and features are documented
+- [ ] Architecture and design philosophy are explained
+- [ ] Maturity level is assessed (experimental, stable, mature, legacy)
+- [ ] Community size and activity are measured
+- [ ] Maintenance status is verified (active, maintenance mode, abandoned)
+
+### Practical Considerations
+
+- [ ] Learning curve is evaluated
+- [ ] Documentation quality is assessed
+- [ ] Developer experience is considered
+- [ ] Tooling ecosystem is reviewed
+- [ ] Testing and debugging capabilities are examined
+
+### Operational Assessment
+
+- [ ] Deployment complexity is understood
+- [ ] Monitoring and observability options are evaluated
+- [ ] Operational overhead is estimated
+- [ ] Cloud provider support is verified
+- [ ] Container/Kubernetes compatibility is checked (if relevant)
+
+## Comparative Analysis
+
+### Multi-Dimensional Comparison
+
+- [ ] Technologies are compared across relevant dimensions
+- [ ] Performance benchmarks are included (if available)
+- [ ] Scalability characteristics are compared
+- [ ] Complexity trade-offs are analyzed
+- [ ] Total cost of ownership is estimated for each option
+
+### Trade-off Analysis
+
+- [ ] Key trade-offs between options are identified
+- [ ] Decision factors are prioritized based on user needs
+- [ ] Conditions favoring each option are specified
+- [ ] Weighted analysis reflects user's priorities
+
+## Real-World Evidence
+
+### Production Experience
+
+- [ ] Real-world production experiences are researched
+- [ ] Known issues and gotchas are documented
+- [ ] Performance data from actual deployments is included
+- [ ] Migration experiences are considered (if replacing existing tech)
+- [ ] Community discussions and war stories are referenced
+
+### Source Quality
+
+- [ ] Multiple independent sources validate key claims
+- [ ] Recent sources from {{current_year}} are prioritized
+- [ ] Practitioner experiences are included (blog posts, conference talks, forums)
+- [ ] Both proponent and critic perspectives are considered
+
+## Decision Support
+
+### Recommendations
+
+- [ ] Primary recommendation is clearly stated with rationale
+- [ ] Alternative options are explained with use cases
+- [ ] Fit for user's specific context is explained
+- [ ] Decision is justified by requirements and constraints
+
+### Implementation Guidance
+
+- [ ] Proof-of-concept approach is outlined
+- [ ] Key implementation decisions are identified
+- [ ] Migration path is described (if applicable)
+- [ ] Success criteria are defined
+- [ ] Validation approach is recommended
+
+### Risk Management
+
+- [ ] Technical risks are identified
+- [ ] Mitigation strategies are provided
+- [ ] Contingency options are outlined (if primary choice doesn't work)
+- [ ] Exit strategy considerations are discussed
+
+## Architecture Decision Record
+
+### ADR Completeness
+
+- [ ] Status is specified (Proposed, Accepted, Superseded)
+- [ ] Context and problem statement are clear
+- [ ] Decision drivers are documented
+- [ ] All considered options are listed
+- [ ] Chosen option and rationale are explained
+- [ ] Consequences (positive, negative, neutral) are identified
+- [ ] Implementation notes are included
+- [ ] References to research sources are provided
+
+## References and Source Documentation (CRITICAL)
+
+### References Section Completeness
+
+- [ ] Report includes comprehensive "References and Sources" section
+- [ ] Sources organized by category (official docs, benchmarks, community, architecture)
+- [ ] Every source includes: Title, Publisher/Site, Date Accessed, Full URL
+- [ ] URLs are clickable and functional (documentation links, release pages, GitHub)
+- [ ] Version verification sources clearly listed
+- [ ] Inline citations throughout report reference the sources section
+
+### Technology Source Documentation
+
+- [ ] For each technology evaluated, sources documented:
+  - Official documentation URL
+  - Release notes/changelog URL for version
+  - Pricing page URL (if applicable)
+  - Community/GitHub URL
+  - Benchmark source URLs
+- [ ] Comparison data cites source for each claim
+- [ ] Architecture pattern sources cited (articles, books, official guides)
+
+### Source Quality Metrics
+
+- [ ] Report documents total sources cited
+- [ ] Official sources count (highest credibility)
+- [ ] Third-party sources count (benchmarks, articles)
+- [ ] Version verification count (all technologies verified {{current_year}})
+- [ ] Outdated sources flagged (if any used)
+
+### Citation Format Standards
+
+- [ ] Inline citations format: [Source: Docs URL] or [Version: 1.2.3, Source: Release Page URL]
+- [ ] Consistent citation style throughout
+- [ ] No vague citations like "according to the community" without specifics
+- [ ] GitHub links include star count and last update date
+- [ ] Documentation links point to current stable version docs
+
+## Document Quality
+
+### Anti-Hallucination Final Check
+
+- [ ] Spot-check 5 random version numbers - can you find the cited source?
+- [ ] Verify feature claims against official documentation
+- [ ] Check any performance numbers have benchmark sources
+- [ ] Ensure no "cutting edge" or "latest" without specific version number
+- [ ] Cross-check technology comparisons with cited sources
+
+### Structure and Completeness
+
+- [ ] Executive summary captures key findings
+- [ ] No placeholder text remains (all {{variables}} are replaced)
+- [ ] References section is complete and properly formatted
+- [ ] Version verification audit trail included
+- [ ] Document ready for technical fact-checking by third party
+
+## Research Completeness
+
+### Coverage
+
+- [ ] All user requirements were addressed
+- [ ] All constraints were considered
+- [ ] Sufficient depth for the decision at hand
+- [ ] Optional analyses were considered and included/excluded appropriately
+- [ ] Web research was conducted for current market data
+
+### Data Freshness
+
+- [ ] Current {{current_year}} data was used throughout
+- [ ] Version information is up-to-date
+- [ ] Recent developments and trends are included
+- [ ] Outdated or deprecated information is flagged or excluded
+
+---
+
+## Issues Found
+
+### Critical Issues
+
+_List any critical gaps or errors that must be addressed:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Minor Improvements
+
+_List minor improvements that would enhance the report:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Additional Research Needed
+
+_List areas requiring further investigation:_
+
+- [ ] Topic 1: [Description]
+- [ ] Topic 2: [Description]
+
+---
+
+**Validation Complete:** ☐ Yes ☐ No
+**Ready for Decision:** ☐ Yes ☐ No
+**Reviewer:** \***\*\_\*\***
+**Date:** \***\*\_\*\***

.bmad/bmm/workflows/1-analysis/research/checklist.md

@@ -0,0 +1,299 @@
+# Market Research Report Validation Checklist
+
+## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
+
+### Source Citation Completeness
+
+- [ ] **EVERY** market size claim has at least 2 cited sources with URLs
+- [ ] **EVERY** growth rate/CAGR has cited sources with URLs
+- [ ] **EVERY** competitive data point (pricing, features, funding) has sources with URLs
+- [ ] **EVERY** customer statistic or insight has cited sources
+- [ ] **EVERY** industry trend claim has sources from {{current_year}} or recent years
+- [ ] All sources include: Name, Date, URL (clickable links)
+- [ ] No claims exist without verifiable sources
+
+### Source Quality and Credibility
+
+- [ ] Market size sources are HIGH credibility (Gartner, Forrester, IDC, government data, industry associations)
+- [ ] NOT relying on single blog posts or unverified sources for critical data
+- [ ] Sources are recent ({{current_year}} or within 1-2 years for time-sensitive data)
+- [ ] Primary sources prioritized over secondary/tertiary sources
+- [ ] Paywalled reports are cited with proper attribution (e.g., "Gartner Market Report 2025")
+
+### Multi-Source Verification (Critical Claims)
+
+- [ ] TAM calculation verified by at least 2 independent sources
+- [ ] SAM calculation methodology is transparent and sourced
+- [ ] SOM estimates are conservative and based on comparable benchmarks
+- [ ] Market growth rates corroborated by multiple analyst reports
+- [ ] Competitive market share data verified across sources
+
+### Conflicting Data Resolution
+
+- [ ] Where sources conflict, ALL conflicting estimates are presented
+- [ ] Variance between sources is explained (methodology, scope differences)
+- [ ] No arbitrary selection of "convenient" numbers without noting alternatives
+- [ ] Conflicting data is flagged with confidence levels
+- [ ] User is made aware of uncertainty in conflicting claims
+
+### Confidence Level Marking
+
+- [ ] Every major claim is marked with confidence level:
+  - **[Verified - 2+ sources]** = High confidence, multiple independent sources agree
+  - **[Single source - verify]** = Medium confidence, only one source found
+  - **[Estimated - low confidence]** = Low confidence, calculated/projected without strong sources
+- [ ] Low confidence claims are clearly flagged for user to verify independently
+- [ ] Speculative/projected data is labeled as PROJECTION or FORECAST, not presented as fact
+
+### Fact vs Analysis vs Speculation
+
+- [ ] Clear distinction between:
+  - **FACT:** Sourced data with citations (e.g., "Market is $5.2B [Source: Gartner 2025]")
+  - **ANALYSIS:** Interpretation of facts (e.g., "This suggests strong growth momentum")
+  - **SPECULATION:** Educated guesses (e.g., "This trend may continue if...")
+- [ ] Analysis and speculation are NOT presented as verified facts
+- [ ] Recommendations are based on sourced facts, not unsupported assumptions
+
+### Anti-Hallucination Verification
+
+- [ ] No invented statistics or "made up" market sizes
+- [ ] All percentages, dollar amounts, and growth rates are traceable to sources
+- [ ] If data couldn't be found, report explicitly states "No verified data available for [X]"
+- [ ] No use of vague sources like "industry experts say" without naming the expert/source
+- [ ] Version numbers, dates, and specific figures match source material exactly
+
+## Market Sizing Analysis (Source-Verified)
+
+### TAM Calculation Sources
+
+- [ ] TAM figure has at least 2 independent source citations
+- [ ] Calculation methodology is sourced (not invented)
+- [ ] Industry benchmarks used for sanity-check are cited
+- [ ] Growth rate assumptions are backed by sourced projections
+- [ ] Any adjustments or filters applied are justified and documented
+
+### SAM and SOM Source Verification
+
+- [ ] SAM constraints are based on sourced data (addressable market scope)
+- [ ] SOM competitive assumptions cite actual competitor data
+- [ ] Market share benchmarks reference comparable companies with sources
+- [ ] Scenarios (conservative/realistic/optimistic) are justified with sourced reasoning
+
+## Competitive Analysis (Source-Verified)
+
+### Competitor Data Source Verification
+
+- [ ] **EVERY** competitor mentioned has source for basic company info
+- [ ] Competitor pricing data has sources (website URLs, pricing pages, reviews)
+- [ ] Funding amounts cite sources (Crunchbase, press releases, SEC filings)
+- [ ] Product features verified through sources (official website, documentation, reviews)
+- [ ] Market positioning claims are backed by sources (analyst reports, company statements)
+- [ ] Customer count/user numbers cite sources (company announcements, verified reports)
+- [ ] Recent news and developments cite article URLs with dates from {{current_year}}
+
+### Competitive Data Credibility
+
+- [ ] Company websites/official sources used for product info (highest credibility)
+- [ ] Financial data from Crunchbase, PitchBook, or SEC filings (not rumors)
+- [ ] Review sites cited for customer sentiment (G2, Capterra, TrustPilot with URLs)
+- [ ] Pricing verified from official pricing pages (with URL and date checked)
+- [ ] No assumptions about competitors without sourced evidence
+
+### Competitive Claims Verification
+
+- [ ] Market share claims cite analyst reports or verified data
+- [ ] "Leading" or "dominant" claims backed by sourced market data
+- [ ] Competitor weaknesses cited from reviews, articles, or public statements (not speculation)
+- [ ] Product comparison claims verified (feature lists from official sources)
+
+## Customer Intelligence (Source-Verified)
+
+### Customer Data Sources
+
+- [ ] Customer segment data cites research sources (reports, surveys, studies)
+- [ ] Demographics/firmographics backed by census data, industry reports, or studies
+- [ ] Pain points sourced from customer research, reviews, surveys (not assumed)
+- [ ] Willingness to pay backed by pricing studies, surveys, or comparable market data
+- [ ] Buying behavior sourced from research studies or industry data
+- [ ] Jobs-to-be-Done insights cite customer research or validated frameworks
+
+### Customer Insight Credibility
+
+- [ ] Primary research (if conducted) documents sample size and methodology
+- [ ] Secondary research cites the original study/report with full attribution
+- [ ] Customer quotes or testimonials cite the source (interview, review site, case study)
+- [ ] Persona data based on real research findings (not fictional archetypes)
+- [ ] No invented customer statistics or behaviors without source backing
+
+### Positioning Analysis
+
+- [ ] Market positioning map uses relevant dimensions for the industry
+- [ ] White space opportunities are clearly identified
+- [ ] Differentiation strategy is supported by competitive gaps
+- [ ] Switching costs and barriers are quantified
+- [ ] Network effects and moats are assessed
+
+## Industry Analysis
+
+### Porter's Five Forces
+
+- [ ] Each force has a clear rating (Low/Medium/High) with justification
+- [ ] Specific examples and evidence support each assessment
+- [ ] Industry-specific factors are considered (not generic template)
+- [ ] Implications for strategy are drawn from each force
+- [ ] Overall industry attractiveness conclusion is provided
+
+### Trends and Dynamics
+
+- [ ] At least 5 major trends are identified with evidence
+- [ ] Technology disruptions are assessed for probability and timeline
+- [ ] Regulatory changes and their impacts are documented
+- [ ] Social/cultural shifts relevant to adoption are included
+- [ ] Market maturity stage is identified with supporting indicators
+
+## Strategic Recommendations
+
+### Go-to-Market Strategy
+
+- [ ] Target segment prioritization has clear rationale
+- [ ] Positioning statement is specific and differentiated
+- [ ] Channel strategy aligns with customer buying behavior
+- [ ] Partnership opportunities are identified with specific targets
+- [ ] Pricing strategy is justified by willingness-to-pay analysis
+
+### Opportunity Assessment
+
+- [ ] Each opportunity is sized quantitatively
+- [ ] Resource requirements are estimated (time, money, people)
+- [ ] Success criteria are measurable and time-bound
+- [ ] Dependencies and prerequisites are identified
+- [ ] Quick wins vs. long-term plays are distinguished
+
+### Risk Analysis
+
+- [ ] All major risk categories are covered (market, competitive, execution, regulatory)
+- [ ] Each risk has probability and impact assessment
+- [ ] Mitigation strategies are specific and actionable
+- [ ] Early warning indicators are defined
+- [ ] Contingency plans are outlined for high-impact risks
+
+## References and Source Documentation (CRITICAL)
+
+### References Section Completeness
+
+- [ ] Report includes comprehensive "References and Sources" section
+- [ ] Sources organized by category (market size, competitive, customer, trends)
+- [ ] Every source includes: Title/Name, Publisher, Date, Full URL
+- [ ] URLs are clickable and functional (not broken links)
+- [ ] Sources are numbered or organized for easy reference
+- [ ] Inline citations throughout report reference the sources section
+
+### Source Quality Metrics
+
+- [ ] Report documents total sources cited count
+- [ ] High confidence claims (2+ sources) count is reported
+- [ ] Single source claims are identified and counted
+- [ ] Low confidence/speculative claims are flagged
+- [ ] Web searches conducted count is included (for transparency)
+
+### Source Audit Trail
+
+- [ ] For each major section, sources are listed
+- [ ] TAM/SAM/SOM calculations show source for each number
+- [ ] Competitive data shows source for each competitor profile
+- [ ] Customer insights show research sources
+- [ ] Industry trends show article/report sources with dates
+
+### Citation Format Standards
+
+- [ ] Inline citations format: [Source: Company/Publication, Year, URL] or similar
+- [ ] Consistent citation style throughout document
+- [ ] No vague citations like "according to sources" without specifics
+- [ ] URLs are complete (not truncated)
+- [ ] Accessed/verified dates included for web sources
+
+## Document Quality
+
+### Anti-Hallucination Final Check
+
+- [ ] Read through entire report - does anything "feel" invented or too convenient?
+- [ ] Spot-check 5-10 random claims - can you find the cited source?
+- [ ] Check suspicious round numbers - are they actually from sources?
+- [ ] Verify any "shocking" statistics have strong sources
+- [ ] Cross-check key market size claims against multiple cited sources
+
+### Structure and Completeness
+
+- [ ] Executive summary captures all key insights
+- [ ] No placeholder text remains (all {{variables}} are replaced)
+- [ ] References section is complete and properly formatted
+- [ ] Source quality assessment included
+- [ ] Document ready for fact-checking by third party
+
+## Research Completeness
+
+### Coverage Check
+
+- [ ] All workflow steps were completed (none skipped without justification)
+- [ ] Optional analyses were considered and included where valuable
+- [ ] Web research was conducted for current market intelligence
+- [ ] Financial projections align with market size analysis
+- [ ] Implementation roadmap provides clear next steps
+
+### Validation
+
+- [ ] Key findings are triangulated across multiple sources
+- [ ] Surprising insights are double-checked for accuracy
+- [ ] Calculations are verified for mathematical accuracy
+- [ ] Conclusions logically follow from the analysis
+- [ ] Recommendations are actionable and specific
+
+## Final Quality Assurance
+
+### Ready for Decision-Making
+
+- [ ] Research answers all initial objectives
+- [ ] Sufficient detail for investment decisions
+- [ ] Clear go/no-go recommendation provided
+- [ ] Success metrics are defined
+- [ ] Follow-up research needs are identified
+
+### Document Meta
+
+- [ ] Research date is current
+- [ ] Confidence levels are indicated for key assertions
+- [ ] Next review date is set
+- [ ] Distribution list is appropriate
+- [ ] Confidentiality classification is marked
+
+---
+
+## Issues Found
+
+### Critical Issues
+
+_List any critical gaps or errors that must be addressed:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Minor Issues
+
+_List minor improvements that would enhance the report:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Additional Research Needed
+
+_List areas requiring further investigation:_
+
+- [ ] Topic 1: [Description]
+- [ ] Topic 2: [Description]
+
+---
+
+**Validation Complete:** ☐ Yes ☐ No
+**Ready for Distribution:** ☐ Yes ☐ No
+**Reviewer:** **\*\***\_\_\_\_**\*\***
+**Date:** **\*\***\_\_\_\_**\*\***

.bmad/bmm/workflows/1-analysis/research/claude-code/injections.yaml

@@ -0,0 +1,114 @@
+# Market Research Workflow - Claude Code Integration Configuration
+# This file configures how subagents are installed and integrated
+
+subagents:
+  # List of subagent files to be installed
+  files:
+    - bmm-market-researcher.md
+    - bmm-trend-spotter.md
+    - bmm-data-analyst.md
+    - bmm-competitor-analyzer.md
+    - bmm-user-researcher.md
+
+  # Installation configuration
+  installation:
+    prompt: "The Market Research workflow includes specialized AI subagents for enhanced research capabilities. Would you like to install them?"
+    location_options:
+      - project # Install to .claude/agents/ in project
+      - user # Install to ~/.claude/agents/ for all projects
+    default_location: project
+
+# Content injections for the workflow
+injections:
+  - injection_point: "market-research-subagents"
+    description: "Injects subagent activation instructions into the workflow"
+    content: |
+      <critical>
+      Claude Code Enhanced Mode: The following specialized subagents are available to enhance your market research:
+
+      - **bmm-market-researcher**: Comprehensive market intelligence gathering and analysis
+      - **bmm-trend-spotter**: Identifies emerging trends and weak signals
+      - **bmm-data-analyst**: Quantitative analysis and market sizing calculations
+      - **bmm-competitor-analyzer**: Deep competitive intelligence and positioning
+      - **bmm-user-researcher**: User research, personas, and journey mapping
+
+      These subagents will be automatically invoked when their expertise is relevant to the current research task.
+      Use them PROACTIVELY throughout the workflow for enhanced insights.
+      </critical>
+
+  - injection_point: "market-tam-calculations"
+    description: "Enhanced TAM calculation with data analyst"
+    content: |
+      <invoke-subagent name="bmm-data-analyst">
+      Calculate TAM using multiple methodologies and provide confidence intervals.
+      Use all available market data from previous research steps.
+      Show detailed calculations and assumptions.
+      </invoke-subagent>
+
+  - injection_point: "market-trends-analysis"
+    description: "Enhanced trend analysis with trend spotter"
+    content: |
+      <invoke-subagent name="bmm-trend-spotter">
+      Identify emerging trends, weak signals, and future disruptions.
+      Look for cross-industry patterns and second-order effects.
+      Provide timeline estimates for mainstream adoption.
+      </invoke-subagent>
+
+  - injection_point: "market-customer-segments"
+    description: "Enhanced customer research"
+    content: |
+      <invoke-subagent name="bmm-user-researcher">
+      Develop detailed user personas with jobs-to-be-done analysis.
+      Map the complete customer journey with pain points and opportunities.
+      Provide behavioral and psychographic insights.
+      </invoke-subagent>
+
+  - injection_point: "market-executive-summary"
+    description: "Enhanced executive summary synthesis"
+    content: |
+      <invoke-subagent name="bmm-market-researcher">
+      Synthesize all research findings into a compelling executive summary.
+      Highlight the most critical insights and strategic implications.
+      Ensure all key metrics and recommendations are captured.
+      </invoke-subagent>
+
+# Configuration for subagent behavior
+configuration:
+  auto_invoke: true # Automatically invoke subagents when relevant
+  parallel_execution: true # Allow parallel subagent execution
+  cache_results: true # Cache subagent outputs for reuse
+
+  # Subagent-specific configurations
+  subagent_config:
+    bmm-market-researcher:
+      priority: high
+      max_execution_time: 300 # seconds
+      retry_on_failure: true
+
+    bmm-trend-spotter:
+      priority: medium
+      max_execution_time: 180
+      retry_on_failure: false
+
+    bmm-data-analyst:
+      priority: high
+      max_execution_time: 240
+      retry_on_failure: true
+
+    bmm-competitor-analyzer:
+      priority: high
+      max_execution_time: 300
+      retry_on_failure: true
+
+    bmm-user-researcher:
+      priority: medium
+      max_execution_time: 240
+      retry_on_failure: false
+
+# Metadata
+metadata:
+  compatible_with: "claude-code-1.0+"
+  workflow: "market-research"
+  module: "bmm"
+  author: "BMad Builder"
+  description: "Claude Code enhancements for comprehensive market research"

.bmad/bmm/workflows/1-analysis/research/instructions-deep-prompt.md

@@ -0,0 +1,439 @@
+# Deep Research Prompt Generator Instructions
+
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
+<critical>This workflow generates structured research prompts optimized for AI platforms</critical>
+<critical>Based on {{current_year}} best practices from ChatGPT, Gemini, Grok, and Claude</critical>
+<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>🚨 BUILD ANTI-HALLUCINATION INTO PROMPTS 🚨</critical>
+<critical>Generated prompts MUST instruct AI to cite sources with URLs for all factual claims</critical>
+<critical>Include validation requirements: "Cross-reference claims with at least 2 independent sources"</critical>
+<critical>Add explicit instructions: "If you cannot find reliable data, state 'No verified data found for [X]'"</critical>
+<critical>Require confidence indicators in prompts: "Mark each claim with confidence level and source quality"</critical>
+<critical>Include fact-checking instructions: "Distinguish between verified facts, analysis, and speculation"</critical>
+
+<workflow>
+
+<step n="1" goal="Discover what research prompt they need">
+
+<action>Engage conversationally to understand their needs:
+
+<check if="{user_skill_level} == 'expert'">
+  "Let's craft a research prompt optimized for AI deep research tools.
+
+What topic or question do you want to investigate, and which platform are you planning to use? (ChatGPT Deep Research, Gemini, Grok, Claude Projects)"
+</check>
+
+<check if="{user_skill_level} == 'intermediate'">
+  "I'll help you create a structured research prompt for AI platforms like ChatGPT Deep Research, Gemini, or Grok.
+
+These tools work best with well-structured prompts that define scope, sources, and output format.
+
+What do you want to research?"
+</check>
+
+<check if="{user_skill_level} == 'beginner'">
+  "Think of this as creating a detailed brief for an AI research assistant.
+
+Tools like ChatGPT Deep Research can spend hours searching the web and synthesizing information - but they work best when you give them clear instructions about what to look for and how to present it.
+
+What topic are you curious about?"
+</check>
+</action>
+
+<action>Through conversation, discover:
+
+- **The research topic** - What they want to explore
+- **Their purpose** - Why they need this (decision-making, learning, writing, etc.)
+- **Target platform** - Which AI tool they'll use (affects prompt structure)
+- **Existing knowledge** - What they already know vs. what's uncertain
+
+Adapt your questions based on their clarity:
+
+- If they're vague → Help them sharpen the focus
+- If they're specific → Capture the details
+- If they're unsure about platform → Guide them to the best fit
+
+Don't make them fill out a form - have a real conversation.
+</action>
+
+<template-output>research_topic</template-output>
+<template-output>research_goal</template-output>
+<template-output>target_platform</template-output>
+
+</step>
+
+<step n="2" goal="Define Research Scope and Boundaries">
+<action>Help user define clear boundaries for focused research</action>
+
+**Let's define the scope to ensure focused, actionable results:**
+
+<ask>**Temporal Scope** - What time period should the research cover?
+
+- Current state only (last 6-12 months)
+- Recent trends (last 2-3 years)
+- Historical context (5-10 years)
+- Future outlook (projections 3-5 years)
+- Custom date range (specify)</ask>
+
+<template-output>temporal_scope</template-output>
+
+<ask>**Geographic Scope** - What geographic focus?
+
+- Global
+- Regional (North America, Europe, Asia-Pacific, etc.)
+- Specific countries
+- US-focused
+- Other (specify)</ask>
+
+<template-output>geographic_scope</template-output>
+
+<ask>**Thematic Boundaries** - Are there specific aspects to focus on or exclude?
+
+Examples:
+
+- Focus: technological innovation, regulatory changes, market dynamics
+- Exclude: historical background, unrelated adjacent markets</ask>
+
+<template-output>thematic_boundaries</template-output>
+
+</step>
+
+<step n="3" goal="Specify Information Types and Sources">
+<action>Determine what types of information and sources are needed</action>
+
+**What types of information do you need?**
+
+<ask>Select all that apply:
+
+- [ ] Quantitative data and statistics
+- [ ] Qualitative insights and expert opinions
+- [ ] Trends and patterns
+- [ ] Case studies and examples
+- [ ] Comparative analysis
+- [ ] Technical specifications
+- [ ] Regulatory and compliance information
+- [ ] Financial data
+- [ ] Academic research
+- [ ] Industry reports
+- [ ] News and current events</ask>
+
+<template-output>information_types</template-output>
+
+<ask>**Preferred Sources** - Any specific source types or credibility requirements?
+
+Examples:
+
+- Peer-reviewed academic journals
+- Industry analyst reports (Gartner, Forrester, IDC)
+- Government/regulatory sources
+- Financial reports and SEC filings
+- Technical documentation
+- News from major publications
+- Expert blogs and thought leadership
+- Social media and forums (with caveats)</ask>
+
+<template-output>preferred_sources</template-output>
+
+</step>
+
+<step n="4" goal="Define Output Structure and Format">
+<action>Specify desired output format for the research</action>
+
+<ask>**Output Format** - How should the research be structured?
+
+1. Executive Summary + Detailed Sections
+2. Comparative Analysis Table
+3. Chronological Timeline
+4. SWOT Analysis Framework
+5. Problem-Solution-Impact Format
+6. Question-Answer Format
+7. Custom structure (describe)</ask>
+
+<template-output>output_format</template-output>
+
+<ask>**Key Sections** - What specific sections or questions should the research address?
+
+Examples for market research:
+
+- Market size and growth
+- Key players and competitive landscape
+- Trends and drivers
+- Challenges and barriers
+- Future outlook
+
+Examples for technical research:
+
+- Current state of technology
+- Alternative approaches and trade-offs
+- Best practices and patterns
+- Implementation considerations
+- Tool/framework comparison</ask>
+
+<template-output>key_sections</template-output>
+
+<ask>**Depth Level** - How detailed should each section be?
+
+- High-level overview (2-3 paragraphs per section)
+- Standard depth (1-2 pages per section)
+- Comprehensive (3-5 pages per section with examples)
+- Exhaustive (deep dive with all available data)</ask>
+
+<template-output>depth_level</template-output>
+
+</step>
+
+<step n="5" goal="Add Context and Constraints">
+<action>Gather additional context to make the prompt more effective</action>
+
+<ask>**Persona/Perspective** - Should the research take a specific viewpoint?
+
+Examples:
+
+- "Act as a venture capital analyst evaluating investment opportunities"
+- "Act as a CTO evaluating technology choices for a fintech startup"
+- "Act as an academic researcher reviewing literature"
+- "Act as a product manager assessing market opportunities"
+- No specific persona needed</ask>
+
+<template-output>research_persona</template-output>
+
+<ask>**Special Requirements or Constraints:**
+
+- Citation requirements (e.g., "Include source URLs for all claims")
+- Bias considerations (e.g., "Consider perspectives from both proponents and critics")
+- Recency requirements (e.g., "Prioritize sources from 2024-2025")
+- Specific keywords or technical terms to focus on
+- Any topics or angles to avoid</ask>
+
+<template-output>special_requirements</template-output>
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+
+</step>
+
+<step n="6" goal="Define Validation and Follow-up Strategy">
+<action>Establish how to validate findings and what follow-ups might be needed</action>
+
+<ask>**Validation Criteria** - How should the research be validated?
+
+- Cross-reference multiple sources for key claims
+- Identify conflicting viewpoints and resolve them
+- Distinguish between facts, expert opinions, and speculation
+- Note confidence levels for different findings
+- Highlight gaps or areas needing more research</ask>
+
+<template-output>validation_criteria</template-output>
+
+<ask>**Follow-up Questions** - What potential follow-up questions should be anticipated?
+
+Examples:
+
+- "If cost data is unclear, drill deeper into pricing models"
+- "If regulatory landscape is complex, create separate analysis"
+- "If multiple technical approaches exist, create comparison matrix"</ask>
+
+<template-output>follow_up_strategy</template-output>
+
+</step>
+
+<step n="7" goal="Generate Optimized Research Prompt">
+<action>Synthesize all inputs into platform-optimized research prompt</action>
+
+<critical>Generate the deep research prompt using best practices for the target platform</critical>
+
+**Prompt Structure Best Practices:**
+
+1. **Clear Title/Question** (specific, focused)
+2. **Context and Goal** (why this research matters)
+3. **Scope Definition** (boundaries and constraints)
+4. **Information Requirements** (what types of data/insights)
+5. **Output Structure** (format and sections)
+6. **Source Guidance** (preferred sources and credibility)
+7. **Validation Requirements** (how to verify findings)
+8. **Keywords** (precise technical terms, brand names)
+
+<action>Generate prompt following this structure</action>
+
+<template-output file="deep-research-prompt.md">deep_research_prompt</template-output>
+
+<ask>Review the generated prompt:
+
+- [a] Accept and save
+- [e] Edit sections
+- [r] Refine with additional context
+- [o] Optimize for different platform</ask>
+
+<check if="edit or refine">
+  <ask>What would you like to adjust?</ask>
+  <goto step="7">Regenerate with modifications</goto>
+</check>
+
+</step>
+
+<step n="8" goal="Generate Platform-Specific Tips">
+<action>Provide platform-specific usage tips based on target platform</action>
+
+<check if="target_platform includes ChatGPT">
+  **ChatGPT Deep Research Tips:**
+
+- Use clear verbs: "compare," "analyze," "synthesize," "recommend"
+- Specify keywords explicitly to guide search
+- Answer clarifying questions thoroughly (requests are more expensive)
+- You have 25-250 queries/month depending on tier
+- Review the research plan before it starts searching
+  </check>
+
+<check if="target_platform includes Gemini">
+  **Gemini Deep Research Tips:**
+
+- Keep initial prompt simple - you can adjust the research plan
+- Be specific and clear - vagueness is the enemy
+- Review and modify the multi-point research plan before it runs
+- Use follow-up questions to drill deeper or add sections
+- Available in 45+ languages globally
+  </check>
+
+<check if="target_platform includes Grok">
+  **Grok DeepSearch Tips:**
+
+- Include date windows: "from Jan-Jun 2025"
+- Specify output format: "bullet list + citations"
+- Pair with Think Mode for reasoning
+- Use follow-up commands: "Expand on [topic]" to deepen sections
+- Verify facts when obscure sources cited
+- Free tier: 5 queries/24hrs, Premium: 30/2hrs
+  </check>
+
+<check if="target_platform includes Claude">
+  **Claude Projects Tips:**
+
+- Use Chain of Thought prompting for complex reasoning
+- Break into sub-prompts for multi-step research (prompt chaining)
+- Add relevant documents to Project for context
+- Provide explicit instructions and examples
+- Test iteratively and refine prompts
+  </check>
+
+<template-output>platform_tips</template-output>
+
+</step>
+
+<step n="9" goal="Generate Research Execution Checklist">
+<action>Create a checklist for executing and evaluating the research</action>
+
+Generate execution checklist with:
+
+**Before Running Research:**
+
+- [ ] Prompt clearly states the research question
+- [ ] Scope and boundaries are well-defined
+- [ ] Output format and structure specified
+- [ ] Keywords and technical terms included
+- [ ] Source guidance provided
+- [ ] Validation criteria clear
+
+**During Research:**
+
+- [ ] Review research plan before execution (if platform provides)
+- [ ] Answer any clarifying questions thoroughly
+- [ ] Monitor progress if platform shows reasoning process
+- [ ] Take notes on unexpected findings or gaps
+
+**After Research Completion:**
+
+- [ ] Verify key facts from multiple sources
+- [ ] Check citation credibility
+- [ ] Identify conflicting information and resolve
+- [ ] Note confidence levels for findings
+- [ ] Identify gaps requiring follow-up
+- [ ] Ask clarifying follow-up questions
+- [ ] Export/save research before query limit resets
+
+<template-output>execution_checklist</template-output>
+
+</step>
+
+<step n="10" goal="Finalize and Export">
+<action>Save complete research prompt package</action>
+
+**Your Deep Research Prompt Package is ready!**
+
+The output includes:
+
+1. **Optimized Research Prompt** - Ready to paste into AI platform
+2. **Platform-Specific Tips** - How to get the best results
+3. **Execution Checklist** - Ensure thorough research process
+4. **Follow-up Strategy** - Questions to deepen findings
+
+<action>Save all outputs to {default_output_file}</action>
+
+<ask>Would you like to:
+
+1. Generate a variation for a different platform
+2. Create a follow-up prompt based on hypothetical findings
+3. Generate a related research prompt
+4. Exit workflow
+
+Select option (1-4):</ask>
+
+<check if="option 1">
+  <goto step="1">Start with different platform selection</goto>
+</check>
+
+<check if="option 2 or 3">
+  <goto step="1">Start new prompt with context from previous</goto>
+</check>
+
+</step>
+
+<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-deep-prompt-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<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>**✅ Deep Research Prompt Generated**
+
+**Research Prompt:**
+
+- Structured research prompt generated and saved to {output_folder}/bmm-research-deep-prompt-{{date}}.md
+- Ready to execute with ChatGPT, Claude, Gemini, or Grok
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: research marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Execute the research prompt with AI platform, gather findings, or run additional research workflows
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Execute the research prompt with AI platform and gather findings
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/research/instructions-market.md

@@ -0,0 +1,679 @@
+# Market Research Workflow Instructions
+
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
+<critical>This is a HIGHLY INTERACTIVE workflow - collaborate with user throughout, don't just gather info and disappear</critical>
+<critical>Web research is MANDATORY - use WebSearch tool with {{current_year}} for all market intelligence gathering</critical>
+<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
+<critical>NEVER invent market data - if you cannot find reliable data, explicitly state: "I could not find verified data for [X]"</critical>
+<critical>EVERY statistic, market size, growth rate, or competitive claim MUST have a cited source with URL</critical>
+<critical>For CRITICAL claims (TAM/SAM/SOM, market size, growth rates), require 2+ independent sources that agree</critical>
+<critical>When data sources conflict (e.g., different market size estimates), present ALL estimates with sources and explain variance</critical>
+<critical>Mark data confidence: [Verified - 2+ sources], [Single source - verify], [Estimated - low confidence]</critical>
+<critical>Clearly label: FACT (sourced data), ANALYSIS (your interpretation), PROJECTION (forecast/speculation)</critical>
+<critical>After each WebSearch, extract and store source URLs - include them in the report</critical>
+<critical>If a claim seems suspicious or too convenient, STOP and cross-verify with additional searches</critical>
+
+<!-- IDE-INJECT-POINT: market-research-subagents -->
+
+<workflow>
+
+<step n="1" goal="Discover research needs and scope collaboratively">
+
+<action>Welcome {user_name} warmly. Position yourself as their collaborative research partner who will:
+
+- Gather live {{current_year}} market data
+- Share findings progressively throughout
+- Help make sense of what we discover together
+
+Ask what they're building and what market questions they need answered.
+</action>
+
+<action>Through natural conversation, discover:
+
+- The product/service and current stage
+- Their burning questions (what they REALLY need to know)
+- Context and urgency (fundraising? launch decision? pivot?)
+- Existing knowledge vs. uncertainties
+- Desired depth (gauge from their needs, don't ask them to choose)
+
+Adapt your approach: If uncertain → help them think it through. If detailed → dig deeper.
+
+Collaboratively define scope:
+
+- Markets/segments to focus on
+- Geographic boundaries
+- Critical questions vs. nice-to-have
+  </action>
+
+<action>Reflect understanding back to confirm you're aligned on what matters.</action>
+
+<template-output>product_name</template-output>
+<template-output>product_description</template-output>
+<template-output>research_objectives</template-output>
+<template-output>research_scope</template-output>
+</step>
+
+<step n="2" goal="Market Definition and Boundaries">
+<action>Help the user precisely define the market scope</action>
+
+Work with the user to establish:
+
+1. **Market Category Definition**
+   - Primary category/industry
+   - Adjacent or overlapping markets
+   - Where this fits in the value chain
+
+2. **Geographic Scope**
+   - Global, regional, or country-specific?
+   - Primary markets vs. expansion markets
+   - Regulatory considerations by region
+
+3. **Customer Segment Boundaries**
+   - B2B, B2C, or B2B2C?
+   - Primary vs. secondary segments
+   - Segment size estimates
+
+<ask>Should we include adjacent markets in the TAM calculation? This could significantly increase market size but may be less immediately addressable.</ask>
+
+<template-output>market_definition</template-output>
+<template-output>geographic_scope</template-output>
+<template-output>segment_boundaries</template-output>
+</step>
+
+<step n="3" goal="Gather live market intelligence collaboratively">
+
+<critical>This step REQUIRES WebSearch tool usage - gather CURRENT data from {{current_year}}</critical>
+<critical>Share findings as you go - make this collaborative, not a black box</critical>
+
+<action>Let {user_name} know you're searching for current {{market_category}} market data: size, growth, analyst reports, recent trends. Tell them you'll share what you find in a few minutes and review it together.</action>
+
+<step n="3a" title="Search for market size and industry data">
+<action>Conduct systematic web searches using WebSearch tool:
+
+<WebSearch>{{market_category}} market size {{geographic_scope}} {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} industry report Gartner Forrester IDC {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} market growth rate CAGR forecast {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} market trends {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} TAM SAM market opportunity {{current_year}}</WebSearch>
+</action>
+
+<action>Share findings WITH SOURCES including URLs and dates. Ask if it aligns with their expectations.</action>
+
+<action>CRITICAL - Validate data before proceeding:
+
+- Multiple sources with similar figures?
+- Recent sources ({{current_year}} or within 1-2 years)?
+- Credible sources (Gartner, Forrester, govt data, reputable pubs)?
+- Conflicts? Note explicitly, search for more sources, mark [Low Confidence]
+  </action>
+
+<action if="user_has_questions">Explore surprising data points together</action>
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+
+<template-output>sources_market_size</template-output>
+</step>
+
+<step n="3b" title="Search for recent news and developments" optional="true">
+<action>Search for recent market developments:
+
+<WebSearch>{{market_category}} news {{current_year}} funding acquisitions</WebSearch>
+<WebSearch>{{market_category}} recent developments {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} regulatory changes {{current_year}}</WebSearch>
+</action>
+
+<action>Share noteworthy findings:
+
+"I found some interesting recent developments:
+
+{{key_news_highlights}}
+
+Anything here surprise you or confirm what you suspected?"
+</action>
+</step>
+
+<step n="3c" title="Optional: Government and academic sources" optional="true">
+<action if="research needs high credibility">Search for authoritative sources:
+
+<WebSearch>{{market_category}} government statistics census data {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} academic research white papers {{current_year}}</WebSearch>
+</action>
+</step>
+
+<template-output>market_intelligence_raw</template-output>
+<template-output>key_data_points</template-output>
+<template-output>source_credibility_notes</template-output>
+</step>
+
+<step n="4" goal="TAM, SAM, SOM Calculations">
+<action>Calculate market sizes using multiple methodologies for triangulation</action>
+
+<critical>Use actual data gathered in previous steps, not hypothetical numbers</critical>
+
+<step n="4a" title="TAM Calculation">
+**Method 1: Top-Down Approach**
+- Start with total industry size from research
+- Apply relevant filters and segments
+- Show calculation: Industry Size × Relevant Percentage
+
+**Method 2: Bottom-Up Approach**
+
+- Number of potential customers × Average revenue per customer
+- Build from unit economics
+
+**Method 3: Value Theory Approach**
+
+- Value created × Capturable percentage
+- Based on problem severity and alternative costs
+
+<ask>Which TAM calculation method seems most credible given our data? Should we use multiple methods and triangulate?</ask>
+
+<template-output>tam_calculation</template-output>
+<template-output>tam_methodology</template-output>
+</step>
+
+<step n="4b" title="SAM Calculation">
+<action>Calculate Serviceable Addressable Market</action>
+
+Apply constraints to TAM:
+
+- Geographic limitations (markets you can serve)
+- Regulatory restrictions
+- Technical requirements (e.g., internet penetration)
+- Language/cultural barriers
+- Current business model limitations
+
+SAM = TAM × Serviceable Percentage
+Show the calculation with clear assumptions.
+
+<template-output>sam_calculation</template-output>
+</step>
+
+<step n="4c" title="SOM Calculation">
+<action>Calculate realistic market capture</action>
+
+Consider competitive dynamics:
+
+- Current market share of competitors
+- Your competitive advantages
+- Resource constraints
+- Time to market considerations
+- Customer acquisition capabilities
+
+Create 3 scenarios:
+
+1. Conservative (1-2% market share)
+2. Realistic (3-5% market share)
+3. Optimistic (5-10% market share)
+
+<template-output>som_scenarios</template-output>
+</step>
+</step>
+
+<step n="5" goal="Customer Segment Deep Dive">
+<action>Develop detailed understanding of target customers</action>
+
+<step n="5a" title="Segment Identification" repeat="for-each-segment">
+For each major segment, research and define:
+
+**Demographics/Firmographics:**
+
+- Size and scale characteristics
+- Geographic distribution
+- Industry/vertical (for B2B)
+
+**Psychographics:**
+
+- Values and priorities
+- Decision-making process
+- Technology adoption patterns
+
+**Behavioral Patterns:**
+
+- Current solutions used
+- Purchasing frequency
+- Budget allocation
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+<template-output>segment*profile*{{segment_number}}</template-output>
+</step>
+
+<step n="5b" title="Jobs-to-be-Done Framework">
+<action>Apply JTBD framework to understand customer needs</action>
+
+For primary segment, identify:
+
+**Functional Jobs:**
+
+- Main tasks to accomplish
+- Problems to solve
+- Goals to achieve
+
+**Emotional Jobs:**
+
+- Feelings sought
+- Anxieties to avoid
+- Status desires
+
+**Social Jobs:**
+
+- How they want to be perceived
+- Group dynamics
+- Peer influences
+
+<ask>Would you like to conduct actual customer interviews or surveys to validate these jobs? (We can create an interview guide)</ask>
+
+<template-output>jobs_to_be_done</template-output>
+</step>
+
+<step n="5c" title="Willingness to Pay Analysis">
+<action>Research and estimate pricing sensitivity</action>
+
+Analyze:
+
+- Current spending on alternatives
+- Budget allocation for this category
+- Value perception indicators
+- Price points of substitutes
+
+<template-output>pricing_analysis</template-output>
+</step>
+</step>
+
+<step n="6" goal="Understand the competitive landscape">
+<action>Ask if they know their main competitors or if you should search for them.</action>
+
+<step n="6a" title="Discover competitors together">
+<action if="user doesn't know competitors">Search for competitors:
+
+<WebSearch>{{product_category}} competitors {{geographic_scope}} {{current_year}}</WebSearch>
+<WebSearch>{{product_category}} alternatives comparison {{current_year}}</WebSearch>
+<WebSearch>top {{product_category}} companies {{current_year}}</WebSearch>
+</action>
+
+<action>Present findings. Ask them to pick the 3-5 that matter most (most concerned about or curious to understand).</action>
+</step>
+
+<step n="6b" title="Research each competitor together" repeat="for-each-selected-competitor">
+<action>For each competitor, search for:
+- Company overview, product features
+- Pricing model
+- Funding and recent news
+- Customer reviews and ratings
+
+Use {{current_year}} in all searches.
+</action>
+
+<action>Share findings with sources. Ask what jumps out and if it matches expectations.</action>
+
+<action if="user has follow-up questions">Dig deeper based on their interests</action>
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+<template-output>competitor*analysis*{{competitor_name}}</template-output>
+</step>
+
+<step n="6c" title="Competitive Positioning Map">
+<action>Create positioning analysis</action>
+
+Map competitors on key dimensions:
+
+- Price vs. Value
+- Feature completeness vs. Ease of use
+- Market segment focus
+- Technology approach
+- Business model
+
+Identify:
+
+- Gaps in the market
+- Over-served areas
+- Differentiation opportunities
+
+<template-output>competitive_positioning</template-output>
+</step>
+</step>
+
+<step n="7" goal="Industry Forces Analysis">
+<action>Apply Porter's Five Forces framework</action>
+
+<critical>Use specific evidence from research, not generic assessments</critical>
+
+Analyze each force with concrete examples:
+
+<step n="7a" title="Supplier Power">
+Rate: [Low/Medium/High]
+- Key suppliers and dependencies
+- Switching costs
+- Concentration of suppliers
+- Forward integration threat
+</step>
+
+<step n="7b" title="Buyer Power">
+Rate: [Low/Medium/High]
+- Customer concentration
+- Price sensitivity
+- Switching costs for customers
+- Backward integration threat
+</step>
+
+<step n="7c" title="Competitive Rivalry">
+Rate: [Low/Medium/High]
+- Number and strength of competitors
+- Industry growth rate
+- Exit barriers
+- Differentiation levels
+</step>
+
+<step n="7d" title="Threat of New Entry">
+Rate: [Low/Medium/High]
+- Capital requirements
+- Regulatory barriers
+- Network effects
+- Brand loyalty
+</step>
+
+<step n="7e" title="Threat of Substitutes">
+Rate: [Low/Medium/High]
+- Alternative solutions
+- Switching costs to substitutes
+- Price-performance trade-offs
+</step>
+
+<template-output>porters_five_forces</template-output>
+</step>
+
+<step n="8" goal="Market Trends and Future Outlook">
+<action>Identify trends and future market dynamics</action>
+
+Research and analyze:
+
+**Technology Trends:**
+
+- Emerging technologies impacting market
+- Digital transformation effects
+- Automation possibilities
+
+**Social/Cultural Trends:**
+
+- Changing customer behaviors
+- Generational shifts
+- Social movements impact
+
+**Economic Trends:**
+
+- Macroeconomic factors
+- Industry-specific economics
+- Investment trends
+
+**Regulatory Trends:**
+
+- Upcoming regulations
+- Compliance requirements
+- Policy direction
+
+<ask>Should we explore any specific emerging technologies or disruptions that could reshape this market?</ask>
+
+<template-output>market_trends</template-output>
+<template-output>future_outlook</template-output>
+</step>
+
+<step n="9" goal="Opportunity Assessment and Strategy">
+<action>Synthesize research into strategic opportunities</action>
+
+<step n="9a" title="Opportunity Identification">
+Based on all research, identify top 3-5 opportunities:
+
+For each opportunity:
+
+- Description and rationale
+- Size estimate (from SOM)
+- Resource requirements
+- Time to market
+- Risk assessment
+- Success criteria
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+<template-output>market_opportunities</template-output>
+</step>
+
+<step n="9b" title="Go-to-Market Recommendations">
+Develop GTM strategy based on research:
+
+**Positioning Strategy:**
+
+- Value proposition refinement
+- Differentiation approach
+- Messaging framework
+
+**Target Segment Sequencing:**
+
+- Beachhead market selection
+- Expansion sequence
+- Segment-specific approaches
+
+**Channel Strategy:**
+
+- Distribution channels
+- Partnership opportunities
+- Marketing channels
+
+**Pricing Strategy:**
+
+- Model recommendation
+- Price points
+- Value metrics
+
+<template-output>gtm_strategy</template-output>
+</step>
+
+<step n="9c" title="Risk Analysis">
+Identify and assess key risks:
+
+**Market Risks:**
+
+- Demand uncertainty
+- Market timing
+- Economic sensitivity
+
+**Competitive Risks:**
+
+- Competitor responses
+- New entrants
+- Technology disruption
+
+**Execution Risks:**
+
+- Resource requirements
+- Capability gaps
+- Scaling challenges
+
+For each risk: Impact (H/M/L) × Probability (H/M/L) = Risk Score
+Provide mitigation strategies.
+
+<template-output>risk_assessment</template-output>
+</step>
+</step>
+
+<step n="10" goal="Financial Projections" optional="true" if="enable_financial_modeling == true">
+<action>Create financial model based on market research</action>
+
+<ask>Would you like to create a financial model with revenue projections based on the market analysis?</ask>
+
+<check if="yes">
+  Build 3-year projections:
+
+- Revenue model based on SOM scenarios
+- Customer acquisition projections
+- Unit economics
+- Break-even analysis
+- Funding requirements
+
+<template-output>financial_projections</template-output>
+</check>
+
+</step>
+
+<step n="11" goal="Synthesize findings together into executive summary">
+
+<critical>This is the last major content section - make it collaborative</critical>
+
+<action>Review the research journey together. Share high-level summaries of market size, competitive dynamics, customer insights. Ask what stands out most - what surprised them or confirmed their thinking.</action>
+
+<action>Collaboratively craft the narrative:
+
+- What's the headline? (The ONE thing someone should know)
+- What are the 3-5 critical insights?
+- Recommended path forward?
+- Key risks?
+
+This should read like a strategic brief, not a data dump.
+</action>
+
+<action>Draft executive summary and share. Ask if it captures the essence and if anything is missing or overemphasized.</action>
+
+<template-output>executive_summary</template-output>
+</step>
+
+<step n="12" goal="Validate sources and compile report">
+
+<critical>MANDATORY SOURCE VALIDATION - Do NOT skip this step!</critical>
+
+<action>Before finalizing, conduct source audit:
+
+Review every major claim in the report and verify:
+
+**For Market Size Claims:**
+
+- [ ] At least 2 independent sources cited with URLs
+- [ ] Sources are from {{current_year}} or within 2 years
+- [ ] Sources are credible (Gartner, Forrester, govt data, reputable pubs)
+- [ ] Conflicting estimates are noted with all sources
+
+**For Competitive Data:**
+
+- [ ] Competitor information has source URLs
+- [ ] Pricing data is current and sourced
+- [ ] Funding data is verified with dates
+- [ ] Customer reviews/ratings have source links
+
+**For Growth Rates and Projections:**
+
+- [ ] CAGR and forecast data are sourced
+- [ ] Methodology is explained or linked
+- [ ] Multiple analyst estimates are compared if available
+
+**For Customer Insights:**
+
+- [ ] Persona data is based on real research (cited)
+- [ ] Survey/interview data has sample size and source
+- [ ] Behavioral claims are backed by studies/data
+      </action>
+
+<action>Count and document source quality:
+
+- Total sources cited: {{count_all_sources}}
+- High confidence (2+ sources): {{high_confidence_claims}}
+- Single source (needs verification): {{single_source_claims}}
+- Uncertain/speculative: {{low_confidence_claims}}
+
+If {{single_source_claims}} or {{low_confidence_claims}} is high, consider additional research.
+</action>
+
+<action>Compile full report with ALL sources properly referenced:
+
+Generate the complete market research report using the template:
+
+- Ensure every statistic has inline citation: [Source: Company, Year, URL]
+- Populate all {{sources_*}} template variables
+- Include confidence levels for major claims
+- Add References section with full source list
+  </action>
+
+<action>Present source quality summary to user:
+
+"I've completed the research with {{count_all_sources}} total sources:
+
+- {{high_confidence_claims}} claims verified with multiple sources
+- {{single_source_claims}} claims from single sources (marked for verification)
+- {{low_confidence_claims}} claims with low confidence or speculation
+
+Would you like me to strengthen any areas with additional research?"
+</action>
+
+<ask>Would you like to review any specific sections before finalizing? Are there any additional analyses you'd like to include?</ask>
+
+<goto step="9a" if="user requests changes">Return to refine opportunities</goto>
+
+<template-output>final_report_ready</template-output>
+<template-output>source_audit_complete</template-output>
+</step>
+
+<step n="13" goal="Appendices and Supporting Materials" optional="true">
+<ask>Would you like to include detailed appendices with calculations, full competitor profiles, or raw research data?</ask>
+
+<check if="yes">
+  Create appendices with:
+
+- Detailed TAM/SAM/SOM calculations
+- Full competitor profiles
+- Customer interview notes
+- Data sources and methodology
+- Financial model details
+- Glossary of terms
+
+<template-output>appendices</template-output>
+</check>
+
+</step>
+
+<step n="14" goal="Update status file on completion" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-{{research_mode}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<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>**✅ Research Complete ({{research_mode}} mode)**
+
+**Research Report:**
+
+- Research report generated and saved to {output_folder}/bmm-research-{{research_mode}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: research marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review findings with stakeholders, or run additional analysis workflows (product-brief for software, or install BMGD module for game-brief)
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review research findings
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/research/instructions-router.md

@@ -0,0 +1,133 @@
+# Research Workflow Router Instructions
+
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate in {communication_language}, generate documents in {document_output_language}</critical>
+<critical>Web research is ENABLED - always use current {{current_year}} data</critical>
+
+<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
+<critical>NEVER present information without a verified source - if you cannot find a source, say "I could not find reliable data on this"</critical>
+<critical>ALWAYS cite sources with URLs when presenting data, statistics, or factual claims</critical>
+<critical>REQUIRE at least 2 independent sources for critical claims (market size, growth rates, competitive data)</critical>
+<critical>When sources conflict, PRESENT BOTH views and note the discrepancy - do NOT pick one arbitrarily</critical>
+<critical>Flag any data you are uncertain about with confidence levels: [High Confidence], [Medium Confidence], [Low Confidence - verify]</critical>
+<critical>Distinguish clearly between: FACTS (from sources), ANALYSIS (your interpretation), and SPECULATION (educated guesses)</critical>
+<critical>When using WebSearch results, ALWAYS extract and include the source URL for every claim</critical>
+
+<!-- IDE-INJECT-POINT: research-subagents -->
+
+<workflow>
+
+<critical>This is a ROUTER that directs to specialized research instruction sets</critical>
+
+<step n="1" 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. Research is optional - you can continue without status tracking.</output>
+  <action>Set standalone_mode = true</action>
+</check>
+
+<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 "research" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+  <action>Pass status context to loaded instruction set for final update</action>
+
+  <check if="research status is file path (already completed)">
+    <output>⚠️ Research already completed: {{research status}}</output>
+    <ask>Re-running will create a new research report. 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="research is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Research is out of sequence.</output>
+    <output>Note: Research can provide valuable insights at any project stage.</output>
+    <ask>Continue with Research 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>
+</step>
+
+<step n="2" goal="Discover research needs through conversation">
+
+<action>Welcome {user_name} warmly. Position yourself as their research partner who uses live {{current_year}} web data. Ask what they're looking to understand or research.</action>
+
+<action>Listen and collaboratively identify the research type based on what they describe:
+
+- Market/Business questions → Market Research
+- Competitor questions → Competitive Intelligence
+- Customer questions → User Research
+- Technology questions → Technical Research
+- Industry questions → Domain Research
+- Creating research prompts for AI platforms → Deep Research Prompt Generator
+
+Confirm your understanding of what type would be most helpful and what it will produce.
+</action>
+
+<action>Capture {{research_type}} and {{research_mode}}</action>
+
+<template-output>research_type_discovery</template-output>
+</step>
+
+<step n="3" goal="Route to Appropriate Research Instructions">
+
+<critical>Based on user selection, load the appropriate instruction set</critical>
+
+<check if="research_type == 1 OR fuzzy match market research">
+  <action>Set research_mode = "market"</action>
+  <action>LOAD: {installed_path}/instructions-market.md</action>
+  <action>Continue with market research workflow</action>
+</check>
+
+<check if="research_type == 2 or prompt or fuzzy match deep research prompt">
+  <action>Set research_mode = "deep-prompt"</action>
+  <action>LOAD: {installed_path}/instructions-deep-prompt.md</action>
+  <action>Continue with deep research prompt generation</action>
+</check>
+
+<check if="research_type == 3 technical or architecture or fuzzy match indicates technical type of research">
+  <action>Set research_mode = "technical"</action>
+  <action>LOAD: {installed_path}/instructions-technical.md</action>
+  <action>Continue with technical research workflow</action>
+
+</check>
+
+<check if="research_type == 4 or fuzzy match competitive">
+  <action>Set research_mode = "competitive"</action>
+  <action>This will use market research workflow with competitive focus</action>
+  <action>LOAD: {installed_path}/instructions-market.md</action>
+  <action>Pass mode="competitive" to focus on competitive intelligence</action>
+
+</check>
+
+<check if="research_type == 5 or fuzzy match user research">
+  <action>Set research_mode = "user"</action>
+  <action>This will use market research workflow with user research focus</action>
+  <action>LOAD: {installed_path}/instructions-market.md</action>
+  <action>Pass mode="user" to focus on customer insights</action>
+
+</check>
+
+<check if="research_type == 6 or fuzzy match domain or industry or category">
+  <action>Set research_mode = "domain"</action>
+  <action>This will use market research workflow with domain focus</action>
+  <action>LOAD: {installed_path}/instructions-market.md</action>
+  <action>Pass mode="domain" to focus on industry/domain analysis</action>
+</check>
+
+<critical>The loaded instruction set will continue from here with full context of the {research_type}</critical>
+
+</step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/research/instructions-technical.md

@@ -0,0 +1,538 @@
+# Technical/Architecture Research Instructions
+
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
+<critical>This is a HIGHLY INTERACTIVE workflow - make technical decisions WITH user, not FOR them</critical>
+<critical>Web research is MANDATORY - use WebSearch tool with {{current_year}} for current version info and trends</critical>
+<critical>ALWAYS verify current versions - NEVER use hardcoded or outdated version numbers</critical>
+<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
+<critical>NEVER invent version numbers, features, or technical details - ALWAYS verify with current {{current_year}} sources</critical>
+<critical>Every technical claim (version, feature, performance, compatibility) MUST have a cited source with URL</critical>
+<critical>Version numbers MUST be verified via WebSearch - do NOT rely on training data (it's outdated!)</critical>
+<critical>When comparing technologies, cite sources for each claim (performance benchmarks, community size, etc.)</critical>
+<critical>Mark confidence levels: [Verified {{current_year}} source], [Older source - verify], [Uncertain - needs verification]</critical>
+<critical>Distinguish: FACT (from official docs/sources), OPINION (from community/reviews), SPECULATION (your analysis)</critical>
+<critical>If you cannot find current information about a technology, state: "I could not find recent {{current_year}} data on [X]"</critical>
+<critical>Extract and include source URLs in all technology profiles and comparisons</critical>
+
+<workflow>
+
+<step n="1" goal="Discover technical research needs through conversation">
+
+<action>Engage conversationally based on skill level:
+
+<check if="{user_skill_level} == 'expert'">
+  "Let's research the technical options for your decision.
+
+I'll gather current data from {{current_year}}, compare approaches, and help you think through trade-offs.
+
+What technical question are you wrestling with?"
+</check>
+
+<check if="{user_skill_level} == 'intermediate'">
+  "I'll help you research and evaluate your technical options.
+
+We'll look at current technologies (using {{current_year}} data), understand the trade-offs, and figure out what fits your needs best.
+
+What technical decision are you trying to make?"
+</check>
+
+<check if="{user_skill_level} == 'beginner'">
+  "Think of this as having a technical advisor help you research your options.
+
+I'll explain what different technologies do, why you might choose one over another, and help you make an informed decision.
+
+What technical challenge brought you here?"
+</check>
+</action>
+
+<action>Through conversation, understand:
+
+- **The technical question** - What they need to decide or understand
+- **The context** - Greenfield? Brownfield? Learning? Production?
+- **Current constraints** - Languages, platforms, team skills, budget
+- **What they already know** - Do they have candidates in mind?
+
+Don't interrogate - explore together. If they're unsure, help them articulate the problem.
+</action>
+
+<template-output>technical_question</template-output>
+<template-output>project_context</template-output>
+
+</step>
+
+<step n="2" goal="Define Technical Requirements and Constraints">
+<action>Gather requirements and constraints that will guide the research</action>
+
+**Let's define your technical requirements:**
+
+<ask>**Functional Requirements** - What must the technology do?
+
+Examples:
+
+- Handle 1M requests per day
+- Support real-time data processing
+- Provide full-text search capabilities
+- Enable offline-first mobile app
+- Support multi-tenancy</ask>
+
+<template-output>functional_requirements</template-output>
+
+<ask>**Non-Functional Requirements** - Performance, scalability, security needs?
+
+Consider:
+
+- Performance targets (latency, throughput)
+- Scalability requirements (users, data volume)
+- Reliability and availability needs
+- Security and compliance requirements
+- Maintainability and developer experience</ask>
+
+<template-output>non_functional_requirements</template-output>
+
+<ask>**Constraints** - What limitations or requirements exist?
+
+- Programming language preferences or requirements
+- Cloud platform (AWS, Azure, GCP, on-prem)
+- Budget constraints
+- Team expertise and skills
+- Timeline and urgency
+- Existing technology stack (if brownfield)
+- Open source vs commercial requirements
+- Licensing considerations</ask>
+
+<template-output>technical_constraints</template-output>
+
+</step>
+
+<step n="3" goal="Discover and evaluate technology options together">
+
+<critical>MUST use WebSearch to find current options from {{current_year}}</critical>
+
+<action>Ask if they have candidates in mind:
+
+"Do you already have specific technologies you want to compare, or should I search for the current options?"
+</action>
+
+<action if="user has candidates">Great! Let's research: {{user_candidates}}</action>
+
+<action if="discovering options">Search for current leading technologies:
+
+<WebSearch>{{technical_category}} best tools {{current_year}}</WebSearch>
+<WebSearch>{{technical_category}} comparison {{use_case}} {{current_year}}</WebSearch>
+<WebSearch>{{technical_category}} popular frameworks {{current_year}}</WebSearch>
+<WebSearch>state of {{technical_category}} {{current_year}}</WebSearch>
+</action>
+
+<action>Share findings conversationally:
+
+"Based on current {{current_year}} data, here are the main options:
+
+{{discovered_options}}
+
+<check if="{user_skill_level} == 'expert'">
+These are the leaders right now. Which ones make sense to evaluate for your use case?"
+</check>
+
+<check if="{user_skill_level} == 'beginner'">
+Each of these is popular for different reasons. Let me know if you want me to explain what makes each one different."
+</check>
+</action>
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+
+<template-output>technology_options</template-output>
+
+</step>
+
+<step n="4" goal="Research each technology together in depth">
+
+<critical>For each option, use WebSearch to gather CURRENT {{current_year}} information</critical>
+
+<step n="4a" title="Deep dive on each technology" repeat="for-each-option">
+
+<action>For {{technology_name}}, conduct comprehensive research:
+
+<WebSearch>{{technology_name}} overview what is {{current_year}}</WebSearch>
+<WebSearch>{{technology_name}} latest version release notes {{current_year}}</WebSearch>
+<WebSearch>{{technology_name}} pros cons trade-offs {{current_year}}</WebSearch>
+<WebSearch>{{technology_name}} production experience real world {{current_year}}</WebSearch>
+<WebSearch>{{technology_name}} vs alternatives comparison {{current_year}}</WebSearch>
+</action>
+
+<action>Share findings conversationally and collaboratively:
+
+"Here's what I found about {{technology_name}}:
+
+**Overview:**
+{{what_it_is_and_solves}}
+
+**Current Status ({{current_year}}):**
+{{maturity_community_release_cadence}}
+
+**Technical Characteristics:**
+
+- Architecture and design philosophy
+- Core features and capabilities
+- Performance characteristics
+- Scalability approach
+- Integration capabilities
+
+**Developer Experience:**
+
+- Learning curve
+- Documentation quality
+- Tooling ecosystem
+- Testing support
+- Debugging capabilities
+
+**Operations:**
+
+- Deployment complexity
+- Monitoring and observability
+- Operational overhead
+- Cloud provider support
+- Container/K8s compatibility
+
+**Ecosystem:**
+
+- Available libraries and plugins
+- Third-party integrations
+- Commercial support options
+- Training and educational resources
+
+**Community and Adoption:**
+
+- GitHub stars/contributors (if applicable)
+- Production usage examples
+- Case studies from similar use cases
+- Community support channels
+- Job market demand
+
+**Costs:**
+
+- Licensing model
+- Hosting/infrastructure costs
+- Support costs
+- Training costs
+- Total cost of ownership estimate
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+<template-output>tech*profile*{{option_number}}</template-output>
+
+</step>
+
+</step>
+
+<step n="5" goal="Comparative Analysis">
+<action>Create structured comparison across all options</action>
+
+**Create comparison matrices:**
+
+<action>Generate comparison table with key dimensions:</action>
+
+**Comparison Dimensions:**
+
+1. **Meets Requirements** - How well does each meet functional requirements?
+2. **Performance** - Speed, latency, throughput benchmarks
+3. **Scalability** - Horizontal/vertical scaling capabilities
+4. **Complexity** - Learning curve and operational complexity
+5. **Ecosystem** - Maturity, community, libraries, tools
+6. **Cost** - Total cost of ownership
+7. **Risk** - Maturity, vendor lock-in, abandonment risk
+8. **Developer Experience** - Productivity, debugging, testing
+9. **Operations** - Deployment, monitoring, maintenance
+10. **Future-Proofing** - Roadmap, innovation, sustainability
+
+<action>Rate each option on relevant dimensions (High/Medium/Low or 1-5 scale)</action>
+
+<template-output>comparative_analysis</template-output>
+
+</step>
+
+<step n="6" goal="Trade-offs and Decision Factors">
+<action>Analyze trade-offs between options</action>
+
+**Identify key trade-offs:**
+
+For each pair of leading options, identify trade-offs:
+
+- What do you gain by choosing Option A over Option B?
+- What do you sacrifice?
+- Under what conditions would you choose one vs the other?
+
+**Decision factors by priority:**
+
+<ask>What are your top 3 decision factors?
+
+Examples:
+
+- Time to market
+- Performance
+- Developer productivity
+- Operational simplicity
+- Cost efficiency
+- Future flexibility
+- Team expertise match
+- Community and support</ask>
+
+<template-output>decision_priorities</template-output>
+
+<action>Weight the comparison analysis by decision priorities</action>
+
+<template-output>weighted_analysis</template-output>
+
+</step>
+
+<step n="7" goal="Use Case Fit Analysis">
+<action>Evaluate fit for specific use case</action>
+
+**Match technologies to your specific use case:**
+
+Based on:
+
+- Your functional and non-functional requirements
+- Your constraints (team, budget, timeline)
+- Your context (greenfield vs brownfield)
+- Your decision priorities
+
+Analyze which option(s) best fit your specific scenario.
+
+<ask>Are there any specific concerns or "must-haves" that would immediately eliminate any options?</ask>
+
+<template-output>use_case_fit</template-output>
+
+</step>
+
+<step n="8" goal="Real-World Evidence">
+<action>Gather production experience evidence</action>
+
+**Search for real-world experiences:**
+
+For top 2-3 candidates:
+
+- Production war stories and lessons learned
+- Known issues and gotchas
+- Migration experiences (if replacing existing tech)
+- Performance benchmarks from real deployments
+- Team scaling experiences
+- Reddit/HackerNews discussions
+- Conference talks and blog posts from practitioners
+
+<template-output>real_world_evidence</template-output>
+
+</step>
+
+<step n="9" goal="Architecture Pattern Research" optional="true">
+<action>If researching architecture patterns, provide pattern analysis</action>
+
+<ask>Are you researching architecture patterns (microservices, event-driven, etc.)?</ask>
+
+<check if="yes">
+
+Research and document:
+
+**Pattern Overview:**
+
+- Core principles and concepts
+- When to use vs when not to use
+- Prerequisites and foundations
+
+**Implementation Considerations:**
+
+- Technology choices for the pattern
+- Reference architectures
+- Common pitfalls and anti-patterns
+- Migration path from current state
+
+**Trade-offs:**
+
+- Benefits and drawbacks
+- Complexity vs benefits analysis
+- Team skill requirements
+- Operational overhead
+
+<template-output>architecture_pattern_analysis</template-output>
+</check>
+
+</step>
+
+<step n="10" goal="Recommendations and Decision Framework">
+<action>Synthesize research into clear recommendations</action>
+
+**Generate recommendations:**
+
+**Top Recommendation:**
+
+- Primary technology choice with rationale
+- Why it best fits your requirements and constraints
+- Key benefits for your use case
+- Risks and mitigation strategies
+
+**Alternative Options:**
+
+- Second and third choices
+- When you might choose them instead
+- Scenarios where they would be better
+
+**Implementation Roadmap:**
+
+- Proof of concept approach
+- Key decisions to make during implementation
+- Migration path (if applicable)
+- Success criteria and validation approach
+
+**Risk Mitigation:**
+
+- Identified risks and mitigation plans
+- Contingency options if primary choice doesn't work
+- Exit strategy considerations
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+
+<template-output>recommendations</template-output>
+
+</step>
+
+<step n="11" goal="Decision Documentation">
+<action>Create architecture decision record (ADR) template</action>
+
+**Generate Architecture Decision Record:**
+
+Create ADR format documentation:
+
+```markdown
+# ADR-XXX: [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Superseded]
+
+## Context
+
+[Technical context and problem statement]
+
+## Decision Drivers
+
+[Key factors influencing the decision]
+
+## Considered Options
+
+[Technologies/approaches evaluated]
+
+## Decision
+
+[Chosen option and rationale]
+
+## Consequences
+
+**Positive:**
+
+- [Benefits of this choice]
+
+**Negative:**
+
+- [Drawbacks and risks]
+
+**Neutral:**
+
+- [Other impacts]
+
+## Implementation Notes
+
+[Key considerations for implementation]
+
+## References
+
+[Links to research, benchmarks, case studies]
+```
+
+<template-output>architecture_decision_record</template-output>
+
+</step>
+
+<step n="12" goal="Finalize Technical Research Report">
+<action>Compile complete technical research report</action>
+
+**Your Technical Research Report includes:**
+
+1. **Executive Summary** - Key findings and recommendation
+2. **Requirements and Constraints** - What guided the research
+3. **Technology Options** - All candidates evaluated
+4. **Detailed Profiles** - Deep dive on each option
+5. **Comparative Analysis** - Side-by-side comparison
+6. **Trade-off Analysis** - Key decision factors
+7. **Real-World Evidence** - Production experiences
+8. **Recommendations** - Detailed recommendation with rationale
+9. **Architecture Decision Record** - Formal decision documentation
+10. **Next Steps** - Implementation roadmap
+
+<action>Save complete report to {default_output_file}</action>
+
+<ask>Would you like to:
+
+1. Deep dive into specific technology
+2. Research implementation patterns for chosen technology
+3. Generate proof-of-concept plan
+4. Create deep research prompt for ongoing investigation
+5. Exit workflow
+
+Select option (1-5):</ask>
+
+<check if="option 4">
+  <action>LOAD: {installed_path}/instructions-deep-prompt.md</action>
+  <action>Pre-populate with technical research context</action>
+</check>
+
+</step>
+
+<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-technical-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<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>**✅ Technical Research Complete**
+
+**Research Report:**
+
+- Technical research report generated and saved to {output_folder}/bmm-research-technical-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: research marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review findings with architecture team, or run additional analysis workflows
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review technical research findings
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
+
+</workflow>

.bmad/bmm/workflows/1-analysis/research/template-deep-prompt.md

@@ -0,0 +1,94 @@
+# Deep Research Prompt
+
+**Generated:** {{date}}
+**Created by:** {{user_name}}
+**Target Platform:** {{target_platform}}
+
+---
+
+## Research Prompt (Ready to Use)
+
+### Research Question
+
+{{research_topic}}
+
+### Research Goal and Context
+
+**Objective:** {{research_goal}}
+
+**Context:**
+{{research_persona}}
+
+### Scope and Boundaries
+
+**Temporal Scope:** {{temporal_scope}}
+
+**Geographic Scope:** {{geographic_scope}}
+
+**Thematic Focus:**
+{{thematic_boundaries}}
+
+### Information Requirements
+
+**Types of Information Needed:**
+{{information_types}}
+
+**Preferred Sources:**
+{{preferred_sources}}
+
+### Output Structure
+
+**Format:** {{output_format}}
+
+**Required Sections:**
+{{key_sections}}
+
+**Depth Level:** {{depth_level}}
+
+### Research Methodology
+
+**Keywords and Technical Terms:**
+{{research_keywords}}
+
+**Special Requirements:**
+{{special_requirements}}
+
+**Validation Criteria:**
+{{validation_criteria}}
+
+### Follow-up Strategy
+
+{{follow_up_strategy}}
+
+---
+
+## Complete Research Prompt (Copy and Paste)
+
+```
+{{deep_research_prompt}}
+```
+
+---
+
+## Platform-Specific Usage Tips
+
+{{platform_tips}}
+
+---
+
+## Research Execution Checklist
+
+{{execution_checklist}}
+
+---
+
+## Metadata
+
+**Workflow:** BMad Research Workflow - Deep Research Prompt Generator v2.0
+**Generated:** {{date}}
+**Research Type:** Deep Research Prompt
+**Platform:** {{target_platform}}
+
+---
+
+_This research prompt was generated using the BMad Method Research Workflow, incorporating best practices from ChatGPT Deep Research, Gemini Deep Research, Grok DeepSearch, and Claude Projects (2025)._

.bmad/bmm/workflows/1-analysis/research/template-market.md

@@ -0,0 +1,347 @@
+# Market Research Report: {{product_name}}
+
+**Date:** {{date}}
+**Prepared by:** {{user_name}}
+**Research Depth:** {{research_depth}}
+
+---
+
+## Executive Summary
+
+{{executive_summary}}
+
+### Key Market Metrics
+
+- **Total Addressable Market (TAM):** {{tam_calculation}}
+- **Serviceable Addressable Market (SAM):** {{sam_calculation}}
+- **Serviceable Obtainable Market (SOM):** {{som_scenarios}}
+
+### Critical Success Factors
+
+{{key_success_factors}}
+
+---
+
+## 1. Research Objectives and Methodology
+
+### Research Objectives
+
+{{research_objectives}}
+
+### Scope and Boundaries
+
+- **Product/Service:** {{product_description}}
+- **Market Definition:** {{market_definition}}
+- **Geographic Scope:** {{geographic_scope}}
+- **Customer Segments:** {{segment_boundaries}}
+
+### Research Methodology
+
+{{research_methodology}}
+
+### Data Sources
+
+{{source_credibility_notes}}
+
+---
+
+## 2. Market Overview
+
+### Market Definition
+
+{{market_definition}}
+
+### Market Size and Growth
+
+#### Total Addressable Market (TAM)
+
+**Methodology:** {{tam_methodology}}
+
+{{tam_calculation}}
+
+#### Serviceable Addressable Market (SAM)
+
+{{sam_calculation}}
+
+#### Serviceable Obtainable Market (SOM)
+
+{{som_scenarios}}
+
+### Market Intelligence Summary
+
+{{market_intelligence_raw}}
+
+### Key Data Points
+
+{{key_data_points}}
+
+---
+
+## 3. Market Trends and Drivers
+
+### Key Market Trends
+
+{{market_trends}}
+
+### Growth Drivers
+
+{{growth_drivers}}
+
+### Market Inhibitors
+
+{{market_inhibitors}}
+
+### Future Outlook
+
+{{future_outlook}}
+
+---
+
+## 4. Customer Analysis
+
+### Target Customer Segments
+
+{{#segment_profile_1}}
+
+#### Segment 1
+
+{{segment_profile_1}}
+{{/segment_profile_1}}
+
+{{#segment_profile_2}}
+
+#### Segment 2
+
+{{segment_profile_2}}
+{{/segment_profile_2}}
+
+{{#segment_profile_3}}
+
+#### Segment 3
+
+{{segment_profile_3}}
+{{/segment_profile_3}}
+
+{{#segment_profile_4}}
+
+#### Segment 4
+
+{{segment_profile_4}}
+{{/segment_profile_4}}
+
+{{#segment_profile_5}}
+
+#### Segment 5
+
+{{segment_profile_5}}
+{{/segment_profile_5}}
+
+### Jobs-to-be-Done Analysis
+
+{{jobs_to_be_done}}
+
+### Pricing Analysis and Willingness to Pay
+
+{{pricing_analysis}}
+
+---
+
+## 5. Competitive Landscape
+
+### Market Structure
+
+{{market_structure}}
+
+### Competitor Analysis
+
+{{#competitor_analysis_1}}
+
+#### Competitor 1
+
+{{competitor_analysis_1}}
+{{/competitor_analysis_1}}
+
+{{#competitor_analysis_2}}
+
+#### Competitor 2
+
+{{competitor_analysis_2}}
+{{/competitor_analysis_2}}
+
+{{#competitor_analysis_3}}
+
+#### Competitor 3
+
+{{competitor_analysis_3}}
+{{/competitor_analysis_3}}
+
+{{#competitor_analysis_4}}
+
+#### Competitor 4
+
+{{competitor_analysis_4}}
+{{/competitor_analysis_4}}
+
+{{#competitor_analysis_5}}
+
+#### Competitor 5
+
+{{competitor_analysis_5}}
+{{/competitor_analysis_5}}
+
+### Competitive Positioning
+
+{{competitive_positioning}}
+
+---
+
+## 6. Industry Analysis
+
+### Porter's Five Forces Assessment
+
+{{porters_five_forces}}
+
+### Technology Adoption Lifecycle
+
+{{adoption_lifecycle}}
+
+### Value Chain Analysis
+
+{{value_chain_analysis}}
+
+---
+
+## 7. Market Opportunities
+
+### Identified Opportunities
+
+{{market_opportunities}}
+
+### Opportunity Prioritization Matrix
+
+{{opportunity_prioritization}}
+
+---
+
+## 8. Strategic Recommendations
+
+### Go-to-Market Strategy
+
+{{gtm_strategy}}
+
+#### Positioning Strategy
+
+{{positioning_strategy}}
+
+#### Target Segment Sequencing
+
+{{segment_sequencing}}
+
+#### Channel Strategy
+
+{{channel_strategy}}
+
+#### Pricing Strategy
+
+{{pricing_recommendations}}
+
+### Implementation Roadmap
+
+{{implementation_roadmap}}
+
+---
+
+## 9. Risk Assessment
+
+### Risk Analysis
+
+{{risk_assessment}}
+
+### Mitigation Strategies
+
+{{mitigation_strategies}}
+
+---
+
+## 10. Financial Projections
+
+{{#financial_projections}}
+{{financial_projections}}
+{{/financial_projections}}
+
+---
+
+## Appendices
+
+### Appendix A: Data Sources and References
+
+{{data_sources}}
+
+### Appendix B: Detailed Calculations
+
+{{detailed_calculations}}
+
+### Appendix C: Additional Analysis
+
+{{#appendices}}
+{{appendices}}
+{{/appendices}}
+
+### Appendix D: Glossary of Terms
+
+{{glossary}}
+
+---
+
+## References and Sources
+
+**CRITICAL: All data in this report must be verifiable through the sources listed below**
+
+### Market Size and Growth Data Sources
+
+{{sources_market_size}}
+
+### Competitive Intelligence Sources
+
+{{sources_competitive}}
+
+### Customer Research Sources
+
+{{sources_customer}}
+
+### Industry Trends and Analysis Sources
+
+{{sources_trends}}
+
+### Additional References
+
+{{sources_additional}}
+
+### Source Quality Assessment
+
+- **High Credibility Sources (2+ corroborating):** {{high_confidence_count}} claims
+- **Medium Credibility (single source):** {{medium_confidence_count}} claims
+- **Low Credibility (needs verification):** {{low_confidence_count}} claims
+
+**Note:** Any claim marked [Low Confidence] or [Single source] should be independently verified before making critical business decisions.
+
+---
+
+## Document Information
+
+**Workflow:** BMad Market Research Workflow v1.0
+**Generated:** {{date}}
+**Next Review:** {{next_review_date}}
+**Classification:** {{classification}}
+
+### Research Quality Metrics
+
+- **Data Freshness:** Current as of {{date}}
+- **Source Reliability:** {{source_reliability_score}}
+- **Confidence Level:** {{confidence_level}}
+- **Total Sources Cited:** {{total_sources}}
+- **Web Searches Conducted:** {{search_count}}
+
+---
+
+_This market research report was generated using the BMad Method Market Research Workflow, combining systematic analysis frameworks with real-time market intelligence gathering. All factual claims are backed by cited sources with verification dates._

.bmad/bmm/workflows/1-analysis/research/template-technical.md

@@ -0,0 +1,245 @@
+# Technical Research Report: {{technical_question}}
+
+**Date:** {{date}}
+**Prepared by:** {{user_name}}
+**Project Context:** {{project_context}}
+
+---
+
+## Executive Summary
+
+{{recommendations}}
+
+### Key Recommendation
+
+**Primary Choice:** [Technology/Pattern Name]
+
+**Rationale:** [2-3 sentence summary]
+
+**Key Benefits:**
+
+- [Benefit 1]
+- [Benefit 2]
+- [Benefit 3]
+
+---
+
+## 1. Research Objectives
+
+### Technical Question
+
+{{technical_question}}
+
+### Project Context
+
+{{project_context}}
+
+### Requirements and Constraints
+
+#### Functional Requirements
+
+{{functional_requirements}}
+
+#### Non-Functional Requirements
+
+{{non_functional_requirements}}
+
+#### Technical Constraints
+
+{{technical_constraints}}
+
+---
+
+## 2. Technology Options Evaluated
+
+{{technology_options}}
+
+---
+
+## 3. Detailed Technology Profiles
+
+{{#tech_profile_1}}
+
+### Option 1: [Technology Name]
+
+{{tech_profile_1}}
+{{/tech_profile_1}}
+
+{{#tech_profile_2}}
+
+### Option 2: [Technology Name]
+
+{{tech_profile_2}}
+{{/tech_profile_2}}
+
+{{#tech_profile_3}}
+
+### Option 3: [Technology Name]
+
+{{tech_profile_3}}
+{{/tech_profile_3}}
+
+{{#tech_profile_4}}
+
+### Option 4: [Technology Name]
+
+{{tech_profile_4}}
+{{/tech_profile_4}}
+
+{{#tech_profile_5}}
+
+### Option 5: [Technology Name]
+
+{{tech_profile_5}}
+{{/tech_profile_5}}
+
+---
+
+## 4. Comparative Analysis
+
+{{comparative_analysis}}
+
+### Weighted Analysis
+
+**Decision Priorities:**
+{{decision_priorities}}
+
+{{weighted_analysis}}
+
+---
+
+## 5. Trade-offs and Decision Factors
+
+{{use_case_fit}}
+
+### Key Trade-offs
+
+[Comparison of major trade-offs between top options]
+
+---
+
+## 6. Real-World Evidence
+
+{{real_world_evidence}}
+
+---
+
+## 7. Architecture Pattern Analysis
+
+{{#architecture_pattern_analysis}}
+{{architecture_pattern_analysis}}
+{{/architecture_pattern_analysis}}
+
+---
+
+## 8. Recommendations
+
+{{recommendations}}
+
+### Implementation Roadmap
+
+1. **Proof of Concept Phase**
+   - [POC objectives and timeline]
+
+2. **Key Implementation Decisions**
+   - [Critical decisions to make during implementation]
+
+3. **Migration Path** (if applicable)
+   - [Migration approach from current state]
+
+4. **Success Criteria**
+   - [How to validate the decision]
+
+### Risk Mitigation
+
+{{risk_mitigation}}
+
+---
+
+## 9. Architecture Decision Record (ADR)
+
+{{architecture_decision_record}}
+
+---
+
+## 10. References and Resources
+
+### Documentation
+
+- [Links to official documentation]
+
+### Benchmarks and Case Studies
+
+- [Links to benchmarks and real-world case studies]
+
+### Community Resources
+
+- [Links to communities, forums, discussions]
+
+### Additional Reading
+
+- [Links to relevant articles, papers, talks]
+
+---
+
+## Appendices
+
+### Appendix A: Detailed Comparison Matrix
+
+[Full comparison table with all evaluated dimensions]
+
+### Appendix B: Proof of Concept Plan
+
+[Detailed POC plan if needed]
+
+### Appendix C: Cost Analysis
+
+[TCO analysis if performed]
+
+---
+
+## References and Sources
+
+**CRITICAL: All technical claims, versions, and benchmarks must be verifiable through sources below**
+
+### Official Documentation and Release Notes
+
+{{sources_official_docs}}
+
+### Performance Benchmarks and Comparisons
+
+{{sources_benchmarks}}
+
+### Community Experience and Reviews
+
+{{sources_community}}
+
+### Architecture Patterns and Best Practices
+
+{{sources_architecture}}
+
+### Additional Technical References
+
+{{sources_additional}}
+
+### Version Verification
+
+- **Technologies Researched:** {{technology_count}}
+- **Versions Verified ({{current_year}}):** {{verified_versions_count}}
+- **Sources Requiring Update:** {{outdated_sources_count}}
+
+**Note:** All version numbers were verified using current {{current_year}} sources. Versions may change - always verify latest stable release before implementation.
+
+---
+
+## Document Information
+
+**Workflow:** BMad Research Workflow - Technical Research v2.0
+**Generated:** {{date}}
+**Research Type:** Technical/Architecture Research
+**Next Review:** [Date for review/update]
+**Total Sources Cited:** {{total_sources}}
+
+---
+
+_This technical research report was generated using the BMad Method Research Workflow, combining systematic technology evaluation frameworks with real-time research and analysis. All version numbers and technical claims are backed by current {{current_year}} sources._

.bmad/bmm/workflows/1-analysis/research/workflow.yaml

@@ -0,0 +1,44 @@
+# Research Workflow - Multi-Type Research System
+name: research
+description: "Adaptive research workflow supporting multiple research types: market research, deep research prompt generation, technical/architecture evaluation, competitive intelligence, user research, and domain analysis"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+current_year: system-generated
+current_month: system-generated
+
+# Research behavior - WEB RESEARCH IS DEFAULT
+enable_web_research: true
+
+# Source tracking and verification - CRITICAL FOR ACCURACY
+require_citations: true
+require_source_urls: true
+minimum_sources_per_claim: 2
+fact_check_critical_data: true
+
+# Workflow components - ROUTER PATTERN
+installed_path: "{project-root}/.bmad/bmm/workflows/1-analysis/research"
+instructions: "{installed_path}/instructions-router.md" # Router loads specific instruction sets
+validation: "{installed_path}/checklist.md"
+
+# Research type specific instructions (loaded by router)
+instructions_market: "{installed_path}/instructions-market.md"
+instructions_deep_prompt: "{installed_path}/instructions-deep-prompt.md"
+instructions_technical: "{installed_path}/instructions-technical.md"
+
+# Templates (loaded based on research type)
+template_market: "{installed_path}/template-market.md"
+template_deep_prompt: "{installed_path}/template-deep-prompt.md"
+template_technical: "{installed_path}/template-technical.md"
+
+# Output configuration (dynamic based on research type selected in router)
+default_output_file: "{output_folder}/research-{{research_type}}-{{date}}.md"
+
+standalone: true

.bmad/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md

@@ -0,0 +1,310 @@
+# Create UX Design Workflow Validation Checklist
+
+**Purpose**: Validate UX Design Specification is complete, collaborative, and implementation-ready.
+
+**Paradigm**: Visual collaboration-driven, not template generation
+
+**Expected Outputs**:
+
+- ux-design-specification.md
+- ux-color-themes.html (color theme visualizer)
+- ux-design-directions.html (design mockups)
+- Optional: ux-prototype.html, ux-component-showcase.html, ai-frontend-prompt.md
+
+---
+
+## 1. Output Files Exist
+
+- [ ] **ux-design-specification.md** created in output folder
+- [ ] **ux-color-themes.html** generated (interactive color exploration)
+- [ ] **ux-design-directions.html** generated (6-8 design mockups)
+- [ ] No unfilled {{template_variables}} in specification
+- [ ] All sections have content (not placeholder text)
+
+---
+
+## 2. Collaborative Process Validation
+
+**The workflow should facilitate decisions WITH the user, not FOR them**
+
+- [ ] **Design system chosen by user** (not auto-selected)
+- [ ] **Color theme selected from options** (user saw visualizations and chose)
+- [ ] **Design direction chosen from mockups** (user explored 6-8 options)
+- [ ] **User journey flows designed collaboratively** (options presented, user decided)
+- [ ] **UX patterns decided with user input** (not just generated)
+- [ ] **Decisions documented WITH rationale** (why each choice was made)
+
+---
+
+## 3. Visual Collaboration Artifacts
+
+### Color Theme Visualizer
+
+- [ ] **HTML file exists and is valid** (ux-color-themes.html)
+- [ ] **Shows 3-4 theme options** (or documented existing brand)
+- [ ] **Each theme has complete palette** (primary, secondary, semantic colors)
+- [ ] **Live UI component examples** in each theme (buttons, forms, cards)
+- [ ] **Side-by-side comparison** enabled
+- [ ] **User's selection documented** in specification
+
+### Design Direction Mockups
+
+- [ ] **HTML file exists and is valid** (ux-design-directions.html)
+- [ ] **6-8 different design approaches** shown
+- [ ] **Full-screen mockups** of key screens
+- [ ] **Design philosophy labeled** for each direction (e.g., "Dense Dashboard", "Spacious Explorer")
+- [ ] **Interactive navigation** between directions
+- [ ] **Responsive preview** toggle available
+- [ ] **User's choice documented WITH reasoning** (what they liked, why it fits)
+
+---
+
+## 4. Design System Foundation
+
+- [ ] **Design system chosen** (or custom design decision documented)
+- [ ] **Current version identified** (if using established system)
+- [ ] **Components provided by system documented**
+- [ ] **Custom components needed identified**
+- [ ] **Decision rationale clear** (why this system for this project)
+
+---
+
+## 5. Core Experience Definition
+
+- [ ] **Defining experience articulated** (the ONE thing that makes this app unique)
+- [ ] **Novel UX patterns identified** (if applicable)
+- [ ] **Novel patterns fully designed** (interaction model, states, feedback)
+- [ ] **Core experience principles defined** (speed, guidance, flexibility, feedback)
+
+---
+
+## 6. Visual Foundation
+
+### Color System
+
+- [ ] **Complete color palette** (primary, secondary, accent, semantic, neutrals)
+- [ ] **Semantic color usage defined** (success, warning, error, info)
+- [ ] **Color accessibility considered** (contrast ratios for text)
+- [ ] **Brand alignment** (follows existing brand or establishes new identity)
+
+### Typography
+
+- [ ] **Font families selected** (heading, body, monospace if needed)
+- [ ] **Type scale defined** (h1-h6, body, small, etc.)
+- [ ] **Font weights documented** (when to use each)
+- [ ] **Line heights specified** for readability
+
+### Spacing & Layout
+
+- [ ] **Spacing system defined** (base unit, scale)
+- [ ] **Layout grid approach** (columns, gutters)
+- [ ] **Container widths** for different breakpoints
+
+---
+
+## 7. Design Direction
+
+- [ ] **Specific direction chosen** from mockups (not generic)
+- [ ] **Layout pattern documented** (navigation, content structure)
+- [ ] **Visual hierarchy defined** (density, emphasis, focus)
+- [ ] **Interaction patterns specified** (modal vs inline, disclosure approach)
+- [ ] **Visual style documented** (minimal, balanced, rich, maximalist)
+- [ ] **User's reasoning captured** (why this direction fits their vision)
+
+---
+
+## 8. User Journey Flows
+
+- [ ] **All critical journeys from PRD designed** (no missing flows)
+- [ ] **Each flow has clear goal** (what user accomplishes)
+- [ ] **Flow approach chosen collaboratively** (user picked from options)
+- [ ] **Step-by-step documentation** (screens, actions, feedback)
+- [ ] **Decision points and branching** defined
+- [ ] **Error states and recovery** addressed
+- [ ] **Success states specified** (completion feedback)
+- [ ] **Mermaid diagrams or clear flow descriptions** included
+
+---
+
+## 9. Component Library Strategy
+
+- [ ] **All required components identified** (from design system + custom)
+- [ ] **Custom components fully specified**:
+  - Purpose and user-facing value
+  - Content/data displayed
+  - User actions available
+  - All states (default, hover, active, loading, error, disabled)
+  - Variants (sizes, styles, layouts)
+  - Behavior on interaction
+  - Accessibility considerations
+- [ ] **Design system components customization needs** documented
+
+---
+
+## 10. UX Pattern Consistency Rules
+
+**These patterns ensure consistent UX across the entire app**
+
+- [ ] **Button hierarchy defined** (primary, secondary, tertiary, destructive)
+- [ ] **Feedback patterns established** (success, error, warning, info, loading)
+- [ ] **Form patterns specified** (labels, validation, errors, help text)
+- [ ] **Modal patterns defined** (sizes, dismiss behavior, focus, stacking)
+- [ ] **Navigation patterns documented** (active state, breadcrumbs, back button)
+- [ ] **Empty state patterns** (first use, no results, cleared content)
+- [ ] **Confirmation patterns** (when to confirm destructive actions)
+- [ ] **Notification patterns** (placement, duration, stacking, priority)
+- [ ] **Search patterns** (trigger, results, filters, no results)
+- [ ] **Date/time patterns** (format, timezone, pickers)
+
+**Each pattern should have:**
+
+- [ ] Clear specification (how it works)
+- [ ] Usage guidance (when to use)
+- [ ] Examples (concrete implementations)
+
+---
+
+## 11. Responsive Design
+
+- [ ] **Breakpoints defined** for target devices (mobile, tablet, desktop)
+- [ ] **Adaptation patterns documented** (how layouts change)
+- [ ] **Navigation adaptation** (how nav changes on small screens)
+- [ ] **Content organization changes** (multi-column to single, grid to list)
+- [ ] **Touch targets adequate** on mobile (minimum size specified)
+- [ ] **Responsive strategy aligned** with chosen design direction
+
+---
+
+## 12. Accessibility
+
+- [ ] **WCAG compliance level specified** (A, AA, or AAA)
+- [ ] **Color contrast requirements** documented (ratios for text)
+- [ ] **Keyboard navigation** addressed (all interactive elements accessible)
+- [ ] **Focus indicators** specified (visible focus states)
+- [ ] **ARIA requirements** noted (roles, labels, announcements)
+- [ ] **Screen reader considerations** (meaningful labels, structure)
+- [ ] **Alt text strategy** for images
+- [ ] **Form accessibility** (label associations, error identification)
+- [ ] **Testing strategy** defined (automated tools, manual testing)
+
+---
+
+## 13. Coherence and Integration
+
+- [ ] **Design system and custom components visually consistent**
+- [ ] **All screens follow chosen design direction**
+- [ ] **Color usage consistent with semantic meanings**
+- [ ] **Typography hierarchy clear and consistent**
+- [ ] **Similar actions handled the same way** (pattern consistency)
+- [ ] **All PRD user journeys have UX design**
+- [ ] **All entry points designed**
+- [ ] **Error and edge cases handled**
+- [ ] **Every interactive element meets accessibility requirements**
+- [ ] **All flows keyboard-navigable**
+- [ ] **Colors meet contrast requirements**
+
+---
+
+## 14. Cross-Workflow Alignment (Epics File Update)
+
+**As UX design progresses, you discover implementation details that affect the story breakdown**
+
+### Stories Discovered During UX Design
+
+- [ ] **Review epics.md file** for alignment with UX design
+- [ ] **New stories identified** during UX design that weren't in epics.md:
+  - [ ] Custom component build stories (if significant)
+  - [ ] UX pattern implementation stories
+  - [ ] Animation/transition stories
+  - [ ] Responsive adaptation stories
+  - [ ] Accessibility implementation stories
+  - [ ] Edge case handling stories discovered during journey design
+  - [ ] Onboarding/empty state stories
+  - [ ] Error state handling stories
+
+### Story Complexity Adjustments
+
+- [ ] **Existing stories complexity reassessed** based on UX design:
+  - [ ] Stories that are now more complex (UX revealed additional requirements)
+  - [ ] Stories that are simpler (design system handles more than expected)
+  - [ ] Stories that should be split (UX design shows multiple components/flows)
+  - [ ] Stories that can be combined (UX design shows they're tightly coupled)
+
+### Epic Alignment
+
+- [ ] **Epic scope still accurate** after UX design
+- [ ] **New epic needed** for discovered work (if significant)
+- [ ] **Epic ordering might change** based on UX dependencies
+
+### Action Items for Epics File Update
+
+- [ ] **List of new stories to add** to epics.md documented
+- [ ] **Complexity adjustments noted** for existing stories
+- [ ] **Update epics.md** OR flag for architecture review first
+- [ ] **Rationale documented** for why new stories/changes are needed
+
+**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
+
+---
+
+## 15. Decision Rationale
+
+**Unlike template-driven workflows, this workflow should document WHY**
+
+- [ ] **Design system choice has rationale** (why this fits the project)
+- [ ] **Color theme selection has reasoning** (why this emotional impact)
+- [ ] **Design direction choice explained** (what user liked, how it fits vision)
+- [ ] **User journey approaches justified** (why this flow pattern)
+- [ ] **UX pattern decisions have context** (why these patterns for this app)
+- [ ] **Responsive strategy aligned with user priorities**
+- [ ] **Accessibility level appropriate for deployment intent**
+
+---
+
+## 16. Implementation Readiness
+
+- [ ] **Designers can create high-fidelity mockups** from this spec
+- [ ] **Developers can implement** with clear UX guidance
+- [ ] **Sufficient detail** for frontend development
+- [ ] **Component specifications actionable** (states, variants, behaviors)
+- [ ] **Flows implementable** (clear steps, decision logic, error handling)
+- [ ] **Visual foundation complete** (colors, typography, spacing all defined)
+- [ ] **Pattern consistency enforceable** (clear rules for implementation)
+
+---
+
+## 17. Critical Failures (Auto-Fail)
+
+- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
+- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
+- [ ] ❌ **No design direction chosen** (missing key visual decisions)
+- [ ] ❌ **No user journey designs** (critical flows not documented)
+- [ ] ❌ **No UX pattern consistency rules** (implementation will be inconsistent)
+- [ ] ❌ **Missing core experience definition** (no clarity on what makes app unique)
+- [ ] ❌ **No component specifications** (components not actionable)
+- [ ] ❌ **Responsive strategy missing** (for multi-platform projects)
+- [ ] ❌ **Accessibility ignored** (no compliance target or requirements)
+- [ ] ❌ **Generic/templated content** (not specific to this project)
+
+---
+
+## Validation Notes
+
+**Document findings:**
+
+- UX Design Quality: [Exceptional / Strong / Adequate / Needs Work / Incomplete]
+- Collaboration Level: [Highly Collaborative / Collaborative / Somewhat Collaborative / Generated]
+- Visual Artifacts: [Complete & Interactive / Partial / Missing]
+- Implementation Readiness: [Ready / Needs Design Phase / Not Ready]
+
+## **Strengths:**
+
+## **Areas for Improvement:**
+
+## **Recommended Actions:**
+
+**Ready for next phase?** [Yes - Proceed to Design / Yes - Proceed to Development / Needs Refinement]
+
+---
+
+_This checklist validates collaborative UX design facilitation, not template generation. A successful UX workflow creates design decisions WITH the user through visual exploration and informed choices._

.bmad/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md

@@ -0,0 +1,145 @@
+# {{project_name}} UX Design Specification
+
+_Created on {{date}} by {{user_name}}_
+_Generated using BMad Method - Create UX Design Workflow v1.0_
+
+---
+
+## Executive Summary
+
+{{project_vision}}
+
+---
+
+## 1. Design System Foundation
+
+### 1.1 Design System Choice
+
+{{design_system_decision}}
+
+---
+
+## 2. Core User Experience
+
+### 2.1 Defining Experience
+
+{{core_experience}}
+
+### 2.2 Novel UX Patterns
+
+{{novel_ux_patterns}}
+
+---
+
+## 3. Visual Foundation
+
+### 3.1 Color System
+
+{{visual_foundation}}
+
+**Interactive Visualizations:**
+
+- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
+
+---
+
+## 4. Design Direction
+
+### 4.1 Chosen Design Approach
+
+{{design_direction_decision}}
+
+**Interactive Mockups:**
+
+- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
+
+---
+
+## 5. User Journey Flows
+
+### 5.1 Critical User Paths
+
+{{user_journey_flows}}
+
+---
+
+## 6. Component Library
+
+### 6.1 Component Strategy
+
+{{component_library_strategy}}
+
+---
+
+## 7. UX Pattern Decisions
+
+### 7.1 Consistency Rules
+
+{{ux_pattern_decisions}}
+
+---
+
+## 8. Responsive Design & Accessibility
+
+### 8.1 Responsive Strategy
+
+{{responsive_accessibility_strategy}}
+
+---
+
+## 9. Implementation Guidance
+
+### 9.1 Completion Summary
+
+{{completion_summary}}
+
+---
+
+## Appendix
+
+### Related Documents
+
+- Product Requirements: `{{prd_file}}`
+- Product Brief: `{{brief_file}}`
+- Brainstorming: `{{brainstorm_file}}`
+
+### Core Interactive Deliverables
+
+This UX Design Specification was created through visual collaboration:
+
+- **Color Theme Visualizer**: {{color_themes_html}}
+  - Interactive HTML showing all color theme options explored
+  - Live UI component examples in each theme
+  - Side-by-side comparison and semantic color usage
+
+- **Design Direction Mockups**: {{design_directions_html}}
+  - Interactive HTML with 6-8 complete design approaches
+  - Full-screen mockups of key screens
+  - Design philosophy and rationale for each direction
+
+### Optional Enhancement Deliverables
+
+_This section will be populated if additional UX artifacts are generated through follow-up workflows._
+
+<!-- Additional deliverables added here by other workflows -->
+
+### Next Steps & Follow-Up Workflows
+
+This UX Design Specification can serve as input to:
+
+- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
+- **Figma Design Workflow** - Generate Figma files via MCP integration
+- **Interactive Prototype Workflow** - Build clickable HTML prototypes
+- **Component Showcase Workflow** - Create interactive component library
+- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
+- **Solution Architecture Workflow** - Define technical architecture with UX context
+
+### Version History
+
+| Date     | Version | Changes                         | Author        |
+| -------- | ------- | ------------------------------- | ------------- |
+| {{date}} | 1.0     | Initial UX Design Specification | {{user_name}} |
+
+---
+
+_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._

.bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml

@@ -0,0 +1,60 @@
+# Create UX Design Workflow Configuration
+name: create-ux-design
+description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Input requirements - We work from PRD, Brief, or Brainstorming docs
+recommended_inputs:
+  - prd: "Product Requirements Document with features and user journeys"
+  - product_brief: "Product brief with vision and target users"
+  - brainstorming: "Brainstorming documents with ideas and concepts"
+
+# Input file references (fuzzy matched from output folder)
+prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
+brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
+brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.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"
+
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/2-plan-workflows/create-ux-design"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: "{installed_path}/ux-design-template.md"
+
+# Output configuration - Progressive saves throughout workflow
+default_output_file: "{output_folder}/ux-design-specification.md"
+color_themes_html: "{output_folder}/ux-color-themes.html"
+design_directions_html: "{output_folder}/ux-design-directions.html"
+
+standalone: true
+# Web bundle configuration for standalone deployment

.bmad/bmm/workflows/2-plan-workflows/prd/checklist.md

@@ -0,0 +1,350 @@
+# PRD + Epics + Stories Validation Checklist
+
+**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
+
+**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
+
+**Expected Outputs**:
+
+- PRD.md with complete requirements
+- epics.md with detailed epic and story breakdown
+- Updated bmm-workflow-status.yaml
+
+---
+
+## 1. PRD Document Completeness
+
+### Core Sections Present
+
+- [ ] Executive Summary with vision alignment
+- [ ] Product magic essence clearly articulated
+- [ ] Project classification (type, domain, complexity)
+- [ ] Success criteria defined
+- [ ] Product scope (MVP, Growth, Vision) clearly delineated
+- [ ] Functional requirements comprehensive and numbered
+- [ ] Non-functional requirements (when applicable)
+- [ ] References section with source documents
+
+### Project-Specific Sections
+
+- [ ] **If complex domain:** Domain context and considerations documented
+- [ ] **If innovation:** Innovation patterns and validation approach documented
+- [ ] **If API/Backend:** Endpoint specification and authentication model included
+- [ ] **If Mobile:** Platform requirements and device features documented
+- [ ] **If SaaS B2B:** Tenant model and permission matrix included
+- [ ] **If UI exists:** UX principles and key interactions documented
+
+### Quality Checks
+
+- [ ] No unfilled template variables ({{variable}})
+- [ ] All variables properly populated with meaningful content
+- [ ] Product magic woven throughout (not just stated once)
+- [ ] Language is clear, specific, and measurable
+- [ ] Project type correctly identified and sections match
+- [ ] Domain complexity appropriately addressed
+
+---
+
+## 2. Functional Requirements Quality
+
+### FR Format and Structure
+
+- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
+- [ ] FRs describe WHAT capabilities, not HOW to implement
+- [ ] FRs are specific and measurable
+- [ ] FRs are testable and verifiable
+- [ ] FRs focus on user/business value
+- [ ] No technical implementation details in FRs (those belong in architecture)
+
+### FR Completeness
+
+- [ ] All MVP scope features have corresponding FRs
+- [ ] Growth features documented (even if deferred)
+- [ ] Vision features captured for future reference
+- [ ] Domain-mandated requirements included
+- [ ] Innovation requirements captured with validation needs
+- [ ] Project-type specific requirements complete
+
+### FR Organization
+
+- [ ] FRs organized by capability/feature area (not by tech stack)
+- [ ] Related FRs grouped logically
+- [ ] Dependencies between FRs noted when critical
+- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
+
+---
+
+## 3. Epics Document Completeness
+
+### Required Files
+
+- [ ] epics.md exists in output folder
+- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+- [ ] All epics have detailed breakdown sections
+
+### Epic Quality
+
+- [ ] Each epic has clear goal and value proposition
+- [ ] Each epic includes complete story breakdown
+- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
+- [ ] Each story has numbered acceptance criteria
+- [ ] Prerequisites/dependencies explicitly stated per story
+- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
+
+---
+
+## 4. FR Coverage Validation (CRITICAL)
+
+### Complete Traceability
+
+- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
+- [ ] Each story references relevant FR numbers
+- [ ] No orphaned FRs (requirements without stories)
+- [ ] No orphaned stories (stories without FR connection)
+- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
+
+### Coverage Quality
+
+- [ ] Stories sufficiently decompose FRs into implementable units
+- [ ] Complex FRs broken into multiple stories appropriately
+- [ ] Simple FRs have appropriately scoped single stories
+- [ ] Non-functional requirements reflected in story acceptance criteria
+- [ ] Domain requirements embedded in relevant stories
+
+---
+
+## 5. Story Sequencing Validation (CRITICAL)
+
+### Epic 1 Foundation Check
+
+- [ ] **Epic 1 establishes foundational infrastructure**
+- [ ] Epic 1 delivers initial deployable functionality
+- [ ] Epic 1 creates baseline for subsequent epics
+- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
+
+### Vertical Slicing
+
+- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
+- [ ] No "build database" or "create UI" stories in isolation
+- [ ] Stories integrate across stack (data + logic + presentation when applicable)
+- [ ] Each story leaves system in working/deployable state
+
+### No Forward Dependencies
+
+- [ ] **No story depends on work from a LATER story or epic**
+- [ ] Stories within each epic are sequentially ordered
+- [ ] Each story builds only on previous work
+- [ ] Dependencies flow backward only (can reference earlier stories)
+- [ ] Parallel tracks clearly indicated if stories are independent
+
+### Value Delivery Path
+
+- [ ] Each epic delivers significant end-to-end value
+- [ ] Epic sequence shows logical product evolution
+- [ ] User can see value after each epic completion
+- [ ] MVP scope clearly achieved by end of designated epics
+
+---
+
+## 6. Scope Management
+
+### MVP Discipline
+
+- [ ] MVP scope is genuinely minimal and viable
+- [ ] Core features list contains only true must-haves
+- [ ] Each MVP feature has clear rationale for inclusion
+- [ ] No obvious scope creep in "must-have" list
+
+### Future Work Captured
+
+- [ ] Growth features documented for post-MVP
+- [ ] Vision features captured to maintain long-term direction
+- [ ] Out-of-scope items explicitly listed
+- [ ] Deferred features have clear reasoning for deferral
+
+### Clear Boundaries
+
+- [ ] Stories marked as MVP vs Growth vs Vision
+- [ ] Epic sequencing aligns with MVP → Growth progression
+- [ ] No confusion about what's in vs out of initial scope
+
+---
+
+## 7. Research and Context Integration
+
+### Source Document Integration
+
+- [ ] **If product brief exists:** Key insights incorporated into PRD
+- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
+- [ ] **If research documents exist:** Research findings inform requirements
+- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
+- [ ] All source documents referenced in PRD References section
+
+### Research Continuity to Architecture
+
+- [ ] Domain complexity considerations documented for architects
+- [ ] Technical constraints from research captured
+- [ ] Regulatory/compliance requirements clearly stated
+- [ ] Integration requirements with existing systems documented
+- [ ] Performance/scale requirements informed by research data
+
+### Information Completeness for Next Phase
+
+- [ ] PRD provides sufficient context for architecture decisions
+- [ ] Epics provide sufficient detail for technical design
+- [ ] Stories have enough acceptance criteria for implementation
+- [ ] Non-obvious business rules documented
+- [ ] Edge cases and special scenarios captured
+
+---
+
+## 8. Cross-Document Consistency
+
+### Terminology Consistency
+
+- [ ] Same terms used across PRD and epics for concepts
+- [ ] Feature names consistent between documents
+- [ ] Epic titles match between PRD and epics.md
+- [ ] No contradictions between PRD and epics
+
+### Alignment Checks
+
+- [ ] Success metrics in PRD align with story outcomes
+- [ ] Product magic articulated in PRD reflected in epic goals
+- [ ] Technical preferences in PRD align with story implementation hints
+- [ ] Scope boundaries consistent across all documents
+
+---
+
+## 9. Readiness for Implementation
+
+### Architecture Readiness (Next Phase)
+
+- [ ] PRD provides sufficient context for architecture workflow
+- [ ] Technical constraints and preferences documented
+- [ ] Integration points identified
+- [ ] Performance/scale requirements specified
+- [ ] Security and compliance needs clear
+
+### Development Readiness
+
+- [ ] Stories are specific enough to estimate
+- [ ] Acceptance criteria are testable
+- [ ] Technical unknowns identified and flagged
+- [ ] Dependencies on external systems documented
+- [ ] Data requirements specified
+
+### Track-Appropriate Detail
+
+**If BMad Method:**
+
+- [ ] PRD supports full architecture workflow
+- [ ] Epic structure supports phased delivery
+- [ ] Scope appropriate for product/platform development
+- [ ] Clear value delivery through epic sequence
+
+**If Enterprise Method:**
+
+- [ ] PRD addresses enterprise requirements (security, compliance, multi-tenancy)
+- [ ] Epic structure supports extended planning phases
+- [ ] Scope includes security, devops, and test strategy considerations
+- [ ] Clear value delivery with enterprise gates
+
+---
+
+## 10. Quality and Polish
+
+### Writing Quality
+
+- [ ] Language is clear and free of jargon (or jargon is defined)
+- [ ] Sentences are concise and specific
+- [ ] No vague statements ("should be fast", "user-friendly")
+- [ ] Measurable criteria used throughout
+- [ ] Professional tone appropriate for stakeholder review
+
+### Document Structure
+
+- [ ] Sections flow logically
+- [ ] Headers and numbering consistent
+- [ ] Cross-references accurate (FR numbers, section references)
+- [ ] Formatting consistent throughout
+- [ ] Tables/lists formatted properly
+
+### Completeness Indicators
+
+- [ ] No [TODO] or [TBD] markers remain
+- [ ] No placeholder text
+- [ ] All sections have substantive content
+- [ ] Optional sections either complete or omitted (not half-done)
+
+---
+
+## Critical Failures (Auto-Fail)
+
+If ANY of these are true, validation FAILS:
+
+- [ ] ❌ **No epics.md file exists** (two-file output required)
+- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
+- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
+- [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
+- [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
+- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
+- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
+- [ ] ❌ **Template variables unfilled** (incomplete document)
+
+---
+
+## Validation Summary
+
+**Total Validation Points:** ~85
+
+### Scoring Guide
+
+- **Pass Rate ≥ 95% (81+/85):** ✅ EXCELLENT - Ready for architecture phase
+- **Pass Rate 85-94% (72-80/85):** ⚠️ GOOD - Minor fixes needed
+- **Pass Rate 70-84% (60-71/85):** ⚠️ FAIR - Important issues to address
+- **Pass Rate < 70% (<60/85):** ❌ POOR - Significant rework required
+
+### Critical Issue Threshold
+
+- **0 Critical Failures:** Proceed to fixes
+- **1+ Critical Failures:** STOP - Must fix critical issues first
+
+---
+
+## Validation Execution Notes
+
+**When validating:**
+
+1. **Load ALL documents:**
+   - PRD.md (required)
+   - epics.md (required)
+   - product-brief.md (if exists)
+   - domain-brief.md (if exists)
+   - research documents (if referenced)
+
+2. **Validate in order:**
+   - Check critical failures first (immediate stop if any found)
+   - Verify PRD completeness
+   - Verify epics completeness
+   - Cross-reference FR coverage (most important)
+   - Check sequencing (second most important)
+   - Validate research integration
+   - Check polish and quality
+
+3. **Report findings:**
+   - List critical failures prominently
+   - Group issues by severity
+   - Provide specific line numbers/sections
+   - Suggest concrete fixes
+   - Highlight what's working well
+
+4. **Provide actionable next steps:**
+   - If validation passes: "Ready for architecture workflow"
+   - If minor issues: "Fix [X] items then re-validate"
+   - If major issues: "Rework [sections] then re-validate"
+   - If critical failures: "Must fix critical items before proceeding"
+
+---
+
+**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.

.bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md

@@ -0,0 +1,52 @@
+# {{project_name}} - Epic Breakdown
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+**Project Level:** {{project_level}}
+**Target Scale:** {{target_scale}}
+
+---
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the [PRD](./PRD.md) into implementable stories.
+
+{{epics_summary}}
+
+---
+
+<!-- Repeat for each epic (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+
+**And** {{additional_criteria}}
+
+**Prerequisites:** {{dependencies_on_previous_stories}}
+
+**Technical Notes:** {{implementation_guidance}}
+
+<!-- End story repeat -->
+
+---
+
+<!-- End epic repeat -->
+
+---
+
+_For implementation: Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown._

.bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md

@@ -0,0 +1,169 @@
+# Epic and Story Decomposition - Intent-Based Implementation Planning
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow transforms requirements into BITE-SIZED STORIES for development agents</critical>
+<critical>EVERY story must be completable by a single dev agent in one focused session</critical>
+<critical>Communicate all responses in {communication_language} and adapt to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to epics.md continuously as you work - never wait until the end</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+
+<workflow>
+
+<step n="1" goal="Load PRD and extract requirements">
+<action>Welcome {user_name} to epic and story planning
+
+Load required documents (fuzzy match, handle both whole and sharded):
+
+- PRD.md (required)
+- domain-brief.md (if exists)
+- product-brief.md (if exists)
+
+Extract from PRD:
+
+- All functional requirements
+- Non-functional requirements
+- Domain considerations and compliance needs
+- Project type and complexity
+- MVP vs growth vs vision scope boundaries
+
+Understand the context:
+
+- What makes this product special (the magic)
+- Technical constraints
+- User types and their goals
+- Success criteria</action>
+  </step>
+
+<step n="2" goal="Propose epic structure from natural groupings">
+<action>Analyze requirements and identify natural epic boundaries
+
+INTENT: Find organic groupings that make sense for THIS product
+
+Look for natural patterns:
+
+- Features that work together cohesively
+- User journeys that connect
+- Business capabilities that cluster
+- Domain requirements that relate (compliance, validation, security)
+- Technical systems that should be built together
+
+Name epics based on VALUE, not technical layers:
+
+- Good: "User Onboarding", "Content Discovery", "Compliance Framework"
+- Avoid: "Database Layer", "API Endpoints", "Frontend"
+
+Each epic should:
+
+- Have clear business goal and user value
+- Be independently valuable
+- Contain 3-8 related capabilities
+- Be deliverable in cohesive phase
+
+For greenfield projects:
+
+- First epic MUST establish foundation (project setup, core infrastructure, deployment pipeline)
+- Foundation enables all subsequent work
+
+For complex domains:
+
+- Consider dedicated compliance/regulatory epics
+- Group validation and safety requirements logically
+- Note expertise requirements
+
+Present proposed epic structure showing:
+
+- Epic titles with clear value statements
+- High-level scope of each epic
+- Suggested sequencing
+- Why this grouping makes sense</action>
+
+<template-output>epics_summary</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="3" goal="Decompose each epic into bite-sized stories" repeat="for-each-epic">
+<action>Break down Epic {{N}} into small, implementable stories
+
+INTENT: Create stories sized for single dev agent completion
+
+For each epic, generate:
+
+- Epic title as `epic_title_{{N}}`
+- Epic goal/value as `epic_goal_{{N}}`
+- All stories as repeated pattern `story_title_{{N}}_{{M}}` for each story M
+
+CRITICAL for Epic 1 (Foundation):
+
+- Story 1.1 MUST be project setup/infrastructure initialization
+- Sets up: repo structure, build system, deployment pipeline basics, core dependencies
+- Creates foundation for all subsequent stories
+- Note: Architecture workflow will flesh out technical details
+
+Each story should follow BDD-style acceptance criteria:
+
+**Story Pattern:**
+As a [user type],
+I want [specific capability],
+So that [clear value/benefit].
+
+**Acceptance Criteria using BDD:**
+Given [precondition or initial state]
+When [action or trigger]
+Then [expected outcome]
+
+And [additional criteria as needed]
+
+**Prerequisites:** Only previous stories (never forward dependencies)
+
+**Technical Notes:** Implementation guidance, affected components, compliance requirements
+
+Ensure stories are:
+
+- Vertically sliced (deliver complete functionality, not just one layer)
+- Sequentially ordered (logical progression, no forward dependencies)
+- Independently valuable when possible
+- Small enough for single-session completion
+- Clear enough for autonomous implementation
+
+For each story in epic {{N}}, output variables following this pattern:
+
+- story*title*{{N}}_1, story_title_{{N}}\_2, etc.
+- Each containing: user story, BDD acceptance criteria, prerequisites, technical notes</action>
+
+<template-output>epic*title*{{N}}</template-output>
+<template-output>epic*goal*{{N}}</template-output>
+
+<action>For each story M in epic {{N}}, generate story content</action>
+<template-output>story*title*{{N}}\_{{M}}</template-output>
+
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="4" goal="Review and finalize epic breakdown">
+<action>Review the complete epic breakdown for quality and completeness
+
+Validate:
+
+- All functional requirements from PRD are covered by stories
+- Epic 1 establishes proper foundation
+- All stories are vertically sliced
+- No forward dependencies exist
+- Story sizing is appropriate for single-session completion
+- BDD acceptance criteria are clear and testable
+- Domain/compliance requirements are properly distributed
+- Sequencing enables incremental value delivery
+
+Confirm with {user_name}:
+
+- Epic structure makes sense
+- Story breakdown is actionable
+- Dependencies are clear
+- BDD format provides clarity
+- Ready for architecture and implementation phases</action>
+
+<template-output>epic_breakdown_summary</template-output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml

@@ -0,0 +1,45 @@
+# Epic and Story Decomposition Workflow
+name: create-epics-and-stories
+description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+project_name: "{config_source}:project_name"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Input requirements
+recommended_inputs:
+  - prd: "Product Requirements Document with FRs and NFRs"
+  - product_brief: "Product Brief with vision and goals (optional)"
+  - domain_brief: "Domain-specific requirements and context (optional)"
+
+# 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"
+
+  product_brief:
+    whole: "{output_folder}/*product*brief*.md"
+    sharded: "{output_folder}/*product*brief*/index.md"
+
+  domain_brief:
+    whole: "{output_folder}/*domain*brief*.md"
+    sharded: "{output_folder}/*domain*brief*/index.md"
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/epics-template.md"
+
+# Output configuration
+default_output_file: "{output_folder}/epics.md"
+
+standalone: true

.bmad/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv

@@ -0,0 +1,13 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"

.bmad/bmm/workflows/2-plan-workflows/prd/instructions.md

@@ -0,0 +1,408 @@
+# PRD Workflow - Intent-Driven Product Planning
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
+<critical>GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+
+<workflow>
+
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {status_file} exists</action>
+
+<action if="status file not found">Set standalone_mode = true</action>
+
+<check if="status file found">
+  <action>Load the FULL file: {status_file}</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "prd" workflow</action>
+  <action>Get project_track from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="project_track is Quick Flow">
+    <output>**Quick Flow Track - Redirecting**
+
+Quick Flow projects use tech-spec workflow for implementation-focused planning.
+PRD is for BMad Method and Enterprise Method tracks that need comprehensive requirements.</output>
+<action>Exit and suggest tech-spec workflow</action>
+</check>
+
+  <check if="prd status is file path (already completed)">
+    <output>⚠️ PRD already completed: {{prd status}}</output>
+    <ask>Re-running will overwrite the existing PRD. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
+</step>
+
+<step n="1" goal="Discovery - Project, Domain, and Vision">
+<action>Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT:
+1. Check workflow-status.yaml for project_context (if exists)
+2. Look for existing documents (Product Brief, Domain Brief, research)
+3. Detect project type AND domain complexity
+
+Load references:
+{installed_path}/project-types.csv
+{installed_path}/domain-complexity.csv
+
+Through natural conversation:
+"Tell me about what you want to build - what problem does it solve and for whom?"
+
+DUAL DETECTION:
+Project type signals: API, mobile, web, CLI, SDK, SaaS
+Domain complexity signals: medical, finance, government, education, aerospace
+
+SPECIAL ROUTING:
+If game detected → Inform user that game development requires the BMGD module (BMad Game Development)
+If complex domain detected → Offer domain research options:
+A) Run domain-research workflow (thorough)
+B) Quick web search (basic)
+C) User provides context
+D) Continue with general knowledge
+
+CAPTURE THE MAGIC EARLY with a few questions such as for example: "What excites you most about this product?", "What would make users love this?", "What's the moment that will make people go 'wow'?"
+
+This excitement becomes the thread woven throughout the PRD.</action>
+
+<template-output>vision_alignment</template-output>
+<template-output>project_classification</template-output>
+<template-output>project_type</template-output>
+<template-output>domain_type</template-output>
+<template-output>complexity_level</template-output>
+<check if="complex domain">
+<template-output>domain_context_summary</template-output>
+</check>
+<template-output>product_magic_essence</template-output>
+<template-output>product_brief_path</template-output>
+<template-output>domain_brief_path</template-output>
+<template-output>research_documents</template-output>
+</step>
+
+<step n="2" goal="Success Definition">
+<action>Define what winning looks like for THIS specific product
+
+INTENT: Meaningful success criteria, not generic metrics
+
+Adapt to context:
+
+- Consumer: User love, engagement, retention
+- B2B: ROI, efficiency, adoption
+- Developer tools: Developer experience, community
+- Regulated: Compliance, safety, validation
+
+Make it specific:
+
+- NOT: "10,000 users"
+- BUT: "100 power users who rely on it daily"
+
+- NOT: "99.9% uptime"
+- BUT: "Zero data loss during critical operations"
+
+Weave in the magic:
+
+- "Success means users experience [that special moment] and [desired outcome]"</action>
+
+<template-output>success_criteria</template-output>
+<check if="business focus">
+<template-output>business_metrics</template-output>
+</check>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="3" goal="Scope Definition">
+<action>Smart scope negotiation - find the sweet spot
+
+The Scoping Game:
+
+1. "What must work for this to be useful?" → MVP
+2. "What makes it competitive?" → Growth
+3. "What's the dream version?" → Vision
+
+Challenge scope creep conversationally:
+
+- "Could that wait until after launch?"
+- "Is that essential for proving the concept?"
+
+For complex domains:
+
+- Include compliance minimums in MVP
+- Note regulatory gates between phases</action>
+
+<template-output>mvp_scope</template-output>
+<template-output>growth_features</template-output>
+<template-output>vision_features</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="4" goal="Domain-Specific Exploration" optional="true">
+<action>Only if complex domain detected or domain-brief exists
+
+Synthesize domain requirements that will shape everything:
+
+- Regulatory requirements
+- Compliance needs
+- Industry standards
+- Safety/risk factors
+- Required validations
+- Special expertise needed
+
+These inform:
+
+- What features are mandatory
+- What NFRs are critical
+- How to sequence development
+- What validation is required</action>
+
+<check if="complex domain">
+  <template-output>domain_considerations</template-output>
+</check>
+</step>
+
+<step n="5" goal="Innovation Discovery" optional="true">
+<action>Identify truly novel patterns if applicable
+
+Listen for innovation signals:
+
+- "Nothing like this exists"
+- "We're rethinking how [X] works"
+- "Combining [A] with [B] for the first time"
+
+Explore deeply:
+
+- What makes it unique?
+- What assumption are you challenging?
+- How do we validate it?
+- What's the fallback?
+
+<WebSearch if="novel">{concept} innovations {date}</WebSearch></action>
+
+<check if="innovation detected">
+  <template-output>innovation_patterns</template-output>
+  <template-output>validation_approach</template-output>
+</check>
+</step>
+
+<step n="6" goal="Project-Specific Deep Dive">
+<action>Based on detected project type, dive deep into specific needs
+
+Load project type requirements from CSV and expand naturally.
+
+FOR API/BACKEND:
+
+- Map out endpoints, methods, parameters
+- Define authentication and authorization
+- Specify error codes and rate limits
+- Document data schemas
+
+FOR MOBILE:
+
+- Platform requirements (iOS/Android/both)
+- Device features needed
+- Offline capabilities
+- Store compliance
+
+FOR SAAS B2B:
+
+- Multi-tenant architecture
+- Permission models
+- Subscription tiers
+- Critical integrations
+
+[Continue for other types...]
+
+Always relate back to the product magic:
+"How does [requirement] enhance [the special thing]?"</action>
+
+<template-output>project_type_requirements</template-output>
+
+<!-- Dynamic sections based on project type -->
+<check if="API/Backend project">
+  <template-output>endpoint_specification</template-output>
+  <template-output>authentication_model</template-output>
+</check>
+
+<check if="Mobile project">
+  <template-output>platform_requirements</template-output>
+  <template-output>device_features</template-output>
+</check>
+
+<check if="SaaS B2B project">
+  <template-output>tenant_model</template-output>
+  <template-output>permission_matrix</template-output>
+</check>
+</step>
+
+<step n="7" goal="UX Principles" if="project has UI or UX">
+  <action>Only if product has a UI
+
+Light touch on UX - not full design:
+
+- Visual personality
+- Key interaction patterns
+- Critical user flows
+
+"How should this feel to use?"
+"What's the vibe - professional, playful, minimal?"
+
+Connect to the magic:
+"The UI should reinforce [the special moment] through [design approach]"</action>
+
+  <check if="has UI">
+    <template-output>ux_principles</template-output>
+    <template-output>key_interactions</template-output>
+  </check>
+</step>
+
+<step n="8" goal="Functional Requirements Synthesis">
+<action>Transform everything discovered into clear functional requirements
+
+Pull together:
+
+- Core features from scope
+- Domain-mandated features
+- Project-type specific needs
+- Innovation requirements
+
+Organize by capability, not technology:
+
+- User Management (not "auth system")
+- Content Discovery (not "search algorithm")
+- Team Collaboration (not "websockets")
+
+Each requirement should:
+
+- Be specific and measurable
+- Connect to user value
+- Include acceptance criteria
+- Note domain constraints
+
+The magic thread:
+Highlight which requirements deliver the special experience</action>
+
+<template-output>functional_requirements_complete</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="9" goal="Non-Functional Requirements Discovery">
+<action>Only document NFRs that matter for THIS product
+
+Performance: Only if user-facing impact
+Security: Only if handling sensitive data
+Scale: Only if growth expected
+Accessibility: Only if broad audience
+Integration: Only if connecting systems
+
+For each NFR:
+
+- Why it matters for THIS product
+- Specific measurable criteria
+- Domain-driven requirements
+
+Skip categories that don't apply!</action>
+
+<!-- Only output sections that were discussed -->
+<check if="performance matters">
+  <template-output>performance_requirements</template-output>
+</check>
+<check if="security matters">
+  <template-output>security_requirements</template-output>
+</check>
+<check if="scale matters">
+  <template-output>scalability_requirements</template-output>
+</check>
+<check if="accessibility matters">
+  <template-output>accessibility_requirements</template-output>
+</check>
+<check if="integration matters">
+  <template-output>integration_requirements</template-output>
+</check>
+</step>
+
+<step n="10" goal="Review PRD and transition to epics">
+<action>Review the PRD we've built together
+
+"Let's review what we've captured:
+
+- Vision: [summary]
+- Success: [key metrics]
+- Scope: [MVP highlights]
+- Requirements: [count] functional, [count] non-functional
+- Special considerations: [domain/innovation]
+
+Does this capture your product vision?"</action>
+
+<template-output>prd_summary</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+
+<action>After PRD review and refinement complete:
+
+"Excellent! Now we need to break these requirements into implementable epics and stories.
+
+For the epic breakdown, you have two options:
+
+1. Start a new session focused on epics (recommended for complex projects)
+2. Continue here (I'll transform requirements into epics now)
+
+Which would you prefer?"
+
+If new session:
+"To start epic planning in a new session:
+
+1. Save your work here
+2. Start fresh and run: workflow epics-stories
+3. It will load your PRD and create the epic breakdown
+
+This keeps each session focused and manageable."
+
+If continue:
+"Let's continue with epic breakdown here..."
+[Proceed with epics-stories subworkflow]
+Set project_track based on workflow status (BMad Method or Enterprise Method)
+Generate epic_details for the epics breakdown document</action>
+
+<template-output>project_track</template-output>
+<template-output>epic_details</template-output>
+</step>
+
+<step n="11" goal="Complete PRD and suggest next steps">
+<template-output>product_magic_summary</template-output>
+
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {status_file}</action>
+  <action>Update workflow_status["prd"] = "{default_output_file}"</action>
+  <action>Save file, preserving ALL comments and structure</action>
+</check>
+
+<output>**✅ PRD Complete, {user_name}!**
+
+Your product requirements are documented and ready for implementation.
+
+**Created:**
+
+- **PRD.md** - Complete requirements adapted to {project_type} and {domain}
+
+**Next Steps:**
+
+1. **Epic Breakdown** (Required)
+   Run: `workflow create-epics-and-stories` to decompose requirements into implementable stories
+
+2. **UX Design** (If UI exists)
+   Run: `workflow ux-design` for detailed user experience design
+
+3. **Architecture** (Recommended)
+   Run: `workflow create-architecture` for technical architecture decisions
+
+The magic of your product - {product_magic_summary} - is woven throughout the PRD and will guide all subsequent work.
+</output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md

@@ -0,0 +1,237 @@
+# {{project_name}} - Product Requirements Document
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+**Version:** 1.0
+
+---
+
+## Executive Summary
+
+{{vision_alignment}}
+
+### What Makes This Special
+
+{{product_magic_essence}}
+
+---
+
+## Project Classification
+
+**Technical Type:** {{project_type}}
+**Domain:** {{domain_type}}
+**Complexity:** {{complexity_level}}
+
+{{project_classification}}
+
+{{#if domain_context_summary}}
+
+### Domain Context
+
+{{domain_context_summary}}
+{{/if}}
+
+---
+
+## Success Criteria
+
+{{success_criteria}}
+
+{{#if business_metrics}}
+
+### Business Metrics
+
+{{business_metrics}}
+{{/if}}
+
+---
+
+## Product Scope
+
+### MVP - Minimum Viable Product
+
+{{mvp_scope}}
+
+### Growth Features (Post-MVP)
+
+{{growth_features}}
+
+### Vision (Future)
+
+{{vision_features}}
+
+---
+
+{{#if domain_considerations}}
+
+## Domain-Specific Requirements
+
+{{domain_considerations}}
+
+This section shapes all functional and non-functional requirements below.
+{{/if}}
+
+---
+
+{{#if innovation_patterns}}
+
+## Innovation & Novel Patterns
+
+{{innovation_patterns}}
+
+### Validation Approach
+
+{{validation_approach}}
+{{/if}}
+
+---
+
+{{#if project_type_requirements}}
+
+## {{project_type}} Specific Requirements
+
+{{project_type_requirements}}
+
+{{#if endpoint_specification}}
+
+### API Specification
+
+{{endpoint_specification}}
+{{/if}}
+
+{{#if authentication_model}}
+
+### Authentication & Authorization
+
+{{authentication_model}}
+{{/if}}
+
+{{#if platform_requirements}}
+
+### Platform Support
+
+{{platform_requirements}}
+{{/if}}
+
+{{#if device_features}}
+
+### Device Capabilities
+
+{{device_features}}
+{{/if}}
+
+{{#if tenant_model}}
+
+### Multi-Tenancy Architecture
+
+{{tenant_model}}
+{{/if}}
+
+{{#if permission_matrix}}
+
+### Permissions & Roles
+
+{{permission_matrix}}
+{{/if}}
+{{/if}}
+
+---
+
+{{#if ux_principles}}
+
+## User Experience Principles
+
+{{ux_principles}}
+
+### Key Interactions
+
+{{key_interactions}}
+{{/if}}
+
+---
+
+## Functional Requirements
+
+{{functional_requirements_complete}}
+
+---
+
+## Non-Functional Requirements
+
+{{#if performance_requirements}}
+
+### Performance
+
+{{performance_requirements}}
+{{/if}}
+
+{{#if security_requirements}}
+
+### Security
+
+{{security_requirements}}
+{{/if}}
+
+{{#if scalability_requirements}}
+
+### Scalability
+
+{{scalability_requirements}}
+{{/if}}
+
+{{#if accessibility_requirements}}
+
+### Accessibility
+
+{{accessibility_requirements}}
+{{/if}}
+
+{{#if integration_requirements}}
+
+### Integration
+
+{{integration_requirements}}
+{{/if}}
+
+{{#if no_nfrs}}
+_No specific non-functional requirements identified for this project type._
+{{/if}}
+
+---
+
+## Implementation Planning
+
+### Epic Breakdown Required
+
+Requirements must be decomposed into epics and bite-sized stories (200k context limit).
+
+**Next Step:** Run `workflow epics-stories` to create the implementation breakdown.
+
+---
+
+## References
+
+{{#if product_brief_path}}
+
+- Product Brief: {{product_brief_path}}
+  {{/if}}
+  {{#if domain_brief_path}}
+- Domain Brief: {{domain_brief_path}}
+  {{/if}}
+  {{#if research_documents}}
+- Research: {{research_documents}}
+  {{/if}}
+
+---
+
+## Next Steps
+
+1. **Epic & Story Breakdown** - Run: `workflow epics-stories`
+2. **UX Design** (if UI) - Run: `workflow ux-design`
+3. **Architecture** - Run: `workflow create-architecture`
+
+---
+
+_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
+
+_Created through collaborative discovery between {{user_name}} and AI facilitator._

.bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv

@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO GAME WORKFLOWS","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"

.bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml

@@ -0,0 +1,46 @@
+# Product Requirements Document (PRD) Workflow
+name: prd
+description: "Unified PRD workflow for BMad Method and Enterprise Method tracks. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Quick Flow track uses tech-spec workflow."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+project_name: "{config_source}:project_name"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/2-plan-workflows/prd"
+instructions: "{installed_path}/instructions.md"
+
+# Templates
+prd_template: "{installed_path}/prd-template.md"
+
+# Output files
+status_file: "{output_folder}/bmm-workflow-status.yaml"
+default_output_file: "{output_folder}/PRD.md"
+
+# Recommended input documents
+recommended_inputs:
+  - product_brief: "{output_folder}/product-brief.md"
+  - market_research: "{output_folder}/market-research.md"
+
+# 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

.bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md

@@ -0,0 +1,214 @@
+# Tech-Spec Workflow Validation Checklist
+
+**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
+
+**Scope**: Levels 0-1 software projects
+
+**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
+
+**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
+
+---
+
+## 1. Output Files Exist
+
+- [ ] tech-spec.md created in output folder
+- [ ] Story file(s) created in dev_ephemeral_location
+  - Level 0: 1 story file (story-{slug}.md)
+  - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
+- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
+- [ ] No unfilled {{template_variables}} in any files
+
+---
+
+## 2. Context Gathering (NEW - CRITICAL)
+
+### Document Discovery
+
+- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist)
+- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map)
+- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized
+- [ ] **Context summary**: loaded_documents_summary lists all sources used
+
+### Project Stack Detection
+
+- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed
+- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2")
+- [ ] **Dependencies extracted**: All production dependencies with specific versions
+- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions
+- [ ] **Scripts documented**: Available npm/pip/etc scripts identified
+- [ ] **Stack summary**: project_stack_summary is complete and accurate
+
+### Brownfield Analysis (if applicable)
+
+- [ ] **Directory structure**: Main code directories identified and documented
+- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.)
+- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.)
+- [ ] **Key modules**: Important existing modules/services identified
+- [ ] **Testing patterns**: Test framework and patterns documented
+- [ ] **Structure summary**: existing_structure_summary is comprehensive
+
+---
+
+## 3. Tech-Spec Definitiveness (CRITICAL)
+
+### No Ambiguity Allowed
+
+- [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include"
+- [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions
+  - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)"
+  - ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston"
+- [ ] **Definitive decisions**: Every technical choice is final, not a proposal
+- [ ] **Stack-aligned**: Decisions reference detected project stack
+
+### Implementation Clarity
+
+- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
+  - ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
+  - ❌ BAD: "Update some files in the services folder"
+- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack
+- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable)
+- [ ] **Integration points**: Specific modules, APIs, services identified
+
+---
+
+## 4. Context-Rich Content (NEW)
+
+### Context Section
+
+- [ ] **Available Documents**: Lists all loaded documents
+- [ ] **Project Stack**: Complete framework and dependency information
+- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation
+
+### The Change Section
+
+- [ ] **Problem Statement**: Clear, specific problem definition
+- [ ] **Proposed Solution**: Concrete solution approach
+- [ ] **Scope In/Out**: Clear boundaries defined
+
+### Development Context Section
+
+- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield)
+- [ ] **Framework Dependencies**: Complete list with exact versions from project
+- [ ] **Internal Dependencies**: Internal modules listed
+- [ ] **Configuration Changes**: Specific config file updates identified
+
+### Developer Resources Section
+
+- [ ] **File Paths Reference**: Complete list of all files involved
+- [ ] **Key Code Locations**: Functions, classes, modules with file:line references
+- [ ] **Testing Locations**: Specific test directories and patterns
+- [ ] **Documentation Updates**: Docs that need updating identified
+
+---
+
+## 5. Story Quality
+
+### Story Format
+
+- [ ] All stories use "As a [role], I want [capability], so that [benefit]" format
+- [ ] Each story has numbered acceptance criteria
+- [ ] Tasks reference AC numbers: (AC: #1), (AC: #2)
+- [ ] Dev Notes section links to tech-spec.md
+
+### Story Context Integration (NEW)
+
+- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context
+- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.)
+- [ ] **Test Results section**: Placeholder ready for dev execution
+- [ ] **Review Notes section**: Placeholder ready for code review
+
+### Story Sequencing (If Level 1)
+
+- [ ] **Vertical slices**: Each story delivers complete, testable functionality
+- [ ] **Sequential ordering**: Stories in logical progression
+- [ ] **No forward dependencies**: No story depends on later work
+- [ ] Each story leaves system in working state
+
+### Coverage
+
+- [ ] Story acceptance criteria derived from tech-spec
+- [ ] Story tasks map to tech-spec implementation guide
+- [ ] Files in stories match tech-spec source tree
+- [ ] Key code references align with tech-spec Developer Resources
+
+---
+
+## 6. Epic Quality (Level 1 Only)
+
+- [ ] **Epic title**: User-focused outcome (not implementation detail)
+- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
+- [ ] **Epic goal**: Clear purpose and value statement
+- [ ] **Epic scope**: Boundaries clearly defined
+- [ ] **Success criteria**: Measurable outcomes
+- [ ] **Story map**: Visual representation of epic → stories
+- [ ] **Implementation sequence**: Logical story ordering with dependencies
+- [ ] **Tech-spec reference**: Links back to tech-spec.md
+
+---
+
+## 7. Workflow Status Integration
+
+- [ ] bmm-workflow-status.yaml updated (if exists)
+- [ ] Current phase reflects tech-spec completion
+- [ ] Progress percentage updated appropriately
+- [ ] Next workflow clearly identified
+
+---
+
+## 8. Implementation Readiness (NEW - ENHANCED)
+
+### Can Developer Start Immediately?
+
+- [ ] **All context available**: Brownfield analysis + stack details + existing patterns
+- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns
+- [ ] **Specific file paths**: Developer knows exactly which files to create/modify
+- [ ] **Code references**: Can find similar code to reference (brownfield)
+- [ ] **Testing clear**: Knows what to test and how
+- [ ] **Deployment documented**: Knows how to deploy and rollback
+
+### Tech-Spec Replaces Story-Context?
+
+- [ ] **Comprehensive enough**: Contains all info typically in story-context XML
+- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance
+- [ ] **Framework specifics**: Exact versions and usage patterns
+- [ ] **Pattern guidance**: Shows examples of existing patterns to follow
+
+---
+
+## 9. Critical Failures (Auto-Fail)
+
+- [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices)
+- [ ] ❌ **Missing versions** (framework/library without specific version)
+- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.)
+- [ ] ❌ **Stack mismatch** (decisions don't align with detected project stack)
+- [ ] ❌ **Stories don't match template** (missing Dev Agent Record sections)
+- [ ] ❌ **Missing tech-spec sections** (required section missing from enhanced template)
+- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
+- [ ] ❌ **Vague source tree** (file changes not specific with actions)
+- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used)
+
+---
+
+## Validation Notes
+
+**Document any findings:**
+
+- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
+- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
+- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
+- **Stack Alignment**: [Perfect / Good / Partial / None]
+
+## **Strengths:**
+
+## **Issues to address:**
+
+## **Recommended actions:**
+
+**Ready for implementation?** [Yes / No - explain]
+
+**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A]
+
+---
+
+_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._

.bmad/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md

@@ -0,0 +1,80 @@
+# {{project_name}} - Epic Breakdown
+
+**Date:** {{date}}
+**Project Level:** {{project_level}}
+
+---
+
+<!-- Repeat for each epic (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+**Slug:** {{epic_slug_N}}
+
+### Goal
+
+{{epic_goal_N}}
+
+### Scope
+
+{{epic_scope_N}}
+
+### Success Criteria
+
+{{epic_success_criteria_N}}
+
+### Dependencies
+
+{{epic_dependencies_N}}
+
+---
+
+## Story Map - Epic {{N}}
+
+{{story_map_N}}
+
+---
+
+## Stories - Epic {{N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+
+**And** {{additional_criteria}}
+
+**Prerequisites:** {{dependencies_on_previous_stories}}
+
+**Technical Notes:** {{implementation_guidance}}
+
+**Estimated Effort:** {{story_points}} points ({{time_estimate}})
+
+<!-- End story repeat -->
+
+---
+
+## Implementation Timeline - Epic {{N}}
+
+**Total Story Points:** {{total_points_N}}
+
+**Estimated Timeline:** {{estimated_timeline_N}}
+
+---
+
+<!-- End epic repeat -->
+
+---
+
+## Tech-Spec Reference
+
+See [tech-spec.md](../tech-spec.md) for complete technical implementation details.

.bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md

@@ -0,0 +1,200 @@
+# Level 0 - Minimal User Story Generation
+
+<workflow>
+
+<critical>This generates a single user story for Level 0 atomic changes</critical>
+<critical>Level 0 = single file change, bug fix, or small isolated task</critical>
+<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
+<critical>Output format MUST match create-story template for compatibility with story-context and dev-story workflows</critical>
+
+<step n="1" goal="Load tech spec and extract the change">
+
+<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
+<action>Extract dev_ephemeral_location from config (where stories are stored)</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Problem statement from "The Change → Problem Statement" section
+- Solution overview from "The Change → Proposed Solution" section
+- Scope from "The Change → Scope" section
+- Source tree from "Implementation Details → Source Tree Changes" section
+- Time estimate from "Implementation Guide → Implementation Steps" section
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
+- Framework dependencies from "Development Context → Framework/Libraries" section
+- Existing code references from "Development Context → Relevant Existing Code" section
+- File paths from "Developer Resources → File Paths Reference" section
+- Key code locations from "Developer Resources → Key Code Locations" section
+- Testing locations from "Developer Resources → Testing Locations" section
+  </action>
+
+</step>
+
+<step n="2" goal="Generate story slug and filename">
+
+<action>Derive a short URL-friendly slug from the feature/change name</action>
+<action>Max slug length: 3-5 words, kebab-case format</action>
+
+<example>
+- "Migrate JS Library Icons" → "icon-migration"
+- "Fix Login Validation Bug" → "login-fix"
+- "Add OAuth Integration" → "oauth-integration"
+</example>
+
+<action>Set story_filename = "story-{slug}.md"</action>
+<action>Set story_path = "{dev_ephemeral_location}/story-{slug}.md"</action>
+
+</step>
+
+<step n="3" goal="Create user story in standard format">
+
+<action>Create 1 story that describes the technical change as a deliverable</action>
+<action>Story MUST use create-story template format for compatibility</action>
+
+<guidelines>
+**Story Point Estimation:**
+- 1 point = < 1 day (2-4 hours)
+- 2 points = 1-2 days
+- 3 points = 2-3 days
+- 5 points = 3-5 days (if this high, question if truly Level 0)
+
+**Story Title Best Practices:**
+
+- Use active, user-focused language
+- Describe WHAT is delivered, not HOW
+- Good: "Icon Migration to Internal CDN"
+- Bad: "Run curl commands to download PNGs"
+
+**Story Description Format:**
+
+- As a [role] (developer, user, admin, etc.)
+- I want [capability/change]
+- So that [benefit/value]
+
+**Acceptance Criteria:**
+
+- Extract from tech-spec "Testing Approach" section
+- Must be specific, measurable, and testable
+- Include performance criteria if specified
+
+**Tasks/Subtasks:**
+
+- Map directly to tech-spec "Implementation Guide" tasks
+- Use checkboxes for tracking
+- Reference AC numbers: (AC: #1), (AC: #2)
+- Include explicit testing subtasks
+
+**Dev Notes:**
+
+- Extract technical constraints from tech-spec
+- Include file paths from "Developer Resources → File Paths Reference"
+- Include existing code references from "Development Context → Relevant Existing Code"
+- Reference architecture patterns if applicable
+- Cite tech-spec sections for implementation details
+- Note dependencies (internal and external)
+
+**NEW: Comprehensive Context**
+
+Since tech-spec is now context-rich, populate all new template fields:
+
+- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
+  </guidelines>
+
+<action>Initialize story file using user_story_template</action>
+
+<template-output file="{story_path}">story_title</template-output>
+<template-output file="{story_path}">role</template-output>
+<template-output file="{story_path}">capability</template-output>
+<template-output file="{story_path}">benefit</template-output>
+<template-output file="{story_path}">acceptance_criteria</template-output>
+<template-output file="{story_path}">tasks_subtasks</template-output>
+<template-output file="{story_path}">technical_summary</template-output>
+<template-output file="{story_path}">files_to_modify</template-output>
+<template-output file="{story_path}">test_locations</template-output>
+<template-output file="{story_path}">story_points</template-output>
+<template-output file="{story_path}">time_estimate</template-output>
+<template-output file="{story_path}">dependencies</template-output>
+<template-output file="{story_path}">existing_code_references</template-output>
+<template-output file="{story_path}">architecture_references</template-output>
+
+</step>
+
+<step n="4" goal="Update status - Level 0 single story">
+
+<invoke-workflow path="{project-root}/.bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: tech-spec</param>
+</invoke-workflow>
+
+<check if="success == true">
+  <output>✅ Tech-spec complete! Next: {{next_workflow}}</output>
+</check>
+
+<action>Load {{status_file_path}}</action>
+<action>Set STORIES_SEQUENCE: [{slug}]</action>
+<action>Set TODO_STORY: {slug}</action>
+<action>Set TODO_TITLE: {{story_title}}</action>
+<action>Set IN_PROGRESS_STORY: (empty)</action>
+<action>Set STORIES_DONE: []</action>
+<action>Save {{status_file_path}}</action>
+
+<output>Story queue initialized with single story: {slug}</output>
+
+</step>
+
+<step n="5" goal="Provide user guidance for next steps">
+
+<action>Display completion summary</action>
+
+**Level 0 Planning Complete!**
+
+**Generated Artifacts:**
+
+- `tech-spec.md` → Technical source of truth
+- `story-{slug}.md` → User story ready for implementation
+
+**Story Location:** `{story_path}`
+
+**Next Steps:**
+
+**🎯 RECOMMENDED - Direct to Development (Level 0):**
+
+Since the tech-spec is now CONTEXT-RICH with:
+
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+
+**You can skip story-context and go straight to dev!**
+
+1. Load DEV agent: `{project-root}/.bmad/bmm/agents/dev.md`
+2. Run `dev-story` workflow
+3. Begin implementation immediately
+
+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex scenarios:
+
+1. Load SM agent: `{project-root}/.bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow (generates additional XML context)
+3. Then load DEV agent and run `dev-story` workflow
+
+**Progress Tracking:**
+
+- All decisions logged in: `bmm-workflow-status.yaml`
+- Next action clearly identified
+
+<ask>Ready to proceed? Choose your path:
+
+1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context (for complex edge cases)
+3. Exit for now
+
+Select option (1-3):</ask>
+
+</step>
+
+</workflow>

.bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md

@@ -0,0 +1,451 @@
+# Level 1 - Epic and Stories Generation
+
+<workflow>
+
+<critical>This generates epic and user stories for Level 1 projects after tech-spec completion</critical>
+<critical>This is a lightweight story breakdown - not a full PRD</critical>
+<critical>Level 1 = coherent feature, 1-10 stories (prefer 2-3), 1 epic</critical>
+<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
+<critical>Story format MUST match create-story template for compatibility with story-context and dev-story workflows</critical>
+
+<step n="1" goal="Load tech spec and extract implementation tasks">
+
+<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
+<action>Extract dev_ephemeral_location from config (where stories are stored)</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
+- Implementation tasks from "Implementation Guide → Implementation Steps"
+- Time estimates from "Implementation Guide → Implementation Steps"
+- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
+- Source tree from "Implementation Details → Source Tree Changes"
+- Framework dependencies from "Development Context → Framework/Libraries"
+- Existing code references from "Development Context → Relevant Existing Code"
+- File paths from "Developer Resources → File Paths Reference"
+- Key code locations from "Developer Resources → Key Code Locations"
+- Testing locations from "Developer Resources → Testing Locations"
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
+  </action>
+
+</step>
+
+<step n="2" goal="Create single epic">
+
+<action>Create 1 epic that represents the entire feature</action>
+<action>Epic title should be user-facing value statement</action>
+<action>Epic goal should describe why this matters to users</action>
+
+<guidelines>
+**Epic Best Practices:**
+- Title format: User-focused outcome (not implementation detail)
+- Good: "JS Library Icon Reliability"
+- Bad: "Update recommendedLibraries.ts file"
+- Scope: Clearly define what's included/excluded
+- Success criteria: Measurable outcomes that define "done"
+</guidelines>
+
+<example>
+**Epic:** JS Library Icon Reliability
+
+**Goal:** Eliminate external dependencies for JS library icons to ensure consistent, reliable display and improve application performance.
+
+**Scope:** Migrate all 14 recommended JS library icons from third-party CDN URLs (GitHub, jsDelivr) to internal static asset hosting.
+
+**Success Criteria:**
+
+- All library icons load from internal paths
+- Zero external requests for library icons
+- Icons load 50-200ms faster than baseline
+- No broken icons in production
+  </example>
+
+<action>Derive epic slug from epic title (kebab-case, 2-3 words max)</action>
+<example>
+
+- "JS Library Icon Reliability" → "icon-reliability"
+- "OAuth Integration" → "oauth-integration"
+- "Admin Dashboard" → "admin-dashboard"
+  </example>
+
+<action>Initialize epics.md summary document using epics_template</action>
+
+<action>Also capture project_level for the epic template</action>
+
+<template-output file="{output_folder}/epics.md">project_level</template-output>
+<template-output file="{output_folder}/epics.md">epic_title</template-output>
+<template-output file="{output_folder}/epics.md">epic_slug</template-output>
+<template-output file="{output_folder}/epics.md">epic_goal</template-output>
+<template-output file="{output_folder}/epics.md">epic_scope</template-output>
+<template-output file="{output_folder}/epics.md">epic_success_criteria</template-output>
+<template-output file="{output_folder}/epics.md">epic_dependencies</template-output>
+
+</step>
+
+<step n="3" goal="Determine optimal story count">
+
+<critical>Level 1 should have 2-3 stories maximum - prefer longer stories over more stories</critical>
+
+<action>Analyze tech spec implementation tasks and time estimates</action>
+<action>Group related tasks into logical story boundaries</action>
+
+<guidelines>
+**Story Count Decision Matrix:**
+
+**2 Stories (preferred for most Level 1):**
+
+- Use when: Feature has clear build/verify split
+- Example: Story 1 = Build feature, Story 2 = Test and deploy
+- Typical points: 3-5 points per story
+
+**3 Stories (only if necessary):**
+
+- Use when: Feature has distinct setup, build, verify phases
+- Example: Story 1 = Setup, Story 2 = Core implementation, Story 3 = Integration and testing
+- Typical points: 2-3 points per story
+
+**Never exceed 3 stories for Level 1:**
+
+- If more needed, consider if project should be Level 2
+- Better to have longer stories (5 points) than more stories (5x 1-point stories)
+  </guidelines>
+
+<action>Determine story_count = 2 or 3 based on tech spec complexity</action>
+
+</step>
+
+<step n="4" goal="Generate user stories from tech spec tasks">
+
+<action>For each story (2-3 total), generate separate story file</action>
+<action>Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3</action>
+
+<guidelines>
+**Story Generation Guidelines:**
+- Each story = multiple implementation tasks from tech spec
+- Story title format: User-focused deliverable (not implementation steps)
+- Include technical acceptance criteria from tech spec tasks
+- Link back to tech spec sections for implementation details
+
+**CRITICAL: Acceptance Criteria Must Be:**
+
+1. **Numbered** - AC #1, AC #2, AC #3, etc.
+2. **Specific** - No vague statements like "works well" or "is fast"
+3. **Testable** - Can be verified objectively
+4. **Complete** - Covers all success conditions
+5. **Independent** - Each AC tests one thing
+6. **Format**: Use Given/When/Then when applicable
+
+**Good AC Examples:**
+✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
+✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
+✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
+
+**Bad AC Examples:**
+❌ "User can create account" (too vague)
+❌ "System performs well" (not measurable)
+❌ "Works correctly" (not specific)
+
+**Story Point Estimation:**
+
+- 1 point = < 1 day (2-4 hours)
+- 2 points = 1-2 days
+- 3 points = 2-3 days
+- 5 points = 3-5 days
+
+**Level 1 Typical Totals:**
+
+- Total story points: 5-10 points
+- 2 stories: 3-5 points each
+- 3 stories: 2-3 points each
+- If total > 15 points, consider if this should be Level 2
+
+**Story Structure (MUST match create-story format):**
+
+- Status: Draft
+- Story: As a [role], I want [capability], so that [benefit]
+- Acceptance Criteria: Numbered list from tech spec
+- Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
+- Dev Notes: Technical summary, project structure notes, references
+- Dev Agent Record: Empty sections (tech-spec provides context)
+
+**NEW: Comprehensive Context Fields**
+
+Since tech-spec is context-rich, populate ALL template fields:
+
+- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
+  </guidelines>
+
+<for-each story="1 to story_count">
+  <action>Set story_path_{n} = "{dev_ephemeral_location}/story-{epic_slug}-{n}.md"</action>
+  <action>Create story file from user_story_template with the following content:</action>
+
+  <template-output file="{story_path_{n}}">
+    - story_title: User-focused deliverable title
+    - role: User role (e.g., developer, user, admin)
+    - capability: What they want to do
+    - benefit: Why it matters
+    - acceptance_criteria: Specific, measurable criteria from tech spec
+    - tasks_subtasks: Implementation tasks with AC references
+    - technical_summary: High-level approach, key decisions
+    - files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
+    - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
+    - story_points: Estimated effort (1/2/3/5)
+    - time_estimate: Days/hours estimate
+    - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
+    - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
+    - architecture_references: Links to tech-spec.md sections
+  </template-output>
+</for-each>
+
+<critical>Generate exactly {story_count} story files (2 or 3 based on Step 3 decision)</critical>
+
+</step>
+
+<step n="5" goal="Create story map and implementation sequence with dependency validation">
+
+<critical>Stories MUST be ordered so earlier stories don't depend on later ones</critical>
+<critical>Each story must have CLEAR, TESTABLE acceptance criteria</critical>
+
+<action>Analyze dependencies between stories:
+
+**Dependency Rules:**
+
+1. Infrastructure/setup → Feature implementation → Testing/polish
+2. Database changes → API changes → UI changes
+3. Backend services → Frontend components
+4. Core functionality → Enhancement features
+5. No story can depend on a later story!
+
+**Validate Story Sequence:**
+For each story N, check:
+
+- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
+- Does it only use things from Story 1...N-1? ✅ VALID
+- Can it be implemented independently or using only prior stories? ✅ VALID
+
+If invalid dependencies found, REORDER stories!
+</action>
+
+<action>Generate visual story map showing epic → stories hierarchy with dependencies</action>
+<action>Calculate total story points across all stories</action>
+<action>Estimate timeline based on total points (1-2 points per day typical)</action>
+<action>Define implementation sequence with explicit dependency notes</action>
+
+<example>
+## Story Map
+
+```
+Epic: Icon Reliability
+├── Story 1: Build Icon Infrastructure (3 points)
+│   Dependencies: None (foundational work)
+│
+└── Story 2: Test and Deploy Icons (2 points)
+    Dependencies: Story 1 (requires infrastructure)
+```
+
+**Total Story Points:** 5
+**Estimated Timeline:** 1 sprint (1 week)
+
+## Implementation Sequence
+
+1. **Story 1** → Build icon infrastructure (setup, download, configure)
+   - Dependencies: None
+   - Deliverable: Icon files downloaded, organized, accessible
+
+2. **Story 2** → Test and deploy (depends on Story 1)
+   - Dependencies: Story 1 must be complete
+   - Deliverable: Icons verified, tested, deployed to production
+
+**Dependency Validation:** ✅ Valid sequence - no forward dependencies
+</example>
+
+<template-output file="{output_folder}/epics.md">story_summaries</template-output>
+<template-output file="{output_folder}/epics.md">story_map</template-output>
+<template-output file="{output_folder}/epics.md">total_points</template-output>
+<template-output file="{output_folder}/epics.md">estimated_timeline</template-output>
+<template-output file="{output_folder}/epics.md">implementation_sequence</template-output>
+
+</step>
+
+<step n="6" goal="Update status and populate story backlog">
+
+<invoke-workflow path="{project-root}/.bmad/bmm/workflows/workflow-status">
+  <param>mode: update</param>
+  <param>action: complete_workflow</param>
+  <param>workflow_name: tech-spec</param>
+  <param>populate_stories_from: {epics_output_file}</param>
+</invoke-workflow>
+
+<check if="success == true">
+  <output>✅ Status updated! Loaded {{total_stories}} stories from epics.</output>
+  <output>Next: {{next_workflow}} ({{next_agent}} agent)</output>
+</check>
+
+<check if="success == false">
+  <output>⚠️ Status update failed: {{error}}</output>
+</check>
+
+</step>
+
+<step n="7" goal="Auto-validate story quality and sequence">
+
+<critical>Auto-run validation - NOT optional!</critical>
+
+<action>Running automatic story validation...</action>
+
+<action>**Validate Story Sequence (CRITICAL):**
+
+For each story, check:
+
+1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
+2. Are dependencies clearly documented? ✅ PASS
+3. Can stories be implemented in order 1→2→3? ✅ PASS
+
+If sequence validation FAILS:
+
+- Identify the problem dependencies
+- Propose new ordering
+- Ask user to confirm reordering
+  </action>
+
+<action>**Validate Acceptance Criteria Quality:**
+
+For each story's AC, check:
+
+1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
+2. Is it specific and testable? ✅ Required
+3. Does it use Given/When/Then or equivalent? ✅ Recommended
+4. Are all success conditions covered? ✅ Required
+
+Count vague AC (contains "works", "good", "fast", "well"):
+
+- 0 vague AC: ✅ EXCELLENT
+- 1-2 vague AC: ⚠️ WARNING - Should improve
+- 3+ vague AC: ❌ FAIL - Must improve
+  </action>
+
+<action>**Validate Story Completeness:**
+
+1. Do all stories map to tech spec tasks? ✅ Required
+2. Do story points align with tech spec estimates? ✅ Recommended
+3. Are dependencies clearly noted? ✅ Required
+4. Does each story have testable AC? ✅ Required
+   </action>
+
+<action>Generate validation report</action>
+
+<check if="sequence validation fails OR AC quality fails">
+  <output>❌ **Story Validation Failed:**
+
+{{issues_found}}
+
+**Recommended Fixes:**
+{{recommended_fixes}}
+
+Shall I fix these issues? (yes/no)</output>
+
+<ask>Apply fixes? (yes/no)</ask>
+
+  <check if="yes">
+    <action>Apply fixes (reorder stories, rewrite vague AC, add missing details)</action>
+    <action>Re-validate</action>
+    <output>✅ Validation passed after fixes!</output>
+  </check>
+</check>
+
+<check if="validation passes">
+  <output>✅ **Story Validation Passed!**
+
+**Sequence:** ✅ Valid (no forward dependencies)
+**AC Quality:** ✅ All specific and testable
+**Completeness:** ✅ All tech spec tasks covered
+**Dependencies:** ✅ Clearly documented
+
+Stories are implementation-ready!</output>
+</check>
+
+</step>
+
+<step n="8" goal="Finalize and provide user guidance">
+
+<action>Confirm all validation passed</action>
+<action>Verify total story points align with tech spec time estimates</action>
+<action>Confirm epic and stories are complete</action>
+
+**Level 1 Planning Complete!**
+
+**Epic:** {{epic_title}}
+**Total Stories:** {{story_count}}
+**Total Story Points:** {{total_points}}
+**Estimated Timeline:** {{estimated_timeline}}
+
+**Generated Artifacts:**
+
+- `tech-spec.md` → Technical source of truth
+- `epics.md` → Epic and story summary
+- `story-{epic_slug}-1.md` → First story (ready for implementation)
+- `story-{epic_slug}-2.md` → Second story
+  {{#if story_3}}
+- `story-{epic_slug}-3.md` → Third story
+  {{/if}}
+
+**Story Location:** `{dev_ephemeral_location}/`
+
+**Next Steps - Iterative Implementation:**
+
+**🎯 RECOMMENDED - Direct to Development (Level 1):**
+
+Since the tech-spec is now CONTEXT-RICH with:
+
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+- ✅ Dependencies clearly mapped
+
+**You can skip story-context for most Level 1 stories!**
+
+**1. Start with Story 1:**
+a. Load DEV agent: `{project-root}/.bmad/bmm/agents/dev.md`
+b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
+c. Tech-spec provides all context needed
+d. Implement story 1
+
+**2. After Story 1 Complete:**
+
+- Repeat for story-{epic_slug}-2.md
+- Reference completed story 1 in your work
+
+**3. After Story 2 Complete:**
+{{#if story_3}}
+
+- Repeat for story-{epic_slug}-3.md
+  {{/if}}
+- Level 1 feature complete!
+
+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex multi-story dependencies:
+
+1. Load SM agent: `{project-root}/.bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow for complex stories
+3. Then load DEV agent and run `dev-story`
+
+**Progress Tracking:**
+
+- All decisions logged in: `bmm-workflow-status.yaml`
+- Next action clearly identified
+
+<ask>Ready to proceed? Choose your path:
+
+1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context first (for complex dependencies)
+3. Exit for now
+
+Select option (1-3):</ask>
+
+</step>
+
+</workflow>

.bmad/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md

@@ -0,0 +1,181 @@
+# {{project_name}} - Technical Specification
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+**Project Level:** {{project_level}}
+**Change Type:** {{change_type}}
+**Development Context:** {{development_context}}
+
+---
+
+## Context
+
+### 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}}
+
+---
+
+## 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
+
+{{implementation_stack}}
+
+---
+
+## Technical Details
+
+{{technical_details}}
+
+---
+
+## Development Setup
+
+{{development_setup}}
+
+---
+
+## 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}}
+
+---
+
+## Testing Approach
+
+{{testing_approach}}
+
+---
+
+## Deployment Strategy
+
+### Deployment Steps
+
+{{deployment_steps}}
+
+### Rollback Plan
+
+{{rollback_plan}}
+
+### Monitoring
+
+{{monitoring_approach}}

.bmad/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md

@@ -0,0 +1,90 @@
+# Story {{N}}.{{M}}: {{story_title}}
+
+**Status:** Draft
+
+---
+
+## User Story
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+---
+
+## Acceptance Criteria
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+
+**And** {{additional_criteria}}
+
+---
+
+## Implementation Details
+
+### Tasks / Subtasks
+
+{{tasks_subtasks}}
+
+### Technical Summary
+
+{{technical_summary}}
+
+### Project Structure Notes
+
+- **Files to modify:** {{files_to_modify}}
+- **Expected test locations:** {{test_locations}}
+- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
+- **Prerequisites:** {{dependencies}}
+
+### Key Code References
+
+{{existing_code_references}}
+
+---
+
+## Context References
+
+**Tech-Spec:** [tech-spec.md](../tech-spec.md) - Primary context document containing:
+
+- Brownfield codebase analysis (if applicable)
+- Framework and library details with versions
+- Existing patterns to follow
+- Integration points and dependencies
+- Complete implementation guidance
+
+**Architecture:** {{architecture_references}}
+
+<!-- Additional context XML paths will be added here if story-context workflow is run -->
+
+---
+
+## Dev Agent Record
+
+### Agent Model Used
+
+<!-- Will be populated during dev-story execution -->
+
+### Debug Log References
+
+<!-- Will be populated during dev-story execution -->
+
+### Completion Notes
+
+<!-- Will be populated during dev-story execution -->
+
+### Files Modified
+
+<!-- Will be populated during dev-story execution -->
+
+### Test Results
+
+<!-- Will be populated during dev-story execution -->
+
+---
+
+## Review Notes
+
+<!-- Will be populated during code review -->

.bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml

@@ -0,0 +1,60 @@
+# Technical Specification
+name: tech-spec
+description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+project_name: "{config_source}:project_name"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+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"
+template: "{installed_path}/tech-spec-template.md"
+
+# Story generation instructions (invoked based on level)
+instructions_level0_story: "{installed_path}/instructions-level0-story.md"
+instructions_level1_stories: "{installed_path}/instructions-level1-stories.md"
+
+# Templates
+user_story_template: "{installed_path}/user-story-template.md"
+epics_template: "{installed_path}/epics-template.md"
+
+# Output configuration
+default_output_file: "{output_folder}/tech-spec.md"
+user_story_file: "{output_folder}/user-story.md"
+epics_file: "{output_folder}/epics.md"
+
+# Recommended input documents (optional for Level 0)
+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

.bmad/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml

@@ -0,0 +1,347 @@
+# Architecture Patterns - Common patterns identified from requirements
+
+requirement_patterns:
+  realtime_collaboration:
+    triggers:
+      - "real-time"
+      - "collaborative"
+      - "live updates"
+      - "multi-user"
+      - "simultaneous editing"
+    decisions_needed:
+      - websocket_solution
+      - conflict_resolution
+      - state_synchronization
+      - presence_tracking
+      - optimistic_updates
+    suggested_stack:
+      - "Socket.io or WebSocket native"
+      - "Redis for pub/sub"
+      - "Operational Transforms or CRDTs for conflict resolution"
+      - "PostgreSQL for persistence"
+
+  ecommerce:
+    triggers:
+      - "shopping cart"
+      - "checkout"
+      - "payments"
+      - "inventory"
+      - "product catalog"
+    decisions_needed:
+      - payment_processor
+      - cart_persistence
+      - inventory_management
+      - order_workflow
+      - tax_calculation
+    suggested_stack:
+      - "Stripe or PayPal for payments"
+      - "PostgreSQL for products and orders"
+      - "Redis for cart sessions"
+      - "BullMQ for order processing"
+
+  saas_platform:
+    triggers:
+      - "multi-tenant"
+      - "subscription"
+      - "billing"
+      - "team management"
+      - "roles and permissions"
+    decisions_needed:
+      - tenancy_model
+      - subscription_billing
+      - permission_system
+      - team_collaboration
+      - usage_tracking
+    suggested_stack:
+      - "PostgreSQL with Row Level Security"
+      - "Stripe Billing for subscriptions"
+      - "RBAC or ABAC for permissions"
+      - "NextAuth or Clerk for auth"
+
+  content_platform:
+    triggers:
+      - "CMS"
+      - "blog"
+      - "publishing"
+      - "content management"
+      - "editorial workflow"
+    decisions_needed:
+      - content_storage
+      - rich_text_editor
+      - media_handling
+      - version_control
+      - publishing_workflow
+    suggested_stack:
+      - "PostgreSQL for structured content"
+      - "S3 or Cloudinary for media"
+      - "Tiptap or Slate for rich text"
+      - "Algolia for search"
+
+  data_analytics:
+    triggers:
+      - "dashboards"
+      - "reporting"
+      - "metrics"
+      - "analytics"
+      - "data visualization"
+    decisions_needed:
+      - data_warehouse
+      - etl_pipeline
+      - visualization_library
+      - query_optimization
+      - caching_strategy
+    suggested_stack:
+      - "PostgreSQL or ClickHouse"
+      - "Apache Airflow or Temporal for ETL"
+      - "Chart.js or D3 for visualization"
+      - "Redis for query caching"
+
+  social_platform:
+    triggers:
+      - "social network"
+      - "feed"
+      - "following"
+      - "likes"
+      - "comments"
+    decisions_needed:
+      - graph_relationships
+      - feed_algorithm
+      - notification_system
+      - content_moderation
+      - privacy_controls
+    suggested_stack:
+      - "PostgreSQL with graph extensions or Neo4j"
+      - "Redis for feed caching"
+      - "Elasticsearch for user search"
+      - "WebSockets for notifications"
+
+  marketplace:
+    triggers:
+      - "marketplace"
+      - "vendors"
+      - "buyers and sellers"
+      - "transactions"
+      - "escrow"
+    decisions_needed:
+      - payment_splitting
+      - escrow_handling
+      - vendor_management
+      - dispute_resolution
+      - commission_model
+    suggested_stack:
+      - "Stripe Connect for payments"
+      - "PostgreSQL for transactions"
+      - "BullMQ for async processing"
+      - "S3 for vendor assets"
+
+  streaming_platform:
+    triggers:
+      - "video streaming"
+      - "live streaming"
+      - "media delivery"
+      - "broadcast"
+    decisions_needed:
+      - video_encoding
+      - cdn_strategy
+      - streaming_protocol
+      - bandwidth_optimization
+      - drm_protection
+    suggested_stack:
+      - "AWS MediaConvert or Mux"
+      - "CloudFront or Fastly CDN"
+      - "HLS or DASH protocol"
+      - "S3 for video storage"
+
+  iot_platform:
+    triggers:
+      - "IoT"
+      - "sensors"
+      - "device management"
+      - "telemetry"
+      - "edge computing"
+    decisions_needed:
+      - message_protocol
+      - time_series_database
+      - device_authentication
+      - data_ingestion
+      - edge_processing
+    suggested_stack:
+      - "MQTT or CoAP protocol"
+      - "TimescaleDB or InfluxDB"
+      - "Apache Kafka for ingestion"
+      - "Grafana for monitoring"
+
+  ai_application:
+    triggers:
+      - "machine learning"
+      - "AI features"
+      - "LLM integration"
+      - "computer vision"
+      - "NLP"
+    decisions_needed:
+      - model_serving
+      - vector_database
+      - prompt_management
+      - token_optimization
+      - fallback_strategy
+    suggested_stack:
+      - "OpenAI or Anthropic API"
+      - "Pinecone or pgvector for embeddings"
+      - "Redis for prompt caching"
+      - "Langchain or LlamaIndex"
+
+# Quality attribute patterns
+quality_attributes:
+  high_availability:
+    triggers:
+      - "99.9% uptime"
+      - "high availability"
+      - "fault tolerance"
+      - "disaster recovery"
+    architectural_needs:
+      - load_balancing
+      - database_replication
+      - health_checks
+      - circuit_breakers
+      - graceful_degradation
+
+  high_performance:
+    triggers:
+      - "millisecond response"
+      - "high throughput"
+      - "low latency"
+      - "performance critical"
+    architectural_needs:
+      - caching_layers
+      - database_optimization
+      - cdn_strategy
+      - code_splitting
+      - lazy_loading
+
+  high_security:
+    triggers:
+      - "compliance"
+      - "HIPAA"
+      - "GDPR"
+      - "financial data"
+      - "PCI DSS"
+    architectural_needs:
+      - encryption_at_rest
+      - encryption_in_transit
+      - audit_logging
+      - access_controls
+      - data_isolation
+
+  scalability:
+    triggers:
+      - "millions of users"
+      - "elastic scale"
+      - "global reach"
+      - "viral growth"
+    architectural_needs:
+      - horizontal_scaling
+      - database_sharding
+      - microservices
+      - queue_systems
+      - auto_scaling
+
+# Integration patterns
+integration_requirements:
+  payment_processing:
+    common_choices:
+      - "Stripe - most developer friendly"
+      - "PayPal - widest consumer adoption"
+      - "Square - best for in-person + online"
+    considerations:
+      - transaction_fees
+      - international_support
+      - subscription_handling
+      - marketplace_capabilities
+
+  email_service:
+    common_choices:
+      - "Resend - modern, developer friendly"
+      - "SendGrid - mature, scalable"
+      - "Amazon SES - cost effective at scale"
+      - "Postmark - transactional focus"
+    considerations:
+      - deliverability
+      - template_management
+      - analytics_needs
+      - cost_per_email
+
+  sms_notifications:
+    common_choices:
+      - "Twilio - most comprehensive"
+      - "Amazon SNS - AWS integrated"
+      - "Vonage - competitive pricing"
+    considerations:
+      - international_coverage
+      - delivery_rates
+      - two_way_messaging
+      - cost_per_message
+
+  authentication_providers:
+    social_providers:
+      - "Google - highest adoption"
+      - "GitHub - developer focused"
+      - "Microsoft - enterprise"
+      - "Apple - iOS users"
+    enterprise_providers:
+      - "SAML 2.0"
+      - "OAuth 2.0"
+      - "OpenID Connect"
+      - "Active Directory"
+
+# Decision heuristics
+decision_rules:
+  database_selection:
+    if_requirements_include:
+      - complex_relationships: "PostgreSQL"
+      - flexible_schema: "MongoDB"
+      - time_series: "TimescaleDB"
+      - graph_data: "Neo4j or PostgreSQL with extensions"
+      - key_value: "Redis"
+      - wide_column: "Cassandra"
+
+  api_pattern_selection:
+    if_requirements_include:
+      - simple_crud: "REST"
+      - complex_queries: "GraphQL"
+      - type_safety_critical: "tRPC"
+      - microservices: "gRPC"
+      - public_api: "REST with OpenAPI"
+
+  deployment_selection:
+    if_requirements_include:
+      - nextjs_only: "Vercel"
+      - complex_infrastructure: "AWS"
+      - quick_prototype: "Railway"
+      - global_edge: "Fly.io"
+      - kubernetes_needed: "GCP or AWS EKS"
+
+# Anti-patterns to avoid
+anti_patterns:
+  overengineering:
+    signs:
+      - "Microservices for < 10k users"
+      - "Kubernetes for single app"
+      - "GraphQL for 5 endpoints"
+      - "Event sourcing for CRUD app"
+    recommendation: "Start simple, evolve as needed"
+
+  underengineering:
+    signs:
+      - "No authentication strategy"
+      - "No error handling plan"
+      - "No monitoring approach"
+      - "No backup strategy"
+    recommendation: "Cover the fundamentals"
+
+  technology_soup:
+    signs:
+      - "5+ different databases"
+      - "Multiple frontend frameworks"
+      - "Inconsistent patterns"
+      - "Too many languages"
+    recommendation: "Maintain consistency"

.bmad/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -0,0 +1,103 @@
+# Architecture
+
+## Executive Summary
+
+{{executive_summary}}
+
+{{project_initialization_section}}
+
+## Decision Summary
+
+| Category | Decision | Version | Affects Epics | Rationale |
+| -------- | -------- | ------- | ------------- | --------- |
+
+{{decision_table_rows}}
+
+## Project Structure
+
+```
+{{project_root}}/
+{{source_tree}}
+```
+
+## Epic to Architecture Mapping
+
+{{epic_mapping_table}}
+
+## Technology Stack Details
+
+### Core Technologies
+
+{{core_stack_details}}
+
+### Integration Points
+
+{{integration_details}}
+
+{{novel_pattern_designs_section}}
+
+## Implementation Patterns
+
+These patterns ensure consistent implementation across all AI agents:
+
+{{implementation_patterns}}
+
+## Consistency Rules
+
+### Naming Conventions
+
+{{naming_conventions}}
+
+### Code Organization
+
+{{code_organization_patterns}}
+
+### Error Handling
+
+{{error_handling_approach}}
+
+### Logging Strategy
+
+{{logging_approach}}
+
+## Data Architecture
+
+{{data_models_and_relationships}}
+
+## API Contracts
+
+{{api_specifications}}
+
+## Security Architecture
+
+{{security_approach}}
+
+## Performance Considerations
+
+{{performance_strategies}}
+
+## Deployment Architecture
+
+{{deployment_approach}}
+
+## Development Environment
+
+### Prerequisites
+
+{{development_prerequisites}}
+
+### Setup Commands
+
+```bash
+{{setup_commands}}
+```
+
+## Architecture Decision Records (ADRs)
+
+{{key_architecture_decisions}}
+
+---
+
+_Generated by BMAD Decision Architecture Workflow v1.0_
+_Date: {{date}}_
+_For: {{user_name}}_

.bmad/bmm/workflows/3-solutioning/architecture/checklist.md

@@ -0,0 +1,244 @@
+# Architecture Document Validation Checklist
+
+**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
+
+**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
+
+---
+
+## 1. Decision Completeness
+
+### All Decisions Made
+
+- [ ] Every critical decision category has been resolved
+- [ ] All important decision categories addressed
+- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
+- [ ] Optional decisions either resolved or explicitly deferred with rationale
+
+### Decision Coverage
+
+- [ ] Data persistence approach decided
+- [ ] API pattern chosen
+- [ ] Authentication/authorization strategy defined
+- [ ] Deployment target selected
+- [ ] All functional requirements have architectural support
+
+---
+
+## 2. Version Specificity
+
+### Technology Versions
+
+- [ ] Every technology choice includes a specific version number
+- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
+- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
+- [ ] Verification dates noted for version checks
+
+### Version Verification Process
+
+- [ ] WebSearch used during workflow to verify current versions
+- [ ] No hardcoded versions from decision catalog trusted without verification
+- [ ] LTS vs. latest versions considered and documented
+- [ ] Breaking changes between versions noted if relevant
+
+---
+
+## 3. Starter Template Integration (if applicable)
+
+### Template Selection
+
+- [ ] Starter template chosen (or "from scratch" decision documented)
+- [ ] Project initialization command documented with exact flags
+- [ ] Starter template version is current and specified
+- [ ] Command search term provided for verification
+
+### Starter-Provided Decisions
+
+- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
+- [ ] List of what starter provides is complete
+- [ ] Remaining decisions (not covered by starter) clearly identified
+- [ ] No duplicate decisions that starter already makes
+
+---
+
+## 4. Novel Pattern Design (if applicable)
+
+### Pattern Detection
+
+- [ ] All unique/novel concepts from PRD identified
+- [ ] Patterns that don't have standard solutions documented
+- [ ] Multi-epic workflows requiring custom design captured
+
+### Pattern Documentation Quality
+
+- [ ] Pattern name and purpose clearly defined
+- [ ] Component interactions specified
+- [ ] Data flow documented (with sequence diagrams if complex)
+- [ ] Implementation guide provided for agents
+- [ ] Edge cases and failure modes considered
+- [ ] States and transitions clearly defined
+
+### Pattern Implementability
+
+- [ ] Pattern is implementable by AI agents with provided guidance
+- [ ] No ambiguous decisions that could be interpreted differently
+- [ ] Clear boundaries between components
+- [ ] Explicit integration points with standard patterns
+
+---
+
+## 5. Implementation Patterns
+
+### Pattern Categories Coverage
+
+- [ ] **Naming Patterns**: API routes, database tables, components, files
+- [ ] **Structure Patterns**: Test organization, component organization, shared utilities
+- [ ] **Format Patterns**: API responses, error formats, date handling
+- [ ] **Communication Patterns**: Events, state updates, inter-component messaging
+- [ ] **Lifecycle Patterns**: Loading states, error recovery, retry logic
+- [ ] **Location Patterns**: URL structure, asset organization, config placement
+- [ ] **Consistency Patterns**: UI date formats, logging, user-facing errors
+
+### Pattern Quality
+
+- [ ] Each pattern has concrete examples
+- [ ] Conventions are unambiguous (agents can't interpret differently)
+- [ ] Patterns cover all technologies in the stack
+- [ ] No gaps where agents would have to guess
+- [ ] Implementation patterns don't conflict with each other
+
+---
+
+## 6. Technology Compatibility
+
+### Stack Coherence
+
+- [ ] Database choice compatible with ORM choice
+- [ ] Frontend framework compatible with deployment target
+- [ ] Authentication solution works with chosen frontend/backend
+- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
+- [ ] Starter template compatible with additional choices
+
+### Integration Compatibility
+
+- [ ] Third-party services compatible with chosen stack
+- [ ] Real-time solutions (if any) work with deployment target
+- [ ] File storage solution integrates with framework
+- [ ] Background job system compatible with infrastructure
+
+---
+
+## 7. Document Structure
+
+### Required Sections Present
+
+- [ ] Executive summary exists (2-3 sentences maximum)
+- [ ] Project initialization section (if using starter template)
+- [ ] Decision summary table with ALL required columns:
+  - Category
+  - Decision
+  - Version
+  - Rationale
+- [ ] Project structure section shows complete source tree
+- [ ] Implementation patterns section comprehensive
+- [ ] Novel patterns section (if applicable)
+
+### Document Quality
+
+- [ ] Source tree reflects actual technology decisions (not generic)
+- [ ] Technical language used consistently
+- [ ] Tables used instead of prose where appropriate
+- [ ] No unnecessary explanations or justifications
+- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
+
+---
+
+## 8. AI Agent Clarity
+
+### Clear Guidance for Agents
+
+- [ ] No ambiguous decisions that agents could interpret differently
+- [ ] Clear boundaries between components/modules
+- [ ] Explicit file organization patterns
+- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
+- [ ] Novel patterns have clear implementation guidance
+- [ ] Document provides clear constraints for agents
+- [ ] No conflicting guidance present
+
+### Implementation Readiness
+
+- [ ] Sufficient detail for agents to implement without guessing
+- [ ] File paths and naming conventions explicit
+- [ ] Integration points clearly defined
+- [ ] Error handling patterns specified
+- [ ] Testing patterns documented
+
+---
+
+## 9. Practical Considerations
+
+### Technology Viability
+
+- [ ] Chosen stack has good documentation and community support
+- [ ] Development environment can be set up with specified versions
+- [ ] No experimental or alpha technologies for critical path
+- [ ] Deployment target supports all chosen technologies
+- [ ] Starter template (if used) is stable and well-maintained
+
+### Scalability
+
+- [ ] Architecture can handle expected user load
+- [ ] Data model supports expected growth
+- [ ] Caching strategy defined if performance is critical
+- [ ] Background job processing defined if async work needed
+- [ ] Novel patterns scalable for production use
+
+---
+
+## 10. Common Issues to Check
+
+### Beginner Protection
+
+- [ ] Not overengineered for actual requirements
+- [ ] Standard patterns used where possible (starter templates leveraged)
+- [ ] Complex technologies justified by specific needs
+- [ ] Maintenance complexity appropriate for team size
+
+### Expert Validation
+
+- [ ] No obvious anti-patterns present
+- [ ] Performance bottlenecks addressed
+- [ ] Security best practices followed
+- [ ] Future migration paths not blocked
+- [ ] Novel patterns follow architectural principles
+
+---
+
+## Validation Summary
+
+### Document Quality Score
+
+- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
+- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
+- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
+- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
+
+### Critical Issues Found
+
+- [ ] Issue 1: **\*\***\_\_\_**\*\***
+- [ ] Issue 2: **\*\***\_\_\_**\*\***
+- [ ] Issue 3: **\*\***\_\_\_**\*\***
+
+### Recommended Actions Before Implementation
+
+1. ***
+2. ***
+3. ***
+
+---
+
+**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
+
+---
+
+_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._

.bmad/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml

@@ -0,0 +1,222 @@
+# Decision Catalog - Composability knowledge for architectural decisions
+# This provides RELATIONSHIPS and WORKFLOW LOGIC, not generic tech knowledge
+#
+# ⚠️ CRITICAL: All version/feature info MUST be verified via WebSearch during workflow
+# This file only provides: triggers, relationships (pairs_with), and opinionated stacks
+
+decision_categories:
+  data_persistence:
+    triggers: ["database", "storage", "data model", "persistence", "state management"]
+    importance: "critical"
+    affects: "most epics"
+    options:
+      postgresql:
+        pairs_with: ["Prisma ORM", "TypeORM", "Drizzle", "node-postgres"]
+      mongodb:
+        pairs_with: ["Mongoose", "Prisma", "MongoDB driver"]
+      redis:
+        pairs_with: ["ioredis", "node-redis"]
+      supabase:
+        pairs_with: ["@supabase/supabase-js"]
+      firebase:
+        pairs_with: ["firebase-admin"]
+
+  api_pattern:
+    triggers: ["API", "client communication", "frontend backend", "service communication"]
+    importance: "critical"
+    affects: "all client-facing epics"
+    options:
+      rest:
+        pairs_with: ["Express", "Fastify", "NestJS", "Hono"]
+      graphql:
+        pairs_with: ["Apollo Server", "GraphQL Yoga", "Mercurius"]
+      trpc:
+        pairs_with: ["Next.js", "React Query"]
+      grpc:
+        pairs_with: ["@grpc/grpc-js", "protobufjs"]
+
+  authentication:
+    triggers: ["auth", "login", "user management", "security", "identity"]
+    importance: "critical"
+    affects: "security and user epics"
+    options:
+      nextauth:
+        pairs_with: ["Next.js", "Prisma"]
+      auth0:
+        pairs_with: ["@auth0/nextjs-auth0"]
+      clerk:
+        pairs_with: ["@clerk/nextjs"]
+      supabase_auth:
+        pairs_with: ["@supabase/supabase-js"]
+      firebase_auth:
+        pairs_with: ["firebase-admin"]
+
+  real_time:
+    triggers: ["real-time", "websocket", "live updates", "chat", "collaboration"]
+    importance: "medium"
+    affects: "real-time features"
+    options:
+      socket_io:
+        pairs_with: ["Express", "socket.io-client"]
+      pusher:
+        pairs_with: ["pusher-js"]
+      ably:
+        pairs_with: ["ably"]
+      supabase_realtime:
+        pairs_with: ["@supabase/supabase-js"]
+      firebase_realtime:
+        pairs_with: ["firebase"]
+
+  email:
+    triggers: ["email", "notifications", "transactional email"]
+    importance: "medium"
+    affects: "notification epics"
+    options:
+      resend:
+        pairs_with: ["resend", "react-email"]
+      sendgrid:
+        pairs_with: ["@sendgrid/mail"]
+      postmark:
+        pairs_with: ["postmark"]
+      ses:
+        pairs_with: ["@aws-sdk/client-ses"]
+
+  file_storage:
+    triggers: ["upload", "file storage", "images", "media", "CDN"]
+    importance: "medium"
+    affects: "media handling epics"
+    options:
+      s3:
+        pairs_with: ["@aws-sdk/client-s3", "multer"]
+      cloudinary:
+        pairs_with: ["cloudinary"]
+      uploadthing:
+        pairs_with: ["uploadthing"]
+      supabase_storage:
+        pairs_with: ["@supabase/supabase-js"]
+
+  search:
+    triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
+    importance: "medium"
+    affects: "search and discovery epics"
+    options:
+      postgres_fts:
+        pairs_with: ["PostgreSQL"]
+      elasticsearch:
+        pairs_with: ["@elastic/elasticsearch"]
+      algolia:
+        pairs_with: ["algoliasearch"]
+      typesense:
+        pairs_with: ["typesense"]
+
+  background_jobs:
+    triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
+    importance: "medium"
+    affects: "async processing epics"
+    options:
+      bullmq:
+        pairs_with: ["Redis"]
+      sqs:
+        pairs_with: ["@aws-sdk/client-sqs"]
+      temporal:
+        pairs_with: ["@temporalio/client"]
+      inngest:
+        pairs_with: ["inngest"]
+
+  deployment_target:
+    triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
+    importance: "high"
+    affects: "all epics"
+    options:
+      vercel:
+        pairs_with: ["Next.js", "serverless functions"]
+      aws:
+        pairs_with: ["any stack"]
+      railway:
+        pairs_with: ["any stack", "managed databases"]
+      fly_io:
+        pairs_with: ["Docker containers"]
+
+# Opinionated stack combinations (BMM methodology)
+common_stacks:
+  modern_fullstack:
+    name: "Modern Full-Stack"
+    components: ["Next.js", "PostgreSQL or Supabase", "Prisma ORM", "NextAuth.js", "Tailwind CSS", "TypeScript", "Vercel"]
+    good_for: "Most web applications"
+
+  enterprise_stack:
+    name: "Enterprise Stack"
+    components: ["NestJS", "PostgreSQL", "TypeORM", "Auth0", "Redis", "Docker", "AWS"]
+    good_for: "Large-scale enterprise applications"
+
+  rapid_prototype:
+    name: "Rapid Prototype"
+    components: ["Next.js", "Supabase", "shadcn/ui", "Vercel"]
+    good_for: "MVP and rapid development"
+
+  real_time_app:
+    name: "Real-Time Application"
+    components: ["Next.js", "Supabase Realtime", "PostgreSQL", "Prisma", "Socket.io fallback"]
+    good_for: "Chat, collaboration, live updates"
+
+  mobile_app:
+    name: "Mobile Application"
+    components: ["Expo", "React Native", "Supabase or Firebase", "React Query"]
+    good_for: "Cross-platform mobile apps"
+
+# Starter templates and what decisions they make
+starter_templates:
+  create_next_app:
+    name: "Create Next App"
+    command_search: "npx create-next-app@latest"
+    decisions_provided: ["Next.js framework", "TypeScript option", "App Router vs Pages", "Tailwind CSS option", "ESLint"]
+    good_for: ["React web applications", "Full-stack apps", "SSR/SSG"]
+
+  create_t3_app:
+    name: "Create T3 App"
+    command_search: "npm create t3-app@latest"
+    decisions_provided: ["Next.js", "TypeScript", "tRPC", "Prisma", "NextAuth", "Tailwind CSS"]
+    good_for: ["Type-safe full-stack apps"]
+
+  create_vite:
+    name: "Create Vite"
+    command_search: "npm create vite@latest"
+    decisions_provided: ["Framework choice (React/Vue/Svelte)", "TypeScript option", "Vite bundler"]
+    good_for: ["Fast dev SPAs", "Library development"]
+
+  create_remix:
+    name: "Create Remix"
+    command_search: "npx create-remix@latest"
+    decisions_provided: ["Remix framework", "TypeScript option", "Deployment target", "CSS solution"]
+    good_for: ["Web standards", "Nested routing", "Progressive enhancement"]
+
+  nest_new:
+    name: "NestJS CLI"
+    command_search: "nest new project"
+    decisions_provided: ["TypeScript (always)", "Package manager", "Testing framework (Jest)", "Project structure"]
+    good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
+
+  create_expo_app:
+    name: "Create Expo App"
+    command_search: "npx create-expo-app"
+    decisions_provided: ["React Native", "Expo SDK", "TypeScript option", "Navigation option"]
+    good_for: ["Cross-platform mobile", "React Native apps"]
+
+# Starter selection heuristics (workflow logic)
+starter_selection_rules:
+  by_project_type:
+    web_application:
+      recommended: ["create_next_app", "create_t3_app", "create_vite"]
+      considerations: "SSR needs? → Next.js. Type safety critical? → T3. SPA only? → Vite"
+
+    mobile_app:
+      recommended: ["create_expo_app"]
+      considerations: "Cross-platform → Expo. Native-heavy → React Native CLI"
+
+    api_backend:
+      recommended: ["nest_new"]
+      considerations: "Enterprise → NestJS. Simple → Express starter. Performance → Fastify"
+
+    full_stack:
+      recommended: ["create_t3_app", "create_remix"]
+      considerations: "Type safety → T3. Web standards → Remix. Monolith → RedwoodJS"

.bmad/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -0,0 +1,704 @@
+# Decision Architecture Workflow Instructions
+
+<workflow name="architecture">
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
+<critical>The goal is ARCHITECTURAL DECISIONS that prevent AI agent conflicts, not detailed implementation specs</critical>
+<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>This workflow replaces architecture with a conversation-driven approach</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+<critical>ELICITATION POINTS: After completing each major architectural decision area (identified by template-output tags for decision_record, project_structure, novel_pattern_designs, implementation_patterns, and architecture_document), invoke advanced elicitation to refine decisions before proceeding</critical>
+
+<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 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**
+
+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 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="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>
+
+<action>Fuzzy match PRD file: {prd_file}</action>
+<check if="PRD_not_found">
+<output>**PRD Not Found**
+
+Decision Architecture works from your Product Requirements Document (PRD).
+
+Looking for: _PRD_, PRD.md, or prd/index.md + files in {output_folder}
+
+Please run the PRD workflow first to define your requirements.
+
+Architect: `create-prd`
+</output>
+<action>Exit workflow - PRD required</action>
+</check>
+
+</step>
+
+<step n="1" goal="Load and understand project context">
+  <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:
+<action>Attempt to locate: {ux_spec_file}</action>
+<check if="ux_spec_found">
+<action>Load UX spec and extract architectural implications: - 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)
+</action>
+</check>
+</action>
+
+<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) - Novel features
+</action>
+
+<action>Reflect understanding back to {user_name}:
+"I'm reviewing your project documentation for {{project_name}}.
+I see {{epic_count}} epics with {{story_count}} total stories.
+{{if_ux_spec}}I also found your UX specification which defines the user experience requirements.{{/if_ux_spec}}
+
+     Key aspects I notice:
+     - [Summarize core functionality]
+     - [Note critical NFRs]
+     {{if_ux_spec}}- [Note UX complexity and requirements]{{/if_ux_spec}}
+     - [Identify unique challenges]
+
+     This will help me guide you through the architectural decisions needed
+     to ensure AI agents implement this consistently."
+
+  </action>
+
+<ask>Does this match your understanding of the project?</ask>
+<template-output>project_context_understanding</template-output>
+</step>
+
+<step n="2" goal="Discover and evaluate starter templates">
+  <critical>Modern starter templates make many good architectural decisions by default</critical>
+
+<action>Based on PRD analysis, identify the primary technology domain: - Web application → Look for Next.js, Vite, Remix starters - Mobile app → Look for React Native, Expo, Flutter starters - API/Backend → Look for NestJS, Express, Fastify starters - CLI tool → Look for CLI framework starters - Full-stack → Look for T3, RedwoodJS, Blitz starters
+</action>
+
+  <check if="ux_spec_loaded">
+    <action>Consider UX requirements when selecting starter:
+      - Rich animations → Framer Motion compatible starter
+      - Complex forms → React Hook Form included starter
+      - Real-time features → Socket.io or WebSocket ready starter
+      - Accessibility focus → WCAG-compliant component library starter
+      - Design system → Storybook-enabled starter
+    </action>
+  </check>
+
+<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>
+
+  <check if="starter_templates_found">
+    <action>Investigate what each starter provides:
+      <WebSearch>{{starter_name}} default setup technologies included latest</WebSearch>
+      <WebSearch>{{starter_name}} project structure file organization</WebSearch>
+    </action>
+
+    <check if="{user_skill_level} == 'expert'">
+      <action>Present starter options concisely:
+        "Found {{starter_name}} which provides:
+         {{quick_decision_list}}
+
+         This would establish our base architecture. Use it?"
+      </action>
+    </check>
+
+    <check if="{user_skill_level} == 'beginner'">
+      <action>Explain starter benefits:
+        "I found {{starter_name}}, which is like a pre-built foundation for your project.
+
+         Think of it like buying a prefab house frame instead of cutting each board yourself.
+
+         It makes these decisions for you:
+         {{friendly_decision_list}}
+
+         This is a great starting point that follows best practices. Should we use it?"
+      </action>
+    </check>
+
+    <ask>Use {{starter_name}} as the foundation? (recommended) [y/n]</ask>
+
+    <check if="user_accepts_starter">
+      <action>Get current starter command and options:
+        <WebSearch>{{starter_name}} CLI command options flags latest 2024</WebSearch>
+      </action>
+
+      <action>Document the initialization command:
+        Store command: {{full_starter_command_with_options}}
+        Example: "npx create-next-app@latest my-app --typescript --tailwind --app"
+      </action>
+
+      <action>Extract and document starter-provided decisions:
+        Starter provides these architectural decisions:
+        - Language/TypeScript: {{provided_or_not}}
+        - Styling solution: {{provided_or_not}}
+        - Testing framework: {{provided_or_not}}
+        - Linting/Formatting: {{provided_or_not}}
+        - Build tooling: {{provided_or_not}}
+        - Project structure: {{provided_pattern}}
+      </action>
+
+      <action>Mark these decisions as "PROVIDED BY STARTER" in our decision tracking</action>
+
+      <action>Note for first implementation story:
+        "Project initialization using {{starter_command}} should be the first implementation story"
+      </action>
+    </check>
+
+    <check if="user_rejects_starter">
+      <ask>Any specific reason to avoid the starter? (helps me understand constraints)</ask>
+      <action>Note: Manual setup required, all decisions need to be made explicitly</action>
+    </check>
+
+  </check>
+
+  <check if="no_starter_found_or_applicable">
+    <action>Note: No standard starter template found for this project type.
+            We will make all architectural decisions explicitly.</action>
+  </check>
+
+<template-output>starter_template_decision</template-output>
+</step>
+
+<step n="3" goal="Adapt facilitation style and identify remaining decisions">
+  <action>Based on {user_skill_level} from config, set facilitation approach:
+
+  <check if="{user_skill_level} == 'expert'">
+    Set mode: EXPERT
+    - Use technical terminology freely
+    - Move quickly through decisions
+    - Assume familiarity with patterns and tools
+    - Focus on edge cases and advanced concerns
+  </check>
+
+  <check if="{user_skill_level} == 'intermediate'">
+    Set mode: INTERMEDIATE
+    - Balance technical accuracy with clarity
+    - Explain complex patterns briefly
+    - Confirm understanding at key points
+    - Provide context for non-obvious choices
+  </check>
+
+  <check if="{user_skill_level} == 'beginner'">
+    Set mode: BEGINNER
+    - Use analogies and real-world examples
+    - Explain technical concepts in simple terms
+    - Provide education about why decisions matter
+    - Protect from complexity overload
+  </check>
+  </action>
+
+<action>Load decision catalog: {decision_catalog}</action>
+<action>Load architecture patterns: {architecture_patterns}</action>
+
+<action>Analyze PRD against patterns to identify needed decisions: - Match functional requirements to known patterns - Identify which categories of decisions are needed - Flag any novel/unique aspects requiring special attention - Consider which decisions the starter template already made (if applicable)
+</action>
+
+<action>Create decision priority list:
+CRITICAL (blocks everything): - {{list_of_critical_decisions}}
+
+    IMPORTANT (shapes architecture):
+    - {{list_of_important_decisions}}
+
+    NICE-TO-HAVE (can defer):
+    - {{list_of_optional_decisions}}
+
+  </action>
+
+<action>Announce plan to {user_name} based on mode:
+<check if="mode == 'EXPERT'">
+"Based on your PRD, we need to make {{total_decision_count}} architectural decisions.
+{{starter_covered_count}} are covered by the starter template.
+Let's work through the remaining {{remaining_count}} decisions."
+</check>
+
+    <check if="mode == 'BEGINNER'">
+      "Great! I've analyzed your requirements and found {{total_decision_count}} technical
+       choices we need to make. Don't worry - I'll guide you through each one and explain
+       why it matters. {{if_starter}}The starter template handles {{starter_covered_count}}
+       of these automatically.{{/if_starter}}"
+    </check>
+
+  </action>
+
+<template-output>decision_identification</template-output>
+</step>
+
+<step n="4" goal="Facilitate collaborative decision making" repeat="for-each-decision">
+  <critical>Each decision must be made WITH the user, not FOR them</critical>
+  <critical>ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions</critical>
+
+<action>For each decision in priority order:</action>
+
+<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}}
+
+      We need to choose {{Specific_Decision}}.
+
+      Common options:
+      {{option_list_with_brief_explanations}}
+
+      For your project, {{recommendation}} would work well because {{reason}}."
+
+  </check>
+
+  <check if="mode == 'BEGINNER'">
+    "Let's talk about {{Human_Friendly_Category}}.
+
+      {{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>
+
+  <check if="decision_involves_specific_technology">
+    <action>Verify current stable version:
+      <WebSearch>{{technology}} latest stable version 2024</WebSearch>
+      <WebSearch>{{technology}} current LTS version</WebSearch>
+    </action>
+
+    <action>Update decision record with verified version:
+      Technology: {{technology}}
+      Verified Version: {{version_from_search}}
+      Verification Date: {{today}}
+    </action>
+
+  </check>
+
+<ask>What's your preference? (or 'explain more' for details)</ask>
+
+  <check if="user_wants_more_info">
+    <action>Provide deeper explanation appropriate to skill level</action>
+    <check if="complex_tradeoffs">
+      <action>Consider using advanced elicitation:
+        "Would you like to explore innovative approaches to this decision?
+         I can help brainstorm unconventional solutions if you have specific goals."
+      </action>
+    </check>
+  </check>
+
+<action>Record decision:
+Category: {{category}}
+Decision: {{user_choice}}
+Version: {{verified_version_if_applicable}}
+Affects Epics: {{list_of_affected_epics}}
+Rationale: {{user_reasoning_or_default}}
+Provided by Starter: {{yes_if_from_starter}}
+</action>
+
+<action>Check for cascading implications:
+"This choice means we'll also need to {{related_decisions}}"
+</action>
+
+<template-output>decision_record</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="5" goal="Address cross-cutting concerns">
+  <critical>These decisions affect EVERY epic and story</critical>
+
+<action>Facilitate decisions for consistency patterns: - Error handling strategy (How will all agents handle errors?) - Logging approach (Structured? Format? Levels?) - Date/time handling (Timezone? Format? Library?) - Authentication pattern (Where? How? Token format?) - API response format (Structure? Status codes? Errors?) - Testing strategy (Unit? Integration? E2E?)
+</action>
+
+  <check if="{user_skill_level} == 'beginner'">
+    <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>
+</step>
+
+<step n="6" goal="Define project structure and boundaries">
+  <action>Based on all decisions made, define the project structure</action>
+
+<action>Create comprehensive source tree: - Root configuration files - Source code organization - Test file locations - Build/dist directories - Documentation structure
+</action>
+
+<action>Map epics to architectural boundaries:
+"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
+</action>
+
+<action>Define integration points: - Where do components communicate? - What are the API boundaries? - How do services interact?
+</action>
+
+<template-output>project_structure</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="7" goal="Design novel architectural patterns" optional="true">
+  <critical>Some projects require INVENTING new patterns, not just choosing existing ones</critical>
+
+<action>Scan PRD for concepts that don't have standard solutions: - Novel interaction patterns (e.g., "swipe to match" before Tinder existed) - Unique multi-component workflows (e.g., "viral invitation system") - New data relationships (e.g., "social graph" before Facebook) - Unprecedented user experiences (e.g., "ephemeral messages" before Snapchat) - Complex state machines crossing multiple epics
+</action>
+
+  <check if="novel_patterns_detected">
+    <action>For each novel pattern identified:</action>
+
+    <action>Engage user in design collaboration:
+      <check if="{user_skill_level} == 'expert'">
+        "The {{pattern_name}} concept requires architectural innovation.
+
+         Core challenge: {{challenge_description}}
+
+         Let's design the component interaction model:"
+      </check>
+
+      <check if="{user_skill_level} == 'beginner'">
+        "Your idea about {{pattern_name}} is unique - there isn't a standard way to build this yet!
+
+         This is exciting - we get to invent the architecture together.
+
+         Let me help you think through how this should work:"
+      </check>
+    </action>
+
+    <action>Facilitate pattern design:
+      1. Identify core components involved
+      2. Map data flow between components
+      3. Design state management approach
+      4. Create sequence diagrams for complex flows
+      5. Define API contracts for the pattern
+      6. Consider edge cases and failure modes
+    </action>
+
+    <action>Use advanced elicitation for innovation:
+      "What if we approached this differently?
+       - What would the ideal user experience look like?
+       - Are there analogies from other domains we could apply?
+       - What constraints can we challenge?"
+    </action>
+
+    <action>Document the novel pattern:
+      Pattern Name: {{pattern_name}}
+      Purpose: {{what_problem_it_solves}}
+      Components:
+        {{component_list_with_responsibilities}}
+      Data Flow:
+        {{sequence_description_or_diagram}}
+      Implementation Guide:
+        {{how_agents_should_build_this}}
+      Affects Epics:
+        {{epics_that_use_this_pattern}}
+    </action>
+
+    <action>Validate pattern completeness:
+      "Does this {{pattern_name}} design cover all the use cases in your epics?
+       - {{use_case_1}}: ✓ Handled by {{component}}
+       - {{use_case_2}}: ✓ Handled by {{component}}
+       ..."
+    </action>
+
+  </check>
+
+  <check if="no_novel_patterns">
+    <action>Note: All patterns in this project have established solutions.
+            Proceeding with standard architectural patterns.</action>
+  </check>
+
+<template-output>novel_pattern_designs</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="8" goal="Define implementation patterns to prevent agent conflicts">
+  <critical>These patterns ensure multiple AI agents write compatible code</critical>
+  <critical>Focus on what agents could decide DIFFERENTLY if not specified</critical>
+
+<action>Load pattern categories: {pattern_categories}</action>
+
+<action>Based on chosen technologies, identify potential conflict points:
+"Given that we're using {{tech_stack}}, agents need consistency rules for:"
+</action>
+
+<action>For each relevant pattern category, facilitate decisions:
+
+    NAMING PATTERNS (How things are named):
+    <check if="has_api">
+      - REST endpoint naming: /users or /user? Plural or singular?
+      - Route parameter format: :id or {id}?
+    </check>
+    <check if="has_database">
+      - Table naming: users or Users or user?
+      - Column naming: user_id or userId?
+      - Foreign key format: user_id or fk_user?
+    </check>
+    <check if="has_frontend">
+      - Component naming: UserCard or user-card?
+      - File naming: UserCard.tsx or user-card.tsx?
+    </check>
+
+    STRUCTURE PATTERNS (How things are organized):
+    - Where do tests live? __tests__/ or *.test.ts co-located?
+    - How are components organized? By feature or by type?
+    - Where do shared utilities go?
+
+    FORMAT PATTERNS (Data exchange formats):
+    <check if="has_api">
+      - API response wrapper? {data: ..., error: ...} or direct response?
+      - Error format? {message, code} or {error: {type, detail}}?
+      - Date format in JSON? ISO strings or timestamps?
+    </check>
+
+    COMMUNICATION PATTERNS (How components interact):
+    <check if="has_events">
+      - Event naming convention?
+      - Event payload structure?
+    </check>
+    <check if="has_state_management">
+      - State update pattern?
+      - Action naming convention?
+    </check>
+
+    LIFECYCLE PATTERNS (State and flow):
+    - How are loading states handled?
+    - What's the error recovery pattern?
+    - How are retries implemented?
+
+    LOCATION PATTERNS (Where things go):
+    - API route structure?
+    - Static asset organization?
+    - Config file locations?
+
+    CONSISTENCY PATTERNS (Cross-cutting):
+    - How are dates formatted in the UI?
+    - What's the logging format?
+    - How are user-facing errors written?
+
+  </action>
+
+  <check if="{user_skill_level} == 'expert'">
+    <action>Rapid-fire through patterns:
+      "Quick decisions on implementation patterns:
+       - {{pattern}}: {{suggested_convention}} OK? [y/n/specify]"
+    </action>
+  </check>
+
+  <check if="{user_skill_level} == 'beginner'">
+    <action>Explain each pattern's importance:
+      "Let me explain why this matters:
+       If one AI agent names database tables 'users' and another names them 'Users',
+       your app will crash. We need to pick one style and make sure everyone follows it."
+    </action>
+  </check>
+
+<action>Document implementation patterns:
+Category: {{pattern_category}}
+Pattern: {{specific_pattern}}
+Convention: {{decided_convention}}
+Example: {{concrete_example}}
+Enforcement: "All agents MUST follow this pattern"
+</action>
+
+<template-output>implementation_patterns</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="9" goal="Validate architectural coherence">
+  <action>Run coherence checks:</action>
+
+<action>Check decision compatibility: - Do all decisions work together? - Are there any conflicting choices? - Do the versions align properly?
+</action>
+
+<action>Verify epic coverage: - Does every epic have architectural support? - Are all user stories implementable with these decisions? - Are there any gaps?
+</action>
+
+<action>Validate pattern completeness: - Are there any patterns we missed that agents would need? - Do novel patterns integrate with standard architecture? - Are implementation patterns comprehensive enough?
+</action>
+
+  <check if="issues_found">
+    <action>Address issues with {user_name}:
+      "I notice {{issue_description}}.
+       We should {{suggested_resolution}}."
+    </action>
+    <ask>How would you like to resolve this?</ask>
+    <action>Update decisions based on resolution</action>
+  </check>
+
+<template-output>coherence_validation</template-output>
+</step>
+
+<step n="10" goal="Generate decision architecture document">
+  <critical>The document must be complete, specific, and validation-ready</critical>
+  <critical>This is the consistency contract for all AI agents</critical>
+
+<action>Load template: {architecture_template}</action>
+
+<action>Generate sections: 1. Executive Summary (2-3 sentences about the architecture approach) 2. Project Initialization (starter command if applicable) 3. Decision Summary Table (with verified versions and epic mapping) 4. Complete Project Structure (full tree, no placeholders) 5. Epic to Architecture Mapping (every epic placed) 6. Technology Stack Details (versions, configurations) 7. Integration Points (how components connect) 8. Novel Pattern Designs (if any were created) 9. Implementation Patterns (all consistency rules) 10. Consistency Rules (naming, organization, formats) 11. Data Architecture (models and relationships) 12. API Contracts (request/response formats) 13. Security Architecture (auth, authorization, data protection) 14. Performance Considerations (from NFRs) 15. Deployment Architecture (where and how) 16. Development Environment (setup and prerequisites) 17. Architecture Decision Records (key decisions with rationale)
+</action>
+
+<action>Fill template with all collected decisions and patterns</action>
+
+<action>Ensure starter command is first implementation story:
+<check if="using_starter_template">
+"## Project Initialization
+
+       First implementation story should execute:
+       ```bash
+       {{starter_command_with_options}}
+       ```
+
+       This establishes the base architecture with these decisions:
+       {{starter_provided_decisions}}"
+    </check>
+
+  </action>
+
+<template-output>architecture_document</template-output>
+<invoke-task halt="true">{project-root}/.bmad/core/tasks/adv-elicit.xml</invoke-task>
+</step>
+
+<step n="11" goal="Validate document completeness">
+  <action>Load validation checklist: {installed_path}/checklist.md</action>
+
+<action>Run validation checklist from {installed_path}/checklist.md</action>
+
+<action>Verify MANDATORY items:
+□ Decision table has Version column with specific versions
+□ Every epic is mapped to architecture components
+□ Source tree is complete, not generic
+□ No placeholder text remains
+□ All FRs from PRD have architectural support
+□ All NFRs from PRD are addressed
+□ Implementation patterns cover all potential conflicts
+□ Novel patterns are fully documented (if applicable)
+</action>
+
+  <check if="validation_failed">
+    <action>Fix missing items automatically</action>
+    <goto step="10">Regenerate document section</goto>
+  </check>
+
+<template-output>validation_results</template-output>
+</step>
+
+<step n="12" goal="Final review and update workflow status">
+  <action>Present completion summary:</action>
+
+  <check if="{user_skill_level} == 'expert'">
+    "Architecture complete. {{decision_count}} decisions documented.
+     Ready for implementation phase."
+  </check>
+
+  <check if="{user_skill_level} == 'beginner'">
+    "Excellent! Your architecture is complete. You made {{decision_count}} important
+     decisions that will keep AI agents consistent as they build your app.
+
+     What happens next:
+     1. AI agents will read this architecture before implementing each story
+     2. They'll follow your technical choices exactly
+     3. Your app will be built with consistent patterns throughout
+
+     You're ready to move to the implementation phase!"
+
+  </check>
+
+<action>Save document to {output_folder}/architecture.md</action>
+
+  <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>
+
+    <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
+  {{if_novel_patterns}}
+- ✅ Novel pattern designs for unique concepts
+  {{/if_novel_patterns}}
+  {{if_starter_template}}
+- ✅ Project initialization command documented
+  {{/if_starter_template}}
+
+The architecture is ready to guide AI agents through consistent implementation.
+
+**Next Steps:**
+
+- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+- Review the architecture.md document before proceeding
+
+Check status anytime with: `workflow-status`
+</output>
+
+<template-output>completion_summary</template-output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/3-solutioning/architecture/pattern-categories.csv

@@ -0,0 +1,13 @@
+category,when_needed,what_to_define,why_critical
+naming_patterns,Any technology with named entities,How things are named (format/case/structure),Agents will create different names for same concept
+structure_patterns,Any technology with organization,How things are organized (folders/modules/layers),Agents will put things in different places
+format_patterns,Any technology with data exchange,How data is formatted (JSON/XML/responses),Agents will use incompatible formats
+communication_patterns,Any technology with inter-component communication,How components talk (protocols/events/messages),Agents will use different communication methods
+lifecycle_patterns,Any technology with state or flow,How state changes and flows work,Agents will handle state transitions differently
+location_patterns,Any technology with storage or routing,Where things go (URLs/paths/storage),Agents will put things in different locations
+consistency_patterns,Always,Cross-cutting concerns (dates/errors/logs),Every agent will do these differently
+
+# PRINCIPLE FOR LLM:
+# Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture.
+# Think about: What could an agent encounter where they'd have to guess?
+# If they'd guess, define the pattern. If it's obvious from the tech choice, skip it.

.bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml

@@ -0,0 +1,68 @@
+# Architecture Workflow Configuration
+name: architecture
+description: "Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts."
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Input requirements - We work from PRD, Epics, and optionally UX Spec
+recommended_inputs:
+  - prd: "Product Requirements Document with FRs and NFRs"
+  - epics: "Epic definitions with user stories and acceptance criteria"
+  - ux_spec: "UX specification with interface designs and interaction patterns (optional)"
+
+# 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"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: "{installed_path}/architecture-template.md"
+
+# Knowledge bases for intelligent decision making
+decision_catalog: "{installed_path}/decision-catalog.yaml"
+architecture_patterns: "{installed_path}/architecture-patterns.yaml"
+pattern_categories: "{installed_path}/pattern-categories.csv"
+
+# Output configuration
+default_output_file: "{output_folder}/architecture.md"
+
+# Workflow metadata
+version: "1.3.2"
+replaces: "architecture"
+paradigm: "facilitation-driven"
+execution_time: "30-90 minutes depending on user skill level"
+features:
+  - "Starter template discovery and integration"
+  - "Dynamic version verification via web search"
+  - "Adaptive facilitation by skill level"
+  - "Decision-focused architecture"
+  - "Novel pattern design for unique concepts"
+  - "Intelligent pattern identification - LLM figures out what patterns matter"
+  - "Implementation patterns for agent consistency"
+
+standalone: true
+# Web bundle configuration for standalone deployment

.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/checklist.md

@@ -0,0 +1,175 @@
+# Implementation Readiness Validation Checklist
+
+## Document Completeness
+
+### Core Planning Documents
+
+- [ ] PRD exists and is complete (Level 2-4 projects)
+- [ ] PRD contains measurable success criteria
+- [ ] PRD defines clear scope boundaries and exclusions
+- [ ] Architecture document exists (architecture\*.md) (Level 3-4 projects)
+- [ ] Technical Specification exists with implementation details
+- [ ] Epic and story breakdown document exists
+- [ ] All documents are dated and versioned
+
+### Document Quality
+
+- [ ] No placeholder sections remain in any document
+- [ ] All documents use consistent terminology
+- [ ] Technical decisions include rationale and trade-offs
+- [ ] Assumptions and risks are explicitly documented
+- [ ] Dependencies are clearly identified and documented
+
+## Alignment Verification
+
+### PRD to Architecture Alignment (Level 3-4)
+
+- [ ] Every functional requirement in PRD has architectural support documented
+- [ ] All non-functional requirements from PRD are addressed in architecture
+- [ ] Architecture doesn't introduce features beyond PRD scope
+- [ ] Performance requirements from PRD match architecture capabilities
+- [ ] Security requirements from PRD are fully addressed in architecture
+- [ ] If architecture.md: Implementation patterns are defined for consistency
+- [ ] If architecture.md: All technology choices have verified versions
+- [ ] If UX spec exists: Architecture supports UX requirements
+
+### PRD to Stories Coverage (Level 2-4)
+
+- [ ] Every PRD requirement maps to at least one story
+- [ ] All user journeys in PRD have complete story coverage
+- [ ] Story acceptance criteria align with PRD success criteria
+- [ ] Priority levels in stories match PRD feature priorities
+- [ ] No stories exist without PRD requirement traceability
+
+### Architecture to Stories Implementation
+
+- [ ] All architectural components have implementation stories
+- [ ] Infrastructure setup stories exist for each architectural layer
+- [ ] Integration points defined in architecture have corresponding stories
+- [ ] Data migration/setup stories exist if required by architecture
+- [ ] Security implementation stories cover all architecture security decisions
+
+## Story and Sequencing Quality
+
+### Story Completeness
+
+- [ ] All stories have clear acceptance criteria
+- [ ] Technical tasks are defined within relevant stories
+- [ ] Stories include error handling and edge cases
+- [ ] Each story has clear definition of done
+- [ ] Stories are appropriately sized (no epic-level stories remaining)
+
+### Sequencing and Dependencies
+
+- [ ] Stories are sequenced in logical implementation order
+- [ ] Dependencies between stories are explicitly documented
+- [ ] No circular dependencies exist
+- [ ] Prerequisite technical tasks precede dependent stories
+- [ ] Foundation/infrastructure stories come before feature stories
+
+### Greenfield Project Specifics
+
+- [ ] Initial project setup and configuration stories exist
+- [ ] If using architecture.md: First story is starter template initialization command
+- [ ] Development environment setup is documented
+- [ ] CI/CD pipeline stories are included early in sequence
+- [ ] Database/storage initialization stories are properly placed
+- [ ] Authentication/authorization stories precede protected features
+
+## Risk and Gap Assessment
+
+### Critical Gaps
+
+- [ ] No core PRD requirements lack story coverage
+- [ ] No architectural decisions lack implementation stories
+- [ ] All integration points have implementation plans
+- [ ] Error handling strategy is defined and implemented
+- [ ] Security concerns are all addressed
+
+### Technical Risks
+
+- [ ] No conflicting technical approaches between stories
+- [ ] Technology choices are consistent across all documents
+- [ ] Performance requirements are achievable with chosen architecture
+- [ ] Scalability concerns are addressed if applicable
+- [ ] Third-party dependencies are identified with fallback plans
+
+## UX and Special Concerns (if applicable)
+
+### UX Coverage
+
+- [ ] UX requirements are documented in PRD
+- [ ] UX implementation tasks exist in relevant stories
+- [ ] Accessibility requirements have story coverage
+- [ ] Responsive design requirements are addressed
+- [ ] User flow continuity is maintained across stories
+
+### Special Considerations
+
+- [ ] Compliance requirements are fully addressed
+- [ ] Internationalization needs are covered if required
+- [ ] Performance benchmarks are defined and measurable
+- [ ] Monitoring and observability stories exist
+- [ ] Documentation stories are included where needed
+
+## Overall Readiness
+
+### Ready to Proceed Criteria
+
+- [ ] All critical issues have been resolved
+- [ ] High priority concerns have mitigation plans
+- [ ] Story sequencing supports iterative delivery
+- [ ] Team has necessary skills for implementation
+- [ ] No blocking dependencies remain unresolved
+
+### Quality Indicators
+
+- [ ] Documents demonstrate thorough analysis
+- [ ] Clear traceability exists across all artifacts
+- [ ] Consistent level of detail throughout documents
+- [ ] Risks are identified with mitigation strategies
+- [ ] Success criteria are measurable and achievable
+
+## Assessment Completion
+
+### Report Quality
+
+- [ ] All findings are supported by specific examples
+- [ ] Recommendations are actionable and specific
+- [ ] Severity levels are appropriately assigned
+- [ ] Positive findings are highlighted
+- [ ] Next steps are clearly defined
+
+### Process Validation
+
+- [ ] All expected documents were reviewed
+- [ ] Cross-references were systematically checked
+- [ ] Project level considerations were applied correctly
+- [ ] Workflow status was checked and considered
+- [ ] Output folder was thoroughly searched for artifacts
+
+---
+
+## Issue Log
+
+### Critical Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+### High Priority Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+### Medium Priority Issues Found
+
+- [ ] ***
+- [ ] ***
+- [ ] ***
+
+---
+
+_Use this checklist to ensure comprehensive validation of implementation readiness_

.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md

@@ -0,0 +1,305 @@
+# Implementation Ready Check - Workflow Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml</critical>
+<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+
+<workflow>
+
+<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. Implementation Ready Check 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 file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "solutioning-gate-check" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+<action>Based on the project_level, understand what artifacts should exist: - Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning) - Level 2: PRD, tech spec, epics/stories (no separate architecture doc) - Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
+</action>
+
+  <check if="solutioning-gate-check status is file path (already completed)">
+    <output>⚠️ Gate check already completed: {{solutioning-gate-check status}}</output>
+    <ask>Re-running will create a new validation report. 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="solutioning-gate-check is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Gate check is out of sequence.</output>
+    <ask>Continue with gate check 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>
+
+<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
+
+<template-output>project_context</template-output>
+</step>
+
+<step n="1" goal="Discover and inventory project artifacts">
+<action>Search the {output_folder} for relevant planning and solutioning documents based on project level identified in Step 0</action>
+
+<action>For Level 0-1 projects, locate:
+
+- Technical specification document(s)
+- Story/task lists or simple epic breakdowns
+- Any API or interface definitions
+  </action>
+
+<action>For Level 2-4 projects, locate:
+
+- Product Requirements Document (PRD)
+- Architecture document (architecture.md) (Level 3-4 only)
+- Technical Specification (Level 2 includes architecture within)
+- Epic and story breakdowns
+- UX artifacts if the active path includes UX workflow
+- Any supplementary planning documents
+  </action>
+
+<action>Create an inventory of found documents with:
+
+- Document type and purpose
+- File path and last modified date
+- Brief description of what each contains
+- Any missing expected documents flagged as potential issues
+  </action>
+
+<template-output>document_inventory</template-output>
+</step>
+
+<step n="2" goal="Deep analysis of core planning documents">
+<action>Load and thoroughly analyze each discovered document to extract:
+- Core requirements and success criteria
+- Architectural decisions and constraints
+- Technical implementation approaches
+- User stories and acceptance criteria
+- Dependencies and sequencing requirements
+- Any assumptions or risks documented
+</action>
+
+<action>For PRD analysis (Level 2-4), focus on:
+
+- User requirements and use cases
+- Functional and non-functional requirements
+- Success metrics and acceptance criteria
+- Scope boundaries and explicitly excluded items
+- Priority levels for different features
+  </action>
+
+<action>For Architecture/Tech Spec analysis, focus on:
+
+- System design decisions and rationale
+- Technology stack and framework choices
+- Integration points and APIs
+- Data models and storage decisions
+- Security and performance considerations
+- Any architectural constraints that might affect story implementation
+  </action>
+
+<action>For Epic/Story analysis, focus on:
+
+- Coverage of PRD requirements
+- Story sequencing and dependencies
+- Acceptance criteria completeness
+- Technical tasks within stories
+- Estimated complexity and effort indicators
+  </action>
+
+<template-output>document_analysis</template-output>
+</step>
+
+<step n="3" goal="Cross-reference validation and alignment check">
+<action>Systematically validate alignment between all artifacts, adapting validation based on project level</action>
+
+<action>PRD ↔ Architecture Alignment (Level 3-4):
+
+- Verify every PRD requirement has corresponding architectural support
+- Check that architectural decisions don't contradict PRD constraints
+- Identify any architectural additions beyond PRD scope (potential gold-plating)
+- Ensure non-functional requirements from PRD are addressed in architecture document
+- If using new architecture workflow: verify implementation patterns are defined
+  </action>
+
+<action>PRD ↔ Stories Coverage (Level 2-4):
+
+- Map each PRD requirement to implementing stories
+- Identify any PRD requirements without story coverage
+- Find stories that don't trace back to PRD requirements
+- Validate that story acceptance criteria align with PRD success criteria
+  </action>
+
+<action>Architecture ↔ Stories Implementation Check:
+
+- Verify architectural decisions are reflected in relevant stories
+- Check that story technical tasks align with architectural approach
+- Identify any stories that might violate architectural constraints
+- Ensure infrastructure and setup stories exist for architectural components
+  </action>
+
+<action>For Level 0-1 projects (Tech Spec only):
+
+- Validate internal consistency within tech spec
+- Check that all specified features have corresponding stories
+- Verify story sequencing matches technical dependencies
+  </action>
+
+<template-output>alignment_validation</template-output>
+</step>
+
+<step n="4" goal="Gap and risk analysis">
+<action>Identify and categorize all gaps, risks, and potential issues discovered during validation</action>
+
+<action>Check for Critical Gaps:
+
+- Missing stories for core requirements
+- Unaddressed architectural concerns
+- Absent infrastructure or setup stories for greenfield projects
+- Missing error handling or edge case coverage
+- Security or compliance requirements not addressed
+  </action>
+
+<action>Identify Sequencing Issues:
+
+- Dependencies not properly ordered
+- Stories that assume components not yet built
+- Parallel work that should be sequential
+- Missing prerequisite technical tasks
+  </action>
+
+<action>Detect Potential Contradictions:
+
+- Conflicts between PRD and architecture approaches
+- Stories with conflicting technical approaches
+- Acceptance criteria that contradict requirements
+- Resource or technology conflicts
+  </action>
+
+<action>Find Gold-Plating and Scope Creep:
+
+- Features in architecture not required by PRD
+- Stories implementing beyond requirements
+- Technical complexity beyond project needs
+- Over-engineering indicators
+  </action>
+
+<template-output>gap_risk_analysis</template-output>
+</step>
+
+<step n="5" goal="UX and special concerns validation" optional="true">
+<check if="UX artifacts exist or UX workflow in active path">
+<action>Review UX artifacts and validate integration:
+- Check that UX requirements are reflected in PRD
+- Verify stories include UX implementation tasks
+- Ensure architecture supports UX requirements (performance, responsiveness)
+- Identify any UX concerns not addressed in stories
+</action>
+
+<action>Validate accessibility and usability coverage:
+
+- Check for accessibility requirement coverage in stories
+- Verify responsive design considerations if applicable
+- Ensure user flow completeness across stories
+  </action>
+  </check>
+
+<template-output>ux_validation</template-output>
+</step>
+
+<step n="6" goal="Generate comprehensive readiness assessment">
+<action>Compile all findings into a structured readiness report with:
+- Executive summary of readiness status
+- Project context and validation scope
+- Document inventory and coverage assessment
+- Detailed findings organized by severity (Critical, High, Medium, Low)
+- Specific recommendations for each issue
+- Overall readiness recommendation (Ready, Ready with Conditions, Not Ready)
+</action>
+
+<action>Provide actionable next steps:
+
+- List any critical issues that must be resolved
+- Suggest specific document updates needed
+- Recommend additional stories or tasks required
+- Propose sequencing adjustments if needed
+  </action>
+
+<action>Include positive findings:
+
+- Highlight well-aligned areas
+- Note particularly thorough documentation
+- Recognize good architectural decisions
+- Commend comprehensive story coverage where found
+  </action>
+
+<template-output>readiness_assessment</template-output>
+</step>
+
+<step n="7" goal="Update status and complete" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "solutioning-gate-check"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["solutioning-gate-check"] = "{output_folder}/bmm-readiness-assessment-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<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>**✅ Implementation Ready Check Complete!**
+
+**Assessment Report:**
+
+- Readiness assessment saved to: {output_folder}/bmm-readiness-assessment-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: solutioning-gate-check marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- Review the assessment report and address any critical issues before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+
+<template-output>status_update_result</template-output>
+</step>
+
+</workflow>

.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/template.md

@@ -0,0 +1,146 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}
+**Assessed By:** {{user_name}}
+**Assessment Type:** Phase 3 to Phase 4 Transition Validation
+
+---
+
+## Executive Summary
+
+{{readiness_assessment}}
+
+---
+
+## Project Context
+
+{{project_context}}
+
+---
+
+## Document Inventory
+
+### Documents Reviewed
+
+{{document_inventory}}
+
+### Document Analysis Summary
+
+{{document_analysis}}
+
+---
+
+## Alignment Validation Results
+
+### Cross-Reference Analysis
+
+{{alignment_validation}}
+
+---
+
+## Gap and Risk Analysis
+
+### Critical Findings
+
+{{gap_risk_analysis}}
+
+---
+
+## UX and Special Concerns
+
+{{ux_validation}}
+
+---
+
+## Detailed Findings
+
+### 🔴 Critical Issues
+
+_Must be resolved before proceeding to implementation_
+
+{{critical_issues}}
+
+### 🟠 High Priority Concerns
+
+_Should be addressed to reduce implementation risk_
+
+{{high_priority_concerns}}
+
+### 🟡 Medium Priority Observations
+
+_Consider addressing for smoother implementation_
+
+{{medium_priority_observations}}
+
+### 🟢 Low Priority Notes
+
+_Minor items for consideration_
+
+{{low_priority_notes}}
+
+---
+
+## Positive Findings
+
+### ✅ Well-Executed Areas
+
+{{positive_findings}}
+
+---
+
+## Recommendations
+
+### Immediate Actions Required
+
+{{immediate_actions}}
+
+### Suggested Improvements
+
+{{suggested_improvements}}
+
+### Sequencing Adjustments
+
+{{sequencing_adjustments}}
+
+---
+
+## Readiness Decision
+
+### Overall Assessment: {{overall_readiness_status}}
+
+{{readiness_rationale}}
+
+### Conditions for Proceeding (if applicable)
+
+{{conditions_for_proceeding}}
+
+---
+
+## Next Steps
+
+{{recommended_next_steps}}
+
+### Workflow Status Update
+
+{{status_update_result}}
+
+---
+
+## Appendices
+
+### A. Validation Criteria Applied
+
+{{validation_criteria_used}}
+
+### B. Traceability Matrix
+
+{{traceability_matrix}}
+
+### C. Risk Mitigation Strategies
+
+{{risk_mitigation_strategies}}
+
+---
+
+_This readiness assessment was generated using the BMad Method Implementation Ready Check workflow (v6-alpha)_

.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml

@@ -0,0 +1,189 @@
+# Implementation Readiness Validation Criteria
+# Defines systematic validation rules by project level
+
+validation_rules:
+  # Level 0-1 Projects (Simple, minimal planning)
+  level_0_1:
+    required_documents:
+      - tech_spec
+      - stories_or_tasks
+
+    validations:
+      - name: "Tech Spec Completeness"
+        checks:
+          - "All features defined with implementation approach"
+          - "Technical dependencies identified"
+          - "API contracts defined if applicable"
+          - "Data models specified"
+
+      - name: "Story Coverage"
+        checks:
+          - "All tech spec features have corresponding stories"
+          - "Stories are sequenced logically"
+          - "Technical tasks are defined"
+          - "No critical gaps in coverage"
+
+  # Level 2 Projects (PRD + Tech Spec, no separate architecture)
+  level_2:
+    required_documents:
+      - prd
+      - tech_spec # Includes architecture decisions
+      - epics_and_stories
+
+    validations:
+      - name: "PRD to Tech Spec Alignment"
+        checks:
+          - "All PRD requirements addressed in tech spec"
+          - "Architecture embedded in tech spec covers PRD needs"
+          - "Non-functional requirements are specified"
+          - "Technical approach supports business goals"
+
+      - name: "Story Coverage and Alignment"
+        checks:
+          - "Every PRD requirement has story coverage"
+          - "Stories align with tech spec approach"
+          - "Epic breakdown is complete"
+          - "Acceptance criteria match PRD success criteria"
+
+      - name: "Sequencing Validation"
+        checks:
+          - "Foundation stories come first"
+          - "Dependencies are properly ordered"
+          - "Iterative delivery is possible"
+          - "No circular dependencies"
+
+  # Level 3-4 Projects (Full planning with separate architecture)
+  level_3_4:
+    required_documents:
+      - prd
+      - architecture
+      - epics_and_stories
+
+    validations:
+      - name: "PRD Completeness"
+        checks:
+          - "User requirements fully documented"
+          - "Success criteria are measurable"
+          - "Scope boundaries clearly defined"
+          - "Priorities are assigned"
+
+      - name: "Architecture Coverage"
+        checks:
+          - "All PRD requirements have architectural support"
+          - "System design is complete"
+          - "Integration points defined"
+          - "Security architecture specified"
+          - "Performance considerations addressed"
+          - "If architecture.md: Implementation patterns defined"
+          - "If architecture.md: Technology versions verified and current"
+          - "If architecture.md: Starter template command documented (if applicable)"
+
+      - name: "PRD-Architecture Alignment"
+        checks:
+          - "No architecture gold-plating beyond PRD"
+          - "NFRs from PRD reflected in architecture"
+          - "Technology choices support requirements"
+          - "Scalability matches expected growth"
+          - "If UX spec exists: Architecture supports UX requirements"
+          - "If UX spec exists: Component library supports interaction patterns"
+
+      - name: "Story Implementation Coverage"
+        checks:
+          - "All architectural components have stories"
+          - "Infrastructure setup stories exist"
+          - "Integration implementation planned"
+          - "Security implementation stories present"
+
+      - name: "Comprehensive Sequencing"
+        checks:
+          - "Infrastructure before features"
+          - "Authentication before protected resources"
+          - "Core features before enhancements"
+          - "Dependencies properly ordered"
+          - "Allows for iterative releases"
+
+# Special validation contexts
+special_contexts:
+  greenfield:
+    additional_checks:
+      - "Project initialization stories exist"
+      - "If using architecture.md: First story is starter template initialization"
+      - "Development environment setup documented"
+      - "CI/CD pipeline stories included"
+      - "Initial data/schema setup planned"
+      - "Deployment infrastructure stories present"
+
+  ux_workflow_active:
+    additional_checks:
+      - "UX requirements in PRD"
+      - "UX implementation stories exist"
+      - "Accessibility requirements covered"
+      - "Responsive design addressed"
+      - "User flow continuity maintained"
+
+  api_heavy:
+    additional_checks:
+      - "API contracts fully defined"
+      - "Versioning strategy documented"
+      - "Authentication/authorization specified"
+      - "Rate limiting considered"
+      - "API documentation stories included"
+
+# Severity definitions
+severity_levels:
+  critical:
+    description: "Must be resolved before implementation"
+    examples:
+      - "Missing stories for core requirements"
+      - "Conflicting technical approaches"
+      - "No infrastructure setup for greenfield"
+      - "Security requirements not addressed"
+
+  high:
+    description: "Should be addressed to reduce risk"
+    examples:
+      - "Incomplete acceptance criteria"
+      - "Unclear story dependencies"
+      - "Missing error handling coverage"
+      - "Performance requirements not validated"
+
+  medium:
+    description: "Consider addressing for smoother implementation"
+    examples:
+      - "Documentation gaps"
+      - "Test strategy not defined"
+      - "Monitoring approach unclear"
+      - "Minor sequencing improvements possible"
+
+  low:
+    description: "Minor improvements for consideration"
+    examples:
+      - "Formatting inconsistencies"
+      - "Optional enhancements identified"
+      - "Style guide compliance"
+      - "Nice-to-have features noted"
+
+# Readiness decision criteria
+readiness_decisions:
+  ready:
+    criteria:
+      - "No critical issues found"
+      - "All required documents present"
+      - "Core alignments validated"
+      - "Story sequencing logical"
+      - "Team can begin implementation"
+
+  ready_with_conditions:
+    criteria:
+      - "Only high/medium issues found"
+      - "Mitigation plans identified"
+      - "Core path to MVP clear"
+      - "Issues won't block initial stories"
+
+  not_ready:
+    criteria:
+      - "Critical issues identified"
+      - "Major gaps in coverage"
+      - "Conflicting approaches found"
+      - "Required documents missing"
+      - "Blocking dependencies unresolved"

.bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml

@@ -0,0 +1,64 @@
+# Implementation Ready Check - Workflow Configuration
+name: solutioning-gate-check
+description: "Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions."
+author: "BMad Builder"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+# Workflow status integration
+workflow_status_workflow: "{project-root}/.bmad/bmm/workflows/workflow-status/workflow.yaml"
+workflow_paths_dir: "{project-root}/.bmad/bmm/workflows/workflow-status/paths"
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/3-solutioning/solutioning-gate-check"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
+
+# Input requirements
+recommended_inputs:
+  - prd: "Product Requirements Document with FRs and NFRs"
+  - architecture: "System Architecture with decisions and patterns"
+  - tech_spec: "Technical Specification (for Quick Flow track)"
+  - epics: "Epic breakdown with user stories"
+  - ux_design: "UX design specification (if UI components)"
+
+# 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"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/*tech-spec*.md"
+    sharded: "{output_folder}/*tech-spec*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Validation criteria data
+validation_criteria: "{installed_path}/validation-criteria.yaml"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/code-review/backlog_template.md

@@ -0,0 +1,12 @@
+# Engineering Backlog
+
+This backlog collects cross-cutting or future action items that emerge from reviews and planning.
+
+Routing guidance:
+
+- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics.
+- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`.
+- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section.
+
+| Date | Story | Epic | Type | Severity | Owner | Status | Notes |
+| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- |

.bmad/bmm/workflows/4-implementation/code-review/checklist.md

@@ -0,0 +1,22 @@
+# Senior Developer Review - Validation Checklist
+
+- [ ] Story file loaded from `{{story_path}}`
+- [ ] Story Status verified as one of: {{allow_status_values}}
+- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
+- [ ] Story Context located or warning recorded
+- [ ] Epic Tech Spec located or warning recorded
+- [ ] Architecture/standards docs loaded (as available)
+- [ ] Tech stack detected and documented
+- [ ] MCP doc search performed (or web fallback) and references captured
+- [ ] Acceptance Criteria cross-checked against implementation
+- [ ] File List reviewed and validated for completeness
+- [ ] Tests identified and mapped to ACs; gaps noted
+- [ ] Code quality review performed on changed files
+- [ ] Security review performed on changed files and dependencies
+- [ ] Outcome decided (Approve/Changes Requested/Blocked)
+- [ ] Review notes appended under "Senior Developer Review (AI)"
+- [ ] Change Log updated with review entry
+- [ ] Status updated according to settings (if enabled)
+- [ ] Story saved successfully
+
+_Reviewer: {{user_name}} on {{date}}_

.bmad/bmm/workflows/4-implementation/code-review/instructions.md

@@ -0,0 +1,420 @@
+# Senior Developer Review - Workflow Instructions
+
+````xml
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>This workflow performs a SYSTEMATIC Senior Developer Review on a story with status "review", validates EVERY acceptance criterion and EVERY completed task, appends structured review notes with evidence, and updates the story status based on outcome.</critical>
+<critical>If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, offer ad-hoc review option.</critical>
+<critical>Ad-hoc review mode: User can specify any files to review and what to review for (quality, security, requirements, etc.). Creates standalone review report.</critical>
+<critical>SYSTEMATIC VALIDATION REQUIREMENT: For EVERY acceptance criterion, verify implementation with evidence (file:line). For EVERY task marked complete, verify it was actually done. Tasks marked complete but not done = HIGH SEVERITY finding.</critical>
+<critical>⚠️ ZERO TOLERANCE FOR LAZY VALIDATION ⚠️</critical>
+<critical>If you FAIL to catch even ONE task marked complete that was NOT actually implemented, or ONE acceptance criterion marked done that is NOT in the code with evidence, you have FAILED YOUR ONLY PURPOSE. This is an IMMEDIATE DISQUALIFICATION. No shortcuts. No assumptions. No "looks good enough." You WILL read every file. You WILL verify every claim. You WILL provide evidence (file:line) for EVERY validation. Failure to catch false completions = you failed humanity and the project. Your job is to be the uncompromising gatekeeper. DO YOUR JOB COMPLETELY OR YOU WILL BE REPLACED.</critical>
+<critical>Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section.</critical>
+<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+
+<critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
+
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+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 structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
+
+<workflow>
+
+  <step n="1" goal="Find story ready for review" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file and parse sections</action>
+      <action>Extract story_key from filename or story metadata</action>
+      <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed"</action>
+    </check>
+
+    <check if="{{story_path}} is NOT provided">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
+
+      <action>Find FIRST story (reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "review"
+      </action>
+
+      <check if="no story with status 'review' found">
+        <output>📋 No stories with status "review" found
+
+**What would you like to do?**
+1. Run `dev-story` to implement and mark a story ready for review
+2. Check sprint-status.yaml for current story states
+3. Tell me what code to review and what to review it for
+        </output>
+        <ask>Select an option (1/2/3):</ask>
+
+        <check if="option 3 selected">
+          <ask>What code would you like me to review?
+
+Provide:
+- File path(s) or directory to review
+- What to review for:
+  • General quality and standards
+  • Requirements compliance
+  • Security concerns
+  • Performance issues
+  • Architecture alignment
+  • Something else (specify)
+
+Your input:</ask>
+
+          <action>Parse user input to extract:
+            - {{review_files}}: file paths or directories to review
+            - {{review_focus}}: what aspects to focus on
+            - {{review_context}}: any additional context provided
+          </action>
+
+          <action>Set ad_hoc_review_mode = true</action>
+          <action>Skip to step 4 with custom scope</action>
+        </check>
+
+        <check if="option 1 or 2 or no option 3">
+          <action>HALT</action>
+        </check>
+      </check>
+
+      <action>Use the first story found with status "review"</action>
+      <action>Resolve story file path in {{story_dir}}</action>
+      <action>Read the COMPLETE story file</action>
+    </check>
+
+    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata</action>
+    <action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log</action>
+    <action if="story cannot be read">HALT with message: "Unable to read story file"</action>
+  </step>
+
+  <step n="2" goal="Resolve story context file and specification inputs">
+    <action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
+    <action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
+
+    <action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
+    <action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}"</action>
+
+    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
+  </step>
+
+  <step n="3" goal="Detect tech stack and establish best-practice reference set">
+    <action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
+    <action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
+  </step>
+
+  <step n="4" goal="Systematic validation of implementation against acceptance criteria and tasks">
+    <check if="ad_hoc_review_mode == true">
+      <action>Use {{review_files}} as the file list to review</action>
+      <action>Focus review on {{review_focus}} aspects specified by user</action>
+      <action>Use {{review_context}} for additional guidance</action>
+      <action>Skip acceptance criteria checking (no story context)</action>
+      <action>If architecture docs exist, verify alignment with architectural constraints</action>
+    </check>
+
+    <check if="ad_hoc_review_mode != true">
+      <critical>SYSTEMATIC VALIDATION - Check EVERY AC and EVERY task marked complete</critical>
+
+      <action>From the story, read Acceptance Criteria section completely - parse into numbered list</action>
+      <action>From the story, read Tasks/Subtasks section completely - parse ALL tasks and subtasks with their completion state ([x] = completed, [ ] = incomplete)</action>
+      <action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
+
+      <critical>Step 4A: SYSTEMATIC ACCEPTANCE CRITERIA VALIDATION</critical>
+      <action>Create AC validation checklist with one entry per AC</action>
+      <action>For EACH acceptance criterion (AC1, AC2, AC3, etc.):
+        1. Read the AC requirement completely
+        2. Search changed files for evidence of implementation
+        3. Determine: IMPLEMENTED, PARTIAL, or MISSING
+        4. Record specific evidence (file:line references where AC is satisfied)
+        5. Check for corresponding tests (unit/integration/E2E as applicable)
+        6. If PARTIAL or MISSING: Flag as finding with severity based on AC criticality
+        7. Document in AC validation checklist
+      </action>
+      <action>Generate AC Coverage Summary: "X of Y acceptance criteria fully implemented"</action>
+
+      <critical>Step 4B: SYSTEMATIC TASK COMPLETION VALIDATION</critical>
+      <action>Create task validation checklist with one entry per task/subtask</action>
+      <action>For EACH task/subtask marked as COMPLETED ([x]):
+        1. Read the task description completely
+        2. Search changed files for evidence the task was actually done
+        3. Determine: VERIFIED COMPLETE, QUESTIONABLE, or NOT DONE
+        4. Record specific evidence (file:line references proving task completion)
+        5. **CRITICAL**: If marked complete but NOT DONE → Flag as HIGH SEVERITY finding with message: "Task marked complete but implementation not found: [task description]"
+        6. If QUESTIONABLE → Flag as MEDIUM SEVERITY finding: "Task completion unclear: [task description]"
+        7. Document in task validation checklist
+      </action>
+      <action>For EACH task/subtask marked as INCOMPLETE ([ ]):
+        1. Note it was not claimed to be complete
+        2. Check if it was actually done anyway (sometimes devs forget to check boxes)
+        3. If done but not marked: Note in review (helpful correction, not a finding)
+      </action>
+      <action>Generate Task Completion Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"</action>
+
+      <critical>Step 4C: CROSS-CHECK EPIC TECH-SPEC REQUIREMENTS</critical>
+      <action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
+      <action if="critical architecture constraints are violated (e.g., layering, dependency rules)">flag as High Severity finding.</action>
+
+      <critical>Step 4D: COMPILE VALIDATION FINDINGS</critical>
+      <action>Compile all validation findings into structured list:
+        - Missing AC implementations (severity based on AC importance)
+        - Partial AC implementations (MEDIUM severity)
+        - Tasks falsely marked complete (HIGH severity - this is critical)
+        - Questionable task completions (MEDIUM severity)
+        - Missing tests for ACs (severity based on AC criticality)
+        - Architecture violations (HIGH severity)
+      </action>
+    </check>
+  </step>
+
+  <step n="5" goal="Perform code quality and risk review">
+    <action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
+    <action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests).</action>
+    <action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
+    <action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
+  </step>
+
+  <step n="6" goal="Decide review outcome and prepare comprehensive notes">
+    <action>Determine outcome based on validation results:
+      - BLOCKED: Any HIGH severity finding (AC missing, task falsely marked complete, critical architecture violation)
+      - CHANGES REQUESTED: Any MEDIUM severity findings or multiple LOW severity issues
+      - APPROVE: All ACs implemented, all completed tasks verified, no significant issues
+    </action>
+
+    <action>Prepare a structured review report with sections:
+      1. **Summary**: Brief overview of review outcome and key concerns
+      2. **Outcome**: Approve | Changes Requested | Blocked (with justification)
+      3. **Key Findings** (by severity):
+         - HIGH severity issues first (especially falsely marked complete tasks)
+         - MEDIUM severity issues
+         - LOW severity issues
+      4. **Acceptance Criteria Coverage**:
+         - Include complete AC validation checklist from Step 4A
+         - Show: AC# | Description | Status (IMPLEMENTED/PARTIAL/MISSING) | Evidence (file:line)
+         - Summary: "X of Y acceptance criteria fully implemented"
+         - List any missing or partial ACs with severity
+      5. **Task Completion Validation**:
+         - Include complete task validation checklist from Step 4B
+         - Show: Task | Marked As | Verified As | Evidence (file:line)
+         - **CRITICAL**: Highlight any tasks marked complete but not done in RED/bold
+         - Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"
+      6. **Test Coverage and Gaps**:
+         - Which ACs have tests, which don't
+         - Test quality issues found
+      7. **Architectural Alignment**:
+         - Tech-spec compliance
+         - Architecture violations if any
+      8. **Security Notes**: Security findings if any
+      9. **Best-Practices and References**: With links
+      10. **Action Items**:
+          - CRITICAL: ALL action items requiring code changes MUST have checkboxes for tracking
+          - Format for actionable items: `- [ ] [Severity] Description (AC #X) [file: path:line]`
+          - Format for informational notes: `- Note: Description (no action required)`
+          - Imperative phrasing for action items
+          - Map to related ACs or files with specific line references
+          - Include suggested owners if clear
+          - Example format:
+            ```
+            ### Action Items
+
+            **Code Changes Required:**
+            - [ ] [High] Add input validation on login endpoint (AC #1) [file: src/routes/auth.js:23-45]
+            - [ ] [Med] Add unit test for invalid email format [file: tests/unit/auth.test.js]
+
+            **Advisory Notes:**
+            - Note: Consider adding rate limiting for production deployment
+            - Note: Document the JWT expiration policy in README
+            ```
+    </action>
+
+    <critical>The AC validation checklist and task validation checklist MUST be included in the review - this is the evidence trail</critical>
+  </step>
+
+  <step n="7" goal="Append review to story and update metadata">
+    <check if="ad_hoc_review_mode == true">
+      <action>Generate review report as a standalone document</action>
+      <action>Save to {{output_folder}}/code-review-{{date}}.md</action>
+      <action>Include sections:
+        - Review Type: Ad-Hoc Code Review
+        - Reviewer: {{user_name}}
+        - Date: {{date}}
+        - Files Reviewed: {{review_files}}
+        - Review Focus: {{review_focus}}
+        - Outcome: (Approve | Changes Requested | Blocked)
+        - Summary
+        - Key Findings
+        - Test Coverage and Gaps
+        - Architectural Alignment
+        - Security Notes
+        - Best-Practices and References (with links)
+        - Action Items
+      </action>
+      <output>Review saved to: {{output_folder}}/code-review-{{date}}.md</output>
+    </check>
+
+    <check if="ad_hoc_review_mode != true">
+      <action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
+      <action>Insert subsections:
+        - Reviewer: {{user_name}}
+        - Date: {{date}}
+        - Outcome: (Approve | Changes Requested | Blocked) with justification
+        - Summary
+        - Key Findings (by severity - HIGH/MEDIUM/LOW)
+        - **Acceptance Criteria Coverage**:
+          * Include complete AC validation checklist with table format
+          * AC# | Description | Status | Evidence
+          * Summary: X of Y ACs implemented
+        - **Task Completion Validation**:
+          * Include complete task validation checklist with table format
+          * Task | Marked As | Verified As | Evidence
+          * **Highlight falsely marked complete tasks prominently**
+          * Summary: X of Y tasks verified, Z questionable, W false completions
+        - Test Coverage and Gaps
+        - Architectural Alignment
+        - Security Notes
+        - Best-Practices and References (with links)
+        - Action Items:
+          * CRITICAL: Format with checkboxes for tracking resolution
+          * Code changes required: `- [ ] [Severity] Description [file: path:line]`
+          * Advisory notes: `- Note: Description (no action required)`
+          * Group by type: "Code Changes Required" and "Advisory Notes"
+      </action>
+      <action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
+      <action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
+      <action>Save the story file.</action>
+
+      <critical>MUST include the complete validation checklists - this is the evidence that systematic review was performed</critical>
+    </check>
+  </step>
+
+  <step n="8" goal="Update sprint status based on review outcome" tag="sprint-status">
+    <check if="ad_hoc_review_mode == true">
+      <action>Skip sprint status update (no story context)</action>
+      <output>📋 Ad-hoc review complete - no sprint status to update</output>
+    </check>
+
+    <check if="ad_hoc_review_mode != true">
+      <action>Determine target status based on review outcome:
+        - If {{outcome}} == "Approve" → target_status = "done"
+        - If {{outcome}} == "Changes Requested" → target_status = "in-progress"
+        - If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
+      </action>
+
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read all development_status entries to find {{story_key}}</action>
+      <action>Verify current status is "review" (expected previous state)</action>
+      <action>Update development_status[{{story_key}}] = {{target_status}}</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+      <check if="update successful">
+        <output>✅ Sprint status updated: review → {{target_status}}</output>
+      </check>
+
+      <check if="story key not found">
+        <output>⚠️ Could not update sprint-status: {{story_key}} not found
+
+Review was saved to story file, but sprint-status.yaml may be out of sync.
+        </output>
+      </check>
+    </check>
+  </step>
+
+  <step n="9" goal="Persist action items to tasks/backlog/epic">
+    <check if="ad_hoc_review_mode == true">
+      <action>All action items are included in the standalone review report</action>
+      <ask if="action items exist">Would you like me to create tracking items for these action items? (backlog/tasks)</ask>
+      <action if="user confirms">
+        If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
+        Append a row per action item with Date={{date}}, Story="Ad-Hoc Review", Epic="N/A", Type, Severity, Owner (or "TBD"), Status="Open", Notes with file refs and context.
+      </action>
+    </check>
+
+    <check if="ad_hoc_review_mode != true">
+      <action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
+      <ask if="action items exist and 'story_tasks' in {{persist_targets}}">Add {{action_item_count}} follow-up items to story Tasks/Subtasks?</ask>
+      <action if="user confirms or no ask needed">
+        Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
+      </action>
+      <action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
+        If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
+        Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
+      </action>
+      <action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
+        If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
+      </action>
+      <action>Save modified files.</action>
+      <action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
+    </check>
+  </step>
+
+  <step n="10" goal="Validation and completion">
+    <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/.bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <action>Report workflow completion.</action>
+
+    <check if="ad_hoc_review_mode == true">
+      <output>**✅ Ad-Hoc Code Review Complete, {user_name}!**
+
+**Review Details:**
+- Files Reviewed: {{review_files}}
+- Review Focus: {{review_focus}}
+- Review Outcome: {{outcome}}
+- Action Items: {{action_item_count}}
+- Review Report: {{output_folder}}/code-review-{{date}}.md
+
+**Next Steps:**
+1. Review the detailed findings in the review report
+2. If changes requested: Address action items in the code
+3. If blocked: Resolve blockers before proceeding
+4. Re-run review on updated code if needed
+      </output>
+    </check>
+
+    <check if="ad_hoc_review_mode != true">
+      <output>**✅ Story Review Complete, {user_name}!**
+
+**Story Details:**
+- Story: {{epic_num}}.{{story_num}}
+- Story Key: {{story_key}}
+- Review Outcome: {{outcome}}
+- Sprint Status: {{target_status}}
+- Action Items: {{action_item_count}}
+
+**Next Steps:**
+1. Review the Senior Developer Review notes appended to story
+2. If approved: Story is marked done, continue with next story
+3. If changes requested: Address action items and re-run `dev-story`
+4. If blocked: Resolve blockers before proceeding
+      </output>
+    </check>
+  </step>
+
+</workflow>
+````

.bmad/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -0,0 +1,65 @@
+# Review Story Workflow
+name: code-review
+description: "Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/code-review"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# This is an action workflow (no output template document)
+template: false
+
+# Variables (can be provided by caller)
+variables:
+  story_path: "" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
+  story_dir: "{config_source}:dev_ephemeral_location" # Directory containing story files
+  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: |
+    - architecture.md
+
+  backlog_file: "{project-root}/docs/backlog.md"
+  update_epic_followups: true
+  epic_followups_section_title: "Post-Review Follow-ups"
+
+# Recommended inputs
+recommended_inputs:
+  - story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
+  - tech_spec: "Epic technical specification document (auto-discovered)"
+  - story_context_file: "Story context file (.context.xml) (auto-discovered)"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
+input_file_patterns:
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/correct-course/checklist.md

@@ -0,0 +1,279 @@
+# Change Navigation Checklist
+
+<critical>This checklist is executed as part of: {project-root}/.bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>Work through each section systematically with the user, recording findings and impacts</critical>
+
+<checklist>
+
+<section n="1" title="Understand the Trigger and Context">
+
+<check-item id="1.1">
+<prompt>Identify the triggering story that revealed this issue</prompt>
+<action>Document story ID and brief description</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.2">
+<prompt>Define the core problem precisely</prompt>
+<action>Categorize issue type:</action>
+  - Technical limitation discovered during implementation
+  - New requirement emerged from stakeholders
+  - Misunderstanding of original requirements
+  - Strategic pivot or market change
+  - Failed approach requiring different solution
+<action>Write clear problem statement</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.3">
+<prompt>Assess initial impact and gather supporting evidence</prompt>
+<action>Collect concrete examples, error messages, stakeholder feedback, or technical constraints</action>
+<action>Document evidence for later reference</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
+</halt-condition>
+
+</section>
+
+<section n="2" title="Epic Impact Assessment">
+
+<check-item id="2.1">
+<prompt>Evaluate current epic containing the trigger story</prompt>
+<action>Can this epic still be completed as originally planned?</action>
+<action>If no, what modifications are needed?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.2">
+<prompt>Determine required epic-level changes</prompt>
+<action>Check each scenario:</action>
+  - Modify existing epic scope or acceptance criteria
+  - Add new epic to address the issue
+  - Remove or defer epic that's no longer viable
+  - Completely redefine epic based on new understanding
+<action>Document specific epic changes needed</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.3">
+<prompt>Review all remaining planned epics for required changes</prompt>
+<action>Check each future epic for impact</action>
+<action>Identify dependencies that may be affected</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.4">
+<prompt>Check if issue invalidates future epics or necessitates new ones</prompt>
+<action>Does this change make any planned epics obsolete?</action>
+<action>Are new epics needed to address gaps created by this change?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.5">
+<prompt>Consider if epic order or priority should change</prompt>
+<action>Should epics be resequenced based on this issue?</action>
+<action>Do priorities need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="3" title="Artifact Conflict and Impact Analysis">
+
+<check-item id="3.1">
+<prompt>Check PRD for conflicts</prompt>
+<action>Does issue conflict with core PRD goals or objectives?</action>
+<action>Do requirements need modification, addition, or removal?</action>
+<action>Is the defined MVP still achievable or does scope need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.2">
+<prompt>Review Architecture document for conflicts</prompt>
+<action>Check each area for impact:</action>
+  - System components and their interactions
+  - Architectural patterns and design decisions
+  - Technology stack choices
+  - Data models and schemas
+  - API designs and contracts
+  - Integration points
+<action>Document specific architecture sections requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.3">
+<prompt>Examine UI/UX specifications for conflicts</prompt>
+<action>Check for impact on:</action>
+  - User interface components
+  - User flows and journeys
+  - Wireframes or mockups
+  - Interaction patterns
+  - Accessibility considerations
+<action>Note specific UI/UX sections needing revision</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.4">
+<prompt>Consider impact on other artifacts</prompt>
+<action>Review additional artifacts for impact:</action>
+  - Deployment scripts
+  - Infrastructure as Code (IaC)
+  - Monitoring and observability setup
+  - Testing strategies
+  - Documentation
+  - CI/CD pipelines
+<action>Document any secondary artifacts requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="4" title="Path Forward Evaluation">
+
+<check-item id="4.1">
+<prompt>Evaluate Option 1: Direct Adjustment</prompt>
+<action>Can the issue be addressed by modifying existing stories?</action>
+<action>Can new stories be added within the current epic structure?</action>
+<action>Would this approach maintain project timeline and scope?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.2">
+<prompt>Evaluate Option 2: Potential Rollback</prompt>
+<action>Would reverting recently completed stories simplify addressing this issue?</action>
+<action>Which stories would need to be rolled back?</action>
+<action>Is the rollback effort justified by the simplification gained?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.3">
+<prompt>Evaluate Option 3: PRD MVP Review</prompt>
+<action>Is the original PRD MVP still achievable with this issue?</action>
+<action>Does MVP scope need to be reduced or redefined?</action>
+<action>Do core goals need modification based on new constraints?</action>
+<action>What would be deferred to post-MVP if scope is reduced?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.4">
+<prompt>Select recommended path forward</prompt>
+<action>Based on analysis of all options, choose the best path</action>
+<action>Provide clear rationale considering:</action>
+  - Implementation effort and timeline impact
+  - Technical risk and complexity
+  - Impact on team morale and momentum
+  - Long-term sustainability and maintainability
+  - Stakeholder expectations and business value
+<action>Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid]</action>
+<action>Justification: [Document reasoning]</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="5" title="Sprint Change Proposal Components">
+
+<check-item id="5.1">
+<prompt>Create identified issue summary</prompt>
+<action>Write clear, concise problem statement</action>
+<action>Include context about discovery and impact</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.2">
+<prompt>Document epic impact and artifact adjustment needs</prompt>
+<action>Summarize findings from Epic Impact Assessment (Section 2)</action>
+<action>Summarize findings from Artifact Conflict Analysis (Section 3)</action>
+<action>Be specific about what changes are needed and why</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.3">
+<prompt>Present recommended path forward with rationale</prompt>
+<action>Include selected approach from Section 4</action>
+<action>Provide complete justification for recommendation</action>
+<action>Address trade-offs and alternatives considered</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.4">
+<prompt>Define PRD MVP impact and high-level action plan</prompt>
+<action>State clearly if MVP is affected</action>
+<action>Outline major action items needed for implementation</action>
+<action>Identify dependencies and sequencing</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.5">
+<prompt>Establish agent handoff plan</prompt>
+<action>Identify which roles/agents will execute the changes:</action>
+  - Development team (for implementation)
+  - Product Owner / Scrum Master (for backlog changes)
+  - Product Manager / Architect (for strategic changes)
+<action>Define responsibilities for each role</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="6" title="Final Review and Handoff">
+
+<check-item id="6.1">
+<prompt>Review checklist completion</prompt>
+<action>Verify all applicable sections have been addressed</action>
+<action>Confirm all [Action-needed] items have been documented</action>
+<action>Ensure analysis is comprehensive and actionable</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.2">
+<prompt>Verify Sprint Change Proposal accuracy</prompt>
+<action>Review complete proposal for consistency and clarity</action>
+<action>Ensure all recommendations are well-supported by analysis</action>
+<action>Check that proposal is actionable and specific</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.3">
+<prompt>Obtain explicit user approval</prompt>
+<action>Present complete proposal to user</action>
+<action>Get clear yes/no approval for proceeding</action>
+<action>Document approval and any conditions</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.4">
+<prompt>Confirm next steps and handoff plan</prompt>
+<action>Review handoff responsibilities with user</action>
+<action>Ensure all stakeholders understand their roles</action>
+<action>Confirm timeline and success criteria</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
+</halt-condition>
+
+</section>
+
+</checklist>
+
+<execution-notes>
+<note>This checklist is for SIGNIFICANT changes affecting project direction</note>
+<note>Work interactively with user - they make final decisions</note>
+<note>Be factual, not blame-oriented when analyzing issues</note>
+<note>Handle changes professionally as opportunities to improve the project</note>
+<note>Maintain conversation context throughout - this is collaborative work</note>
+</execution-notes>

.bmad/bmm/workflows/4-implementation/correct-course/instructions.md

@@ -0,0 +1,201 @@
+# Correct Course - Sprint Change Management Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/.bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</critical>
+
+<workflow>
+
+<step n="1" goal="Initialize Change Navigation">
+  <action>Confirm change trigger and gather user description of the issue</action>
+  <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
+  <action>Verify access to required project documents:</action>
+    - PRD (Product Requirements Document)
+    - Current Epics and Stories
+    - Architecture documentation
+    - UI/UX specifications
+  <action>Ask user for mode preference:</action>
+    - **Incremental** (recommended): Refine each edit collaboratively
+    - **Batch**: Present all changes at once for review
+  <action>Store mode selection for use throughout workflow</action>
+
+<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
+
+<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
+</step>
+
+<step n="2" goal="Execute Change Analysis Checklist">
+  <action>Load and execute the systematic analysis from: {checklist}</action>
+  <action>Work through each checklist section interactively with the user</action>
+  <action>Record status for each checklist item:</action>
+    - [x] Done - Item completed successfully
+    - [N/A] Skip - Item not applicable to this change
+    - [!] Action-needed - Item requires attention or follow-up
+  <action>Maintain running notes of findings and impacts discovered</action>
+  <action>Present checklist progress after each major section</action>
+
+<action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action>
+</step>
+
+<step n="3" goal="Draft Specific Change Proposals">
+<action>Based on checklist findings, create explicit edit proposals for each identified artifact</action>
+
+<action>For Story changes:</action>
+
+- Show old → new text format
+- Include story ID and section being modified
+- Provide rationale for each change
+- Example format:
+
+  ```
+  Story: [STORY-123] User Authentication
+  Section: Acceptance Criteria
+
+  OLD:
+  - User can log in with email/password
+
+  NEW:
+  - User can log in with email/password
+  - User can enable 2FA via authenticator app
+
+  Rationale: Security requirement identified during implementation
+  ```
+
+<action>For PRD modifications:</action>
+
+- Specify exact sections to update
+- Show current content and proposed changes
+- Explain impact on MVP scope and requirements
+
+<action>For Architecture changes:</action>
+
+- Identify affected components, patterns, or technology choices
+- Describe diagram updates needed
+- Note any ripple effects on other components
+
+<action>For UI/UX specification updates:</action>
+
+- Reference specific screens or components
+- Show wireframe or flow changes needed
+- Connect changes to user experience impact
+
+<check if="mode is Incremental">
+  <action>Present each edit proposal individually</action>
+  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
+  <action>Iterate on each proposal based on user feedback</action>
+</check>
+
+<action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
+
+</step>
+
+<step n="4" goal="Generate Sprint Change Proposal">
+<action>Compile comprehensive Sprint Change Proposal document with following sections:</action>
+
+<action>Section 1: Issue Summary</action>
+
+- Clear problem statement describing what triggered the change
+- Context about when/how the issue was discovered
+- Evidence or examples demonstrating the issue
+
+<action>Section 2: Impact Analysis</action>
+
+- Epic Impact: Which epics are affected and how
+- Story Impact: Current and future stories requiring changes
+- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates
+- Technical Impact: Code, infrastructure, or deployment implications
+
+<action>Section 3: Recommended Approach</action>
+
+- Present chosen path forward from checklist evaluation:
+  - Direct Adjustment: Modify/add stories within existing plan
+  - Potential Rollback: Revert completed work to simplify resolution
+  - MVP Review: Reduce scope or modify goals
+- Provide clear rationale for recommendation
+- Include effort estimate, risk assessment, and timeline impact
+
+<action>Section 4: Detailed Change Proposals</action>
+
+- Include all refined edit proposals from Step 3
+- Group by artifact type (Stories, PRD, Architecture, UI/UX)
+- Ensure each change includes before/after and justification
+
+<action>Section 5: Implementation Handoff</action>
+
+- Categorize change scope:
+  - Minor: Direct implementation by dev team
+  - Moderate: Backlog reorganization needed (PO/SM)
+  - Major: Fundamental replan required (PM/Architect)
+- Specify handoff recipients and their responsibilities
+- Define success criteria for implementation
+
+<action>Present complete Sprint Change Proposal to user</action>
+<action>Write Sprint Change Proposal document to {default_output_file}</action>
+<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
+</step>
+
+<step n="5" goal="Finalize and Route for Implementation">
+<action>Get explicit user approval for complete proposal</action>
+<ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
+
+<check if="no or revise">
+  <action>Gather specific feedback on what needs adjustment</action>
+  <action>Return to appropriate step to address concerns</action>
+  <goto step="3">If changes needed to edit proposals</goto>
+  <goto step="4">If changes needed to overall proposal structure</goto>
+
+</check>
+
+<check if="yes the proposal is approved by the user">
+  <action>Finalize Sprint Change Proposal document</action>
+  <action>Determine change scope classification:</action>
+
+- **Minor**: Can be implemented directly by development team
+- **Moderate**: Requires backlog reorganization and PO/SM coordination
+- **Major**: Needs fundamental replan with PM/Architect involvement
+
+<action>Provide appropriate handoff based on scope:</action>
+
+</check>
+
+<check if="Minor scope">
+  <action>Route to: Development team for direct implementation</action>
+  <action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
+
+<check if="Moderate scope">
+  <action>Route to: Product Owner / Scrum Master agents</action>
+  <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+</check>
+
+<check if="Major scope">
+  <action>Route to: Product Manager / Solution Architect</action>
+  <action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
+
+<action>Confirm handoff completion and next steps with user</action>
+<action>Document handoff in workflow execution log</action>
+</check>
+
+</step>
+
+<step n="6" goal="Workflow Completion">
+<action>Summarize workflow execution:</action>
+  - Issue addressed: {{change_trigger}}
+  - Change scope: {{scope_classification}}
+  - Artifacts modified: {{list_of_artifacts}}
+  - Routed to: {{handoff_recipients}}
+
+<action>Confirm all deliverables produced:</action>
+
+- Sprint Change Proposal document
+- Specific edit proposals with before/after
+- Implementation handoff plan
+
+<action>Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!"</action>
+<action>Remind user of success criteria and next steps for implementation team</action>
+</step>
+
+</workflow>

.bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -0,0 +1,43 @@
+# Correct Course - Sprint Change Management Workflow
+name: "correct-course"
+description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
+author: "BMad Method"
+
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/correct-course"
+template: false
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+checklist: "{installed_path}/checklist.md"
+default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
+
+# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
+mode: interactive
+
+required_inputs:
+  - change_trigger: "Description of the issue or change that triggered this workflow"
+  - project_documents: "Access to PRD, Epics/Stories, Architecture, UI/UX specs"
+
+output_artifacts:
+  - sprint_change_proposal: "Comprehensive proposal documenting issue, impact, and recommended changes"
+  - artifact_edits: "Specific before/after edits for affected documents"
+  - handoff_plan: "Clear routing for implementation based on change scope"
+
+halt_conditions:
+  - "Change trigger unclear or undefined"
+  - "Core project documents unavailable"
+  - "Impact analysis incomplete"
+  - "User approval not obtained"
+
+execution_modes:
+  - incremental: "Recommended - Refine each edit with user collaboration"
+  - batch: "Present all changes at once for review"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/create-story/checklist.md

@@ -0,0 +1,240 @@
+# Create Story Quality Validation Checklist
+
+```xml
+<critical>This validation runs in a FRESH CONTEXT by an independent validator agent</critical>
+<critical>The validator audits story quality and offers to improve if issues are found</critical>
+<critical>Load only the story file and necessary source documents - do NOT load workflow instructions</critical>
+
+<validation-checklist>
+
+<expectations>
+**What create-story workflow should have accomplished:**
+
+1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items
+2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md)
+3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented
+4. **Dev Notes Quality:** Specific guidance with citations, not generic advice
+5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present
+6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized
+</expectations>
+
+## Validation Steps
+
+### 1. Load Story and Extract Metadata
+- [ ] Load story file: {{story_file_path}}
+- [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log
+- [ ] Extract: epic_num, story_num, story_key, story_title
+- [ ] Initialize issue tracker (Critical/Major/Minor)
+
+### 2. Previous Story Continuity Check
+
+**Find previous story:**
+- [ ] Load {output_folder}/sprint-status.yaml
+- [ ] Find current {{story_key}} in development_status
+- [ ] Identify story entry immediately above (previous story)
+- [ ] Check previous story status
+
+**If previous story status is done/review/in-progress:**
+- [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md
+- [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED)
+- [ ] Extract: Senior Developer Review section if present
+- [ ] Count unchecked [ ] items in Review Action Items
+- [ ] Count unchecked [ ] items in Review Follow-ups (AI)
+
+**Validate current story captured continuity:**
+- [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes
+  - If MISSING and previous story has content → **CRITICAL ISSUE**
+- [ ] If subsection exists, verify it includes:
+  - [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE**
+  - [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE**
+  - [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE**
+  - [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md]
+
+**If previous story status is backlog/drafted:**
+- [ ] No continuity expected (note this)
+
+**If no previous story exists:**
+- [ ] First story in epic, no continuity expected
+
+### 3. Source Document Coverage Check
+
+**Build available docs list:**
+- [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir}
+- [ ] Check exists: {output_folder}/epics.md
+- [ ] Check exists: {output_folder}/PRD.md
+- [ ] Check exists in {output_folder}/ or {project-root}/docs/:
+  - architecture.md, testing-strategy.md, coding-standards.md
+  - unified-project-structure.md, tech-stack.md
+  - backend-architecture.md, frontend-architecture.md, data-models.md
+
+**Validate story references available docs:**
+- [ ] Extract all [Source: ...] citations from story Dev Notes
+- [ ] Tech spec exists but not cited → **CRITICAL ISSUE**
+- [ ] Epics exists but not cited → **CRITICAL ISSUE**
+- [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE**
+- [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE**
+- [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE**
+- [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE**
+
+**Validate citation quality:**
+- [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE**
+- [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE**
+
+### 4. Acceptance Criteria Quality Check
+
+- [ ] Extract Acceptance Criteria from story
+- [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt)
+- [ ] Check story indicates AC source (tech spec, epics, PRD)
+
+**If tech spec exists:**
+- [ ] Load tech spec
+- [ ] Search for this story number
+- [ ] Extract tech spec ACs for this story
+- [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE**
+
+**If no tech spec but epics.md exists:**
+- [ ] Load epics.md
+- [ ] Search for Epic {{epic_num}}, Story {{story_num}}
+- [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted)
+- [ ] Extract epics ACs
+- [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE**
+
+**Validate AC quality:**
+- [ ] Each AC is testable (measurable outcome)
+- [ ] Each AC is specific (not vague)
+- [ ] Each AC is atomic (single concern)
+- [ ] Vague ACs found → **MINOR ISSUE**
+
+### 5. Task-AC Mapping Check
+
+- [ ] Extract Tasks/Subtasks from story
+- [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference
+  - [ ] AC has no tasks → **MAJOR ISSUE**
+- [ ] For each task: Check if references an AC number
+  - [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE**
+- [ ] Count tasks with testing subtasks
+  - [ ] Testing subtasks < ac_count → **MAJOR ISSUE**
+
+### 6. Dev Notes Quality Check
+
+**Check required subsections exist:**
+- [ ] Architecture patterns and constraints
+- [ ] References (with citations)
+- [ ] Project Structure Notes (if unified-project-structure.md exists)
+- [ ] Learnings from Previous Story (if previous story has content)
+- [ ] Missing required subsections → **MAJOR ISSUE**
+
+**Validate content quality:**
+- [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE**
+- [ ] Count citations in References subsection
+  - [ ] No citations → **MAJOR ISSUE**
+  - [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE**
+- [ ] Scan for suspicious specifics without citations:
+  - API endpoints, schema details, business rules, tech choices
+  - [ ] Likely invented details found → **MAJOR ISSUE**
+
+### 7. Story Structure Check
+
+- [ ] Status = "drafted" → If not → **MAJOR ISSUE**
+- [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE**
+- [ ] Dev Agent Record has required sections:
+  - Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List
+  - [ ] Missing sections → **MAJOR ISSUE**
+- [ ] Change Log initialized → If missing → **MINOR ISSUE**
+- [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE**
+
+### 8. Unresolved Review Items Alert
+
+**CRITICAL CHECK for incomplete review items from previous story:**
+
+- [ ] If previous story has "Senior Developer Review (AI)" section:
+  - [ ] Count unchecked [ ] items in "Action Items"
+  - [ ] Count unchecked [ ] items in "Review Follow-ups (AI)"
+  - [ ] If unchecked items > 0:
+    - [ ] Check current story "Learnings from Previous Story" mentions these
+    - [ ] If NOT mentioned → **CRITICAL ISSUE** with details:
+      - List all unchecked items with severity
+      - Note: "These may represent epic-wide concerns"
+      - Required: Add to Learnings section with note about pending items
+
+## Validation Report Generation
+
+**Calculate severity counts:**
+- Critical: {{critical_count}}
+- Major: {{major_count}}
+- Minor: {{minor_count}}
+
+**Determine outcome:**
+- Critical > 0 OR Major > 3 → **FAIL**
+- Major ≤ 3 and Critical = 0 → **PASS with issues**
+- All = 0 → **PASS**
+
+**Generate report:**
+```
+
+# Story Quality Validation Report
+
+Story: {{story_key}} - {{story_title}}
+Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
+
+## Critical Issues (Blockers)
+
+{{list_each_with_description_and_evidence}}
+
+## Major Issues (Should Fix)
+
+{{list_each_with_description_and_evidence}}
+
+## Minor Issues (Nice to Have)
+
+{{list_each_with_description}}
+
+## Successes
+
+{{list_what_was_done_well}}
+
+```
+
+## User Alert and Remediation
+
+**If FAIL:**
+- Show issues summary and top 3 issues
+- Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is
+- If option 1: Re-load source docs, regenerate affected sections, re-run validation
+
+**If PASS with issues:**
+- Show issues list
+- Ask: "Improve story? (y/n)"
+- If yes: Enhance story with missing items
+
+**If PASS:**
+- Confirm: All quality standards met
+- List successes
+- Ready for story-context generation
+
+</validation-checklist>
+```
+
+## Quick Reference
+
+**Validation runs in fresh context and checks:**
+
+1. ✅ Previous story continuity captured (files, notes, **unresolved review items**)
+2. ✅ All relevant source docs discovered and cited
+3. ✅ ACs match tech spec/epics exactly
+4. ✅ Tasks cover all ACs with testing
+5. ✅ Dev Notes have specific guidance with citations (not generic)
+6. ✅ Structure and metadata complete
+
+**Severity Levels:**
+
+- **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics
+- **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks
+- **MINOR** = Vague citations, orphan tasks, missing Change Log
+
+**Outcome Triggers:**
+
+- **FAIL** = Any critical OR >3 major issues
+- **PASS with issues** = ≤3 major issues, no critical
+- **PASS** = All checks passed

.bmad/bmm/workflows/4-implementation/create-story/instructions.md

@@ -0,0 +1,283 @@
+# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
+
+````xml
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
+<critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
+
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+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 structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+
+<workflow>
+
+  <step n="1" goal="Load config and initialize">
+    <action>Resolve variables from config_source: story_dir (dev_ephemeral_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, architecture_file</action>
+  </step>
+
+  <step n="2" goal="Discover and load source documents">
+    <critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
+
+    <action>Find the previous completed story to extract dev agent learnings and review findings:
+      1. Load {{output_folder}}/sprint-status.yaml COMPLETELY
+      2. Find current {{story_key}} in development_status section
+      3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order)
+      4. If previous story exists:
+         - Extract {{previous_story_key}}
+         - Check previous story status (done, in-progress, review, etc.)
+         - If status is "done", "review", or "in-progress" (has some completion):
+           * Construct path: {{story_dir}}/{{previous_story_key}}.md
+           * Load the COMPLETE previous story file
+           * Parse ALL sections comprehensively:
+
+             A) Dev Agent Record → Completion Notes List:
+                - New patterns/services created (to reuse, not recreate)
+                - Architectural deviations or decisions made
+                - Technical debt deferred to future stories
+                - Warnings or recommendations for next story
+                - Interfaces/methods created for reuse
+
+             B) Dev Agent Record → Debug Log References:
+                - Issues encountered and solutions
+                - Gotchas or unexpected challenges
+                - Workarounds applied
+
+             C) Dev Agent Record → File List:
+                - Files created (NEW) - understand new capabilities
+                - Files modified (MODIFIED) - track evolving components
+                - Files deleted (DELETED) - removed functionality
+
+             D) Dev Notes:
+                - Any "future story" notes or TODOs
+                - Patterns established
+                - Constraints discovered
+
+             E) Senior Developer Review (AI) section (if present):
+                - Review outcome (Approve/Changes Requested/Blocked)
+                - Unresolved action items (unchecked [ ] items)
+                - Key findings that might affect this story
+                - Architectural concerns raised
+
+             F) Senior Developer Review → Action Items (if present):
+                - Check for unchecked [ ] items still pending
+                - Note any systemic issues that apply to multiple stories
+
+             G) Review Follow-ups (AI) tasks (if present):
+                - Check for unchecked [ ] review tasks still pending
+                - Determine if they're epic-wide concerns
+
+             H) Story Status:
+                - If "review" or "in-progress" - incomplete, note what's pending
+                - If "done" - confirmed complete
+           * Store ALL findings as {{previous_story_learnings}} with structure:
+             - new_files: [list]
+             - modified_files: [list]
+             - new_services: [list with descriptions]
+             - architectural_decisions: [list]
+             - technical_debt: [list]
+             - warnings_for_next: [list]
+             - review_findings: [list if review exists]
+             - pending_items: [list of unchecked action items]
+         - If status is "backlog" or "drafted":
+           * Set {{previous_story_learnings}} = "Previous story not yet implemented"
+      5. If no previous story exists (first story in epic):
+         - Set {{previous_story_learnings}} = "First story in epic - no predecessor context"
+    </action>
+
+    <action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
+    <action>Build a prioritized document set for this epic:
+      1) tech_spec_file (epic-scoped)
+      2) epics_file (acceptance criteria and breakdown)
+      3) prd_file (business requirements and constraints)
+      4) 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>
+  </step>
+
+  <step n="3" goal="Find next backlog story to draft" tag="sprint-status">
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
+
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "backlog"
+    </action>
+
+    <check if="no backlog story found">
+      <output>📋 No backlog stories found in sprint-status.yaml
+
+All stories are either already drafted or completed.
+
+**Options:**
+1. Run sprint-planning to refresh story tracking
+2. Load PM agent and run correct-course to add more stories
+3. Check if current sprint is complete
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Extract from found story key (e.g., "1-2-user-authentication"):
+      - epic_num: first number before dash (e.g., "1")
+      - story_num: second number after first dash (e.g., "2")
+      - story_title: remainder after second dash (e.g., "user-authentication")
+    </action>
+    <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+    <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+    <action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
+    <action>"Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
+
+    <action>Check if story file already exists at expected path in {{story_dir}}</action>
+    <check if="story file exists">
+      <output>ℹ️ Story file already exists: {{story_file_path}}
+
+Will update existing story file rather than creating new one.
+      </output>
+      <action>Set update_mode = true</action>
+    </check>
+  </step>
+
+  <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 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>
+
+  <step n="5" goal="Project structure alignment and lessons learned">
+    <action>Review {{previous_story_learnings}} and extract actionable intelligence:
+      - New patterns/services created → Note for reuse (DO NOT recreate)
+      - Architectural deviations → Understand and maintain consistency
+      - Technical debt items → Assess if this story should address them
+      - Files modified → Understand current state of evolving components
+      - Warnings/recommendations → Apply to this story's approach
+      - Review findings → Learn from issues found in previous story
+      - Pending action items → Determine if epic-wide concerns affect this story
+    </action>
+
+    <action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
+
+    <action>Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located.</action>
+
+    <template-output file="{default_output_file}">structure_alignment_summary</template-output>
+  </step>
+
+  <step n="6" goal="Assemble acceptance criteria and tasks">
+    <action>Assemble acceptance criteria list from tech_spec or epics. If gaps exist, derive minimal, testable criteria from PRD verbatim phrasing (NO invention).</action>
+    <action>Create tasks/subtasks directly mapped to ACs. Include explicit testing subtasks per testing-strategy and existing tests framework. Cite architecture/source documents for any technical mandates.</action>
+    <template-output file="{default_output_file}">acceptance_criteria</template-output>
+    <template-output file="{default_output_file}">tasks_subtasks</template-output>
+  </step>
+
+  <step n="7" goal="Create or update story document">
+    <action>Resolve output path: {default_output_file} using current {{epic_num}} and {{story_num}}. If targeting an existing story for update, use its path.</action>
+    <action>Initialize from template.md if creating a new file; otherwise load existing file for edit.</action>
+    <action>Compute a concise story_title from epic/story context; if missing, synthesize from PRD feature name and epic number.</action>
+    <template-output file="{default_output_file}">story_header</template-output>
+    <template-output file="{default_output_file}">story_body</template-output>
+    <template-output file="{default_output_file}">dev_notes_with_citations</template-output>
+
+    <action>If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"):
+      - Add "Learnings from Previous Story" subsection to Dev Notes
+      - Include relevant completion notes, new files/patterns, deviations
+      - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md]
+      - Highlight interfaces/services to REUSE (not recreate)
+      - Note any technical debt to address in this story
+      - List pending review items that affect this story (if any)
+      - Reference specific files created: "Use {{file_path}} for {{purpose}}"
+      - Format example:
+        ```
+        ### Learnings from Previous Story
+
+        **From Story {{previous_story_key}} (Status: {{previous_status}})**
+
+        - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method
+        - **Architectural Change**: Switched from session-based to JWT authentication
+        - **Schema Changes**: User model now includes `passwordHash` field, migration applied
+        - **Technical Debt**: Email verification skipped, should be included in this or subsequent story
+        - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there
+        - **Pending Review Items**: Rate limiting mentioned in review - consider for this story
+
+        [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record]
+        ```
+    </action>
+
+    <template-output file="{default_output_file}">change_log</template-output>
+  </step>
+
+  <step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using .bmad/core/tasks/validate-workflow.xml</invoke-task>
+    <action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
+
+    <!-- Mark story as drafted in sprint status -->
+    <action>Update {{output_folder}}/sprint-status.yaml</action>
+    <action>Load the FULL file and read all development_status entries</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "drafted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
+
+Story file was created successfully, but sprint-status.yaml was not updated.
+You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`.
+      </output>
+    </check>
+
+    <action>Report created/updated story path</action>
+    <output>**✅ Story Created Successfully, {user_name}!**
+
+**Story Details:**
+
+- Story ID: {{story_id}}
+- Story Key: {{story_key}}
+- File: {{story_file}}
+- Status: drafted (was backlog)
+
+**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
+
+**Next Steps:**
+
+1. Review the drafted story in {{story_file}}
+2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
+3. Or run `story-ready` to manually mark the story ready without generating technical context
+    </output>
+  </step>
+
+</workflow>
+````

.bmad/bmm/workflows/4-implementation/create-story/template.md

@@ -0,0 +1,51 @@
+# Story {{epic_num}}.{{story_num}}: {{story_title}}
+
+Status: drafted
+
+## Story
+
+As a {{role}},
+I want {{action}},
+so that {{benefit}}.
+
+## Acceptance Criteria
+
+1. [Add acceptance criteria from epics/PRD]
+
+## Tasks / Subtasks
+
+- [ ] Task 1 (AC: #)
+  - [ ] Subtask 1.1
+- [ ] Task 2 (AC: #)
+  - [ ] Subtask 2.1
+
+## Dev Notes
+
+- Relevant architecture patterns and constraints
+- Source tree components to touch
+- Testing standards summary
+
+### Project Structure Notes
+
+- Alignment with unified project structure (paths, modules, naming)
+- Detected conflicts or variances (with rationale)
+
+### References
+
+- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
+
+## Dev Agent Record
+
+### Context Reference
+
+<!-- Path(s) to story context XML will be added here by context workflow -->
+
+### Agent Model Used
+
+{{agent_model_name_version}}
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

.bmad/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -0,0 +1,74 @@
+name: create-story
+description: "Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/create-story"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  story_dir: "{config_source}:dev_ephemeral_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
+  architecture_file: "{output_folder}/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: |
+    - architecture.md
+    - infrastructure-architecture.md
+  story_title: "" # Will be elicited if not derivable
+  epic_num: 1
+  story_num: 1
+  non_interactive: true # Generate without elicitation; avoid interactive prompts
+
+# Output configuration
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.md"
+
+recommended_inputs:
+  - epics: "Epic breakdown (epics.md)"
+  - prd: "PRD document"
+  - architecture: "Architecture (optional)"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/tech-spec.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md

@@ -0,0 +1,367 @@
+# Workflow Audit Report
+
+**Workflow:** dev-story
+**Audit Date:** 2025-10-25
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** Action Workflow
+**Module:** BMM (BMad Method)
+
+---
+
+## Executive Summary
+
+**Overall Status:** GOOD - Minor issues to address
+
+- Critical Issues: 0
+- Important Issues: 3
+- Cleanup Recommendations: 2
+
+The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
+
+---
+
+## 1. Standard Config Block Validation
+
+**Status:** PASS ✓
+
+The workflow.yaml contains all required standard config variables:
+
+- ✓ `config_source: "{project-root}/.bmad/bmm/config.yaml"` - Correctly defined
+- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
+- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
+- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
+- ✓ `date: system-generated` - Correctly set
+
+All standard config variables are present and properly formatted using {project-root} variable syntax.
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+**Variables Analyzed:** 9 (excluding standard config)
+**Used in Instructions:** 6
+**Unused (Bloat):** 3
+
+### YAML Variables Defined
+
+1. `story_dir` - USED in instructions (file paths)
+2. `context_path` - UNUSED (appears to duplicate story_dir)
+3. `story_file` - USED in instructions
+4. `context_file` - USED in instructions
+5. `installed_path` - USED in instructions (workflow.xml reference)
+6. `instructions` - USED in instructions (self-reference in critical tag)
+7. `validation` - USED in instructions (checklist reference)
+8. `web_bundle` - CONFIGURATION (correctly set to false)
+9. `date` - USED in instructions (config variable)
+
+### Variables Used in Instructions But NOT Defined in YAML
+
+**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
+
+1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
+2. `{document_output_language}` - Used 1 time (line 7)
+3. `{run_until_complete}` - Used 1 time (line 108)
+4. `{run_tests_command}` - Used 1 time (line 120)
+
+These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
+
+### Unused Variables (Bloat)
+
+1. **context_path** - Defined as `"{config_source}:dev_ephemeral_location"` but never used. This duplicates `story_dir` functionality.
+
+---
+
+## 3. Config Variable Usage
+
+**Communication Language:** PASS ✓
+**User Name:** PASS ✓
+**Output Folder:** PASS ✓
+**Date:** PASS ✓
+
+### Detailed Analysis
+
+**Communication Language:**
+
+- ✓ Used in line 6: "Communicate all responses in {communication_language}"
+- ✓ Properly used as agent instruction variable (not in template)
+
+**User Name:**
+
+- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
+- ✓ Appropriately used for personalization
+
+**Output Folder:**
+
+- ✓ Used multiple times for sprint-status.yaml file paths
+- ✓ All file operations target {output_folder} correctly
+- ✓ No hardcoded paths detected
+
+**Date:**
+
+- ✓ Available for agent use (system-generated)
+- ✓ Used appropriately in context of workflow execution
+
+### Additional Config Variables
+
+**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
+
+1. `{user_skill_level}` - Used to tailor communication style
+2. `{document_output_language}` - Used for document generation
+3. `{run_until_complete}` - Used for execution control
+4. `{run_tests_command}` - Used for test execution
+
+These should either be:
+
+- Added to workflow.yaml with proper config_source references, OR
+- Documented as optional config variables with defaults
+
+---
+
+## 4. Web Bundle Validation
+
+**Web Bundle Present:** No (Intentional)
+**Status:** EXPECTED ✓
+
+The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
+
+- Run locally in the development environment
+- Don't need to be bundled for web deployment
+- Are IDE-integrated workflows
+
+**No issues found** - This is the correct configuration for dev-story.
+
+---
+
+## 5. Bloat Detection
+
+**Bloat Percentage:** 11% (1 unused field / 9 total fields)
+**Cleanup Potential:** Low
+
+### Unused YAML Fields
+
+1. **context_path** (line 11 in workflow.yaml)
+   - Defined as: `"{config_source}:dev_ephemeral_location"`
+   - Never referenced in instructions.md
+   - Duplicates functionality of `story_dir` variable
+   - **Recommendation:** Remove this variable as `story_dir` serves the same purpose
+
+### Hardcoded Values
+
+No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
+
+- File paths ({output_folder}, {story_dir})
+- User personalization ({user_name})
+- Communication style ({communication_language}, {user_skill_level})
+
+### Calculation
+
+- Total yaml fields: 9 (excluding standard config and metadata)
+- Used fields: 8
+- Unused fields: 1 (context_path)
+- Bloat percentage: 11%
+
+**Status:** Acceptable (under 15% threshold)
+
+---
+
+## 6. Template Variable Mapping
+
+**Not Applicable** - This is an action workflow, not a document workflow.
+
+No template.md file exists, which is correct for action-type workflows.
+
+---
+
+## 7. Instructions Quality Analysis
+
+### Structure
+
+- ✓ Steps numbered sequentially (1, 1.5, 2-7)
+- ✓ Each step has clear goal attributes
+- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
+- ✓ Logical flow control with anchors and conditional checks
+- ✓ Repeat patterns used appropriately (step 2-5 loop)
+
+### Critical Tags
+
+- ✓ Critical blocks present and well-defined
+- ✓ Clear references to workflow execution engine
+- ✓ Workflow.yaml load requirement specified
+- ✓ Communication preferences documented
+
+### Variable Usage Consistency
+
+**ISSUE:** Inconsistent variable syntax found:
+
+1. Lines 4, 5 use `{project_root}` (underscore)
+2. Line 166 uses `{project-root}` (hyphen)
+
+**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
+
+### Step Quality
+
+**Excellent:**
+
+- Steps are focused and single-purpose
+- Clear HALT conditions defined
+- Comprehensive validation checks
+- Good error handling patterns
+- Iterative execution model well-structured
+
+**Areas for improvement:**
+
+- Step 1 is complex and could potentially be split
+- Some <action if="..."> conditionals could be clearer with <check> blocks
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+None - No critical issues detected.
+
+### Important (Address Soon)
+
+1. **Document or Define Missing Variables**
+   - Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
+   - OR document these as optional config variables with defaults
+   - These variables are used in instructions but not defined in YAML
+   - **Impact:** Reduces clarity and may cause confusion about variable sources
+
+2. **Standardize project-root Variable Syntax**
+   - Change line 4 `{project_root}` to `{project-root}` (hyphen)
+   - Ensure consistency with BMAD v6 standard naming convention
+   - **Impact:** Maintains consistency with framework standards
+
+3. **Remove or Use context_path Variable**
+   - Variable `context_path` is defined but never used
+   - Since `story_dir` serves the same purpose, remove `context_path`
+   - OR if there's a semantic difference, document why both exist
+   - **Impact:** Reduces bloat and potential confusion
+
+### Cleanup (Nice to Have)
+
+1. **Consider Splitting Step 1**
+   - Step 1 handles both story discovery AND file loading
+   - Could be split into "1. Find Story" and "2. Load Story Files"
+   - Would improve clarity and maintainability
+   - **Impact:** Minor improvement to workflow structure
+
+2. **Add Variable Documentation Comment**
+   - Add a comment block in workflow.yaml listing all variables used by this workflow
+   - Include both explicit YAML variables and config-pulled variables
+   - Example format:
+     ```yaml
+     # Workflow-specific variables
+     # - story_file: Path to story markdown
+     # - story_dir: Directory containing stories
+     #
+     # Config-pulled variables (from bmm/config.yaml)
+     # - user_skill_level: User's technical skill level
+     # - document_output_language: Language for generated docs
+     ```
+   - **Impact:** Improves developer understanding and maintenance
+
+---
+
+## Validation Checklist
+
+### Structure ✓
+
+- [x] workflow.yaml loads without YAML syntax errors
+- [x] instructions.md exists and is properly formatted
+- [x] No template.md (correct for action workflow)
+- [x] All critical headers present in instructions
+- [x] Workflow type correctly identified (action)
+- [x] All referenced files exist
+- [x] No placeholder text remains
+
+### Standard Config Block ✓
+
+- [x] config_source points to correct module config
+- [x] output_folder pulls from config_source
+- [x] user_name pulls from config_source
+- [x] communication_language pulls from config_source
+- [x] date is system-generated
+- [x] Config source uses {project-root} variable
+- [x] Standard config comment present
+
+### Config Variable Usage ✓
+
+- [x] Instructions communicate in {communication_language}
+- [x] Instructions address {user_name}
+- [x] All file outputs use {output_folder}
+- [x] No hardcoded paths
+- [x] Date available for agent awareness
+
+### YAML/Instruction/Template Alignment ⚠️
+
+- [⚠️] Some variables used in instructions not defined in YAML
+- [x] Template variables N/A (action workflow)
+- [x] Variable names are descriptive
+- [⚠️] One unused yaml field (context_path)
+
+### Web Bundle Validation ✓
+
+- [x] web_bundle: false is correct for this workflow
+- [x] No web_bundle section needed
+- [x] Workflow is local/IDE-integrated only
+
+### Instructions Quality ✓
+
+- [x] Steps numbered sequentially
+- [x] Clear goal attributes
+- [x] Proper XML tag usage
+- [x] Logical flow control
+- [⚠️] Minor inconsistency: {project_root} vs {project-root}
+
+### Bloat Detection ✓
+
+- [x] Bloat percentage: 11% (acceptable, under 15%)
+- [x] No significant hardcoded values
+- [x] No redundant configuration
+- [x] One cleanup recommendation (context_path)
+
+---
+
+## Next Steps
+
+1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
+2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
+3. **Remove context_path** - Clean up unused variable
+4. **Re-run audit** - Verify improvements after fixes
+
+---
+
+## Additional Notes
+
+### Strengths
+
+1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
+2. **Config Integration:** Excellent use of config variables for user personalization and output management
+3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
+4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
+5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
+
+### Workflow Purpose
+
+This workflow executes user stories by:
+
+- Finding ready-for-dev stories from sprint status
+- Implementing tasks and subtasks incrementally
+- Writing comprehensive tests
+- Validating against acceptance criteria
+- Updating story status through sprint lifecycle
+- Supporting different user skill levels with adaptive communication
+
+The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
+
+**Pass Rate:** 89% (62 passed / 70 total checks)
+**Recommendation:** Good - Minor fixes needed
+
+The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.

.bmad/bmm/workflows/4-implementation/dev-story/checklist.md

@@ -0,0 +1,38 @@
+---
+title: 'Dev Story Completion Checklist'
+validation-target: 'Story markdown ({{story_path}})'
+required-inputs:
+  - 'Story markdown file with Tasks/Subtasks, Acceptance Criteria'
+optional-inputs:
+  - 'Test results output (if saved)'
+  - 'CI logs (if applicable)'
+validation-rules:
+  - 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status'
+---
+
+# Dev Story Completion Checklist
+
+## Tasks Completion
+
+- [ ] All tasks and subtasks for this story are marked complete with [x]
+- [ ] Implementation aligns with every Acceptance Criterion in the story
+
+## Tests and Quality
+
+- [ ] Unit tests added/updated for core functionality changed by this story
+- [ ] Integration tests added/updated when component interactions are affected
+- [ ] End-to-end tests created for critical user flows, if applicable
+- [ ] All tests pass locally (no regressions introduced)
+- [ ] Linting and static checks (if configured) pass
+
+## Story File Updates
+
+- [ ] File List section includes every new/modified/deleted file (paths relative to repo root)
+- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work
+- [ ] Change Log includes a brief summary of what changed
+- [ ] Only permitted sections of the story file were modified
+
+## Final Status
+
+- [ ] Regression suite executed successfully
+- [ ] Story Status is set to "Ready for Review"

.bmad/bmm/workflows/4-implementation/dev-story/instructions.md

@@ -0,0 +1,262 @@
+# Develop Story - Workflow Instructions
+
+```xml
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status</critical>
+<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical>
+<critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
+
+<critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
+
+<workflow>
+
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto>task_check</goto>
+    </check>
+
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
+
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "ready-for-dev"
+    </action>
+
+    <check if="no ready-for-dev or in-progress story found">
+      <output>📋 No ready-for-dev stories found in sprint-status.yaml
+**Options:**
+1. Run `story-context` to generate context file and mark drafted stories as ready
+2. Run `story-ready` to quickly mark drafted stories as ready without generating context
+3. Run `create-story` if no incomplete stories are drafted yet
+4. Check {output-folder}/sprint-status.yaml to see current sprint status
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md</action>
+    <action>Read COMPLETE story file from discovered path</action>
+
+    <anchor id="task_check" />
+
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
+    <check if="context file exists">
+      <action>Read COMPLETE context file</action>
+      <action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
+      <action>Use this context to inform implementation decisions and approaches</action>
+    </check>
+    <check if="context file does NOT exist">
+      <output>ℹ️ No context file found for {{story_key}}
+
+Proceeding with story file only. For better context, consider running `story-context` workflow first.
+      </output>
+    </check>
+
+    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
+
+    <action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
+  </step>
+
+  <step n="1.5" goal="Detect review continuation and extract review context">
+    <critical>Determine if this is a fresh start or continuation after code review</critical>
+
+    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
+    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
+
+    <check if="Senior Developer Review section exists">
+      <action>Set review_continuation = true</action>
+      <action>Extract from "Senior Developer Review (AI)" section:
+        - Review outcome (Approve/Changes Requested/Blocked)
+        - Review date
+        - Total action items with checkboxes (count checked vs unchecked)
+        - Severity breakdown (High/Med/Low counts)
+      </action>
+      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
+      <action>Store list of unchecked review items as {{pending_review_items}}</action>
+
+      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
+
+**Review Outcome:** {{review_outcome}}
+**Action Items:** {{unchecked_review_count}} remaining to address
+**Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
+
+**Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
+      </output>
+    </check>
+
+    <check if="Senior Developer Review section does NOT exist">
+      <action>Set review_continuation = false</action>
+      <action>Set {{pending_review_items}} = empty</action>
+
+      <output>🚀 **Starting Fresh Implementation**
+
+Story: {{story_key}}
+Context file: {{context_available}}
+First incomplete task: {{first_task_description}}
+      </output>
+    </check>
+  </step>
+
+  <step n="1.6" goal="Mark story in-progress" tag="sprint-status">
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read all development_status entries to find {{story_key}}</action>
+    <action>Get current status value for development_status[{{story_key}}]</action>
+
+    <check if="current status == 'ready-for-dev'">
+      <action>Update the story in the sprint status report to = "in-progress"</action>
+      <output>🚀 Starting work on story {{story_key}}
+Status updated: ready-for-dev → in-progress
+      </output>
+    </check>
+
+    <check if="current status == 'in-progress'">
+      <output>⏯️ Resuming work on story {{story_key}}
+Story is already marked in-progress
+      </output>
+    </check>
+
+    <check if="current status is neither ready-for-dev nor in-progress">
+      <output>⚠️ Unexpected story status: {{current_status}}
+Expected ready-for-dev or in-progress. Continuing anyway...
+      </output>
+    </check>
+  </step>
+
+  <step n="2" goal="Plan and implement task">
+    <action>Review acceptance criteria and dev notes for the selected task</action>
+    <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
+    <action>Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions</action>
+    <action>Handle error conditions and edge cases appropriately</action>
+    <action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
+    <critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
+    <critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
+  </step>
+
+  <step n="3" goal="Author comprehensive tests">
+    <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
+    <action>Add integration tests for component interactions where desired by test plan or story notes</action>
+    <action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
+    <action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
+  </step>
+
+  <step n="4" goal="Run validations and tests">
+    <action>Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided)</action>
+    <action>Run all existing tests to ensure no regressions</action>
+    <action>Run the new tests to verify implementation correctness</action>
+    <action>Run linting and code quality checks if configured</action>
+    <action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
+    <action if="regression tests fail">STOP and fix before continuing, consider how current changes made broke regression</action>
+    <action if="new tests fail">STOP and fix before continuing</action>
+  </step>
+
+  <step n="5" goal="Mark task complete, track review resolutions, and update story">
+    <critical>If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section</critical>
+
+    <action>Check if completed task has [AI-Review] prefix (indicates review follow-up task)</action>
+
+    <check if="task is review follow-up">
+      <action>Extract review item details (severity, description, related AC/file)</action>
+      <action>Add to resolution tracking list: {{resolved_review_items}}</action>
+
+      <!-- Mark task in Review Follow-ups section -->
+      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
+
+      <!-- CRITICAL: Also mark corresponding action item in review section -->
+      <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
+      <action>Mark that action item checkbox [x] as resolved</action>
+
+      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
+    </check>
+
+    <action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
+    <action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
+    <action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
+
+    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
+      <action>Count total resolved review items in this session</action>
+      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
+    </check>
+
+    <action>Save the story file</action>
+    <action>Determine if more incomplete tasks remain</action>
+    <action if="more tasks remain"><goto step="2">Next task</goto></action>
+    <action if="no tasks remain"><goto step="6">Completion</goto></action>
+  </step>
+
+  <step n="6" goal="Story completion and mark for review" tag="sprint-status">
+    <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
+    <action>Run the full regression suite (do not skip)</action>
+    <action>Confirm File List includes every changed file</action>
+    <action>Execute story definition-of-done checklist, if the story includes one</action>
+    <action>Update the story Status to: review</action>
+
+    <!-- Mark story ready for review -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "in-progress" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "review"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+
+Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+
+    <action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
+    <action if="regression failures exist">STOP and resolve before completing</action>
+    <action if="File List is incomplete">Update it before completing</action>
+  </step>
+
+  <step n="7" goal="Completion communication and user support">
+    <action>Optionally run the workflow validation task against the story using {project-root}/.bmad/core/tasks/validate-workflow.xml</action>
+    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
+
+    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
+    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
+    <action>Provide the story file path and current status (now "review", was "in-progress")</action>
+
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>Common next steps to suggest (but allow user flexibility):
+      - Review the implemented story yourself and test the changes
+      - Verify all acceptance criteria are met
+      - Ensure deployment readiness if applicable
+      - Run `code-review` workflow for peer review
+      - Check sprint-status.yaml to see project progress
+    </action>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
+  </step>
+
+</workflow>
+```

.bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -0,0 +1,26 @@
+name: dev-story
+description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+story_dir: "{config_source}:dev_ephemeral_location"
+run_until_complete: "{config_source}:run_until_complete"
+run_tests_command: "{config_source}:run_tests_command"
+date: system-generated
+
+story_file: "" # Explicit story path; auto-discovered if empty
+# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
+context_file: "{story_dir}/{{story_key}}.context.xml"
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/dev-story"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md

@@ -0,0 +1,17 @@
+# Tech Spec Validation Checklist
+
+```xml
+<checklist id=".bmad/bmm/workflows/4-implementation/epic-tech-context/checklist">
+  <item>Overview clearly ties to PRD goals</item>
+  <item>Scope explicitly lists in-scope and out-of-scope</item>
+  <item>Design lists all services/modules with responsibilities</item>
+  <item>Data models include entities, fields, and relationships</item>
+  <item>APIs/interfaces are specified with methods and schemas</item>
+  <item>NFRs: performance, security, reliability, observability addressed</item>
+  <item>Dependencies/integrations enumerated with versions where known</item>
+  <item>Acceptance criteria are atomic and testable</item>
+  <item>Traceability maps AC → Spec → Components → Tests</item>
+  <item>Risks/assumptions/questions listed with mitigation/next steps</item>
+  <item>Test strategy covers all ACs and critical paths</item>
+</checklist>
+```

.bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -0,0 +1,189 @@
+<!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
+
+```xml
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+<critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
+<critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
+
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from workflow context or user input)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+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 structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories.
+
+<workflow>
+  <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
+    <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
+    <ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
+
+    <!-- Intelligent Epic Discovery -->
+    <critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL development_status entries</action>
+    <action>Find all epics with status "backlog" (not yet contexted)</action>
+    <action>Identify the FIRST backlog epic as the suggested default</action>
+
+    <check if="backlog epics found">
+      <output>📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}}</output>
+      <ask>Use this epic?
+- [y] Yes, use {{suggested_epic_id}}
+- [n] No, let me specify a different epic_id
+      </ask>
+
+      <check if="user selects 'n'">
+        <ask>Enter the epic_id you want to context</ask>
+        <action>Store user-provided epic_id as {{epic_id}}</action>
+      </check>
+
+      <check if="user selects 'y'">
+        <action>Use {{suggested_epic_id}} as {{epic_id}}</action>
+      </check>
+    </check>
+
+    <check if="no backlog epics found">
+      <output>✅ All epics are already contexted!
+
+No epics with status "backlog" found in sprint-status.yaml.
+      </output>
+      <ask>Do you want to re-context an existing epic? Enter epic_id or [q] to quit:</ask>
+
+      <check if="user enters epic_id">
+        <action>Store as {{epic_id}}</action>
+      </check>
+
+      <check if="user enters 'q'">
+        <action>HALT - No work needed</action>
+      </check>
+    </check>
+
+    <action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
+    <action>Resolve output file path using workflow variables and initialize by writing the template.</action>
+  </step>
+
+  <step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
+    <action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
+    <action>Get current status value if epic exists</action>
+
+    <check if="epic not found">
+      <output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
+
+This epic hasn't been registered in the sprint plan yet.
+Run sprint-planning workflow to initialize epic tracking.
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <check if="epic status == 'contexted'">
+      <output>ℹ️ Epic {{epic_id}} already marked as contexted
+
+Continuing to regenerate tech spec...
+      </output>
+    </check>
+  </step>
+
+  <step n="3" goal="Overview and scope">
+    <action>Read COMPLETE found {recommended_inputs}.</action>
+    <template-output file="{default_output_file}">
+      Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
+      Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets
+      Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints)
+    </template-output>
+  </step>
+
+  <step n="4" goal="Detailed design">
+    <action>Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate.</action>
+    <template-output file="{default_output_file}">
+      Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners
+      Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available
+      Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes)
+      Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow)
+    </template-output>
+  </step>
+
+  <step n="5" goal="Non-functional requirements">
+    <template-output file="{default_output_file}">
+      Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture
+      Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections
+      Replace {{nfr_reliability}} with availability, recovery, and degradation behavior
+      Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals
+    </template-output>
+  </step>
+
+  <step n="6" goal="Dependencies and integrations">
+    <action>Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json).</action>
+    <template-output file="{default_output_file}">
+      Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known
+    </template-output>
+  </step>
+
+  <step n="7" goal="Acceptance criteria and traceability">
+    <action>Extract acceptance criteria from PRD; normalize into atomic, testable statements.</action>
+    <template-output file="{default_output_file}">
+      Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria
+      Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea
+    </template-output>
+  </step>
+
+  <step n="8" goal="Risks and test strategy">
+    <template-output file="{default_output_file}">
+      Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step
+      Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases)
+    </template-output>
+  </step>
+
+  <step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using .bmad/core/tasks/validate-workflow.xml</invoke-task>
+
+    <!-- Mark epic as contexted -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key "epic-{{epic_id}}"</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="epic key not found in file">
+      <output>⚠️ Could not update epic status: epic-{{epic_id}} not found</output>
+    </check>
+
+    <output>**✅ Tech Spec Generated Successfully, {user_name}!**
+
+**Epic Details:**
+- Epic ID: {{epic_id}}
+- Epic Title: {{epic_title}}
+- Tech Spec File: {{default_output_file}}
+- Epic Status: contexted (was backlog)
+
+**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
+
+**Next Steps:**
+1. Load SM agent and run `create-story` to begin implementing the first story under this epic.
+    </output>
+  </step>
+
+</workflow>
+```

.bmad/bmm/workflows/4-implementation/epic-tech-context/template.md

@@ -0,0 +1,76 @@
+# Epic Technical Specification: {{epic_title}}
+
+Date: {{date}}
+Author: {{user_name}}
+Epic ID: {{epic_id}}
+Status: Draft
+
+---
+
+## Overview
+
+{{overview}}
+
+## Objectives and Scope
+
+{{objectives_scope}}
+
+## System Architecture Alignment
+
+{{system_arch_alignment}}
+
+## Detailed Design
+
+### Services and Modules
+
+{{services_modules}}
+
+### Data Models and Contracts
+
+{{data_models}}
+
+### APIs and Interfaces
+
+{{apis_interfaces}}
+
+### Workflows and Sequencing
+
+{{workflows_sequencing}}
+
+## Non-Functional Requirements
+
+### Performance
+
+{{nfr_performance}}
+
+### Security
+
+{{nfr_security}}
+
+### Reliability/Availability
+
+{{nfr_reliability}}
+
+### Observability
+
+{{nfr_observability}}
+
+## Dependencies and Integrations
+
+{{dependencies_integrations}}
+
+## Acceptance Criteria (Authoritative)
+
+{{acceptance_criteria}}
+
+## Traceability Mapping
+
+{{traceability_mapping}}
+
+## Risks, Assumptions, Open Questions
+
+{{risks_assumptions_questions}}
+
+## Test Strategy Summary
+
+{{test_strategy}}

.bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -0,0 +1,58 @@
+name: epic-tech-context
+description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
+author: "BMAD BMM"
+
+# Critical variables
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Inputs expected (check output_folder or ask user if missing)
+recommended_inputs:
+  - prd
+  - gdd
+  - architecture
+  - ux_design
+  - epics (only the specific epic needed for this tech spec)
+  - prior epic tech-specs for model, style and consistency reference
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed (epic_num from context)
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  gdd:
+    whole: "{output_folder}/*gdd*.md"
+    sharded: "{output_folder}/*gdd*/index.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/epic-tech-context"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -0,0 +1,71 @@
+# Retrospective - Epic Completion Review Workflow
+name: "retrospective"
+description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic"
+author: "BMad"
+
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/retrospective"
+template: false
+instructions: "{installed_path}/instructions.md"
+
+mode: interactive
+trigger: "Run AFTER completing an epic"
+
+required_inputs:
+  - agent_manifest: "{project-root}/.bmad/_cfg/agent-manifest.csv"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  previous_retrospective:
+    pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Required files
+sprint_status_file: "{output_folder}/sprint-status.yaml"
+story_directory: "{config_source}:dev_ephemeral_location"
+retrospectives_folder: "{output_folder}/retrospectives"
+
+output_artifacts:
+  - retrospective_summary: "Comprehensive review of what went well and what could improve"
+  - lessons_learned: "Key insights for future epics"
+  - action_items: "Specific improvements with ownership"
+  - next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
+  - critical_path: "Blockers or prerequisites that must be addressed"
+
+facilitation:
+  facilitator: "Bob (Scrum Master)"
+  tone: "Psychological safety - no blame, focus on systems and processes"
+  format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
+
+validation_required:
+  - testing_complete: "Has full regression testing been completed?"
+  - deployment_status: "Has epic been deployed to production?"
+  - business_validation: "Have stakeholders reviewed and accepted deliverables?"
+  - technical_health: "Is codebase in stable, maintainable state?"
+  - blocker_resolution: "Any unresolved blockers that will impact next epic?"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/sprint-planning/checklist.md

@@ -0,0 +1,33 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation
+
+### Complete Coverage Check
+
+- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml:
+
+```
+Epic Files Contains:                Sprint Status Contains:
+✓ Epic 1                            ✓ epic-1: [status]
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
+  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
+                                      ✓ epic-1-retrospective: [status]
+✓ Epic 2                            ✓ epic-2: [status]
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
+  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
+                                      ✓ epic-2-retrospective: [status]
+```
+
+### Final Check
+
+- [ ] Total count of epics matches
+- [ ] Total count of stories matches
+- [ ] All items are in the expected order (epic, stories, retrospective)

.bmad/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -0,0 +1,238 @@
+# Sprint Planning - Sprint Status Generator
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/.bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml</critical>
+
+## 📚 Document Discovery - Full Epic Loading
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+   - This ensures complete sprint status coverage
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+<action>Communicate in {communication_language} with {user_name}</action>
+<action>Look for all files matching `{epics_pattern}` in {epics_location}</action>
+<action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>
+
+<action>For each epic file found, extract:</action>
+
+- Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
+- Story IDs and titles from patterns like `### Story 1.1: User Authentication`
+- Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title`
+
+**Story ID Conversion Rules:**
+
+- Original: `### Story 1.1: User Authentication`
+- Replace period with dash: `1-1`
+- Convert title to kebab-case: `user-authentication`
+- Final key: `1-1-user-authentication`
+
+<action>Build complete inventory of all epics and stories from all epic files</action>
+</step>
+
+<step n="2" goal="Build sprint status structure">
+<action>For each epic found, create entries in this order:</action>
+
+1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog`
+2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog`
+3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional`
+
+**Example structure:**
+
+```yaml
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: backlog
+  1-2-account-management: backlog
+  epic-1-retrospective: optional
+```
+
+</step>
+
+<step n="3" goal="Apply intelligent status detection">
+<action>For each epic, check if tech context file exists:</action>
+
+- Check: `{output_folder}/epic-{num}-context.md`
+- If exists → set epic status to `contexted`
+- Else → keep as `backlog`
+
+<action>For each story, detect current status by checking files:</action>
+
+**Story file detection:**
+
+- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
+- If exists → upgrade status to at least `drafted`
+
+**Story context detection:**
+
+- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`)
+- If exists → upgrade status to at least `ready-for-dev`
+
+**Preservation rule:**
+
+- If existing `{status_file}` exists and has more advanced status, preserve it
+- Never downgrade status (e.g., don't change `done` to `drafted`)
+
+**Status Flow Reference:**
+
+- Epic: `backlog` → `contexted`
+- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `completed`
+  </step>
+
+<step n="4" goal="Generate sprint status file">
+<action>Create or update {status_file} with:</action>
+
+**File Structure:**
+
+```yaml
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic exists in epic file but not contexted
+#   - contexted: Epic tech context created (required before drafting stories)
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - drafted: Story file created in stories folder
+#   - ready-for-dev: Draft approved and story context created
+#   - in-progress: Developer actively working on implementation
+#   - review: Under SM review (via code-review workflow)
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - completed: Retrospective has been done
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epics should be 'contexted' before stories can be 'drafted'
+# - Stories can be worked in parallel if team capacity allows
+# - SM typically drafts next story after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
+
+generated: { date }
+project: { project_name }
+project_key: { project_key }
+tracking_system: { tracking_system }
+story_location: { story_location }
+
+development_status:
+  # All epics, stories, and retrospectives in order
+```
+
+<action>Write the complete sprint status YAML to {status_file}</action>
+<action>CRITICAL: For story_location field, write the variable value EXACTLY as defined in workflow.yaml: "{project-root}/docs/stories"</action>
+<action>CRITICAL: Do NOT resolve {project-root} to an absolute path - keep it as the literal string "{project-root}/docs/stories"</action>
+<action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
+<action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
+</step>
+
+<step n="5" goal="Validate and report">
+<action>Perform validation checks:</action>
+
+- [ ] Every epic in epic files appears in sprint-status.yaml
+- [ ] Every story in epic files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+- [ ] All status values are legal (match state machine definitions)
+- [ ] File is valid YAML syntax
+
+<action>Count totals:</action>
+
+- Total epics: {{epic_count}}
+- Total stories: {{story_count}}
+- Epics contexted: {{contexted_count}}
+- Stories in progress: {{in_progress_count}}
+- Stories done: {{done_count}}
+
+<action>Display completion summary to {user_name} in {communication_language}:</action>
+
+**Sprint Status Generated Successfully**
+
+- **File Location:** {status_file}
+- **Total Epics:** {{epic_count}}
+- **Total Stories:** {{story_count}}
+- **Contexted Epics:** {{contexted_count}}
+- **Stories In Progress:** {{in_progress_count}}
+- **Stories Completed:** {{done_count}}
+
+**Next Steps:**
+
+1. Review the generated sprint-status.yaml
+2. Use this file to track development progress
+3. Agents will update statuses as they work
+4. Re-run this workflow to refresh auto-detected statuses
+
+</step>
+
+</workflow>
+
+## Additional Documentation
+
+### Status State Machine
+
+**Epic Status Flow:**
+
+```
+backlog → contexted
+```
+
+- **backlog**: Epic exists in epic file but tech context not created
+- **contexted**: Epic tech context has been generated (prerequisite for story drafting)
+
+**Story Status Flow:**
+
+```
+backlog → drafted → ready-for-dev → in-progress → review → done
+```
+
+- **backlog**: Story only exists in epic file
+- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
+- **ready-for-dev**: Draft approved + story context created
+- **in-progress**: Developer actively working
+- **review**: Under SM review (via code-review workflow)
+- **done**: Completed
+
+**Retrospective Status:**
+
+```
+optional ↔ completed
+```
+
+- **optional**: Can be done but not required
+- **completed**: Retrospective has been completed
+
+### Guidelines
+
+1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted`
+2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported
+3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
+4. **Review Before Done**: Stories should pass through `review` before `done`
+5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings
+
+### Error Handling
+
+- If epic file can't be parsed, report specific file and continue with others
+- If existing status file is malformed, backup and regenerate
+- Log warnings for duplicate story IDs across epics
+- Validate status transitions are legal (can't go from `backlog` to `done`)

.bmad/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml

@@ -0,0 +1,55 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the expected format
+# The actual file will be generated with all epics/stories from your epic files
+
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic exists in epic file but not contexted
+#   - contexted: Next epic tech context created by *epic-tech-context (required)
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - drafted: Story file created in stories folder by *create-story
+#   - ready-for-dev: Draft approved and story context created by *story-ready
+#   - in-progress: Developer actively working on implementation by *dev-story
+#   - review: Implementation complete, ready for review by *code-review
+#   - done: Story completed by *story-done
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - completed: Retrospective has been done by *retrospective
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epics should be 'contexted' before stories can be 'drafted'
+# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', dev reviews, then Dev moves to 'done'
+
+# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
+
+generated: 05-06-2-2025 21:30
+project: My Awesome Project
+project_key: jira-1234
+tracking_system: file-system
+story_location: "{project-root}/docs/stories"
+
+development_status:
+  epic-1: contexted
+  1-1-user-authentication: done
+  1-2-account-management: drafted
+  1-3-plant-data-model: backlog
+  1-4-add-plant-manual: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional

.bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -0,0 +1,47 @@
+name: sprint-planning
+description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/sprint-planning"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/sprint-status-template.yaml"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  # Project identification
+  project_name: "{config_source}:project_name"
+  project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
+
+  # Tracking system configuration
+  tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
+  story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+  story_location_absolute: "{config_source}:dev_ephemeral_location" # Absolute path for file operations
+
+  # Source files (file-system only)
+  epics_location: "{output_folder}" # Directory containing epic*.md files
+  epics_pattern: "epic*.md" # Pattern to find epic files
+
+  # Output configuration
+  status_file: "{output_folder}/sprint-status.yaml"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+# Output configuration
+default_output_file: "{status_file}"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/story-context/checklist.md

@@ -0,0 +1,16 @@
+# Story Context Assembly Checklist
+
+```xml
+<checklist id=".bmad/bmm/workflows/4-implementation/story-context/checklist">
+  <item>Story fields (asA/iWant/soThat) captured</item>
+  <item>Acceptance criteria list matches story draft exactly (no invention)</item>
+  <item>Tasks/subtasks captured as task list</item>
+  <item>Relevant docs (5-15) included with path and snippets</item>
+  <item>Relevant code references included with reason and line hints</item>
+  <item>Interfaces/API contracts extracted if applicable</item>
+  <item>Constraints include applicable dev rules and patterns</item>
+  <item>Dependencies detected from manifests and frameworks</item>
+  <item>Testing standards and locations populated</item>
+  <item>XML structure follows story-context template format</item>
+</checklist>
+```

.bmad/bmm/workflows/4-implementation/story-context/context-template.xml

@@ -0,0 +1,34 @@
+<story-context id="{bmad_folder}/bmm/workflows/4-implementation/story-context/template" v="1.0">
+  <metadata>
+    <epicId>{{epic_id}}</epicId>
+    <storyId>{{story_id}}</storyId>
+    <title>{{story_title}}</title>
+    <status>{{story_status}}</status>
+    <generatedAt>{{date}}</generatedAt>
+    <generator>BMAD Story Context Workflow</generator>
+    <sourceStoryPath>{{story_path}}</sourceStoryPath>
+  </metadata>
+
+  <story>
+    <asA>{{as_a}}</asA>
+    <iWant>{{i_want}}</iWant>
+    <soThat>{{so_that}}</soThat>
+    <tasks>{{story_tasks}}</tasks>
+  </story>
+
+  <acceptanceCriteria>{{acceptance_criteria}}</acceptanceCriteria>
+
+  <artifacts>
+    <docs>{{docs_artifacts}}</docs>
+    <code>{{code_artifacts}}</code>
+    <dependencies>{{dependencies_artifacts}}</dependencies>
+  </artifacts>
+
+  <constraints>{{constraints}}</constraints>
+  <interfaces>{{interfaces}}</interfaces>
+  <tests>
+    <standards>{{test_standards}}</standards>
+    <locations>{{test_locations}}</locations>
+    <ideas>{{test_ideas}}</ideas>
+  </tests>
+</story-context>

.bmad/bmm/workflows/4-implementation/story-context/instructions.md

@@ -0,0 +1,234 @@
+<!-- BMAD BMM Story Context Assembly Instructions (v6) -->
+
+```xml
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>This workflow assembles a Story Context file for a single drafted story by extracting acceptance criteria, tasks, relevant docs/code, interfaces, constraints, and testing guidance.</critical>
+<critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
+<critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical>
+
+<critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
+
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story key - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+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 structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+
+<workflow>
+  <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file and parse sections</action>
+      <action>Extract story_key from filename or story metadata</action>
+      <action>Verify Status is "drafted" - if not, HALT with message: "Story status must be 'drafted' to generate context"</action>
+    </check>
+
+    <check if="{{story_path}} is NOT provided">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely</action>
+
+      <action>Find FIRST story (reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "drafted"
+      </action>
+
+      <check if="no story with status 'drafted' found">
+        <output>📋 No drafted stories found in sprint-status.yaml
+
+All stories are either still in backlog or already marked ready/in-progress/done.
+
+**Next Steps:**
+1. Run `create-story` to draft more stories
+2. Run `sprint-planning` to refresh story tracking
+        </output>
+        <action>HALT</action>
+      </check>
+
+      <action>Use the first drafted story found</action>
+      <action>Find matching story file in {{story_dir}} using story_key pattern</action>
+      <action>Read the COMPLETE story file</action>
+    </check>
+
+    <action>Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes</action>
+    <action>Extract user story fields (asA, iWant, soThat)</action>
+    <template-output file="{default_output_file}">story_tasks</template-output>
+    <template-output file="{default_output_file}">acceptance_criteria</template-output>
+
+    <!-- Check if context file already exists -->
+    <action>Check if file exists at {default_output_file}</action>
+
+    <check if="context file already exists">
+      <output>⚠️ Context file already exists: {default_output_file}
+
+**What would you like to do?**
+1. **Replace** - Generate new context file (overwrites existing)
+2. **Verify** - Validate existing context file
+3. **Cancel** - Exit without changes
+      </output>
+      <ask>Choose action (replace/verify/cancel):</ask>
+
+      <check if="user chooses verify">
+        <action>GOTO validation_step</action>
+      </check>
+
+      <check if="user chooses cancel">
+        <action>HALT with message: "Context generation cancelled"</action>
+      </check>
+
+      <check if="user chooses replace">
+        <action>Continue to generate new context file</action>
+      </check>
+    </check>
+
+    <action>Store project root path for relative path conversion: extract from {project-root} variable</action>
+    <action>Define path normalization function: convert any absolute path to project-relative by removing project root prefix</action>
+    <action>Initialize output by writing template to {default_output_file}</action>
+    <template-output file="{default_output_file}">as_a</template-output>
+    <template-output file="{default_output_file}">i_want</template-output>
+    <template-output file="{default_output_file}">so_that</template-output>
+  </step>
+
+  <step n="2" goal="Collect relevant documentation">
+    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
+    <action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
+    <action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
+    <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
+    <template-output file="{default_output_file}">
+      Add artifacts.docs entries with {path, title, section, snippet}:
+      - path: PROJECT-RELATIVE path only (strip {project-root} prefix)
+      - title: Document title
+      - section: Relevant section name
+      - snippet: Brief excerpt (2-3 sentences max, NO invention)
+    </template-output>
+  </step>
+
+  <step n="3" goal="Analyze existing code, interfaces, and constraints">
+    <action>Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests).</action>
+    <action>Identify existing interfaces/APIs the story should reuse rather than recreate.</action>
+    <action>Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements).</action>
+    <action>For all discovered code artifacts: convert absolute paths to project-relative format (strip {project-root} prefix).</action>
+    <template-output file="{default_output_file}">
+      Add artifacts.code entries with {path, kind, symbol, lines, reason}:
+      - path: PROJECT-RELATIVE path only (e.g., "src/services/api.js" not full path)
+      - kind: file type (controller, service, component, test, etc.)
+      - symbol: function/class/interface name
+      - lines: line range if specific (e.g., "45-67")
+      - reason: brief explanation of relevance to this story
+
+      Populate interfaces with API/interface signatures:
+      - name: Interface or API name
+      - kind: REST endpoint, GraphQL, function signature, class interface
+      - signature: Full signature or endpoint definition
+      - path: PROJECT-RELATIVE path to definition
+
+      Populate constraints with development rules:
+      - Extract from Dev Notes and architecture
+      - Include: required patterns, layer restrictions, testing requirements, coding standards
+    </template-output>
+  </step>
+
+  <step n="4" goal="Gather dependencies and frameworks">
+    <action>Detect dependency manifests and frameworks in the repo:
+      - Node: package.json (dependencies/devDependencies)
+      - Python: pyproject.toml/requirements.txt
+      - Go: go.mod
+      - Unity: Packages/manifest.json, Assets/, ProjectSettings/
+      - Other: list notable frameworks/configs found</action>
+    <template-output file="{default_output_file}">
+      Populate artifacts.dependencies with keys for detected ecosystems and their packages with version ranges where present
+    </template-output>
+  </step>
+
+  <step n="5" goal="Testing standards and ideas">
+    <action>From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations).</action>
+    <template-output file="{default_output_file}">
+      Populate tests.standards with a concise paragraph
+      Populate tests.locations with directories or glob patterns where tests live
+      Populate tests.ideas with initial test ideas mapped to acceptance criteria IDs
+    </template-output>
+  </step>
+
+  <step n="6" goal="Validate and save">
+    <anchor id="validation_step" />
+    <action>Validate output context file structure and content</action>
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using .bmad/core/tasks/validate-workflow.xml</invoke-task>
+  </step>
+
+  <step n="7" goal="Update story file and mark ready for dev" tag="sprint-status">
+    <action>Open {{story_path}}</action>
+    <action>Find the "Status:" line (usually at the top)</action>
+    <action>Update story file: Change Status to "ready-for-dev"</action>
+    <action>Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}.</action>
+    <action>Save the story file.</action>
+
+    <!-- Update sprint status to mark ready-for-dev -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "drafted" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
+
+You may need to run sprint-planning to refresh tracking.
+      </output>
+    </check>
+
+    <output>✅ Story context generated successfully, {user_name}!
+
+**Story Details:**
+
+- Story: {{epic_id}}.{{story_id}} - {{story_title}}
+- Story Key: {{story_key}}
+- Context File: {default_output_file}
+- Status: drafted → ready-for-dev
+
+**Context Includes:**
+
+- Documentation artifacts and references
+- Existing code and interfaces
+- Dependencies and frameworks
+- Testing standards and ideas
+- Development constraints
+
+**Next Steps:**
+
+1. Review the context file: {default_output_file}
+2. Run `dev-story` to implement the story
+3. Generate context for more drafted stories if needed
+    </output>
+  </step>
+
+</workflow>
+```

.bmad/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -0,0 +1,57 @@
+# Story Context Creation Workflow
+name: story-context
+description: "Assemble a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story"
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+story_path: "{config_source}:dev_ephemeral_location"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/story-context"
+template: "{installed_path}/context-template.xml"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
+  story_dir: "{config_source}:dev_ephemeral_location"
+
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/tech-spec.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Output configuration
+# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
+default_output_file: "{story_dir}/{{story_key}}.context.xml"
+
+standalone: true

.bmad/bmm/workflows/4-implementation/story-done/instructions.md

@@ -0,0 +1,111 @@
+# Story Approved Workflow Instructions (DEV Agent)
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
+<critical>Workflow: Update story file status to Done</critical>
+
+<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
+
+<check if="{story_path} is provided">
+  <action>Use {story_path} directly</action>
+  <action>Read COMPLETE story file and parse sections</action>
+  <action>Extract story_key from filename or story metadata</action>
+  <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
+</check>
+
+<check if="{story_path} is NOT provided">
+  <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+  <action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+  <action>Read ALL lines from beginning to end - do not skip any content</action>
+  <action>Parse the development_status section completely</action>
+
+<action>Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review"
+</action>
+
+  <check if="no story with status 'review' found">
+    <output>📋 No stories with status "review" found
+
+All stories are either still in development or already done.
+
+**Next Steps:**
+
+1. Run `dev-story` to implement stories
+2. Run `code-review` if stories need review first
+3. Check sprint-status.yaml for current story states
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Use the first reviewed story found</action>
+<action>Find matching story file in {story_dir} using story_key pattern</action>
+<action>Read the COMPLETE story file</action>
+</check>
+
+<action>Extract story_id and story_title from the story file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "done"</action>
+
+<action>Add completion notes to Dev Agent Record section:</action>
+<action>Find "## Dev Agent Record" section and add:
+
+```
+### Completion Notes
+**Completed:** {date}
+**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
+```
+
+</action>
+
+<action>Save the story file</action>
+</step>
+
+<step n="2" goal="Update sprint status to done" tag="sprint-status">
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Find development_status key matching {story_key}</action>
+<action>Verify current status is "review" (expected previous state)</action>
+<action>Update development_status[{story_key}] = "done"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {story_key} not found
+
+Story is marked Done in file, but sprint-status.yaml may be out of sync.
+</output>
+</check>
+
+</step>
+
+<step n="3" goal="Confirm completion to user">
+
+<output>**Story Approved and Marked Done, {user_name}!**
+
+✅ Story file updated → Status: done
+✅ Sprint status updated: review → done
+
+**Completed Story:**
+
+- **ID:** {story_id}
+- **Key:** {story_key}
+- **Title:** {story_title}
+- **Completed:** {date}
+
+**Next Steps:**
+
+1. Continue with next story in your backlog
+   - Run `create-story` for next backlog story
+   - Or run `dev-story` if ready stories exist
+2. Check epic completion status
+   - Run `retrospective` workflow to check if epic is complete
+   - Epic retrospective will verify all stories are done
+     </output>
+
+</step>
+
+</workflow>
+```

.bmad/bmm/workflows/4-implementation/story-done/workflow.yaml

@@ -0,0 +1,25 @@
+# Story Done Workflow (DEV Agent)
+name: story-done
+description: "Marks a story as done (DoD complete) and moves it from its current status → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/story-done"
+instructions: "{installed_path}/instructions.md"
+
+# Variables and inputs
+variables:
+  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_ephemeral_location" # Directory where stories are stored
+
+# Output configuration - no output file, just status updates
+default_output_file: ""
+
+standalone: true

.bmad/bmm/workflows/4-implementation/story-ready/instructions.md

@@ -0,0 +1,117 @@
+# Story Ready Workflow Instructions (SM Agent)
+
+<critical>The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development</critical>
+<critical>Simple workflow: Update story file status to Ready</critical>
+
+<step n="1" goal="Find drafted story to mark ready" tag="sprint-status">
+
+<action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
+
+<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Read ALL lines from beginning to end - do not skip any content</action>
+<action>Parse the development_status section completely</action>
+
+<action>Find ALL stories (reading in order from top to bottom) where:
+
+- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+- Status value equals "drafted"
+  </action>
+
+<action>Collect up to 10 drafted story keys in order (limit for display purposes)</action>
+<action>Count total drafted stories found</action>
+
+<check if="no drafted stories found">
+  <output>📋 No drafted stories found in sprint-status.yaml
+
+All stories are either still in backlog or already marked ready/in-progress/done.
+
+**Options:**
+
+1. Run `create-story` to draft more stories
+2. Run `sprint-planning` to refresh story tracking
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Display available drafted stories:
+
+**Drafted Stories Available ({{drafted_count}} found):**
+
+{{list_of_drafted_story_keys}}
+
+</action>
+
+<ask if="{{non_interactive}} == false">Select the drafted story to mark as Ready (enter story key or number):</ask>
+<action if="{{non_interactive}} == true">Auto-select first story from the list</action>
+
+<action>Resolve selected story_key from user input or auto-selection</action>
+<action>Find matching story file in {{story_dir}} using story_key pattern</action>
+
+<anchor id="mark_ready" />
+
+<action>Read the story file from resolved path</action>
+<action>Extract story_id and story_title from the file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "ready-for-dev"</action>
+<action>Save the story file</action>
+</step>
+
+<step n="2" goal="Update sprint status to ready-for-dev" tag="sprint-status">
+<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Find development_status key matching {{story_key}}</action>
+<action>Verify current status is "drafted" (expected previous state)</action>
+<action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="story key not found in file">
+  <output>⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found
+
+You may need to run sprint-planning to refresh tracking.
+</output>
+</check>
+
+</step>
+
+<step n="3" goal="Confirm completion to user">
+
+<output>**Story Marked Ready for Development, {user_name}!**
+
+✅ Story file updated: `{{story_file}}` → Status: ready-for-dev
+✅ Sprint status updated: drafted → ready-for-dev
+
+**Story Details:**
+
+- **ID:** {{story_id}}
+- **Key:** {{story_key}}
+- **Title:** {{story_title}}
+- **File:** `{{story_file}}`
+- **Status:** ready-for-dev
+
+**Next Steps:**
+
+1. **Recommended:** Run `story-context` workflow to generate implementation context
+   - This creates a comprehensive context XML for the DEV agent
+   - Includes relevant architecture, dependencies, and existing code
+
+2. **Alternative:** Skip context generation and go directly to `dev-story` workflow
+   - Faster, but DEV agent will have less context
+   - Only recommended for simple, well-understood stories
+
+**To proceed:**
+
+- For context generation: Stay with SM agent and run `story-context` workflow
+- For direct implementation: Load DEV agent and run `dev-story` workflow
+
+</step>
+
+</workflow>

.bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml

@@ -0,0 +1,25 @@
+# Story Ready Workflow (SM Agent)
+name: story-ready
+description: "Marks a drafted story as ready for development and moves it from TODO → IN PROGRESS in the status file. Simple status-update workflow with no searching required."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/4-implementation/story-ready"
+instructions: "{installed_path}/instructions.md"
+
+# Variables and inputs
+variables:
+  story_path: "" # Explicit path to story file
+  story_dir: "{config_source}:dev_ephemeral_location" # Directory where stories are stored
+
+# Output configuration - no output file, just status updates
+default_output_file: ""
+
+standalone: true

.bmad/bmm/workflows/document-project/checklist.md

@@ -0,0 +1,245 @@
+# Document Project Workflow - Validation Checklist
+
+## Scan Level and Resumability (v1.2.0)
+
+- [ ] Scan level selection offered (quick/deep/exhaustive) for initial_scan and full_rescan modes
+- [ ] Deep-dive mode automatically uses exhaustive scan (no choice given)
+- [ ] Quick scan does NOT read source files (only patterns, configs, manifests)
+- [ ] Deep scan reads files in critical directories per project type
+- [ ] Exhaustive scan reads ALL source files (excluding node_modules, dist, build)
+- [ ] State file (project-scan-report.json) created at workflow start
+- [ ] State file updated after each step completion
+- [ ] State file contains all required fields per schema
+- [ ] Resumability prompt shown if state file exists and is <24 hours old
+- [ ] Old state files (>24 hours) automatically archived
+- [ ] Resume functionality loads previous state correctly
+- [ ] Workflow can jump to correct step when resuming
+
+## Write-as-you-go Architecture
+
+- [ ] Each document written to disk IMMEDIATELY after generation
+- [ ] Document validation performed right after writing (section-level)
+- [ ] State file updated after each document is written
+- [ ] Detailed findings purged from context after writing (only summaries kept)
+- [ ] Context contains only high-level summaries (1-2 sentences per section)
+- [ ] No accumulation of full project analysis in memory
+
+## Batching Strategy (Deep/Exhaustive Scans)
+
+- [ ] Batching applied for deep and exhaustive scan levels
+- [ ] Batches organized by SUBFOLDER (not arbitrary file count)
+- [ ] Large files (>5000 LOC) handled with appropriate judgment
+- [ ] Each batch: read files, extract info, write output, validate, purge context
+- [ ] Batch completion tracked in state file (batches_completed array)
+- [ ] Batch summaries kept in context (1-2 sentences max)
+
+## Project Detection and Classification
+
+- [ ] Project type correctly identified and matches actual technology stack
+- [ ] Multi-part vs single-part structure accurately detected
+- [ ] All project parts identified if multi-part (no missing client/server/etc.)
+- [ ] Documentation requirements loaded for each part type
+- [ ] Architecture registry match is appropriate for detected stack
+
+## Technology Stack Analysis
+
+- [ ] All major technologies identified (framework, language, database, etc.)
+- [ ] Versions captured where available
+- [ ] Technology decision table is complete and accurate
+- [ ] Dependencies and libraries documented
+- [ ] Build tools and package managers identified
+
+## Codebase Scanning Completeness
+
+- [ ] All critical directories scanned based on project type
+- [ ] API endpoints documented (if requires_api_scan = true)
+- [ ] Data models captured (if requires_data_models = true)
+- [ ] State management patterns identified (if requires_state_management = true)
+- [ ] UI components inventoried (if requires_ui_components = true)
+- [ ] Configuration files located and documented
+- [ ] Authentication/security patterns identified
+- [ ] Entry points correctly identified
+- [ ] Integration points mapped (for multi-part projects)
+- [ ] Test files and patterns documented
+
+## Source Tree Analysis
+
+- [ ] Complete directory tree generated with no major omissions
+- [ ] Critical folders highlighted and described
+- [ ] Entry points clearly marked
+- [ ] Integration paths noted (for multi-part)
+- [ ] Asset locations identified (if applicable)
+- [ ] File organization patterns explained
+
+## Architecture Documentation Quality
+
+- [ ] Architecture document uses appropriate template from registry
+- [ ] All template sections filled with relevant information (no placeholders)
+- [ ] Technology stack section is comprehensive
+- [ ] Architecture pattern clearly explained
+- [ ] Data architecture documented (if applicable)
+- [ ] API design documented (if applicable)
+- [ ] Component structure explained (if applicable)
+- [ ] Source tree included and annotated
+- [ ] Testing strategy documented
+- [ ] Deployment architecture captured (if config found)
+
+## Development and Operations Documentation
+
+- [ ] Prerequisites clearly listed
+- [ ] Installation steps documented
+- [ ] Environment setup instructions provided
+- [ ] Local run commands specified
+- [ ] Build process documented
+- [ ] Test commands and approach explained
+- [ ] Deployment process documented (if applicable)
+- [ ] CI/CD pipeline details captured (if found)
+- [ ] Contribution guidelines extracted (if found)
+
+## Multi-Part Project Specific (if applicable)
+
+- [ ] Each part documented separately
+- [ ] Part-specific architecture files created (architecture-{part_id}.md)
+- [ ] Part-specific component inventories created (if applicable)
+- [ ] Part-specific development guides created
+- [ ] Integration architecture document created
+- [ ] Integration points clearly defined with type and details
+- [ ] Data flow between parts explained
+- [ ] project-parts.json metadata file created
+
+## Index and Navigation
+
+- [ ] index.md created as master entry point
+- [ ] Project structure clearly summarized in index
+- [ ] Quick reference section complete and accurate
+- [ ] All generated docs linked from index
+- [ ] All existing docs linked from index (if found)
+- [ ] Getting started section provides clear next steps
+- [ ] AI-assisted development guidance included
+- [ ] Navigation structure matches project complexity (simple for single-part, detailed for multi-part)
+
+## File Completeness
+
+- [ ] index.md generated
+- [ ] project-overview.md generated
+- [ ] source-tree-analysis.md generated
+- [ ] architecture.md (or per-part) generated
+- [ ] component-inventory.md (or per-part) generated if UI components exist
+- [ ] development-guide.md (or per-part) generated
+- [ ] api-contracts.md (or per-part) generated if APIs documented
+- [ ] data-models.md (or per-part) generated if data models found
+- [ ] deployment-guide.md generated if deployment config found
+- [ ] contribution-guide.md generated if guidelines found
+- [ ] integration-architecture.md generated if multi-part
+- [ ] project-parts.json generated if multi-part
+
+## Content Quality
+
+- [ ] Technical information is accurate and specific
+- [ ] No generic placeholders or "TODO" items remain
+- [ ] Examples and code snippets are relevant to actual project
+- [ ] File paths and directory references are correct
+- [ ] Technology names and versions are accurate
+- [ ] Terminology is consistent across all documents
+- [ ] Descriptions are clear and actionable
+
+## Brownfield PRD Readiness
+
+- [ ] Documentation provides enough context for AI to understand existing system
+- [ ] Integration points are clear for planning new features
+- [ ] Reusable components are identified for leveraging in new work
+- [ ] Data models are documented for schema extension planning
+- [ ] API contracts are documented for endpoint expansion
+- [ ] Code conventions and patterns are captured for consistency
+- [ ] Architecture constraints are clear for informed decision-making
+
+## Output Validation
+
+- [ ] All files saved to correct output folder
+- [ ] File naming follows convention (no part suffix for single-part, with suffix for multi-part)
+- [ ] No broken internal links between documents
+- [ ] Markdown formatting is correct and renders properly
+- [ ] JSON files are valid (project-parts.json if applicable)
+
+## Final Validation
+
+- [ ] User confirmed project classification is accurate
+- [ ] User provided any additional context needed
+- [ ] All requested areas of focus addressed
+- [ ] Documentation is immediately usable for brownfield PRD workflow
+- [ ] No critical information gaps identified
+
+## Issues Found
+
+### Critical Issues (must fix before completion)
+
+-
+
+### Minor Issues (can be addressed later)
+
+-
+
+### Missing Information (to note for user)
+
+- ***
+
+## Deep-Dive Mode Validation (if deep-dive was performed)
+
+- [ ] Deep-dive target area correctly identified and scoped
+- [ ] All files in target area read completely (no skipped files)
+- [ ] File inventory includes all exports with complete signatures
+- [ ] Dependencies mapped for all files
+- [ ] Dependents identified (who imports each file)
+- [ ] Code snippets included for key implementation details
+- [ ] Patterns and design approaches documented
+- [ ] State management strategy explained
+- [ ] Side effects documented (API calls, DB queries, etc.)
+- [ ] Error handling approaches captured
+- [ ] Testing files and coverage documented
+- [ ] TODOs and comments extracted
+- [ ] Dependency graph created showing relationships
+- [ ] Data flow traced through the scanned area
+- [ ] Integration points with rest of codebase identified
+- [ ] Related code and similar patterns found outside scanned area
+- [ ] Reuse opportunities documented
+- [ ] Implementation guidance provided
+- [ ] Modification instructions clear
+- [ ] Index.md updated with deep-dive link
+- [ ] Deep-dive documentation is immediately useful for implementation
+
+---
+
+## State File Quality
+
+- [ ] State file is valid JSON (no syntax errors)
+- [ ] State file is optimized (no pretty-printing, minimal whitespace)
+- [ ] State file contains all completed steps with timestamps
+- [ ] State file outputs_generated list is accurate and complete
+- [ ] State file resume_instructions are clear and actionable
+- [ ] State file findings contain only high-level summaries (not detailed data)
+- [ ] State file can be successfully loaded for resumption
+
+## Completion Criteria
+
+All items in the following sections must be checked:
+
+- ✓ Scan Level and Resumability (v1.2.0)
+- ✓ Write-as-you-go Architecture
+- ✓ Batching Strategy (if deep/exhaustive scan)
+- ✓ Project Detection and Classification
+- ✓ Technology Stack Analysis
+- ✓ Architecture Documentation Quality
+- ✓ Index and Navigation
+- ✓ File Completeness
+- ✓ Brownfield PRD Readiness
+- ✓ State File Quality
+- ✓ Deep-Dive Mode Validation (if applicable)
+
+The workflow is complete when:
+
+1. All critical checklist items are satisfied
+2. No critical issues remain
+3. User has reviewed and approved the documentation
+4. Generated docs are ready for use in brownfield PRD workflow
+5. Deep-dive docs (if any) are comprehensive and implementation-ready
+6. State file is valid and can enable resumption if interrupted

.bmad/bmm/workflows/document-project/documentation-requirements.csv

@@ -0,0 +1,12 @@
+project_type_id,requires_api_scan,requires_data_models,requires_state_management,requires_ui_components,requires_deployment_config,key_file_patterns,critical_directories,integration_scan_patterns,test_file_patterns,config_patterns,auth_security_patterns,schema_migration_patterns,entry_point_patterns,shared_code_patterns,monorepo_workspace_patterns,async_event_patterns,ci_cd_patterns,asset_patterns,hardware_interface_patterns,protocol_schema_patterns,localization_patterns,requires_hardware_docs,requires_asset_inventory
+web,true,true,true,true,true,package.json;tsconfig.json;*.config.js;*.config.ts;vite.config.*;webpack.config.*;next.config.*;nuxt.config.*,src/;app/;pages/;components/;api/;lib/;styles/;public/;static/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.spec.ts;*.test.tsx;*.spec.tsx;**/__tests__/**;**/*.test.*;**/*.spec.*,.env*;config/*;*.config.*;.config/;settings/,*auth*.ts;*session*.ts;middleware/auth*;*.guard.ts;*authenticat*;*permission*;guards/,migrations/**;prisma/**;*.prisma;alembic/**;knex/**;*migration*.sql;*migration*.ts,main.ts;index.ts;app.ts;server.ts;_app.tsx;_app.ts;layout.tsx,shared/**;common/**;utils/**;lib/**;helpers/**;@*/**;packages/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json;workspace.json;rush.json,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;jobs/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;bitbucket-pipelines.yml,.drone.yml,public/**;static/**;assets/**;images/**;media/**,N/A,*.proto;*.graphql;graphql/**;schema.graphql;*.avro;openapi.*;swagger.*,i18n/**;locales/**;lang/**;translations/**;messages/**;*.po;*.pot,false,false
+mobile,true,true,true,true,true,package.json;pubspec.yaml;Podfile;build.gradle;app.json;capacitor.config.*;ionic.config.json,src/;app/;screens/;components/;services/;models/;assets/;ios/;android/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.test.tsx;*_test.dart;*.test.dart;**/__tests__/**,.env*;config/*;app.json;capacitor.config.*;google-services.json;GoogleService-Info.plist,*auth*.ts;*session*.ts;*authenticat*;*permission*;*biometric*;secure-store*,migrations/**;realm/**;*.realm;watermelondb/**;sqlite/**,main.ts;index.ts;App.tsx;App.ts;main.dart,shared/**;common/**;utils/**;lib/**;components/shared/**;@*/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json,*event*.ts;*notification*.ts;*push*.ts;background-fetch*,fastlane/**;.github/workflows/**;.gitlab-ci.yml;bitbucket-pipelines.yml;appcenter-*,assets/**;Resources/**;res/**;*.xcassets;drawable*/;mipmap*/;images/**,N/A,*.proto;graphql/**;*.graphql,i18n/**;locales/**;translations/**;*.strings;*.xml,false,true
+backend,true,true,false,false,true,package.json;requirements.txt;go.mod;Gemfile;pom.xml;build.gradle;Cargo.toml;*.csproj,src/;api/;services/;models/;routes/;controllers/;middleware/;handlers/;repositories/;domain/,*client.ts;*repository.ts;*service.ts;*connector*.ts;*adapter*.ts,*.test.ts;*.spec.ts;*_test.go;test_*.py;*Test.java;*_test.rs,.env*;config/*;*.config.*;application*.yml;application*.yaml;appsettings*.json;settings.py,*auth*.ts;*session*.ts;*authenticat*;*authorization*;middleware/auth*;guards/;*jwt*;*oauth*,migrations/**;alembic/**;flyway/**;liquibase/**;prisma/**;*.prisma;*migration*.sql;*migration*.ts;db/migrate,main.ts;index.ts;server.ts;app.ts;main.go;main.py;Program.cs;__init__.py,shared/**;common/**;utils/**;lib/**;core/**;@*/**;pkg/**,pnpm-workspace.yaml;lerna.json;nx.json;go.work,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;*handler*.ts;jobs/**;workers/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;.drone.yml,N/A,N/A,*.proto;*.graphql;graphql/**;*.avro;*.thrift;openapi.*;swagger.*;schema/**,N/A,false,false
+cli,false,false,false,false,false,package.json;go.mod;Cargo.toml;setup.py;pyproject.toml;*.gemspec,src/;cmd/;cli/;bin/;lib/;commands/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*_spec.rb,.env*;config/*;*.config.*;.*.rc;.*rc,N/A,N/A,main.ts;index.ts;cli.ts;main.go;main.py;__main__.py;bin/*,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;goreleaser.yml,N/A,N/A,N/A,N/A,false,false
+library,false,false,false,false,false,package.json;setup.py;Cargo.toml;go.mod;*.gemspec;*.csproj;pom.xml,src/;lib/;dist/;pkg/;build/;target/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*Test.java;*_test.rs,.*.rc;tsconfig.json;rollup.config.*;vite.config.*;webpack.config.*,N/A,N/A,index.ts;index.js;lib.rs;main.go;__init__.py,src/**;lib/**;core/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+desktop,false,false,true,true,true,package.json;Cargo.toml;*.csproj;CMakeLists.txt;tauri.conf.json;electron-builder.yml;wails.json,src/;app/;components/;main/;renderer/;resources/;assets/;build/,*service.ts;ipc*.ts;*bridge*.ts;*native*.ts;invoke*,*.test.ts;*.spec.ts;*_test.rs;*.spec.tsx,.env*;config/*;*.config.*;app.config.*;forge.config.*;builder.config.*,*auth*.ts;*session*.ts;keychain*;secure-storage*,N/A,main.ts;index.ts;main.js;src-tauri/main.rs;electron.ts,shared/**;common/**;utils/**;lib/**;components/shared/**,N/A,*event*.ts;*ipc*.ts;*message*.ts,.github/workflows/**;.gitlab-ci.yml;.circleci/**,resources/**;assets/**;icons/**;static/**;build/resources,N/A,N/A,i18n/**;locales/**;translations/**;lang/**,false,true
+game,false,false,true,false,false,*.unity;*.godot;*.uproject;package.json;project.godot,Assets/;Scenes/;Scripts/;Prefabs/;Resources/;Content/;Source/;src/;scenes/;scripts/,N/A,*Test.cs;*_test.gd;*Test.cpp;*.test.ts,.env*;config/*;*.ini;settings/;GameSettings/,N/A,N/A,main.gd;Main.cs;GameManager.cs;main.cpp;index.ts,shared/**;common/**;utils/**;Core/**;Framework/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,Assets/**;Scenes/**;Prefabs/**;Materials/**;Textures/**;Audio/**;Models/**;*.fbx;*.blend;*.shader;*.hlsl;*.glsl;Shaders/**;VFX/**,N/A,N/A,Localization/**;Languages/**;i18n/**,false,true
+data,false,true,false,false,true,requirements.txt;pyproject.toml;dbt_project.yml;airflow.cfg;setup.py;Pipfile,dags/;pipelines/;models/;transformations/;notebooks/;sql/;etl/;jobs/,N/A,test_*.py;*_test.py;tests/**,.env*;config/*;profiles.yml;dbt_project.yml;airflow.cfg,N/A,migrations/**;dbt/models/**;*.sql;schemas/**,main.py;__init__.py;pipeline.py;dag.py,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,*event*.py;*consumer*.py;*producer*.py;*worker*.py;jobs/**;tasks/**,.github/workflows/**;.gitlab-ci.yml;airflow/dags/**,N/A,N/A,*.proto;*.avro;schemas/**;*.parquet,N/A,false,false
+extension,true,false,true,true,false,manifest.json;package.json;wxt.config.ts,src/;popup/;content/;background/;assets/;components/,*message.ts;*runtime.ts;*storage.ts;*tabs.ts,*.test.ts;*.spec.ts;*.test.tsx,.env*;wxt.config.*;webpack.config.*;vite.config.*,*auth*.ts;*session*.ts;*permission*,N/A,index.ts;popup.ts;background.ts;content.ts,shared/**;common/**;utils/**;lib/**,N/A,*message*.ts;*event*.ts;chrome.runtime*;browser.runtime*,.github/workflows/**,assets/**;icons/**;images/**;static/**,N/A,N/A,_locales/**;locales/**;i18n/**,false,false
+infra,false,false,false,false,true,*.tf;*.tfvars;pulumi.yaml;cdk.json;*.yml;*.yaml;Dockerfile;docker-compose*.yml,terraform/;modules/;k8s/;charts/;playbooks/;roles/;policies/;stacks/,N/A,*_test.go;test_*.py;*_test.tf;*_spec.rb,.env*;*.tfvars;config/*;vars/;group_vars/;host_vars/,N/A,N/A,main.tf;index.ts;__main__.py;playbook.yml,modules/**;shared/**;common/**;lib/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+embedded,false,false,false,false,false,platformio.ini;CMakeLists.txt;*.ino;Makefile;*.ioc;mbed-os.lib,src/;lib/;include/;firmware/;drivers/;hal/;bsp/;components/,N/A,test_*.c;*_test.cpp;*_test.c;tests/**,.env*;config/*;sdkconfig;*.json;settings/,N/A,N/A,main.c;main.cpp;main.ino;app_main.c,lib/**;shared/**;common/**;drivers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,N/A,*.h;*.hpp;drivers/**;hal/**;bsp/**;pinout.*;peripheral*;gpio*;*.fzz;schematics/**,*.proto;mqtt*;coap*;modbus*,N/A,true,false

.bmad/bmm/workflows/document-project/instructions.md

@@ -0,0 +1,222 @@
+# Document Project Workflow Router
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/.bmad/bmm/workflows/document-project/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
+
+<step n="1" goal="Validate workflow and get project info">
+
+<invoke-workflow path="{project-root}/.bmad/bmm/workflows/workflow-status">
+  <param>mode: data</param>
+  <param>data_request: project_config</param>
+</invoke-workflow>
+
+<check if="status_exists == false">
+  <output>{{suggestion}}</output>
+  <output>Note: Documentation workflow can run standalone. Continuing without progress tracking.</output>
+  <action>Set standalone_mode = true</action>
+  <action>Set status_file_found = false</action>
+</check>
+
+<check if="status_exists == true">
+  <action>Store {{status_file_path}} for later updates</action>
+  <action>Set status_file_found = true</action>
+
+  <!-- Extract brownfield/greenfield from status data -->
+  <check if="field_type == 'greenfield'">
+    <output>Note: This is a greenfield project. Documentation workflow is typically for brownfield projects.</output>
+    <ask>Continue anyway to document planning artifacts? (y/n)</ask>
+    <check if="n">
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <!-- Now validate sequencing -->
+  <invoke-workflow path="{project-root}/.bmad/bmm/workflows/workflow-status">
+    <param>mode: validate</param>
+    <param>calling_workflow: document-project</param>
+  </invoke-workflow>
+
+  <check if="warning != ''">
+    <output>{{warning}}</output>
+    <output>Note: This may be auto-invoked by prd for brownfield documentation.</output>
+    <ask>Continue with documentation? (y/n)</ask>
+    <check if="n">
+      <output>{{suggestion}}</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+</check>
+
+</step>
+
+<step n="2" goal="Check for resumability and determine workflow mode">
+<critical>SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files</critical>
+
+<action>Check for existing state file at: {output_folder}/project-scan-report.json</action>
+
+<check if="project-scan-report.json exists">
+  <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
+  <action>Extract cached project_type_id(s) from state file if present</action>
+  <action>Calculate age of state file (current time - last_updated)</action>
+
+<ask>I found an in-progress workflow state from {{last_updated}}.
+
+**Current Progress:**
+
+- Mode: {{mode}}
+- Scan Level: {{scan_level}}
+- Completed Steps: {{completed_steps_count}}/{{total_steps}}
+- Last Step: {{current_step}}
+- Project Type(s): {{cached_project_types}}
+
+Would you like to:
+
+1. **Resume from where we left off** - Continue from step {{current_step}}
+2. **Start fresh** - Archive old state and begin new scan
+3. **Cancel** - Exit without changes
+
+Your choice [1/2/3]:
+</ask>
+
+    <check if="user selects 1">
+      <action>Set resume_mode = true</action>
+      <action>Set workflow_mode = {{mode}}</action>
+      <action>Load findings summaries from state file</action>
+      <action>Load cached project_type_id(s) from state file</action>
+
+      <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
+      <action>For each cached project_type_id, load ONLY the corresponding row from: {documentation_requirements_csv}</action>
+      <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
+      <action>Store loaded doc requirements for use in remaining steps</action>
+
+      <action>Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
+
+      <check if="workflow_mode == deep_dive">
+        <action>Load and execute: {installed_path}/workflows/deep-dive-instructions.md with resume context</action>
+      </check>
+
+      <check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
+        <action>Load and execute: {installed_path}/workflows/full-scan-instructions.md with resume context</action>
+      </check>
+    </check>
+
+    <check if="user selects 2">
+      <action>Create archive directory: {output_folder}/.archive/</action>
+      <action>Move old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+      <action>Set resume_mode = false</action>
+      <action>Continue to Step 0.5</action>
+    </check>
+
+    <check if="user selects 3">
+      <action>Display: "Exiting workflow without changes."</action>
+      <action>Exit workflow</action>
+    </check>
+
+  </check>
+
+  <check if="state file age >= 24 hours">
+    <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
+    <action>Archive old state file to: {output_folder}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+</step>
+
+<step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">
+<action>Check if {output_folder}/index.md exists</action>
+
+<check if="index.md exists">
+  <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
+  <action>Store as {{existing_doc_date}}, {{existing_structure}}</action>
+
+<ask>I found existing documentation generated on {{existing_doc_date}}.
+
+What would you like to do?
+
+1. **Re-scan entire project** - Update all documentation with latest changes
+2. **Deep-dive into specific area** - Generate detailed documentation for a particular feature/module/folder
+3. **Cancel** - Keep existing documentation as-is
+
+Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set workflow_mode = "full_rescan"</action>
+    <action>Display: "Starting full project rescan..."</action>
+    <action>Load and execute: {installed_path}/workflows/full-scan-instructions.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 2">
+    <action>Set workflow_mode = "deep_dive"</action>
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Display: "Starting deep-dive documentation mode..."</action>
+    <action>Load and execute: {installed_path}/workflows/deep-dive-instructions.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="index.md does not exist">
+  <action>Set workflow_mode = "initial_scan"</action>
+  <action>Display: "No existing documentation found. Starting initial project scan..."</action>
+  <action>Load and execute: {installed_path}/workflows/full-scan-instructions.md</action>
+  <action>After sub-workflow completes, continue to Step 4</action>
+</check>
+
+</step>
+
+<step n="4" goal="Update status and complete">
+
+<check if="status_file_found == true">
+  <invoke-workflow path="{project-root}/.bmad/bmm/workflows/workflow-status">
+    <param>mode: update</param>
+    <param>action: complete_workflow</param>
+    <param>workflow_name: document-project</param>
+  </invoke-workflow>
+
+  <check if="success == true">
+    <output>Status updated!</output>
+  </check>
+</check>
+
+<output>**✅ Document Project Workflow Complete, {user_name}!**
+
+**Documentation Generated:**
+
+- Mode: {{workflow_mode}}
+- Scan Level: {{scan_level}}
+- Output: {output_folder}/bmm-index.md and related files
+
+{{#if status_file_found}}
+**Status Updated:**
+
+- Progress tracking updated
+
+**Next Steps:**
+
+- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+
+Check status anytime with: `workflow-status`
+{{else}}
+**Next Steps:**
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+
+</step>
+
+</workflow>

.bmad/bmm/workflows/document-project/templates/deep-dive-template.md

@@ -0,0 +1,345 @@
+# {{target_name}} - Deep Dive Documentation
+
+**Generated:** {{date}}
+**Scope:** {{target_path}}
+**Files Analyzed:** {{file_count}}
+**Lines of Code:** {{total_loc}}
+**Workflow Mode:** Exhaustive Deep-Dive
+
+## Overview
+
+{{target_description}}
+
+**Purpose:** {{target_purpose}}
+**Key Responsibilities:** {{responsibilities}}
+**Integration Points:** {{integration_summary}}
+
+## Complete File Inventory
+
+{{#each files_in_inventory}}
+
+### {{file_path}}
+
+**Purpose:** {{purpose}}
+**Lines of Code:** {{loc}}
+**File Type:** {{file_type}}
+
+**What Future Contributors Must Know:** {{contributor_note}}
+
+**Exports:**
+{{#each exports}}
+
+- `{{signature}}` - {{description}}
+  {{/each}}
+
+**Dependencies:**
+{{#each imports}}
+
+- `{{import_path}}` - {{reason}}
+  {{/each}}
+
+**Used By:**
+{{#each dependents}}
+
+- `{{dependent_path}}`
+  {{/each}}
+
+**Key Implementation Details:**
+
+```{{language}}
+{{key_code_snippet}}
+```
+
+{{implementation_notes}}
+
+**Patterns Used:**
+{{#each patterns}}
+
+- {{pattern_name}}: {{pattern_description}}
+  {{/each}}
+
+**State Management:** {{state_approach}}
+
+**Side Effects:**
+{{#each side_effects}}
+
+- {{effect_type}}: {{effect_description}}
+  {{/each}}
+
+**Error Handling:** {{error_handling_approach}}
+
+**Testing:**
+
+- Test File: {{test_file_path}}
+- Coverage: {{coverage_percentage}}%
+- Test Approach: {{test_approach}}
+
+**Comments/TODOs:**
+{{#each todos}}
+
+- Line {{line_number}}: {{todo_text}}
+  {{/each}}
+
+---
+
+{{/each}}
+
+## Contributor Checklist
+
+- **Risks & Gotchas:** {{risks_notes}}
+- **Pre-change Verification Steps:** {{verification_steps}}
+- **Suggested Tests Before PR:** {{suggested_tests}}
+
+## Architecture & Design Patterns
+
+### Code Organization
+
+{{organization_approach}}
+
+### Design Patterns
+
+{{#each design_patterns}}
+
+- **{{pattern_name}}**: {{usage_description}}
+  {{/each}}
+
+### State Management Strategy
+
+{{state_management_details}}
+
+### Error Handling Philosophy
+
+{{error_handling_philosophy}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+## Data Flow
+
+{{data_flow_diagram}}
+
+### Data Entry Points
+
+{{#each entry_points}}
+
+- **{{entry_name}}**: {{entry_description}}
+  {{/each}}
+
+### Data Transformations
+
+{{#each transformations}}
+
+- **{{transformation_name}}**: {{transformation_description}}
+  {{/each}}
+
+### Data Exit Points
+
+{{#each exit_points}}
+
+- **{{exit_name}}**: {{exit_description}}
+  {{/each}}
+
+## Integration Points
+
+### APIs Consumed
+
+{{#each apis_consumed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Authentication: {{auth_requirement}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### APIs Exposed
+
+{{#each apis_exposed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Request: {{request_schema}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### Shared State
+
+{{#each shared_state}}
+
+- **{{state_name}}**: {{state_description}}
+  - Type: {{state_type}}
+  - Accessed By: {{accessors}}
+    {{/each}}
+
+### Events
+
+{{#each events}}
+
+- **{{event_name}}**: {{event_description}}
+  - Type: {{publish_or_subscribe}}
+  - Payload: {{payload_schema}}
+    {{/each}}
+
+### Database Access
+
+{{#each database_operations}}
+
+- **{{table_name}}**: {{operation_type}}
+  - Queries: {{query_patterns}}
+  - Indexes Used: {{indexes}}
+    {{/each}}
+
+## Dependency Graph
+
+{{dependency_graph_visualization}}
+
+### Entry Points (Not Imported by Others in Scope)
+
+{{#each entry_point_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Leaf Nodes (Don't Import Others in Scope)
+
+{{#each leaf_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Circular Dependencies
+
+{{#if has_circular_dependencies}}
+⚠️ Circular dependencies detected:
+{{#each circular_deps}}
+
+- {{cycle_description}}
+  {{/each}}
+  {{else}}
+  ✓ No circular dependencies detected
+  {{/if}}
+
+## Testing Analysis
+
+### Test Coverage Summary
+
+- **Statements:** {{statements_coverage}}%
+- **Branches:** {{branches_coverage}}%
+- **Functions:** {{functions_coverage}}%
+- **Lines:** {{lines_coverage}}%
+
+### Test Files
+
+{{#each test_files}}
+
+- **{{test_file_path}}**
+  - Tests: {{test_count}}
+  - Approach: {{test_approach}}
+  - Mocking Strategy: {{mocking_strategy}}
+    {{/each}}
+
+### Test Utilities Available
+
+{{#each test_utilities}}
+
+- `{{utility_name}}`: {{utility_description}}
+  {{/each}}
+
+### Testing Gaps
+
+{{#each testing_gaps}}
+
+- {{gap_description}}
+  {{/each}}
+
+## Related Code & Reuse Opportunities
+
+### Similar Features Elsewhere
+
+{{#each similar_features}}
+
+- **{{feature_name}}** (`{{feature_path}}`)
+  - Similarity: {{similarity_description}}
+  - Can Reference For: {{reference_use_case}}
+    {{/each}}
+
+### Reusable Utilities Available
+
+{{#each reusable_utilities}}
+
+- **{{utility_name}}** (`{{utility_path}}`)
+  - Purpose: {{utility_purpose}}
+  - How to Use: {{usage_example}}
+    {{/each}}
+
+### Patterns to Follow
+
+{{#each patterns_to_follow}}
+
+- **{{pattern_name}}**: Reference `{{reference_file}}` for implementation
+  {{/each}}
+
+## Implementation Notes
+
+### Code Quality Observations
+
+{{#each quality_observations}}
+
+- {{observation}}
+  {{/each}}
+
+### TODOs and Future Work
+
+{{#each all_todos}}
+
+- **{{file_path}}:{{line_number}}**: {{todo_text}}
+  {{/each}}
+
+### Known Issues
+
+{{#each known_issues}}
+
+- {{issue_description}}
+  {{/each}}
+
+### Optimization Opportunities
+
+{{#each optimizations}}
+
+- {{optimization_suggestion}}
+  {{/each}}
+
+### Technical Debt
+
+{{#each tech_debt_items}}
+
+- {{debt_description}}
+  {{/each}}
+
+## Modification Guidance
+
+### To Add New Functionality
+
+{{modification_guidance_add}}
+
+### To Modify Existing Functionality
+
+{{modification_guidance_modify}}
+
+### To Remove/Deprecate
+
+{{modification_guidance_remove}}
+
+### Testing Checklist for Changes
+
+{{#each testing_checklist_items}}
+
+- [ ] {{checklist_item}}
+      {{/each}}
+
+---
+
+_Generated by `document-project` workflow (deep-dive mode)_
+_Base Documentation: docs/index.md_
+_Scan Date: {{date}}_
+_Analysis Mode: Exhaustive_

.bmad/bmm/workflows/document-project/templates/index-template.md

@@ -0,0 +1,169 @@
+# {{project_name}} Documentation Index
+
+**Type:** {{repository_type}}{{#if is_multi_part}} with {{parts_count}} parts{{/if}}
+**Primary Language:** {{primary_language}}
+**Architecture:** {{architecture_type}}
+**Last Updated:** {{date}}
+
+## Project Overview
+
+{{project_description}}
+
+{{#if is_multi_part}}
+
+## Project Structure
+
+This project consists of {{parts_count}} parts:
+
+{{#each project_parts}}
+
+### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+  {{/each}}
+
+## Cross-Part Integration
+
+{{integration_summary}}
+
+{{/if}}
+
+## Quick Reference
+
+{{#if is_single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+- **Database:** {{database}}
+- **Deployment:** {{deployment_platform}}
+  {{else}}
+  {{#each project_parts}}
+
+### {{part_name}} Quick Ref
+
+- **Stack:** {{tech_stack_summary}}
+- **Entry:** {{entry_point}}
+- **Pattern:** {{architecture_pattern}}
+  {{/each}}
+  {{/if}}
+
+## Generated Documentation
+
+### Core Documentation
+
+- [Project Overview](./project-overview.md) - Executive summary and high-level architecture
+- [Source Tree Analysis](./source-tree-analysis.md) - Annotated directory structure
+
+{{#if is_single_part}}
+
+- [Architecture](./architecture.md) - Detailed technical architecture
+- [Component Inventory](./component-inventory.md) - Catalog of major components{{#if has_ui_components}} and UI elements{{/if}}
+- [Development Guide](./development-guide.md) - Local setup and development workflow
+  {{#if has_api_docs}}- [API Contracts](./api-contracts.md) - API endpoints and schemas{{/if}}
+  {{#if has_data_models}}- [Data Models](./data-models.md) - Database schema and models{{/if}}
+  {{else}}
+
+### Part-Specific Documentation
+
+{{#each project_parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- [Architecture](./architecture-{{part_id}}.md) - Technical architecture for {{part_name}}
+  {{#if has_components}}- [Components](./component-inventory-{{part_id}}.md) - Component catalog{{/if}}
+- [Development Guide](./development-guide-{{part_id}}.md) - Setup and dev workflow
+  {{#if has_api}}- [API Contracts](./api-contracts-{{part_id}}.md) - API documentation{{/if}}
+  {{#if has_data}}- [Data Models](./data-models-{{part_id}}.md) - Data architecture{{/if}}
+  {{/each}}
+
+### Integration
+
+- [Integration Architecture](./integration-architecture.md) - How parts communicate
+- [Project Parts Metadata](./project-parts.json) - Machine-readable structure
+  {{/if}}
+
+### Optional Documentation
+
+{{#if has_deployment_guide}}- [Deployment Guide](./deployment-guide.md) - Deployment process and infrastructure{{/if}}
+{{#if has_contribution_guide}}- [Contribution Guide](./contribution-guide.md) - Contributing guidelines and standards{{/if}}
+
+## Existing Documentation
+
+{{#if has_existing_docs}}
+{{#each existing_docs}}
+
+- [{{title}}]({{path}}) - {{description}}
+  {{/each}}
+  {{else}}
+  No existing documentation files were found in the project.
+  {{/if}}
+
+## Getting Started
+
+{{#if is_single_part}}
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Setup
+
+```bash
+{{setup_commands}}
+```
+
+### Run Locally
+
+```bash
+{{run_commands}}
+```
+
+### Run Tests
+
+```bash
+{{test_commands}}
+```
+
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Setup
+
+**Prerequisites:** {{prerequisites}}
+
+**Install & Run:**
+
+```bash
+cd {{root_path}}
+{{setup_command}}
+{{run_command}}
+```
+
+{{/each}}
+{{/if}}
+
+## For AI-Assisted Development
+
+This documentation was generated specifically to enable AI agents to understand and extend this codebase.
+
+### When Planning New Features:
+
+**UI-only features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{ui_part_id}}.md`, `component-inventory-{{ui_part_id}}.md`{{else}}→ Reference: `architecture.md`, `component-inventory.md`{{/if}}
+
+**API/Backend features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{api_part_id}}.md`, `api-contracts-{{api_part_id}}.md`, `data-models-{{api_part_id}}.md`{{else}}→ Reference: `architecture.md`{{#if has_api_docs}}, `api-contracts.md`{{/if}}{{#if has_data_models}}, `data-models.md`{{/if}}{{/if}}
+
+**Full-stack features:**
+→ Reference: All architecture docs{{#if is_multi_part}} + `integration-architecture.md`{{/if}}
+
+**Deployment changes:**
+{{#if has_deployment_guide}}→ Reference: `deployment-guide.md`{{else}}→ Review CI/CD configs in project{{/if}}
+
+---
+
+_Documentation generated by BMAD Method `document-project` workflow_

.bmad/bmm/workflows/document-project/templates/project-overview-template.md

@@ -0,0 +1,103 @@
+# {{project_name}} - Project Overview
+
+**Date:** {{date}}
+**Type:** {{project_type}}
+**Architecture:** {{architecture_type}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## Project Classification
+
+- **Repository Type:** {{repository_type}}
+- **Project Type(s):** {{project_types_list}}
+- **Primary Language(s):** {{primary_languages}}
+- **Architecture Pattern:** {{architecture_pattern}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project consists of {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Purpose:** {{purpose}}
+- **Tech Stack:** {{tech_stack}}
+  {{/each}}
+
+### How Parts Integrate
+
+{{integration_description}}
+{{/if}}
+
+## Technology Stack Summary
+
+{{#if is_single_part}}
+{{technology_table}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Stack
+
+{{technology_table}}
+{{/each}}
+{{/if}}
+
+## Key Features
+
+{{key_features}}
+
+## Architecture Highlights
+
+{{architecture_highlights}}
+
+## Development Overview
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Getting Started
+
+{{getting_started_summary}}
+
+### Key Commands
+
+{{#if is_single_part}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+- **Build:** `{{build_command}}`
+- **Test:** `{{test_command}}`
+  {{else}}
+  {{#each project_parts}}
+
+#### {{part_name}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+  {{/each}}
+  {{/if}}
+
+## Repository Structure
+
+{{repository_structure_summary}}
+
+## Documentation Map
+
+For detailed information, see:
+
+- [index.md](./index.md) - Master documentation index
+- [architecture.md](./architecture{{#if is_multi_part}}-{part_id}{{/if}}.md) - Detailed architecture
+- [source-tree-analysis.md](./source-tree-analysis.md) - Directory structure
+- [development-guide.md](./development-guide{{#if is_multi_part}}-{part_id}{{/if}}.md) - Development workflow
+
+---
+
+_Generated using BMAD Method `document-project` workflow_

.bmad/bmm/workflows/document-project/templates/project-scan-report-schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Project Scan Report Schema",
+  "description": "State tracking file for document-project workflow resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow",
+      "example": "1.2.0"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed (if finished)"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level (deep_dive mode always uses exhaustive)"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "output_folder": {
+      "type": "string",
+      "description": "Absolute path to output folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier (e.g., 'step_1', 'step_2')"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only (detailed findings purged after writing)",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "description": "For deep/exhaustive scans: subfolders processed",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed (for deep_dive mode)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

.bmad/bmm/workflows/document-project/templates/source-tree-template.md

@@ -0,0 +1,135 @@
+# {{project_name}} - Source Tree Analysis
+
+**Date:** {{date}}
+
+## Overview
+
+{{source_tree_overview}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project is organized into {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+- **{{part_name}}** (`{{root_path}}`): {{purpose}}
+  {{/each}}
+  {{/if}}
+
+## Complete Directory Structure
+
+```
+{{complete_source_tree}}
+```
+
+## Critical Directories
+
+{{#each critical_folders}}
+
+### `{{folder_path}}`
+
+{{description}}
+
+**Purpose:** {{purpose}}
+**Contains:** {{contents_summary}}
+{{#if entry_points}}**Entry Points:** {{entry_points}}{{/if}}
+{{#if integration_note}}**Integration:** {{integration_note}}{{/if}}
+
+{{/each}}
+
+{{#if is_multi_part}}
+
+## Part-Specific Trees
+
+{{#each project_parts}}
+
+### {{part_name}} Structure
+
+```
+{{source_tree}}
+```
+
+**Key Directories:**
+{{#each critical_directories}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+{{/each}}
+
+## Integration Points
+
+{{#each integration_points}}
+
+### {{from_part}} → {{to_part}}
+
+- **Location:** `{{integration_path}}`
+- **Type:** {{integration_type}}
+- **Details:** {{details}}
+  {{/each}}
+
+{{/if}}
+
+## Entry Points
+
+{{#if is_single_part}}
+
+- **Main Entry:** `{{main_entry_point}}`
+  {{#if additional_entry_points}}
+- **Additional:**
+  {{#each additional_entry_points}}
+  - `{{path}}`: {{description}}
+    {{/each}}
+    {{/if}}
+    {{else}}
+    {{#each project_parts}}
+
+### {{part_name}}
+
+- **Entry Point:** `{{entry_point}}`
+- **Bootstrap:** {{bootstrap_description}}
+  {{/each}}
+  {{/if}}
+
+## File Organization Patterns
+
+{{file_organization_patterns}}
+
+## Key File Types
+
+{{#each file_type_patterns}}
+
+### {{file_type}}
+
+- **Pattern:** `{{pattern}}`
+- **Purpose:** {{purpose}}
+- **Examples:** {{examples}}
+  {{/each}}
+
+## Asset Locations
+
+{{#if has_assets}}
+{{#each asset_locations}}
+
+- **{{asset_type}}**: `{{location}}` ({{file_count}} files, {{total_size}})
+  {{/each}}
+  {{else}}
+  No significant assets detected.
+  {{/if}}
+
+## Configuration Files
+
+{{#each config_files}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+## Notes for Development
+
+{{development_notes}}
+
+---
+
+_Generated using BMAD Method `document-project` workflow_

.bmad/bmm/workflows/document-project/workflow.yaml

@@ -0,0 +1,34 @@
+# Document Project Workflow Configuration
+name: "document-project"
+version: "1.2.0"
+description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development"
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/document-project"
+template: false # This is an action workflow with multiple output files
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Required data files - CRITICAL for project type detection and documentation requirements
+documentation_requirements_csv: "{installed_path}/documentation-requirements.csv"
+
+# Optional input - project root to scan (defaults to current working directory)
+recommended_inputs:
+  - project_root: "User will specify or use current directory"
+  - existing_readme: "README.md at project root (if exists)"
+  - project_config: "package.json, go.mod, requirements.txt, etc. (auto-detected)"
+# Output configuration - Multiple files generated in output folder
+# Primary output: {output_folder}/index.md
+# Additional files generated by sub-workflows based on project structure
+
+standalone: true

.bmad/bmm/workflows/document-project/workflows/deep-dive-instructions.md

@@ -0,0 +1,298 @@
+# Deep-Dive Documentation Instructions
+
+<workflow>
+
+<critical>This workflow performs exhaustive deep-dive documentation of specific areas</critical>
+<critical>Called by: ../document-project/instructions.md router</critical>
+<critical>Handles: deep_dive mode only</critical>
+
+<step n="13" goal="Deep-dive documentation of specific area" if="workflow_mode == deep_dive">
+<critical>Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.</critical>
+<action>Load existing project structure from index.md and project-parts.json (if exists)</action>
+<action>Load source tree analysis to understand available areas</action>
+
+<step n="13a" goal="Identify area for deep-dive">
+  <action>Analyze existing documentation to suggest deep-dive options</action>
+
+<ask>What area would you like to deep-dive into?
+
+**Suggested Areas Based on Project Structure:**
+
+{{#if has_api_routes}}
+
+### API Routes ({{api_route_count}} endpoints found)
+
+{{#each api_route_groups}}
+{{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_feature_modules}}
+
+### Feature Modules ({{feature_count}} features)
+
+{{#each feature_modules}}
+{{module_index}}. {{module_name}} - {{file_count}} files in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_ui_components}}
+
+### UI Component Areas
+
+{{#each component_groups}}
+{{group_index}}. {{group_name}} - {{component_count}} components in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_services}}
+
+### Services/Business Logic
+
+{{#each service_groups}}
+{{service_index}}. {{service_name}} - `{{path}}`
+{{/each}}
+{{/if}}
+
+**Or specify custom:**
+
+- Folder path (e.g., "client/src/features/dashboard")
+- File path (e.g., "server/src/api/users.ts")
+- Feature name (e.g., "authentication system")
+
+Enter your choice (number or custom path):
+</ask>
+
+<action>Parse user input to determine: - target_type: "folder" | "file" | "feature" | "api_group" | "component_group" - target_path: Absolute path to scan - target_name: Human-readable name for documentation - target_scope: List of all files to analyze
+</action>
+
+<action>Store as {{deep_dive_target}}</action>
+
+<action>Display confirmation:
+Target: {{target_name}}
+Type: {{target_type}}
+Path: {{target_path}}
+Estimated files to analyze: {{estimated_file_count}}
+
+This will read EVERY file in this area. Proceed? [y/n]
+</action>
+
+<action if="user confirms 'n'">Return to Step 13a (select different area)</action>
+</step>
+
+<step n="13b" goal="Comprehensive exhaustive scan of target area">
+  <action>Set scan_mode = "exhaustive"</action>
+  <action>Initialize file_inventory = []</action>
+  <critical>You must read every line of every file in scope and capture a plain-language explanation (what the file does, side effects, why it matters) that future developer agents can act on. No shortcuts.</critical>
+
+  <check if="target_type == folder">
+    <action>Get complete recursive file list from {{target_path}}</action>
+    <action>Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map</action>
+    <action>For EVERY remaining file in folder:
+      - Read complete file contents (all lines)
+      - Extract all exports (functions, classes, types, interfaces, constants)
+      - Extract all imports (dependencies)
+      - Identify purpose from comments and code structure
+      - Write 1-2 sentences (minimum) in natural language describing behaviour, side effects, assumptions, and anything a developer must know before modifying the file
+      - Extract function signatures with parameter types and return types
+      - Note any TODOs, FIXMEs, or comments
+      - Identify patterns (hooks, components, services, controllers, etc.)
+      - Capture per-file contributor guidance: `contributor_note`, `risks`, `verification_steps`, `suggested_tests`
+      - Store in file_inventory
+    </action>
+  </check>
+
+  <check if="target_type == file">
+    <action>Read complete file at {{target_path}}</action>
+    <action>Extract all information as above</action>
+    <action>Read all files it imports (follow import chain 1 level deep)</action>
+    <action>Find all files that import this file (dependents via grep)</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == api_group">
+    <action>Identify all route/controller files in API group</action>
+    <action>Read all route handlers completely</action>
+    <action>Read associated middleware, controllers, services</action>
+    <action>Read data models and schemas used</action>
+    <action>Extract complete request/response schemas</action>
+    <action>Document authentication and authorization requirements</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == feature">
+    <action>Search codebase for all files related to feature name</action>
+    <action>Include: UI components, API endpoints, models, services, tests</action>
+    <action>Read each file completely</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == component_group">
+    <action>Get all component files in group</action>
+    <action>Read each component completely</action>
+    <action>Extract: Props interfaces, hooks used, child components, state management</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+<action>For each file in file\*inventory, document: - **File Path:** Full path - **Purpose:** What this file does (1-2 sentences) - **Lines of Code:** Total LOC - **Exports:** Complete list with signatures
+
+- Functions: `functionName(param: Type): ReturnType` - Description
+  _ Classes: `ClassName` - Description with key methods
+  _ Types/Interfaces: `TypeName` - Description
+  \_ Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
+  </action>
+
+<template-output>comprehensive_file_inventory</template-output>
+</step>
+
+<step n="13c" goal="Analyze relationships and data flow">
+  <action>Build dependency graph for scanned area:
+    - Create graph with files as nodes
+    - Add edges for import relationships
+    - Identify circular dependencies if any
+    - Find entry points (files not imported by others in scope)
+    - Find leaf nodes (files that don't import others in scope)
+  </action>
+
+<action>Trace data flow through the system: - Follow function calls and data transformations - Track API calls and their responses - Document state updates and propagation - Map database queries and mutations
+</action>
+
+<action>Identify integration points: - External APIs consumed - Internal APIs/services called - Shared state accessed - Events published/subscribed - Database tables accessed
+</action>
+
+<template-output>dependency_graph</template-output>
+<template-output>data_flow_analysis</template-output>
+<template-output>integration_points</template-output>
+</step>
+
+<step n="13d" goal="Find related code and similar patterns">
+  <action>Search codebase OUTSIDE scanned area for:
+    - Similar file/folder naming patterns
+    - Similar function signatures
+    - Similar component structures
+    - Similar API patterns
+    - Reusable utilities that could be used
+  </action>
+
+<action>Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply
+</action>
+
+<action>Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere
+</action>
+
+<template-output>related_code_references</template-output>
+<template-output>reuse_opportunities</template-output>
+</step>
+
+<step n="13e" goal="Generate comprehensive deep-dive documentation">
+  <action>Create documentation filename: deep-dive-{{sanitized_target_name}}.md</action>
+  <action>Aggregate contributor insights across files:
+    - Combine unique risk/gotcha notes into {{risks_notes}}
+    - Combine verification steps developers should run before changes into {{verification_steps}}
+    - Combine recommended test commands into {{suggested_tests}}
+  </action>
+
+<action>Load complete deep-dive template from: {installed_path}/templates/deep-dive-template.md</action>
+<action>Fill template with all collected data from steps 13b-13d</action>
+<action>Write filled template to: {output_folder}/deep-dive-{{sanitized_target_name}}.md</action>
+<action>Validate deep-dive document completeness</action>
+
+<template-output>deep_dive_documentation</template-output>
+
+<action>Update state file: - Add to deep_dive_targets array: {"target_name": "{{target_name}}", "target_path": "{{target_path}}", "files_analyzed": {{file_count}}, "output_file": "deep-dive-{{sanitized_target_name}}.md", "timestamp": "{{now}}"} - Add output to outputs_generated - Update last_updated timestamp
+</action>
+</step>
+
+<step n="13f" goal="Update master index with deep-dive link">
+  <action>Read existing index.md</action>
+
+<action>Check if "Deep-Dive Documentation" section exists</action>
+
+  <check if="section does not exist">
+    <action>Add new section after "Generated Documentation":
+
+## Deep-Dive Documentation
+
+Detailed exhaustive analysis of specific areas:
+
+    </action>
+
+  </check>
+
+<action>Add link to new deep-dive doc:
+
+- [{{target_name}} Deep-Dive](./deep-dive-{{sanitized_target_name}}.md) - Comprehensive analysis of {{target_description}} ({{file_count}} files, {{total_loc}} LOC) - Generated {{date}}
+  </action>
+
+  <action>Update index metadata:
+  Last Updated: {{date}}
+  Deep-Dives: {{deep_dive_count}}
+  </action>
+
+  <action>Save updated index.md</action>
+
+  <template-output>updated_index</template-output>
+  </step>
+
+<step n="13g" goal="Offer to continue or complete">
+  <action>Display summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Deep-Dive Documentation Complete! ✓
+
+**Generated:** {output_folder}/deep-dive-{{target_name}}.md
+**Files Analyzed:** {{file_count}}
+**Lines of Code Scanned:** {{total_loc}}
+**Time Taken:** ~{{duration}}
+
+**Documentation Includes:**
+
+- Complete file inventory with all exports
+- Dependency graph and data flow
+- Integration points and API contracts
+- Testing analysis and coverage
+- Related code and reuse opportunities
+- Implementation guidance
+
+**Index Updated:** {output_folder}/index.md now includes link to this deep-dive
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<ask>Would you like to:
+
+1. **Deep-dive another area** - Analyze another feature/module/folder
+2. **Finish** - Complete workflow
+
+Your choice [1/2]:
+</ask>
+
+  <action if="user selects 1">
+    <action>Clear current deep_dive_target</action>
+    <action>Go to Step 13a (select new area)</action>
+  </action>
+
+  <action if="user selects 2">
+    <action>Display final message:
+
+All deep-dive documentation complete!
+
+**Master Index:** {output_folder}/index.md
+**Deep-Dives Generated:** {{deep_dive_count}}
+
+These comprehensive docs are now ready for:
+
+- Architecture review
+- Implementation planning
+- Code understanding
+- Brownfield PRD creation
+
+Thank you for using the document-project workflow!
+</action>
+<action>Exit workflow</action>
+</action>
+</step>
+</step>
+
+</workflow>

.bmad/bmm/workflows/document-project/workflows/deep-dive.yaml

@@ -0,0 +1,31 @@
+# Deep-Dive Documentation Workflow Configuration
+name: "document-project-deep-dive"
+description: "Exhaustive deep-dive documentation of specific project areas"
+author: "BMad"
+
+# This is a sub-workflow called by document-project/workflow.yaml
+parent_workflow: "{project-root}/.bmad/bmm/workflows/document-project/workflow.yaml"
+
+# Critical variables inherited from parent
+config_source: "{project-root}/.bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/.bmad/bmm/workflows/document-project/workflows"
+template: false # Action workflow
+instructions: "{installed_path}/deep-dive-instructions.md"
+validation: "{project-root}/.bmad/bmm/workflows/document-project/checklist.md"
+
+# Templates
+deep_dive_template: "{project-root}/.bmad/bmm/workflows/document-project/templates/deep-dive-template.md"
+
+# Runtime inputs (passed from parent workflow)
+workflow_mode: "deep_dive"
+scan_level: "exhaustive" # Deep-dive always uses exhaustive scan
+project_root_path: ""
+existing_index_path: "" # Path to existing index.md
+
+# Configuration
+autonomous: false # Requires user input to select target area