18 KiB

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 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

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
story-[slug].md - Single user story ready for development

Quick Spec Flow Commands

# 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

tech-spec.md - Same comprehensive spec as Level 0
epics.md - Epic organization with story breakdown
story-[epic-slug]-1.md - First story
story-[epic-slug]-2.md - Second story
story-[epic-slug]-3.md - Third story (if needed)

Quick Spec Flow Commands

# 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:

Start: Load PM agent, say "I want to fix the login validation bug"
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
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:

Start: Load PM agent, say "I want to add OAuth social login"
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)
Optional Sprint Planning: Load SM agent, run sprint-planning
Implement Story 1:
- Load DEV agent, run dev-story for story 1
- DEV implements backend OAuth
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

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

18 KiB Raw Blame History

BMad Quick Spec Flow

What is Quick Spec Flow?

When to Use Quick Spec Flow

Quick Spec Flow Overview

Level 0: Single Atomic Change

What You Get

Quick Spec Flow Commands

What Makes It Quick

Example Level 0 Scenarios

Level 1: Coherent Small Feature

What You Get

Quick Spec Flow Commands

Story Sequencing

Example Level 1 Scenarios

Smart Context Discovery

1. Existing Documentation

2. Project Stack

3. Brownfield Code Patterns

4. Convention Confirmation

Modern Best Practices via WebSearch

For Greenfield Projects

For Outdated Dependencies

Starter Template Recommendations

UX/UI Considerations

Auto-Validation & Quality Assurance

Tech-Spec Validation (Always Runs)

Story Validation (Level 1 Only)

Complete User Journey

Scenario 1: Bug Fix (Level 0)

Scenario 2: Small Feature (Level 1)

Integration with Phase 4 Workflows

story-context (SM Agent)

create-story (SM Agent)

sprint-planning (SM Agent)

dev-story (DEV Agent)

Comparison: Quick Spec vs Full BMM

When to Graduate from Quick Spec to Full BMM

Quick Spec Flow - Key Benefits

🚀 Speed

🧠 Intelligence

📐 Respect for Existing Code

✅ Quality

🎯 Focus

Getting Started

Prerequisites

Quick Start Commands

No workflow-init Required!

FAQ

Q: Can I use Quick Spec Flow on an existing project?

Q: What if I don't have a package.json or requirements.txt?

Q: Do I need to run workflow-init first?

Q: Can I use this for frontend changes?

Q: What if my Level 0 project grows?

Q: Do I need story-context for every story?

Q: Can I skip validation?

Q: Will it work with my team's code style?

Tips & Best Practices

1. Be Specific in Discovery

2. Trust the Convention Detection

3. Use WebSearch Recommendations for Greenfield

4. Review the Auto-Validation

5. Story Context is Optional

6. Keep Level 0 Truly Atomic

7. Validate Story Sequence for Level 1

Real-World Examples

Example 1: Adding Logging (Level 0)

Example 2: Search Feature (Level 1)

Summary

Next Steps

18 KiB

Raw Blame History