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-17 09:45:25 +00:00 · 2025-11-02 08:17:23 -06:00 · 2025-11-02 08:17:23 -06:00 · 8a00f8ad70
commit 8a00f8ad70
parent 3d4ea5ffd2
14 changed files with 3342 additions and 222 deletions
--- a/README.md
+++ b/README.md
@ -19,22 +19,59 @@ BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies

 ## Table of Contents

- [Quick Start](#quick-start)
- [What is BMad-CORE?](#what-is-bmad-core)
- [Modules](#modules)
-  - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development)
-  - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions)
-  - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity)
- [Installation](#installation)
- [Key Features](#key-features)
- [Documentation](#documentation)
- [Community & Support](#community--support)
+- [BMad CORE + BMad Method](#bmad-core--bmad-method)
+  - [Universal Human-AI Collaboration Platform](#universal-human-ai-collaboration-platform)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Start](#quick-start)
+    - [⚡ NEW: Quick Spec Flow for Rapid Development](#-new-quick-spec-flow-for-rapid-development)
+  - [What is BMad-CORE?](#what-is-bmad-core)
+    - [v6 Core Enhancements](#v6-core-enhancements)
+    - [C.O.R.E. Philosophy](#core-philosophy)
+  - [Modules](#modules)
+    - [BMad Method (BMM) - Agile AI Development](#bmad-method-bmm---agile-ai-development)
+      - [v6 Highlights](#v6-highlights)
+    - [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions)
+    - [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
+  - [Installation](#installation)
+    - [Project Structure](#project-structure)
+    - [Getting Started](#getting-started)
+  - [Key Features](#key-features)
+    - [🎨 Update-Safe Customization](#-update-safe-customization)
+    - [🚀 Intelligent Installation](#-intelligent-installation)
+    - [📁 Unified Architecture](#-unified-architecture)
+    - [📄 Document Sharding](#-document-sharding)
+  - [Documentation](#documentation)
+  - [Community \& Support](#community--support)
+  - [Contributing](#contributing)
+  - [License](#license)

 ## Quick Start

 - **New to v6?** [→ BMad Method V6 Quick Start Guide](./docs/BMad-Method-V6-Quick-Start.md)
+- **Need a quick bug fix or small feature?** ⚡ [→ BMad Quick Spec Flow](./docs/quick-spec-flow.md) - Go from idea to implementation in minutes!
 - **Upgrading?** [→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)

+### ⚡ NEW: Quick Spec Flow for Rapid Development
+
+**Perfect for:** Bug fixes, small features, rapid prototyping
+
+Skip the full planning docs and go **straight to implementation** with auto-detected stack, brownfield analysis, and context-rich technical specs. Ideal for Level 0-1 projects that don't need Product Briefs or PRDs.
+
+📚 **Learn about project levels:** [BMad Method Scale Adaptive System](./docs/scale-adaptive-system.md) - Automatically adapts from Level 0 (bug fixes) to Level 4 (enterprise systems)
+
+**When to use Quick Spec Flow:**
+
+- 🐛 **Bug fixes** - Single file changes, isolated improvements
+- ✨ **Small features** - 2-3 related changes, coherent functionality
+- 🚀 **Rapid prototyping** - Quick experiments and validation
+- 🔧 **Brownfield enhancements** - Adding to existing codebases
+
+**Not sure which flow to use?** Run `workflow-init` - it will analyze your project goal and recommend either Quick Spec Flow (Level 0-1) or Full BMM Flow (Level 2-4).
+
+[**→ Read the complete Quick Spec Flow guide**](./docs/quick-spec-flow.md)
+
+---
+
 ## What is BMad-CORE?

 Foundation framework powering all BMad modules:
--- 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
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
@ -1,11 +1,13 @@
 # Tech-Spec Workflow Validation Checklist

-**Purpose**: Validate tech-spec workflow outputs are definitive, complete, and implementation-ready.
+**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.

 **Scope**: Levels 0-1 software projects

 **Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)

+**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
+
 ---

 ## 1. Output Files Exist
@ -14,38 +16,107 @@
 - [ ] Story file(s) created in dev_story_location
  - Level 0: 1 story file (story-{slug}.md)
  - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
- [ ] bmm-workflow-status.md updated to Phase 4
- [ ] No unfilled {{template_variables}}
+- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
+- [ ] No unfilled {{template_variables}} in any files

 ---

-## 2. Tech-Spec Definitiveness (CRITICAL)
+## 2. Context Gathering (NEW - CRITICAL)
+
+### Document Discovery
+
+- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist)
+- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map)
+- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized
+- [ ] **Context summary**: loaded_documents_summary lists all sources used
+
+### Project Stack Detection
+
+- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed
+- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2")
+- [ ] **Dependencies extracted**: All production dependencies with specific versions
+- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions
+- [ ] **Scripts documented**: Available npm/pip/etc scripts identified
+- [ ] **Stack summary**: project_stack_summary is complete and accurate
+
+### Brownfield Analysis (if applicable)
+
+- [ ] **Directory structure**: Main code directories identified and documented
+- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.)
+- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.)
+- [ ] **Key modules**: Important existing modules/services identified
+- [ ] **Testing patterns**: Test framework and patterns documented
+- [ ] **Structure summary**: existing_structure_summary is comprehensive
+
+---
+
+## 3. Tech-Spec Definitiveness (CRITICAL)

 ### No Ambiguity Allowed

 - [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include"
 - [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions
-  - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2"
+  - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)"
  - ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston"
 - [ ] **Definitive decisions**: Every technical choice is final, not a proposal
+- [ ] **Stack-aligned**: Decisions reference detected project stack

 ### Implementation Clarity

- [ ] Source tree shows EXACT file paths (not "somewhere in src/")
- [ ] Each file marked as create/modify/delete
- [ ] Technical approach describes SPECIFIC implementation
- [ ] Implementation stack has complete toolchain with versions
+- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
+  - ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
+  - ❌ BAD: "Update some files in the services folder"
+- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack
+- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable)
+- [ ] **Integration points**: Specific modules, APIs, services identified

 ---

-## 3. Story Quality
+## 4. Context-Rich Content (NEW)
+
+### Context Section
+
+- [ ] **Available Documents**: Lists all loaded documents
+- [ ] **Project Stack**: Complete framework and dependency information
+- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation
+
+### The Change Section
+
+- [ ] **Problem Statement**: Clear, specific problem definition
+- [ ] **Proposed Solution**: Concrete solution approach
+- [ ] **Scope In/Out**: Clear boundaries defined
+
+### Development Context Section
+
+- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield)
+- [ ] **Framework Dependencies**: Complete list with exact versions from project
+- [ ] **Internal Dependencies**: Internal modules listed
+- [ ] **Configuration Changes**: Specific config file updates identified
+
+### Developer Resources Section
+
+- [ ] **File Paths Reference**: Complete list of all files involved
+- [ ] **Key Code Locations**: Functions, classes, modules with file:line references
+- [ ] **Testing Locations**: Specific test directories and patterns
+- [ ] **Documentation Updates**: Docs that need updating identified
+
+---
+
+## 5. Story Quality

 ### Story Format

 - [ ] All stories use "As a [role], I want [capability], so that [benefit]" format
 - [ ] Each story has numbered acceptance criteria
 - [ ] Tasks reference AC numbers: (AC: #1), (AC: #2)
- [ ] Dev Notes section links back to tech-spec.md
+- [ ] Dev Notes section links to tech-spec.md
+
+### Story Context Integration (NEW)
+
+- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context
+- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.)
+- [ ] **Test Results section**: Placeholder ready for dev execution
+- [ ] **Review Notes section**: Placeholder ready for code review

 ### Story Sequencing (If Level 1)

@ -56,38 +127,66 @@

 ### Coverage

- [ ] Story acceptance criteria derived from tech-spec testing section
+- [ ] Story acceptance criteria derived from tech-spec
 - [ ] Story tasks map to tech-spec implementation guide
 - [ ] Files in stories match tech-spec source tree
+- [ ] Key code references align with tech-spec Developer Resources

 ---

-## 4. Workflow Status Integration
+## 6. Epic Quality (Level 1 Only)

- [ ] bmm-workflow-status.md shows current_phase = "4-Implementation"
- [ ] Phase 2 ("2-Plan") marked complete
- [ ] First story in TODO section, others in BACKLOG (if Level 1)
- [ ] Next action clear (review story, run story-ready)
+- [ ] **Epic title**: User-focused outcome (not implementation detail)
+- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
+- [ ] **Epic goal**: Clear purpose and value statement
+- [ ] **Epic scope**: Boundaries clearly defined
+- [ ] **Success criteria**: Measurable outcomes
+- [ ] **Story map**: Visual representation of epic → stories
+- [ ] **Implementation sequence**: Logical story ordering with dependencies
+- [ ] **Tech-spec reference**: Links back to tech-spec.md

 ---

-## 5. Readiness for Implementation
+## 7. Workflow Status Integration

- [ ] Developer can start coding from tech-spec alone
- [ ] All technical questions answered definitively
- [ ] Testing approach clear and verifiable
- [ ] Deployment strategy documented
+- [ ] bmm-workflow-status.yaml updated (if exists)
+- [ ] Current phase reflects tech-spec completion
+- [ ] Progress percentage updated appropriately
+- [ ] Next workflow clearly identified

 ---

-## 6. Critical Failures (Auto-Fail)
+## 8. Implementation Readiness (NEW - ENHANCED)
+
+### Can Developer Start Immediately?
+
+- [ ] **All context available**: Brownfield analysis + stack details + existing patterns
+- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns
+- [ ] **Specific file paths**: Developer knows exactly which files to create/modify
+- [ ] **Code references**: Can find similar code to reference (brownfield)
+- [ ] **Testing clear**: Knows what to test and how
+- [ ] **Deployment documented**: Knows how to deploy and rollback
+
+### Tech-Spec Replaces Story-Context?
+
+- [ ] **Comprehensive enough**: Contains all info typically in story-context XML
+- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance
+- [ ] **Framework specifics**: Exact versions and usage patterns
+- [ ] **Pattern guidance**: Shows examples of existing patterns to follow
+
+---
+
+## 9. Critical Failures (Auto-Fail)

 - [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices)
 - [ ] ❌ **Missing versions** (framework/library without specific version)
- [ ] ❌ **Stories don't match template** (incompatible with story-context/dev-story workflows)
- [ ] ❌ **Missing tech-spec sections** (required section missing from tech-spec.md)
+- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.)
+- [ ] ❌ **Stack mismatch** (decisions don't align with detected project stack)
+- [ ] ❌ **Stories don't match template** (missing Dev Agent Record sections)
+- [ ] ❌ **Missing tech-spec sections** (required section missing from enhanced template)
 - [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
- [ ] ❌ **Vague source tree** (file changes not specific)
+- [ ] ❌ **Vague source tree** (file changes not specific with actions)
+- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used)

 ---

@ -95,13 +194,21 @@

 **Document any findings:**

- Definitiveness score: [All definitive / Some ambiguity / Significant ambiguity]
- Strengths:
- Issues to address:
- Recommended actions:
+- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
+- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
+- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
+- **Stack Alignment**: [Perfect / Good / Partial / None]
+
+## **Strengths:**
+
+## **Issues to address:**
+
+## **Recommended actions:**

 **Ready for implementation?** [Yes / No - explain]

+**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A]
+
 ---

-_Adapt based on Level 0 vs Level 1. Focus on definitiveness above all else._
+_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md
@ -1,11 +1,58 @@
 # {{project_name}} - Epic Breakdown

-## Epic Overview
-
-{{epic_overview}}
+**Date:** {{date}}
+**Project Level:** {{project_level}}

 ---

-## Epic Details
+## Epic: {{epic_title}}

-{{epic_details}}
+**Slug:** {{epic_slug}}
+
+### Goal
+
+{{epic_goal}}
+
+### Scope
+
+{{epic_scope}}
+
+### Success Criteria
+
+{{epic_success_criteria}}
+
+### Dependencies
+
+{{epic_dependencies}}
+
+---
+
+## Story Map
+
+{{story_map}}
+
+---
+
+## Story Summaries
+
+{{story_summaries}}
+
+---
+
+## Implementation Timeline
+
+**Total Story Points:** {{total_points}}
+
+**Estimated Timeline:** {{estimated_timeline}}
+
+---
+
+## Implementation Sequence
+
+{{implementation_sequence}}
+
+---
+
+## Tech-Spec Reference
+
+See [tech-spec.md](../tech-spec.md) for complete technical implementation details.
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md
@ -10,12 +10,23 @@
 <step n="1" goal="Load tech spec and extract the change">

 <action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
-<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
 <action>Extract dev_story_location from config (where stories are stored)</action>
-<action>Extract the problem statement from "Technical Approach" section</action>
-<action>Extract the scope from "Source Tree Structure" section</action>
-<action>Extract time estimate from "Implementation Guide" or technical details</action>
-<action>Extract acceptance criteria from "Testing Approach" section</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Problem statement from "The Change → Problem Statement" section
+- Solution overview from "The Change → Proposed Solution" section
+- Scope from "The Change → Scope" section
+- Source tree from "Implementation Details → Source Tree Changes" section
+- Time estimate from "Implementation Guide → Implementation Steps" section
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
+- Framework dependencies from "Development Context → Framework/Libraries" section
+- Existing code references from "Development Context → Relevant Existing Code" section
+- File paths from "Developer Resources → File Paths Reference" section
+- Key code locations from "Developer Resources → Key Code Locations" section
+- Testing locations from "Developer Resources → Testing Locations" section
+  </action>

 </step>

@ -76,9 +87,18 @@
 **Dev Notes:**

 - Extract technical constraints from tech-spec
- Include file paths from "Source Tree Structure"
+- Include file paths from "Developer Resources → File Paths Reference"
+- Include existing code references from "Development Context → Relevant Existing Code"
 - Reference architecture patterns if applicable
 - Cite tech-spec sections for implementation details
+- Note dependencies (internal and external)
+
+**NEW: Comprehensive Context**
+
+Since tech-spec is now context-rich, populate all new template fields:
+
+- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
  </guidelines>

 <action>Initialize story file using user_story_template</action>
@ -94,6 +114,8 @@
 <template-output file="{story_path}">test_locations</template-output>
 <template-output file="{story_path}">story_points</template-output>
 <template-output file="{story_path}">time_estimate</template-output>
+<template-output file="{story_path}">dependencies</template-output>
+<template-output file="{story_path}">existing_code_references</template-output>
 <template-output file="{story_path}">architecture_references</template-output>

 </step>
@ -135,29 +157,40 @@

 **Story Location:** `{story_path}`

-**Next Steps (choose one path):**
+**Next Steps:**

-**Option A - Full Context (Recommended for complex changes):**
+**🎯 RECOMMENDED - Direct to Development (Level 0):**

-1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
-2. Run story-context workflow
-3. Then load DEV agent and run dev-story workflow
+Since the tech-spec is now CONTEXT-RICH with:

-**Option B - Direct to Dev (For simple, well-understood changes):**
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+
+**You can skip story-context and go straight to dev!**

 1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
-2. Run dev-story workflow (will auto-discover story)
-3. Begin implementation
+2. Run `dev-story` workflow
+3. Begin implementation immediately
+
+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex scenarios:
+
+1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow (generates additional XML context)
+3. Then load DEV agent and run `dev-story` workflow

 **Progress Tracking:**

- All decisions logged in: `bmm-workflow-status.md`
+- All decisions logged in: `bmm-workflow-status.yaml`
 - Next action clearly identified

 <ask>Ready to proceed? Choose your path:

-1. Generate story context (Option A - recommended)
-2. Go directly to dev-story implementation (Option B - faster)
+1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context (for complex edge cases)
 3. Exit for now

 Select option (1-3):</ask>
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md
@ -11,12 +11,23 @@
 <step n="1" goal="Load tech spec and extract implementation tasks">

 <action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
-<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
 <action>Extract dev_story_location from config (where stories are stored)</action>
-<action>Identify all implementation tasks from the "Implementation Guide" section</action>
-<action>Identify the overall feature goal from "Technical Approach" section</action>
-<action>Extract time estimates for each implementation phase</action>
-<action>Identify any dependencies between implementation tasks</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
+- Implementation tasks from "Implementation Guide → Implementation Steps"
+- Time estimates from "Implementation Guide → Implementation Steps"
+- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
+- Source tree from "Implementation Details → Source Tree Changes"
+- Framework dependencies from "Development Context → Framework/Libraries"
+- Existing code references from "Development Context → Relevant Existing Code"
+- File paths from "Developer Resources → File Paths Reference"
+- Key code locations from "Developer Resources → Key Code Locations"
+- Testing locations from "Developer Resources → Testing Locations"
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
+  </action>

 </step>

@ -60,6 +71,9 @@

 <action>Initialize epics.md summary document using epics_template</action>

+<action>Also capture project_level for the epic template</action>
+
+<template-output file="{output_folder}/epics.md">project_level</template-output>
 <template-output file="{output_folder}/epics.md">epic_title</template-output>
 <template-output file="{output_folder}/epics.md">epic_slug</template-output>
 <template-output file="{output_folder}/epics.md">epic_goal</template-output>
@ -113,6 +127,25 @@
 - Include technical acceptance criteria from tech spec tasks
 - Link back to tech spec sections for implementation details

+**CRITICAL: Acceptance Criteria Must Be:**
+
+1. **Numbered** - AC #1, AC #2, AC #3, etc.
+2. **Specific** - No vague statements like "works well" or "is fast"
+3. **Testable** - Can be verified objectively
+4. **Complete** - Covers all success conditions
+5. **Independent** - Each AC tests one thing
+6. **Format**: Use Given/When/Then when applicable
+
+**Good AC Examples:**
+✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
+✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
+✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
+
+**Bad AC Examples:**
+❌ "User can create account" (too vague)
+❌ "System performs well" (not measurable)
+❌ "Works correctly" (not specific)
+
 **Story Point Estimation:**

 - 1 point = < 1 day (2-4 hours)
@ -134,7 +167,14 @@
 - Acceptance Criteria: Numbered list from tech spec
 - Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
 - Dev Notes: Technical summary, project structure notes, references
- Dev Agent Record: Empty sections for context workflow to populate
+- Dev Agent Record: Empty sections (tech-spec provides context)
+
+**NEW: Comprehensive Context Fields**
+
+Since tech-spec is context-rich, populate ALL template fields:
+
+- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
  </guidelines>

 <for-each story="1 to story_count">
@ -149,10 +189,12 @@
    - acceptance_criteria: Specific, measurable criteria from tech spec
    - tasks_subtasks: Implementation tasks with AC references
    - technical_summary: High-level approach, key decisions
-    - files_to_modify: List of files that will change
-    - test_locations: Where tests will be added
+    - files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
+    - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
    - story_points: Estimated effort (1/2/3/5)
    - time_estimate: Days/hours estimate
+    - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
+    - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
    - architecture_references: Links to tech-spec.md sections
  </template-output>
 </for-each>
@ -161,12 +203,35 @@

 </step>

-<step n="5" goal="Create story map and implementation sequence">
+<step n="5" goal="Create story map and implementation sequence with dependency validation">

-<action>Generate visual story map showing epic → stories hierarchy</action>
+<critical>Stories MUST be ordered so earlier stories don't depend on later ones</critical>
+<critical>Each story must have CLEAR, TESTABLE acceptance criteria</critical>
+
+<action>Analyze dependencies between stories:
+
+**Dependency Rules:**
+
+1. Infrastructure/setup → Feature implementation → Testing/polish
+2. Database changes → API changes → UI changes
+3. Backend services → Frontend components
+4. Core functionality → Enhancement features
+5. No story can depend on a later story!
+
+**Validate Story Sequence:**
+For each story N, check:
+
+- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
+- Does it only use things from Story 1...N-1? ✅ VALID
+- Can it be implemented independently or using only prior stories? ✅ VALID
+
+If invalid dependencies found, REORDER stories!
+</action>
+
+<action>Generate visual story map showing epic → stories hierarchy with dependencies</action>
 <action>Calculate total story points across all stories</action>
 <action>Estimate timeline based on total points (1-2 points per day typical)</action>
-<action>Define implementation sequence considering dependencies</action>
+<action>Define implementation sequence with explicit dependency notes</action>

 <example>
 ## Story Map
@ -174,7 +239,10 @@
 ```
 Epic: Icon Reliability
 ├── Story 1: Build Icon Infrastructure (3 points)
+│   Dependencies: None (foundational work)
+│
 └── Story 2: Test and Deploy Icons (2 points)
+    Dependencies: Story 1 (requires infrastructure)
 ```

 **Total Story Points:** 5
@ -183,8 +251,15 @@ Epic: Icon Reliability
 ## Implementation Sequence

 1. **Story 1** → Build icon infrastructure (setup, download, configure)
+   - Dependencies: None
+   - Deliverable: Icon files downloaded, organized, accessible
+
 2. **Story 2** → Test and deploy (depends on Story 1)
-   </example>
+   - Dependencies: Story 1 must be complete
+   - Deliverable: Icons verified, tested, deployed to production
+
+**Dependency Validation:** ✅ Valid sequence - no forward dependencies
+</example>

 <template-output file="{output_folder}/epics.md">story_summaries</template-output>
 <template-output file="{output_folder}/epics.md">story_map</template-output>
@ -214,12 +289,90 @@ Epic: Icon Reliability

 </step>

-<step n="7" goal="Finalize and provide user guidance">
+<step n="7" goal="Auto-validate story quality and sequence">

-<action>Confirm all stories map to tech spec implementation tasks</action>
+<critical>Auto-run validation - NOT optional!</critical>
+
+<action>Running automatic story validation...</action>
+
+<action>**Validate Story Sequence (CRITICAL):**
+
+For each story, check:
+
+1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
+2. Are dependencies clearly documented? ✅ PASS
+3. Can stories be implemented in order 1→2→3? ✅ PASS
+
+If sequence validation FAILS:
+
+- Identify the problem dependencies
+- Propose new ordering
+- Ask user to confirm reordering
+  </action>
+
+<action>**Validate Acceptance Criteria Quality:**
+
+For each story's AC, check:
+
+1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
+2. Is it specific and testable? ✅ Required
+3. Does it use Given/When/Then or equivalent? ✅ Recommended
+4. Are all success conditions covered? ✅ Required
+
+Count vague AC (contains "works", "good", "fast", "well"):
+
+- 0 vague AC: ✅ EXCELLENT
+- 1-2 vague AC: ⚠️ WARNING - Should improve
+- 3+ vague AC: ❌ FAIL - Must improve
+  </action>
+
+<action>**Validate Story Completeness:**
+
+1. Do all stories map to tech spec tasks? ✅ Required
+2. Do story points align with tech spec estimates? ✅ Recommended
+3. Are dependencies clearly noted? ✅ Required
+4. Does each story have testable AC? ✅ Required
+   </action>
+
+<action>Generate validation report</action>
+
+<check if="sequence validation fails OR AC quality fails">
+  <output>❌ **Story Validation Failed:**
+
+{{issues_found}}
+
+**Recommended Fixes:**
+{{recommended_fixes}}
+
+Shall I fix these issues? (yes/no)</output>
+
+<ask>Apply fixes? (yes/no)</ask>
+
+  <check if="yes">
+    <action>Apply fixes (reorder stories, rewrite vague AC, add missing details)</action>
+    <action>Re-validate</action>
+    <output>✅ Validation passed after fixes!</output>
+  </check>
+</check>
+
+<check if="validation passes">
+  <output>✅ **Story Validation Passed!**
+
+**Sequence:** ✅ Valid (no forward dependencies)
+**AC Quality:** ✅ All specific and testable
+**Completeness:** ✅ All tech spec tasks covered
+**Dependencies:** ✅ Clearly documented
+
+Stories are implementation-ready!</output>
+</check>
+
+</step>
+
+<step n="8" goal="Finalize and provide user guidance">
+
+<action>Confirm all validation passed</action>
 <action>Verify total story points align with tech spec time estimates</action>
-<action>Verify stories are properly sequenced with dependencies noted</action>
-<action>Confirm all stories have measurable acceptance criteria</action>
+<action>Confirm epic and stories are complete</action>

 **Level 1 Planning Complete!**

@ -242,33 +395,53 @@ Epic: Icon Reliability

 **Next Steps - Iterative Implementation:**

+**🎯 RECOMMENDED - Direct to Development (Level 1):**
+
+Since the tech-spec is now CONTEXT-RICH with:
+
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+- ✅ Dependencies clearly mapped
+
+**You can skip story-context for most Level 1 stories!**
+
 **1. Start with Story 1:**
-a. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
-b. Run story-context workflow (select story-{epic_slug}-1.md)
-c. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
-d. Run dev-story workflow to implement story 1
+a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
+b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
+c. Tech-spec provides all context needed
+d. Implement story 1

 **2. After Story 1 Complete:**

- Repeat process for story-{epic_slug}-2.md
- Story context will auto-reference completed story 1
+- Repeat for story-{epic_slug}-2.md
+- Reference completed story 1 in your work

 **3. After Story 2 Complete:**
 {{#if story_3}}

- Repeat process for story-{epic_slug}-3.md
+- Repeat for story-{epic_slug}-3.md
  {{/if}}
 - Level 1 feature complete!

+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex multi-story dependencies:
+
+1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow for complex stories
+3. Then load DEV agent and run `dev-story`
+
 **Progress Tracking:**

- All decisions logged in: `bmm-workflow-status.md`
+- All decisions logged in: `bmm-workflow-status.yaml`
 - Next action clearly identified

 <ask>Ready to proceed? Choose your path:

-1. Generate context for story 1 (recommended - run story-context)
-2. Go directly to dev-story for story 1 (faster)
+1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context first (for complex dependencies)
 3. Exit for now

 Select option (1-3):</ask>
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md
@ -3,21 +3,97 @@
 **Author:** {{user_name}}
 **Date:** {{date}}
 **Project Level:** {{project_level}}
-**Project Type:** {{project_type}}
+**Change Type:** {{change_type}}
 **Development Context:** {{development_context}}

 ---

-## Source Tree Structure
+## Context

-{{source_tree}}
+### Available Documents
+
+{{loaded_documents_summary}}
+
+### Project Stack
+
+{{project_stack_summary}}
+
+### Existing Codebase Structure
+
+{{existing_structure_summary}}

 ---

-## Technical Approach
+## The Change
+
+### Problem Statement
+
+{{problem_statement}}
+
+### Proposed Solution
+
+{{solution_overview}}
+
+### Scope
+
+**In Scope:**
+
+{{scope_in}}
+
+**Out of Scope:**
+
+{{scope_out}}
+
+---
+
+## Implementation Details
+
+### Source Tree Changes
+
+{{source_tree_changes}}
+
+### Technical Approach

 {{technical_approach}}

+### Existing Patterns to Follow
+
+{{existing_patterns}}
+
+### Integration Points
+
+{{integration_points}}
+
+---
+
+## Development Context
+
+### Relevant Existing Code
+
+{{existing_code_references}}
+
+### Dependencies
+
+**Framework/Libraries:**
+
+{{framework_dependencies}}
+
+**Internal Modules:**
+
+{{internal_dependencies}}
+
+### Configuration Changes
+
+{{configuration_changes}}
+
+### Existing Conventions (Brownfield)
+
+{{existing_conventions}}
+
+### Test Framework & Standards
+
+{{test_framework_info}}
+
 ---

 ## Implementation Stack
@ -40,7 +116,47 @@

 ## Implementation Guide

-{{implementation_guide}}
+### Setup Steps
+
+{{setup_steps}}
+
+### Implementation Steps
+
+{{implementation_steps}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+### Acceptance Criteria
+
+{{acceptance_criteria}}
+
+---
+
+## Developer Resources
+
+### File Paths Reference
+
+{{file_paths_complete}}
+
+### Key Code Locations
+
+{{key_code_locations}}
+
+### Testing Locations
+
+{{testing_locations}}
+
+### Documentation to Update
+
+{{documentation_updates}}
+
+---
+
+## UX/UI Considerations
+
+{{ux_ui_considerations}}

 ---

@ -52,4 +168,14 @@

 ## Deployment Strategy

-{{deployment_strategy}}
+### Deployment Steps
+
+{{deployment_steps}}
+
+### Rollback Plan
+
+{{rollback_plan}}
+
+### Monitoring
+
+{{monitoring_approach}}
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md
@ -22,22 +22,43 @@ so that {{benefit}}.

 {{technical_summary}}

+### Tech-Spec Reference
+
+**Full details:** See [tech-spec.md](../tech-spec.md)
+
+The tech-spec contains comprehensive context including:
+
+- Brownfield codebase analysis (if applicable)
+- Framework and library details with versions
+- Existing patterns to follow
+- Integration points and dependencies
+- Complete implementation guidance
+
 ### Project Structure Notes

- Files to modify: {{files_to_modify}}
- Expected test locations: {{test_locations}}
- Estimated effort: {{story_points}} story points ({{time_estimate}})
+- **Files to modify:** {{files_to_modify}}
+- **Expected test locations:** {{test_locations}}
+- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
+- **Dependencies:** {{dependencies}}
+
+### Key Code References
+
+{{existing_code_references}}

 ### References

- **Tech Spec:** See tech-spec.md for detailed implementation
+- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
 - **Architecture:** {{architecture_references}}

+---
+
 ## Dev Agent Record

 ### Context Reference

-<!-- Path(s) to story context XML will be added here by context workflow -->
+**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
+
+<!-- Additional context XML paths will be added here if story-context workflow is run -->

 ### Agent Model Used

@ -54,3 +75,13 @@ so that {{benefit}}.
 ### File List

 <!-- Will be populated during dev-story execution -->
+
+### Test Results
+
+<!-- Will be populated during dev-story execution -->
+
+---
+
+## Review Notes
+
+<!-- Will be populated during code review -->
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
@ -13,6 +13,13 @@ document_output_language: "{config_source}:document_output_language"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated

+# Runtime variables (captured during workflow execution)
+project_level: runtime-captured
+project_type: runtime-captured
+development_context: runtime-captured
+change_type: runtime-captured
+field_type: runtime-captured
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
 instructions: "{installed_path}/instructions.md"
--- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
@ -52,6 +52,9 @@ input_file_patterns:
    whole: "{output_folder}/*prd*.md"
    sharded: "{output_folder}/*prd*/index.md"

+  tech_spec:
+    whole: "{output_folder}/tech-spec.md"
+
  architecture:
    whole: "{output_folder}/*architecture*.md"
    sharded: "{output_folder}/*architecture*/index.md"
--- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md
@ -120,7 +120,8 @@ All stories are either still in backlog or already marked ready/in-progress/done

  <step n="2" goal="Collect relevant documentation">
    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
-    <action>Prefer authoritative sources: PRD, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
+    <action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
+    <action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
    <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
    <template-output file="{default_output_file}">
      Add artifacts.docs entries with {path, title, section, snippet}:
--- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
@ -31,6 +31,9 @@ input_file_patterns:
    whole: "{output_folder}/*prd*.md"
    sharded: "{output_folder}/*prd*/index.md"

+  tech_spec:
+    whole: "{output_folder}/tech-spec.md"
+
  architecture:
    whole: "{output_folder}/*architecture*.md"
    sharded: "{output_folder}/*architecture*/index.md"