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

package/bmad/bmm/{workflows/3-solutioning/architecture/README.md → docs/workflow-architecture-reference.md}

@@ -1,15 +1,24 @@
-# Decision Architecture Workflow
+# Decision Architecture Workflow - Technical Reference
+
+**Module:** BMM (BMAD Method Module)
+**Type:** Solutioning 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
@@ -56,6 +65,8 @@ The Decision Architecture workflow is a complete reimagining of how architectura
 - Validated against hard requirements
 - Optimized for AI agent consumption
 
+---
+
 ## Workflow Structure
 
 ```
@@ -75,6 +86,8 @@ Step 11: Validate document completeness
 Step 12: Final review and update workflow status
 ```
 
+---
+
 ## Files in This Workflow
 
 - **workflow.yaml** - Configuration and metadata
@@ -85,6 +98,8 @@ Step 12: Final review and update workflow status
 - **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                                    |
@@ -98,6 +113,8 @@ Step 12: Final review and update workflow status
 | **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:
@@ -117,6 +134,8 @@ Step 12: Final review and update workflow status
   - Platform-specific UI requirements
   - Performance expectations for interactions
 
+---
+
 ## Output Document
 
 A single `architecture.md` file containing:
@@ -128,84 +147,100 @@ A single `architecture.md` file containing:
 - 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
-   ```
+### 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
-   ```
+### 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
 
@@ -234,6 +269,8 @@ Workflow only asks about: Database choice, deployment target, additional service
 First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma"
 ```
 
+---
+
 ## Usage
 
 ```bash
@@ -249,6 +286,8 @@ The AI agent will:
 4. Generate a comprehensive architecture document
 5. Validate completeness
 
+---
+
 ## Design Principles
 
 1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates
@@ -257,6 +296,8 @@ The AI agent will:
 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:
@@ -266,6 +307,8 @@ This workflow assumes:
 - 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:
@@ -274,9 +317,11 @@ Projects using the old `architecture` workflow should:
 2. Use `architecture` for new projects
 3. The old workflow remains available but is deprecated
 
-## Version
+---
+
+## Version History
 
-1.3.2 - UX specification integration and fuzzy file matching
+**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
@@ -284,7 +329,7 @@ Projects using the old `architecture` workflow should:
 - Added UX alignment validation to checklist
 - Instructions use variable references for flexible file names
 
-  1.3.1 - Workflow refinement and standardization
+**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)
@@ -292,7 +337,7 @@ Projects using the old `architecture` workflow should:
 - Enhanced with intent-based approach throughout
 - Improved cohesiveness across all workflow components
 
-  1.3.0 - Novel pattern design for unique architectures
+**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
@@ -300,7 +345,7 @@ Projects using the old `architecture` workflow should:
 - Uses elicitation for innovative approaches
 - Documents custom patterns for multi-epic consistency
 
-  1.2.0 - Implementation patterns for agent 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)
@@ -308,11 +353,19 @@ Projects using the old `architecture` workflow should:
 - 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
+**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
+**1.0.0** - Initial release replacing architecture workflow
+
+---
+
+**Related Documentation:**
+
+- [Solutioning Workflows](./workflows-solutioning.md)
+- [Planning Workflows](./workflows-planning.md)
+- [Scale Adaptive System](./scale-adaptive-system.md)

package/bmad/bmm/{workflows/document-project/README.md → docs/workflow-document-project-reference.md}

@@ -1,15 +1,18 @@
-# Document Project Workflow
+# Document Project Workflow - Technical Reference
 
-**Version:** 1.2.0
 **Module:** BMM (BMAD Method Module)
 **Type:** Action Workflow (Documentation Generator)
 
+---
+
 ## Purpose
 
 Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development. Generates a master index and multiple documentation files tailored to project structure and type.
 
 **NEW in v1.2.0:** Context-safe architecture with scan levels, resumability, and write-as-you-go pattern to prevent context exhaustion.
 
+---
+
 ## Key Features
 
 - **Multi-Project Type Support**: Handles web, backend, mobile, CLI, game, embedded, data, infra, library, desktop, and extension projects
@@ -23,6 +26,8 @@ Analyzes and documents brownfield projects by scanning codebase, architecture, a
 - **Architecture Matching**: Matches projects to 170+ architecture templates from the solutioning registry
 - **Brownfield PRD Ready**: Generates documentation specifically designed for AI agents planning new features
 
