ma-agents 3.6.2 → 3.9.0

package/lib/bmad-extension-plugin/skills/bmad-dev-story/workflow.md

@@ -0,0 +1,548 @@
+# Dev Story Workflow
+
+**Goal:** Execute story implementation following a context filled story spec file.
+
+**Your Role:** Developer implementing the story.
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
+- Execute ALL steps in exact order; do NOT skip steps
+- 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.
+- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
+- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `story_file` = `` (explicit story path; auto-discovered if empty)
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## Backend Routing
+
+Before executing any status-update operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   a. Perform the Jira operation: Find the Jira issue matching the item ID in project `{jira_project_key}` at `{jira_url}` (search by issue key or summary). Transition the issue to the new status using the Jira issue transition API. Map canonical status to Jira workflow status: backlog → Backlog/Open, ready-for-dev → To Do/Selected for Development, in-progress → In Progress, review → In Review/Code Review, done → Done/Resolved, on-hold → On Hold/Blocked, cancelled → Won't Do/Cancelled.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
+## EXECUTION
+
+<workflow>
+  <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>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>
+
+  <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 anchor="task_check" />
+    </check>
+
+    <!-- Sprint-based story discovery (unified sprint-status.yaml schema) -->
+    <check if="{{sprint_status}} file exists">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Search active sprints first, then planning sprints, then backlog -->
+      <action>Search for first item with status "ready-for-dev" using this priority order:
+        1. Iterate sprints map entries where sprint.status == "active" (skip "closed" sprints);
+           for each active sprint, iterate its items array and find first item where item.status == "ready-for-dev"
+        2. If not found, iterate sprints map entries where sprint.status == "planning";
+           for each planning sprint, iterate its items array and find first item where item.status == "ready-for-dev"
+        3. If not found, iterate the backlog array and find first item where item.status == "ready-for-dev"
+        Note: items in "closed" sprints are SKIPPED entirely
+      </action>
+
+      <action>When a ready-for-dev item is found:
+        - Extract item.id as the story_key
+        - Record location context:
+          * If found in a sprint: location_context = "in {sprint-id}" (e.g., "in sprint-3")
+          * If found in backlog: location_context = "in backlog (unassigned)"
+        - Note the item.type field ("story" or "bug") — no key pattern matching needed
+      </action>
+
+      <check if="no ready-for-dev item found in any sprint or backlog">
+        <action>Build sprint status summary from the unified schema:
+          - Count active/planning/closed sprints
+          - Count total backlog items and their statuses
+          - List any in-progress items
+        </action>
+        <output>No ready-for-dev stories found in sprint-status.yaml
+
+          **Current Sprint Status:** {{sprint_status_summary}}
+
+          **What would you like to do?**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories before development (recommended quality check)
+          3. Specify a particular story file to develop (provide full path)
+          4. Check {{sprint_status}} file to see current sprint status
+
+          **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
+          check.
+        </output>
+        <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>Provide the story file path to develop:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+
+        <check if="user chooses '4'">
+          <output>Loading {{sprint_status}} for detailed status review...</output>
+          <action>Display detailed sprint status analysis</action>
+          <action>HALT - User can review sprint status and provide story path</action>
+        </check>
+
+        <check if="user provides story file path">
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+      </check>
+    </check>
+
+    <!-- Non-sprint story discovery -->
+    <check if="{{sprint_status}} file does NOT exist">
+      <action>Search {implementation_artifacts} for stories directly</action>
+      <action>Find stories with "ready-for-dev" status in files</action>
+      <action>Look for story files matching pattern: *-*-*.md</action>
+      <action>Read each candidate story file to check Status section</action>
+
+      <check if="no ready-for-dev stories found in story files">
+        <output>No ready-for-dev stories found
+
+          **Available Options:**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories
+          3. Specify which story to develop
+        </output>
+        <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>It's unclear what story you want developed. Please provide the full path to the story file:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <action>Continue with provided story file</action>
+        </check>
+      </check>
+
+      <check if="ready-for-dev story found in files">
+        <action>Use discovered story file and extract story_key</action>
+      </check>
+    </check>
+
+    <action>Store the found story_key (e.g., "17-10-rework-generate-backlog") for later status updates</action>
+    <action>Store the found location_context (e.g., "in sprint-3" or "in backlog") for later status updates</action>
+    <action>If location_context was not set (e.g., story_path was provided explicitly), set location_context = "unknown location"</action>
+    <action>Find matching story file in {implementation_artifacts} 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>Load comprehensive context from story file's Dev Notes section</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+
+    <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="2" goal="Load project context and story information">
+    <critical>Load all available context to inform implementation</critical>
+
+    <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+    <action>Load comprehensive context from story file's Dev Notes section</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+    <output>Context Loaded
+      Story and project context available for implementation
+    </output>
+  </step>
+
+  <step n="3" 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}}
+        Story Status: {{current_status}}
+        First incomplete task: {{first_task_description}}
+      </output>
+    </check>
+  </step>
+
+  <step n="4" goal="Mark story in-progress" tag="sprint-status">
+    <check if="{{sprint_status}} file exists">
+      <critical>MUST read COMPLETE sprint-status.yaml file to preserve all content during write-back</critical>
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Cross-section search for the story item by id -->
+      <action>Search for item with id == {{story_key}} across BOTH backlog and sprints sections:
+        1. Search all sprints map entries (active sprints first, then planning; skip closed sprints entirely):
+           - Iterate each non-closed sprint's items array, match item.id == {{story_key}}
+        2. If not found in any sprint, search backlog array:
+           - Iterate items, match item.id == {{story_key}}
+        3. When item is found: update {{location_context}} = sprint id (e.g., "in sprint-3") or "in backlog (unassigned)"
+        4. If not found in either location: output error and exit workflow without writing
+      </action>
+
+      <check if="item found AND (current item.status == 'ready-for-dev' OR review_continuation == true)">
+        <action>Update item.status = "in-progress" in-place (preserve all other fields: id, type, epic, title, priority if present, severity)</action>
+        <action>Update last_updated metadata field to current ISO-8601 timestamp</action>
+        <action>Write back the FULL file preserving ALL sections (epics, backlog, sprints) and ALL comments</action>
+        <output>Starting work on story {{story_key}} ({{location_context}})
+          Status updated: ready-for-dev -> in-progress
+        </output>
+      </check>
+
+      <check if="item found AND current item.status == 'in-progress'">
+        <output>Resuming work on story {{story_key}} ({{location_context}})
+          Story is already marked in-progress
+        </output>
+      </check>
+
+      <check if="item found AND current item.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>
+
+      <check if="item NOT found in any section of sprint-status.yaml">
+        <!-- Check done archive -->
+        <action>Check for file at {implementation_artifacts}/done/{{story_key}}.md</action>
+        <check if="done archive file found">
+          <output>HALT: Story {{story_key}} has been archived (done). It cannot be developed again without manual re-introduction to the backlog.</output>
+          <action>HALT</action>
+        </check>
+        <check if="done archive file NOT found">
+          <output>HALT: Story {{story_key}} not found in sprint-status.yaml. It may not yet have been added to the backlog. Run sprint planning or generate-backlog first.</output>
+          <action>HALT</action>
+        </check>
+      </check>
+
+      <action>Store {{current_sprint_status}} for later use (the item's current status or "found-and-updated")</action>
+    </check>
+
+    <check if="{{sprint_status}} file does NOT exist">
+      <output>No sprint status file exists - story progress will be tracked in story file only</output>
+      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+    </check>
+  </step>
+
+  <step n="5" goal="Implement task following red-green-refactor cycle">
+    <critical>FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION</critical>
+
+    <action>Review the current task/subtask from the story file - this is your authoritative implementation guide</action>
+    <action>Plan implementation following red-green-refactor cycle</action>
+
+    <!-- RED PHASE -->
+    <action>Write FAILING tests first for the task/subtask functionality</action>
+    <action>Confirm tests fail before implementation - this validates test correctness</action>
+
+    <!-- GREEN PHASE -->
+    <action>Implement MINIMAL code to make tests pass</action>
+    <action>Run tests to confirm they now pass</action>
+    <action>Handle error conditions and edge cases as specified in task/subtask</action>
+
+    <!-- REFACTOR PHASE -->
+    <action>Improve code structure while keeping tests green</action>
+    <action>Ensure code follows architecture patterns and coding standards from Dev Notes</action>
+
+    <action>Document technical approach and decisions in Dev Agent Record → Implementation Plan</action>
+
+    <action if="new dependencies required beyond story specifications">HALT: "Additional dependencies need user approval"</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>NEVER implement anything not mapped to a specific task/subtask in the story file</critical>
+    <critical>NEVER proceed to next task until current task/subtask is complete AND tests pass</critical>
+    <critical>Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition</critical>
+    <critical>Do NOT propose to pause for review until Step 9 completion gates are satisfied</critical>
+  </step>
+
+  <step n="6" 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 specified in story requirements</action>
+    <action>Include end-to-end tests for critical user flows when story requirements demand them</action>
+    <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action>
+  </step>
+
+  <step n="7" goal="Run validations and tests">
+    <action>Determine how to run tests for this repo (infer test framework from project structure)</action>
+    <action>Run all existing tests to ensure no regressions</action>
+    <action>Run the new tests to verify implementation correctness</action>
+    <action>Run linting and code quality checks if configured in project</action>
+    <action>Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly</action>
+    <action if="regression tests fail">STOP and fix before continuing - identify breaking changes immediately</action>
+    <action if="new tests fail">STOP and fix before continuing - ensure implementation correctness</action>
+  </step>
+
+  <step n="8" goal="Validate and mark task complete ONLY when fully done">
+    <critical>NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING</critical>
+
+    <!-- VALIDATION GATES -->
+    <action>Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100%</action>
+    <action>Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features</action>
+    <action>Validate that ALL acceptance criteria related to this task are satisfied</action>
+    <action>Run full test suite to ensure NO regressions introduced</action>
+
+    <!-- REVIEW FOLLOW-UP HANDLING -->
+    <check if="task is review follow-up (has [AI-Review] prefix)">
+      <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>
+
+    <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
+    <check if="ALL validation gates pass AND tests ACTUALLY exist and pass">
+      <action>ONLY THEN mark the task (and subtasks) checkbox with [x]</action>
+      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root)</action>
+      <action>Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested</action>
+    </check>
+
+    <check if="ANY validation fails">
+      <action>DO NOT mark task complete - fix issues first</action>
+      <action>HALT if unable to fix validation failures</action>
+    </check>
+
+    <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>
+    <action>Determine if more incomplete tasks remain</action>
+    <action if="more tasks remain">
+      <goto step="5">Next task</goto>
+    </action>
+    <action if="no tasks remain">
+      <goto step="9">Completion</goto>
+    </action>
+  </step>
+
+  <step n="9" 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 enhanced definition-of-done validation</action>
+    <action>Update the story Status to: "review"</action>
+
+    <!-- Enhanced Definition of Done Validation -->
+    <action>Validate definition-of-done checklist with essential requirements:
+      - All tasks/subtasks marked complete with [x]
+      - Implementation satisfies every Acceptance Criterion
+      - Unit tests for core functionality added/updated
+      - Integration tests for component interactions added when required
+      - End-to-end tests for critical flows added when story demands them
+      - All tests pass (no regressions, new tests successful)
+      - Code quality checks pass (linting, static analysis if configured)
+      - File List includes every new/modified/deleted file (relative paths)
+      - Dev Agent Record contains implementation notes
+      - Change Log includes summary of changes
+      - Only permitted story sections were modified
+    </action>
+
+    <!-- Mark story ready for review - sprint status conditional -->
+    <check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'">
+      <critical>MUST read COMPLETE sprint-status.yaml file to preserve all content during write-back</critical>
+      <action>Load the FULL file: {sprint_status}</action>
+      <action>Parse the full unified schema: metadata fields, epics section, backlog array, and sprints map</action>
+
+      <!-- Cross-section search for the story item by id -->
+      <action>Search for item with id == {{story_key}} across BOTH backlog and sprints sections:
+        1. Search all sprints map entries (active sprints first, then planning; skip closed sprints entirely):
+           - Iterate each non-closed sprint's items array, match item.id == {{story_key}}
+        2. If not found in any sprint, search backlog array:
+           - Iterate items, match item.id == {{story_key}}
+        3. When item is found: update {{location_context}} = sprint id (e.g., "in sprint-3") or "in backlog (unassigned)"
+        4. If not found in either location: output error and exit workflow without writing
+      </action>
+
+      <check if="item found">
+        <check if="item.status is NOT 'in-progress'">
+          <output>⚠️ Warning: Story {{story_key}} has status "{{item.status}}", expected "in-progress". Updating to "review" anyway — verify this is intentional.</output>
+        </check>
+        <action>Update item.status = "review" in-place (preserve all other fields: id, type, epic, title, priority if present, severity)</action>
+        <action>Update last_updated metadata field to current ISO-8601 timestamp</action>
+        <action>Write back the FULL file preserving ALL sections (epics, backlog, sprints) and ALL comments</action>
+        <output>Story status updated to "review" in sprint-status.yaml ({{location_context}})</output>
+      </check>
+
+      <check if="item NOT found">
+        <!-- Non-blocking warning — story file already updated to "review" above -->
+        <output>Story file updated to "review", but sprint-status.yaml update failed: {{story_key}} not found.
+          Sprint-status.yaml may be out of sync.
+        </output>
+      </check>
+    </check>
+
+    <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
+      <output>Story status updated to "review" in story file (no sprint tracking configured)</output>
+    </check>
+
+    <!-- Final validation gates -->
+    <action if="any task is incomplete">HALT - Complete remaining tasks before marking ready for review</action>
+    <action if="regression failures exist">HALT - Fix regression issues before completing</action>
+    <action if="File List is incomplete">HALT - Update File List with all changed files</action>
+    <action if="definition-of-done validation fails">HALT - Address DoD failures before completing</action>
+  </step>
+
+  <step n="10" goal="Completion communication and user support">
+    <action>Execute the enhanced definition-of-done checklist using the validation framework</action>
+    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</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")</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>Recommended next steps (flexible based on project setup):
+      - Review the implemented story and test the changes
+      - Verify all acceptance criteria are met
+      - Ensure deployment readiness if applicable
+      - Run `code-review` workflow for peer review
+      - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests
+    </action>
+
+    <output>Tip: For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
+    <check if="{sprint_status} file exists">
+      <action>Suggest checking {sprint_status} to see project progress</action>
+    </check>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
+  </step>
+
+</workflow>

