agentvibes 2.12.4 → 2.12.6

package/.bmad/bmm/docs/scale-adaptive-system.md

@@ -1,612 +0,0 @@
-# BMad Method Scale Adaptive System
-
-**Automatically adapts workflows to project complexity - from quick fixes to enterprise systems**
-
----
-
-## Overview
-
-The **Scale Adaptive System** intelligently routes projects to the right planning methodology based on complexity, not arbitrary story counts.
-
-### The Problem
-
-Traditional methodologies apply the same process to every project:
-
-- Bug fix requires full design docs
-- Enterprise system built with minimal planning
-- One-size-fits-none approach
-
-### The Solution
-
-BMad Method adapts to three distinct planning tracks:
-
-- **Quick Flow**: Tech-spec only, implement immediately
-- **BMad Method**: PRD + Architecture, structured approach
-- **Enterprise Method**: Full planning with security/devops/test
-
-**Result**: Right planning depth for every project.
-
----
-
-## Quick Reference
-
-### Three Tracks at a Glance
-
-| Track                 | Planning Depth        | Time Investment | Best For                                   |
-| --------------------- | --------------------- | --------------- | ------------------------------------------ |
-| **Quick Flow**        | Tech-spec only        | Hours to 1 day  | Simple features, bug fixes, clear scope    |
-| **BMad Method**       | PRD + Arch + UX       | 1-3 days        | Products, platforms, complex features      |
-| **Enterprise Method** | Method + Test/Sec/Ops | 3-7 days        | Enterprise needs, compliance, multi-tenant |
-
-### Decision Tree
-
-```mermaid
-flowchart TD
-    START{Describe your project}
-
-    START -->|Bug fix, simple feature| Q1{Scope crystal clear?}
-    START -->|Product, platform, complex| M[BMad Method<br/>PRD + Architecture]
-    START -->|Enterprise, compliance| E[Enterprise Method<br/>Extended Planning]
-
-    Q1 -->|Yes| QF[Quick Flow<br/>Tech-spec only]
-    Q1 -->|Uncertain| M
-
-    style QF fill:#bfb,stroke:#333,stroke-width:2px,color:#000
-    style M fill:#bbf,stroke:#333,stroke-width:2px,color:#000
-    style E fill:#f9f,stroke:#333,stroke-width:2px,color:#000
-```
-
-### Quick Keywords
-
-- **Quick Flow**: fix, bug, simple, add, clear scope
-- **BMad Method**: product, platform, dashboard, complex, multiple features
-- **Enterprise Method**: enterprise, multi-tenant, compliance, security, audit
-
----
-
-## How Track Selection Works
-
-When you run `workflow-init`, it guides you through an educational choice:
-
-### 1. Description Analysis
-
-Analyzes your project description for complexity indicators and suggests an appropriate track.
-
-### 2. Educational Presentation
-
-Shows all three tracks with:
-
-- Time investment
-- Planning approach
-- Benefits and trade-offs
-- AI agent support level
-- Concrete examples
-
-### 3. Honest Recommendation
-
-Provides tailored recommendation based on:
-
-- Complexity keywords
-- Greenfield vs brownfield
-- User's description
-
-### 4. User Choice
-
-You choose the track that fits your situation. The system guides but never forces.
-
-**Example:**
-
-```
-workflow-init: "Based on 'Add user dashboard with analytics', I recommend BMad Method.
-               This involves multiple features and system design. The PRD + Architecture
-               gives AI agents complete context for better code generation."
-
-You: "Actually, this is simpler than it sounds. Quick Flow."
-
-workflow-init: "Got it! Using Quick Flow with tech-spec."
-```
-
----
-
-## The Three Tracks
-
-### Track 1: Quick Flow
-
-**Definition**: Fast implementation with tech-spec planning.
-
-**Time**: Hours to 1 day of planning
-
-**Planning Docs**:
-
-- Tech-spec.md (implementation-focused)
-- Story files (1-15 typically, auto-detects epic structure)
-
-**Workflow Path**:
-
-```
-(Brownfield: document-project first if needed)
-↓
-Tech-Spec → Implement
-```
-
-**Use For**:
-
-- Bug fixes
-- Simple features
-- Enhancements with clear scope
-- Quick additions
-
-**Story Count**: Typically 1-15 stories (guidance, not rule)
-
-**Example**: "Fix authentication token expiration bug"
-
-**AI Agent Support**: Basic - minimal context provided
-
-**Trade-off**: Less planning = higher rework risk if complexity emerges
-
----
-
-### Track 2: BMad Method (RECOMMENDED)
-
-**Definition**: Full product + system design planning.
-
-**Time**: 1-3 days of planning
-
-**Planning Docs**:
-
-- PRD.md (functional and non-functional requirements)
-- Architecture.md (system design)
-- UX Design (if UI components)
-- Epics and Stories (created after architecture)
-
-**Workflow Path**:
-
-```
-(Brownfield: document-project first if needed)
-↓
-(Optional: Analysis phase - brainstorm, research, product brief)
-↓
-PRD → (Optional UX) → Architecture → Create Epics and Stories → Implementation Readiness Check → Implement
-```
-
-**Use For**:
-
-**Greenfield**:
-
-- Products
-- Platforms
-- Multi-feature initiatives
-
-**Brownfield**:
-
-- Complex additions (new UIs + APIs)
-- Major refactors
-- New modules
-
-**Story Count**: Typically 10-50+ stories (guidance, not rule)
-
-**Examples**:
-
-- "User dashboard with analytics and preferences"
-- "Add real-time collaboration to existing document editor"
-- "Payment integration system"
-
-**AI Agent Support**: Exceptional - complete context for coding partnership
-
-**Why Architecture for Brownfield?**
-
-Your brownfield documentation might be huge. Architecture workflow distills massive codebase context into a focused solution design specific to YOUR project. This keeps AI agents focused without getting lost in existing code.
-
-**Benefits**:
-
-- Complete AI agent context
-- Prevents architectural drift
-- Fewer surprises during implementation
-- Better code quality
-- Faster overall delivery (planning pays off)
-
----
-
-### Track 3: Enterprise Method
-
-**Definition**: Extended planning with security, devops, and test strategy.
-
-**Time**: 3-7 days of planning
-
-**Planning Docs**:
-
-- All BMad Method docs PLUS:
-- Security Architecture
-- DevOps Strategy
-- Test Strategy
-- Compliance documentation
-
-**Workflow Path**:
-
-```
-(Brownfield: document-project nearly mandatory)
-↓
-Analysis (recommended/required) → PRD → UX → Architecture
-↓
-Create Epics and Stories
-↓
-Security Architecture → DevOps Strategy → Test Strategy
-↓
-Implementation Readiness Check → Implement
-```
-
-**Use For**:
-
-- Enterprise requirements
-- Multi-tenant systems
-- Compliance needs (HIPAA, SOC2, etc.)
-- Mission-critical systems
-- Security-sensitive applications
-
-**Story Count**: Typically 30+ stories (but defined by enterprise needs, not count)
-
-**Examples**:
-
-- "Multi-tenant SaaS platform"
-- "HIPAA-compliant patient portal"
-- "Add SOC2 audit logging to enterprise app"
-
-**AI Agent Support**: Elite - comprehensive enterprise planning
-
-**Critical for Enterprise**:
-
-- Security architecture and threat modeling
-- DevOps pipeline planning
-- Comprehensive test strategy
-- Risk assessment
-- Compliance mapping
-
----
-
-## Planning Documents by Track
-
-### Quick Flow Documents
-
-**Created**: Upfront in Planning Phase
-
-**Tech-Spec**:
-
-- Problem statement and solution
-- Source tree changes
-- Technical implementation details
-- Detected stack and conventions (brownfield)
-- UX/UI considerations (if user-facing)
-- Testing strategy
-
-**Serves as**: Complete planning document (replaces PRD + Architecture)
-
----
-
-### BMad Method Documents
-
-**Created**: Upfront in Planning and Solutioning Phases
-
-**PRD (Product Requirements Document)**:
-
-- Product vision and goals
-- Functional requirements (FRs)
-- Non-functional requirements (NFRs)
-- Success criteria
-- User experience considerations
-- Business context
-
-**Note**: Epics and stories are created AFTER architecture in the create-epics-and-stories workflow
-
-**Architecture Document**:
-
-- System components and responsibilities
-- Data models and schemas
-- Integration patterns
-- Security architecture
-- Performance considerations
-- Deployment architecture
-
-**For Brownfield**: Acts as focused "solution design" that distills existing codebase into integration plan
-
----
-
-### Enterprise Method Documents
-
-**Created**: Extended planning across multiple phases
-
-Includes all BMad Method documents PLUS:
-
-**Security Architecture**:
-
-- Threat modeling
-- Authentication/authorization design
-- Data protection strategy
-- Audit requirements
-
-**DevOps Strategy**:
-
-- CI/CD pipeline design
-- Infrastructure architecture
-- Monitoring and alerting
-- Disaster recovery
-
-**Test Strategy**:
-
-- Test approach and coverage
-- Automation strategy
-- Quality gates
-- Performance testing
-
----
-
-## Workflow Comparison
-
-| Track           | Analysis    | Planning  | Architecture | Security/Ops | Typical Stories |
-| --------------- | ----------- | --------- | ------------ | ------------ | --------------- |
-| **Quick Flow**  | Optional    | Tech-spec | None         | None         | 1-15            |
-| **BMad Method** | Recommended | PRD + UX  | Required     | None         | 10-50+          |
-| **Enterprise**  | Required    | PRD + UX  | Required     | Required     | 30+             |
-
-**Note**: Story counts are GUIDANCE based on typical usage, NOT definitions of tracks.
-
----
-
-## Brownfield Projects
-
-### Critical First Step
-
-For ALL brownfield projects: Run `document-project` BEFORE planning workflows.
-
-### Why document-project is Critical
-
-**Quick Flow** uses it for:
-
-- Auto-detecting existing patterns
-- Understanding codebase structure
-- Confirming conventions
-
-**BMad Method** uses it for:
-
-- Architecture inputs (existing structure)
-- Integration design
-- Pattern consistency
-
-**Enterprise Method** uses it for:
-
-- Security analysis
-- Integration architecture
-- Risk assessment
-
-### Brownfield Workflow Pattern
-
-```mermaid
-flowchart TD
-    START([Brownfield Project])
-    CHECK{Has docs/<br/>index.md?}
-
-    START --> CHECK
-    CHECK -->|No| DOC[document-project workflow<br/>10-30 min]
-    CHECK -->|Yes| TRACK[Choose Track]
-
-    DOC --> TRACK
-    TRACK -->|Quick| QF[Tech-Spec]
-    TRACK -->|Method| M[PRD + Arch]
-    TRACK -->|Enterprise| E[PRD + Arch + Sec/Ops]
-
-    style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
-    style TRACK fill:#bfb,stroke:#333,stroke-width:2px,color:#000
-```
-
----
-
-## Common Scenarios
-
-### Scenario 1: Bug Fix (Quick Flow)
-
-**Input**: "Fix email validation bug in login form"
-
-**Detection**: Keywords "fix", "bug"
-
-**Track**: Quick Flow
-
-**Workflow**:
-
-1. (Optional) Brief analysis
-2. Tech-spec with single story
-3. Implement immediately
-
-**Time**: 2-4 hours total
-
----
-
-### Scenario 2: Small Feature (Quick Flow)
-
-**Input**: "Add OAuth social login (Google, GitHub, Facebook)"
-
-**Detection**: Keywords "add", "feature", clear scope
-
-**Track**: Quick Flow
-
-**Workflow**:
-
-1. (Optional) Research OAuth providers
-2. Tech-spec with 3 stories
-3. Implement story-by-story
-
-**Time**: 1-3 days
-
----
-
-### Scenario 3: Customer Portal (BMad Method)
-
-**Input**: "Build customer portal with dashboard, tickets, billing"
-
-**Detection**: Keywords "portal", "dashboard", multiple features
-
-**Track**: BMad Method
-
-**Workflow**:
-
-1. (Recommended) Product Brief
-2. PRD (FRs/NFRs)
-3. (If UI) UX Design
-4. Architecture (system design)
-5. Create Epics and Stories
-6. Implementation Readiness Check
-7. Implement with sprint planning
-
-**Time**: 1-2 weeks
-
----
-
-### Scenario 4: E-commerce Platform (BMad Method)
-
-**Input**: "Build e-commerce platform with products, cart, checkout, admin, analytics"
-
-**Detection**: Keywords "platform", multiple subsystems
-
-**Track**: BMad Method
-
-**Workflow**:
-
-1. Research + Product Brief
-2. Comprehensive PRD (FRs/NFRs)
-3. UX Design (recommended)
-4. System Architecture (required)
-5. Create Epics and Stories
-6. Implementation Readiness Check
-7. Implement with phased approach
-
-**Time**: 3-6 weeks
-
----
-
-### Scenario 5: Brownfield Addition (BMad Method)
-
-**Input**: "Add search functionality to existing product catalog"
-
-**Detection**: Brownfield + moderate complexity
-
-**Track**: BMad Method (not Quick Flow)
-
-**Critical First Step**:
-
-1. **Run document-project** to analyze existing codebase
-
-**Then Workflow**:
-
-2. PRD for search feature (FRs/NFRs)
-3. Architecture (integration design - highly recommended)
-4. Create Epics and Stories
-5. Implementation Readiness Check
-6. Implement following existing patterns
-
-**Time**: 1-2 weeks
-
-**Why Method not Quick Flow?**: Integration with existing catalog system benefits from architecture planning to ensure consistency.
-
----
-
-### Scenario 6: Multi-tenant Platform (Enterprise Method)
-
-**Input**: "Add multi-tenancy to existing single-tenant SaaS platform"
-
-**Detection**: Keywords "multi-tenant", enterprise scale
-
-**Track**: Enterprise Method
-
-**Workflow**:
-
-1. Document-project (mandatory)
-2. Research (compliance, security)
-3. PRD (multi-tenancy requirements - FRs/NFRs)
-4. Architecture (tenant isolation design)
-5. Create Epics and Stories
-6. Security Architecture (data isolation, auth)
-7. DevOps Strategy (tenant provisioning, monitoring)
-8. Test Strategy (tenant isolation testing)
-9. Implementation Readiness Check
-10. Phased implementation
-
-**Time**: 3-6 months
-
----
-
-## Best Practices
-
-### 1. Document-Project First for Brownfield
-
-Always run `document-project` before starting brownfield planning. AI agents need existing codebase context.
-
-### 2. Trust the Recommendation
-
-If `workflow-init` suggests BMad Method, there's probably complexity you haven't considered. Review carefully before overriding.
-
-### 3. Start Smaller if Uncertain
-
-Uncertain between Quick Flow and Method? Start with Quick Flow. You can create PRD later if needed.
-
-### 4. Don't Skip Implementation Readiness Check
-
-For BMad Method and Enterprise, implementation readiness checks prevent costly mistakes. Invest the time.
-
-### 5. Architecture is Optional but Recommended for Brownfield
-
-Brownfield BMad Method makes architecture optional, but it's highly recommended. It distills complex codebase into focused solution design.
-
-### 6. Discovery Phase Based on Need
-
-Brainstorming and research are offered regardless of track. Use them when you need to think through the problem space.
-
-### 7. Product Brief for Greenfield Method
-
-Product Brief is only offered for greenfield BMad Method and Enterprise. It's optional but helps with strategic thinking.
-
----
-
-## Key Differences from Legacy System
-
-### Old System (Levels 0-4)
-
-- Arbitrary story count thresholds
-- Level 2 vs Level 3 based on story count
-- Confusing overlap zones (5-10 stories, 12-40 stories)
-- Tech-spec and PRD shown as conflicting options
-
-### New System (3 Tracks)
-
-- Methodology-based distinction (not story counts)
-- Story counts as guidance, not definitions
-- Clear track purposes:
-  - Quick Flow = Implementation-focused
-  - BMad Method = Product + system design
-  - Enterprise = Extended with security/ops
-- Mutually exclusive paths chosen upfront
-- Educational decision-making
-
----
-
-## Migration from Old System
-
-If you have existing projects using the old level system:
-
-- **Level 0-1** → Quick Flow
-- **Level 2-3** → BMad Method
-- **Level 4** → Enterprise Method
-
-Run `workflow-init` on existing projects to migrate to new tracking system. It detects existing planning artifacts and creates appropriate workflow tracking.
-
----
-
-## Related Documentation
-
-- **[Quick Start Guide](./quick-start.md)** - Get started with BMM
-- **[Quick Spec Flow](./quick-spec-flow.md)** - Details on Quick Flow track
-- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
-- **[Glossary](./glossary.md)** - Complete terminology
-- **[FAQ](./faq.md)** - Common questions
-- **[Workflows Guide](./README.md#-workflow-guides)** - Complete workflow reference
-
----
-
-_Scale Adaptive System - Right planning depth for every project._