+---
+
 ## How to Invoke
 
 ```bash
@@ -35,6 +40,8 @@ Or from BMAD CLI:
 /bmad:bmm:workflows:document-project
 ```
 
+---
+
 ## Scan Levels (NEW in v1.2.0)
 
 Choose the right scan depth for your needs:
@@ -79,6 +86,8 @@ Choose the right scan depth for your needs:
 
 **Note:** Deep-dive mode ALWAYS uses exhaustive scan (no choice)
 
+---
+
 ## Resumability (NEW in v1.2.0)
 
 The workflow can be interrupted and resumed without losing progress:
@@ -110,6 +119,8 @@ Would you like to:
 Your choice [1/2/3]:
 ```
 
+---
+
 ## What It Does
 
 ### Step-by-Step Process
@@ -160,6 +171,8 @@ Your choice [1/2/3]:
 - `project-scan-report.json` - State file for resumability (NEW v1.2.0)
 - Additional conditional files per part (API, data models, etc.)
 
+---
+
 ## Data Files
 
 The workflow uses a single comprehensive CSV file:
@@ -175,6 +188,8 @@ The workflow uses a single comprehensive CSV file:
 - Self-contained: All project detection AND scanning requirements in one file
 - Architecture patterns inferred from tech stack (no external registry needed)
 
+---
+
 ## Use Cases
 
 ### Primary Use Case: Brownfield PRD Creation
@@ -197,6 +212,8 @@ PRD Workflow: Loads docs/index.md
 - **Technical Debt Assessment** - Identify patterns and anti-patterns
 - **Migration Planning** - Understand current state before refactoring
 
+---
+
 ## Requirements
 
 ### Recommended Inputs (Optional)
@@ -211,6 +228,8 @@ PRD Workflow: Loads docs/index.md
 - Code analysis
 - Git repository analysis (optional)
 
+---
+
 ## Configuration
 
 ### Default Output Location
@@ -225,6 +244,8 @@ Default: `/docs/` folder in project root
 - Add new project types to `project-types.csv`
 - Add new architecture templates to `registry.csv`
 
+---
+
 ## Example: Multi-Part Web App
 
 **Input:**
@@ -260,6 +281,8 @@ docs/
 └── project-parts.json
 ```
 
+---
+
 ## Example: Simple CLI Tool
 
 **Input:**
@@ -286,6 +309,8 @@ docs/
 └── source-tree-analysis.md
 ```
 
+---
+
 ## Deep-Dive Mode
 
 ### What is Deep-Dive Mode?
@@ -353,6 +378,8 @@ You can deep-dive multiple areas over time:
 
 All deep-dive docs are linked from the master index.
 
+---
+
 ## Validation
 
 The workflow includes a comprehensive 160+ point checklist covering:
@@ -365,6 +392,8 @@ The workflow includes a comprehensive 160+ point checklist covering:
 - Brownfield PRD readiness
 - Deep-dive completeness (if applicable)
 
+---
+
 ## Next Steps After Completion
 
 1. **Review** `docs/index.md` - Your master documentation index
@@ -372,6 +401,8 @@ The workflow includes a comprehensive 160+ point checklist covering:
 3. **Use for PRD** - Point brownfield PRD workflow to index.md
 4. **Maintain** - Re-run workflow when architecture changes significantly
 
+---
+
 ## File Structure
 
 ```
@@ -387,6 +418,8 @@ document-project/
 └── README.md                        # This file
 ```
 
+---
+
 ## Troubleshooting
 
 **Issue: Project type not detected correctly**
@@ -405,6 +438,8 @@ document-project/
 
 - Solution: Check registry.csv; may need to add new template or adjust matching criteria
 
+---
+
 ## Architecture Improvements in v1.2.0
 
 ### Context-Safe Design
@@ -442,3 +477,11 @@ Optimized JSON (no pretty-printing):
   "resume_instructions": "..."
 }
 ```
+
+---
+
+**Related Documentation:**
+
+- [Brownfield Development Guide](./brownfield-guide.md)
+- [Implementation Workflows](./workflows-implementation.md)
+- [Scale Adaptive System](./scale-adaptive-system.md)