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.

README.md

@@ -19,22 +19,59 @@ BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies
 
 ## Table of Contents
 
-- [Quick Start](#quick-start)
+- [BMad CORE + BMad Method](#bmad-core--bmad-method)
-- [What is BMad-CORE?](#what-is-bmad-core)
+  - [Universal Human-AI Collaboration Platform](#universal-human-ai-collaboration-platform)
-- [Modules](#modules)
+  - [Table of Contents](#table-of-contents)
-  - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development)
+  - [Quick Start](#quick-start)
-  - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions)
+    - [⚡ NEW: Quick Spec Flow for Rapid Development](#-new-quick-spec-flow-for-rapid-development)
-  - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity)
+  - [What is BMad-CORE?](#what-is-bmad-core)
-- [Installation](#installation)
+    - [v6 Core Enhancements](#v6-core-enhancements)
-- [Key Features](#key-features)
+    - [C.O.R.E. Philosophy](#core-philosophy)
-- [Documentation](#documentation)
+  - [Modules](#modules)
-- [Community & Support](#community--support)
+    - [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:
@@ -180,6 +217,17 @@ This initializes the workflow system and helps choose your starting point.
 
 Single `bmad/` folder - clean, organized, maintainable.
 
+### 📄 Document Sharding
+
+Optional efficiency optimization for large projects:
+
+- **Automatic Support** - All workflows handle whole or sharded documents
+- **Selective Loading** - Phase 4 workflows load only needed sections (90%+ token savings)
+- **Easy Sharding** - Built-in tool splits documents by headings
+- **Smart Discovery** - Workflows auto-detect format
+
+**[→ Document Sharding Guide](./docs/document-sharding-guide.md)**
+
 ## Documentation
 
 - **[📚 Documentation Index](./docs/index.md)** - Complete documentation map

bmad/core/agents/bmad-master.md

@@ -14,17 +14,15 @@ You must fully embody this agent's persona and follow all activation instruction
       - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
       - VERIFY: If config not loaded, STOP and report error to user
       - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored</step>
-  <step n="3">Remember: user's name is {user_name}</step>
   <step n="4">Load into memory {project-root}/bmad/core/config.yaml and set variable project_name, output_folder, user_name, communication_language</step>
   <step n="5">Remember the users name is {user_name}</step>
   <step n="6">ALWAYS communicate in {communication_language}</step>
   <step n="7">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of
       ALL menu items from menu section</step>
-  <step n="8">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text</step>
+  <step n="8">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or trigger text or fuzzy matching from conversation</step>
-  <step n="9">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user
+  <step n="9">If you are unsure, verify the workflow the user wants to run - PLEASE PLEASE DO NOT JUST GUESS OR WORSE INVENT A WORKFLOW THAT YOU CANNOT REALLY FIND</step>
-      to clarify | No match → show "Not recognized"</step>
   <step n="10">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item
-      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+      (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handlers instructions</step>
 
   <menu-handlers>
     <handlers>

docs/conversion-report-shard-doc-2025-10-26.md

@@ -1,188 +0,0 @@
-# Legacy Task Conversion Report
-
-**Generated**: 2025-10-26
-**Converted By**: BMad Builder Agent
-**Conversion Type**: Legacy Task → v6 XML Task
-
----
-
-## Source Information
-
-- **Original Location**: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md
-- **Original Format**: Markdown task (v4/legacy format)
-- **Original Type**: Document sharding utility task
-
----
-
-## Target Information
-
-- **New Location**: `/Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml`
-- **New Format**: v6 XML task format
-- **Task ID**: `bmad/core/tasks/shard-doc`
-- **Task Name**: Shard Document
-
----
-
-## Conversion Summary
-
-### Components Converted
-
-✅ **Task Structure**: Converted from markdown to XML format
-✅ **Execution Flow**: 6 steps properly structured in `<flow>` section (simplified to tool-only)
-✅ **Critical Instructions**: Moved to `<llm critical="true">` section
-✅ **Validation Rules**: Extracted to `<validation>` section
-✅ **Halt Conditions**: Extracted to `<halt-conditions>` section
-✅ **Special Guidelines**: Moved to `<critical-context>` section
-✅ **Output Format**: Documented in `<output-format>` section
-✅ **Tool Information**: Preserved in `<tool-info>` section
-
-### Key Features Preserved
-
-- **Automated Tool**: Uses @kayvan/markdown-tree-parser exclusively
-- **Simplified Flow**: Removed all manual steps, tool handles everything
-- **Code Block Awareness**: Tool automatically handles ## inside code blocks
-- **Content Preservation**: Tool preserves all markdown formatting and special content
-- **Heading Adjustment**: Tool automatically reduces heading levels by one
-- **Index Generation**: Tool automatically creates index.md
-- **Validation Steps**: Verification of tool installation and output
-- **Error Handling**: Halt conditions for tool and file system issues
-
-### v6 Conventions Applied
-
-- ✅ Proper `<task>` wrapper with id and name attributes
-- ✅ `<llm critical="true">` section with mandatory instructions
-- ✅ `<flow>` section with numbered `<step>` elements
-- ✅ Used `<action>` tags for required actions
-- ✅ Used `<i>` tags for instruction lists and context
-- ✅ Conditional logic with `if` attributes on actions
-- ✅ Optional steps marked with `optional="true"`
-- ✅ Supporting sections for validation, halt conditions, output format
-- ✅ Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml)
-
----
-
-## Structural Comparison
-
-### Legacy Format (Markdown)
-
-```
-# Document Sharding Task
-## Primary Method: Automated Approach
-## Manual Method (Fallback)
-1. Identify target location
-2. Parse sections
-...
-## Critical Guidelines
-```
-
-### v6 Format (XML)
-
-```xml
-<task id="bmad/core/tasks/shard-doc" name="Shard Document">
-  <objective>...</objective>
-  <llm critical="true">...</llm>
-  <critical-context>...</critical-context>
-  <flow>
-    <step n="1" title="...">
-      <action>...</action>
-    </step>
-  </flow>
-  <halt-conditions>...</halt-conditions>
-  <validation>...</validation>
-</task>
-```
-
----
-
-## Validation Results
-
-### XML Structure
-
-- ✅ Valid XML syntax
-- ✅ Properly nested elements
-- ✅ All tags closed correctly
-- ✅ Attributes properly formatted
-
-### v6 Compliance
-
-- ✅ Matches v6 task conventions
-- ✅ Follows existing core task patterns
-- ✅ Uses standard v6 tag set
-- ✅ Proper section organization
-
-### Content Integrity
-
-- ✅ All original instructions preserved
-- ✅ No functionality lost in conversion
-- ✅ Critical warnings maintained
-- ✅ Tool information preserved
-- ✅ Validation logic intact
-
-### File System
-
-- ✅ Saved to correct location: `src/core/tasks/`
-- ✅ Proper filename: `shard-doc.xml`
-- ✅ Follows core task naming convention
-
----
-
-## Usage Notes
-
-### How to Invoke This Task
-
-From an agent or workflow, reference:
-
-```xml
-<invoke-task>{project-root}/bmad/core/tasks/shard-doc.xml</invoke-task>
-```
-
-Or from agent menu:
-
-```yaml
-menu:
-  - trigger: shard
-    description: 'Split large document into organized files'
-    exec: '{project-root}/bmad/core/tasks/shard-doc.xml'
-```
-
-### Task Capabilities
-
-1. **Automated Mode**: Uses @kayvan/markdown-tree-parser for fast sharding
-2. **Manual Mode**: Step-by-step guided process for controlled sharding
-3. **Safety Checks**: Validates code blocks aren't treated as headers
-4. **Content Preservation**: Maintains all formatting, code, tables, diagrams
-5. **Index Generation**: Creates navigable index.md automatically
-6. **Validation**: Verifies completeness and integrity
-
----
-
-## Post-Conversion Actions
-
-### Recommended Next Steps
-
-1. ✅ **Task Created**: File saved to core tasks directory
-2. **Test Task**: Invoke from an agent or workflow to verify functionality
-3. **Update Documentation**: Reference in core task documentation if needed
-4. **Integration**: Add to relevant agent menus if appropriate
-
-### No Manual Adjustments Required
-
-The conversion is complete and ready for use. All legacy functionality has been successfully migrated to v6 XML format.
-
----
-
-## Notes
-
-- Original legacy file can be archived or left as-is (located on GitHub)
-- This task is now a core BMAD task available to all modules
-- The task follows v6 conventions and is fully compatible with BMAD-CORE v6 alpha
-- **UPDATED 2025-10-26**: Manual fallback steps removed - task now exclusively uses @kayvan/markdown-tree-parser
-- Flow simplified from 8 steps to 6 steps (tool installation → execution → verification)
-- All manual parsing, file creation, and index generation logic removed (tool handles automatically)
-
----
-
-**Conversion Status**: ✅ COMPLETE (Updated)
-**Ready for Use**: YES
-**Manual Adjustments Needed**: NONE
-**Approach**: Automated tool only (no manual fallback)

docs/document-sharding-guide.md

@@ -0,0 +1,447 @@
+# Document Sharding Guide
+
+Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
+
+## Table of Contents
+
+- [What is Document Sharding?](#what-is-document-sharding)
+- [When to Use Sharding](#when-to-use-sharding)
+- [How Sharding Works](#how-sharding-works)
+- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
+- [Workflow Support](#workflow-support)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+
+## What is Document Sharding?
+
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
+
+### Architecture
+
+```
+Before Sharding:
+docs/
+└── PRD.md (large 50k token file)
+
+After Sharding:
+docs/
+└── prd/
+    ├── index.md                    # Table of contents with descriptions
+    ├── overview.md                 # Section 1
+    ├── user-requirements.md        # Section 2
+    ├── technical-requirements.md   # Section 3
+    └── ...                         # Additional sections
+```
+
+## When to Use Sharding
+
+### Ideal Candidates
+
+**Large Multi-Epic Projects:**
+
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
+
+**Token Thresholds:**
+
+- **Consider sharding**: Documents > 20k tokens
+- **Strongly recommended**: Documents > 40k tokens
+- **Critical for efficiency**: Documents > 60k tokens
+
+### When NOT to Shard
+
+**Small Projects:**
+
+- Single epic projects
+- Level 0-1 projects (tech-spec only)
+- Documents under 10k tokens
+- Quick prototypes
+
+**Frequently Updated Docs:**
+
+- Active work-in-progress documents
+- Documents updated daily
+- Documents where whole-file context is essential
+
+## How Sharding Works
+
+### Sharding Process
+
+1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
+2. **Section Extraction**: Tool splits by level 2 headings
+3. **File Creation**: Each section becomes a separate file
+4. **Index Generation**: `index.md` created with structure and descriptions
+
+### Workflow Discovery
+
+BMad workflows use a **dual discovery system**:
+
+1. **Try whole document first** - Look for `document-name.md`
+2. **Check for sharded version** - Look for `document-name/index.md`
+3. **Priority rule** - Whole document takes precedence if both exist
+
+### Loading Strategies
+
+**Full Load (Phase 1-3 workflows):**
+
+```
+If sharded:
+  - Read index.md
+  - Read ALL section files
+  - Treat as single combined document
+```
+
+**Selective Load (Phase 4 workflows):**
+
+```
+If sharded epics and working on Epic 3:
+  - Read epics/index.md
+  - Load ONLY epics/epic-3.md
+  - Skip all other epic files
+  - 90%+ token savings!
+```
+
+## Using the Shard-Doc Tool
+
+### CLI Command
+
+```bash
+# Activate bmad-master or analyst agent, then:
+/shard-doc
+```
+
+### Interactive Process
+
+```
+Agent: Which document would you like to shard?
+User: docs/PRD.md
+
+Agent: Default destination: docs/prd/
+       Accept default? [y/n]
+User: y
+
+Agent: Sharding PRD.md...
+       ✓ Created 12 section files
+       ✓ Generated index.md
+       ✓ Complete!
+```
+
+### What Gets Created
+
+**index.md structure:**
+
+```markdown
+# PRD - Index
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
+## Workflow Support
+
+### Universal Support
+
+**All BMM workflows support both formats:**
+
+- ✅ Whole documents
+- ✅ Sharded documents
+- ✅ Automatic detection
+- ✅ Transparent to user
+
+### Workflow-Specific Patterns
+
+#### Phase 1-3 (Full Load)
+
+Workflows load entire sharded documents:
+
+- `product-brief` - Research, brainstorming docs
+- `prd` - Product brief, research
+- `gdd` - Game brief, research
+- `create-ux-design` - PRD, brief, epics
+- `tech-spec` - Brief, research
+- `architecture` - PRD, epics, UX design
+- `solutioning-gate-check` - All planning docs
+
+#### Phase 4 (Selective Load)
+
+Workflows load only needed sections:
+
+**sprint-planning** (Full Load):
+
+- Needs ALL epics to build complete status
+
+**epic-tech-context, create-story, story-context, code-review** (Selective):
+
+```
+Working on Epic 3, Story 2:
+  ✓ Load epics/epic-3.md only
+  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
+
+Result: 90%+ token reduction for 10-epic projects!
+```
+
+### Input File Patterns
+
+Workflows use standardized patterns:
+
+```yaml
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+## Best Practices
+
+### Sharding Strategy
+
+**Do:**
+
+- ✅ Shard after planning phase complete
+- ✅ Keep level 2 headings well-organized
+- ✅ Use descriptive section names
+- ✅ Shard before Phase 4 implementation
+- ✅ Keep original file as backup initially
+
+**Don't:**
+
+- ❌ Shard work-in-progress documents
+- ❌ Shard small documents (<20k tokens)
+- ❌ Mix sharded and whole versions
+- ❌ Manually edit index.md structure
+
+### Naming Conventions
+
+**Good Section Names:**
+
+```markdown
+## Epic 1: User Authentication
+
+## Technical Requirements
+
+## System Architecture
+
+## UX Design Principles
+```
+
+**Poor Section Names:**
+
+```markdown
+## Section 1
+
+## Part A
+
+## Details
+
+## More Info
+```
+
+### File Management
+
+**When to Re-shard:**
+
+- Significant structural changes to document
+- Adding/removing major sections
+- After major refactoring
+
+**Updating Sharded Docs:**
+
+1. Edit individual section files directly
+2. OR edit original, delete sharded folder, re-shard
+3. Don't manually edit index.md
+
+## Examples
+
+### Example 1: Large PRD
+
+**Scenario:** 15-epic project, PRD is 45k tokens
+
+**Before Sharding:**
+
+```
+Every workflow loads entire 45k token PRD
+Epic-tech-context for Epic 3: 45k tokens
+Create-story for Epic 3: 45k tokens
+```
+
+**After Sharding:**
+
+```bash
+/shard-doc
+Source: docs/PRD.md
+Destination: docs/prd/
+
+Created:
+  prd/index.md
+  prd/overview.md (3k tokens)
+  prd/epic-1-auth.md (3k tokens)
+  prd/epic-2-dashboard.md (3k tokens)
+  prd/epic-3-reports.md (3k tokens)
+  ...15 epic files
+```
+
+**Result:**
+
+```
+Epic-tech-context for Epic 3: 3k tokens (93% reduction!)
+Create-story for Epic 3: 3k tokens (93% reduction!)
+```
+
+### Example 2: Sharding Epics File
+
+**Scenario:** 8 epics with detailed stories, 35k tokens total
+
+```bash
+/shard-doc
+Source: docs/bmm-epics.md
+Destination: docs/epics/
+
+Created:
+  epics/index.md
+  epics/epic-1.md
+  epics/epic-2.md
+  ...
+  epics/epic-8.md
+```
+
+**Efficiency Gain:**
+
+```
+Working on Epic 5 stories:
+  Old: Load all 8 epics (35k tokens)
+  New: Load epic-5.md only (4k tokens)
+  Savings: 88% reduction
+```
+
+### Example 3: Architecture Document
+
+**Scenario:** Multi-layer system architecture, 28k tokens
+
+```bash
+/shard-doc
+Source: docs/architecture.md
+Destination: docs/architecture/
+
+Created:
+  architecture/index.md
+  architecture/system-overview.md
+  architecture/frontend-architecture.md
+  architecture/backend-services.md
+  architecture/data-layer.md
+  architecture/infrastructure.md
+  architecture/security-architecture.md
+```
+
+**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
+
+## Custom Workflow Integration
+
+### For Workflow Builders
+
+When creating custom workflows that load large documents:
+
+**1. Add input_file_patterns to workflow.yaml:**
+
+```yaml
+input_file_patterns:
+  your_document:
+    whole: '{output_folder}/*your-doc*.md'
+    sharded: '{output_folder}/*your-doc*/index.md'
+```
+
+**2. Add discovery instructions to instructions.md:**
+
+```markdown
+## Document Discovery
+
+1. Search for whole document: _your-doc_.md
+2. Check for sharded version: _your-doc_/index.md
+3. If sharded: Read index + ALL sections (or specific sections if selective load)
+4. Priority: Whole document first
+```
+
+**3. Choose loading strategy:**
+
+- **Full Load**: Read all sections when sharded
+- **Selective Load**: Read only relevant sections (requires section identification logic)
+
+### Pattern Templates
+
+**Full Load Pattern:**
+
+```xml
+<action>Search for document: {output_folder}/*doc-name*.md</action>
+<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Pattern (with section ID):**
+
+```xml
+<action>Determine section needed (e.g., epic_num = 3)</action>
+<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file needed</action>
+<action if="sharded found">Skip all other section files</action>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Both whole and sharded exist:**
+
+- Workflows will use whole document (priority rule)
+- Delete or archive the one you don't want
+
+**Index.md out of sync:**
+
+- Delete sharded folder
+- Re-run shard-doc on original
+
+**Workflow can't find document:**
+
+- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
+- Verify index.md exists in sharded folder
+- Check output_folder path in config
+
+**Sections too granular:**
+
+- Combine sections in original document
+- Use fewer level 2 headings
+- Re-shard
+
+## Related Documentation
+
+- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
+- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Workflow overview
+- [Workflow Creation Guide](../src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns
+
+---
+
+**Document sharding is optional but powerful** - use it when efficiency matters for large projects!

docs/index.md

@@ -99,6 +99,10 @@ Instructions for loading agents and running workflows in your development enviro
 - [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
 - [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles
 
+### Optimization & Efficiency
+
+- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings in Phase 4 workflows
+
 ---
 
 ## 📊 Documentation Map

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

src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -1020,6 +1020,164 @@ _Generated on {{date}}_
 - **Unclosed check tags** - Always close `<check if="">...</check>` blocks
 - **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks
 
+## Document Sharding Support
+
+If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
+
+### What is Document Sharding?
+
+Document sharding splits large markdown files into smaller section-based files:
+
+- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Enables selective loading (90%+ token savings)
+- All BMM workflows support both whole and sharded documents
+
+### When to Add Sharding Support
+
+**Add sharding support if your workflow:**
+
+- Loads planning documents (PRD, epics, architecture, UX specs)
+- May be used in large multi-epic projects
+- Processes documents that could exceed 20k tokens
+- Would benefit from selective section loading
+
+**Skip sharding support if your workflow:**
+
+- Only generates small documents
+- Doesn't load external documents
+- Works with code files (not planning docs)
+
+### Implementation Pattern
+
+#### 1. Add input_file_patterns to workflow.yaml
+
+```yaml
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
+
+  architecture:
+    whole: '{output_folder}/*architecture*.md'
+    sharded: '{output_folder}/*architecture*/index.md'
+
+  document_project:
+    sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
+```
+
+#### 2. Add Discovery Instructions to instructions.md
+
+Place early in instructions (after critical declarations, before workflow steps):
+
+```markdown
+## 📚 Document Discovery
+
+This workflow requires: [list required documents]
+
+**Discovery Process** (execute for each document):
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index (or specific sections for selective load)
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations.
+```
+
+#### 3. Choose Loading Strategy
+
+**Full Load Strategy** (most workflows):
+
+```xml
+<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
+<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Strategy** (advanced - for phase 4 type workflows):
+
+```xml
+<action>Determine section needed (e.g., epic_num from story key)</action>
+<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
+<action if="sharded found">Skip all other section files (efficiency optimization)</action>
+<action if="whole document found">Load complete document and extract relevant section</action>
+```
+
+### Pattern Examples
+
+**Example 1: Simple Full Load**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  requirements:
+    whole: '{output_folder}/*requirements*.md'
+    sharded: '{output_folder}/*requirements*/index.md'
+```
+
+```markdown
+<!-- instructions.md -->
+
+## Document Discovery
+
+Load requirements document (whole or sharded).
+
+1. Try whole: _requirements_.md
+2. If not found, try sharded: _requirements_/index.md
+3. If sharded: Read index + ALL section files
+```
+
+**Example 2: Selective Load with Epic Number**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+```xml
+<!-- instructions.md step -->
+<step n="2" goal="Load Epic Content">
+  <action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
+  <action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
+  <action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
+  <action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
+</step>
+```
+
+### Testing Your Sharding Support
+
+1. **Test with whole document**: Verify workflow works with single `document.md`
+2. **Test with sharded document**: Create sharded version and verify discovery
+3. **Test with both present**: Ensure whole document takes priority
+4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
+
+### Complete Reference
+
+**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
+
+**BMM Examples**:
+
+- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
+- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
+
 ## Web Bundles
 
 Web bundles allow workflows to be deployed as self-contained packages for web environments.

src/modules/bmm/agents/game-designer.agent.yaml

@@ -30,11 +30,11 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml"
       description: Guide me through Game Brainstorming
 
-    - trigger: game-brief
+    - trigger: create-game-brief
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/game-brief/workflow.yaml"
       description: Create Game Brief
 
-    - trigger: gdd
+    - trigger: create-gdd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/gdd/workflow.yaml"
       description: Create Game Design Document (GDD)
 

src/modules/bmm/agents/pm.agent.yaml

@@ -31,10 +31,20 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
-    - trigger: prd
+    - trigger: create-prd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
       description: Create Product Requirements Document (PRD) for Level 2-4 projects
 
+    - trigger: create-epics-and-stories
+      workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+      description: Break PRD requirements into implementable epics and stories
+
+    - trigger: validate-prd
+      validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+      document: "{output_folder}/PRD.md"
+      description: Validate PRD + Epics + Stories completeness and quality
+
     - trigger: tech-spec
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
       description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects

src/modules/bmm/workflows/1-analysis/domain-research/instructions.md

@@ -0,0 +1,423 @@
+# Domain Research - Collaborative Domain Exploration
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This is COLLABORATIVE RESEARCH - engage the user as a partner, not just a data source</critical>
+<critical>The goal is PRACTICAL UNDERSTANDING that directly informs requirements and architecture</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to domain-brief.md continuously as you discover - never wait until the end</critical>
+
+<workflow>
+
+<step n="0" goal="Set research context">
+<action>Welcome {user_name} to collaborative domain research
+
+Check for context:
+
+- Was this triggered from PRD workflow?
+- Is there a workflow-status.yaml with project context?
+- Did user provide initial domain/project description?
+
+If context exists, reflect it back:
+"I understand you're building [description]. Let's explore the [domain] aspects together to ensure we capture all critical requirements."
+
+If no context:
+"Let's explore your project's domain together. Tell me about what you're building and what makes it unique or complex."</action>
+</step>
+
+<step n="1" goal="Domain detection and scoping">
+<action>Through conversation, identify the domain and its complexity
+
+Listen for domain signals and explore:
+
+- "Is this in a regulated industry?"
+- "Are there safety or compliance concerns?"
+- "What could go wrong if this fails?"
+- "Who are the stakeholders beyond direct users?"
+- "Are there industry standards we need to follow?"
+
+Based on responses, identify primary domain(s):
+
+- Healthcare/Medical
+- Financial Services
+- Government/Public Sector
+- Education
+- Aerospace/Defense
+- Automotive
+- Energy/Utilities
+- Legal
+- Insurance
+- Scientific/Research
+- Other specialized domain
+
+Share your understanding:
+"Based on our discussion, this appears to be a [domain] project with [key characteristics]. The main areas we should research are:
+
+- [Area 1]
+- [Area 2]
+- [Area 3]
+
+What concerns you most about building in this space?"</action>
+
+<template-output>domain_overview</template-output>
+</step>
+
+<step n="2" goal="Collaborative concern mapping">
+<action>Work WITH the user to identify critical concerns
+
+"Let's map out the important considerations together. I'll share what I typically see in [domain], and you tell me what applies to your case."
+
+For detected domain, explore relevant areas:
+
+HEALTHCARE:
+"In healthcare software, teams often worry about:
+
+- FDA approval pathways (510k, De Novo, PMA)
+- HIPAA compliance for patient data
+- Clinical validation requirements
+- Integration with hospital systems (HL7, FHIR, DICOM)
+- Patient safety and liability
+
+Which of these apply to you? What else concerns you?"
+
+FINTECH:
+"Financial software typically deals with:
+
+- KYC/AML requirements
+- Payment processing regulations (PCI DSS)
+- Regional compliance (US, EU, specific countries?)
+- Fraud prevention
+- Audit trails and reporting
+
+What's your situation with these? Any specific regions?"
+
+AEROSPACE:
+"Aerospace software often requires:
+
+- DO-178C certification levels
+- Safety analysis (FMEA, FTA)
+- Simulation validation
+- Real-time performance guarantees
+- Export control (ITAR)
+
+Which are relevant for your project?"
+
+[Continue for other domains...]
+
+Document concerns as the user shares them
+Ask follow-up questions to understand depth:
+
+- "How critical is this requirement?"
+- "Is this a must-have for launch or can it come later?"
+- "Do you have expertise here or need guidance?"</action>
+
+<template-output>concern_mapping</template-output>
+</step>
+
+<step n="3" goal="Research key requirements together">
+<action>Conduct research WITH the user watching and contributing
+
+"Let me research the current requirements for [specific concern]. You can guide me toward what's most relevant."
+
+<WebSearch>{specific_requirement} requirements {date}</WebSearch>
+
+Share findings immediately:
+"Here's what I found about [requirement]:
+
+- [Key point 1]
+- [Key point 2]
+- [Key point 3]
+
+Does this match your understanding? Anything surprising or concerning?"
+
+For each major concern:
+
+1. Research current standards/regulations
+2. Share findings with user
+3. Get their interpretation
+4. Note practical implications
+
+If user has expertise:
+"You seem knowledgeable about [area]. What should I know that might not be in public documentation?"
+
+If user is learning:
+"This might be new territory. Let me explain what this means practically for your development..."</action>
+
+<template-output>regulatory_requirements</template-output>
+<template-output>industry_standards</template-output>
+</step>
+
+<step n="4" goal="Identify practical implications">
+<action>Translate research into practical development impacts
+
+"Based on what we've learned, here's what this means for your project:
+
+ARCHITECTURE IMPLICATIONS:
+
+- [How this affects system design]
+- [Required components or patterns]
+- [Performance or security needs]
+
+DEVELOPMENT IMPLICATIONS:
+
+- [Additional development effort]
+- [Special expertise needed]
+- [Testing requirements]
+
+TIMELINE IMPLICATIONS:
+
+- [Certification/approval timelines]
+- [Validation requirements]
+- [Documentation needs]
+
+COST IMPLICATIONS:
+
+- [Compliance costs]
+- [Required tools or services]
+- [Ongoing maintenance]
+
+Does this align with your expectations? Any surprises we should dig into?"</action>
+
+<template-output>practical_implications</template-output>
+</step>
+
+<step n="5" goal="Discover domain-specific patterns">
+<action>Explore how others solve similar problems
+
+"Let's look at how successful [domain] products handle these challenges."
+
+<WebSearch>best {domain} software architecture patterns {date}</WebSearch>
+<WebSearch>{domain} software case studies {date}</WebSearch>
+
+Discuss patterns:
+"I found these common approaches in [domain]:
+
+Pattern 1: [Description]
+
+- Pros: [Benefits]
+- Cons: [Tradeoffs]
+- When to use: [Conditions]
+
+Pattern 2: [Description]
+
+- Pros: [Benefits]
+- Cons: [Tradeoffs]
+- When to use: [Conditions]
+
+Which resonates with your vision? Or are you thinking something different?"
+
+If user proposes novel approach:
+"That's interesting and different from the standard patterns. Let's explore:
+
+- What makes your approach unique?
+- What problem does it solve that existing patterns don't?
+- What are the risks?
+- How do we validate it?"</action>
+
+<template-output>domain_patterns</template-output>
+<template-output if="novel approach">innovation_notes</template-output>
+</step>
+
+<step n="6" goal="Risk assessment and mitigation">
+<action>Collaboratively identify and address risks
+
+"Every [domain] project has risks. Let's think through yours:
+
+REGULATORY RISKS:
+
+- What if regulations change during development?
+- What if approval/certification takes longer?
+- What if we misinterpret requirements?
+
+TECHNICAL RISKS:
+
+- What if the domain requirements conflict with user experience?
+- What if performance requirements are harder than expected?
+- What if integrations are more complex?
+
+MARKET RISKS:
+
+- What if competitors move faster?
+- What if domain experts are hard to find?
+- What if users resist domain-mandated workflows?
+
+For each risk you're concerned about, let's identify:
+
+1. How likely is it?
+2. What's the impact if it happens?
+3. How can we mitigate it?
+4. What's our plan B?"</action>
+
+<template-output>risk_assessment</template-output>
+</step>
+
+<step n="7" goal="Create validation strategy">
+<action>Plan how to ensure domain requirements are met
+
+"Let's plan how to validate that we're meeting [domain] requirements:
+
+COMPLIANCE VALIDATION:
+
+- How do we verify regulatory compliance?
+- Who needs to review/approve?
+- What documentation is required?
+
+TECHNICAL VALIDATION:
+
+- How do we prove the system works correctly?
+- What metrics matter?
+- What testing is required?
+
+DOMAIN EXPERT VALIDATION:
+
+- Who are the domain experts to involve?
+- When should they review?
+- What are their success criteria?
+
+USER VALIDATION:
+
+- How do we ensure it's still usable despite constraints?
+- What user testing is needed?
+- How do we balance domain requirements with UX?
+
+What validation is most critical for your confidence?"</action>
+
+<template-output>validation_strategy</template-output>
+</step>
+
+<step n="8" goal="Document decision points">
+<action>Capture key decisions and rationale
+
+"Let's document the important decisions we've made:
+
+DOMAIN APPROACH:
+
+- We're choosing [approach] because [rationale]
+- We're prioritizing [requirement] over [requirement] because [reason]
+- We're deferring [requirement] to Phase 2 because [justification]
+
+COMPLIANCE STRATEGY:
+
+- We'll pursue [pathway] for regulatory approval
+- We'll implement [standard] for industry compliance
+- We'll handle [requirement] by [approach]
+
+RISK DECISIONS:
+
+- We accept [risk] because [reason]
+- We'll mitigate [risk] through [approach]
+- We'll monitor [risk] by [method]
+
+Any decisions you want to revisit or rationale to add?"</action>
+
+<template-output>key_decisions</template-output>
+</step>
+
+<step n="9" goal="Create actionable recommendations">
+<action>Synthesize research into specific recommendations
+
+"Based on our research, here are my recommendations for your PRD and development:
+
+MUST HAVE (Domain Critical):
+
+1. [Specific requirement with why it's critical]
+2. [Specific requirement with why it's critical]
+3. [Specific requirement with why it's critical]
+
+SHOULD HAVE (Domain Important):
+
+1. [Requirement that's important but not blocking]
+2. [Requirement that's important but not blocking]
+
+CONSIDER (Domain Nice-to-Have):
+
+1. [Enhancement that would differentiate]
+2. [Enhancement that would differentiate]
+
+DEVELOPMENT SEQUENCE:
+
+1. First: [What to build first and why]
+2. Then: [What comes next and why]
+3. Later: [What can wait and why]
+
+EXPERTISE NEEDED:
+
+- [Domain expert role]: For [specific areas]
+- [Technical expert role]: For [specific requirements]
+
+TIMELINE CONSIDERATIONS:
+
+- Allow [time] for [process/approval]
+- Start [requirement] early because [reason]
+- [Requirement] can be parallel with development
+
+Do these recommendations feel right? What would you adjust?"</action>
+
+<template-output>recommendations</template-output>
+</step>
+
+<step n="10" goal="Package for PRD integration">
+<action>Create clear handoff to PRD workflow
+
+"I've captured everything in domain-brief.md. Here's the summary for your PRD:
+
+DOMAIN: {identified_domain}
+COMPLEXITY: {high|medium}
+
+KEY REQUIREMENTS TO INCORPORATE:
+
+- [Requirement 1 - critical for domain]
+- [Requirement 2 - critical for domain]
+- [Requirement 3 - important consideration]
+
+IMPACTS ON:
+
+- Functional Requirements: [How domain affects features]
+- Non-Functional Requirements: [Performance, security, etc.]
+- Architecture: [System design considerations]
+- Development: [Process and timeline impacts]
+
+REFERENCE DOCS:
+
+- Full domain analysis: domain-brief.md
+- Regulations researched: [List with links]
+- Standards referenced: [List with links]
+
+When you return to PRD, reference this brief for domain context.
+
+Any final questions before we wrap up the domain research?"</action>
+
+<template-output>summary_for_prd</template-output>
+</step>
+
+<step n="11" goal="Close with next steps">
+<output>**✅ Domain Research Complete, {user_name}!**
+
+We've explored the {domain} aspects of your project together and documented critical requirements.
+
+**Created:**
+
+- **domain-brief.md** - Complete domain analysis with requirements and recommendations
+
+**Key Findings:**
+
+- Primary domain: {domain}
+- Complexity level: {complexity}
+- Critical requirements: {count} identified
+- Risks identified: {count} with mitigation strategies
+
+**Next Steps:**
+
+1. Return to PRD workflow with this domain context
+2. Domain requirements will shape your functional requirements
+3. Reference domain-brief.md for detailed requirements
+
+**Remember:**
+{most_important_finding}
+
+The domain research will ensure your PRD captures not just what to build, but HOW to build it correctly for {domain}.
+</output>
+</step>
+
+</workflow>

src/modules/bmm/workflows/1-analysis/domain-research/template.md

@@ -0,0 +1,180 @@
+# Domain Brief - {project_name}
+
+Generated: {date}
+Domain: {primary_domain}
+Complexity: {complexity_level}
+
+## Executive Summary
+
+{brief_overview_of_domain_research_findings}
+
+## Domain Overview
+
+### Industry Context
+
+{domain_overview}
+
+### Regulatory Landscape
+
+{regulatory_environment}
+
+### Key Stakeholders
+
+{stakeholder_analysis}
+
+## Critical Concerns
+
+### Compliance Requirements
+
+{concern_mapping}
+
+### Technical Constraints
+
+{technical_limitations_from_domain}
+
+### Safety/Risk Considerations
+
+{safety_risk_factors}
+
+## Regulatory Requirements
+
+{regulatory_requirements}
+
+## Industry Standards
+
+{industry_standards}
+
+## Practical Implications
+
+### Architecture Impact
+
+{architecture_implications}
+
+### Development Impact
+
+{development_implications}
+
+### Timeline Impact
+
+{timeline_implications}
+
+### Cost Impact
+
+{cost_implications}
+
+## Domain Patterns
+
+### Established Patterns
+
+{domain_patterns}
+
+### Innovation Opportunities
+
+{innovation_notes}
+
+## Risk Assessment
+
+### Identified Risks
+
+{risk_assessment}
+
+### Mitigation Strategies
+
+{mitigation_approaches}
+
+## Validation Strategy
+
+### Compliance Validation
+
+{compliance_validation_approach}
+
+### Technical Validation
+
+{technical_validation_approach}
+
+### Domain Expert Validation
+
+{expert_validation_approach}
+
+## Key Decisions
+
+{key_decisions}
+
+## Recommendations
+
+### Must Have (Critical)
+
+{critical_requirements}
+
+### Should Have (Important)
+
+{important_requirements}
+
+### Consider (Nice-to-Have)
+
+{optional_enhancements}
+
+### Development Sequence
+
+{recommended_sequence}
+
+### Required Expertise
+
+{expertise_needed}
+
+## PRD Integration Guide
+
+### Summary for PRD
+
+{summary_for_prd}
+
+### Requirements to Incorporate
+
+- {requirement_1}
+- {requirement_2}
+- {requirement_3}
+
+### Architecture Considerations
+
+- {architecture_consideration_1}
+- {architecture_consideration_2}
+
+### Development Considerations
+
+- {development_consideration_1}
+- {development_consideration_2}
+
+## References
+
+### Regulations Researched
+
+- {regulation_1_with_link}
+- {regulation_2_with_link}
+
+### Standards Referenced
+
+- {standard_1_with_link}
+- {standard_2_with_link}
+
+### Additional Resources
+
+- {resource_1}
+- {resource_2}
+
+## Appendix
+
+### Research Notes
+
+{detailed_research_notes}
+
+### Conversation Highlights
+
+{key_discussion_points_with_user}
+
+### Open Questions
+
+{questions_requiring_further_research}
+
+---
+
+_This domain brief was created through collaborative research between {user_name} and the AI facilitator. It should be referenced during PRD creation and updated as new domain insights emerge._

src/modules/bmm/workflows/1-analysis/domain-research/workflow.yaml

@@ -0,0 +1,36 @@
+workflow:
+  id: domain-research
+  name: "Domain Research"
+  module: bmm
+  version: "6.0.0-alpha"
+  description: "Collaborative exploration of domain-specific requirements, regulations, and patterns for complex projects"
+
+  environment:
+    # Inherit from parent workflow or set defaults
+    user_name: "partner"
+    user_skill_level: "intermediate"
+    communication_language: "English"
+    document_output_language: "English"
+    date: "{system.date}"
+
+  required_files:
+    - instructions.md
+    - template.md
+
+  optional_files:
+    - domain-knowledge-base.md
+
+  outputs:
+    - domain-brief.md
+
+  metadata:
+    category: "analysis"
+    complexity: "medium"
+    estimated_time: "30-45 minutes"
+    prerequisites:
+      - "Basic project understanding"
+    when_to_use:
+      - "Complex regulated domains (healthcare, finance, aerospace)"
+      - "Novel technical domains requiring deep understanding"
+      - "Before PRD when domain expertise needed"
+      - "When compliance and regulations matter"

src/modules/bmm/workflows/1-analysis/product-brief/instructions.md

@@ -1,21 +1,37 @@
-# Product Brief - Interactive Workflow Instructions
+# Product Brief - Context-Adaptive Discovery Instructions
 
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>This workflow uses INTENT-DRIVEN FACILITATION - adapt organically to what emerges</critical>
+<critical>The goal is DISCOVERING WHAT MATTERS through natural conversation, not filling a template</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to the document continuously as you discover - never wait until the end</critical>
 
-<critical>DOCUMENT OUTPUT: Concise, professional, strategically focused. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+## Input Document Discovery
+
+This workflow may reference: market research, brainstorming documents, user specified other inputs, or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
 
 <workflow>
 
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
 <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<check if="status file not found">
+<action if="status file not found">Set standalone_mode = true</action>
-  <output>No workflow status file found. Product Brief is optional - you can continue without status tracking.</output>
-  <action>Set standalone_mode = true</action>
-</check>
 
 <check if="status file found">
   <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
@@ -25,9 +41,10 @@
   <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 2">
-    <output>Note: Product Brief is most valuable for Level 2+ projects. Your project is Level {{project_level}}.</output>
+    <output>**Note: Level {{project_level}} Project**
-    <output>You may want to skip directly to technical planning instead.</output>
+
-  </check>
+Product Brief is most valuable for Level 2+ projects, but can help clarify vision for any project.</output>
+</check>
 
   <check if="product-brief status is file path (already completed)">
     <output>⚠️ Product Brief already completed: {{product-brief status}}</output>
@@ -38,7 +55,7 @@
     </check>
   </check>
 
-  <check if="product-brief is not the next expected workflow (latter items are completed already in the list)">
+  <check if="product-brief is not the next expected workflow">
     <output>⚠️ Next expected workflow: {{next_workflow}}. Product Brief is out of sequence.</output>
     <ask>Continue with Product Brief anyway? (y/n)</ask>
     <check if="n">
@@ -51,241 +68,427 @@
 </check>
 </step>
 
-<step n="1" goal="Initialize product brief session">
+<step n="1" goal="Begin the journey and understand context">
-<action>Welcome the user in {communication_language} to the Product Brief creation process</action>
+<action>Welcome {user_name} warmly in {communication_language}
-<action>Explain this is a collaborative process to define their product vision and strategic foundation</action>
+
-<action>Ask the user to provide the project name for this product brief</action>
+Adapt your tone to {user_skill_level}:
+
+- Expert: "Let's define your product vision. What are you building?"
+- Intermediate: "I'm here to help shape your product vision. Tell me about your idea."
+- Beginner: "Hi! I'm going to help you figure out exactly what you want to build. Let's start with your idea - what got you excited about this?"
+
+Start with open exploration:
+
+- What sparked this idea?
+- What are you hoping to build?
+- Who is this for - yourself, a business, users you know?
+
+CRITICAL: Listen for context clues that reveal their situation:
+
+- Personal/hobby project (fun, learning, small audience)
+- Startup/solopreneur (market opportunity, competition matters)
+- Enterprise/corporate (stakeholders, compliance, strategic alignment)
+- Technical enthusiasm (implementation focused)
+- Business opportunity (market/revenue focused)
+- Problem frustration (solution focused)
+
+Based on their initial response, sense:
+
+- How formal/casual they want to be
+- Whether they think in business or technical terms
+- If they have existing materials to share
+- Their confidence level with the domain</action>
+
+<ask>What's the project name, and what got you excited about building this?</ask>
+
+<action>From even this first exchange, create initial document sections</action>
 <template-output>project_name</template-output>
-</step>
-
-<step n="1" goal="Gather available inputs and context">
-<action>Explore what existing materials the user has available to inform the brief</action>
-<action>Offer options for input sources: market research, brainstorming results, competitive analysis, initial ideas, or starting fresh</action>
-<action>If documents are provided, load and analyze them to extract key insights, themes, and patterns</action>
-<action>Engage the user about their core vision: what problem they're solving, who experiences it most acutely, and what sparked this product idea</action>
-<action>Build initial understanding through conversational exploration rather than rigid questioning</action>
-
-<template-output>initial_context</template-output>
-</step>
-
-<step n="2" goal="Choose collaboration mode">
-<ask>How would you like to work through the brief?
-
-**1. Interactive Mode** - We'll work through each section together, discussing and refining as we go
-
-**2. YOLO Mode** - I'll generate a complete draft based on our conversation so far, then we'll refine it together
-
-Which approach works best for you?</ask>
-
-<action>Store the user's preference for mode</action>
-<template-output>collaboration_mode</template-output>
-</step>
-
-<step n="3" goal="Define the problem statement" if="collaboration_mode == 'interactive'">
-<action>Guide deep exploration of the problem: current state frustrations, quantifiable impact (time/money/opportunities), why existing solutions fall short, urgency of solving now</action>
-<action>Challenge vague statements and push for specificity with probing questions</action>
-<action>Help the user articulate measurable pain points with evidence</action>
-<action>Craft a compelling, evidence-based problem statement</action>
-
-<template-output>problem_statement</template-output>
-</step>
-
-<step n="4" goal="Develop the proposed solution" if="collaboration_mode == 'interactive'">
-<action>Shape the solution vision by exploring: core approach to solving the problem, key differentiators from existing solutions, why this will succeed, ideal user experience</action>
-<action>Focus on the "what" and "why", not implementation details - keep it strategic</action>
-<action>Help articulate compelling differentiators that make this solution unique</action>
-<action>Craft a clear, inspiring solution vision</action>
-
-<template-output>proposed_solution</template-output>
-</step>
-
-<step n="5" goal="Identify target users" if="collaboration_mode == 'interactive'">
-<action>Guide detailed definition of primary users: demographic/professional profile, current problem-solving methods, specific pain points, goals they're trying to achieve</action>
-<action>Explore secondary user segments if applicable and define how their needs differ</action>
-<action>Push beyond generic personas like "busy professionals" - demand specificity and actionable details</action>
-<action>Create specific, actionable user profiles that inform product decisions</action>
-
-<template-output>primary_user_segment</template-output>
-<template-output>secondary_user_segment</template-output>
-</step>
-
-<step n="6" goal="Establish goals and success metrics" if="collaboration_mode == 'interactive'">
-<action>Guide establishment of SMART goals across business objectives and user success metrics</action>
-<action>Explore measurable business outcomes (user acquisition targets, cost reductions, revenue goals)</action>
-<action>Define user success metrics focused on behaviors and outcomes, not features (task completion time, return frequency)</action>
-<action>Help formulate specific, measurable goals that distinguish between business and user success</action>
-<action>Identify top 3-5 Key Performance Indicators that will track product success</action>
-
-<template-output>business_objectives</template-output>
-<template-output>user_success_metrics</template-output>
-<template-output>key_performance_indicators</template-output>
-</step>
-
-<step n="7" goal="Define MVP scope" if="collaboration_mode == 'interactive'">
-<action>Be ruthless about MVP scope - identify absolute MUST-HAVE features for launch that validate the core hypothesis</action>
-<action>For each proposed feature, probe why it's essential vs nice-to-have</action>
-<action>Identify tempting features that need to wait for v2 - what adds complexity without core value</action>
-<action>Define what constitutes a successful MVP launch with clear criteria</action>
-<action>Challenge scope creep aggressively and push for true minimum viability</action>
-<action>Clearly separate must-haves from nice-to-haves</action>
-
-<template-output>core_features</template-output>
-<template-output>out_of_scope</template-output>
-<template-output>mvp_success_criteria</template-output>
-</step>
-
-<step n="8" goal="Assess financial impact and ROI" if="collaboration_mode == 'interactive'">
-<action>Explore financial considerations: development investment, revenue potential, cost savings opportunities, break-even timing, budget alignment</action>
-<action>Investigate strategic alignment: company OKRs, strategic objectives, key initiatives supported, opportunity cost of NOT doing this</action>
-<action>Help quantify financial impact where possible - both tangible and intangible value</action>
-<action>Connect this product to broader company strategy and demonstrate strategic value</action>
-
-<template-output>financial_impact</template-output>
-<template-output>company_objectives_alignment</template-output>
-<template-output>strategic_initiatives</template-output>
-</step>
-
-<step n="9" goal="Explore post-MVP vision" optional="true" if="collaboration_mode == 'interactive'">
-<action>Guide exploration of post-MVP future: Phase 2 features, expansion opportunities, long-term vision (1-2 years)</action>
-<action>Ensure MVP decisions align with future direction while staying focused on immediate goals</action>
-
-<template-output>phase_2_features</template-output>
-<template-output>long_term_vision</template-output>
-<template-output>expansion_opportunities</template-output>
-</step>
-
-<step n="10" goal="Document technical considerations" if="collaboration_mode == 'interactive'">
-<action>Capture technical context as preferences, not final decisions</action>
-<action>Explore platform requirements: web/mobile/desktop, browser/OS support, performance needs, accessibility standards</action>
-<action>Investigate technology preferences or constraints: frontend/backend frameworks, database needs, infrastructure requirements</action>
-<action>Identify existing systems requiring integration</action>
-<action>Check for technical-preferences.yaml file if available</action>
-<action>Note these are initial thoughts for PM and architect to consider during planning</action>
-
-<template-output>platform_requirements</template-output>
-<template-output>technology_preferences</template-output>
-<template-output>architecture_considerations</template-output>
-</step>
-
-<step n="11" goal="Identify constraints and assumptions" if="collaboration_mode == 'interactive'">
-<action>Guide realistic expectations setting around constraints: budget/resource limits, timeline pressures, team size/expertise, technical limitations</action>
-<action>Explore assumptions being made about: user behavior, market conditions, technical feasibility</action>
-<action>Document constraints clearly and list assumptions that need validation during development</action>
-
-<template-output>constraints</template-output>
-<template-output>key_assumptions</template-output>
-</step>
-
-<step n="12" goal="Assess risks and open questions" optional="true" if="collaboration_mode == 'interactive'">
-<action>Facilitate honest risk assessment: what could derail the project, impact if risks materialize</action>
-<action>Document open questions: what still needs figuring out, what needs more research</action>
-<action>Help prioritize risks by impact and likelihood</action>
-<action>Frame unknowns as opportunities to prepare, not just worries</action>
-
-<template-output>key_risks</template-output>
-<template-output>open_questions</template-output>
-<template-output>research_areas</template-output>
-</step>
-
-<!-- YOLO Mode - Generate everything then refine -->
-<step n="3" goal="Generate complete brief draft" if="collaboration_mode == 'yolo'">
-<action>Based on initial context and any provided documents, generate a complete product brief covering all sections</action>
-<action>Make reasonable assumptions where information is missing</action>
-<action>Flag areas that need user validation with [NEEDS CONFIRMATION] tags</action>
-
-<template-output>problem_statement</template-output>
-<template-output>proposed_solution</template-output>
-<template-output>primary_user_segment</template-output>
-<template-output>secondary_user_segment</template-output>
-<template-output>business_objectives</template-output>
-<template-output>user_success_metrics</template-output>
-<template-output>key_performance_indicators</template-output>
-<template-output>core_features</template-output>
-<template-output>out_of_scope</template-output>
-<template-output>mvp_success_criteria</template-output>
-<template-output>phase_2_features</template-output>
-<template-output>long_term_vision</template-output>
-<template-output>expansion_opportunities</template-output>
-<template-output>financial_impact</template-output>
-<template-output>company_objectives_alignment</template-output>
-<template-output>strategic_initiatives</template-output>
-<template-output>platform_requirements</template-output>
-<template-output>technology_preferences</template-output>
-<template-output>architecture_considerations</template-output>
-<template-output>constraints</template-output>
-<template-output>key_assumptions</template-output>
-<template-output>key_risks</template-output>
-<template-output>open_questions</template-output>
-<template-output>research_areas</template-output>
-
-<action>Present the complete draft to the user</action>
-<ask>Here's the complete brief draft. What would you like to adjust or refine?</ask>
-</step>
-
-<step n="4" goal="Refine brief sections" repeat="until-approved" if="collaboration_mode == 'yolo'">
-<ask>Which section would you like to refine?
-1. Problem Statement
-2. Proposed Solution
-3. Target Users
-4. Goals and Metrics
-5. MVP Scope
-6. Post-MVP Vision
-7. Financial Impact and Strategic Alignment
-8. Technical Considerations
-9. Constraints and Assumptions
-10. Risks and Questions
-11. Save and continue</ask>
-
-<action>Work with user to refine selected section</action>
-<action>Update relevant template outputs</action>
-</step>
-
-<!-- Final steps for both modes -->
-<step n="13" goal="Create executive summary">
-<action>Synthesize all sections into a compelling executive summary</action>
-<action>Include:
-- Product concept in 1-2 sentences
-- Primary problem being solved
-- Target market identification
-- Key value proposition</action>
-
 <template-output>executive_summary</template-output>
+
+<action>If they mentioned existing documents (research, brainstorming, etc.):
+
+- Load and analyze these materials
+- Extract key themes and insights
+- Reference these naturally in conversation: "I see from your research that..."
+- Use these to accelerate discovery, not repeat questions</action>
+
+<template-output>initial_vision</template-output>
 </step>
 
-<step n="14" goal="Compile supporting materials">
+<step n="2" goal="Discover the problem worth solving">
-<action>If research documents were provided, create a summary of key findings</action>
+<action>Guide problem discovery through natural conversation
-<action>Document any stakeholder input received during the process</action>
-<action>Compile list of reference documents and resources</action>
 
-<template-output>research_summary</template-output>
+DON'T ask: "What problem does this solve?"
-<template-output>stakeholder_input</template-output>
-<template-output>references</template-output>
-</step>
 
-<step n="15" goal="Final review and handoff">
+DO explore conversationally based on their context:
-<action>Generate the complete product brief document</action>
-<action>Review all sections for completeness and consistency</action>
-<action>Flag any areas that need PM attention with [PM-TODO] tags</action>
 
-<ask>The product brief is complete! Would you like to:
+For hobby projects:
 
-1. Review the entire document
+- "What's annoying you that this would fix?"
-2. Make final adjustments
+- "What would this make easier or more fun?"
-3. Generate an executive summary version (3-page limit)
+- "Show me what the experience is like today without this"
-4. Save and prepare for handoff to PM
 
-This brief will serve as the primary input for creating the Product Requirements Document (PRD).</ask>
+For business ventures:
 
-<check if="user chooses option 3 (executive summary)">
+- "Walk me through the frustration your users face today"
-  <action>Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment</action>
+- "What's the cost of this problem - time, money, opportunities?"
-  <action>Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md</action>
+- "Who's suffering most from this? Tell me about them"
+- "What solutions have people tried? Why aren't they working?"
+
+For enterprise:
+
+- "What's driving the need for this internally?"
+- "Which teams/processes are most affected?"
+- "What's the business impact of not solving this?"
+- "Are there compliance or strategic drivers?"
+
+Listen for depth cues:
+
+- Brief answers → dig deeper with follow-ups
+- Detailed passion → let them flow, capture everything
+- Uncertainty → help them explore with examples
+- Multiple problems → help prioritize the core issue
+
+Adapt your response:
+
+- If they struggle: offer analogies, examples, frameworks
+- If they're clear: validate and push for specifics
+- If they're technical: explore implementation challenges
+- If they're business-focused: quantify impact</action>
+
+<action>Immediately capture what emerges - even if preliminary</action>
+<template-output>problem_statement</template-output>
+
+<check if="user mentioned metrics, costs, or business impact">
+  <action>Explore the measurable impact of the problem</action>
+  <template-output>problem_impact</template-output>
 </check>
 
-<template-output>final_brief</template-output>
+<check if="user mentioned current solutions or competitors">
-<template-output>executive_brief</template-output>
+  <action>Understand why existing solutions fall short</action>
+  <template-output>existing_solutions_gaps</template-output>
+</check>
+
+<action>Reflect understanding: "So the core issue is {{problem_summary}}, and {{impact_if_mentioned}}. Let me capture that..."</action>
+</step>
+
+<step n="3" goal="Shape the solution vision">
+<action>Transition naturally from problem to solution
+
+Based on their energy and context, explore:
+
+For builders/makers:
+
+- "How do you envision this working?"
+- "Walk me through the experience you want to create"
+- "What's the 'magic moment' when someone uses this?"
+
+For business minds:
+
+- "What's your unique approach to solving this?"
+- "How is this different from what exists today?"
+- "What makes this the RIGHT solution now?"
+
+For enterprise:
+
+- "What would success look like for the organization?"
+- "How does this fit with existing systems/processes?"
+- "What's the transformation you're enabling?"
+
+Go deeper based on responses:
+
+- If innovative → explore the unique angle
+- If standard → focus on execution excellence
+- If technical → discuss key capabilities
+- If user-focused → paint the journey
+
+Web research when relevant:
+
+- If they mention competitors → research current solutions
+- If they claim innovation → verify uniqueness
+- If they reference trends → get current data</action>
+
+<action if="competitor or market mentioned">
+  <WebSearch>{{competitor/market}} latest features 2024</WebSearch>
+  <action>Use findings to sharpen differentiation discussion</action>
+</action>
+
+<template-output>proposed_solution</template-output>
+
+<check if="unique differentiation discussed">
+  <template-output>key_differentiators</template-output>
+</check>
+
+<action>Continue building the living document</action>
+</step>
+
+<step n="4" goal="Understand the people who need this">
+<action>Discover target users through storytelling, not demographics
+
+Facilitate based on project type:
+
+Personal/hobby:
+
+- "Who else would love this besides you?"
+- "Tell me about someone who would use this"
+- Keep it light and informal
+
+Startup/business:
+
+- "Describe your ideal first customer - not demographics, but their situation"
+- "What are they doing today without your solution?"
+- "What would make them say 'finally, someone gets it!'?"
+- "Are there different types of users with different needs?"
+
+Enterprise:
+
+- "Which roles/departments will use this?"
+- "Walk me through their current workflow"
+- "Who are the champions vs skeptics?"
+- "What about indirect stakeholders?"
+
+Push beyond generic personas:
+
+- Not: "busy professionals" → "Sales reps who waste 2 hours/day on data entry"
+- Not: "tech-savvy users" → "Developers who know Docker but hate configuring it"
+- Not: "small businesses" → "Shopify stores doing $10-50k/month wanting to scale"
+
+For each user type that emerges:
+
+- Current behavior/workflow
+- Specific frustrations
+- What they'd value most
+- Their technical comfort level</action>
+
+<template-output>primary_user_segment</template-output>
+
+<check if="multiple user types mentioned">
+  <action>Explore secondary users only if truly different needs</action>
+  <template-output>secondary_user_segment</template-output>
+</check>
+
+<check if="user journey or workflow discussed">
+  <template-output>user_journey</template-output>
+</check>
+</step>
+
+<step n="5" goal="Define what success looks like" repeat="adapt-to-context">
+<action>Explore success measures that match their context
+
+For personal projects:
+
+- "How will you know this is working well?"
+- "What would make you proud of this?"
+- Keep metrics simple and meaningful
+
+For startups:
+
+- "What metrics would convince you this is taking off?"
+- "What user behaviors show they love it?"
+- "What business metrics matter most - users, revenue, retention?"
+- Push for specific targets: "100 users" not "lots of users"
+
+For enterprise:
+
+- "How will the organization measure success?"
+- "What KPIs will stakeholders care about?"
+- "What are the must-hit metrics vs nice-to-haves?"
+
+Only dive deep into metrics if they show interest
+Skip entirely for pure hobby projects
+Focus on what THEY care about measuring</action>
+
+<check if="metrics or goals discussed">
+  <template-output>success_metrics</template-output>
+
+  <check if="business objectives mentioned">
+    <template-output>business_objectives</template-output>
+  </check>
+
+  <check if="KPIs matter to them">
+    <template-output>key_performance_indicators</template-output>
+  </check>
+</check>
+
+<action>Keep the document growing with each discovery</action>
+</step>
+
+<step n="6" goal="Discover the MVP scope">
+<critical>Focus on FEATURES not epics - that comes in Phase 2</critical>
+
+<action>Guide MVP scoping based on their maturity
+
+For experimental/hobby:
+
+- "What's the ONE thing this must do to be useful?"
+- "What would make a fun first version?"
+- Embrace simplicity
+
+For business ventures:
+
+- "What's the smallest version that proves your hypothesis?"
+- "What features would make early adopters say 'good enough'?"
+- "What's tempting to add but would slow you down?"
+- Be ruthless about scope creep
+
+For enterprise:
+
+- "What's the pilot scope that demonstrates value?"
+- "Which capabilities are must-have for initial rollout?"
+- "What can we defer to Phase 2?"
+
+Use this framing:
+
+- Core features: "Without this, the product doesn't work"
+- Nice-to-have: "This would be great, but we can launch without it"
+- Future vision: "This is where we're headed eventually"
+
+Challenge feature creep:
+
+- "Do we need that for launch, or could it come later?"
+- "What if we started without that - what breaks?"
+- "Is this core to proving the concept?"</action>
+
+<template-output>core_features</template-output>
+
+<check if="scope creep discussed">
+  <template-output>out_of_scope</template-output>
+</check>
+
+<check if="future features mentioned">
+  <template-output>future_vision_features</template-output>
+</check>
+
+<check if="success criteria for MVP mentioned">
+  <template-output>mvp_success_criteria</template-output>
+</check>
+</step>
+
+<step n="7" goal="Explore relevant context dimensions" repeat="until-natural-end">
+<critical>Only explore what emerges naturally - skip what doesn't matter</critical>
+
+<action>Based on the conversation so far, selectively explore:
+
+IF financial aspects emerged:
+
+- Development investment needed
+- Revenue potential or cost savings
+- ROI timeline
+- Budget constraints
+  <check if="discussed">
+  <template-output>financial_considerations</template-output>
+  </check>
+
+IF market competition mentioned:
+
+- Competitive landscape
+- Market opportunity size
+- Differentiation strategy
+- Market timing
+  <check if="discussed">
+  <WebSearch>{{market}} size trends 2024</WebSearch>
+  <template-output>market_analysis</template-output>
+  </check>
+
+IF technical preferences surfaced:
+
+- Platform choices (web/mobile/desktop)
+- Technology stack preferences
+- Integration needs
+- Performance requirements
+  <check if="discussed">
+  <template-output>technical_preferences</template-output>
+  </check>
+
+IF organizational context emerged:
+
+- Strategic alignment
+- Stakeholder buy-in needs
+- Change management considerations
+- Compliance requirements
+  <check if="discussed">
+  <template-output>organizational_context</template-output>
+  </check>
+
+IF risks or concerns raised:
+
+- Key risks and mitigation
+- Critical assumptions
+- Open questions needing research
+  <check if="discussed">
+  <template-output>risks_and_assumptions</template-output>
+  </check>
+
+IF timeline pressures mentioned:
+
+- Launch timeline
+- Critical milestones
+- Dependencies
+  <check if="discussed">
+  <template-output>timeline_constraints</template-output>
+  </check>
+
+Skip anything that hasn't naturally emerged
+Don't force sections that don't fit their context</action>
+</step>
+
+<step n="8" goal="Refine and complete the living document">
+<action>Review what's been captured with the user
+
+"Let me show you what we've built together..."
+
+Present the actual document sections created so far
+
+- Not a summary, but the real content
+- Shows the document has been growing throughout
+
+Ask:
+"Looking at this, what stands out as most important to you?"
+"Is there anything critical we haven't explored?"
+"Does this capture your vision?"
+
+Based on their response:
+
+- Refine sections that need more depth
+- Add any missing critical elements
+- Remove or simplify sections that don't matter
+- Ensure the document fits THEIR needs, not a template</action>
+
+<action>Make final refinements based on feedback</action>
+<template-output>final_refinements</template-output>
+
+<action>Create executive summary that captures the essence</action>
+<template-output>executive_summary</template-output>
+</step>
+<step n="9" goal="Complete and save the product brief">
+<action>The document has been building throughout our conversation
+Now ensure it's complete and well-organized</action>
+
+<check if="research documents were provided">
+  <action>Append summary of incorporated research</action>
+  <template-output>supporting_materials</template-output>
+</check>
+
+<action>Ensure the document structure makes sense for what was discovered:
+
+- Hobbyist projects might be 2-3 pages focused on problem/solution/features
+- Startup ventures might be 5-7 pages with market analysis and metrics
+- Enterprise briefs might be 10+ pages with full strategic context
+
+The document should reflect their world, not force their world into a template</action>
+
+<ask>Your product brief is ready! Would you like to:
+
+1. Review specific sections together
+2. Make any final adjustments
+3. Save and move forward
+
+What feels right?</ask>
+
+<action>Make any requested refinements</action>
+<template-output>final_document</template-output>
 </step>
 
-<step n="16" goal="Update status file on completion" tag="workflow-status">
 <check if="standalone_mode != true">
   <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
   <action>Find workflow_status key "product-brief"</action>
@@ -299,34 +502,23 @@ This brief will serve as the primary input for creating the Product Requirements
 
 <output>**✅ Product Brief Complete, {user_name}!**
 
-**Brief Document:**
+Your product vision has been captured in a document that reflects what matters most for your {{context_type}} project.
 
-- Product brief saved to {output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md
+**Document saved:** {output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md
 
 {{#if standalone_mode != true}}
-**Status Updated:**
+**What's next:** {{next_workflow}} ({{next_agent}} agent)
 
-- Progress tracking updated: product-brief marked complete
+The next phase will take your brief and create the detailed planning artifacts needed for implementation.
-- Next workflow: {{next_workflow}}
-  {{else}}
-  **Note:** Running in standalone mode (no progress tracking)
-  {{/if}}
-
-**Next Steps:**
-
-{{#if standalone_mode != true}}
-
-- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
-- **Optional:** Gather additional stakeholder input or run research workflows before proceeding
-
-Check status anytime with: `workflow-status`
 {{else}}
-Since no workflow is in progress:
+**Next steps:**
 
-- Refer to the BMM workflow guide if unsure what to do next
+- Run `workflow-init` to set up guided workflow tracking
-- Or run `workflow-init` to create a workflow path and get guided next steps
+- Or proceed directly to the PRD workflow if you know your path
   {{/if}}
-  </output>
+
-  </step>
+Remember: This brief captures YOUR vision. It grew from our conversation, not from a rigid template. It's ready to guide the next phase of bringing your idea to life.
+</output>
+</step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/product-brief/template.md

@@ -2,7 +2,7 @@
 
 **Date:** {{date}}
 **Author:** {{user_name}}
-**Status:** Draft for PM Review
+**Context:** {{context_type}}
 
 ---
 
@@ -12,154 +12,170 @@
 
 ---
 
-## Problem Statement
+## Core Vision
+
+### Problem Statement
 
 {{problem_statement}}
 
----
+{{#if problem_impact}}
 
-## Proposed Solution
+### Problem Impact
+
+{{problem_impact}}
+{{/if}}
+
+{{#if existing_solutions_gaps}}
+
+### Why Existing Solutions Fall Short
+
+{{existing_solutions_gaps}}
+{{/if}}
+
+### Proposed Solution
 
 {{proposed_solution}}
 
+{{#if key_differentiators}}
+
+### Key Differentiators
+
+{{key_differentiators}}
+{{/if}}
+
 ---
 
 ## Target Users
 
-### Primary User Segment
+### Primary Users
 
 {{primary_user_segment}}
 
-### Secondary User Segment
+{{#if secondary_user_segment}}
+
+### Secondary Users
 
 {{secondary_user_segment}}
+{{/if}}
+
+{{#if user_journey}}
+
+### User Journey
+
+{{user_journey}}
+{{/if}}
 
 ---
 
-## Goals and Success Metrics
+{{#if success_metrics}}
+
+## Success Metrics
+
+{{success_metrics}}
+
+{{#if business_objectives}}
 
 ### Business Objectives
 
 {{business_objectives}}
+{{/if}}
 
-### User Success Metrics
+{{#if key_performance_indicators}}
 
-{{user_success_metrics}}
+### Key Performance Indicators
-
-### Key Performance Indicators (KPIs)
 
 {{key_performance_indicators}}
-
+{{/if}}
----
+{{/if}}
-
-## Strategic Alignment and Financial Impact
-
-### Financial Impact
-
-{{financial_impact}}
-
-### Company Objectives Alignment
-
-{{company_objectives_alignment}}
-
-### Strategic Initiatives
-
-{{strategic_initiatives}}
 
 ---
 
 ## MVP Scope
 
-### Core Features (Must Have)
+### Core Features
 
 {{core_features}}
 
+{{#if out_of_scope}}
+
 ### Out of Scope for MVP
 
 {{out_of_scope}}
+{{/if}}
+
+{{#if mvp_success_criteria}}
 
 ### MVP Success Criteria
 
 {{mvp_success_criteria}}
+{{/if}}
+
+{{#if future_vision_features}}
+
+### Future Vision
+
+{{future_vision_features}}
+{{/if}}
 
 ---
 
-## Post-MVP Vision
+{{#if market_analysis}}
 
-### Phase 2 Features
+## Market Context
 
-{{phase_2_features}}
+{{market_analysis}}
+{{/if}}
 
-### Long-term Vision
+{{#if financial_considerations}}
 
-{{long_term_vision}}
+## Financial Considerations
 
-### Expansion Opportunities
+{{financial_considerations}}
+{{/if}}
 
-{{expansion_opportunities}}
+{{#if technical_preferences}}
+
+## Technical Preferences
+
+{{technical_preferences}}
+{{/if}}
+
+{{#if organizational_context}}
+
+## Organizational Context
+
+{{organizational_context}}
+{{/if}}
+
+{{#if risks_and_assumptions}}
+
+## Risks and Assumptions
+
+{{risks_and_assumptions}}
+{{/if}}
+
+{{#if timeline_constraints}}
+
+## Timeline
+
+{{timeline_constraints}}
+{{/if}}
+
+{{#if supporting_materials}}
+
+## Supporting Materials
+
+{{supporting_materials}}
+{{/if}}
 
 ---
 
-## Technical Considerations
+_This Product Brief captures the vision and requirements for {{project_name}}._
 
-### Platform Requirements
+_It was created through collaborative discovery and reflects the unique needs of this {{context_type}} project._
 
-{{platform_requirements}}
+{{#if next_workflow}}
-
+_Next: {{next_workflow}} will transform this brief into detailed planning artifacts._
-### Technology Preferences
+{{else}}
-
+_Next: Use the PRD workflow to create detailed product requirements from this brief._
-{{technology_preferences}}
+{{/if}}
-
-### Architecture Considerations
-
-{{architecture_considerations}}
-
----
-
-## Constraints and Assumptions
-
-### Constraints
-
-{{constraints}}
-
-### Key Assumptions
-
-{{key_assumptions}}
-
----
-
-## Risks and Open Questions
-
-### Key Risks
-
-{{key_risks}}
-
-### Open Questions
-
-{{open_questions}}
-
-### Areas Needing Further Research
-
-{{research_areas}}
-
----
-
-## Appendices
-
-### A. Research Summary
-
-{{research_summary}}
-
-### B. Stakeholder Input
-
-{{stakeholder_input}}
-
-### C. References
-
-{{references}}
-
----
-
-_This Product Brief serves as the foundational input for Product Requirements Document (PRD) creation._
-
-_Next Steps: Handoff to Product Manager for PRD development using the `workflow prd` command._

src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml

@@ -19,6 +19,20 @@ recommended_inputs:
   - competitive_analysis: "Competitive analysis (optional)"
   - initial_ideas: "Initial product ideas or notes (optional)"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief"
 template: "{installed_path}/template.md"

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md

@@ -12,6 +12,24 @@
 
 <critical>DOCUMENT OUTPUT: Professional, specific, actionable UX design decisions WITH RATIONALE. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
+## 📚 Input Document Discovery
+
+This workflow requires: PRD or product brief, and may reference epics/stories, brainstorming documents, or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
 <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml

@@ -23,6 +23,28 @@ prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
 brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
 brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
 instructions: "{installed_path}/instructions.md"

src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md

@@ -14,6 +14,24 @@
 
 <critical>DOCUMENT OUTPUT: Concise, clear, actionable game design specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
+## Input Document Discovery
+
+This workflow requires: game brief, and may reference market research or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <step n="0" goal="Validate workflow and extract project configuration">
 
 <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">

src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml

@@ -30,6 +30,20 @@ recommended_inputs:
   - narrative_design: "{output_folder}/narrative-design.md"
   - market_research: "{output_folder}/market-research.md"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  game_brief:
+    whole: "{output_folder}/*game-brief*.md"
+    sharded: "{output_folder}/*game-brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:

src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md

@@ -1,117 +1,349 @@
-# PRD Workflow Validation Checklist
+# PRD + Epics + Stories Validation Checklist
 
-**Purpose**: Validate PRD workflow outputs are complete, consistent, and ready for next phase.
+**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
 
-**Scope**: Levels 2-4 software projects
+**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
 
-**Expected Outputs**: PRD.md, epics.md, updated bmm-workflow-status.md
+**Expected Outputs**:
+
+- PRD.md with complete requirements
+- epics.md with detailed epic and story breakdown
+- Updated bmm-workflow-status.yaml
 
 ---
 
-## 1. Output Files Exist
+## 1. PRD Document Completeness
 
-- [ ] PRD.md created in output folder
+### Core Sections Present
-- [ ] epics.md created in output folder (separate file)
+
-- [ ] bmm-workflow-status.md updated
+- [ ] Executive Summary with vision alignment
-- [ ] No unfilled {{template_variables}}
+- [ ] Product magic essence clearly articulated
+- [ ] Project classification (type, domain, complexity)
+- [ ] Success criteria defined
+- [ ] Product scope (MVP, Growth, Vision) clearly delineated
+- [ ] Functional requirements comprehensive and numbered
+- [ ] Non-functional requirements (when applicable)
+- [ ] References section with source documents
+
+### Project-Specific Sections
+
+- [ ] **If complex domain:** Domain context and considerations documented
+- [ ] **If innovation:** Innovation patterns and validation approach documented
+- [ ] **If API/Backend:** Endpoint specification and authentication model included
+- [ ] **If Mobile:** Platform requirements and device features documented
+- [ ] **If SaaS B2B:** Tenant model and permission matrix included
+- [ ] **If UI exists:** UX principles and key interactions documented
+
+### Quality Checks
+
+- [ ] No unfilled template variables ({{variable}})
+- [ ] All variables properly populated with meaningful content
+- [ ] Product magic woven throughout (not just stated once)
+- [ ] Language is clear, specific, and measurable
+- [ ] Project type correctly identified and sections match
+- [ ] Domain complexity appropriately addressed
 
 ---
 
-## 2. PRD.md Core Quality
+## 2. Functional Requirements Quality
 
-### Requirements Coverage
+### FR Format and Structure
 
-- [ ] Functional requirements describe WHAT capabilities (not HOW to implement)
+- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
-- [ ] Each FR has unique identifier (FR001, FR002, etc.)
+- [ ] FRs describe WHAT capabilities, not HOW to implement
-- [ ] Non-functional requirements (if any) have business justification
+- [ ] FRs are specific and measurable
-- [ ] Requirements are testable and verifiable
+- [ ] FRs are testable and verifiable
+- [ ] FRs focus on user/business value
+- [ ] No technical implementation details in FRs (those belong in architecture)
 
-### User Journeys
+### FR Completeness
 
-- [ ] User journeys reference specific FR numbers
+- [ ] All MVP scope features have corresponding FRs
-- [ ] Journeys show complete user paths through system
+- [ ] Growth features documented (even if deferred)
-- [ ] Success outcomes are clear
+- [ ] Vision features captured for future reference
+- [ ] Domain-mandated requirements included
+- [ ] Innovation requirements captured with validation needs
+- [ ] Project-type specific requirements complete
 
-### Strategic Focus
+### FR Organization
 
-- [ ] PRD focuses on WHAT and WHY (not technical HOW)
+- [ ] FRs organized by capability/feature area (not by tech stack)
-- [ ] No specific technology choices in PRD (those belong in technical-decisions.md)
+- [ ] Related FRs grouped logically
-- [ ] Goals are outcome-focused, not implementation-focused
+- [ ] Dependencies between FRs noted when critical
+- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
 
 ---
 
-## 3. epics.md Story Quality
+## 3. Epics Document Completeness
 
-### Story Format
+### Required Files
 
-- [ ] All stories follow user story format: "As a [role], I want [capability], so that [benefit]"
+- [ ] epics.md exists in output folder
-- [ ] Each story has numbered acceptance criteria
-- [ ] Prerequisites/dependencies explicitly stated
-
-### Story Sequencing (CRITICAL)
-
-- [ ] **Epic 1 establishes foundation** (infrastructure, initial deployable functionality)
-  - Exception noted if adding to existing app
-- [ ] **Vertical slices**: Each story delivers complete, testable functionality (not horizontal layers)
-- [ ] **No forward dependencies**: No story depends on work from a LATER story or epic
-- [ ] Stories are sequentially ordered within each epic
-- [ ] Each story leaves system in working state
-
-### Coverage
-
-- [ ] All FRs from PRD.md are covered by stories in epics.md
 - [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+- [ ] All epics have detailed breakdown sections
+
+### Epic Quality
+
+- [ ] Each epic has clear goal and value proposition
+- [ ] Each epic includes complete story breakdown
+- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
+- [ ] Each story has numbered acceptance criteria
+- [ ] Prerequisites/dependencies explicitly stated per story
+- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
 
 ---
 
-## 4. Cross-Document Consistency
+## 4. FR Coverage Validation (CRITICAL)
 
-- [ ] Epic titles consistent between PRD.md and epics.md
+### Complete Traceability
-- [ ] FR references in user journeys exist in requirements section
+
-- [ ] Terminology consistent across documents
+- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
+- [ ] Each story references relevant FR numbers
+- [ ] No orphaned FRs (requirements without stories)
+- [ ] No orphaned stories (stories without FR connection)
+- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
+
+### Coverage Quality
+
+- [ ] Stories sufficiently decompose FRs into implementable units
+- [ ] Complex FRs broken into multiple stories appropriately
+- [ ] Simple FRs have appropriately scoped single stories
+- [ ] Non-functional requirements reflected in story acceptance criteria
+- [ ] Domain requirements embedded in relevant stories
+
+---
+
+## 5. Story Sequencing Validation (CRITICAL)
+
+### Epic 1 Foundation Check
+
+- [ ] **Epic 1 establishes foundational infrastructure**
+- [ ] Epic 1 delivers initial deployable functionality
+- [ ] Epic 1 creates baseline for subsequent epics
+- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
+
+### Vertical Slicing
+
+- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
+- [ ] No "build database" or "create UI" stories in isolation
+- [ ] Stories integrate across stack (data + logic + presentation when applicable)
+- [ ] Each story leaves system in working/deployable state
+
+### No Forward Dependencies
+
+- [ ] **No story depends on work from a LATER story or epic**
+- [ ] Stories within each epic are sequentially ordered
+- [ ] Each story builds only on previous work
+- [ ] Dependencies flow backward only (can reference earlier stories)
+- [ ] Parallel tracks clearly indicated if stories are independent
+
+### Value Delivery Path
+
+- [ ] Each epic delivers significant end-to-end value
+- [ ] Epic sequence shows logical product evolution
+- [ ] User can see value after each epic completion
+- [ ] MVP scope clearly achieved by end of designated epics
+
+---
+
+## 6. Scope Management
+
+### MVP Discipline
+
+- [ ] MVP scope is genuinely minimal and viable
+- [ ] Core features list contains only true must-haves
+- [ ] Each MVP feature has clear rationale for inclusion
+- [ ] No obvious scope creep in "must-have" list
+
+### Future Work Captured
+
+- [ ] Growth features documented for post-MVP
+- [ ] Vision features captured to maintain long-term direction
+- [ ] Out-of-scope items explicitly listed
+- [ ] Deferred features have clear reasoning for deferral
+
+### Clear Boundaries
+
+- [ ] Stories marked as MVP vs Growth vs Vision
+- [ ] Epic sequencing aligns with MVP → Growth progression
+- [ ] No confusion about what's in vs out of initial scope
+
+---
+
+## 7. Research and Context Integration
+
+### Source Document Integration
+
+- [ ] **If product brief exists:** Key insights incorporated into PRD
+- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
+- [ ] **If research documents exist:** Research findings inform requirements
+- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
+- [ ] All source documents referenced in PRD References section
+
+### Research Continuity to Architecture
+
+- [ ] Domain complexity considerations documented for architects
+- [ ] Technical constraints from research captured
+- [ ] Regulatory/compliance requirements clearly stated
+- [ ] Integration requirements with existing systems documented
+- [ ] Performance/scale requirements informed by research data
+
+### Information Completeness for Next Phase
+
+- [ ] PRD provides sufficient context for architecture decisions
+- [ ] Epics provide sufficient detail for technical design
+- [ ] Stories have enough acceptance criteria for implementation
+- [ ] Non-obvious business rules documented
+- [ ] Edge cases and special scenarios captured
+
+---
+
+## 8. Cross-Document Consistency
+
+### Terminology Consistency
+
+- [ ] Same terms used across PRD and epics for concepts
+- [ ] Feature names consistent between documents
+- [ ] Epic titles match between PRD and epics.md
 - [ ] No contradictions between PRD and epics
 
----
+### Alignment Checks
 
-## 5. Readiness for Next Phase
+- [ ] Success metrics in PRD align with story outcomes
-
+- [ ] Product magic articulated in PRD reflected in epic goals
-**Adapt based on project level from bmm-workflow-status.md:**
+- [ ] Technical preferences in PRD align with story implementation hints
-
+- [ ] Scope boundaries consistent across all documents
-### If Level 2:
-
-- [ ] PRD provides sufficient context for tech-spec workflow (lightweight solutioning)
-- [ ] Epic structure supports 5-15 story implementation scope
-
-### If Level 3-4:
-
-- [ ] PRD provides sufficient context for create-architecture workflow
-- [ ] Epic structure supports phased delivery approach
-- [ ] Clear value delivery path through epic sequence
 
 ---
 
-## 6. Critical Failures (Auto-Fail)
+## 9. Readiness for Implementation
 
-- [ ] ❌ **No epics.md file** (two-file output is required)
+### Architecture Readiness (Next Phase)
-- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core principle)
+
-- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
+- [ ] PRD provides sufficient context for architecture workflow
+- [ ] Technical constraints and preferences documented
+- [ ] Integration points identified
+- [ ] Performance/scale requirements specified
+- [ ] Security and compliance needs clear
+
+### Development Readiness
+
+- [ ] Stories are specific enough to estimate
+- [ ] Acceptance criteria are testable
+- [ ] Technical unknowns identified and flagged
+- [ ] Dependencies on external systems documented
+- [ ] Data requirements specified
+
+### Level-Appropriate Detail
+
+**If Level 2:**
+
+- [ ] PRD supports lightweight tech-spec workflow
+- [ ] 5-15 story scope reasonable for project size
+- [ ] Complexity appropriate for small team/solo dev
+
+**If Level 3-4:**
+
+- [ ] PRD supports full architecture workflow
+- [ ] Epic structure supports phased delivery
+- [ ] Scope appropriate for team-based development
+- [ ] Clear value delivery through epic sequence
+
+---
+
+## 10. Quality and Polish
+
+### Writing Quality
+
+- [ ] Language is clear and free of jargon (or jargon is defined)
+- [ ] Sentences are concise and specific
+- [ ] No vague statements ("should be fast", "user-friendly")
+- [ ] Measurable criteria used throughout
+- [ ] Professional tone appropriate for stakeholder review
+
+### Document Structure
+
+- [ ] Sections flow logically
+- [ ] Headers and numbering consistent
+- [ ] Cross-references accurate (FR numbers, section references)
+- [ ] Formatting consistent throughout
+- [ ] Tables/lists formatted properly
+
+### Completeness Indicators
+
+- [ ] No [TODO] or [TBD] markers remain
+- [ ] No placeholder text
+- [ ] All sections have substantive content
+- [ ] Optional sections either complete or omitted (not half-done)
+
+---
+
+## Critical Failures (Auto-Fail)
+
+If ANY of these are true, validation FAILS:
+
+- [ ] ❌ **No epics.md file exists** (two-file output required)
+- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
+- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
 - [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
-- [ ] ❌ **Technical decisions in PRD** (should be in technical-decisions.md)
 - [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
-- [ ] ❌ **User journeys don't reference FR numbers** (missing traceability)
+- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
+- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
+- [ ] ❌ **Template variables unfilled** (incomplete document)
 
 ---
 
-## Validation Notes
+## Validation Summary
 
-**Document any findings:**
+**Total Validation Points:** ~85
 
-- Strengths:
+### Scoring Guide
-- Issues to address:
-- Recommended actions:
 
-**Ready for next phase?** [Yes / No - explain]
+- **Pass Rate ≥ 95% (81+/85):** ✅ EXCELLENT - Ready for architecture phase
+- **Pass Rate 85-94% (72-80/85):** ⚠️ GOOD - Minor fixes needed
+- **Pass Rate 70-84% (60-71/85):** ⚠️ FAIR - Important issues to address
+- **Pass Rate < 70% (<60/85):** ❌ POOR - Significant rework required
+
+### Critical Issue Threshold
+
+- **0 Critical Failures:** Proceed to fixes
+- **1+ Critical Failures:** STOP - Must fix critical issues first
 
 ---
 
-_Adapt this checklist based on actual outputs. Not all sections may apply to every project._
+## Validation Execution Notes
+
+**When validating:**
+
+1. **Load ALL documents:**
+   - PRD.md (required)
+   - epics.md (required)
+   - product-brief.md (if exists)
+   - domain-brief.md (if exists)
+   - research documents (if referenced)
+
+2. **Validate in order:**
+   - Check critical failures first (immediate stop if any found)
+   - Verify PRD completeness
+   - Verify epics completeness
+   - Cross-reference FR coverage (most important)
+   - Check sequencing (second most important)
+   - Validate research integration
+   - Check polish and quality
+
+3. **Report findings:**
+   - List critical failures prominently
+   - Group issues by severity
+   - Provide specific line numbers/sections
+   - Suggest concrete fixes
+   - Highlight what's working well
+
+4. **Provide actionable next steps:**
+   - If validation passes: "Ready for architecture workflow"
+   - If minor issues: "Fix [X] items then re-validate"
+   - If major issues: "Rework [sections] then re-validate"
+   - If critical failures: "Must fix critical items before proceeding"
+
+---
+
+**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.

src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md

@@ -0,0 +1,395 @@
+# Epic and Story Decomposition - Bite-Sized Implementation Planning
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow transforms requirements into BITE-SIZED STORIES for limited context agents</critical>
+<critical>EVERY story must be completable by a single limited context window dev agent in one session</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+<critical>LIVING DOCUMENT: Write to epics.md continuously as you work - never wait until the end</critical>
+
+<workflow>
+
+<step n="0" goal="Load context and requirements">
+<action>Welcome the {user_name} to the project inception high level epic and story planning.
+
+Load required documents:
+
+1. PRD.md (must exist - fuzzy match on name, might be a folder with an index and smaller sharded files also)
+2. domain-brief.md (if exists)
+3. product-brief.md (if exists)
+
+Extract from PRD:
+
+- Functional requirements
+- Non-functional requirements
+- Domain considerations
+- Project type
+- MVP scope vs growth features
+
+If continuing from PRD workflow:
+"Great! Now let's break down your requirements into actionable epics and bite-sized stories that development agents can implement independently."
+
+If starting fresh:
+"I'll help you transform your PRD into organized epics with implementable stories. Each story will be small enough for a single dev agent to complete in one session."</action>
+</step>
+
+<step n="1" goal="Form epics from natural groupings">
+<action>Transform requirements into epics organically
+
+INTENT: Find natural boundaries that make sense for THIS product
+
+Look at the requirements and find patterns:
+
+- Features that work together
+- User journeys that connect
+- Technical systems that relate
+- Business capabilities that group
+- Domain requirements that cluster (compliance, validation, etc.)
+
+Examples of natural epic formation:
+
+- Auth features → "User Management" epic
+- Payment features → "Monetization" epic
+- Social features → "Community" epic
+- Admin features → "Administration" epic
+- Compliance requirements → "Regulatory Compliance" epic
+- API endpoints → "API Infrastructure" epic
+
+But let the product guide you - don't force standard patterns
+
+Each epic should:
+
+- Have a clear business goal
+- Be independently valuable
+- Contain 3-8 related features
+- Be completable in 1-2 sprints
+
+Name epics based on value, not technical components:
+GOOD: "User Onboarding", "Content Discovery", "Team Collaboration"
+NOT: "Database", "Frontend", "API"
+
+If domain considerations exist:
+
+- Create dedicated compliance/validation epics
+- Note special expertise needed per epic
+- Flag epics with regulatory dependencies
+
+Present epic groupings conversationally:
+"Based on your requirements, I see these natural epic groupings:
+
+1. [Epic Name] - [Brief description]
+2. [Epic Name] - [Brief description]
+3. [Epic Name] - [Brief description]
+
+Does this organization make sense for how you think about the product?"</action>
+
+<template-output>epics_structure</template-output>
+</step>
+
+<step n="2" goal="Decompose into bite-sized stories">
+<critical>Small vertical sliced small stories are best for agentic dumb developers to implement without forgetting things</critical>
+
+<action>Break each epic into small, implementable stories
+
+INTENT: Create stories that one dev agent can complete independently
+
+For each epic, decompose into stories that are:
+
+- Small enough for single context window
+- Clear enough for autonomous implementation
+- Independent enough to develop in parallel when possible
+- Specific enough to have clear acceptance criteria
+
+GOOD story examples:
+
+- "Create login API endpoint that accepts email/password and returns JWT"
+- "Build user profile component with avatar upload to S3"
+- "Add password reset email template and sending logic"
+- "Implement rate limiting on auth endpoints (5 attempts per minute)"
+- "Create HIPAA-compliant audit log for patient data access"
+- "Build FDA 21 CFR Part 11 electronic signature component"
+
+BAD story examples:
+
+- "Build complete authentication system" (too big)
+- "Handle user management" (too vague)
+- "Make it secure" (not specific)
+- "Integrate everything" (requires multiple contexts)
+
+Story format:
+"As a [user type], I want [specific feature], so that [clear value]"
+
+Technical notes to include:
+
+- Affected files/components if known
+- Required endpoints/methods
+- Data structures needed
+- Specific validation rules
+- Compliance requirements if applicable
+- Dependencies on other stories
+
+Domain-aware story creation:
+
+- For healthcare: Include specific regulations per story
+- For fintech: Note PCI/security requirements per story
+- For govtech: Flag accessibility needs per story
+- For aerospace: Include safety/validation requirements
+
+Check each story:
+
+- Can this be explained in <1000 words?
+- Can one agent complete without another's output?
+- Is the scope crystal clear?
+- Are success criteria obvious?
+- Are domain requirements specified?
+
+If too big → split into smaller stories
+If too vague → add specifics
+If dependent → note the dependency clearly
+If domain-critical → flag compliance needs</action>
+
+<template-output>epic_1_stories</template-output>
+<template-output>epic_2_stories</template-output>
+<template-output>epic_3_stories</template-output>
+
+<!-- Continue for each epic discovered -->
+</step>
+
+<step n="3" goal="Sequence for smart implementation">
+<action>Order stories for successful development
+
+INTENT: Create a logical flow that minimizes blockers and maximizes progress
+
+Consider dependencies:
+TECHNICAL:
+
+- Authentication before protected features
+- Data models before business logic
+- Core features before enhancements
+- API before frontend that uses it
+
+DOMAIN:
+
+- Compliance infrastructure before features
+- Validation framework before clinical features
+- Audit logging before financial transactions
+- Safety systems before operational features
+
+PRACTICAL:
+
+- What gives visible progress early?
+- What reduces risk soonest?
+- What enables parallel work?
+- What delivers value fastest?
+
+Create implementation phases:
+
+Phase 1 - Foundation:
+
+- Core data models
+- Authentication/authorization
+- Basic infrastructure
+- Essential APIs
+- Compliance foundation (if domain requires)
+
+Phase 2 - Core Features:
+
+- MVP functionality
+- Key user flows
+- Basic UI/UX
+- Critical integrations
+- Domain validations (if applicable)
+
+Phase 3 - Enhancement:
+
+- Polish and refinement
+- Additional features
+- Performance optimization
+- Extended functionality
+- Advanced compliance features
+
+Phase 4 - Growth:
+
+- Analytics and monitoring
+- Advanced features
+- Scaling preparations
+- Nice-to-have additions
+
+For complex domains, add gates:
+
+- "Gate: Security audit before payment processing"
+- "Gate: Clinical validation before patient features"
+- "Gate: Compliance review before launch"
+
+Present the sequencing conversationally:
+"Here's a smart implementation order:
+
+**Phase 1 (Foundation) - Week 1-2:**
+
+- Story 1.1: [Description]
+- Story 1.2: [Description] (can parallel with 1.1)
+- Story 1.3: [Description] (depends on 1.1)
+
+**Phase 2 (Core) - Week 3-4:**
+[Continue...]
+
+This gives you something working by [milestone] and allows [X] stories to run in parallel."</action>
+
+<template-output>implementation_sequence</template-output>
+<template-output>development_phases</template-output>
+<template-output>dependency_graph</template-output>
+</step>
+
+<step n="4" goal="Validate story sizing and clarity">
+<action>Review all stories for dev agent compatibility
+
+Run through each story and verify:
+
+SIZE CHECK:
+
+- Story description < 500 words
+- Clear inputs and outputs defined
+- Single responsibility principle
+- No hidden complexity
+
+CLARITY CHECK:
+
+- Acceptance criteria explicit
+- Technical approach clear
+- No ambiguous requirements
+- Success measurable
+
+DEPENDENCY CHECK:
+
+- Dependencies documented
+- Can start with clear inputs
+- Outputs well-defined
+- Parallel opportunities noted
+
+DOMAIN CHECK (if applicable):
+
+- Compliance requirements stated
+- Validation criteria defined
+- Regulatory references included
+- Special expertise noted
+
+If any issues found:
+"Story [X] seems too large. Let me split it:
+
+- [Smaller story 1]
+- [Smaller story 2]"
+
+"Story [Y] needs clarification on [aspect]. How should we handle [specific question]?"
+
+Final validation:
+"All stories are now sized for 200k context limits.
+
+- Total stories: [count]
+- Can run in parallel: [count]
+- Sequential dependencies: [count]
+- Estimated completion: [timeframe]"</action>
+
+<template-output>story_validation</template-output>
+</step>
+
+<step n="5" goal="Create development guidance">
+<action>Add practical guidance for implementation teams
+
+Create quick reference for development:
+
+GETTING STARTED:
+"Start with Phase 1 stories - multiple can run in parallel.
+Key files to create first: [list]
+Recommended agent allocation: [suggestion]"
+
+DOMAIN GUIDANCE (if applicable):
+"Critical compliance checkpoints:
+
+- After story [X]: Run [validation]
+- Before story [Y]: Review [regulation]
+- Throughout: Maintain [audit trail]"
+
+TECHNICAL NOTES:
+"Architecture decisions needed:
+
+- [Decision 1] affects stories [A, B, C]
+- [Decision 2] blocks story [D]
+
+Consider these patterns:
+
+- [Pattern] for [epic]
+- [Pattern] for [requirement]"
+
+RISK MITIGATION:
+"Watch out for:
+
+- [Risk] in story [X]
+- [Complexity] in epic [Y]
+- [Dependency] between [A] and [B]"
+
+SUCCESS METRICS:
+"You'll know Phase 1 is complete when:
+
+- [Measurable outcome]
+- [Testable feature]
+- [Validation passed]"</action>
+
+<template-output>implementation_guidance</template-output>
+</step>
+
+<step n="6" goal="Finalize and prepare handoff">
+<action>Complete the epics document and prepare for development
+
+Review what we've created:
+"We've successfully decomposed your requirements into:
+
+- [x] epics
+- [Y] total stories
+- [Z] phases of development
+
+Every story is sized for a single dev agent to complete independently."
+
+Highlight key achievements:
+
+- Stories respect 200k context limit
+- Dependencies clearly mapped
+- Domain requirements integrated
+- Parallel development enabled
+
+Save completed epics.md with:
+
+- Full epic descriptions
+- All stories with acceptance criteria
+- Implementation sequence
+- Development phases
+- Dependency notes
+- Domain compliance requirements (if applicable)</action>
+
+<output>**✅ Epic Decomposition Complete, {user_name}!**
+
+Your requirements are now organized into **{epic_count} epics** with **{story_count} bite-sized stories**.
+
+**Created:**
+
+- **epics.md** - Complete epic breakdown with implementable stories
+
+**Key Stats:**
+
+- Average story size: Fits in 200k context
+- Parallel stories: {parallel_count} can run simultaneously
+- Sequential chains: {sequential_count} dependency chains
+- Estimated velocity: {velocity_estimate}
+
+**Next Steps:**
+
+1. Review epics.md for the complete breakdown
+2. Start Phase 1 implementation with parallel stories
+3. Use story IDs for tracking progress
+
+Each story is crafted for a single dev agent to complete autonomously. No monoliths, no confusion, just clear implementation paths.
+
+Ready to begin development with any story marked "can start immediately"!</output>
+</step>
+
+</workflow>

src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml

@@ -0,0 +1,43 @@
+# Epic and Story Decomposition Workflow
+name: create-epics-and-stories
+description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+project_name: "{config_source}:project_name"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/epics-template.md"
+
+# Input files (from parent PRD workflow)
+prd_file: "{output_folder}/PRD.md"
+
+# Output files
+default_output_file: "{output_folder}/epics.md"
+
+# Optional input documents
+recommended_inputs:
+  - prd: "{output_folder}/PRD.md"
+  - product_brief: "{output_folder}/product-brief.md"
+  - domain_brief: "{output_folder}/domain-brief.md"
+
+standalone: true
+
+web_bundle:
+  name: "create-epics-and-stories"
+  description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents"
+  author: "BMad"
+  instructions: "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md"
+  template: "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md"
+  web_bundle_files:
+    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md"

src/modules/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv

@@ -0,0 +1,13 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"

src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md

@@ -1,47 +1,51 @@
-# PRD Workflow Instructions
+# PRD Workflow - Intent-Driven Product Planning
 
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+<critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
+<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
-<critical>This workflow is for Level 2-4 projects. Level 0-1 use tech-spec workflow.</critical>
+<critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
-<critical>Produces TWO outputs: PRD.md (strategic) and epics.md (tactical implementation)</critical>
+<critical>GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section</critical>
-<critical>TECHNICAL NOTES: If ANY technical details, preferences, or constraints are mentioned during PRD discussions, append them to {technical_decisions_file}. If file doesn't exist, create it from {technical_decisions_template}</critical>
 
-<critical>DOCUMENT OUTPUT: Concise, clear, actionable requirements. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+## 📚 Input Document Discovery
+
+This workflow requires: product brief, and may reference market research or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
 
 <workflow>
 
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
-<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
+<action>Check if {status_file} exists</action>
 
-<check if="status file not found">
+<action if="status file not found">Set standalone_mode = true</action>
-  <output>No workflow status file found. PRD workflow can run standalone or as part of BMM workflow path.</output>
-  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
-  <check if="continue">
-    <action>Set standalone_mode = true</action>
-  </check>
-  <check if="exit">
-    <action>Exit workflow</action>
-  </check>
-</check>
 
 <check if="status file found">
-  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Load the FULL file: {status_file}</action>
   <action>Parse workflow_status section</action>
   <action>Check status of "prd" workflow</action>
   <action>Get project_level from YAML metadata</action>
   <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 2">
-    <output>**Incorrect Workflow for Level {{project_level}}**
+    <output>**Level {{project_level}} Project - Redirecting**
 
-PRD is for Level 2-4 projects. Level 0-1 should use tech-spec directly.
+Level 0-1 projects use tech-spec workflow for simpler planning.
-
+PRD is for Level 2-4 projects that need comprehensive requirements.</output>
-**Correct workflow:** `tech-spec` (Architect agent)
+<action>Exit and suggest tech-spec workflow</action>
-</output>
-<action>Exit and redirect to tech-spec</action>
 </check>
 
   <check if="prd status is file path (already completed)">
@@ -53,379 +57,367 @@ PRD is for Level 2-4 projects. Level 0-1 should use tech-spec directly.
     </check>
   </check>
 
-  <check if="prd is not the next expected workflow">
-    <output>⚠️ Next expected workflow: {{next_workflow}}. PRD is out of sequence.</output>
-    <ask>Continue with PRD anyway? (y/n)</ask>
-    <check if="n">
-      <output>Exiting. Run {{next_workflow}} instead.</output>
-      <action>Exit workflow</action>
-    </check>
-  </check>
-
 <action>Set standalone_mode = false</action>
 </check>
 </step>
 
-<step n="1" goal="Initialize PRD context">
+<step n="1" goal="Discovery - Project, Domain, and Vision">
+<action>Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT:
+1. Check workflow-status.yaml for project_context (if exists)
+2. Look for existing documents (Product Brief, Domain Brief, research)
+3. Detect project type AND domain complexity
 
-<action>Use {{project_level}} from status data</action>
+Load references:
-<action>Check for existing PRD.md in {output_folder}</action>
+{installed_path}/project-types.csv
+{installed_path}/domain-complexity.csv
 
-<check if="PRD.md exists">
+Through natural conversation:
-  <ask>Found existing PRD.md. Would you like to:
+"Tell me about what you want to build - what problem does it solve and for whom?"
-1. Continue where you left off
+
-2. Modify existing sections
+DUAL DETECTION:
-3. Start fresh (will archive existing file)
+Project type signals: API, mobile, web, CLI, SDK, SaaS
-  </ask>
+Domain complexity signals: medical, finance, government, education, aerospace
-  <action if="option 1">Load existing PRD and skip to first incomplete section</action>
+
-  <action if="option 2">Load PRD and ask which section to modify</action>
+SPECIAL ROUTING:
-  <action if="option 3">Archive existing PRD and start fresh</action>
+If game detected → Suggest game-brief and GDD workflows
+If complex domain detected → Offer domain research options:
+A) Run domain-research workflow (thorough)
+B) Quick web search (basic)
+C) User provides context
+D) Continue with general knowledge
+
+CAPTURE THE MAGIC EARLY with a few questions such as for example: "What excites you most about this product?", "What would make users love this?", "What's the moment that will make people go 'wow'?"
+
+This excitement becomes the thread woven throughout the PRD.</action>
+
+<template-output>vision_alignment</template-output>
+<template-output>project_classification</template-output>
+<template-output>project_type</template-output>
+<template-output>domain_type</template-output>
+<template-output>complexity_level</template-output>
+<check if="complex domain">
+<template-output>domain_context_summary</template-output>
 </check>
-
+<template-output>product_magic_essence</template-output>
-<action>Load PRD template: {prd_template}</action>
+<template-output>product_brief_path</template-output>
-<action>Load epics template: {epics_template}</action>
+<template-output>domain_brief_path</template-output>
-
+<template-output>research_documents</template-output>
-<ask>Do you have a Product Brief? (Strongly recommended for Level 3-4, helpful for Level 2)</ask>
-
-<check if="yes">
-  <action>Load and review product brief: {output_folder}/product-brief.md</action>
-  <action>Extract key elements: problem statement, target users, success metrics, MVP scope, constraints</action>
-</check>
-
-<check if="no and level >= 3">
-  <warning>Product Brief is strongly recommended for Level 3-4 projects. Consider running the product-brief workflow first.</warning>
-  <ask>Continue without Product Brief? (y/n)</ask>
-  <action if="no">Exit to allow Product Brief creation</action>
-</check>
-
 </step>
 
-<step n="2" goal="Goals and Background Context">
+<step n="2" goal="Success Definition">
+<action>Define what winning looks like for THIS specific product
 
-**Goals** - What success looks like for this project
+INTENT: Meaningful success criteria, not generic metrics
 
-<check if="product brief exists">
+Adapt to context:
-  <action>Review goals from product brief and refine for PRD context</action>
+
+- Consumer: User love, engagement, retention
+- B2B: ROI, efficiency, adoption
+- Developer tools: Developer experience, community
+- Regulated: Compliance, safety, validation
+
+Make it specific:
+
+- NOT: "10,000 users"
+- BUT: "100 power users who rely on it daily"
+
+- NOT: "99.9% uptime"
+- BUT: "Zero data loss during critical operations"
+
+Weave in the magic:
+
+- "Success means users experience [that special moment] and [desired outcome]"</action>
+
+<template-output>success_criteria</template-output>
+<check if="business focus">
+<template-output>business_metrics</template-output>
 </check>
-
-<check if="no product brief">
-  <action>Gather goals through discussion with user, use probing questions and converse until you are ready to propose that you have enough information to proceed</action>
-</check>
-
-Create a bullet list of single-line desired outcomes that capture user and project goals.
-
-**Scale guidance:**
-
-- Level 2: 2-3 core goals
-- Level 3: 3-5 strategic goals
-- Level 4: 5-7 comprehensive goals
-
-<template-output>goals</template-output>
-
-**Background Context** - Why this matters now
-
-<check if="product brief exists">
-  <action>Summarize key context from brief without redundancy</action>
-</check>
-
-<check if="no product brief">
-  <action>Gather context through discussion</action>
-</check>
-
-Write 1-2 paragraphs covering:
-
-- What problem this solves and why
-- Current landscape or need
-- Key insights from discovery/brief (if available)
-
-<template-output>background_context</template-output>
-
 </step>
 
-<step n="3" goal="Requirements - Functional and Non-Functional">
+<step n="3" goal="Scope Definition">
+<action>Smart scope negotiation - find the sweet spot
 
-**Functional Requirements** - What the system must do
+The Scoping Game:
 
-Draft functional requirements as numbered items with FR prefix.
+1. "What must work for this to be useful?" → MVP
+2. "What makes it competitive?" → Growth
+3. "What's the dream version?" → Vision
 
-**Scale guidance:**
+Challenge scope creep conversationally:
 
-- Level 2: 8-15 FRs (focused MVP set)
+- "Could that wait until after launch?"
-- Level 3: 12-25 FRs (comprehensive product)
+- "Is that essential for proving the concept?"
-- Level 4: 20-35 FRs (enterprise platform)
 
-**Format:**
+For complex domains:
 
-- FR001: [Clear capability statement]
+- Include compliance minimums in MVP
-- FR002: [Another capability]
+- Note regulatory gates between phases</action>
-
-**Focus on:**
-
-- User-facing capabilities
-- Core system behaviors
-- Integration requirements
-- Data management needs
-
-Group related requirements logically.
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-<template-output>functional_requirements</template-output>
-
-**Non-Functional Requirements** - How the system must perform
-
-Draft non-functional requirements with NFR prefix.
-
-**Scale guidance:**
-
-- Level 2: 1-3 NFRs (critical MVP only)
-- Level 3: 2-5 NFRs (production quality)
-- Level 4: 3-7+ NFRs (enterprise grade)
-
-<template-output>non_functional_requirements</template-output>
 
+<template-output>mvp_scope</template-output>
+<template-output>growth_features</template-output>
+<template-output>vision_features</template-output>
 </step>
 
-<step n="4" goal="User Journeys - scale-adaptive" optional="level == 2">
+<step n="4" goal="Domain-Specific Exploration" optional="true">
+<action>Only if complex domain detected or domain-brief exists
 
-**Journey Guidelines (scale-adaptive):**
+Synthesize domain requirements that will shape everything:
 
-- **Level 2:** 1 simple journey (primary use case happy path)
+- Regulatory requirements
-- **Level 3:** 2-3 detailed journeys (complete flows with decision points)
+- Compliance needs
-- **Level 4:** 3-5 comprehensive journeys (all personas and edge cases)
+- Industry standards
+- Safety/risk factors
+- Required validations
+- Special expertise needed
 
-<check if="level == 2">
+These inform:
-  <ask>Would you like to document a user journey for the primary use case? (recommended but optional)</ask>
+
-  <check if="yes">
+- What features are mandatory
-    Create 1 simple journey showing the happy path.
+- What NFRs are critical
-  </check>
+- How to sequence development
+- What validation is required</action>
+
+<check if="complex domain">
+  <template-output>domain_considerations</template-output>
+</check>
+</step>
+
+<step n="5" goal="Innovation Discovery" optional="true">
+<action>Identify truly novel patterns if applicable
+
+Listen for innovation signals:
+
+- "Nothing like this exists"
+- "We're rethinking how [X] works"
+- "Combining [A] with [B] for the first time"
+
+Explore deeply:
+
+- What makes it unique?
+- What assumption are you challenging?
+- How do we validate it?
+- What's the fallback?
+
+<WebSearch if="novel">{concept} innovations {date}</WebSearch></action>
+
+<check if="innovation detected">
+  <template-output>innovation_patterns</template-output>
+  <template-output>validation_approach</template-output>
+</check>
+</step>
+
+<step n="6" goal="Project-Specific Deep Dive">
+<action>Based on detected project type, dive deep into specific needs
+
+Load project type requirements from CSV and expand naturally.
+
+FOR API/BACKEND:
+
+- Map out endpoints, methods, parameters
+- Define authentication and authorization
+- Specify error codes and rate limits
+- Document data schemas
+
+FOR MOBILE:
+
+- Platform requirements (iOS/Android/both)
+- Device features needed
+- Offline capabilities
+- Store compliance
+
+FOR SAAS B2B:
+
+- Multi-tenant architecture
+- Permission models
+- Subscription tiers
+- Critical integrations
+
+[Continue for other types...]
+
+Always relate back to the product magic:
+"How does [requirement] enhance [the special thing]?"</action>
+
+<template-output>project_type_requirements</template-output>
+
+<!-- Dynamic sections based on project type -->
+<check if="API/Backend project">
+  <template-output>endpoint_specification</template-output>
+  <template-output>authentication_model</template-output>
 </check>
 
-<check if="level >= 3">
+<check if="Mobile project">
-  Map complete user flows with decision points, alternatives, and edge cases.
+  <template-output>platform_requirements</template-output>
+  <template-output>device_features</template-output>
 </check>
 
-<template-output>user_journeys</template-output>
+<check if="SaaS B2B project">
-
+  <template-output>tenant_model</template-output>
-<check if="level >= 3">
+  <template-output>permission_matrix</template-output>
-  <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </check>
-
 </step>
 
-<step n="5" goal="UX and UI Vision - high-level overview" optional="level == 2 and minimal UI">
+<step n="7" goal="UX Principles" optional="true">
+<action>Only if product has a UI
 
-**Purpose:** Capture essential UX/UI information needed for epic and story planning. A dedicated UX workflow will provide deeper design detail later.
+Light touch on UX - not full design:
 
-<check if="level == 2 and minimal UI">
+- Visual personality
-  <action>For backend-heavy or minimal UI projects, keep this section very brief or skip</action>
+- Key interaction patterns
+- Critical user flows
+
+"How should this feel to use?"
+"What's the vibe - professional, playful, minimal?"
+
+Connect to the magic:
+"The UI should reinforce [the special moment] through [design approach]"</action>
+
+<check if="has UI">
+  <template-output>ux_principles</template-output>
+  <template-output>key_interactions</template-output>
 </check>
-
-**Gather high-level UX/UI information:**
-
-1. **UX Principles** (2-4 key principles that guide design decisions)
-   - What core experience qualities matter most?
-   - Any critical accessibility or usability requirements?
-
-2. **Platform & Screens**
-   - Target platforms (web, mobile, desktop)
-   - Core screens/views users will interact with
-   - Key interaction patterns or navigation approach
-
-3. **Design Constraints**
-   - Existing design systems or brand guidelines
-   - Technical UI constraints (browser support, etc.)
-
-<note>Keep responses high-level. Detailed UX planning happens in the UX workflow after PRD completion.</note>
-
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-<template-output>ux_principles</template-output>
-<template-output>ui_design_goals</template-output>
-
 </step>
 
-<step n="6" goal="Epic List - High-level delivery sequence">
+<step n="8" goal="Functional Requirements Synthesis">
+<action>Transform everything discovered into clear functional requirements
 
-**Epic Structure** - Major delivery milestones
+Pull together:
 
-Create high-level epic list showing logical delivery sequence.
+- Core features from scope
+- Domain-mandated features
+- Project-type specific needs
+- Innovation requirements
 
-**Epic Sequencing Rules:**
+Organize by capability, not technology:
 
-1. **Epic 1 MUST establish foundation**
+- User Management (not "auth system")
-   - Project infrastructure (repo, CI/CD, core setup)
+- Content Discovery (not "search algorithm")
-   - Initial deployable functionality
+- Team Collaboration (not "websockets")
-   - Development workflow established
-   - Exception: If adding to existing app, Epic 1 can be first major feature
 
-2. **Subsequent Epics:**
+Each requirement should:
-   - Each delivers significant, end-to-end, fully deployable increment
-   - Build upon previous epics (no forward dependencies)
-   - Represent major functional blocks
-   - Prefer fewer, larger epics over fragmentation
 
-**Scale guidance:**
+- Be specific and measurable
+- Connect to user value
+- Include acceptance criteria
+- Note domain constraints
 
-- Level 2: 1-2 epics, 5-15 stories total
+The magic thread:
-- Level 3: 2-5 epics, 15-40 stories total
+Highlight which requirements deliver the special experience</action>
-- Level 4: 5-10 epics, 40-100+ stories total
-
-**For each epic provide:**
-
-- Epic number and title
-- Single-sentence goal statement
-- Estimated story count
-
-**Example:**
-
-- **Epic 1: Project Foundation & User Authentication**
-- **Epic 2: Core Task Management**
-
-<ask>Review the epic list. Does the sequence make sense? Any epics to add, remove, or resequence?</ask>
-<action>Refine epic list based on feedback</action>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
-
-<template-output>epic_list</template-output>
 
+<template-output>functional_requirements_complete</template-output>
 </step>
 
-<step n="7" goal="Out of Scope - Clear boundaries and future additions">
+<step n="9" goal="Non-Functional Requirements Discovery">
+<action>Only document NFRs that matter for THIS product
 
-**Out of Scope** - What we're NOT doing (now)
+Performance: Only if user-facing impact
+Security: Only if handling sensitive data
+Scale: Only if growth expected
+Accessibility: Only if broad audience
+Integration: Only if connecting systems
 
-Document what is explicitly excluded from this project:
+For each NFR:
 
-- Features/capabilities deferred to future phases
+- Why it matters for THIS product
-- Adjacent problems not being solved
+- Specific measurable criteria
-- Integrations or platforms not supported
+- Domain-driven requirements
-- Scope boundaries that need clarification
 
-This helps prevent scope creep and sets clear expectations.
+Skip categories that don't apply!</action>
-
-<template-output>out_of_scope</template-output>
 
+<!-- Only output sections that were discussed -->
+<check if="performance matters">
+  <template-output>performance_requirements</template-output>
+</check>
+<check if="security matters">
+  <template-output>security_requirements</template-output>
+</check>
+<check if="scale matters">
+  <template-output>scalability_requirements</template-output>
+</check>
+<check if="accessibility matters">
+  <template-output>accessibility_requirements</template-output>
+</check>
+<check if="integration matters">
+  <template-output>integration_requirements</template-output>
+</check>
+<check if="no NFRs discussed">
+  <template-output>no_nfrs</template-output>
+</check>
 </step>
 
-<step n="8" goal="Finalize PRD.md">
+<step n="10" goal="Review PRD and transition to epics">
+<action>Review the PRD we've built together
 
-<action>Review all PRD sections for completeness and consistency</action>
+"Let's review what we've captured:
-<action>Ensure all placeholders are filled</action>
-<action>Save final PRD.md to {default_output_file}</action>
 
-**PRD.md is complete!** Strategic document ready.
+- Vision: [summary]
+- Success: [key metrics]
+- Scope: [MVP highlights]
+- Requirements: [count] functional, [count] non-functional
+- Special considerations: [domain/innovation]
 
-Now we'll create the tactical implementation guide in epics.md.
+Does this capture your product vision?"
 
+After confirmation:
+"Excellent! Now we need to break these requirements into implementable epics and stories.
+
+For the epic breakdown, you have two options:
+
+1. Start a new session focused on epics (recommended for complex projects)
+2. Continue here (I'll transform requirements into epics now)
+
+Which would you prefer?"
+
+If new session:
+"To start epic planning in a new session:
+
+1. Save your work here
+2. Start fresh and run: workflow epics-stories
+3. It will load your PRD and create the epic breakdown
+
+This keeps each session focused and manageable."
+
+If continue:
+"Let's continue with epic breakdown here..."
+[Proceed with epics-stories subworkflow]
+Set project_level and target_scale based on project analysis
+Generate epic_details for the epics breakdown document</action>
+
+<template-output>prd_summary</template-output>
+<template-output>project_level</template-output>
+<template-output>target_scale</template-output>
+<template-output>epic_details</template-output>
 </step>
 
-<step n="9" goal="Epic Details - Full story breakdown in epics.md">
+<step n="11" goal="Complete PRD and suggest next steps">
-
+<template-output>product_magic_summary</template-output>
-<critical>Now we create epics.md - the tactical implementation roadmap</critical>
-<critical>This is a SEPARATE FILE from PRD.md</critical>
-
-<action>Load epics template: {epics_template}</action>
-<action>Initialize epics.md with project metadata</action>
-
-For each epic from the epic list, expand with full story details:
-
-**Epic Expansion Process:**
-
-1. **Expanded Goal** (2-3 sentences)
-   - Describe the epic's objective and value delivery
-   - Explain how it builds on previous work
-
-2. **Story Breakdown**
-
-   **Critical Story Requirements:**
-   - **Vertical slices** - Each story delivers complete, testable functionality
-   - **Sequential** - Stories must be logically ordered within epic
-   - **No forward dependencies** - No story depends on work from a later story/epic
-   - **AI-agent sized** - Completable in single focused session (2-4 hours)
-   - **Value-focused** - Minimize pure enabler stories; integrate technical work into value delivery
-
-   **Story Format:**
-
-   ```
-   **Story [EPIC.N]: [Story Title]**
-
-   As a [user type],
-   I want [goal/desire],
-   So that [benefit/value].
-
-   **Acceptance Criteria:**
-   1. [Specific testable criterion]
-   2. [Another specific criterion]
-   3. [etc.]
-
-   **Prerequisites:** [Any dependencies on previous stories]
-   ```
-
-3. **Story Sequencing Within Epic:**
-   - Start with foundational/setup work if needed
-   - Build progressively toward epic goal
-   - Each story should leave system in working state
-   - Final stories complete the epic's value delivery
-
-**Process each epic:**
-
-<repeat for-each="epic in epic_list">
-
-<ask>Ready to break down {{epic_title}}? (y/n)</ask>
-
-<action>Discuss epic scope and story ideas with user</action>
-<action>Draft story list ensuring vertical slices and proper sequencing</action>
-<action>For each story, write user story format and acceptance criteria</action>
-<action>Verify no forward dependencies exist</action>
-
-<template-output file="epics.md">{{epic_title}}\_details</template-output>
-
-<ask>Review {{epic_title}} stories. Any adjustments needed?</ask>
-
-<action if="yes">Refine stories based on feedback</action>
-
-</repeat>
-
-<action>Save complete epics.md to {epics_output_file}</action>
-
-**Epic Details complete!** Implementation roadmap ready.
-
-</step>
-
-<step n="10" goal="Update status and complete" tag="workflow-status">
 
 <check if="standalone_mode != true">
-  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Load the FULL file: {status_file}</action>
-  <action>Find workflow_status key "prd"</action>
-  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
   <action>Update workflow_status["prd"] = "{default_output_file}"</action>
-  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+  <action>Save file, preserving ALL comments and structure</action>
-
-<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-<action>Determine next agent from path file based on next workflow</action>
 </check>
 
-<output>**✅ PRD Workflow Complete, {user_name}!**
+<output>**✅ PRD Complete, {user_name}!**
 
-**Deliverables Created:**
+Your product requirements are documented and ready for implementation.
 
-1. ✅ bmm-PRD.md - Strategic product requirements document
+**Created:**
-2. ✅ bmm-epics.md - Tactical implementation roadmap with story breakdown
+
+- **PRD.md** - Complete requirements adapted to {project_type} and {domain}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+1. **Epic Breakdown** (Required)
-- **Optional:** Review PRD and epics with stakeholders, or run `create-design` if you have UI requirements
+   Run: `workflow create-epics-and-stories` to decompose requirements into implementable stories
 
-Check status anytime with: `workflow-status`
+2. **UX Design** (If UI exists)
+   Run: `workflow ux-design` for detailed user experience design
 
-Would you like to:
+3. **Architecture** (Recommended)
-
+   Run: `workflow create-architecture` for technical architecture decisions
-1. Review/refine any section
-2. Proceed to next phase
-3. Exit and review documents
-   </output>
 
+The magic of your product - {product_magic_summary} - is woven throughout the PRD and will guide all subsequent work.
+</output>
 </step>
 
 </workflow>

src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md

@@ -1,62 +1,237 @@
-# {{project_name}} Product Requirements Document (PRD)
+# {{project_name}} - Product Requirements Document
 
 **Author:** {{user_name}}
 **Date:** {{date}}
-**Project Level:** {{project_level}}
+**Version:** 1.0
-**Target Scale:** {{target_scale}}
 
 ---
 
-## Goals and Background Context
+## Executive Summary
 
-### Goals
+{{vision_alignment}}
 
-{{goals}}
+### What Makes This Special
 
-### Background Context
+{{product_magic_essence}}
-
-{{background_context}}
 
 ---
 
-## Requirements
+## Project Classification
 
-### Functional Requirements
+**Technical Type:** {{project_type}}
+**Domain:** {{domain_type}}
+**Complexity:** {{complexity_level}}
 
-{{functional_requirements}}
+{{project_classification}}
 
-### Non-Functional Requirements
+{{#if domain_context_summary}}
 
-{{non_functional_requirements}}
+### Domain Context
+
+{{domain_context_summary}}
+{{/if}}
 
 ---
 
-## User Journeys
+## Success Criteria
 
-{{user_journeys}}
+{{success_criteria}}
+
+{{#if business_metrics}}
+
+### Business Metrics
+
+{{business_metrics}}
+{{/if}}
 
 ---
 
-## UX Design Principles
+## Product Scope
+
+### MVP - Minimum Viable Product
+
+{{mvp_scope}}
+
+### Growth Features (Post-MVP)
+
+{{growth_features}}
+
+### Vision (Future)
+
+{{vision_features}}
+
+---
+
+{{#if domain_considerations}}
+
+## Domain-Specific Requirements
+
+{{domain_considerations}}
+
+This section shapes all functional and non-functional requirements below.
+{{/if}}
+
+---
+
+{{#if innovation_patterns}}
+
+## Innovation & Novel Patterns
+
+{{innovation_patterns}}
+
+### Validation Approach
+
+{{validation_approach}}
+{{/if}}
+
+---
+
+{{#if project_type_requirements}}
+
+## {{project_type}} Specific Requirements
+
+{{project_type_requirements}}
+
+{{#if endpoint_specification}}
+
+### API Specification
+
+{{endpoint_specification}}
+{{/if}}
+
+{{#if authentication_model}}
+
+### Authentication & Authorization
+
+{{authentication_model}}
+{{/if}}
+
+{{#if platform_requirements}}
+
+### Platform Support
+
+{{platform_requirements}}
+{{/if}}
+
+{{#if device_features}}
+
+### Device Capabilities
+
+{{device_features}}
+{{/if}}
+
+{{#if tenant_model}}
+
+### Multi-Tenancy Architecture
+
+{{tenant_model}}
+{{/if}}
+
+{{#if permission_matrix}}
+
+### Permissions & Roles
+
+{{permission_matrix}}
+{{/if}}
+{{/if}}
+
+---
+
+{{#if ux_principles}}
+
+## User Experience Principles
 
 {{ux_principles}}
 
----
+### Key Interactions
 
-## User Interface Design Goals
+{{key_interactions}}
-
+{{/if}}
-{{ui_design_goals}}
 
 ---
 
-## Epic List
+## Functional Requirements
 
-{{epic_list}}
+{{functional_requirements_complete}}
-
-> **Note:** Detailed epic breakdown with full story specifications is available in [epics.md](./epics.md)
 
 ---
 
-## Out of Scope
+## Non-Functional Requirements
 
-{{out_of_scope}}
+{{#if performance_requirements}}
+
+### Performance
+
+{{performance_requirements}}
+{{/if}}
+
+{{#if security_requirements}}
+
+### Security
+
+{{security_requirements}}
+{{/if}}
+
+{{#if scalability_requirements}}
+
+### Scalability
+
+{{scalability_requirements}}
+{{/if}}
+
+{{#if accessibility_requirements}}
+
+### Accessibility
+
+{{accessibility_requirements}}
+{{/if}}
+
+{{#if integration_requirements}}
+
+### Integration
+
+{{integration_requirements}}
+{{/if}}
+
+{{#if no_nfrs}}
+_No specific non-functional requirements identified for this project type._
+{{/if}}
+
+---
+
+## Implementation Planning
+
+### Epic Breakdown Required
+
+Requirements must be decomposed into epics and bite-sized stories (200k context limit).
+
+**Next Step:** Run `workflow epics-stories` to create the implementation breakdown.
+
+---
+
+## References
+
+{{#if product_brief_path}}
+
+- Product Brief: {{product_brief_path}}
+  {{/if}}
+  {{#if domain_brief_path}}
+- Domain Brief: {{domain_brief_path}}
+  {{/if}}
+  {{#if research_documents}}
+- Research: {{research_documents}}
+  {{/if}}
+
+---
+
+## Next Steps
+
+1. **Epic & Story Breakdown** - Run: `workflow epics-stories`
+2. **UX Design** (if UI) - Run: `workflow ux-design`
+3. **Architecture** - Run: `workflow create-architecture`
+
+---
+
+_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
+
+_Created through collaborative discovery between {{user_name}} and AI facilitator._

src/modules/bmm/workflows/2-plan-workflows/prd/project-types.csv

@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO GAME WORKFLOWS","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"

src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml

@@ -19,20 +19,30 @@ instructions: "{installed_path}/instructions.md"
 
 # Templates
 prd_template: "{installed_path}/prd-template.md"
-epics_template: "{installed_path}/epics-template.md"
 
 # Output files
-status_file: "{output_folder}/bmm-workflow-status.md"
+status_file: "{output_folder}/bmm-workflow-status.yaml"
 default_output_file: "{output_folder}/PRD.md"
-epics_output_file: "{output_folder}/epics.md"
-technical_decisions_file: "{output_folder}/technical-decisions.md"
-technical_decisions_template: "{project-root}/bmad/bmm/_module-installer/assets/technical-decisions.md"
 
 # Recommended input documents
 recommended_inputs:
   - product_brief: "{output_folder}/product-brief.md"
   - market_research: "{output_folder}/market-research.md"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:
@@ -40,7 +50,15 @@ web_bundle:
   description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
   author: "BMad"
   instructions: "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
+  validation: "bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
   web_bundle_files:
     - "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
     - "bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/epics-template.md"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md"
+    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md"
+  child_workflows:
+    - create-epics-and-stories: "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"

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
+- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
-- [ ] No unfilled {{template_variables}}
+- [ ] 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/")
+- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
-- [ ] Each file marked as create/modify/delete
+  - ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
-- [ ] Technical approach describes SPECIFIC implementation
+  - ❌ BAD: "Update some files in the services folder"
-- [ ] Implementation stack has complete toolchain with versions
+- [ ] **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"
+- [ ] **Epic title**: User-focused outcome (not implementation detail)
-- [ ] Phase 2 ("2-Plan") marked complete
+- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
-- [ ] First story in TODO section, others in BACKLOG (if Level 1)
+- [ ] **Epic goal**: Clear purpose and value statement
-- [ ] Next action clear (review story, run story-ready)
+- [ ] **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
+- [ ] bmm-workflow-status.yaml updated (if exists)
-- [ ] All technical questions answered definitively
+- [ ] Current phase reflects tech-spec completion
-- [ ] Testing approach clear and verifiable
+- [ ] Progress percentage updated appropriately
-- [ ] Deployment strategy documented
+- [ ] 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)
+- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.)
-- [ ] ❌ **Missing tech-spec sections** (required section missing from tech-spec.md)
+- [ ] ❌ **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]
+- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
-- Strengths:
+- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
-- Issues to address:
+- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
-- Recommended actions:
+- **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._

src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md

@@ -1,11 +1,58 @@
 # {{project_name}} - Epic Breakdown
 
-## Epic Overview
+**Date:** {{date}}
-
+**Project Level:** {{project_level}}
-{{epic_overview}}
 
 ---
 
-## 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.

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 from the ENHANCED tech-spec structure:
-<action>Extract time estimate from "Implementation Guide" or technical details</action>
+
-<action>Extract acceptance criteria from "Testing Approach" section</action>
+- 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`
+Since the tech-spec is now CONTEXT-RICH with:
-2. Run story-context workflow
-3. Then load DEV agent and run dev-story workflow
 
-**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)
+2. Run `dev-story` workflow
-3. Begin implementation
+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)
+1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
-2. Go directly to dev-story implementation (Option B - faster)
+2. Generate additional story context (for complex edge cases)
 3. Exit for now
 
 Select option (1-3):</ask>

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 from the ENHANCED tech-spec structure:
-<action>Extract time estimates for each implementation phase</action>
+
-<action>Identify any dependencies between implementation tasks</action>
+- 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
+    - files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
-    - test_locations: Where tests will be added
+    - 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 epic and stories are complete</action>
-<action>Confirm all stories have measurable acceptance criteria</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`
+a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
-b. Run story-context workflow (select story-{epic_slug}-1.md)
+b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
-c. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
+c. Tech-spec provides all context needed
-d. Run dev-story workflow to implement story 1
+d. Implement story 1
 
 **2. After Story 1 Complete:**
 
-- Repeat process for story-{epic_slug}-2.md
+- Repeat for story-{epic_slug}-2.md
-- Story context will auto-reference completed story 1
+- 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)
+1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
-2. Go directly to dev-story for story 1 (faster)
+2. Generate additional story context first (for complex dependencies)
 3. Exit for now
 
 Select option (1-3):</ask>

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

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}}
+- **Files to modify:** {{files_to_modify}}
-- Expected test locations: {{test_locations}}
+- **Expected test locations:** {{test_locations}}
-- Estimated effort: {{story_points}} story points ({{time_estimate}})
+- **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 -->

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"
@@ -36,6 +43,20 @@ recommended_inputs:
   - bug_report: "Bug description or issue ticket"
   - feature_request: "Brief feature description"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:

src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -1,4 +1,4 @@
-# Decision Architecture
+# Architecture
 
 ## Executive Summary
 

src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -10,6 +10,24 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow replaces architecture with a conversation-driven approach</critical>
 
+## 📚 Input Document Discovery
+
+This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
 <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
@@ -35,7 +53,7 @@
   <check if="project_level < 3">
     <output>**Note: Level {{project_level}} Project**
 
-Decision Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
+The Detailed Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
 
 For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 </output>
@@ -70,11 +88,11 @@ For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 
 Decision Architecture works from your Product Requirements Document (PRD).
 
-Looking for: bmm-PRD.md, PRD.md, or product-requirements.md in {output_folder}
+Looking for: _PRD_, PRD.md, or prd/index.md + files in {output_folder}
 
 Please run the PRD workflow first to define your requirements.
 
-Run: `workflow prd`
+Architect: `create-prd`
 </output>
 <action>Exit workflow - PRD required</action>
 </check>
@@ -82,7 +100,7 @@ Run: `workflow prd`
 </step>
 
 <step n="1" goal="Load and understand project context">
-  <action>Load the PRD using fuzzy matching: {prd_file}</action>
+  <action>Load the PRD using fuzzy matching: {prd_file}, if the PRD is mulitple files in a folder, load the index file and all files associated with the PRD</action>
   <action>Load epics file using fuzzy matching: {epics_file}</action>
 
 <action>Check for UX specification using fuzzy matching:
@@ -96,7 +114,7 @@ Run: `workflow prd`
 <action>Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned
 </action>
 
-<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists)
+<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features
 </action>
 
 <action>Reflect understanding back to {user_name}:
@@ -135,8 +153,8 @@ I see {{epic_count}} epics with {{story_count}} total stories.
     </action>
   </check>
 
-<action>Search for relevant starter templates:
+<action>Search for relevant starter templates with websearch, examples:
-<WebSearch>{{primary_technology}} starter template CLI create command latest 2024</WebSearch>
+<WebSearch>{{primary_technology}} starter template CLI create command latest {date}</WebSearch>
 <WebSearch>{{primary_technology}} boilerplate generator latest options</WebSearch>
 </action>
 
@@ -206,7 +224,7 @@ I see {{epic_count}} epics with {{story_count}} total stories.
 
   <check if="no_starter_found_or_applicable">
     <action>Note: No standard starter template found for this project type.
-            Will need to make all architectural decisions explicitly.</action>
+            We will make all architectural decisions explicitly.</action>
   </check>
 
 <template-output>starter_template_decision</template-output>
@@ -285,9 +303,12 @@ Let's work through the remaining {{remaining_count}} decisions."
 <action>Present the decision based on mode:
 <check if="mode == 'EXPERT'">
 "{{Decision_Category}}: {{Specific_Decision}}
-Options: {{concise_option_list_with_tradeoffs}}
+
-Recommendation: {{recommendation}} for {{reason}}"
+    Options: {{concise_option_list_with_tradeoffs}}
-</check>
+
+    Recommendation: {{recommendation}} for {{reason}}"
+
+  </check>
 
   <check if="mode == 'INTERMEDIATE'">
     "Next decision: {{Human_Friendly_Category}}
@@ -298,6 +319,7 @@ Recommendation: {{recommendation}} for {{reason}}"
       {{option_list_with_brief_explanations}}
 
       For your project, {{recommendation}} would work well because {{reason}}."
+
   </check>
 
   <check if="mode == 'BEGINNER'">
@@ -312,6 +334,7 @@ Recommendation: {{recommendation}} for {{reason}}"
 
       My suggestion: {{recommendation}}
       This is good for you because {{beginner_friendly_reason}}."
+
   </check>
 
   </action>
@@ -365,11 +388,7 @@ Provided by Starter: {{yes_if_from_starter}}
 </action>
 
   <check if="{user_skill_level} == 'beginner'">
-    <action>Explain why these matter:
+    <action>Explain why these matter why its critical to go through and decide these things now.</action>
-      "These are rules that EVERY part of your app must follow.
-       If we don't decide now, each AI agent will do it differently,
-       and your app won't work properly when the pieces come together."
-    </action>
   </check>
 
 <template-output>cross_cutting_decisions</template-output>

src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml

@@ -18,10 +18,23 @@ recommended_inputs:
   - epics: "Epic definitions with user stories and acceptance criteria"
   - ux_spec: "UX specification with interface designs and interaction patterns (optional)"
 
-# Input file references (fuzzy matched from output folder)
+# Smart input file references - handles both whole docs and sharded docs
-prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
+# Priority: Whole document first, then sharded version
-epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md"
+input_file_patterns:
-ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md"
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
 
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture"

src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md

@@ -4,6 +4,24 @@
 <critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml</critical>
 <critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
 
+## 📚 Input Document Discovery
+
+This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation.
+
+**Discovery Process** (execute for each referenced document):
+
+1. **Search for whole document first** - Use fuzzy file matching to find the complete document
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
+
 <workflow>
 
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">

src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml

@@ -32,6 +32,32 @@ recommended_inputs:
   - epics_stories: "{output_folder}/epic*.md"
   - ux_artifacts: "{output_folder}/ux*.md"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  tech_spec:
+    whole: "{output_folder}/*tech-spec*.md"
+    sharded: "{output_folder}/*tech-spec*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Validation criteria data
 validation_criteria: "{installed_path}/validation-criteria.yaml"
 

src/modules/bmm/workflows/4-implementation/code-review/instructions.md

@@ -16,6 +16,35 @@
 
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
+
 <workflow>
 
   <step n="1" goal="Find story ready for review" tag="sprint-status">

src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -51,6 +51,26 @@ recommended_inputs:
   - tech_spec: "Epic technical specification document (auto-discovered)"
   - story_context_file: "Story context file (.context.xml) (auto-discovered)"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
+input_file_patterns:
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle: false

src/modules/bmm/workflows/4-implementation/create-story/instructions.md

@@ -7,6 +7,35 @@
 <critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
 <critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+
 <workflow>
 
   <step n="1" goal="Load config and initialize">

src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -44,6 +44,33 @@ recommended_inputs:
   - prd: "PRD document"
   - architecture: "Architecture (optional)"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
+input_file_patterns:
+  prd:
+    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"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle: false

src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md

@@ -7,6 +7,35 @@
 <critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
 <critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from workflow context or user input)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories.
+
 <workflow>
   <step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
     <action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>

src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml

@@ -9,17 +9,43 @@ user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
 
-# Inputs expected ( check output_folder or ask user if missing)
+# Inputs expected (check output_folder or ask user if missing)
 recommended_inputs:
   - prd
   - gdd
-  - spec
   - architecture
-  - ux_spec
+  - ux_design
-  - ux-design
+  - epics (only the specific epic needed for this tech spec)
-  - if there is an index.md then read the index.md to find other related docs that could be relevant
   - prior epic tech-specs for model, style and consistency reference
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed (epic_num from context)
+input_file_patterns:
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  gdd:
+    whole: "{output_folder}/*gdd*.md"
+    sharded: "{output_folder}/*gdd*/index.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"
 template: "{installed_path}/template.md"

src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -21,6 +21,34 @@ trigger: "Run AFTER completing an epic"
 required_inputs:
   - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  previous_retrospective:
+    pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
+
+  architecture:
+    whole: "{output_folder}/*architecture*.md"
+    sharded: "{output_folder}/*architecture*/index.md"
+
+  prd:
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
+# Required files
+sprint_status_file: "{output_folder}/sprint-status.yaml"
+story_directory: "{config_source}:dev_story_location"
+retrospectives_folder: "{output_folder}/retrospectives"
+
 output_artifacts:
   - retrospective_summary: "Comprehensive review of what went well and what could improve"
   - lessons_learned: "Key insights for future epics"

src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -3,6 +3,23 @@
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml</critical>
 
+## 📚 Document Discovery - Full Epic Loading
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+   - This ensures complete sprint status coverage
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
+
 <workflow>
 
 <step n="1" goal="Parse epic files and extract all work items">

src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -33,6 +33,14 @@ variables:
   # Output configuration
   status_file: "{output_folder}/sprint-status.yaml"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status
+input_file_patterns:
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+
 # Output configuration
 default_output_file: "{status_file}"
 

src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -11,6 +11,35 @@
 
 <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
 
+## 📚 Document Discovery - Selective Epic Loading
+
+**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
+
+**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
+
+1. **Determine which epic** you need (epic_num from story key - e.g., story "3-2-feature-name" needs Epic 3)
+2. **Check for sharded version**: Look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
+   - DO NOT load all epic files - only the one needed!
+   - This is the key efficiency optimization for large multi-epic projects
+4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
+
+**Other Documents (prd, architecture, ux-design) - Full Load:**
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand structure
+   - Read ALL section files listed in the index
+   - Treat combined content as single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
+
 <workflow>
   <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
     <check if="{{story_path}} is provided">
@@ -91,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}:

src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -23,6 +23,33 @@ variables:
   story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted"
   story_dir: "{config_source}:dev_story_location"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
+input_file_patterns:
+  prd:
+    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"
+
+  ux_design:
+    whole: "{output_folder}/*ux*.md"
+    sharded: "{output_folder}/*ux*/index.md"
+
+  epics:
+    whole: "{output_folder}/*epic*.md"
+    sharded_index: "{output_folder}/*epic*/index.md"
+    sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Output configuration
 # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
 default_output_file: "{story_dir}/{{story_key}}.context.xml"

src/modules/bmm/workflows/README.md

@@ -23,6 +23,7 @@ Master guide for BMM's four-phase methodology that adapts to project scale (Leve
 - **Just-In-Time Design** - Tech specs created per epic during implementation
 - **Dynamic Expertise Injection** - Story-specific technical guidance
 - **Continuous Learning Loop** - Retrospectives improve each cycle
+- **Document Sharding Support** - All workflows handle whole or sharded documents for efficiency
 
 ## Universal Entry Point
 
@@ -209,6 +210,46 @@ document-project (if needed) → Phase 1 (optional) → Phase 2 → Phase 3 (L2-
 2. **Respect scale** - Don't over-document small projects
 3. **Use status tracking** - Always know where you are
 4. **Iterate and learn** - Each epic improves the next
+5. **Consider sharding** - Split large documents (PRD, epics, architecture) for efficiency
+
+## Document Sharding
+
+For large multi-epic projects, consider sharding planning documents to improve workflow efficiency.
+
+### What is Sharding?
+
+Splits large markdown files into smaller section-based files:
+
+- PRD with 15 epics → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Large epics file → Individual epic files
+- Architecture layers → Separate layer files
+
+### Benefits
+
+**Phase 1-3 Workflows:**
+
+- Workflows load entire sharded documents (transparent to user)
+- Better organization for large projects
+
+**Phase 4 Workflows:**
+
+- **Selective loading** - Only load the epic/section needed
+- **Massive efficiency** - 90%+ token reduction for 10+ epic projects
+- Examples: `epic-tech-context`, `create-story`, `story-context`, `code-review`
+
+### Usage
+
+```
+Load bmad-master or analyst agent:
+/shard-doc
+
+Source: docs/PRD.md
+Destination: docs/prd/
+```
+
+**All BMM workflows automatically support both whole and sharded documents.**
+
+**[→ Complete Sharding Guide](../../../docs/document-sharding-guide.md)**
 
 ---