bmad-method 6.0.0-alpha.3 → 6.0.0-alpha.5

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md

@@ -10,12 +10,23 @@
 <step n="1" goal="Load tech spec and extract the change">
 
 <action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
-<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
 <action>Extract dev_story_location from config (where stories are stored)</action>
-<action>Extract the problem statement from "Technical Approach" section</action>
-<action>Extract the scope from "Source Tree Structure" section</action>
-<action>Extract time estimate from "Implementation Guide" or technical details</action>
-<action>Extract acceptance criteria from "Testing Approach" section</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Problem statement from "The Change → Problem Statement" section
+- Solution overview from "The Change → Proposed Solution" section
+- Scope from "The Change → Scope" section
+- Source tree from "Implementation Details → Source Tree Changes" section
+- Time estimate from "Implementation Guide → Implementation Steps" section
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
+- Framework dependencies from "Development Context → Framework/Libraries" section
+- Existing code references from "Development Context → Relevant Existing Code" section
+- File paths from "Developer Resources → File Paths Reference" section
+- Key code locations from "Developer Resources → Key Code Locations" section
+- Testing locations from "Developer Resources → Testing Locations" section
+  </action>
 
 </step>
 
@@ -76,9 +87,18 @@
 **Dev Notes:**
 
 - Extract technical constraints from tech-spec
-- Include file paths from "Source Tree Structure"
+- Include file paths from "Developer Resources → File Paths Reference"
+- Include existing code references from "Development Context → Relevant Existing Code"
 - Reference architecture patterns if applicable
 - Cite tech-spec sections for implementation details
+- Note dependencies (internal and external)
+
+**NEW: Comprehensive Context**
+
+Since tech-spec is now context-rich, populate all new template fields:
+
+- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
   </guidelines>
 
 <action>Initialize story file using user_story_template</action>
@@ -94,6 +114,8 @@
 <template-output file="{story_path}">test_locations</template-output>
 <template-output file="{story_path}">story_points</template-output>
 <template-output file="{story_path}">time_estimate</template-output>
+<template-output file="{story_path}">dependencies</template-output>
+<template-output file="{story_path}">existing_code_references</template-output>
 <template-output file="{story_path}">architecture_references</template-output>
 
 </step>
@@ -135,29 +157,40 @@
 
 **Story Location:** `{story_path}`
 
-**Next Steps (choose one path):**
+**Next Steps:**
 
-**Option A - Full Context (Recommended for complex changes):**
+**🎯 RECOMMENDED - Direct to Development (Level 0):**
 
-1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
-2. Run story-context workflow
-3. Then load DEV agent and run dev-story workflow
+Since the tech-spec is now CONTEXT-RICH with:
 
-**Option B - Direct to Dev (For simple, well-understood changes):**
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+
+**You can skip story-context and go straight to dev!**
 
 1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
-2. Run dev-story workflow (will auto-discover story)
-3. Begin implementation
+2. Run `dev-story` workflow
+3. Begin implementation immediately
+
+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex scenarios:
+
+1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow (generates additional XML context)
+3. Then load DEV agent and run `dev-story` workflow
 
 **Progress Tracking:**
 
-- All decisions logged in: `bmm-workflow-status.md`
+- All decisions logged in: `bmm-workflow-status.yaml`
 - Next action clearly identified
 
 <ask>Ready to proceed? Choose your path:
 
-1. Generate story context (Option A - recommended)
-2. Go directly to dev-story implementation (Option B - faster)
+1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context (for complex edge cases)
 3. Exit for now
 
 Select option (1-3):</ask>

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md

@@ -11,12 +11,23 @@
 <step n="1" goal="Load tech spec and extract implementation tasks">
 
 <action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
-<action>Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md</action>
+<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
 <action>Extract dev_story_location from config (where stories are stored)</action>
-<action>Identify all implementation tasks from the "Implementation Guide" section</action>
-<action>Identify the overall feature goal from "Technical Approach" section</action>
-<action>Extract time estimates for each implementation phase</action>
-<action>Identify any dependencies between implementation tasks</action>
+
+<action>Extract from the ENHANCED tech-spec structure:
+
+- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
+- Implementation tasks from "Implementation Guide → Implementation Steps"
+- Time estimates from "Implementation Guide → Implementation Steps"
+- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
+- Source tree from "Implementation Details → Source Tree Changes"
+- Framework dependencies from "Development Context → Framework/Libraries"
+- Existing code references from "Development Context → Relevant Existing Code"
+- File paths from "Developer Resources → File Paths Reference"
+- Key code locations from "Developer Resources → Key Code Locations"
+- Testing locations from "Developer Resources → Testing Locations"
+- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
+  </action>
 
 </step>
 
@@ -60,6 +71,9 @@
 
 <action>Initialize epics.md summary document using epics_template</action>
 
