npm - bmad-method - Versions diffs - 6.0.0-alpha.4 → 6.0.0-alpha.6 - Mend

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

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

Files changed (225) hide show

package/bmad/bmm/docs/quick-spec-flow.md DELETED Viewed

@@ -1,645 +0,0 @@
-# BMad Quick Spec Flow
-**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements
-**Time to implementation:** Minutes, not hours
----
-## What is Quick Spec Flow?
-Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Level 0-1 projects. Instead of going through Product Brief → PRD → Architecture, you go **straight to a context-aware technical specification** and start coding.
-### When to Use Quick Spec Flow
-✅ **Use Quick Spec Flow (Level 0-1) when:**
-- Single bug fix or small enhancement (Level 0)
-- Small feature with 2-3 related changes (Level 1)
-- Rapid prototyping or experimentation
-- Adding to existing brownfield codebase
-- You know exactly what you want to build
-❌ **Use Full BMM Flow (Level 2-4) when:**
-- Building new products or major features (Level 2-4)
-- Need stakeholder alignment
-- Complex multi-team coordination
-- Requires extensive planning and architecture
-💡 **Not sure?** Run `workflow-init` to get a recommendation based on your project's size and complexity!
----
-## Quick Spec Flow Overview
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    QUICK SPEC FLOW                          │
-│                   (Level 0-1 Projects)                      │
-└─────────────────────────────────────────────────────────────┘
-Step 1: Run Tech-Spec Workflow
-    │
-    ├─► Detects your project stack (package.json, requirements.txt, etc.)
-    ├─► Analyzes brownfield codebase (if exists)
-    ├─► Detects test frameworks and conventions
-    ├─► Confirms conventions with you
-    ├─► Generates context-rich tech-spec
-    └─► Creates ready-to-implement stories
-Step 2: Optional - Generate Story Context (SM Agent)
-    │
-    └─► For complex scenarios only
-Step 3: Implement (DEV Agent)
-    │
-    └─► Code, test, commit
-DONE! 🚀
-```
----
-## Level 0: Single Atomic Change
-**Best for:** Bug fixes, single file changes, isolated improvements
-### What You Get
-1. **tech-spec.md** - Comprehensive technical specification with:
-   - Problem statement and solution
-   - Detected framework versions and dependencies
-   - Brownfield code patterns (if applicable)
-   - Existing test patterns to follow
-   - Specific file paths to modify
-   - Complete implementation guidance
-2. **story-[slug].md** - Single user story ready for development
-### Quick Spec Flow Commands
-```bash
-# Start Quick Spec Flow (no workflow-init needed!)
-# Load PM agent and run tech-spec
-# When complete, implement directly:
-# Load DEV agent and run dev-story
-```
-### What Makes It Quick
-- ✅ No Product Brief needed
-- ✅ No PRD needed
-- ✅ No Architecture doc needed
-- ✅ Auto-detects your stack
-- ✅ Auto-analyzes brownfield code
-- ✅ Auto-validates quality
-- ✅ Story context optional (tech-spec is comprehensive!)
-### Example Level 0 Scenarios
-- "Fix the login validation bug"
-- "Add email field to user registration form"
-- "Update API endpoint to return additional field"
-- "Improve error handling in payment processing"
----
-## Level 1: Coherent Small Feature
-**Best for:** Small features with 2-3 related user stories
-### What You Get
-1. **tech-spec.md** - Same comprehensive spec as Level 0
-2. **epics.md** - Epic organization with story breakdown
-3. **story-[epic-slug]-1.md** - First story
-4. **story-[epic-slug]-2.md** - Second story
-5. **story-[epic-slug]-3.md** - Third story (if needed)
-### Quick Spec Flow Commands
-```bash
-# Start Quick Spec Flow
-# Load PM agent and run tech-spec
-# Optional: Organize stories as a sprint
-# Load SM agent and run sprint-planning
-# Implement story-by-story:
-# Load DEV agent and run dev-story for each story
-```
-### Story Sequencing
-Stories are **automatically validated** to ensure proper sequence:
-- ✅ No forward dependencies (Story 2 can't depend on Story 3)
-- ✅ Clear dependency documentation
-- ✅ Infrastructure → Features → Polish order
-- ✅ Backend → Frontend flow
-### Example Level 1 Scenarios
-- "Add OAuth social login (Google, GitHub, Twitter)"
-- "Build user profile page with avatar upload"
-- "Implement basic search with filters"
-- "Add dark mode toggle to application"
----
-## Smart Context Discovery
-Quick Spec Flow automatically discovers and uses:
-### 1. Existing Documentation
-- Product briefs (if they exist)
-- Research documents
-- `document-project` output (brownfield codebase map)
-### 2. Project Stack
-- **Node.js:** package.json → frameworks, dependencies, scripts, test framework
-- **Python:** requirements.txt, pyproject.toml → packages, tools
-- **Ruby:** Gemfile → gems and versions
-- **Java:** pom.xml, build.gradle → Maven/Gradle dependencies
-- **Go:** go.mod → modules
-- **Rust:** Cargo.toml → crates
-- **PHP:** composer.json → packages
-### 3. Brownfield Code Patterns
-- Directory structure and organization
-- Existing code patterns (class-based, functional, MVC)
-- Naming conventions (camelCase, snake_case, PascalCase)
-- Test frameworks and patterns
-- Code style (semicolons, quotes, indentation)
-- Linter/formatter configs
-- Error handling patterns
-- Logging conventions
-- Documentation style
-### 4. Convention Confirmation
-**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**:
-```
-I've detected these conventions in your codebase:
-Code Style:
-- ESLint with Airbnb config
-- Prettier with single quotes, 2-space indent
-- No semicolons
-Test Patterns:
-- Jest test framework
-- .test.js file naming
-- expect() assertion style
-Should I follow these existing conventions? (yes/no)
-```
-**You decide:** Conform to existing patterns or establish new standards!
----
-## Modern Best Practices via WebSearch
-Quick Spec Flow stays current by using WebSearch when appropriate:
-### For Greenfield Projects
-- Searches for latest framework versions
-- Recommends official starter templates
-- Suggests modern best practices
-### For Outdated Dependencies
-- Detects if your dependencies are >2 years old
-- Searches for migration guides
-- Notes upgrade complexity
-### Starter Template Recommendations
-For greenfield projects, Quick Spec Flow recommends:
-**React:**
-- Vite (modern, fast)
-- Next.js (full-stack)
-**Python:**
-- cookiecutter templates
-- FastAPI starter
-**Node.js:**
-- NestJS CLI
-- express-generator
-**Benefits:**
-- ✅ Modern best practices baked in
-- ✅ Proper project structure
-- ✅ Build tooling configured
-- ✅ Testing framework set up
-- ✅ Faster time to first feature
----
-## UX/UI Considerations
-For user-facing changes, Quick Spec Flow captures:
-- UI components affected (create vs modify)
-- UX flow changes (current vs new)
-- Responsive design needs (mobile, tablet, desktop)
-- Accessibility requirements:
-  - Keyboard navigation
-  - Screen reader compatibility
-  - ARIA labels
-  - Color contrast standards
-- User feedback patterns:
-  - Loading states
-  - Error messages
-  - Success confirmations
-  - Progress indicators
----
-## Auto-Validation & Quality Assurance
-Quick Spec Flow **automatically validates** everything:
-### Tech-Spec Validation (Always Runs)
-Checks:
-- ✅ Context gathering completeness
-- ✅ Definitiveness (no "use X or Y" statements)
-- ✅ Brownfield integration quality
-- ✅ Stack alignment
-- ✅ Implementation readiness
-Generates scores:
-```
-✅ Validation Passed!
-- Context Gathering: Comprehensive
-- Definitiveness: All definitive
-- Brownfield Integration: Excellent
-- Stack Alignment: Perfect
-- Implementation Readiness: ✅ Ready
-```
-### Story Validation (Level 1 Only)
-Checks:
-- ✅ Story sequence (no forward dependencies!)
-- ✅ Acceptance criteria quality (specific, testable)
-- ✅ Completeness (all tech spec tasks covered)
-- ✅ Clear dependency documentation
-**Auto-fixes issues if found!**
----
-## Complete User Journey
-### Scenario 1: Bug Fix (Level 0)
-**Goal:** Fix login validation bug
-**Steps:**
-1. **Start:** Load PM agent, say "I want to fix the login validation bug"
-2. **PM runs tech-spec workflow:**
-   - Asks: "What problem are you solving?"
-   - You explain the validation issue
-   - Detects your Node.js stack (Express 4.18.2, Jest for testing)
-   - Analyzes existing UserService code patterns
-   - Asks: "Should I follow your existing conventions?" → You say yes
-   - Generates tech-spec.md with specific file paths and patterns
-   - Creates story-login-fix.md
-3. **Implement:** Load DEV agent, run `dev-story`
-   - DEV reads tech-spec (has all context!)
-   - Implements fix following existing patterns
-   - Runs tests (following existing Jest patterns)
-   - Done!
-**Total time:** 15-30 minutes (mostly implementation)
----
-### Scenario 2: Small Feature (Level 1)
-**Goal:** Add OAuth social login (Google, GitHub)
-**Steps:**
-1. **Start:** Load PM agent, say "I want to add OAuth social login"
-2. **PM runs tech-spec workflow:**
-   - Asks about the feature scope
-   - You specify: Google and GitHub OAuth
-   - Detects your stack (Next.js 13.4, NextAuth.js already installed!)
-   - Analyzes existing auth patterns
-   - Confirms conventions with you
-   - Generates:
-     - tech-spec.md (comprehensive implementation guide)
-     - epics.md (OAuth Integration epic)
-     - story-oauth-1.md (Backend OAuth setup)
-     - story-oauth-2.md (Frontend login buttons)
-3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning`
-4. **Implement Story 1:**
-   - Load DEV agent, run `dev-story` for story 1
-   - DEV implements backend OAuth
-5. **Implement Story 2:**
-   - DEV agent, run `dev-story` for story 2
-   - DEV implements frontend
-   - Done!
-**Total time:** 1-3 hours (mostly implementation)
----
-## Integration with Phase 4 Workflows
-Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
-### story-context (SM Agent)
-- ✅ Recognizes tech-spec.md as authoritative source
-- ✅ Extracts context from tech-spec (replaces PRD)
-- ✅ Generates XML context for complex scenarios
-### create-story (SM Agent)
-- ✅ Can work with tech-spec.md instead of PRD
-- ✅ Uses epics.md from tech-spec workflow
-- ✅ Creates additional stories if needed
-### sprint-planning (SM Agent)
-- ✅ Works with epics.md from tech-spec
-- ✅ Organizes Level 1 stories for coordinated implementation
-- ✅ Tracks progress through sprint-status.yaml
-### dev-story (DEV Agent)
-- ✅ Reads stories generated by tech-spec
-- ✅ Uses tech-spec.md as comprehensive context
-- ✅ Implements following detected conventions
----
-## Comparison: Quick Spec vs Full BMM
-| Aspect                | Quick Spec Flow (Level 0-1)  | Full BMM Flow (Level 2-4)          |
-| --------------------- | ---------------------------- | ---------------------------------- |
-| **Setup**             | None (standalone)            | workflow-init recommended          |
-| **Planning Docs**     | tech-spec.md only            | Product Brief → PRD → Architecture |
-| **Time to Code**      | Minutes                      | Hours to days                      |
-| **Best For**          | Bug fixes, small features    | New products, major features       |
-| **Context Discovery** | Automatic                    | Manual + guided                    |
-| **Story Context**     | Optional (tech-spec is rich) | Required (generated from PRD)      |
-| **Validation**        | Auto-validates everything    | Manual validation steps            |
-| **Brownfield**        | Auto-analyzes and conforms   | Manual documentation required      |
-| **Conventions**       | Auto-detects and confirms    | Document in PRD/Architecture       |
----
-## When to Graduate from Quick Spec to Full BMM
-Start with Quick Spec, but switch to Full BMM when:
-- ❌ Project grows beyond 3-5 stories
-- ❌ Multiple teams need coordination
-- ❌ Stakeholders need formal documentation
-- ❌ Product vision is unclear
-- ❌ Architectural decisions need deep analysis
-- ❌ Compliance/regulatory requirements exist
-💡 **Tip:** You can always run `workflow-init` later to transition from Quick Spec to Full BMM!
----
-## Quick Spec Flow - Key Benefits
-### 🚀 **Speed**
-- No Product Brief
-- No PRD
-- No Architecture doc
-- Straight to implementation
-### 🧠 **Intelligence**
-- Auto-detects stack
-- Auto-analyzes brownfield
-- Auto-validates quality
-- WebSearch for current info
-### 📐 **Respect for Existing Code**
-- Detects conventions
-- Asks for confirmation
-- Follows patterns
-- Adapts vs. changes
-### ✅ **Quality**
-- Auto-validation
-- Definitive decisions (no "or" statements)
-- Comprehensive context
-- Clear acceptance criteria
-### 🎯 **Focus**
-- Level 0: Single atomic change
-- Level 1: Coherent small feature
-- No scope creep
-- Fast iteration
----
-## Getting Started
-### Prerequisites
-- BMad Method installed (`npx bmad-method install`)
-- Project directory with code (or empty for greenfield)
-### Quick Start Commands
-```bash
-# For a quick bug fix or small change:
-# 1. Load PM agent
-# 2. Say: "I want to [describe your change]"
-# 3. PM will ask if you want to run tech-spec
-# 4. Answer questions about your change
-# 5. Get tech-spec + story
-# 6. Load DEV agent and implement!
-# For a small feature with multiple stories:
-# Same as above, but get epic + 2-3 stories
-# Optionally use SM sprint-planning to organize
-```
-### No workflow-init Required!
-Quick Spec Flow is **fully standalone**:
-- Detects if you're Level 0 or Level 1
-- Asks for greenfield vs brownfield
-- Works without status file tracking
-- Perfect for rapid prototyping
----
-## FAQ
-### Q: Can I use Quick Spec Flow on an existing project?
-**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them.
-### Q: What if I don't have a package.json or requirements.txt?
-**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices.
-### Q: Do I need to run workflow-init first?
-**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help.
-### Q: Can I use this for frontend changes?
-**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements.
-### Q: What if my Level 0 project grows?
-**A:** No problem! You can always transition to Full BMM by running workflow-init and create-prd. Your tech-spec becomes input for the PRD.
-### Q: Do I need story-context for every story?
-**A:** Usually no! Tech-spec is comprehensive enough for most Level 0-1 projects. Only use story-context for complex edge cases.
-### Q: Can I skip validation?
-**A:** No, validation always runs automatically. But it's fast and catches issues early!
-### Q: Will it work with my team's code style?
-**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones.
----
-## Tips & Best Practices
-### 1. **Be Specific in Discovery**
-When describing your change, provide specifics:
-- ✅ "Fix email validation in UserService to allow plus-addressing"
-- ❌ "Fix validation bug"
-### 2. **Trust the Convention Detection**
-If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
-### 3. **Use WebSearch Recommendations for Greenfield**
-Starter templates save hours of setup time. Let Quick Spec Flow find the best ones.
-### 4. **Review the Auto-Validation**
-When validation runs, read the scores. They tell you if your spec is production-ready.
-### 5. **Story Context is Optional**
-For Level 0, try going directly to dev-story first. Only add story-context if you hit complexity.
-### 6. **Keep Level 0 Truly Atomic**
-If your "single change" needs 3+ files, it might be Level 1. Let the workflow guide you.
-### 7. **Validate Story Sequence for Level 1**
-When you get multiple stories, check the dependency validation output. Proper sequence matters!
----
-## Real-World Examples
-### Example 1: Adding Logging (Level 0)
-**Input:** "Add structured logging to payment processing"
-**Tech-Spec Output:**
-- Detected: winston 3.8.2 already in package.json
-- Analyzed: Existing services use winston with JSON format
-- Confirmed: Follow existing logging patterns
-- Generated: Specific file paths, log levels, format example
-- Story: Ready to implement in 1-2 hours
-**Result:** Consistent logging added, following team patterns, no research needed.
----
-### Example 2: Search Feature (Level 1)
-**Input:** "Add search to product catalog with filters"
-**Tech-Spec Output:**
-- Detected: React 18.2.0, MUI component library, Express backend
-- Analyzed: Existing ProductList component patterns
-- Confirmed: Follow existing API and component structure
-- Generated:
-  - Epic: Product Search Functionality
-  - Story 1: Backend search API with filters
-  - Story 2: Frontend search UI component
-- Auto-validated: Story 1 → Story 2 sequence correct
-**Result:** Search feature implemented in 4-6 hours with proper architecture.
----
-## Summary
-Quick Spec Flow is your **fast path from idea to implementation** for:
-- 🐛 Bug fixes
-- ✨ Small features
-- 🚀 Rapid prototyping
-- 🔧 Quick enhancements
-**Key Features:**
-- Auto-detects your stack
-- Auto-analyzes brownfield code
-- Auto-validates quality
-- Respects existing conventions
-- Uses WebSearch for modern practices
-- Generates comprehensive tech-specs
-- Creates implementation-ready stories
-**Time to code:** Minutes, not hours.
-**Ready to try it?** Load the PM agent and say what you want to build! 🚀
----
-## Next Steps
-- **Try it now:** Load PM agent and describe a small change
-- **Learn more:** See `src/modules/bmm/workflows/README.md` for full BMM workflow guide
-- **Need help deciding?** Run `workflow-init` to get a recommendation
-- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
----
-_Quick Spec Flow - Because not every change needs a Product Brief._