bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.1

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

@@ -1,48 +1,159 @@
 # Develop Story - Workflow Instructions
 
 ```xml
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<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>Generate all documents in {document_output_language}</critical>
 <critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status</critical>
 <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
-<critical>If {{run_until_complete}} == true, run non-interactively: do not pause between steps unless a HALT condition is reached or explicit user approval is required for unapproved dependencies.</critical>
-<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) or a HALT condition is triggered.</critical>
+<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical>
 <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
 
+<critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
+
 <workflow>
 
-  <step n="1" goal="Load story and select next task">
-    <action>If {{story_path}} was explicitly provided and is valid → use it. Otherwise, attempt auto-discovery.</action>
-    <action>Auto-discovery: Read {{story_dir}} from config (dev_story_location). If invalid/missing or contains no .md files, ASK user to provide either: (a) a story file path, or (b) a directory to scan.</action>
-    <action>If a directory is provided, list story markdown files recursively under that directory matching pattern: "story-*.md".</action>
-    <action>Sort candidates by last modified time (newest first) and take the top {{story_selection_limit}} items.</action>
-    <ask>Present the list with index, filename, and modified time. Ask: "Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
-    <action>Resolve the selected item into {{story_path}}</action>
-    <action>Read the COMPLETE story file from {{story_path}}</action>
-    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks (including subtasks), Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
-    <action>Identify the first incomplete task (unchecked [ ]) in Tasks/Subtasks; if subtasks exist, treat all subtasks as part of the selected task scope</action>
-    <check>If no incomplete tasks found → "All tasks completed - proceed to completion sequence" and <goto step="6">Continue</goto></check>
-    <check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
-    <check>If task requirements ambiguous → ASK user to clarify; if unresolved, HALT: "Task requirements must be clear before implementation"</check>
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto>task_check</goto>
+    </check>
+
+    <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely to understand story order</action>
+
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "ready-for-dev"
+    </action>
+
+    <check if="no ready-for-dev or in-progress story found">
+      <output>📋 No ready-for-dev stories found in sprint-status.yaml
+**Options:**
+1. Run `story-context` to generate context file and mark drafted stories as ready
+2. Run `story-ready` to quickly mark drafted stories as ready without generating context
+3. Run `create-story` if no incomplete stories are drafted yet
+4. Check {output-folder}/sprint-status.yaml to see current sprint status
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md</action>
+    <action>Read COMPLETE story file from discovered path</action>
+
+    <anchor id="task_check" />
+
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
+    <check if="context file exists">
+      <action>Read COMPLETE context file</action>
+      <action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
+      <action>Use this context to inform implementation decisions and approaches</action>
+    </check>
+    <check if="context file does NOT exist">
+      <output>ℹ️ No context file found for {{story_key}}
+
+Proceeding with story file only. For better context, consider running `story-context` workflow first.
+      </output>
+    </check>
+
+    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
+
+    <action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
+  </step>
+
+  <step n="1.5" goal="Detect review continuation and extract review context">
+    <critical>Determine if this is a fresh start or continuation after code review</critical>
+
+    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
+    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
+
+    <check if="Senior Developer Review section exists">
+      <action>Set review_continuation = true</action>
+      <action>Extract from "Senior Developer Review (AI)" section:
+        - Review outcome (Approve/Changes Requested/Blocked)
+        - Review date
+        - Total action items with checkboxes (count checked vs unchecked)
+        - Severity breakdown (High/Med/Low counts)
+      </action>
+      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
+      <action>Store list of unchecked review items as {{pending_review_items}}</action>
+
+      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
+
+**Review Outcome:** {{review_outcome}}
+**Action Items:** {{unchecked_review_count}} remaining to address
+**Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
+
+**Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
+      </output>
+    </check>
+
+    <check if="Senior Developer Review section does NOT exist">
+      <action>Set review_continuation = false</action>
+      <action>Set {{pending_review_items}} = empty</action>
+
+      <output>🚀 **Starting Fresh Implementation**
+
+Story: {{story_key}}
+Context file: {{context_available}}
+First incomplete task: {{first_task_description}}
+      </output>
+    </check>
+  </step>
+
+  <step n="1.6" goal="Mark story in-progress" tag="sprint-status">
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read all development_status entries to find {{story_key}}</action>
+    <action>Get current status value for development_status[{{story_key}}]</action>
+
+    <check if="current status == 'ready-for-dev'">
+      <action>Update the story in the sprint status report to = "in-progress"</action>
+      <output>🚀 Starting work on story {{story_key}}
+Status updated: ready-for-dev → in-progress
+      </output>
+    </check>
+
+    <check if="current status == 'in-progress'">
+      <output>⏯️ Resuming work on story {{story_key}}
+Story is already marked in-progress
+      </output>
+    </check>
+
+    <check if="current status is neither ready-for-dev nor in-progress">
+      <output>⚠️ Unexpected story status: {{current_status}}
+Expected ready-for-dev or in-progress. Continuing anyway...
+      </output>
+    </check>
   </step>
 
   <step n="2" goal="Plan and implement task">
     <action>Review acceptance criteria and dev notes for the selected task</action>
     <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
-    <action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
+    <action>Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions</action>
     <action>Handle error conditions and edge cases appropriately</action>
-    <check>If unapproved dependencies are needed → ASK user for approval before adding</check>
-    <check>If 3 consecutive implementation failures occur → HALT and request guidance</check>
-    <check>If required configuration is missing → HALT: "Cannot proceed without necessary configuration files"</check>
-    <check>If {{run_until_complete}} == true → Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</check>
-    <check>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</check>
+    <action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
+    <critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
+    <critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
   </step>
 
   <step n="3" goal="Author comprehensive tests">
     <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
-    <action>Add integration tests for component interactions where applicable</action>
-    <action>Include end-to-end tests for critical user flows if applicable</action>
-    <action>Cover edge cases and error handling scenarios noted in the plan</action>
+    <action>Add integration tests for component interactions where desired by test plan or story notes</action>
+    <action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
+    <action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
   </step>
 
   <step n="4" goal="Run validations and tests">
@@ -51,36 +162,100 @@
     <action>Run the new tests to verify implementation correctness</action>
     <action>Run linting and code quality checks if configured</action>
     <action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
-    <check>If regression tests fail → STOP and fix before continuing</check>
-    <check>If new tests fail → STOP and fix before continuing</check>
+    <action if="regression tests fail">STOP and fix before continuing, consider how current changes made broke regression</action>
+    <action if="new tests fail">STOP and fix before continuing</action>
   </step>
 
-  <step n="5" goal="Mark task complete and update story">
+  <step n="5" goal="Mark task complete, track review resolutions, and update story">
+    <critical>If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section</critical>
+
+    <action>Check if completed task has [AI-Review] prefix (indicates review follow-up task)</action>
+
+    <check if="task is review follow-up">
+      <action>Extract review item details (severity, description, related AC/file)</action>
+      <action>Add to resolution tracking list: {{resolved_review_items}}</action>
+
+      <!-- Mark task in Review Follow-ups section -->
+      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
+
+      <!-- CRITICAL: Also mark corresponding action item in review section -->
+      <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
+      <action>Mark that action item checkbox [x] as resolved</action>
+
+      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
+    </check>
+
     <action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
     <action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
     <action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
-    <action>Append a brief entry to Change Log describing the change</action>
+
+    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
+      <action>Count total resolved review items in this session</action>
+      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
+    </check>
+
     <action>Save the story file</action>
-    <check>Determine if more incomplete tasks remain</check>
-    <check>If more tasks remain → <goto step="1">Next task</goto></check>
-    <check>If no tasks remain → <goto step="6">Completion</goto></check>
+    <action>Determine if more incomplete tasks remain</action>
+    <action if="more tasks remain"><goto step="2">Next task</goto></action>
+    <action if="no tasks remain"><goto step="6">Completion</goto></action>
   </step>
 
-  <step n="6" goal="Story completion sequence">
+  <step n="6" goal="Story completion and mark for review" tag="sprint-status">
     <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
     <action>Run the full regression suite (do not skip)</action>
     <action>Confirm File List includes every changed file</action>
     <action>Execute story definition-of-done checklist, if the story includes one</action>
-    <action>Update the story Status to: Ready for Review</action>
-    <check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
-    <check>If regression failures exist → STOP and resolve before completing</check>
-    <check>If File List is incomplete → Update it before completing</check>
+    <action>Update the story Status to: review</action>
+
+    <!-- Mark story ready for review -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "in-progress" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "review"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+
+Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+
+    <action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
+    <action if="regression failures exist">STOP and resolve before completing</action>
+    <action if="File List is incomplete">Update it before completing</action>
   </step>
 
-  <step n="7" goal="Validation and handoff" optional="true">
-    <action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.md</action>
+  <step n="7" goal="Completion communication and user support">
+    <action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
     <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
-    <action>Communicate that the story is Ready for Review</action>
+
+    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
+    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
+    <action>Provide the story file path and current status (now "review", was "in-progress")</action>
+
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>Common next steps to suggest (but allow user flexibility):
+      - Review the implemented story yourself and test the changes
+      - Verify all acceptance criteria are met
+      - Ensure deployment readiness if applicable
+      - Run `code-review` workflow for peer review
+      - Check sprint-status.yaml to see project progress
+    </action>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
   </step>
 
 </workflow>

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

@@ -7,47 +7,22 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
+user_skill_level: "{config_source}:user_skill_level"
+document_output_language: "{config_source}:document_output_language"
+story_dir: "{config_source}:dev_story_location"
+run_until_complete: "{config_source}:run_until_complete"
+run_tests_command: "{config_source}:run_tests_command"
 date: system-generated
 
+story_file: "" # Explicit story path; auto-discovered if empty
+# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
+context_file: "{story_dir}/{{story_key}}.context.xml"
+
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/dev-story"
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
-# This is an action workflow (no output template document)
-template: false
-
-# Variables (can be provided by caller)
-variables:
-  story_path: ""
-  run_tests_command: "auto" # 'auto' = infer from repo, or override with explicit command
-  strict: true # if true, halt on validation failures
-  story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
-  story_selection_limit: 10
-  run_until_complete: true # Continue through all tasks without pausing except on HALT conditions
-  force_yolo: true # Hint executor to activate #yolo: skip optional prompts and elicitation
-
-# Recommended inputs
-recommended_inputs:
-  - story_markdown: "Path to the story markdown file (Tasks/Subtasks, Acceptance Criteria present)"
-
-# Required tools (conceptual; executor should provide equivalents)
-required_tools:
-  - read_file
-  - write_file
-  - search_repo
-  - run_tests
-  - list_files
-  - file_info
-
-tags:
-  - development
-  - story-execution
-  - tests
-  - validation
-  - bmad-v6
+standalone: true
 
-execution_hints:
-  interactive: false # Minimize prompts; intended to run to completion
-  autonomous: true # Proceed without user input unless blocked
-  iterative: true
+web_bundle: false

package/src/modules/bmm/workflows/{3-solutioning/tech-spec → 4-implementation/epic-tech-context}/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
+Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
 
 ## Key Features
 
@@ -25,10 +25,10 @@ workflow tech-spec
 
 ```bash
 # With specific PRD and architecture