package/lib/bmad-extension-plugin/skills/bmad-sprint-planning/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-sprint-planning
+description: 'Bootstrap or update the unified sprint-status.yaml from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
+---
+
+Follow the instructions in ./workflow.md.

package/lib/bmad-extension-plugin/skills/bmad-sprint-planning/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: bmad-sprint-planning
+module: ma-skills

package/lib/bmad-extension-plugin/skills/bmad-sprint-planning/checklist.md

@@ -0,0 +1,74 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation — Unified Three-Section Schema
+
+### File Structure
+
+- [ ] File is valid YAML syntax
+- [ ] Exactly 6 metadata fields present: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
+- [ ] Exactly 3 data sections: `epics` (map), `backlog` (array), `sprints` (map)
+- [ ] No `development_status` section present (old flat format must not appear)
+
+### Epics Section Validation
+
+- [ ] Every epic found in `epics.md` (or sharded epic files) has a corresponding entry in the `epics` section
+- [ ] Every epic entry has both `status` and `retrospective` fields
+- [ ] All epic `status` values are legal: `backlog`, `in-progress`, `done`, `on-hold`, `cancelled`
+- [ ] All epic `retrospective` values are legal: `optional`, `done`, or `null`
+- [ ] Epic keys follow the pattern `epic-N` (e.g., `epic-1`, `epic-17`)
+- [ ] Epic statuses were not downgraded from existing values (never-downgrade rule applied)
+
+### Backlog Section Validation
+
+- [ ] Every story in `epics.md` appears in exactly one location: `backlog` array, a sprint's `items` array, or `done/` folder
+- [ ] No item ID appears in more than one active location (single-location invariant)
+- [ ] Every backlog item has all 7 required fields: `id`, `type`, `epic`, `title`, `priority`, `status`, `severity`
+- [ ] `type` is either `story` or `bug` for every item
+- [ ] `severity` is `null` for all story items
+- [ ] Bug items have a non-null `severity` value (`critical`, `high`, `medium`, or `low`)
+- [ ] All item `status` values are legal: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`, `on-hold`, `cancelled`
+- [ ] Backlog `priority` values are sequential integers starting at 1 (position 0 = `priority: 1`)
+- [ ] `priority` field values match array position (array[0].priority == 1, array[1].priority == 2, etc.)
+- [ ] Done items (in `done/` folder) are NOT present in the backlog array
+- [ ] Existing backlog items are preserved unchanged (refresh mode: status, priority, all fields preserved)
+- [ ] New items are appended at the end of the backlog (refresh mode)
+
+### Sprints Section Validation
+
+- [ ] `sprints` section is present (may be empty map `{}`)
+- [ ] Sprint keys follow the pattern `sprint-N`
+- [ ] Every sprint entry has all 6 required fields: `name`, `status`, `capacity`, `start`, `end`, `items`
+- [ ] Sprint items do NOT have a `priority` field (priority is backlog-only)
+- [ ] At most one sprint has `status: active`
+- [ ] Sprints section is unchanged from existing file (refresh mode — this skill does NOT modify sprints)
+
+### Metadata Validation
+
+- [ ] `generated` timestamp is present and in ISO-8601 format
+- [ ] `last_updated` timestamp is present and set to current time
+- [ ] `generated` timestamp is unchanged from existing file (refresh mode — never overwritten)
+- [ ] `project` matches `project_name` from config
+- [ ] `project_key` is set (default: `NOKEY`)
+- [ ] `tracking_system` is `file-system` (or a valid alternative)
+- [ ] `story_location` matches `implementation_artifacts` path from config
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml epics section:
+
+```
+Epic Files Contains:                Sprint Status epics Contains:
+✓ Epic 1: Some Feature              ✓ epic-1: {status: backlog, retrospective: optional}
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth in backlog or sprint or done/
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt in backlog or sprint or done/
+✓ Epic 2: Another Feature           ✓ epic-2: {status: backlog, retrospective: optional}
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model in backlog or sprint or done/
+```
+
+Note: Unlike the old format, each epic does NOT have a separate retrospective key — retrospective is a field on the epic entry.
+
+### Final Count Check
+
+- [ ] Total count of epics in `epics` section matches count in epic files
+- [ ] Total count of stories in `backlog` + all sprints + `done/` folder matches count in epic files
+- [ ] Total count of bugs in `backlog` + all sprints + `done/` folder matches count of `bug-*.md` files