ucg-dev-story git:20261024.35a60a5A

Immutable. This exact content never changes and is served at /api/v1/blob/6ca99a77305290d2.

---
name: ucg-dev-story
description: "Implements an UltraCode Goal story file to completion (red-green-refactor, every task checked, the story set to review), or a decomposed child's claimed acceptance criteria with no story file written, adapted from BMAD Method's dev-story workflow so a run needs no deprecated BMAD shim. Use when the ultracode-goal skill delegates a story's implementation to it, or when invoked by name; not for implementation outside an UltraCode Goal run."
---

<!-- Adapted for UltraCode Goal from BMAD Method 6.12.4, src/bmm-skills/v6-shims/bmad-dev-story. Copyright (c) 2025 BMad Code, LLC. MIT License: see LICENSE.md in this folder. UltraCode Goal ships this copy so a run never depends on BMAD's deprecated shim, which BMAD removes at v7. -->

# 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: YAML frontmatter `baseline_commit`, 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 9 decides completion.
- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.

## Conventions

- Bare paths (e.g. `steps/step-01-init.md`) resolve from the skill root.
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
- `{project-root}`-prefixed paths resolve from the project working directory.
- `{skill-name}` resolves to the skill directory's basename.

## On Activation

### Step 1: Resolve the Workflow Block

Run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`

**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. `{skill-root}/customize.toml`: defaults
2. `{project-root}/_bmad/custom/{skill-name}.toml`: team overrides
3. `{project-root}/_bmad/custom/{skill-name}.user.toml`: personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.

### Step 2: Execute Prepend Steps

Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.

### Step 3: Load Persistent Facts

Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}`; load the referenced contents as facts. All other entries are facts verbatim.

### Step 4: Load Config

Run `uv run --no-project {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` and resolve:

- `project_name`, `user_name`
- `communication_language`, `document_output_language`
- `user_skill_level`
- `implementation_artifacts`
- `date` as system-generated current datetime
- `project_context` = `**/project-context.md` (load if exists)

If that script is absent or fails, read the same keys from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (the root and the `bmm` section), falling back to `{project-root}/_bmad/bmm/config.yaml`.

### Step 5: Greet the User

Greet `{user_name}`, speaking in `{communication_language}`.

### Step 6: Execute Append Steps

Execute each entry in `{workflow.activation_steps_append}` in order.

Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

## Paths