-workflow tech-spec --input prd.md --input architecture.md
+workflow tech-spec --input PRD.md --input architecture.md
 
 # With comprehensive inputs
-workflow tech-spec --input prd.md --input architecture.md --input front-end-spec.md
+workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec.md
 ```
 
 ### Configuration
@@ -104,7 +104,7 @@ tech-spec/
 ### Output Structure
 
 1. **Overview and Scope** - Project context and boundaries
-2. **System Architecture Alignment** - Connection to high-level architecture
+2. **System Architecture Alignment** - Connection to architecture
 3. **Detailed Design** - Services, data models, APIs, and workflows
 4. **Non-Functional Requirements** - Performance, security, reliability, observability
 5. **Dependencies and Integrations** - External systems and technical dependencies
@@ -116,7 +116,7 @@ tech-spec/
 ## Requirements
 
 - **PRD Document**: Product Requirements Document with clear acceptance criteria
-- **Architecture Document**: High-level architecture or technical design
+- **Architecture Document**: architecture or technical design
 - **Repository Access**: For dependency analysis and framework detection
 - **Epic Context**: Clear epic identification and scope definition
 
@@ -185,7 +185,7 @@ To customize this workflow:
 
 For issues or questions:
 
-- Review the workflow creation guide at `/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md`
+- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
 - Validate output using `checklist.md`
 - Ensure PRD and architecture documents are complete before starting
 - Consult BMAD documentation for technical specification standards

package/src/modules/bmm/workflows/{3-solutioning/tech-spec → 4-implementation/epic-tech-context}/checklist.md

@@ -1,7 +1,7 @@
 # Tech Spec Validation Checklist
 
 ```xml
