BMAD-METHOD/docs/quick-spec-flow.md

# 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._