mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
749
src/modules/bmm/docs/scale-adaptive-system.md
Normal file
749
src/modules/bmm/docs/scale-adaptive-system.md
Normal file
@@ -0,0 +1,749 @@
|
||||
# BMad Method Scale Adaptive System
|
||||
|
||||
**Automatically adapts workflows to project complexity - from bug fixes to enterprise systems**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The **Scale Adaptive System** is BMad Method's intelligent workflow orchestration that automatically adjusts planning depth, documentation requirements, and implementation processes based on project size and complexity.
|
||||
|
||||
### The Problem It Solves
|
||||
|
||||
Traditional methodologies apply the same process to every project:
|
||||
|
||||
- ❌ **Overkill:** Bug fix requires full design docs
|
||||
- ❌ **Insufficient:** Enterprise system built with minimal planning
|
||||
- ❌ **One-Size-Fits-None:** Same process for 1 story and 100 stories
|
||||
|
||||
### The Solution
|
||||
|
||||
BMad Method **adapts workflows to match project scale**:
|
||||
|
||||
- ✅ **Level 0 (1 story):** Tech-spec only, implement immediately
|
||||
- ✅ **Level 2 (10 stories):** PRD + Architecture, structured approach
|
||||
- ✅ **Level 4 (100+ stories):** Full enterprise planning, comprehensive docs
|
||||
|
||||
**Result:** Right amount of planning for every project - no more, no less.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Five Levels at a Glance
|
||||
|
||||
| Level | Scope | Stories | Documentation | Timeline |
|
||||
| ----- | -------------------- | ------- | ------------------- | -------- |
|
||||
| **0** | Single atomic change | 1 | tech-spec only | Hours |
|
||||
| **1** | Small feature | 1-10 | tech-spec + epic | Days |
|
||||
| **2** | Medium project | 5-15 | PRD + optional arch | Weeks |
|
||||
| **3** | Complex integration | 12-40 | PRD + architecture | Months |
|
||||
| **4** | Enterprise scale | 40+ | Full methodology | Quarters |
|
||||
|
||||
### Level Selection Decision Tree
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START{Describe your project}
|
||||
|
||||
START -->|Bug fix, typo, patch| L0[Level 0<br/>tech-spec only]
|
||||
START -->|Small feature, 2-3 stories| L1[Level 1<br/>tech-spec + epic]
|
||||
START -->|Dashboard, multiple features| L2[Level 2<br/>PRD + optional arch]
|
||||
START -->|Platform, complex integration| L3[Level 3<br/>PRD + architecture]
|
||||
START -->|Enterprise, multi-tenant| L4[Level 4<br/>Full methodology]
|
||||
|
||||
style L0 fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style L1 fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style L2 fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style L3 fill:#fbf,stroke:#333,stroke-width:2px
|
||||
style L4 fill:#f9f,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
### Quick Keywords
|
||||
|
||||
- **Level 0:** fix, bug, typo, small change, patch
|
||||
- **Level 1:** simple, basic, small feature, add, minor
|
||||
- **Level 2:** dashboard, several features, admin panel, medium
|
||||
- **Level 3:** platform, integration, complex, system, architecture
|
||||
- **Level 4:** enterprise, multi-tenant, multiple products, ecosystem, scale
|
||||
|
||||
---
|
||||
|
||||
## How Level Detection Works
|
||||
|
||||
When you run `workflow-init`, it analyzes your project using three methods:
|
||||
|
||||
### 1. Keyword Analysis
|
||||
|
||||
Scans your description for level-specific keywords (see Quick Keywords above).
|
||||
|
||||
### 2. Story Count Estimation
|
||||
|
||||
Asks about expected scope and matches to ranges:
|
||||
|
||||
| Stories | Suggested Level |
|
||||
| ------- | --------------- |
|
||||
| 1 | Level 0 |
|
||||
| 2-10 | Level 1 |
|
||||
| 5-15 | Level 2 |
|
||||
| 12-40 | Level 3 |
|
||||
| 40+ | Level 4 |
|
||||
|
||||
**Note:** Overlap zones (5-10, 12-15) are intentional - choose based on need for product-level planning.
|
||||
|
||||
### 3. Complexity Indicators
|
||||
|
||||
Additional factors:
|
||||
|
||||
- Multiple teams involved? → Higher level
|
||||
- External integrations? → Higher level
|
||||
- Compliance requirements? → Higher level
|
||||
- Multi-tenant needs? → Level 4
|
||||
- Existing system modifications? → Consider brownfield path
|
||||
|
||||
### Manual Override
|
||||
|
||||
**You can always override the suggested level.** workflow-init asks for confirmation - if you disagree, just say so and choose the appropriate level. Trust your judgment.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
workflow-init: "Based on your description: Level 3 project. Is that correct?"
|
||||
You: "No, this is simpler - Level 2"
|
||||
workflow-init: "Got it, creating Level 2 workflow"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Five Levels
|
||||
|
||||
### Level 0: Single Atomic Change
|
||||
|
||||
**Definition:** Single-story projects like bug fixes, typos, or small patches.
|
||||
|
||||
**Story Count:** 1 story
|
||||
|
||||
**Timeline:** Hours to 1 day
|
||||
|
||||
**Documentation Requirements:**
|
||||
|
||||
- **tech-spec.md** - Technical specification with implementation details
|
||||
- Single story file
|
||||
|
||||
**Workflow Path:**
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
Tech-Spec → Implement
|
||||
```
|
||||
|
||||
**No Architecture:** Skip entirely
|
||||
**No PRD:** Tech-spec serves as complete planning doc
|
||||
|
||||
**Use For:**
|
||||
|
||||
- Bug fixes
|
||||
- Single file changes
|
||||
- Minor configuration updates
|
||||
- Small refactors
|
||||
- Typo corrections
|
||||
|
||||
**Example:** "Fix authentication token expiration bug in auth middleware"
|
||||
|
||||
**Keywords:** fix, bug, typo, small change, quick update, patch
|
||||
|
||||
---
|
||||
|
||||
### Level 1: Small Feature
|
||||
|
||||
**Definition:** Small coherent features with 2-10 related stories.
|
||||
|
||||
**Story Count:** 1-10 stories (typically 2-5)
|
||||
|
||||
**Timeline:** 1-3 days
|
||||
|
||||
**Documentation Requirements:**
|
||||
|
||||
- **tech-spec.md** - Technical specification with epic breakdown
|
||||
- **Epic organization** - Stories grouped by epic
|
||||
- 2-10 story files
|
||||
|
||||
**Workflow Path:**
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
Tech-Spec + Epic → (Optional) UX Design → Implement
|
||||
```
|
||||
|
||||
**No Architecture:** Skip entirely
|
||||
**No PRD:** Tech-spec with epic is sufficient
|
||||
|
||||
**Use For:**
|
||||
|
||||
- Single module additions
|
||||
- Small UI enhancements
|
||||
- Isolated feature additions
|
||||
- API endpoint additions (OAuth, forgot password, search)
|
||||
|
||||
**Example:** "Add OAuth social login (Google, GitHub, Facebook)"
|
||||
|
||||
**UX Note:** Tech-spec can include UX considerations inline, or run separate UX Design workflow if UI is complex.
|
||||
|
||||
**Keywords:** simple, basic, small feature, add, minor
|
||||
|
||||
---
|
||||
|
||||
### Level 2: Medium Project
|
||||
|
||||
**Definition:** Multiple related features across 1-3 epics.
|
||||
|
||||
**Story Count:** 5-15 stories
|
||||
|
||||
**Timeline:** 1-2 weeks
|
||||
|
||||
**Documentation Requirements:**
|
||||
|
||||
- **PRD.md** - Product requirements document
|
||||
- **epics.md** - Epic breakdown with stories
|
||||
- **tech-spec.md** (optional) - Or use epic-tech-specs during implementation
|
||||
- **architecture.md** (optional) - Only if system design needed
|
||||
|
||||
**Workflow Path:**
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
Analysis (recommended) → PRD + Epics → (Optional) UX Design → (Optional) Architecture → Implement
|
||||
↓
|
||||
Epic-tech-spec per epic (recommended)
|
||||
↓
|
||||
Retrospective after each epic (if >1 epic)
|
||||
```
|
||||
|
||||
**Architecture:** Optional - only if system design needed
|
||||
**Epic-Tech-Specs:** Recommended during implementation
|
||||
|
||||
**Use For:**
|
||||
|
||||
- Multiple related features
|
||||
- Cross-module enhancements
|
||||
- Admin dashboards
|
||||
- Customer portals
|
||||
- Reporting systems
|
||||
|
||||
**Example:** "Add user dashboard with analytics, preferences, and activity history"
|
||||
|
||||
**Level 2 Decision:** Choose Level 2 over Level 1 when you need product-level planning, have multiple epics, or require stakeholder alignment.
|
||||
|
||||
**Keywords:** dashboard, several features, admin panel, medium
|
||||
|
||||
---
|
||||
|
||||
### Level 3: Complex Integration
|
||||
|
||||
**Definition:** Complex systems with multiple subsystems and integrations.
|
||||
|
||||
**Story Count:** 12-40 stories
|
||||
|
||||
**Timeline:** 3-6 weeks
|
||||
|
||||
**Documentation Requirements:**
|
||||
|
||||
- **PRD.md** - Comprehensive product requirements
|
||||
- **epics.md** - Detailed epic breakdown
|
||||
- **architecture.md** - Required comprehensive system architecture
|
||||
- **UX design** (recommended for user-facing systems)
|
||||
|
||||
**Workflow Path:**
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
Analysis + Research → PRD + Epics → (Recommended) UX Design → Architecture (required) → Gate Check → Implement
|
||||
↓
|
||||
Epic-tech-spec per epic (recommended)
|
||||
↓
|
||||
Retrospective after each epic
|
||||
```
|
||||
|
||||
**Architecture:** Required - comprehensive system design
|
||||
**Gate Check:** Required - validate cohesion before implementation
|
||||
**Epic-Tech-Specs:** Highly recommended
|
||||
|
||||
**Use For:**
|
||||
|
||||
- Major feature additions
|
||||
- Architectural integrations
|
||||
- Multi-system changes
|
||||
- E-commerce platforms
|
||||
- SaaS products
|
||||
- Multi-module systems
|
||||
|
||||
**Example:** "Adding real-time collaboration features to existing document editor"
|
||||
|
||||
**Critical for Level 3:**
|
||||
|
||||
- Architecture review before planning
|
||||
- Integration strategy document
|
||||
- Backward compatibility planning
|
||||
- Phased rollout consideration
|
||||
|
||||
**Keywords:** platform, integration, complex, system, architecture
|
||||
|
||||
---
|
||||
|
||||
### Level 4: Enterprise Scale
|
||||
|
||||
**Definition:** Enterprise-scale projects across multiple products or major platform expansions.
|
||||
|
||||
**Story Count:** 40+ stories
|
||||
|
||||
**Timeline:** 3-6 months
|
||||
|
||||
**Documentation Requirements:**
|
||||
|
||||
- **Product brief** - Strategic planning document
|
||||
- **PRD.md** - Comprehensive product requirements
|
||||
- **epics.md** - Detailed epic breakdown
|
||||
- **architecture.md** - Required enterprise-grade architecture
|
||||
- **UX design** (recommended) - Design system and patterns
|
||||
|
||||
**Workflow Path:**
|
||||
|
||||
```
|
||||
(Brownfield: document-project first - nearly mandatory)
|
||||
↓
|
||||
Analysis + Research → PRD + Epics → UX Design → Enterprise Architecture → Gate Check → Implement
|
||||
↓
|
||||
Epic-tech-spec per epic (recommended)
|
||||
↓
|
||||
Additional design docs for complex subsystems
|
||||
↓
|
||||
Retrospective after each epic
|
||||
```
|
||||
|
||||
**Architecture:** Required - enterprise-grade system design including:
|
||||
|
||||
- Multi-tenancy design
|
||||
- Security architecture
|
||||
- Scalability planning
|
||||
- Integration architecture
|
||||
- Data architecture
|
||||
- Deployment architecture
|
||||
|
||||
**Gate Checks:** Required - multiple validation gates
|
||||
**Additional Design Documents:** Created during implementation as needed
|
||||
|
||||
**Use For:**
|
||||
|
||||
- Platform expansions
|
||||
- Multi-team initiatives
|
||||
- System-wide modernization
|
||||
- Multi-tenant systems
|
||||
- Product ecosystems
|
||||
- Enterprise platforms
|
||||
|
||||
**Example:** "Adding multi-tenancy to existing single-tenant SaaS platform"
|
||||
|
||||
**Critical for Enterprise:**
|
||||
|
||||
- Documentation phase nearly mandatory
|
||||
- Analysis phase (research, product brief) required
|
||||
- Full architecture review before planning
|
||||
- Extensive integration testing strategy
|
||||
- Risk assessment and mitigation planning
|
||||
- Cross-team coordination
|
||||
- Feature flag implementation
|
||||
- Migration strategy for existing data/users
|
||||
|
||||
**Keywords:** enterprise, multi-tenant, multiple products, ecosystem, scale
|
||||
|
||||
---
|
||||
|
||||
## Planning Documents by Level
|
||||
|
||||
### Understanding Document Types
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
LEVEL{What Level?}
|
||||
|
||||
LEVEL -->|0-1| TS[tech-spec<br/>Created upfront<br/>Only planning doc]
|
||||
LEVEL -->|2-4| PRD[PRD<br/>Created upfront<br/>Product planning]
|
||||
|
||||
PRD --> ARCH{Architecture<br/>needed?}
|
||||
ARCH -->|Yes<br/>Level 3-4| ARCHD[architecture.md<br/>Created upfront<br/>System design]
|
||||
ARCH -->|Optional<br/>Level 2| MAYBE[Maybe architecture<br/>if system design needed]
|
||||
|
||||
TS --> IMPL1[Implementation]
|
||||
ARCHD --> IMPL2[Implementation]
|
||||
MAYBE --> IMPL2
|
||||
|
||||
IMPL2 --> ETS[epic-tech-spec<br/>Created just-in-time<br/>Per epic during Phase 4]
|
||||
|
||||
style TS fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style PRD fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style ARCHD fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style ETS fill:#fbf,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
### Tech-Spec (Level 0-1)
|
||||
|
||||
**Created:** Upfront in Planning Phase (Phase 2)
|
||||
**Serves as:** Primary and only planning document
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Problem statement and solution
|
||||
- Source tree changes (specific files)
|
||||
- Technical implementation details
|
||||
- Detected stack and conventions (brownfield)
|
||||
- UX/UI considerations (if user-facing)
|
||||
- Testing strategy
|
||||
- Developer resources
|
||||
|
||||
**When Used:** Replaces PRD + Architecture for small projects
|
||||
|
||||
### PRD (Level 2-4)
|
||||
|
||||
**Created:** Upfront in Planning Phase (Phase 2)
|
||||
**Serves as:** Product-level planning document
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Product vision and goals
|
||||
- Feature requirements
|
||||
- Epic breakdown with stories
|
||||
- Success criteria
|
||||
- User experience considerations
|
||||
- Business context
|
||||
|
||||
**Complements:** Architecture document (system design)
|
||||
|
||||
### Architecture Document (Level 2-4)
|
||||
|
||||
**Created:** Upfront in Solutioning Phase (Phase 3)
|
||||
**Serves as:** System-level design document
|
||||
|
||||
**Scale-Adaptive Complexity:**
|
||||
|
||||
- **Level 2:** Optional, lightweight if needed
|
||||
- **Level 3:** Required, comprehensive
|
||||
- **Level 4:** Required, enterprise-grade
|
||||
|
||||
**Contains:**
|
||||
|
||||
- System components and responsibilities
|
||||
- Data models and schemas
|
||||
- Integration patterns
|
||||
- Security architecture
|
||||
- Performance considerations
|
||||
- Deployment architecture
|
||||
|
||||
**Note:** Takes the place of tech-spec for system-level planning in Level 2-4 projects.
|
||||
|
||||
### Epic-Tech-Spec (Level 2-4)
|
||||
|
||||
**Created:** Just-in-time during Implementation Phase (Phase 4)
|
||||
**Serves as:** Epic-specific implementation guide
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Epic-specific technical details
|
||||
- Detailed implementation approach for this epic
|
||||
- Code-level design decisions
|
||||
- Epic-scoped testing strategy
|
||||
- Integration points with other epics
|
||||
|
||||
**Key Difference from Tech-Spec:**
|
||||
|
||||
- **Tech-spec (0-1):** Created upfront, primary planning doc
|
||||
- **Epic-tech-spec (2-4):** Created during implementation, supplements PRD + Architecture
|
||||
|
||||
**Why Just-In-Time?**
|
||||
|
||||
- Implementation learnings inform later epic-tech-specs
|
||||
- Avoids over-planning details that may change
|
||||
- Keeps specs fresh and relevant
|
||||
- Retrospectives provide input for next epic-tech-spec
|
||||
|
||||
---
|
||||
|
||||
## Workflow Comparison
|
||||
|
||||
| Level | Analysis | Planning | Architecture | Epic-Tech-Specs | Stories | Retrospectives |
|
||||
| ----- | ----------- | ---------------- | ------------ | --------------- | ------- | ----------------------- |
|
||||
| **0** | Optional | Tech-spec | None | N/A | 1 | N/A |
|
||||
| **1** | Optional | Tech-spec + Epic | None | N/A | 2-10 | N/A |
|
||||
| **2** | Recommended | PRD | Optional | Recommended | 5-15 | After each epic (if >1) |
|
||||
| **3** | Required | PRD | Required | Recommended | 12-40 | After each epic |
|
||||
| **4** | Required | PRD | Required | Recommended | 40+ | After each epic |
|
||||
|
||||
---
|
||||
|
||||
## Brownfield Projects
|
||||
|
||||
### Critical First Step
|
||||
|
||||
🚨 **For ALL brownfield projects (Level 0-4): Run document-project BEFORE planning workflows**
|
||||
|
||||
### Why document-project is Critical
|
||||
|
||||
- **Tech-spec workflow** (Level 0-1) uses this for auto-detection
|
||||
- **PRD workflow** (Level 2-4) references existing code
|
||||
- **Architecture workflow** (Level 3-4) builds on existing structure
|
||||
- **Epic-tech-specs** reference existing implementations
|
||||
|
||||
### Brownfield Workflow Pattern
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START([Brownfield Project])
|
||||
CHECK{Has docs/<br/>index.md?}
|
||||
|
||||
START --> CHECK
|
||||
CHECK -->|No| DOC[document-project workflow<br/>Creates comprehensive docs]
|
||||
CHECK -->|Yes| PLAN[Continue to Planning]
|
||||
|
||||
DOC --> PLAN
|
||||
PLAN --> IMPL[Implementation]
|
||||
|
||||
style START fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style PLAN fill:#bfb,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
**Three Options:**
|
||||
|
||||
1. **No documentation:** Run document-project workflow (10-30 min)
|
||||
2. **Has docs, no index.md:** Run index-docs task (2-5 min)
|
||||
3. **Complete documentation:** Skip to planning
|
||||
|
||||
**For complete brownfield guidance:** See [Brownfield Development Guide](./brownfield-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Bug Fix (Level 0)
|
||||
|
||||
**Input:** "Fix email validation bug in login form"
|
||||
|
||||
**Detection:**
|
||||
|
||||
- Keywords: "fix", "bug"
|
||||
- Estimated stories: 1
|
||||
|
||||
**Result:** Level 0 → Tech-spec only
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. (Optional) Brief analysis
|
||||
2. Tech-spec with single story
|
||||
3. Implement immediately
|
||||
|
||||
**Time:** ~2-4 hours total
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Small Feature (Level 1)
|
||||
|
||||
**Input:** "Add OAuth social login (Google, GitHub, Facebook)"
|
||||
|
||||
**Detection:**
|
||||
|
||||
- Keywords: "add", "feature"
|
||||
- Estimated stories: 2-3
|
||||
|
||||
**Result:** Level 1 → Tech-spec with epic
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. (Optional) Research OAuth providers
|
||||
2. Tech-spec with epic + 3 stories
|
||||
3. (Optional) UX Design if UI is complex
|
||||
4. Implement story-by-story
|
||||
|
||||
**Time:** 1-3 days
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Customer Portal (Level 2)
|
||||
|
||||
**Input:** "Build customer portal with dashboard, tickets, billing"
|
||||
|
||||
**Detection:**
|
||||
|
||||
- Keywords: "portal", "dashboard"
|
||||
- Estimated stories: 10-12
|
||||
|
||||
**Result:** Level 2 → PRD + optional architecture
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Product Brief (recommended)
|
||||
2. PRD with epics
|
||||
3. (Optional) UX Design
|
||||
4. (Optional) Architecture if system design needed
|
||||
5. Implement with sprint planning
|
||||
6. Create epic-tech-spec for each epic as you implement
|
||||
7. Run retrospective after each epic
|
||||
|
||||
**Time:** 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: E-commerce Platform (Level 3)
|
||||
|
||||
**Input:** "Build full e-commerce platform with products, cart, checkout, admin, analytics"
|
||||
|
||||
**Detection:**
|
||||
|
||||
- Keywords: "platform", "full"
|
||||
- Estimated stories: 30-35
|
||||
|
||||
**Result:** Level 3 → PRD + Architecture required
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Research + Product Brief
|
||||
2. Comprehensive PRD
|
||||
3. UX Design (recommended)
|
||||
4. System Architecture (required)
|
||||
5. Gate check
|
||||
6. Implement with phased approach
|
||||
7. Create epic-tech-spec per epic before implementing
|
||||
8. Run retrospective after each epic
|
||||
9. Create additional design docs as needed for complex subsystems
|
||||
|
||||
**Time:** 3-6 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Adding Feature to Existing App (Brownfield Level 1)
|
||||
|
||||
**Input:** "Add search functionality to existing product catalog"
|
||||
|
||||
**Detection:**
|
||||
|
||||
- Keywords: "add", "existing"
|
||||
- Estimated stories: 3-4
|
||||
- Field type: Brownfield
|
||||
|
||||
**Result:** Level 1 Brownfield
|
||||
|
||||
**Critical First Step:**
|
||||
|
||||
1. **Run document-project** to analyze existing codebase
|
||||
|
||||
**Then Workflow:** 2. Tech-spec (uses document-project output for analysis) 3. Auto-detects existing patterns 4. Confirms conventions 5. Implement following existing patterns
|
||||
|
||||
**Time:** 1-3 days (including documentation)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Document-Project First for Brownfield
|
||||
|
||||
Always run document-project before starting any brownfield workflow. Even if you know the code, AI agents need it.
|
||||
|
||||
### 2. Trust the Detection
|
||||
|
||||
If workflow-init suggests Level 2, there's probably complexity you haven't considered. Review before overriding.
|
||||
|
||||
### 3. Start Small, Upgrade Later
|
||||
|
||||
Uncertain between Level 1 and 2? Start with Level 1. You can always run PRD creation later if needed.
|
||||
|
||||
### 4. Don't Skip Gate Checks
|
||||
|
||||
For Level 3-4, gate checks prevent costly mistakes. Invest the time upfront.
|
||||
|
||||
### 5. Create Epic-Tech-Specs Just-Before-Implementation
|
||||
|
||||
For Level 2-4, create epic-tech-spec right before implementing each epic. Don't create all upfront.
|
||||
|
||||
### 6. Run Retrospectives Between Epics
|
||||
|
||||
Capture learnings after each epic. Feed insights into next epic-tech-spec.
|
||||
|
||||
### 7. Optional UX for Level 1
|
||||
|
||||
If your Level 1 feature has complex UI, run separate UX Design. Otherwise, include UX notes in tech-spec.
|
||||
|
||||
### 8. Architecture Scales
|
||||
|
||||
Level 2 architecture is lighter than Level 3, which is lighter than Level 4. Don't over-architect.
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### A. Terminology Quick Reference
|
||||
|
||||
For complete definitions, see [Glossary](./glossary.md).
|
||||
|
||||
**Key Terms:**
|
||||
|
||||
- **Scale-Adaptive:** System that adjusts workflow based on project complexity
|
||||
- **Tech-Spec:** Technical specification document (Level 0-1, created upfront)
|
||||
- **Epic-Tech-Spec:** Epic technical specification (Level 2-4, created just-in-time)
|
||||
- **PRD:** Product Requirements Document
|
||||
- **Just-In-Time Design:** Creating epic-tech-specs during implementation, not upfront
|
||||
- **Context Injection:** Dynamic guidance via epic-tech-context and story-context workflows
|
||||
- **Greenfield:** New project from scratch
|
||||
- **Brownfield:** Existing codebase
|
||||
|
||||
### B. Workflow Path Configuration
|
||||
|
||||
The v6 system uses modular path definitions stored in YAML configuration files.
|
||||
|
||||
**Location:** `src/modules/bmm/workflows/workflow-status/paths/`
|
||||
|
||||
**Files:**
|
||||
|
||||
- `greenfield-level-0.yaml` through `greenfield-level-4.yaml`
|
||||
- `brownfield-level-0.yaml` through `brownfield-level-4.yaml`
|
||||
- `game-design.yaml`
|
||||
- `project-levels.yaml` (source of truth)
|
||||
|
||||
Each path file defines:
|
||||
|
||||
- Required vs optional workflows for each phase
|
||||
- Agent assignments
|
||||
- Expected outputs
|
||||
- Phase progression rules
|
||||
|
||||
### C. FAQ
|
||||
|
||||
**Q: What's the difference between tech-spec and epic-tech-spec?**
|
||||
A: Tech-spec (Level 0-1) is created upfront and serves as the primary planning doc. Epic-tech-spec (Level 2-4) is created during implementation per epic and supplements PRD + Architecture.
|
||||
|
||||
**Q: Why no tech-spec at Level 2+?**
|
||||
A: Level 2+ needs product-level planning (PRD) and system-level design (Architecture), which tech-spec doesn't provide. Instead, use epic-tech-specs during implementation for detailed technical guidance per epic.
|
||||
|
||||
**Q: Do I always need Architecture at Level 2?**
|
||||
A: No, it's optional. Only create Architecture if you need system-level design. Many Level 2 projects work with just PRD + epic-tech-specs.
|
||||
|
||||
**Q: Can I change levels mid-project?**
|
||||
A: Yes! If you started at Level 1 but realize it's Level 2, run create-prd to add proper planning docs. The system is flexible.
|
||||
|
||||
For more questions, see [FAQ](./faq.md).
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[Quick Start Guide](./quick-start.md)** - Get started with BMM
|
||||
- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Level 0-1
|
||||
- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
|
||||
- **[Glossary](./glossary.md)** - Complete terminology
|
||||
- **[FAQ](./faq.md)** - Common questions
|
||||
- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
|
||||
|
||||
---
|
||||
|
||||
_Scale Adaptive System - Because one size doesn't fit all._
|
||||
Reference in New Issue
Block a user