- `story_file` = `` (explicit story path; auto-discovered if empty)
- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`

## Decomposed Child

An UltraCode Goal run splits a story too large to drive into child rows in `sprint-status.yaml`, above the parent's row, and sets the parent's row to `done`. Each child row claims some of the parent's acceptance criteria by AC id and has no story file of its own: the parent's story file holds the text of every criterion. To implement a child, the run passes these inputs in place of a story path:

- `{{story_key}}`: the child's own sprint-status key.
- `{{parent_story_path}}`: the parent's story file, read only.
- `{{claimed_acs}}`: the parent AC ids the child's row claims.
- `{{review_findings}}`: on a re-loop only, the reasons of the gate verdict that sent the child back and the findings of that cycle's reviews.

When `{{parent_story_path}}` is provided, the workflow runs as written except:

- **Read the parent's file for the claimed ACs' text and its Dev Notes only.** Steps 1 and 2 take from it the text of each AC in `{{claimed_acs}}`, and its Dev Notes as the architecture and coding guidance steps 5 and 6 follow. Its tasks and its other ACs are the parent's: never work through them. Keep `{{story_key}}` as given, never taken from that file's name.
- **Write no story file.** Never edit the parent's file and never create `{{story_key}}.md`: a child must never get one. Skip every write to a story file (`baseline_commit`, checkboxes, Dev Agent Record, File List, Change Log, Status), and give the File List and the completion notes in step 10's summary instead.
- **Implement the claimed ACs only.** Where steps 1 and 5 to 9 work through the story's tasks and subtasks, work through the claimed ACs in the order `{{claimed_acs}}` gives them: implement and test each in turn, and track their completion in this session. A parent AC the child does not claim belongs to a sibling: leave it alone.
- **Take review findings from the input.** Step 3 sets review_continuation = true when `{{review_findings}}` is given, and false otherwise, and never reads a review section of the parent's file. Each finding is a review follow-up: fix and test it before re-checking the claimed ACs.
- **Check the definition of done against the child.** At steps 9 and 10 the definition of done and `checklist.md` read the claimed ACs for the story's tasks and acceptance criteria, and step 10's summary for the File List and the Dev Agent Record. The items only a story file can meet (the Change Log, the story's Status, the story sections modified) do not apply: mark them N/A, never failed.
- **Move only the child's row.** Step 4 sets development_status[{{story_key}}] to `in-progress` and step 9 sets it to `review`. The parent's row stays `done`.
- **HALT rather than repair.** HALT when the parent's file cannot be read, when `sprint-status.yaml` has no row for `{{story_key}}`, when an id in `{{claimed_acs}}` names no AC in the parent's file, or when a claimed AC is too vague to implement, and name the ACs concerned. Never edit the parent's file to fix one.

## 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: YAML frontmatter `baseline_commit`, 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 9 decides completion.</critical>
  <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
  <critical>When {{parent_story_path}} is provided, the story is a decomposed child: the "Decomposed Child" section above governs every step, and no step writes a story file</critical>

  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
    <check if="{{parent_story_path}} is provided">
      <action>Keep {{story_key}} as given: it is the child's sprint-status key</action>
      <action>Read COMPLETE parent story file at {{parent_story_path}}, for the text of the ACs in {{claimed_acs}} and its Dev Notes only</action>
      <goto anchor="task_check" />
    </check>

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

          **Current Sprint Status:** {{sprint_status_summary}}

          **What would you like to do?**
          1. Run `ucg-create-story` to create next story from epics with comprehensive context
          2. Check existing stories against the `ucg-create-story` checklist 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 checking them against the `ucg-create-story` checklist 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 ucg-create-story to create next story</action>
        </check>

        <check if="user chooses '2'">
          <action>HALT - Check existing stories against the ucg-create-story checklist</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 `ucg-create-story` to create next story from epics with comprehensive context
          2. Check existing stories against the `ucg-create-story` checklist
          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 ucg-create-story to create next story</action>
        </check>

        <check if="user chooses '2'">
          <action>HALT - Check existing stories against the ucg-create-story checklist</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., "1-2-user-authentication") for later status updates</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>

    <check if="{{parent_story_path}} is provided">
      <action>Take the ACs in {{claimed_acs}}, in the order given, as the work list in place of Tasks/Subtasks: the parent's tasks are never this child's</action>
      <action if="parent story file inaccessible, an id in {{claimed_acs}} names no AC in it, or a claimed AC is too vague to implement">HALT and name the ACs concerned</action>
    </check>

    <check if="{{parent_story_path}} is not provided">
      <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>

      <action if="no incomplete tasks">
        <goto step="9">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>
    </check>
  </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>

    <check if="{{parent_story_path}} is provided">
      <action>Set review_continuation = true when {{review_findings}} is given, and false otherwise: a child's findings arrive as that input, never from the parent's file</action>
      <action>Set {{pending_review_items}} to the findings in {{review_findings}}, or empty</action>
      <goto step="4">Mark story in-progress</goto>
    </check>

    <check if="{{parent_story_path}} is not provided">
      <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>

    <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">
    <action>If story file YAML frontmatter already contains `baseline_commit`, preserve the existing value and do not overwrite it</action>

    <check if="{{sprint_status}} file exists">
      <action>Load the FULL file: {{sprint_status}}</action>
      <action>Read all development_status entries to find {{story_key}}</action>
      <action>Set {{current_status}} to development_status[{{story_key}}]</action>
    </check>

    <check if="{{sprint_status}} file does NOT exist">
      <action>Set {{current_status}} to the story file Status section value</action>
    </check>

    <check if="{{current_status}} == 'ready-for-dev' AND story file YAML frontmatter does NOT contain baseline_commit AND {{parent_story_path}} is not provided">
      <action>Run `git rev-parse HEAD` to capture current commit into {{baseline_commit}}; if git/version control is unavailable, set {{baseline_commit}} = `NO_VCS`</action>
      <action>If story file YAML frontmatter exists, add `baseline_commit: {{baseline_commit}}` to the frontmatter</action>
      <action>If story file has no YAML frontmatter, create frontmatter at the top containing only `baseline_commit: {{baseline_commit}}`</action>
    </check>

    <check if="{{sprint_status}} file exists">
      <check if="{{current_status}} == 'ready-for-dev' OR (review_continuation == true AND {{current_status}} != 'in-progress') OR ({{parent_story_path}} is provided AND {{current_status}} != 'in-progress')">
        <action>Update the story in the sprint status report to = "in-progress"</action>
        <action>Update last_updated field to current date</action>
        <output>🚀 Starting work on story {{story_key}}
          Status updated: {{current_status}} → 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 AND {{parent_story_path}} is not provided">
        <output>⚠️ Unexpected story status: {{current_status}}
          Expected ready-for-dev or in-progress. Continuing anyway...
        </output>
      </check>

      <action>Store {{current_sprint_status}} for later use</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 if="{{parent_story_path}} is not provided">Document technical approach and decisions in Dev Agent Record → Implementation Plan</action>
    <action if="{{parent_story_path}} is provided">Keep the technical approach and decisions for step 10's summary</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="{{parent_story_path}} is provided AND the work item is a finding from {{review_findings}}">
      <action>Add it to {{resolved_review_items}} once fixed and tested; mark nothing in a file</action>
    </check>

    <check if="task is review follow-up (has [AI-Review] prefix) AND {{parent_story_path}} is not provided">
      <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 AND {{parent_story_path}} is not provided">
      <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="ALL validation gates pass AND tests ACTUALLY exist and pass AND {{parent_story_path}} is provided">
      <action>ONLY THEN record the claimed AC as complete in this session</action>
      <action>Add ALL new, modified, or deleted files (paths relative to repo root) to the File List step 10's summary gives, and what was ACTUALLY implemented and tested to its completion notes</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 and {{parent_story_path}} is not provided">
      <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 if="{{parent_story_path}} is not provided">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 if="{{parent_story_path}} is not provided">Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
    <action if="{{parent_story_path}} is provided">Verify every AC in {{claimed_acs}} is implemented and tested, and every finding in {{review_findings}} resolved</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 if="{{parent_story_path}} is not provided">Update the story Status to: "review"</action>

    <!-- Enhanced Definition of Done Validation -->
    <action if="{{parent_story_path}} is provided">Validate the list below against the child, as the "Decomposed Child" section says: the claimed ACs stand for the tasks and the Acceptance Criteria, step 10's summary for the File List and the Dev Agent Record, and the Change Log and story-section items are N/A</action>
    <action if="{{parent_story_path}} is not provided">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'">
      <action>Load the FULL file: {sprint_status}</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>Update last_updated field to current date</action>
      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
      <output>✅ Story status updated to "review" in sprint-status.yaml</output>
    </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>

    <check if="story key not found in sprint status">
      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found

        Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
      </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 if="{{parent_story_path}} is not provided">Prepare a concise summary in Dev Agent Record → Completion Notes</action>
    <action if="{{parent_story_path}} is provided">Prepare the record a child has in place of a story file: the File List (every new, modified, or deleted file, relative to the repo root) and the completion notes, both given in this summary</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 if="{{parent_story_path}} is not provided">Provide the story file path and current status (now "review")</action>
    <action if="{{parent_story_path}} is provided">Provide {{story_key}}, the parent story file path, the claimed ACs and the child row's 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>
  <action>Run: `uv run --no-project {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`; if the script fails, take `on_complete` from the `workflow` block resolved on activation. If the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
  </step>

</workflow>