-<checklist id="bmad/bmm/workflows/3-solutioning/tech-spec/checklist">
+<checklist id="bmad/bmm/workflows/4-implementation/epic-tech-context/checklist">
   <item>Overview clearly ties to PRD goals</item>
   <item>Scope explicitly lists in-scope and out-of-scope</item>
   <item>Design lists all services/modules with responsibilities</item>

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

@@ -0,0 +1,160 @@
+<!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
+
+```xml
+<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}</critical>
+<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>
+
+<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>
+    <ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
+
+    <!-- Intelligent Epic Discovery -->
+    <critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Read ALL development_status entries</action>
+    <action>Find all epics with status "backlog" (not yet contexted)</action>
+    <action>Identify the FIRST backlog epic as the suggested default</action>
+
+    <check if="backlog epics found">
+      <output>📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}}</output>
+      <ask>Use this epic?
+- [y] Yes, use {{suggested_epic_id}}
+- [n] No, let me specify a different epic_id
+      </ask>
+
+      <check if="user selects 'n'">
+        <ask>Enter the epic_id you want to context</ask>
+        <action>Store user-provided epic_id as {{epic_id}}</action>
+      </check>
+
+      <check if="user selects 'y'">
+        <action>Use {{suggested_epic_id}} as {{epic_id}}</action>
+      </check>
+    </check>
+
+    <check if="no backlog epics found">
+      <output>✅ All epics are already contexted!
+
+No epics with status "backlog" found in sprint-status.yaml.
+      </output>
+      <ask>Do you want to re-context an existing epic? Enter epic_id or [q] to quit:</ask>
+
+      <check if="user enters epic_id">
+        <action>Store as {{epic_id}}</action>
+      </check>
+
+      <check if="user enters 'q'">
+        <action>HALT - No work needed</action>
+      </check>
+    </check>
+
+    <action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
+    <action>Resolve output file path using workflow variables and initialize by writing the template.</action>
+  </step>
+
+  <step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
+    <action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
+    <action>Get current status value if epic exists</action>
+
+    <check if="epic not found">
+      <output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
+
+This epic hasn't been registered in the sprint plan yet.
+Run sprint-planning workflow to initialize epic tracking.
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <check if="epic status == 'contexted'">
+      <output>ℹ️ Epic {{epic_id}} already marked as contexted
+
+Continuing to regenerate tech spec...
+      </output>
+    </check>
+  </step>
+
+  <step n="3" goal="Overview and scope">
+    <action>Read COMPLETE found {recommended_inputs}.</action>
+    <template-output file="{default_output_file}">
+      Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
+      Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets
+      Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints)
+    </template-output>
+  </step>
+
+  <step n="4" goal="Detailed design">
+    <action>Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate.</action>
+    <template-output file="{default_output_file}">
+      Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners
+      Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available
+      Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes)
+      Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow)
+    </template-output>
+  </step>
+
+  <step n="5" goal="Non-functional requirements">
+    <template-output file="{default_output_file}">
+      Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture
+      Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections
+      Replace {{nfr_reliability}} with availability, recovery, and degradation behavior
+      Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals
+    </template-output>
+  </step>
+
+  <step n="6" goal="Dependencies and integrations">
+    <action>Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json).</action>
+    <template-output file="{default_output_file}">
+      Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known
+    </template-output>
+  </step>
+
+  <step n="7" goal="Acceptance criteria and traceability">
+    <action>Extract acceptance criteria from PRD; normalize into atomic, testable statements.</action>
+    <template-output file="{default_output_file}">
+      Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria
+      Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea
+    </template-output>
+  </step>
+
+  <step n="8" goal="Risks and test strategy">
+    <template-output file="{default_output_file}">
+      Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step
+      Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases)
+    </template-output>
+  </step>
+
+  <step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
+    <invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
+
+    <!-- Mark epic as contexted -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key "epic-{{epic_id}}"</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="epic key not found in file">
+      <output>⚠️ Could not update epic status: epic-{{epic_id}} not found</output>
+    </check>
+
+    <output>**✅ Tech Spec Generated Successfully, {user_name}!**
+
+**Epic Details:**
+- Epic ID: {{epic_id}}
+- Epic Title: {{epic_title}}
+- Tech Spec File: {{default_output_file}}
+- Epic Status: contexted (was backlog)
+
+**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
+
+**Next Steps:**
+1. Load SM agent and run `create-story` to begin implementing the first story under this epic.
+    </output>
+  </step>
+
+</workflow>
+```

package/src/modules/bmm/workflows/{3-solutioning/tech-spec → 4-implementation/epic-tech-context}/template.md

@@ -1,4 +1,4 @@
-# Technical Specification: {{epic_title}}
+# Epic Technical Specification: {{epic_title}}
 
 Date: {{date}}
 Author: {{user_name}}

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

@@ -0,0 +1,34 @@
+name: tech-spec
+description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
+author: "BMAD BMM"
+
+# Critical variables
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+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)
+recommended_inputs:
+  - prd
+  - gdd
+  - spec
+  - architecture
+  - ux_spec
+  - ux-design
+  - 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
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
+
+standalone: true
+
+web_bundle: false