feat: transform tech-spec workflow into intelligent Quick Spec Flow for Level 0-1

This major enhancement revolutionizes the tech-spec workflow from a basic template-filling exercise into a context-aware, intelligent planning system for rapid development of bug fixes and small features. ## Tech-Spec Workflow Transformation (11 files) ### Core Workflow Intelligence (instructions.md) - Add standalone mode with interactive level/field-type detection - Implement brownfield convention detection and user confirmation - Integrate WebSearch for current framework versions and starter templates - Add comprehensive context discovery (stack, patterns, dependencies) - Implement auto-validation with quality scoring (always runs) - Add UX/UI considerations capture for user-facing changes - Add test framework detection and pattern analysis - Transform from batch generation to living document approach ### Comprehensive Tech-Spec Template (tech-spec-template.md) - Expand from 8 to 23 sections for complete context - Add Context section (available docs, project stack, existing structure) - Add Development Context (conventions, test framework, existing code) - Add UX/UI Considerations section - Add Developer Resources (file paths, key locations, testing) - Add Integration Points and Configuration Changes - All sections populated via template-output tags during workflow ### Enhanced Story Generation - Level 0 (instructions-level0-story.md): Extract from comprehensive tech-spec - Level 1 (instructions-level1-stories.md): Add story sequence validation, AC quality checks - User Story Template: Add Dev Agent Record sections for implementation tracking - Epic Template: Complete rewrite with proper structure and variables ### Validation & Quality (checklist.md) - Add context gathering completeness checks - Add definitiveness validation (no "use X or Y" statements) - Add brownfield integration quality scoring - Add stack alignment verification - Add implementation readiness assessment - Auto-generates validation report with scores ### Configuration (workflow.yaml) - Add runtime variables: project_level, project_type, development_context, change_type, field_type - Enable standalone operation without workflow-status.yaml - Support both workflow-init integration and quick-start mode ## Phase 4 Integration (3 files) ### Story Context Workflow - Add tech_spec to input_file_patterns (recognizes as authoritative source) - Update instructions to prioritize tech-spec for Level 0-1 projects - Tech-spec provides brownfield analysis, framework details, existing patterns ### Create Story Workflow - Add tech_spec to input_file_patterns - Enable story generation from tech-spec (alternative to PRD) - Supports both Quick Spec Flow and traditional BMM flow ## Documentation (2 new files) ### Quick Spec Flow Guide (docs/quick-spec-flow.md) - Comprehensive 595-line guide for Level 0-1 rapid development - Complete user journey examples (bug fix, small feature) - Context discovery explanation (stack, brownfield, conventions) - Auto-validation details and benefits - Integration with Phase 4 workflows - Comparison: Quick Spec vs Full BMM - Real-world examples and best practices ### Scale Adaptive System (docs/scale-adaptive-system.md) - Complete 950-line technical guide to BMad Method's 5-level system - Key terminology: Analysis, Tech-Spec, Epic-Tech-Spec, Architecture - Level 0-4 workflows, planning docs, and progression - Brownfield emphasis: document-project required first - Tech-spec (upfront, Level 0-1) vs epic-tech-spec (during implementation, Level 2-4) - Architecture document replaces tech-spec at Level 2+ (scales with complexity) - Retrospectives after each epic in multi-epic projects - Workflow path configuration reference ### README Updates - Add Quick Spec Flow announcement with benefits - Link to Scale Adaptive System documentation - Clarify when to use Quick Spec Flow vs Full BMM ## Key Features ### Context-Aware Intelligence - Auto-detects project stack from package.json, requirements.txt, etc. - Analyzes brownfield codebases using document-project output - Detects code conventions and confirms with user before proceeding - Uses WebSearch for up-to-date framework info and starter templates ### Brownfield Respect - Detects existing patterns (code style, test framework, naming conventions) - Asks user for confirmation before applying conventions - Adapts to existing code vs forcing changes - References document-project analysis for comprehensive context ### Auto-Validation - Always runs (not optional) - Validates context gathering, definitiveness, brownfield integration - Scores tech-spec quality and implementation readiness - Validates story sequence for Level 1 (no forward dependencies) ### Living Document Approach - Write to tech-spec continuously during discovery - Progressive refinement vs batch generation - Template variables populated via template-output tags in real-time ## Breaking Changes None - all changes are additive and backward compatible. ## Impact This transformation enables: - Bug fixes and small features implemented in minutes vs hours - Automatic stack detection and brownfield analysis - Respect for existing conventions and patterns - Current best practices via WebSearch integration - Comprehensive context that can replace story-context for simple efforts - Seamless integration with Phase 4 implementation workflows Quick Spec Flow now provides a **true fast path from idea to implementation** for Level 0-1 projects while maintaining quality through auto-validation and comprehensive context gathering.
2025-12-29 16:14:59 +00:00 · 2025-11-02 08:17:23 -06:00
parent 3d4ea5ffd2
commit 8a00f8ad70
14 changed files with 3342 additions and 222 deletions
--- a/docs/quick-spec-flow.md
+++ b/docs/quick-spec-flow.md
@@ -0,0 +1,645 @@
+# 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._
--- a/docs/scale-adaptive-system.md
+++ b/docs/scale-adaptive-system.md