+<action>Also capture project_level for the epic template</action>
+
+<template-output file="{output_folder}/epics.md">project_level</template-output>
 <template-output file="{output_folder}/epics.md">epic_title</template-output>
 <template-output file="{output_folder}/epics.md">epic_slug</template-output>
 <template-output file="{output_folder}/epics.md">epic_goal</template-output>
@@ -113,6 +127,25 @@
 - Include technical acceptance criteria from tech spec tasks
 - Link back to tech spec sections for implementation details
 
+**CRITICAL: Acceptance Criteria Must Be:**
+
+1. **Numbered** - AC #1, AC #2, AC #3, etc.
+2. **Specific** - No vague statements like "works well" or "is fast"
+3. **Testable** - Can be verified objectively
+4. **Complete** - Covers all success conditions
+5. **Independent** - Each AC tests one thing
+6. **Format**: Use Given/When/Then when applicable
+
+**Good AC Examples:**
+✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
+✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
+✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
+
+**Bad AC Examples:**
+❌ "User can create account" (too vague)
+❌ "System performs well" (not measurable)
+❌ "Works correctly" (not specific)
+
 **Story Point Estimation:**
 
 - 1 point = < 1 day (2-4 hours)
@@ -134,7 +167,14 @@
 - Acceptance Criteria: Numbered list from tech spec
 - Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
 - Dev Notes: Technical summary, project structure notes, references
-- Dev Agent Record: Empty sections for context workflow to populate
+- Dev Agent Record: Empty sections (tech-spec provides context)
+
+**NEW: Comprehensive Context Fields**
+
+Since tech-spec is context-rich, populate ALL template fields:
+
+- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
+- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
   </guidelines>
 
 <for-each story="1 to story_count">
@@ -149,10 +189,12 @@
     - acceptance_criteria: Specific, measurable criteria from tech spec
     - tasks_subtasks: Implementation tasks with AC references
     - technical_summary: High-level approach, key decisions
-    - files_to_modify: List of files that will change
-    - test_locations: Where tests will be added
+    - files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
+    - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
     - story_points: Estimated effort (1/2/3/5)
     - time_estimate: Days/hours estimate
+    - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
+    - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
     - architecture_references: Links to tech-spec.md sections
   </template-output>
 </for-each>
@@ -161,12 +203,35 @@
 
 </step>
 
-<step n="5" goal="Create story map and implementation sequence">
+<step n="5" goal="Create story map and implementation sequence with dependency validation">
+
+<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:
 
-<action>Generate visual story map showing epic → stories hierarchy</action>
+- 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">
+
+<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 stories map to tech spec implementation tasks</action>
+<action>Confirm all validation passed</action>
 <action>Verify total story points align with tech spec time estimates</action>
-<action>Verify stories are properly sequenced with dependencies noted</action>
-<action>Confirm all stories have measurable acceptance criteria</action>
+<action>Confirm epic and stories are complete</action>
 
 **Level 1 Planning Complete!**
 
@@ -242,33 +395,53 @@ Epic: Icon Reliability
 
 **Next Steps - Iterative Implementation:**
 
+**🎯 RECOMMENDED - Direct to Development (Level 1):**
+
+Since the tech-spec is now CONTEXT-RICH with:
+
+- ✅ Brownfield codebase analysis (if applicable)
+- ✅ Framework and library details with exact versions
+- ✅ Existing patterns and code references
+- ✅ Complete file paths and integration points
+- ✅ Dependencies clearly mapped
+
+**You can skip story-context for most Level 1 stories!**
+
 **1. Start with Story 1:**
-a. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
-b. Run story-context workflow (select story-{epic_slug}-1.md)
-c. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
-d. Run dev-story workflow to implement story 1
+a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
+b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
+c. Tech-spec provides all context needed
+d. Implement story 1
 
 **2. After Story 1 Complete:**
 
-- Repeat process for story-{epic_slug}-2.md
-- Story context will auto-reference completed story 1
+- Repeat for story-{epic_slug}-2.md
+- Reference completed story 1 in your work
 
 **3. After Story 2 Complete:**
 {{#if story_3}}
 
-- Repeat process for story-{epic_slug}-3.md
+- Repeat for story-{epic_slug}-3.md
   {{/if}}
 - Level 1 feature complete!
 
+**Option B - Generate Additional Context (optional):**
+
+Only needed for extremely complex multi-story dependencies:
+
+1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
+2. Run `story-context` workflow for complex stories
+3. Then load DEV agent and run `dev-story`
+
 **Progress Tracking:**
 
-- All decisions logged in: `bmm-workflow-status.md`
+- All decisions logged in: `bmm-workflow-status.yaml`
 - Next action clearly identified
 
 <ask>Ready to proceed? Choose your path:
 
-1. Generate context for story 1 (recommended - run story-context)
-2. Go directly to dev-story for story 1 (faster)
+1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
+2. Generate additional story context first (for complex dependencies)
 3. Exit for now
 
 Select option (1-3):</ask>