root
/
Midtrans-Middleware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Midtrans-Middleware/.bmad/bmm/docs/quick-spec-flow.md

653 lines
18 KiB
Markdown
Raw Blame History

# 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 Quick Flow track 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 Flow track when:**
- Single bug fix or small enhancement
- Small feature with clear scope (typically 1-15 stories)
- Rapid prototyping or experimentation
- Adding to existing brownfield codebase
- You know exactly what you want to build
❌ **Use BMad Method or Enterprise tracks when:**
- Building new products or major features
- 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 needs!
---
## Quick Spec Flow Overview
```mermaid
flowchart TD
START[Step 1: Run Tech-Spec Workflow]
DETECT[Detects project stack<br/>package.json, requirements.txt, etc.]
ANALYZE[Analyzes brownfield codebase<br/>if exists]
TEST[Detects test frameworks<br/>and conventions]
CONFIRM[Confirms conventions<br/>with you]
GENERATE[Generates context-rich<br/>tech-spec]
STORIES[Creates ready-to-implement<br/>stories]
OPTIONAL[Step 2: Optional<br/>Generate Story Context<br/>SM Agent<br/>For complex scenarios only]
IMPL[Step 3: Implement<br/>DEV Agent<br/>Code, test, commit]
DONE[DONE! 🚀]
START --> DETECT
DETECT --> ANALYZE
ANALYZE --> TEST
TEST --> CONFIRM
CONFIRM --> GENERATE
GENERATE --> STORIES
STORIES --> OPTIONAL
OPTIONAL -.->|Optional| IMPL
STORIES --> IMPL
IMPL --> DONE
style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000
style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style IMPL fill:#bbf,stroke:#333,stroke-width:2px,color:#000
style DONE fill:#f9f,stroke:#333,stroke-width:3px,color:#000
```
---
## 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 Single Change 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"
---
## Coherent Small Feature
**Best for:** Small features with 2-3 related user stories
### What You Get
1. **tech-spec.md** - Same comprehensive spec as single change projects
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 Small Feature 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 and 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 (Multi-Story Features)
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 (Single Change)
**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 (Multi-Story)
**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 multi-story features 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 Flow Track | BMad Method/Enterprise Tracks |
| --------------------- | ---------------------------- | ---------------------------------- |
| **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 Flow to BMad Method
Start with Quick Flow, but switch to BMad Method when:
- ❌ Project grows beyond initial scope
- ❌ 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 Flow to BMad Method!
---
## 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**
- Single atomic changes
- Coherent small features
- 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 it's a single change or multi-story feature
- 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 Quick Flow project grows?
**A:** No problem! You can always transition to BMad Method 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 Quick Flow 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 and 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 single changes, try going directly to dev-story first. Only add story-context if you hit complexity.
### 6. **Keep Single Changes Truly Atomic**
If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you.
### 7. **Validate Story Sequence for Multi-Story Features**
When you get multiple stories, check the dependency validation output. Proper sequence matters!
---
## Real-World Examples
### Example 1: Adding Logging (Single Change)
**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 (Multi-Story)
**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 the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation
- **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._
Reference in New Issue View Git Blame Copy Permalink