diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
index 5710bd23..f28734dc 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
@@ -2,20 +2,22 @@
**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
-**Scope**: Levels 0-1 software projects
+**Scope**: Quick-flow software projects (1-5 stories)
-**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
+**Expected Outputs**: tech-spec.md + epics.md + story files (1-5 stories)
-**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
+**New Standard**: Tech-spec should be comprehensive enough to replace story-context for most quick-flow projects
---
## 1. Output Files Exist
- [ ] tech-spec.md created in output folder
+- [ ] epics.md created (minimal for 1 story, detailed for multiple)
- [ ] Story file(s) created in sprint_artifacts
- - Level 0: 1 story file (story-{slug}.md)
- - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
+ - Naming convention: story-{epic-slug}-N.md (where N = 1 to story_count)
+ - 1 story: story-{epic-slug}-1.md
+ - Multiple stories: story-{epic-slug}-1.md through story-{epic-slug}-N.md
- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
- [ ] No unfilled {{template_variables}} in any files
@@ -134,16 +136,17 @@
---
-## 6. Epic Quality (Level 1 Only)
+## 6. Epic Quality (All Projects)
- [ ] **Epic title**: User-focused outcome (not implementation detail)
- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
- [ ] **Epic goal**: Clear purpose and value statement
- [ ] **Epic scope**: Boundaries clearly defined
- [ ] **Success criteria**: Measurable outcomes
-- [ ] **Story map**: Visual representation of epic → stories
-- [ ] **Implementation sequence**: Logical story ordering with dependencies
+- [ ] **Story map** (if multiple stories): Visual representation of epic → stories
+- [ ] **Implementation sequence** (if multiple stories): Logical story ordering with dependencies
- [ ] **Tech-spec reference**: Links back to tech-spec.md
+- [ ] **Detail level appropriate**: Minimal for 1 story, detailed for multiple
---
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-generate-stories.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-generate-stories.md
new file mode 100644
index 00000000..dd49dd77
--- /dev/null
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-generate-stories.md
@@ -0,0 +1,434 @@
+# Unified Epic and Story Generation
+
+
+
+This generates epic + stories for ALL quick-flow projects
+Always generates: epics.md + story files (1-5 stories based on {{story_count}})
+Runs AFTER tech-spec.md completion
+Story format MUST match create-story template for compatibility with story-context and dev-story workflows
+
+
+
+Read the completed tech-spec.md file from {default_output_file}
+Load bmm-workflow-status.yaml from {workflow-status} (if exists)
+Get story_count from workflow variables (1-5)
+Ensure {sprint_artifacts} directory exists
+
+Extract from tech-spec structure:
+
+**From "The Change" section:**
+
+- Problem statement and solution overview
+- Scope (in/out)
+
+**From "Implementation Details" section:**
+
+- Source tree changes
+- Technical approach
+- Integration points
+
+**From "Implementation Guide" section:**
+
+- Implementation steps
+- Testing strategy
+- Acceptance criteria
+- Time estimates
+
+**From "Development Context" section:**
+
+- Framework dependencies with versions
+- Existing code references
+- Internal dependencies
+
+**From "Developer Resources" section:**
+
+- File paths
+- Key code locations
+- Testing locations
+
+Use this rich context to generate comprehensive, implementation-ready epic and stories.
+
+
+
+
+
+
+Create epic based on the overall feature/change from tech-spec
+
+Derive epic slug from the feature name:
+
+- Use 2-3 words max
+- Kebab-case format
+- User-focused, not implementation-focused
+
+Examples:
+
+- "OAuth Integration" → "oauth-integration"
+- "Fix Login Bug" → "login-fix"
+- "User Profile Page" → "user-profile"
+
+
+Store as {{epic_slug}} - this will be used for all story filenames
+
+Adapt epic detail to story count:
+
+**For single story (story_count == 1):**
+
+- Epic is minimal - just enough structure
+- Goal: Brief statement of what's being accomplished
+- Scope: High-level boundary
+- Success criteria: Core outcomes
+
+**For multiple stories (story_count > 1):**
+
+- Epic is detailed - full breakdown
+- Goal: Comprehensive purpose and value statement
+- Scope: Clear boundaries with in/out examples
+- Success criteria: Measurable, testable outcomes
+- Story map: Visual representation of epic → stories
+- Implementation sequence: Logical ordering with dependencies
+
+
+
+
+
+
+Initialize {epics_file} using {epics_template}
+
+Populate epic metadata from tech-spec context:
+
+**Epic Title:** User-facing outcome (not implementation detail)
+
+- Good: "OAuth Integration", "Login Bug Fix", "Icon Reliability"
+- Bad: "Update recommendedLibraries.ts", "Refactor auth service"
+
+**Epic Goal:** Why this matters to users/business
+
+**Epic Scope:** Clear boundaries from tech-spec scope section
+
+**Epic Success Criteria:** Measurable outcomes from tech-spec acceptance criteria
+
+**Dependencies:** From tech-spec integration points and dependencies
+
+
+project_name
+date
+epic_title
+epic_slug
+epic_goal
+epic_scope
+epic_success_criteria
+epic_dependencies
+
+
+
+
+
+Analyze tech-spec implementation steps and create story breakdown
+
+**For story_count == 1:**
+
+- Create single comprehensive story covering all implementation
+- Title: Focused on the deliverable outcome
+- Tasks: Map directly to tech-spec implementation steps
+- Estimated points: Typically 1-5 points
+
+**For story_count > 1:**
+
+- Break implementation into logical story boundaries
+- Each story must be:
+ - Independently valuable (delivers working functionality)
+ - Testable (has clear acceptance criteria)
+ - Sequentially ordered (no forward dependencies)
+ - Right-sized (prefer 2-4 stories over many tiny ones)
+
+**Story Sequencing Rules (CRITICAL):**
+
+1. Foundation → Build → Test → Polish
+2. Database → API → UI
+3. Backend → Frontend
+4. Core → Enhancement
+5. NO story can depend on a later story!
+
+Validate sequence: Each story N should only depend on stories 1...N-1
+
+
+For each story position (1 to {{story_count}}):
+
+1. **Determine story scope from tech-spec tasks**
+ - Group related implementation steps
+ - Ensure story leaves system in working state
+
+2. **Create story title**
+ - User-focused deliverable
+ - Active, clear language
+ - Good: "OAuth Backend Integration", "OAuth UI Components"
+ - Bad: "Write some OAuth code", "Update files"
+
+3. **Extract acceptance criteria**
+ - From tech-spec testing strategy and acceptance criteria
+ - Must be numbered (AC #1, AC #2, etc.)
+ - Must be specific and testable
+ - Use Given/When/Then format when applicable
+
+4. **Map tasks to implementation steps**
+ - Break down tech-spec implementation steps for this story
+ - Create checkbox list
+ - Reference AC numbers: (AC: #1), (AC: #2)
+
+5. **Estimate story points**
+ - 1 point = < 1 day (2-4 hours)
+ - 2 points = 1-2 days
+ - 3 points = 2-3 days
+ - 5 points = 3-5 days
+ - Total across all stories should align with tech-spec estimates
+
+
+
+
+
+
+
+ Set story_filename = "story-{{epic_slug}}-{{n}}.md"
+ Set story_path = "{sprint_artifacts}/{{story_filename}}"
+
+Create story file using {user_story_template}
+
+Populate story with:
+
+**Story Header:**
+
+- N.M format (where N is always 1 for quick-flow, M is story number)
+- Title: User-focused deliverable
+- Status: Draft
+
+**User Story:**
+
+- As a [role] (developer, user, admin, system, etc.)
+- I want [capability/change]
+- So that [benefit/value]
+
+**Acceptance Criteria:**
+
+- Numbered list (AC #1, AC #2, ...)
+- Specific, measurable, testable
+- Derived from tech-spec testing strategy and acceptance criteria
+- Cover all success conditions for this story
+
+**Tasks/Subtasks:**
+
+- Checkbox list mapped to tech-spec implementation steps
+- Each task references AC numbers: (AC: #1)
+- Include explicit testing tasks
+
+**Technical Summary:**
+
+- High-level approach for this story
+- Key technical decisions
+- Files/modules involved
+
+**Project Structure Notes:**
+
+- files_to_modify: From tech-spec "Developer Resources → File Paths"
+- test_locations: From tech-spec "Developer Resources → Testing Locations"
+- story_points: Estimated effort
+- dependencies: Prerequisites (other stories, systems, data)
+
+**Key Code References:**
+
+- From tech-spec "Development Context → Relevant Existing Code"
+- From tech-spec "Developer Resources → Key Code Locations"
+- Specific file:line references when available
+
+**Context References:**
+
+- Link to tech-spec.md (primary context document)
+- Note: Tech-spec contains brownfield analysis, framework versions, patterns, etc.
+
+**Dev Agent Record:**
+
+- Empty sections (populated during dev-story execution)
+- Agent Model Used
+- Debug Log References
+- Completion Notes
+- Files Modified
+- Test Results
+
+**Review Notes:**
+
+- Empty section (populated during code review)
+
+
+story_number
+story_title
+user_role
+capability
+benefit
+acceptance_criteria
+tasks_subtasks
+technical_summary
+files_to_modify
+test_locations
+story_points
+time_estimate
+dependencies
+existing_code_references
+
+
+
+
+
+
+Create visual story map showing epic → stories hierarchy
+
+Include:
+
+- Epic title at top
+- Stories listed with point estimates
+- Dependencies noted
+- Sequence validation confirmation
+
+Example:
+
+```
+Epic: OAuth Integration (8 points)
+├── Story 1.1: OAuth Backend (3 points)
+│ Dependencies: None
+│
+├── Story 1.2: OAuth UI Components (3 points)
+│ Dependencies: Story 1.1
+│
+└── Story 1.3: OAuth Testing & Polish (2 points)
+ Dependencies: Stories 1.1, 1.2
+```
+
+
+
+Calculate totals:
+
+- Total story points across all stories
+- Estimated timeline (typically 1-2 points per day)
+
+
+Append to {epics_file}:
+
+- Story summaries
+- Story map visual
+- Implementation sequence
+- Total points and timeline
+
+
+story_map
+story_summaries
+total_points
+estimated_timeline
+implementation_sequence
+
+
+
+
+
+Always run validation - NOT optional!
+
+Validate all stories against quality standards:
+
+**Story Sequence Validation (CRITICAL):**
+
+- For each story N, verify it doesn't depend on story N+1 or later
+- Check: Can stories be implemented in order 1→2→3→...?
+- If sequence invalid: Identify problem, propose reordering, ask user to confirm
+
+**Acceptance Criteria Quality:**
+
+- All AC are numbered (AC #1, AC #2, ...)
+- Each AC is specific and testable (no "works well", "is good", "performs fast")
+- AC use Given/When/Then or equivalent structure
+- All success conditions are covered
+
+**Story Completeness:**
+
+- All stories map to tech-spec implementation steps
+- Story points align with tech-spec time estimates
+- Dependencies are clearly documented
+- Each story has testable AC
+- Files and locations reference tech-spec developer resources
+
+**Template Compliance:**
+
+- All required sections present
+- Dev Agent Record sections exist (even if empty)
+- Context references link to tech-spec.md
+- Story numbering follows N.M format
+
+
+
+
+
+Apply fixes? (yes/no)
+
+
+ Apply fixes (reorder stories, rewrite vague AC, add missing details)
+ Re-validate
+
+
+
+
+
+
+
+
+
+
+
+
+Update bmm-workflow-status.yaml (if exists):
+
+- Mark tech-spec as complete
+- Initialize story sequence tracking
+- Set first story as TODO
+- Track epic slug and story count
+
+
+
+
+
+
+
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md
deleted file mode 100644
index 5bbd5c57..00000000
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md
+++ /dev/null
@@ -1,200 +0,0 @@
-# Level 0 - Minimal User Story Generation
-
-
-
-This generates a single user story for Level 0 atomic changes
-Level 0 = single file change, bug fix, or small isolated task
-This workflow runs AFTER tech-spec.md has been completed
-Output format MUST match create-story template for compatibility with story-context and dev-story workflows
-
-
-
-Read the completed tech-spec.md file from {output_folder}/tech-spec.md
-Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)
-Extract sprint_artifacts from config (where stories are stored)
-
-Extract from the ENHANCED tech-spec structure:
-
-- Problem statement from "The Change → Problem Statement" section
-- Solution overview from "The Change → Proposed Solution" section
-- Scope from "The Change → Scope" section
-- Source tree from "Implementation Details → Source Tree Changes" section
-- Time estimate from "Implementation Guide → Implementation Steps" section
-- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
-- Framework dependencies from "Development Context → Framework/Libraries" section
-- Existing code references from "Development Context → Relevant Existing Code" section
-- File paths from "Developer Resources → File Paths Reference" section
-- Key code locations from "Developer Resources → Key Code Locations" section
-- Testing locations from "Developer Resources → Testing Locations" section
-
-
-
-
-
-
-Derive a short URL-friendly slug from the feature/change name
-Max slug length: 3-5 words, kebab-case format
-
-
-- "Migrate JS Library Icons" → "icon-migration"
-- "Fix Login Validation Bug" → "login-fix"
-- "Add OAuth Integration" → "oauth-integration"
-
-
-Set story_filename = "story-{slug}.md"
-Set story_path = "{sprint_artifacts}/story-{slug}.md"
-
-
-
-
-
-Create 1 story that describes the technical change as a deliverable
-Story MUST use create-story template format for compatibility
-
-
-**Story Point Estimation:**
-- 1 point = < 1 day (2-4 hours)
-- 2 points = 1-2 days
-- 3 points = 2-3 days
-- 5 points = 3-5 days (if this high, question if truly Level 0)
-
-**Story Title Best Practices:**
-
-- Use active, user-focused language
-- Describe WHAT is delivered, not HOW
-- Good: "Icon Migration to Internal CDN"
-- Bad: "Run curl commands to download PNGs"
-
-**Story Description Format:**
-
-- As a [role] (developer, user, admin, etc.)
-- I want [capability/change]
-- So that [benefit/value]
-
-**Acceptance Criteria:**
-
-- Extract from tech-spec "Testing Approach" section
-- Must be specific, measurable, and testable
-- Include performance criteria if specified
-
-**Tasks/Subtasks:**
-
-- Map directly to tech-spec "Implementation Guide" tasks
-- Use checkboxes for tracking
-- Reference AC numbers: (AC: #1), (AC: #2)
-- Include explicit testing subtasks
-
-**Dev Notes:**
-
-- Extract technical constraints from tech-spec
-- 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"
-
-
-Initialize story file using user_story_template
-
-story_title
-role
-capability
-benefit
-acceptance_criteria
-tasks_subtasks
-technical_summary
-files_to_modify
-test_locations
-story_points
-time_estimate
-dependencies
-existing_code_references
-architecture_references
-
-
-
-
-
-
- mode: update
- action: complete_workflow
- workflow_name: tech-spec
-
-
-
-
-
-
-Load {{status_file_path}}
-Set STORIES_SEQUENCE: [{slug}]
-Set TODO_STORY: {slug}
-Set TODO_TITLE: {{story_title}}
-Set IN_PROGRESS_STORY: (empty)
-Set STORIES_DONE: []
-Save {{status_file_path}}
-
-
-
-
-
-
-
-Display completion summary
-
-**Level 0 Planning Complete!**
-
-**Generated Artifacts:**
-
-- `tech-spec.md` → Technical source of truth
-- `story-{slug}.md` → User story ready for implementation
-
-**Story Location:** `{story_path}`
-
-**Next Steps:**
-
-**🎯 RECOMMENDED - Direct to Development (Level 0):**
-
-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
-
-**You can skip story-context and go straight to dev!**
-
-1. Load DEV agent: `{project-root}/{bmad_folder}/bmm/agents/dev.md`
-2. Run `dev-story` workflow
-3. Begin implementation immediately
-
-**Option B - Generate Additional Context (optional):**
-
-Only needed for extremely complex scenarios:
-
-1. Load SM agent: `{project-root}/{bmad_folder}/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.yaml`
-- Next action clearly identified
-
-Ready to proceed? Choose your path:
-
-1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
-2. Generate additional story context (for complex edge cases)
-3. Exit for now
-
-Select option (1-3)
-
-
-
-
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md
deleted file mode 100644
index aa316f36..00000000
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md
+++ /dev/null
@@ -1,451 +0,0 @@
-# Level 1 - Epic and Stories Generation
-
-
-
-This generates epic and user stories for Level 1 projects after tech-spec completion
-This is a lightweight story breakdown - not a full PRD
-Level 1 = coherent feature, 1-10 stories (prefer 2-3), 1 epic
-This workflow runs AFTER tech-spec.md has been completed
-Story format MUST match create-story template for compatibility with story-context and dev-story workflows
-
-
-
-Read the completed tech-spec.md file from {output_folder}/tech-spec.md
-Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)
-Extract sprint_artifacts from config (where stories are stored)
-
-Extract from the ENHANCED tech-spec structure:
-
-- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
-- Implementation tasks from "Implementation Guide → Implementation Steps"
-- Time estimates from "Implementation Guide → Implementation Steps"
-- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
-- Source tree from "Implementation Details → Source Tree Changes"
-- Framework dependencies from "Development Context → Framework/Libraries"
-- Existing code references from "Development Context → Relevant Existing Code"
-- File paths from "Developer Resources → File Paths Reference"
-- Key code locations from "Developer Resources → Key Code Locations"
-- Testing locations from "Developer Resources → Testing Locations"
-- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
-
-
-
-
-
-
-Create 1 epic that represents the entire feature
-Epic title should be user-facing value statement
-Epic goal should describe why this matters to users
-
-
-**Epic Best Practices:**
-- Title format: User-focused outcome (not implementation detail)
-- Good: "JS Library Icon Reliability"
-- Bad: "Update recommendedLibraries.ts file"
-- Scope: Clearly define what's included/excluded
-- Success criteria: Measurable outcomes that define "done"
-
-
-
-**Epic:** JS Library Icon Reliability
-
-**Goal:** Eliminate external dependencies for JS library icons to ensure consistent, reliable display and improve application performance.
-
-**Scope:** Migrate all 14 recommended JS library icons from third-party CDN URLs (GitHub, jsDelivr) to internal static asset hosting.
-
-**Success Criteria:**
-
-- All library icons load from internal paths
-- Zero external requests for library icons
-- Icons load 50-200ms faster than baseline
-- No broken icons in production
-
-
-Derive epic slug from epic title (kebab-case, 2-3 words max)
-
-
-- "JS Library Icon Reliability" → "icon-reliability"
-- "OAuth Integration" → "oauth-integration"
-- "Admin Dashboard" → "admin-dashboard"
-
-
-Initialize epics.md summary document using epics_template
-
-Also capture project_level for the epic template
-
-project_level
-epic_title
-epic_slug
-epic_goal
-epic_scope
-epic_success_criteria
-epic_dependencies
-
-
-
-
-
-Level 1 should have 2-3 stories maximum - prefer longer stories over more stories
-
-Analyze tech spec implementation tasks and time estimates
-Group related tasks into logical story boundaries
-
-
-**Story Count Decision Matrix:**
-
-**2 Stories (preferred for most Level 1):**
-
-- Use when: Feature has clear build/verify split
-- Example: Story 1 = Build feature, Story 2 = Test and deploy
-- Typical points: 3-5 points per story
-
-**3 Stories (only if necessary):**
-
-- Use when: Feature has distinct setup, build, verify phases
-- Example: Story 1 = Setup, Story 2 = Core implementation, Story 3 = Integration and testing
-- Typical points: 2-3 points per story
-
-**Never exceed 3 stories for Level 1:**
-
-- If more needed, consider if project should be Level 2
-- Better to have longer stories (5 points) than more stories (5x 1-point stories)
-
-
-Determine story_count = 2 or 3 based on tech spec complexity
-
-
-
-
-
-For each story (2-3 total), generate separate story file
-Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3
-
-
-**Story Generation Guidelines:**
-- Each story = multiple implementation tasks from tech spec
-- Story title format: User-focused deliverable (not implementation steps)
-- 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)
-- 2 points = 1-2 days
-- 3 points = 2-3 days
-- 5 points = 3-5 days
-
-**Level 1 Typical Totals:**
-
-- Total story points: 5-10 points
-- 2 stories: 3-5 points each
-- 3 stories: 2-3 points each
-- If total > 15 points, consider if this should be Level 2
-
-**Story Structure (MUST match create-story format):**
-
-- Status: Draft
-- Story: As a [role], I want [capability], so that [benefit]
-- 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 (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"
-
-
-
- Set story_path_{n} = "{sprint_artifacts}/story-{epic_slug}-{n}.md"
- Create story file from user_story_template with the following content:
-
-
- - story_title: User-focused deliverable title
- - role: User role (e.g., developer, user, admin)
- - capability: What they want to do
- - benefit: Why it matters
- - 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 (from tech-spec "Developer Resources → File Paths Reference")
- - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
- - story_points: Estimated effort (1/2/3/5)
- - time_estimate: Days/hours estimate
- - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
- - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
- - architecture_references: Links to tech-spec.md sections
-
-
-
-Generate exactly {story_count} story files (2 or 3 based on Step 3 decision)
-
-
-
-
-
-Stories MUST be ordered so earlier stories don't depend on later ones
-Each story must have CLEAR, TESTABLE acceptance criteria
-
-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!
-
-
-Generate visual story map showing epic → stories hierarchy with dependencies
-Calculate total story points across all stories
-Estimate timeline based on total points (1-2 points per day typical)
-Define implementation sequence with explicit dependency notes
-
-
-## Story Map
-
-```
-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
-**Estimated Timeline:** 1 sprint (1 week)
-
-## 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)
- - Dependencies: Story 1 must be complete
- - Deliverable: Icons verified, tested, deployed to production
-
-**Dependency Validation:** ✅ Valid sequence - no forward dependencies
-
-
-story_summaries
-story_map
-total_points
-estimated_timeline
-implementation_sequence
-
-
-
-
-
-
- mode: update
- action: complete_workflow
- workflow_name: tech-spec
- populate_stories_from: {epics_output_file}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Auto-run validation - NOT optional!
-
-Running automatic story validation...
-
-**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
-
-
-**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
-
-
-**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
-
-
-Generate validation report
-
-
-
-
-Apply fixes? (yes/no)
-
-
- Apply fixes (reorder stories, rewrite vague AC, add missing details)
- Re-validate
-
-
-
-
-
-
-
-
-
-
-
-
-Confirm all validation passed
-Verify total story points align with tech spec time estimates
-Confirm epic and stories are complete
-
-**Level 1 Planning Complete!**
-
-**Epic:** {{epic_title}}
-**Total Stories:** {{story_count}}
-**Total Story Points:** {{total_points}}
-**Estimated Timeline:** {{estimated_timeline}}
-
-**Generated Artifacts:**
-
-- `tech-spec.md` → Technical source of truth
-- `epics.md` → Epic and story summary
-- `story-{epic_slug}-1.md` → First story (ready for implementation)
-- `story-{epic_slug}-2.md` → Second story
- {{#if story_3}}
-- `story-{epic_slug}-3.md` → Third story
- {{/if}}
-
-**Story Location:** `{sprint_artifacts}/`
-
-**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 DEV agent: `{project-root}/{bmad_folder}/bmm/agents/dev.md`
-b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
-c. Tech-spec provides all context needed
-d. Implement story 1
-
-**2. After Story 1 Complete:**
-
-- Repeat for story-{epic_slug}-2.md
-- Reference completed story 1 in your work
-
-**3. After Story 2 Complete:**
-{{#if story_3}}
-
-- 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_folder}/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.yaml`
-- Next action clearly identified
-
-Ready to proceed? Choose your path:
-
-1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
-2. Generate additional story context first (for complex dependencies)
-3. Exit for now
-
-Select option (1-3):
-
-
-
-
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
index 29778b5f..a71d50c4 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
@@ -1,4 +1,4 @@
-# Tech-Spec Workflow - Context-Aware Technical Planning (Level 0-1)
+# Tech-Spec Workflow - Context-Aware Technical Planning (quick-flow)
@@ -6,8 +6,8 @@
You MUST have already loaded and processed: {installed_path}/workflow.yaml
Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
Generate all documents in {document_output_language}
-This is for Level 0-1 projects - tech-spec with context-rich story generation
-Level 0: tech-spec + single user story | Level 1: tech-spec + epic/stories
+This is quick-flow efforts - tech-spec with context-rich story generation
+Quick Flow: tech-spec + epic with 1-5 stories (always generates epic structure)
LIVING DOCUMENT: Write to tech-spec.md continuously as you discover - never wait until the end
CONTEXT IS KING: Gather ALL available context before generating specs
DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.
@@ -26,34 +26,34 @@
- What level is this project?
+ How many user stories do you think this work requires?
-**Level 0** - Single atomic change (bug fix, small isolated feature, single file change)
-→ Generates: 1 tech-spec + 1 story
+**Single Story** - Simple change (bug fix, small isolated feature, single file change)
+→ Generates: tech-spec + epic (minimal) + 1 story
→ Example: "Fix login validation bug" or "Add email field to user form"
-**Level 1** - Coherent feature (multiple related changes, small feature set)
-→ Generates: 1 tech-spec + 1 epic + 2-3 stories
+**Multiple Stories (2-5)** - Coherent feature (multiple related changes, small feature set)
+→ Generates: tech-spec + epic (detailed) + 2-5 stories
→ Example: "Add OAuth integration" or "Build user profile page"
-Enter **0** or **1**:
+Enter **1** for single story, or **2-5** for number of stories you estimate
- Capture user response as project_level (0 or 1)
- Validate: If not 0 or 1, ask again
+ Capture user response as story_count (1-5)
+ Validate: If not 1-5, ask for clarification. If > 5, suggest using full BMad Method instead
- Is this a **greenfield** (new/empty codebase) or **brownfield** (existing codebase) project?
+ Is this a **greenfield** (new/empty codebase) or **brownfield** (existing codebase) project?
-**Greenfield** - Starting fresh, no existing code
-**Brownfield** - Adding to or modifying existing code
+ **Greenfield** - Starting fresh, no existing code aside from starter templates
+ **Brownfield** - Adding to or modifying existing functional code or project
-Enter **greenfield** or **brownfield**:
+ Enter **greenfield** or **brownfield**:
Capture user response as field_type (greenfield or brownfield)
Validate: If not greenfield or brownfield, ask again
- Load the FULL file: {output_folder}/bmm-workflow-status.yaml
+ Load the FULL file: {workflow-status}
Parse workflow_status section
Check status of "tech-spec" workflow
- Get project_level from YAML metadata
+ Get selected_track from YAML metadata indicating this is quick-flow-greenfield or quick-flow-brownfield
Get field_type from YAML metadata (greenfield or brownfield)
Find first non-completed workflow (next expected workflow)
-
-
-
+
-Now generate stories that reference the rich tech-spec context
+Invoke unified story generation workflow: {instructions_generate_stories}
-
- Invoke {installed_path}/instructions-level0-story.md to generate single user story
- Story will leverage tech-spec.md as primary context
- Developers can skip story-context workflow since tech-spec is comprehensive
-
+This will generate:
-
- Invoke {installed_path}/instructions-level1-stories.md to generate epic and stories
- Stories will reference tech-spec.md for all technical details
- Epic provides organization, tech-spec provides implementation context
-
+- **epics.md** - Epic structure (minimal for 1 story, detailed for multiple)
+- **story-{epic-slug}-N.md** - Story files (where N = 1 to {{story_count}})
+
+All stories reference tech-spec.md as primary context - comprehensive enough that developers can often skip story-context workflow.
+
@@ -1028,22 +911,13 @@ Tech-spec is high quality and ready for story generation!
**Deliverables Created:**
-
- ✅ **tech-spec.md** - Context-rich technical specification
- Includes: brownfield analysis, framework details, existing patterns
-- ✅ **story-{slug}.md** - Implementation-ready user story
- - References tech-spec as primary context
-
-
-
-- ✅ **tech-spec.md** - Context-rich technical specification
-- ✅ **epics.md** - Epic and story organization
-- ✅ **story-{epic-slug}-1.md** - First story
-- ✅ **story-{epic-slug}-2.md** - Second story
-{{#if story_3}}
-- ✅ **story-{epic-slug}-3.md** - Third story
-{{/if}}
-
+- ✅ **epics.md** - Epic structure{{#if story_count == 1}} (minimal for single story){{else}} with {{story_count}} stories{{/if}}
+- ✅ **story-{epic-slug}-1.md** - First story{{#if story_count > 1}}
+- ✅ **story-{epic-slug}-2.md** - Second story{{/if}}{{#if story_count > 2}}
+- ✅ **story-{epic-slug}-3.md** - Third story{{/if}}{{#if story_count > 3}}
+- ✅ **Additional stories** through story-{epic-slug}-{{story_count}}.md{{/if}}
**What Makes This Tech-Spec Special:**
@@ -1057,55 +931,41 @@ The tech-spec is comprehensive enough to serve as the primary context document:
**Next Steps:**
-
-**For Single Story (Level 0):**
+**🎯 Recommended Path - Direct to Development:**
-**Option A - With Story Context (for complex changes):**
+Since the tech-spec is CONTEXT-RICH, you can often skip story-context generation!
-1. Ask SM agent to run `create-story-context` for the story
- - This generates additional XML context if needed
-2. Then ask DEV agent to run `dev-story` to implement
+{{#if story_count == 1}}
+**For Your Single Story:**
-**Option B - Direct to Dev (most Level 0):**
-
-1. Ask DEV agent to run `dev-story` directly
+1. Ask DEV agent to run `dev-story`
+ - Select story-{epic-slug}-1.md
- Tech-spec provides all the context needed!
- - Story is ready to implement
-💡 **Tip:** Most Level 0 changes don't need separate story context since tech-spec is comprehensive!
-
+💡 **Optional:** Only run `story-context` (SM agent) if this is unusually complex
+{{else}}
+**For Your {{story_count}} Stories - Iterative Approach:**
-
-**For Multiple Stories (Level 1):**
+1. **Start with Story 1:**
+ - Ask DEV agent to run `dev-story`
+ - Select story-{epic-slug}-1.md
+ - Tech-spec provides context
-**Recommended: Story-by-Story Approach**
+2. **After Story 1 Complete:**
+ - Repeat for story-{epic-slug}-2.md
+ - Continue through story {{story_count}}
-For the **first story** ({{first_story_name}}):
+💡 **Alternative:** Use `sprint-planning` (SM agent) to organize all stories as a coordinated sprint
-**Option A - With Story Context (recommended for first story):**
-
-1. Ask SM agent to run `create-story-context` for story 1
- - Generates focused context for this specific story
-2. Then ask DEV agent to run `dev-story` to implement story 1
-
-**Option B - Direct to Dev:**
-
-1. Ask DEV agent to run `dev-story` for story 1
- - Tech-spec has most context needed
-
-After completing story 1, repeat for stories 2 and 3.
-
-**Alternative: Sprint Planning Approach**
-
-- If managing multiple stories as a sprint, ask SM agent to run `sprint-planning`
-- This organizes all stories for coordinated implementation
-
+💡 **Optional:** Run `story-context` (SM agent) for complex stories needing additional context
+{{/if}}
**Your Tech-Spec:**
- 📄 Saved to: `{output_folder}/tech-spec.md`
+- Epic & Stories: `{output_folder}/epics.md` + `{sprint_artifacts}/`
- Contains: All context, decisions, patterns, and implementation guidance
-- Ready for: Direct development or story context generation
+- Ready for: Direct development!
The tech-spec is your single source of truth! 🚀
diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
index d4cb37ca..3cdea776 100644
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
@@ -1,6 +1,6 @@
# Technical Specification
name: tech-spec
-description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
+description: "Technical specification workflow for quick-flow projects. Creates focused tech spec and generates epic + stories (1 story for simple changes, 2-5 stories for features). Tech-spec only - no PRD needed."
author: "BMad"
# Critical variables from config
@@ -13,10 +13,11 @@ document_output_language: "{config_source}:document_output_language"
user_skill_level: "{config_source}:user_skill_level"
date: system-generated
+workflow-status: "{output_folder}/bmm-workflow-status.yaml"
+
# Runtime variables (captured during workflow execution)
-project_level: runtime-captured
-project_type: runtime-captured
-development_context: runtime-captured
+story_count: runtime-captured
+epic_slug: runtime-captured
change_type: runtime-captured
field_type: runtime-captured
@@ -25,23 +26,15 @@ installed_path: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/tec
instructions: "{installed_path}/instructions.md"
template: "{installed_path}/tech-spec-template.md"
-# Story generation instructions (invoked based on level)
-instructions_level0_story: "{installed_path}/instructions-level0-story.md"
-instructions_level1_stories: "{installed_path}/instructions-level1-stories.md"
-
-# Templates
+# Story generation (unified approach - always generates epic + stories)
+instructions_generate_stories: "{installed_path}/instructions-generate-stories.md"
user_story_template: "{installed_path}/user-story-template.md"
epics_template: "{installed_path}/epics-template.md"
# Output configuration
default_output_file: "{output_folder}/tech-spec.md"
-user_story_file: "{output_folder}/user-story.md"
epics_file: "{output_folder}/epics.md"
-
-# Recommended input documents (optional for Level 0)
-recommended_inputs:
- - bug_report: "Bug description or issue ticket"
- - feature_request: "Brief feature description"
+sprint_artifacts: "{output_folder}/sprint_artifacts"
# Smart input file references - handles both whole docs and sharded docs
# Priority: Whole document first, then sharded version
@@ -49,31 +42,12 @@ 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:
- name: "tech-spec-sm"
- description: "Technical specification workflow for Level 0-1 projects. Creates focused tech spec with story generation. Level 0: tech-spec + user story. Level 1: tech-spec + epic/stories."
- author: "BMad"
- instructions: "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/instructions.md"
- web_bundle_files:
- # Core workflow files
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/instructions.md"
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md"
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md"
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md"
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md"
- - "{bmad_folder}/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md"
-
- # Task dependencies (referenced in instructions.md)
- - "{bmad_folder}/core/tasks/workflow.xml"
- - "{bmad_folder}/core/tasks/adv-elicit.xml"
- - "{bmad_folder}/core/tasks/adv-elicit-methods.csv"
+web_bundle: false