architecture reorganization in preparation of architecture solutioning rework
This commit is contained in:
Brian Madison
@@ -27,17 +27,13 @@ agent:
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: solution-architecture
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/workflow.yaml"
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/workflow.yaml"
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
|
||||
- trigger: tech-spec
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec/workflow.yaml"
|
||||
description: Use the PRD and Architecture to create a Tech-Spec for a specific epic
|
||||
|
||||
- trigger: validate-tech-spec
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
||||
@@ -22,14 +22,18 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: Check workflow status and get recommendations
|
||||
|
||||
- trigger: solutioning
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/workflow.yaml"
|
||||
description: Design Technical Game Solution
|
||||
|
||||
- trigger: tech-spec
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec/workflow.yaml"
|
||||
description: Create Technical Specification
|
||||
|
||||
- trigger: correct-course
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: solution-architecture
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
||||
@@ -37,7 +37,7 @@ agent:
|
||||
|
||||
- trigger: tech-spec
|
||||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
|
||||
description: Create Tech Spec for Level 0-1 projects
|
||||
description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects
|
||||
|
||||
- trigger: correct-course
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
|
||||
@@ -25,10 +25,6 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: Check workflow status and get recommendations
|
||||
|
||||
- trigger: assess-project-ready
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/implementation-ready-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
||||
- trigger: create-story
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
|
||||
description: Create a Draft Story with Context
|
||||
@@ -53,3 +49,11 @@ agent:
|
||||
- trigger: correct-course
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Execute correct-course task
|
||||
|
||||
- trigger: epic-tech-context
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
|
||||
description: Use the PRD and Architecture to create a Tech-Spec for a specific epic
|
||||
|
||||
- trigger: validate-epic-tech-context
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
|
||||
@@ -141,7 +141,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
|
||||
|
||||
1. **Planning:** Analyst runs `*product-brief`; PM executes `*plan-project` to produce PRD and epics; Architect completes `*solution-architecture` for the new module.
|
||||
2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans.
|
||||
3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*assess-project-ready`.
|
||||
3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*solutioning-gate-check`.
|
||||
4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan.
|
||||
5. **Post-Dev and Release:** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled to generate both traceability and gate decision.
|
||||
|
||||
@@ -149,15 +149,15 @@ This complexity **requires specialized documentation** (this guide), **extensive
|
||||
|
||||
### Brownfield Feature Enhancement (Level 3–4)
|
||||
|
||||
| Phase | Test Architect | Dev / Team | Outputs |
|
||||
| ----------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
|
||||
| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet |
|
||||
| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix |
|
||||
| Story Prep | - | Scrum Master `*create-story` | Updated story markdown |
|
||||
| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist |
|
||||
| Post-Dev | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, quality report, refreshed coverage matrix, NFR report |
|
||||
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Product Owner `*assess-project-ready`, share release notes | Quality audit, Gate YAML + release summary |
|
||||
| Phase | Test Architect | Dev / Team | Outputs |
|
||||
| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
|
||||
| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
|
||||
| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet |
|
||||
| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix |
|
||||
| Story Prep | - | Scrum Master `*create-story` | Updated story markdown |
|
||||
| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist |
|
||||
| Post-Dev | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, quality report, refreshed coverage matrix, NFR report |
|
||||
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Product Owner `*solutioning-gate-check`, share release notes | Quality audit, Gate YAML + release summary |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
@@ -167,7 +167,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
|
||||
- Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation.
|
||||
- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier.
|
||||
- Use `*test-review` to validate existing brownfield tests or audit new tests before gate.
|
||||
- Product Owner `*assess-project-ready` confirms the team has artifacts before handoff or release.
|
||||
- Product Owner `*solutioning-gate-check` confirms the team has artifacts before handoff or release.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@@ -165,7 +165,7 @@ Your choice [1/2/3]:
|
||||
The workflow uses three CSV files:
|
||||
|
||||
1. **project-types.csv** - Project type detection and classification
|
||||
- Location: `/bmad/bmm/workflows/3-solutioning/project-types/project-types.csv`
|
||||
- Location: `/bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv`
|
||||
- 12 project types with detection keywords
|
||||
|
||||
2. **registry.csv** - Architecture template matching
|
||||
|
||||
@@ -20,7 +20,7 @@ instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Required data files - CRITICAL for project type detection and documentation requirements
|
||||
project_types_csv: "{project-root}/bmad/bmm/workflows/3-solutioning/project-types/project-types.csv"
|
||||
project_types_csv: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
|
||||
architecture_registry_csv: "{project-root}/bmad/bmm/workflows/3-solutioning/templates/registry.csv"
|
||||
documentation_requirements_csv: "{installed_path}/documentation-requirements.csv"
|
||||
|
||||
|
||||
@@ -1,500 +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
|
||||
- ✅ **Intent-based**: LLM intelligence over prescriptive lists
|
||||
- ✅ **Template-driven**: 11 adaptive architecture document templates
|
||||
- ✅ **Game-aware**: Adapts heavily based on game type (RPG, Puzzle, Shooter, etc.)
|
||||
- ✅ **GDD/PRD aware**: Uses Game Design Doc for games, PRD for everything else
|
||||
- ✅ **ADR tracking**: Separate Architecture Decision Records document
|
||||
- ✅ **Simplified structure**: ~11 core project types with consistent naming
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
Run this workflow **AFTER** completing:
|
||||
|
||||
| Prerequisite | Required For | Location |
|
||||
| -------------------------- | ----------------------------- | -------------------------------- |
|
||||
| **plan-project workflow** | All projects | `/docs/bmm-workflow-status.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 `bmm-workflow-status.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 and Templates
|
||||
|
||||
### Simplified Project Type System
|
||||
|
||||
The workflow uses ~11 core project types that cover 99% of software projects:
|
||||
|
||||
| Type | Name | Template | Instructions |
|
||||
| ------------------ | ------------------------ | -------------------------- | ------------------------------ |
|
||||
| **web** | Web Application | web-template.md | web-instructions.md |
|
||||
| **mobile** | Mobile Application | mobile-template.md | mobile-instructions.md |
|
||||
| **game** | Game Development | game-template.md | game-instructions.md |
|
||||
| **backend** | Backend Service | backend-template.md | backend-instructions.md |
|
||||
| **data** | Data Pipeline | data-template.md | data-instructions.md |
|
||||
| **cli** | CLI Tool | cli-template.md | cli-instructions.md |
|
||||
| **library** | Library/SDK | library-template.md | library-instructions.md |
|
||||
| **desktop** | Desktop Application | desktop-template.md | desktop-instructions.md |
|
||||
| **embedded** | Embedded System | embedded-template.md | embedded-instructions.md |
|
||||
| **extension** | Browser/Editor Extension | extension-template.md | extension-instructions.md |
|
||||
| **infrastructure** | Infrastructure | infrastructure-template.md | infrastructure-instructions.md |
|
||||
|
||||
### Intent-Based Architecture
|
||||
|
||||
Instead of maintaining 171 prescriptive technology combinations, the workflow now:
|
||||
|
||||
- **Leverages LLM intelligence** to understand project requirements
|
||||
- **Adapts templates dynamically** based on actual needs
|
||||
- **Uses intent-based instructions** rather than prescriptive checklists
|
||||
- **Allows for emerging technologies** without constant updates
|
||||
|
||||
Each project type has:
|
||||
|
||||
- **Instruction file**: Intent-based guidance for architecture decisions
|
||||
- **Template file**: Adaptive starting point for the architecture document
|
||||
|
||||
---
|
||||
|
||||
## Architecture Flow
|
||||
|
||||
### Step 0: Prerequisites and Scale Check
|
||||
|
||||
Load `bmm-workflow-status.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: Intent-Based Technical Decisions
|
||||
|
||||
Load: `project-types/{project_type}-instructions.md`
|
||||
|
||||
- Use intent-based guidance, not prescriptive lists
|
||||
- Allow LLM intelligence to identify relevant decisions
|
||||
- Consider emerging technologies naturally
|
||||
|
||||
### Step 6: Adaptive Template Selection
|
||||
|
||||
**6.1: Simple Template Selection**
|
||||
|
||||
```
|
||||
Based on project_type from analysis:
|
||||
web → web-template.md
|
||||
mobile → mobile-template.md
|
||||
game → game-template.md (adapts heavily by game type)
|
||||
backend → backend-template.md
|
||||
... (consistent naming pattern)
|
||||
```
|
||||
|
||||
**6.2: Load Template**
|
||||
|
||||
```
|
||||
Read: project-types/{type}-template.md
|
||||
Example: project-types/game-template.md
|
||||
|
||||
Templates are adaptive starting points:
|
||||
- Standard sections (exec summary, tech stack, data arch, etc.)
|
||||
- Pattern-specific sections conditionally included
|
||||
- All {{placeholders}} to fill based on requirements
|
||||
```
|
||||
|
||||
**6.3: Dynamic Adaptation**
|
||||
|
||||
Templates adapt based on:
|
||||
|
||||
- Actual project requirements from PRD/GDD
|
||||
- User skill level (beginner/intermediate/expert)
|
||||
- Specific technology choices made
|
||||
- Game type for game projects (RPG, Puzzle, Shooter, etc.)
|
||||
|
||||
**Example Flow for Unity RPG:**
|
||||
|
||||
1. GDD says "Unity 2022 LTS" and "RPG"
|
||||
2. Load game-template.md and game-instructions.md
|
||||
3. Template adapts to include RPG-specific sections (inventory, quests, dialogue)
|
||||
4. Instructions guide Unity-specific decisions (MonoBehaviour vs ECS, etc.)
|
||||
5. LLM intelligence fills gaps not in any list
|
||||
6. Generate optimized `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
|
||||
└── project-types/ # All project type files in one folder
|
||||
├── project-types.csv # Simple 2-column mapping (type, name)
|
||||
├── web-instructions.md # Intent-based guidance for web projects
|
||||
├── web-template.md # Adaptive web architecture template
|
||||
├── mobile-instructions.md # Intent-based guidance for mobile
|
||||
├── mobile-template.md # Adaptive mobile architecture template
|
||||
├── game-instructions.md # Intent-based guidance (adapts by game type)
|
||||
├── game-template.md # Highly adaptive game architecture template
|
||||
├── backend-instructions.md # Intent-based guidance for backend services
|
||||
├── backend-template.md # Adaptive backend architecture template
|
||||
├── data-instructions.md # Intent-based guidance for data pipelines
|
||||
├── data-template.md # Adaptive data pipeline template
|
||||
├── cli-instructions.md # Intent-based guidance for CLI tools
|
||||
├── cli-template.md # Adaptive CLI architecture template
|
||||
├── library-instructions.md # Intent-based guidance for libraries/SDKs
|
||||
├── library-template.md # Adaptive library architecture template
|
||||
├── desktop-instructions.md # Intent-based guidance for desktop apps
|
||||
├── desktop-template.md # Adaptive desktop architecture template
|
||||
├── embedded-instructions.md # Intent-based guidance for embedded systems
|
||||
├── embedded-template.md # Adaptive embedded architecture template
|
||||
├── extension-instructions.md # Intent-based guidance for extensions
|
||||
├── extension-template.md # Adaptive extension architecture template
|
||||
├── infrastructure-instructions.md # Intent-based guidance for infra
|
||||
└── infrastructure-template.md # Adaptive infrastructure template
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 and Decisions (required table)
|
||||
3. Architecture Overview
|
||||
4. Repository and Service Strategy
|
||||
5. Data Architecture
|
||||
6. Component and 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 and Conventions (Agent Guidance)
|
||||
N+4. Testing Strategy
|
||||
N+5. Deployment and 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
|
||||
|
||||
---
|
||||
|
||||
## 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 and 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 Project Type
|
||||
|
||||
1. Add row to `project-types/project-types.csv` (just type and name)
|
||||
2. Create `project-types/{type}-instructions.md` with intent-based guidance
|
||||
3. Create `project-types/{type}-template.md` with adaptive template
|
||||
4. Update instructions.md if special handling needed (like GDD for games)
|
||||
|
||||
### Key Principles
|
||||
|
||||
- **Intent over prescription**: Guide decisions, don't list every option
|
||||
- **Leverage LLM intelligence**: Trust the model to know technologies
|
||||
- **Adaptive templates**: Templates should adapt to project needs
|
||||
- **Consistent naming**: Always use {type}-instructions.md and {type}-template.md
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- **Validation:** See `checklist.md`
|
||||
- **Workflow Logic:** See `instructions.md`
|
||||
- **Configuration:** See `workflow.yaml`
|
||||
- **Project Types:** See `project-types/project-types.csv`
|
||||
- **Example Template:** See `project-types/game-template.md`
|
||||
|
||||
---
|
||||
|
||||
_This workflow replaces the legacy HLA workflow with a modern, scale-adaptive, pattern-aware architecture generation system._
|
||||
New Doc Incoming...
|
||||
|
||||
@@ -1,53 +1,47 @@
|
||||
# Solution Architecture Workflow Instructions
|
||||
|
||||
This workflow generates scale-adaptive solution architecture documentation that replaces the legacy HLA workflow.
|
||||
|
||||
<workflow name="solution-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>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: Concise, technical, LLM-optimized. Use tables/lists over prose. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
|
||||
<critical>DOCUMENT OUTPUT: Concise, technical, LLM-optimized. Use tables/lists over prose. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not documented output content.</critical>
|
||||
|
||||
<step n="0" goal="Validate workflow and extract project configuration">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: data</param>
|
||||
<param>data_request: project_config</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<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>**⚠️ No Workflow Status File Found**
|
||||
|
||||
<check if="status_exists == false">
|
||||
<output>**⚠️ No Workflow Status File Found**
|
||||
Please run `workflow-init` first to:
|
||||
|
||||
The solution-architecture workflow requires a status file to understand your project context.
|
||||
- Define your project type and level
|
||||
- Map out your workflow journey
|
||||
- Create the status file
|
||||
|
||||
Please run `workflow-init` first to:
|
||||
Run: `workflow-init`
|
||||
|
||||
- Define your project type and level
|
||||
- Map out your workflow journey
|
||||
- Create the status file
|
||||
After setup, return here to run solution-architecture.
|
||||
</output>
|
||||
<action>Exit workflow - cannot proceed without status file</action>
|
||||
|
||||
Run: `workflow-init`
|
||||
</check>
|
||||
|
||||
After setup, return here to run solution-architecture.
|
||||
</output>
|
||||
<action>Exit workflow - cannot proceed without status file</action>
|
||||
</check>
|
||||
|
||||
<check if="status_exists == true">
|
||||
<action>Store {{status_file_path}} for later updates</action>
|
||||
<action>Use extracted project configuration:</action>
|
||||
- project_level: {{project_level}}
|
||||
- field_type: {{field_type}}
|
||||
- project_type: {{project_type}}
|
||||
- has_user_interface: {{has_user_interface}}
|
||||
- ui_complexity: {{ui_complexity}}
|
||||
- ux_spec_path: {{ux_spec_path}}
|
||||
- prd_status: {{prd_status}}
|
||||
|
||||
</check>
|
||||
<check if="status_exists == true">
|
||||
<action>Store {{status_file_path}} for later updates</action>
|
||||
<action>Use extracted project configuration:</action>
|
||||
- project_level: {{project_level}}
|
||||
- field_type: {{field_type}}
|
||||
- project_type: {{project_type}}
|
||||
- has_user_interface: {{has_user_interface}}
|
||||
- ui_complexity: {{ui_complexity}}
|
||||
- ux_spec_path: {{ux_spec_path}}
|
||||
- prd_status: {{prd_status}}
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="0.5" goal="Validate workflow sequencing and prerequisites">
|
||||
@@ -112,7 +106,7 @@ IF all prerequisites met:
|
||||
✅ Prerequisites validated - PRD: complete - UX Spec: {{complete | not_applicable}}
|
||||
Proceeding with solution architecture workflow...
|
||||
|
||||
5. Determine workflow path:
|
||||
1. Determine workflow path:
|
||||
IF project_level == 0: - Skip solution architecture entirely - Output: "Level 0 project - validate/update tech-spec.md only" - STOP WORKFLOW
|
||||
ELSE: - Proceed with full solution architecture workflow
|
||||
</action>
|
||||
@@ -121,7 +115,7 @@ Proceeding with solution architecture workflow...
|
||||
|
||||
<step n="1" goal="Analyze requirements and identify project characteristics">
|
||||
|
||||
<action>Load and deeply understand the requirements documents (PRD/GDD) and any UX specifications.</action>
|
||||
<action>Load and deeply understand the requirements documents (PRD/GDD), epics and the stories to complete them and any UX specifications.</action>
|
||||
|
||||
<action>Intelligently determine the true nature of this project by analyzing:
|
||||
|
||||
@@ -151,14 +151,6 @@ Discuss service boundaries, data consistency, service discovery, and distributed
|
||||
**For an enterprise integration:**
|
||||
Focus on security, compliance, audit logging, and existing system compatibility.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Start simple, evolve as needed** - Don't build for imaginary scale
|
||||
2. **Use boring technology** - Proven solutions over cutting edge
|
||||
3. **Optimize for your constraint** - Development speed, performance, or operations
|
||||
4. **Make reversible decisions** - Avoid early lock-in
|
||||
5. **Document the "why"** - But keep it brief
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure decisions as:
|
||||
@@ -0,0 +1,95 @@
|
||||
# Solution Architecture Workflow Configuration
|
||||
name: solution-architecture
|
||||
description: "Scale-adaptive solution architecture generation."
|
||||
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
|
||||
|
||||
# Inputs expected ( check output_folder or ask user if missing)
|
||||
recommended_inputs:
|
||||
- prd
|
||||
- gdd
|
||||
- spec
|
||||
- architecture
|
||||
- epics
|
||||
- ux_spec
|
||||
|
||||
# Input requirements
|
||||
inputs:
|
||||
- name: project_workflow_analysis_path
|
||||
description: "Path to bmm-workflow-status.md from plan-project workflow"
|
||||
default: "{output_folder}/bmm-workflow-status.md"
|
||||
required: true
|
||||
- name: project_level
|
||||
description: "Project level (0-4) from analysis file"
|
||||
type: integer
|
||||
required: true
|
||||
|
||||
# Output artifacts
|
||||
outputs:
|
||||
- name: architecture.md
|
||||
description: "Complete solution architecture document"
|
||||
default: "{output_folder}/solution-architecture.md"
|
||||
- name: architecture_decisions.md
|
||||
description: "Architecture Decision Records (ADRs)"
|
||||
default: "{output_folder}/architecture-decisions.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"
|
||||
|
||||
# Reference data files
|
||||
project_types: "{installed_path}/project-types/project-types.csv"
|
||||
|
||||
# Default output location
|
||||
default_output_file: "{output_folder}/solution-architecture.md"
|
||||
|
||||
web_bundle:
|
||||
name: "solution-architecture"
|
||||
description: "Scale-adaptive solution architecture generation with dynamic template sections. Replaces legacy HLA workflow with modern BMAD Core compliance."
|
||||
author: "BMad Builder"
|
||||
instructions: "bmad/bmm/workflows/3-solutioning/architecture/instructions.md"
|
||||
validation: "bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
tech_spec_workflow: "bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
|
||||
# Reference data files
|
||||
project_types: "bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
|
||||
# Workflow dependencies
|
||||
existing_workflows:
|
||||
- workflow_status: "bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/ADR-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
|
||||
# Instructions files
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md"
|
||||
# Template files
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/web-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/game-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/data-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/library-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md"
|
||||
@@ -1,168 +0,0 @@
|
||||
# Solution Architecture Checklist
|
||||
|
||||
Use this checklist during workflow execution and review.
|
||||
|
||||
## Pre-Workflow
|
||||
|
||||
- [ ] PRD exists with FRs, NFRs, epics, and stories (for Level 1+)
|
||||
- [ ] UX specification exists (for UI projects at Level 2+)
|
||||
- [ ] Project level determined (0-4)
|
||||
|
||||
## During Workflow
|
||||
|
||||
### Step 0: Scale Assessment
|
||||
|
||||
- [ ] Analysis template loaded
|
||||
- [ ] Project level extracted
|
||||
- [ ] Level 0 → Skip workflow OR Level 1-4 → Proceed
|
||||
|
||||
### Step 1: PRD Analysis
|
||||
|
||||
- [ ] All FRs extracted
|
||||
- [ ] All NFRs extracted
|
||||
- [ ] All epics/stories identified
|
||||
- [ ] Project type detected
|
||||
- [ ] Constraints identified
|
||||
|
||||
### Step 2: User Skill Level
|
||||
|
||||
- [ ] Skill level clarified (beginner/intermediate/expert)
|
||||
- [ ] Technical preferences captured
|
||||
|
||||
### Step 3: Stack Recommendation
|
||||
|
||||
- [ ] Reference architectures searched
|
||||
- [ ] Top 3 presented to user
|
||||
- [ ] Selection made (reference or custom)
|
||||
|
||||
### Step 4: Component Boundaries
|
||||
|
||||
- [ ] Epics analyzed
|
||||
- [ ] Component boundaries identified
|
||||
- [ ] Architecture style determined (monolith/microservices/etc.)
|
||||
- [ ] Repository strategy determined (monorepo/polyrepo)
|
||||
|
||||
### Step 5: Project-Type Questions
|
||||
|
||||
- [ ] Project-type questions loaded
|
||||
- [ ] Only unanswered questions asked (dynamic narrowing)
|
||||
- [ ] All decisions recorded
|
||||
|
||||
### Step 6: Architecture Generation
|
||||
|
||||
- [ ] Template sections determined dynamically
|
||||
- [ ] User approved section list
|
||||
- [ ] solution-architecture.md generated with ALL sections
|
||||
- [ ] Technology and Library Decision Table included with specific versions
|
||||
- [ ] Proposed Source Tree included
|
||||
- [ ] Design-level only (no extensive code)
|
||||
- [ ] Output adapted to user skill level
|
||||
|
||||
### Step 7: Cohesion Check
|
||||
|
||||
- [ ] Requirements coverage validated (FRs, NFRs, epics, stories)
|
||||
- [ ] Technology table validated (no vagueness)
|
||||
- [ ] Code vs design balance checked
|
||||
- [ ] Epic Alignment Matrix generated (separate output)
|
||||
- [ ] Story readiness assessed (X of Y ready)
|
||||
- [ ] Vagueness detected and flagged
|
||||
- [ ] Over-specification detected and flagged
|
||||
- [ ] Cohesion check report generated
|
||||
- [ ] Issues addressed or acknowledged
|
||||
|
||||
### Step 7.5: Specialist Sections
|
||||
|
||||
- [ ] DevOps assessed (simple inline or complex placeholder)
|
||||
- [ ] Security assessed (simple inline or complex placeholder)
|
||||
- [ ] Testing assessed (simple inline or complex placeholder)
|
||||
- [ ] Specialist sections added to END of solution-architecture.md
|
||||
|
||||
### Step 8: PRD Updates (Optional)
|
||||
|
||||
- [ ] Architectural discoveries identified
|
||||
- [ ] PRD updated if needed (enabler epics, story clarifications)
|
||||
|
||||
### Step 9: Tech-Spec Generation
|
||||
|
||||
- [ ] Tech-spec generated for each epic
|
||||
- [ ] Saved as tech-spec-epic-{{N}}.md
|
||||
- [ ] bmm-workflow-status.md updated
|
||||
|
||||
### Step 10: Polyrepo Strategy (Optional)
|
||||
|
||||
- [ ] Polyrepo identified (if applicable)
|
||||
- [ ] Documentation copying strategy determined
|
||||
- [ ] Full docs copied to all repos
|
||||
|
||||
### Step 11: Validation
|
||||
|
||||
- [ ] All required documents exist
|
||||
- [ ] All checklists passed
|
||||
- [ ] Completion summary generated
|
||||
|
||||
## Quality Gates
|
||||
|
||||
### Technology and Library Decision Table
|
||||
|
||||
- [ ] Table exists in solution-architecture.md
|
||||
- [ ] ALL technologies have specific versions (e.g., "pino 8.17.0")
|
||||
- [ ] NO vague entries ("a logging library", "appropriate caching")
|
||||
- [ ] NO multi-option entries without decision ("Pino or Winston")
|
||||
- [ ] Grouped logically (core stack, libraries, devops)
|
||||
|
||||
### Proposed Source Tree
|
||||
|
||||
- [ ] Section exists in solution-architecture.md
|
||||
- [ ] Complete directory structure shown
|
||||
- [ ] For polyrepo: ALL repo structures included
|
||||
- [ ] Matches technology stack conventions
|
||||
|
||||
### Cohesion Check Results
|
||||
|
||||
- [ ] 100% FR coverage OR gaps documented
|
||||
- [ ] 100% NFR coverage OR gaps documented
|
||||
- [ ] 100% epic coverage OR gaps documented
|
||||
- [ ] 100% story readiness OR gaps documented
|
||||
- [ ] Epic Alignment Matrix generated (separate file)
|
||||
- [ ] Readiness score ≥ 90% OR user accepted lower score
|
||||
|
||||
### Design vs Code Balance
|
||||
|
||||
- [ ] No code blocks > 10 lines
|
||||
- [ ] Focus on schemas, patterns, diagrams
|
||||
- [ ] No complete implementations
|
||||
|
||||
## Post-Workflow Outputs
|
||||
|
||||
### Required Files
|
||||
|
||||
- [ ] /docs/solution-architecture.md (or architecture.md)
|
||||
- [ ] /docs/cohesion-check-report.md
|
||||
- [ ] /docs/epic-alignment-matrix.md
|
||||
- [ ] /docs/tech-spec-epic-1.md
|
||||
- [ ] /docs/tech-spec-epic-2.md
|
||||
- [ ] /docs/tech-spec-epic-N.md (for all epics)
|
||||
|
||||
### Optional Files (if specialist placeholders created)
|
||||
|
||||
- [ ] Handoff instructions for devops-architecture workflow
|
||||
- [ ] Handoff instructions for security-architecture workflow
|
||||
- [ ] Handoff instructions for test-architect workflow
|
||||
|
||||
### Updated Files
|
||||
|
||||
- [ ] PRD.md (if architectural discoveries required updates)
|
||||
|
||||
## Next Steps After Workflow
|
||||
|
||||
If specialist placeholders created:
|
||||
|
||||
- [ ] Run devops-architecture workflow (if placeholder)
|
||||
- [ ] Run security-architecture workflow (if placeholder)
|
||||
- [ ] Run test-architect workflow (if placeholder)
|
||||
|
||||
For implementation:
|
||||
|
||||
- [ ] Review all tech specs
|
||||
- [ ] Set up development environment per architecture
|
||||
- [ ] Begin epic implementation using tech specs
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
|
||||
Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Solution Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
|
||||
|
||||
## Key Features
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Tech Spec Validation Checklist
|
||||
|
||||
```xml
|
||||
<checklist id="bmad/bmm/workflows/3-solutioning/tech-spec/checklist">
|
||||
<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>
|
||||
@@ -11,15 +11,16 @@ document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Inputs expected (ask user if missing)
|
||||
# Inputs expected ( check output_folder or ask user if missing)
|
||||
recommended_inputs:
|
||||
- prd: "{project-root}/docs/PRD.md"
|
||||
- architecture: "{project-root}/docs/solution-architecture.md"
|
||||
- frontend_spec: "{project-root}/docs/front-end-spec.md"
|
||||
- brownfield_notes: "{project-root}/docs/brownfield-notes.md"
|
||||
- prd
|
||||
- gdd
|
||||
- spec
|
||||
- architecture
|
||||
- ux_spec
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec"
|
||||
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"
|
||||
@@ -36,6 +37,6 @@ web_bundle:
|
||||
description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
|
||||
author: "BMAD BMM"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/3-solutioning/tech-spec/template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/tech-spec/instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/tech-spec/checklist.md"
|
||||
- "bmad/bmm/workflows/4-implementation/epic-tech-context/template.md"
|
||||
- "bmad/bmm/workflows/4-implementation/epic-tech-context/instructions.md"
|
||||
- "bmad/bmm/workflows/4-implementation/epic-tech-context/checklist.md"
|
||||
@@ -51,13 +51,13 @@ The workflow adapts its validation based on project level:
|
||||
### Via Scrum Master Agent
|
||||
|
||||
```
|
||||
*assess-project-ready
|
||||
*solutioning-gate-check
|
||||
```
|
||||
|
||||
### Direct Workflow Invocation
|
||||
|
||||
```
|
||||
workflow implementation-ready-check
|
||||
workflow solutioning-gate-check
|
||||
```
|
||||
|
||||
## Expected Inputs
|
||||
@@ -1,7 +1,7 @@
|
||||
# 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/implementation-ready-check/workflow.yaml</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>
|
||||
|
||||
<workflow>
|
||||
@@ -1,5 +1,5 @@
|
||||
# Implementation Ready Check - Workflow Configuration
|
||||
name: implementation-ready-check
|
||||
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"
|
||||
|
||||
@@ -16,7 +16,7 @@ workflow_status_workflow: "{project-root}/bmad/bmm/workflows/workflow-status/wor
|
||||
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/implementation-ready-check"
|
||||
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"
|
||||
@@ -1,103 +0,0 @@
|
||||
# Solution Architecture Workflow Configuration
|
||||
name: solution-architecture
|
||||
description: "Scale-adaptive solution architecture generation with dynamic template sections. Replaces legacy HLA workflow with modern BMAD Core compliance."
|
||||
author: "BMad Builder"
|
||||
|
||||
# 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
|
||||
inputs:
|
||||
- name: prd_path
|
||||
description: "Path to PRD document"
|
||||
default: "{output_folder}/PRD.md"
|
||||
required: true
|
||||
- name: project_workflow_analysis_path
|
||||
description: "Path to bmm-workflow-status.md from plan-project workflow"
|
||||
default: "{output_folder}/bmm-workflow-status.md"
|
||||
required: true
|
||||
- name: project_level
|
||||
description: "Project level (0-4) from analysis file"
|
||||
type: integer
|
||||
required: true
|
||||
|
||||
# Output artifacts
|
||||
outputs:
|
||||
- name: architecture_md
|
||||
description: "Complete solution architecture document"
|
||||
default: "{output_folder}/solution-architecture.md"
|
||||
- name: architecture_decisions_md
|
||||
description: "Architecture Decision Records (ADRs)"
|
||||
default: "{output_folder}/architecture-decisions.md"
|
||||
- name: epic_alignment_matrix
|
||||
description: "Epic-to-component mapping (from cohesion check)"
|
||||
- name: tech_specs
|
||||
description: "Per-epic tech spec documents"
|
||||
|
||||
# Workflow variables (set during execution)
|
||||
variables:
|
||||
project_type: ""
|
||||
architecture_style: ""
|
||||
repo_strategy: ""
|
||||
template_sections: []
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning"
|
||||
adr_template: "{installed_path}/ADR-template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Reference data files
|
||||
project_types: "{installed_path}/project-types/project-types.csv"
|
||||
templates: "{installed_path}/project-types"
|
||||
|
||||
# Default output location
|
||||
default_output_file: "{output_folder}/solution-architecture.md"
|
||||
|
||||
# Additional workflow dependencies
|
||||
tech_spec_workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/tech-spec/workflow.yaml"
|
||||
|
||||
web_bundle:
|
||||
name: "solution-architecture"
|
||||
description: "Scale-adaptive solution architecture generation with dynamic template sections. Replaces legacy HLA workflow with modern BMAD Core compliance."
|
||||
author: "BMad Builder"
|
||||
instructions: "bmad/bmm/workflows/3-solutioning/instructions.md"
|
||||
validation: "bmad/bmm/workflows/3-solutioning/checklist.md"
|
||||
tech_spec_workflow: "bmad/bmm/workflows/3-solutioning/tech-spec/workflow.yaml"
|
||||
# Reference data files
|
||||
project_types: "bmad/bmm/workflows/3-solutioning/project-types/project-types.csv"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/3-solutioning/instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/checklist.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/ADR-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/project-types.csv"
|
||||
# Instructions files
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/web-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/mobile-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/game-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/backend-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/data-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/cli-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/library-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/desktop-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/embedded-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/extension-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/infrastructure-instructions.md"
|
||||
# Template files
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/web-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/mobile-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/game-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/backend-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/data-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/cli-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/library-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/desktop-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/embedded-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/extension-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/project-types/infrastructure-template.md"
|
||||
@@ -36,7 +36,7 @@ phases:
|
||||
workflows:
|
||||
- id: "tech-spec"
|
||||
required: true
|
||||
agent: "architect"
|
||||
agent: "pm"
|
||||
command: "tech-spec"
|
||||
output: "Creates story files for feature"
|
||||
note: "Must integrate with existing architecture"
|
||||
|
||||
@@ -46,13 +46,13 @@ phases:
|
||||
note: "Must consider existing system constraints"
|
||||
- id: "tech-spec"
|
||||
required: true
|
||||
agent: "architect"
|
||||
agent: "pm"
|
||||
command: "tech-spec"
|
||||
output: "Creates multiple story files"
|
||||
output: "Creates spec with multiple story files"
|
||||
note: "Integrate with existing patterns"
|
||||
- id: "ux-spec"
|
||||
conditional: "if_has_ui"
|
||||
agent: "pm"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
|
||||
- phase: 3
|
||||
|
||||
@@ -69,10 +69,10 @@ phases:
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
note: "Extension of existing architecture"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
|
||||
- phase: 4
|
||||
name: "Implementation"
|
||||
|
||||
@@ -36,11 +36,6 @@ phases:
|
||||
agent: "analyst"
|
||||
command: "product-brief"
|
||||
note: "Strategic brief for major expansion"
|
||||
- id: "impact-assessment"
|
||||
recommended: true
|
||||
agent: "analyst"
|
||||
command: "impact-assessment"
|
||||
note: "Assess impact on existing systems"
|
||||
|
||||
- phase: 2
|
||||
name: "Planning"
|
||||
@@ -56,15 +51,6 @@ phases:
|
||||
agent: "pm"
|
||||
command: "ux-spec"
|
||||
note: "Multiple UI/UX specifications"
|
||||
- id: "product-spec"
|
||||
recommended: true
|
||||
agent: "pm"
|
||||
command: "product-spec"
|
||||
note: "Detailed specifications for expansion"
|
||||
- id: "migration-plan"
|
||||
conditional: "if_breaking_changes"
|
||||
agent: "architect"
|
||||
command: "migration-plan"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
@@ -76,10 +62,10 @@ phases:
|
||||
command: "solution-architecture"
|
||||
output: "Architecture for system expansion"
|
||||
note: "Must maintain backward compatibility"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
note: "Critical validation before major changes"
|
||||
|
||||
- phase: 4
|
||||
@@ -89,7 +75,7 @@ phases:
|
||||
epic_workflows:
|
||||
- id: "tech-spec"
|
||||
required: true
|
||||
agent: "architect"
|
||||
agent: "sm"
|
||||
command: "tech-spec"
|
||||
note: "JIT per epic - creates stories considering existing code"
|
||||
story_loop: "for_each_story_in_epic"
|
||||
|
||||
@@ -50,10 +50,10 @@ phases:
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
note: "Engine architecture, networking, systems"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
|
||||
- phase: 4
|
||||
name: "Implementation"
|
||||
|
||||
@@ -26,9 +26,9 @@ phases:
|
||||
workflows:
|
||||
- id: "tech-spec"
|
||||
required: true
|
||||
agent: "architect"
|
||||
agent: "pm"
|
||||
command: "tech-spec"
|
||||
output: "Creates single story file"
|
||||
output: "Creates Technical Specification with single story file"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
||||
@@ -30,9 +30,9 @@ phases:
|
||||
workflows:
|
||||
- id: "tech-spec"
|
||||
required: true
|
||||
agent: "architect"
|
||||
agent: "pm"
|
||||
command: "tech-spec"
|
||||
output: "Creates 2-3 story files"
|
||||
output: "Creates Technical Specification with an epic and 2-3 story files"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
||||
@@ -33,16 +33,16 @@ phases:
|
||||
required: true
|
||||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Creates epics.md and story list"
|
||||
output: "Creates PRD with epics.md and story list"
|
||||
- id: "ux-spec"
|
||||
conditional: "if_has_ui"
|
||||
agent: "pm"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
- id: "tech-spec"
|
||||
optional: true
|
||||
agent: "architect"
|
||||
agent: "pm"
|
||||
command: "tech-spec"
|
||||
note: "Lightweight technical planning"
|
||||
note: "Lightweight Technical Specification planning"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
@@ -53,11 +53,11 @@ phases:
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
output: "System-wide architecture document"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
note: "Validate architecture before implementation"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
note: "Validate PRD + UX + architecture cohesion before implementation"
|
||||
|
||||
- phase: 4
|
||||
name: "Implementation"
|
||||
|
||||
@@ -36,7 +36,7 @@ phases:
|
||||
output: "High-level requirements and epic definitions"
|
||||
- id: "ux-spec"
|
||||
conditional: "if_has_ui"
|
||||
agent: "pm"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
|
||||
- phase: 3
|
||||
@@ -48,11 +48,11 @@ phases:
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
output: "System-wide architecture document"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
note: "Validate architecture before implementation"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
note: "Validate PRD + UX + architecture cohesion before implementation"
|
||||
|
||||
- phase: 4
|
||||
name: "Implementation"
|
||||
|
||||
@@ -37,14 +37,9 @@ phases:
|
||||
output: "Comprehensive product requirements document"
|
||||
- id: "ux-spec"
|
||||
required: true
|
||||
agent: "pm"
|
||||
agent: "ux-expert"
|
||||
command: "ux-spec"
|
||||
note: "Multiple UI/UX specifications needed"
|
||||
- id: "product-spec"
|
||||
recommended: true
|
||||
agent: "pm"
|
||||
command: "product-spec"
|
||||
note: "Detailed product specifications"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
@@ -55,11 +50,11 @@ phases:
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
output: "Enterprise architecture documentation"
|
||||
- id: "assess-project-ready"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
agent: "sm"
|
||||
command: "assess-project-ready"
|
||||
note: "Critical validation before enterprise implementation"
|
||||
agent: "architect"
|
||||
command: "solutioning-gate-check"
|
||||
note: "Validate PRD + UX + architecture cohesion before implementation"
|
||||
|
||||
- phase: 4
|
||||
name: "Implementation"
|
||||
|
||||
Reference in New Issue
Block a user