bmad-dev-story

name	bmad-dev-story
description	Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan" Use when this capability is needed.
metadata	{"author":"CDCgov"}

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 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: python3 {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

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

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. Begin the workflow below.

Paths

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

Execution

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 9 decides completion. User skill level ({user_skill_level}) affects conversation style ONLY, not code updates. Use {{story_path}} directly Read COMPLETE story file Extract story_key from filename or metadata

<!-- 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 `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., "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>

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

Load all available context to inform implementation

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

Determine if this is a fresh start or continuation after code review

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

Load the FULL file: {{sprint_status}} Read all development_status entries to find {{story_key}} Get current status value for development_status[{{story_key}}]

  <check if="current status == 'ready-for-dev' OR review_continuation == true">
    <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: 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>

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

FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION

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