npm - bmad-method - Versions diffs - 6.0.0-alpha.0 → 6.0.0-alpha.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (788) hide show

package/src/modules/bmm/workflows/3-solutioning/README.md CHANGED Viewed

@@ -1,565 +1 @@
-# Solution Architecture Workflow
-**Status:** Production-Ready | Scale-Adaptive Architecture Generation
----
-## Overview
-This workflow generates comprehensive, scale-adaptive solution architecture documentation tailored to your project type, technology stack, and scale level (0-4).
-**Unique Features:**
-- ✅ **Scale-adaptive**: Level 0 = skip, Levels 1-4 = progressive depth
-- ✅ **Pattern-aware**: 171 technology combinations across 12 project types
-- ✅ **Template-driven**: 11 complete architecture document templates
-- ✅ **Engine-specific guidance**: Unity, Godot, Phaser, and more
-- ✅ **GDD/PRD aware**: Uses Game Design Doc for games, PRD for everything else
-- ✅ **ADR tracking**: Separate Architecture Decision Records document
-- ✅ **Specialist integration**: Pattern-specific specialist recommendations
----
-## When to Use
-Run this workflow **AFTER** completing:
-| Prerequisite               | Required For                  | Location                             |
-| -------------------------- | ----------------------------- | ------------------------------------ |
-| **plan-project workflow**  | All projects                  | `/docs/project-workflow-analysis.md` |
-| **PRD with epics/stories** | Level 1+ projects             | `/docs/PRD.md`                       |
-| **GDD (for games)**        | Game projects                 | `/docs/GDD.md` or `/docs/PRD.md`     |
-| **UX Specification**       | UI projects (web/mobile/game) | `/docs/ux-specification.md`          |
----
-## Quick Start
-```bash
-workflow solution-architecture
-```
-**The workflow will:**
-1. Load `project-workflow-analysis.md` (from plan-project)
-2. Check prerequisites (PRD/GDD, UX spec if needed)
-3. Read requirements (PRD for apps, GDD for games)
-4. Ask architecture pattern questions
-5. Load appropriate template and guide
-6. Generate architecture + ADR documents
-7. Run cohesion check validation
----
-## Outputs
-### Primary Documents
-| File                        | Purpose                              | Notes                                               |
-| --------------------------- | ------------------------------------ | --------------------------------------------------- |
-| `solution-architecture.md`  | Complete architecture document       | Pattern-specific sections                           |
-| `architecture-decisions.md` | Architecture Decision Records (ADRs) | Tracks all decisions, options considered, rationale |
-### Validation Outputs
-| File                       | Purpose                             |
-| -------------------------- | ----------------------------------- |
-| `cohesion-check-report.md` | Validates 100% FR/NFR/Epic coverage |
-| `epic-alignment-matrix.md` | Maps epics → components/tech/APIs   |
----
-## Project Types & Templates
-### 12 Project Types Supported
-| Type          | Examples                     | Template                          | Guide Examples       |
-| ------------- | ---------------------------- | --------------------------------- | -------------------- |
-| **web**       | Next.js, Rails, Django       | web-fullstack-architecture.md     | (TBD)                |
-| **mobile**    | React Native, Flutter, Swift | mobile-app-architecture.md        | (TBD)                |
-| **game**      | Unity, Godot, Phaser         | game-engine-architecture.md       | Unity, Godot, Phaser |
-| **embedded**  | ESP32, STM32, Raspberry Pi   | embedded-firmware-architecture.md | (TBD)                |
-| **backend**   | Express, FastAPI, gRPC       | backend-service-architecture.md   | (TBD)                |
-| **data**      | Spark, Airflow, MLflow       | data-pipeline-architecture.md     | (TBD)                |
-| **cli**       | Commander, Click, Cobra      | cli-tool-architecture.md          | (TBD)                |
-| **desktop**   | Electron, Tauri, Qt          | desktop-app-architecture.md       | (TBD)                |
-| **library**   | npm, PyPI, cargo             | library-package-architecture.md   | (TBD)                |
-| **infra**     | Terraform, K8s Operator      | infrastructure-architecture.md    | (TBD)                |
-| **extension** | Chrome, VS Code plugins      | desktop-app-architecture.md       | (TBD)                |
-### 171 Technology Combinations
-The workflow maintains a registry (`templates/registry.csv`) with 171 pre-defined technology stack combinations:
-**Examples:**
-- `web-nextjs-ssr-monorepo` → Next.js SSR, TypeScript, monorepo
-- `game-unity-3d` → Unity 3D, C#, monorepo
-- `mobile-react-native` → React Native, TypeScript, cross-platform
-- `backend-fastapi-rest` → FastAPI, Python, REST API
-- `data-ml-training` → PyTorch/TensorFlow, Python, ML pipeline
-Each row maps to:
-- **template_path**: Architecture document structure (11 templates)
-- **guide_path**: Engine/framework-specific guidance (optional)
----
-## Architecture Flow
-### Step 0: Prerequisites & Scale Check
-Load `project-workflow-analysis.md`:
-- Extract: `project_level` (0-4), `project_type` (web/game/mobile/etc.), `field_type` (greenfield/brownfield)
-- Validate: PRD exists, UX spec exists (if UI project)
-- **Skip if Level 0** (single atomic change)
-### Step 1: Requirements Analysis
-**For Games:**
-- Read **GDD** (Game Design Document)
-- Extract: gameplay mechanics, engine (Unity/Godot/etc.), platform, multiplayer
-**For Everything Else:**
-- Read **PRD** (Product Requirements Document)
-- Extract: FRs, NFRs, epics, stories, integrations
-**For UI Projects:**
-- Read **UX Specification**
-- Extract: screens, flows, component patterns
-### Step 2: User Skill Level
-Ask user: Beginner / Intermediate / Expert
-- Affects verbosity of generated architecture
-### Step 3: Architecture Pattern
-Determine:
-- Architecture style (monolith, microservices, serverless, etc.)
-- Repository strategy (monorepo, polyrepo, hybrid)
-- Pattern-specific choices (SSR for web, native vs cross-platform for mobile)
-### Step 4: Epic Analysis
-Analyze PRD epics:
-- Identify component boundaries
-- Map domain capabilities
-- Determine service boundaries (if microservices)
-### Step 5: Project-Type Questions
-Load: `project-types/{project_type}-questions.md`
-- Ask project-type-specific questions (not yet engine-specific)
-### Step 6: Load Template + Guide
-**6.1: Search Registry**
-```
-Read: templates/registry.csv
-Match WHERE:
-  - project_types = {determined_type}
-  - languages = {preferred_languages}
-  - architecture_style = {determined_style}
-  - tags overlap with {requirements}
-Get: template_path, guide_path
-```
-**6.2: Load Template**
-```
-Read: templates/{template_path}
-Example: templates/game-engine-architecture.md
-This is a COMPLETE document structure with:
-- Standard sections (exec summary, tech stack, data arch, etc.)
-- Pattern-specific sections (Gameplay Systems for games, SSR Strategy for web)
-- All {{placeholders}} to fill
-```
-**6.3: Load Guide (if available)**
-```
-IF guide_path not empty:
-  Read: templates/{guide_path}
-  Example: templates/game-engine-unity-guide.md
-Guide contains:
-- Engine/framework-specific questions
-- Architecture patterns for this tech
-- Common pitfalls
-- Specialist recommendations
-- ADR templates
-```
-**Example Flow for Unity Game:**
-1. GDD says "Unity 2022 LTS"
-2. Registry match: `game-unity-3d` → `game-engine-architecture.md` + `game-engine-unity-guide.md`
-3. Load complete game architecture template
-4. Load Unity-specific guide
-5. Ask Unity-specific questions (MonoBehaviour vs ECS, ScriptableObjects, etc.)
-6. Fill template placeholders
-7. Generate `solution-architecture.md` + `architecture-decisions.md`
-### Step 7: Cohesion Check
-Validate architecture quality:
-- 100% FR/NFR/Epic/Story coverage
-- Technology table has specific versions
-- No vagueness ("a library", "some framework")
-- Design-level only (no implementation code)
-- Generate Epic Alignment Matrix
----
-## File Structure
-```
-/solution-architecture/
-├── README.md                        # This file
-├── workflow.yaml                    # Workflow configuration
-├── instructions.md                  # Main workflow logic
-├── checklist.md                     # Validation checklist
-├── ADR-template.md                  # ADR document template
-├── templates/                       # Architecture templates & guides
-│   ├── registry.csv                 # 171 tech combinations → templates
-│   ├── game-engine-architecture.md  # Complete game architecture doc
-│   ├── game-engine-unity-guide.md   # Unity-specific guidance
-│   ├── game-engine-godot-guide.md   # Godot-specific guidance
-│   ├── game-engine-web-guide.md     # Phaser/PixiJS/Three.js guidance
-│   ├── web-fullstack-architecture.md
-│   ├── web-api-architecture.md
-│   ├── mobile-app-architecture.md
-│   ├── embedded-firmware-architecture.md
-│   ├── backend-service-architecture.md
-│   ├── data-pipeline-architecture.md
-│   ├── cli-tool-architecture.md
-│   ├── desktop-app-architecture.md
-│   ├── library-package-architecture.md
-│   └── infrastructure-architecture.md
-└── project-types/                   # Project type detection & questions
-    ├── project-types.csv            # 12 project types + detection keywords
-    ├── game-questions.md
-    ├── web-questions.md
-    ├── mobile-questions.md
-    └── ... (12 question files)
-```
----
-## Template System
-### Complete, Standalone Templates
-Each template in `templates/` is a **complete** architecture document structure:
-**Standard Sections (all templates):**
-1. Executive Summary
-2. Technology Stack & Decisions (required table)
-3. Architecture Overview
-4. Repository & Service Strategy
-5. Data Architecture
-6. Component & Integration Overview
-   7-N. **Pattern-Specific Sections** (varies by template)
-   N+1. Proposed Source Tree
-   N+2. Getting Started (Human Setup)
-   N+3. Implementation Patterns & Conventions (Agent Guidance)
-   N+4. Testing Strategy
-   N+5. Deployment & Operations
-   N+6. Security
-   N+7. Specialist Sections
-**Pattern-Specific Sections Examples:**
-**Game Engine Template:**
-- Gameplay Systems (player controller, game state)
-- Scene Architecture
-- Asset Pipeline
-- Audio Architecture
-- Save System
-- Multiplayer Architecture (if applicable)
-**Web Fullstack Template:**
-- Frontend Architecture
-- Backend Architecture
-- API Design (REST/GraphQL/tRPC)
-- State Management
-- SSR/Caching Strategy
-- Performance Optimization
-**Embedded Firmware Template:**
-- Hardware Architecture
-- Communication Protocols
-- Power Management
-- Sensor/Actuator Integration
-- OTA Update Strategy
----
-## Guide System
-### Engine/Framework-Specific Guides
-Guides are **workflow instruction documents** that:
-- Ask engine-specific questions
-- Provide architecture pattern recommendations
-- Suggest what sections to emphasize
-- Define ADRs to create
-**Guides are NOT:**
-- ❌ Reference documentation (use official docs)
-- ❌ Tutorials (how to code)
-- ❌ API references
-**Guides ARE:**
-- ✅ Question flows for architecture decisions
-- ✅ Pattern recommendations specific to the tech
-- ✅ Common pitfalls to avoid
-- ✅ Specialist recommendations
-**Example: game-engine-unity-guide.md**
-```markdown
-## Unity Architecture Questions
-- MonoBehaviour or ECS?
-- ScriptableObjects for game data?
-- Addressables or Resources?
-## Unity Patterns
-- Singleton GameManager (when to use)
-- Event-driven communication
-- Object pooling strategy
-## Unity-Specific Sections to Include
-- Unity Project Configuration
-- Scene Architecture
-- Component Organization
-- Package Dependencies
-## Common Pitfalls
-- Caching GetComponent calls
-- Avoiding empty Update methods
-```
----
-## ADR Tracking
-Architecture Decision Records are maintained separately in `architecture-decisions.md`.
-**ADR Format:**
-```markdown
-### ADR-001: [Decision Title]
-**Date:** YYYY-MM-DD
-**Status:** Accepted | Rejected | Superseded
-**Decider:** User | Agent | Collaborative
-**Context:**
-What problem are we solving?
-**Options Considered:**
-1. Option A - pros/cons
-2. Option B - pros/cons
-3. Option C - pros/cons
-**Decision:**
-We chose Option X
-**Rationale:**
-Why we chose this over others
-**Consequences:**
-- Positive: ...
-- Negative: ...
-**Rejected Options:**
-- Option A rejected because: ...
-```
-**ADRs are populated throughout the workflow** as decisions are made:
-- Step 3: Architecture pattern ADR
-- Step 5: Technology selection ADRs
-- Step 6: Engine-specific ADRs (from guide)
----
-## Scale-Adaptive Behavior
-| Level | Project Size                     | Architecture Depth          | Specialist Sections        |
-| ----- | -------------------------------- | --------------------------- | -------------------------- |
-| **0** | Single task                      | Skip architecture           | N/A                        |
-| **1** | Small feature (1-10 stories)     | Lightweight, essential only | Inline guidance            |
-| **2** | Small project (5-15 stories)     | Standard depth              | Inline guidance            |
-| **3** | Standard project (12-40 stories) | Comprehensive               | Specialist placeholders    |
-| **4** | Ambitious product (40+ stories)  | Comprehensive + specialists | Specialist recommendations |
----
-## Specialist Integration
-Pattern-specific specialists are recommended based on project characteristics:
-**Game Projects:**
-- Audio Designer (music, SFX, adaptive audio)
-- Performance Optimizer (profiling, optimization)
-- Multiplayer Architect (netcode, state sync)
-- Monetization Specialist (IAP, ads, economy)
-**Web Projects:**
-- Frontend Architect (component design, state management)
-- Backend Architect (API design, microservices)
-- DevOps Specialist (CI/CD, deployment)
-- Security Specialist (auth, authorization, secrets)
-**Embedded Projects:**
-- Hardware Integration (sensors, actuators, protocols)
-- Power Management (battery, sleep modes)
-- RF/Wireless (WiFi, BLE, LoRa)
-- Safety Certification (if required)
-Specialists are documented with:
-- When they're needed
-- What they're responsible for
-- How they integrate with the workflow
----
-## Key Differences from Legacy HLA Workflow
-| Aspect              | Legacy HLA      | New Solution Architecture                 |
-| ------------------- | --------------- | ----------------------------------------- |
-| **Templates**       | Fixed structure | 11 complete templates, pattern-specific   |
-| **Tech Selection**  | Manual          | 171 pre-defined combinations              |
-| **Engine Guidance** | Generic         | Engine-specific guides (Unity/Godot/etc.) |
-| **ADRs**            | Inline          | Separate document                         |
-| **GDD Support**     | No              | Yes, for game projects                    |
-| **Guides**          | None            | Pattern-specific workflow guidance        |
-| **Scale**           | One size        | Adaptive Levels 0-4                       |
----
-## Validation & Quality Gates
-### Cohesion Check (Step 7)
-**Validates:**
-- ✅ 100% FR coverage (or gaps documented)
-- ✅ 100% NFR coverage (or gaps documented)
-- ✅ Every epic has technical foundation
-- ✅ Every story can be implemented with current architecture
-- ✅ Technology table complete with specific versions
-- ✅ No vagueness detected
-- ✅ Design-level only (no over-implementation)
-**Outputs:**
-- `cohesion-check-report.md` - Pass/fail with detailed gaps
-- `epic-alignment-matrix.md` - Mapping validation
-**If cohesion check fails:**
-- Document gaps
-- Update architecture
-- Re-run check
----
-## Getting Started for Implementers
-### For Games:
-1. Run `workflow plan-project` → Create GDD
-2. Specify engine in GDD (Unity/Godot/Phaser/etc.)
-3. Run `workflow solution-architecture`
-4. System detects engine from GDD
-5. Loads game-engine template + engine-specific guide
-6. Generates Unity/Godot/Phaser-specific architecture
-### For Web Apps:
-1. Run `workflow plan-project` → Create PRD
-2. Run `workflow ux-spec` → Create UX spec
-3. Run `workflow solution-architecture`
-4. Answer: SSR or SPA? Monolith or microservices?
-5. System loads web-fullstack template
-6. Generates framework-specific architecture
-### For Other Projects:
-1. Run `workflow plan-project` → Create PRD
-2. Run `workflow solution-architecture`
-3. Answer project-type questions
-4. System loads appropriate template
-5. Generates pattern-specific architecture
----
-## Extending the System
-### Adding a New Template
-1. Create `templates/new-pattern-architecture.md`
-2. Include all standard sections + pattern-specific sections
-3. Add rows to `templates/registry.csv` pointing to new template
-### Adding a New Guide
-1. Create `templates/new-tech-guide.md`
-2. Include: questions, patterns, pitfalls, specialist recommendations
-3. Update `templates/registry.csv` with `guide_path` column
-### Adding a New Project Type
-1. Add row to `project-types/project-types.csv`
-2. Create `project-types/new-type-questions.md`
-3. Ensure templates exist for this type
-4. Update instructions.md if special handling needed (like GDD for games)
----
-## Questions?
-- **Validation:** See `checklist.md`
-- **Workflow Logic:** See `instructions.md`
-- **Configuration:** See `workflow.yaml`
-- **Registry Format:** See `templates/registry.csv`
-- **Example Guide:** See `templates/game-engine-unity-guide.md`
----
-_This workflow replaces the legacy HLA workflow with a modern, scale-adaptive, pattern-aware architecture generation system._
+New Doc Incoming...