bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.1

package/src/modules/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.

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

@@ -0,0 +1,318 @@
+# Decision Architecture Workflow
+
+## Overview
+
+The Decision Architecture workflow is a complete reimagining of how architectural decisions are made in the BMAD Method. Instead of template-driven documentation, this workflow facilitates an intelligent conversation that produces a **decision-focused architecture document** optimized for preventing AI agent conflicts during implementation.
+
+## Core Philosophy
+
+**The Problem**: When multiple AI agents implement different parts of a system, they make conflicting technical decisions leading to incompatible implementations.
+
+**The Solution**: A "consistency contract" that documents all critical technical decisions upfront, ensuring every agent follows the same patterns and uses the same technologies.
+
+## Key Features
+
+### 1. Starter Template Intelligence ⭐ NEW
+
+- Discovers relevant starter templates (create-next-app, create-t3-app, etc.)
+- Considers UX requirements when selecting templates (animations, accessibility, etc.)
+- Searches for current CLI options and defaults
+- Documents decisions made BY the starter template
+- Makes remaining architectural decisions around the starter foundation
+- First implementation story becomes "initialize with starter command"
+
+### 2. Adaptive Facilitation
+
+- Adjusts conversation style based on user skill level (beginner/intermediate/expert)
+- Experts get rapid, technical discussions
+- Beginners receive education and protection from complexity
+- Everyone produces the same high-quality output
+
+### 3. Dynamic Version Verification
+
+- NEVER trusts hardcoded version numbers
+- Uses WebSearch to find current stable versions
+- Verifies versions during the conversation
+- Documents only verified, current versions
+
+### 4. Intelligent Discovery
+
+- No rigid project type templates
+- Analyzes PRD to identify which decisions matter for THIS project
+- Uses knowledge base of decisions and patterns
+- Scales to infinite project types
+
+### 5. Collaborative Decision Making
+
+- Facilitates discussion for each critical decision
+- Presents options with trade-offs
+- Integrates advanced elicitation for innovative approaches
+- Ensures decisions are coherent and compatible
+
+### 6. Consistent Output
+
+- Structured decision collection during conversation
+- Strict document generation from collected decisions
+- Validated against hard requirements
+- Optimized for AI agent consumption
+
+## Workflow Structure
+
+```
+Step 0: Validate workflow and extract project configuration
+Step 0.5: Validate workflow sequencing
+Step 1: Load PRD and understand project context
+Step 2: Discover and evaluate starter templates ⭐ NEW
+Step 3: Adapt facilitation style and identify remaining decisions
+Step 4: Facilitate collaborative decision making (with version verification)
+Step 5: Address cross-cutting concerns
+Step 6: Define project structure and boundaries
+Step 7: Design novel architectural patterns (when needed) ⭐ NEW
+Step 8: Define implementation patterns to prevent agent conflicts
+Step 9: Validate architectural coherence
+Step 10: Generate decision architecture document (with initialization commands)
+Step 11: Validate document completeness
+Step 12: Final review and update workflow status
+```
+
+## Files in This Workflow
+
+- **workflow.yaml** - Configuration and metadata
+- **instructions.md** - The adaptive facilitation flow
+- **decision-catalog.yaml** - Knowledge base of all architectural decisions
+- **architecture-patterns.yaml** - Common patterns identified from requirements
+- **pattern-categories.csv** - Pattern principles that teach LLM what needs defining
+- **checklist.md** - Validation requirements for the output document
+- **architecture-template.md** - Strict format for the final document
+
+## How It's Different from Old architecture
+
+| Aspect               | Old Workflow                                 | New Workflow                                    |
+| -------------------- | -------------------------------------------- | ----------------------------------------------- |
+| **Approach**         | Template-driven                              | Conversation-driven                             |
+| **Project Types**    | 11 rigid types with 22+ files                | Infinite flexibility with intelligent discovery |
+| **User Interaction** | Output sections with "Continue?"             | Collaborative decision facilitation             |
+| **Skill Adaptation** | One-size-fits-all                            | Adapts to beginner/intermediate/expert          |
+| **Decision Making**  | Late in process (Step 5)                     | Upfront and central focus                       |
+| **Output**           | Multiple documents including faux tech-specs | Single decision-focused architecture            |
+| **Time**             | Confusing and slow                           | 30-90 minutes depending on skill level          |
+| **Elicitation**      | Never used                                   | Integrated at decision points                   |
+
+## Expected Inputs
+
+- **PRD** (Product Requirements Document) with:
+  - Functional Requirements
+  - Non-Functional Requirements
+  - Performance and compliance needs
+
+- **Epics** file with:
+  - User stories
+  - Acceptance criteria
+  - Dependencies
+
+- **UX Spec** (Optional but valuable) with:
+  - Interface designs and interaction patterns
+  - Accessibility requirements (WCAG levels)
+  - Animation and transition needs
+  - Platform-specific UI requirements
+  - Performance expectations for interactions
+
+## Output Document
+
+A single `architecture.md` file containing:
+
+- Executive summary (2-3 sentences)
+- Project initialization command (if using starter template)
+- Decision summary table with verified versions and epic mapping
+- Complete project structure
+- Integration specifications
+- Consistency rules for AI agents
+
+## How Novel Pattern Design Works
+
+Step 7 handles unique or complex patterns that need to be INVENTED:
+
+1. **Detection**:
+   The workflow analyzes the PRD for concepts that don't have standard solutions:
+   - Novel interaction patterns (e.g., "swipe to match" when Tinder doesn't exist)
+   - Complex multi-epic workflows (e.g., "viral invitation system")
+   - Unique data relationships (e.g., "social graph" before Facebook)
+   - New paradigms (e.g., "ephemeral messages" before Snapchat)
+
+2. **Design Collaboration**:
+   Instead of just picking technologies, the workflow helps DESIGN the solution:
+   - Identifies the core problem to solve
+   - Explores different approaches with the user
+   - Documents how components interact
+   - Creates sequence diagrams for complex flows
+   - Uses elicitation to find innovative solutions
+
+3. **Documentation**:
+   Novel patterns become part of the architecture with:
+   - Pattern name and purpose
+   - Component interactions
+   - Data flow diagrams
+   - Which epics/stories are affected
+   - Implementation guidance for agents
+
+4. **Example**:
+   ```
+   PRD: "Users can create 'circles' of friends with overlapping membership"
+   ↓
+   Workflow detects: This is a novel social structure pattern
+   ↓
+   Designs with user: Circle membership model, permission cascading, UI patterns
+   ↓
+   Documents: "Circle Pattern" with component design and data flow
+   ↓
+   All agents understand how to implement circle-related features consistently
+   ```
+
+## How Implementation Patterns Work
+
+Step 8 prevents agent conflicts by defining patterns for consistency:
+
+1. **The Core Principle**:
+
+   > "Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture"
+
+   The LLM asks: "What could an agent encounter where they'd have to guess?"
+
+2. **Pattern Categories** (principles, not prescriptions):
+   - **Naming**: How things are named (APIs, database fields, files)
+   - **Structure**: How things are organized (folders, modules, layers)
+   - **Format**: How data is formatted (JSON structures, responses)
+   - **Communication**: How components talk (events, messages, protocols)
+   - **Lifecycle**: How states change (workflows, transitions)
+   - **Location**: Where things go (URLs, paths, storage)
+   - **Consistency**: Cross-cutting concerns (dates, errors, logs)
+
+3. **LLM Intelligence**:
+   - Uses the principle to identify patterns beyond the 7 categories
+   - Figures out what specific patterns matter for chosen tech
+   - Only asks about patterns that could cause conflicts
+   - Skips obvious patterns that the tech choice determines
+
+4. **Example**:
+   ```
+   Tech chosen: REST API + PostgreSQL + React
+   ↓
+   LLM identifies needs:
+   - REST: URL structure, response format, status codes
+   - PostgreSQL: table naming, column naming, FK patterns
+   - React: component structure, state management, test location
+   ↓
+   Facilitates each with user
+   ↓
+   Documents as Implementation Patterns in architecture
+   ```
+
+## How Starter Templates Work
+
+When the workflow detects a project type that has a starter template:
+
+1. **Discovery**: Searches for relevant starter templates based on PRD
+2. **Investigation**: Looks up current CLI options and defaults
+3. **Presentation**: Shows user what the starter provides
+4. **Integration**: Documents starter decisions as "PROVIDED BY STARTER"
+5. **Continuation**: Only asks about decisions NOT made by starter
+6. **Documentation**: Includes exact initialization command in architecture
+
+### Example Flow
+
+```
+PRD says: "Next.js web application with authentication"
+↓
+Workflow finds: create-next-app and create-t3-app
+↓
+User chooses: create-t3-app (includes auth setup)
+↓
+Starter provides: Next.js, TypeScript, tRPC, Prisma, NextAuth, Tailwind
+↓
+Workflow only asks about: Database choice, deployment target, additional services
+↓
+First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma"
+```
+
+## Usage
+
+```bash
+# In your BMAD-enabled project
+workflow architecture
+```
+
+The AI agent will:
+
+1. Load your PRD and epics
+2. Identify critical decisions needed
+3. Facilitate discussion on each decision
+4. Generate a comprehensive architecture document
+5. Validate completeness
+
+## Design Principles
+
+1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates
+2. **Intelligence over Templates** - Use AI understanding rather than rigid structures
+3. **Decisions over Details** - Focus on what prevents agent conflicts, not implementation minutiae
+4. **Adaptation over Uniformity** - Meet users where they are while ensuring quality output
+5. **Collaboration over Output** - The conversation matters as much as the document
+
+## For Developers
+
+This workflow assumes:
+
+- Single developer + AI agents (not teams)
+- Speed matters (decisions in minutes, not days)
+- AI agents need clear constraints to prevent conflicts
+- The architecture document is for agents, not humans
+
+## Migration from architecture
+
+Projects using the old `architecture` workflow should:
+
+1. Complete any in-progress architecture work
+2. Use `architecture` for new projects
+3. The old workflow remains available but is deprecated
+
+## Version
+
+1.3.2 - UX specification integration and fuzzy file matching
+
+- Added UX spec as optional input with fuzzy file matching
+- Updated workflow.yaml with input file references
+- Starter template selection now considers UX requirements
+- Added UX alignment validation to checklist
+- Instructions use variable references for flexible file names
+
+  1.3.1 - Workflow refinement and standardization
+
+- Added workflow status checking at start (Steps 0 and 0.5)
+- Added workflow status updating at end (Step 12)
+- Reorganized step numbering for clarity (removed fractional steps)
+- Enhanced with intent-based approach throughout
+- Improved cohesiveness across all workflow components
+
+  1.3.0 - Novel pattern design for unique architectures
+
+- Added novel pattern design (now Step 7, formerly Step 5.3)
+- Detects novel concepts in PRD that need architectural invention
+- Facilitates design collaboration with sequence diagrams
+- Uses elicitation for innovative approaches
+- Documents custom patterns for multi-epic consistency
+
+  1.2.0 - Implementation patterns for agent consistency
+
+- Added implementation patterns (now Step 8, formerly Step 5.5)
+- Created principle-based pattern-categories.csv (7 principles, not 118 prescriptions)
+- Core principle: "What could agents decide differently?"
+- LLM uses principle to identify patterns beyond the categories
+- Prevents agent conflicts through intelligent pattern discovery
+
+  1.1.0 - Enhanced with starter template discovery and version verification
+
+- Added intelligent starter template detection and integration (now Step 2)
+- Added dynamic version verification via web search
+- Starter decisions are documented as "PROVIDED BY STARTER"
+- First implementation story uses starter initialization command
+
+  1.0.0 - Initial release replacing architecture workflow

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

@@ -0,0 +1,54 @@
+# 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)"
+
+# Input file references (fuzzy matched from output folder)
+prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
+epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md"
+ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md"
+
+# 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

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/README.md

@@ -0,0 +1,177 @@
+# Implementation Ready Check Workflow
+
+## Overview
+
+The Implementation Ready Check workflow provides a systematic validation of all planning and solutioning artifacts before transitioning from Phase 3 (Solutioning) to Phase 4 (Implementation) in the BMad Method. This workflow ensures that PRDs, architecture documents, and story breakdowns are properly aligned with no critical gaps or contradictions.
+
+## Purpose
+
+This workflow is designed to:
+
+- **Validate Completeness**: Ensure all required planning documents exist and are complete
+- **Verify Alignment**: Check that PRD, architecture, and stories are cohesive and aligned
+- **Identify Gaps**: Detect missing stories, unaddressed requirements, or sequencing issues
+- **Assess Risks**: Find contradictions, conflicts, or potential implementation blockers
+- **Provide Confidence**: Give teams confidence that planning is solid before starting development
+
+## When to Use
+
+This workflow should be invoked:
+
+- At the end of Phase 3 (Solutioning) for Level 2-4 projects
+- Before beginning Phase 4 (Implementation)
+- After significant planning updates or architectural changes
+- When validating readiness for Level 0-1 projects (simplified validation)
+
+## Project Level Adaptations
+
+The workflow adapts its validation based on project level:
+
+### Level 0-1 Projects
+
+- Validates tech spec and simple stories only
+- Checks internal consistency and basic coverage
+- Lighter validation appropriate for simple projects
+
+### Level 2 Projects
+
+- Validates PRD, tech spec (with embedded architecture), and stories
+- Ensures PRD requirements are fully covered
+- Verifies technical approach aligns with business goals
+
+### Level 3-4 Projects
+
+- Full validation of PRD, architecture document, and comprehensive stories
+- Deep cross-reference checking across all artifacts
+- Validates architectural decisions don't introduce scope creep
+- Checks UX artifacts if applicable
+
+## How to Invoke
+
+### Via Scrum Master Agent
+
+```
+*solutioning-gate-check
+```
+
+### Direct Workflow Invocation
+
+```
+workflow solutioning-gate-check
+```
+
+## Expected Inputs
+
+The workflow will automatically search your project's output folder for:
+
+- Product Requirements Documents (PRD)
+- Architecture documents
+- Technical Specifications
+- Epic and Story breakdowns
+- UX artifacts (if applicable)
+
+No manual input file specification needed - the workflow discovers documents automatically.
+
+## Generated Output
+
+The workflow produces a comprehensive **Implementation Readiness Report** containing:
+
+1. **Executive Summary** - Overall readiness status
+2. **Document Inventory** - What was found and reviewed
+3. **Alignment Validation** - Cross-reference analysis results
+4. **Gap Analysis** - Missing items and risks identified
+5. **Findings by Severity** - Critical, High, Medium, Low issues
+6. **Recommendations** - Specific actions to address issues
+7. **Readiness Decision** - Ready, Ready with Conditions, or Not Ready
+
+Output Location: `{output_folder}/implementation-readiness-report-{date}.md`
+
+## Workflow Steps
+
+1. **Initialize** - Get current workflow status and project level
+2. **Document Discovery** - Find all planning artifacts
+3. **Deep Analysis** - Extract requirements, decisions, and stories
+4. **Cross-Reference Validation** - Check alignment between all documents
+5. **Gap and Risk Analysis** - Identify issues and conflicts
+6. **UX Validation** (optional) - Verify UX concerns are addressed
+7. **Generate Report** - Compile comprehensive readiness assessment
+8. **Status Update** (optional) - Offer to advance workflow to next phase
+
+## Validation Criteria
+
+The workflow uses systematic validation rules adapted to each project level:
+
+- **Document completeness and quality**
+- **Requirement to story traceability**
+- **Architecture to implementation alignment**
+- **Story sequencing and dependencies**
+- **Greenfield project setup coverage**
+- **Risk identification and mitigation**
+
+For projects using the new architecture workflow (decision-architecture.md), additional validations include:
+
+- **Implementation patterns defined for consistency**
+- **Technology versions verified and current**
+- **Starter template initialization as first story**
+- **UX specification alignment (if provided)**
+
+## Special Features
+
+### Intelligent Adaptation
+
+- Automatically adjusts validation based on project level
+- Recognizes when UX workflow is active
+- Handles greenfield vs. brownfield projects differently
+
+### Comprehensive Coverage
+
+- Validates not just presence but quality and alignment
+- Checks for both gaps and gold-plating
+- Ensures logical story sequencing
+
+### Actionable Output
+
+- Provides specific, actionable recommendations
+- Categorizes issues by severity
+- Includes positive findings and commendations
+
+## Integration with BMad Method
+
+This workflow integrates seamlessly with the BMad Method workflow system:
+
+- Uses workflow-status to understand project context
+- Can update workflow status to advance to next phase
+- Follows standard BMad document naming conventions
+- Searches standard output folders automatically
+
+## Troubleshooting
+
+### Documents Not Found
+
+- Ensure documents are in the configured output folder
+- Check that document names follow BMad conventions
+- Verify workflow-status is properly configured
+
+### Validation Too Strict
+
+- The workflow adapts to project level automatically
+- Level 0-1 projects get lighter validation
+- Consider if your project level is set correctly
+
+### Report Too Long
+
+- Focus on Critical and High priority issues first
+- Use the executive summary for quick decisions
+- Review detailed findings only for areas of concern
+
+## Support
+
+For issues or questions about this workflow:
+
+- Consult the BMad Method documentation
+- Check the SM agent for workflow guidance
+- Review validation-criteria.yaml for detailed rules
+
+---
+
+_This workflow is part of the BMad Method v6-alpha suite of planning and solutioning tools_