Execute a single user story end-to-end: select the next incomplete task, implement it following repo standards, write tests, run validations, and update the story file — all in a v6 action workflow.

Key Features

Auto-discovers recent stories from config dev_story_location
Presents a selectable list of latest stories
Iterates task-by-task until the story is complete
Enforces acceptance criteria and test coverage
Restricts edits to approved sections of the story file

How to Invoke

By workflow name (if your runner supports it):
- workflow dev-story
By path:
- workflow {project-root}/bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml

Inputs and Variables

story_path (optional): Explicit path to a story markdown file. If omitted, the workflow will auto-discover stories.
run_tests_command (optional, default: auto): Command used to run tests. When auto, the runner should infer (e.g., npm test, pnpm test, yarn test, pytest, go test, etc.).
strict (default: true): If true, halt on validation or test failures.
story_dir (from config): Resolved from {project-root}/bmad/bmm/config.yaml key dev_story_location.
story_selection_limit (default: 10): Number of recent stories to show when selecting.

Config

Ensure your BMM config defines the stories directory:

# bmad/bmm/config.yaml
output_folder: ./outputs
user_name: Your Name
communication_language: en
# Directory where story markdown files live
dev_story_location: ./docs/stories

Workflow Summary

Load story and select next task
- Use story_path if provided; otherwise list most recent stories from dev_story_location
- Parse Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status
- Pick the first incomplete task
Plan and implement
- Log brief plan in Dev Agent Record → Debug Log
- Implement task and subtasks, handle edge cases
Write tests
- Add unit, integration, and E2E (as applicable)
Run validations and tests
- Run existing tests for regressions + new tests
- Lint/quality checks if configured; ensure ACs met
Mark task complete and update story
- Check [x] on task(s), update File List, add Completion Notes and Change Log
- Repeat from step 1 if tasks remain
Completion sequence
- Verify all tasks done, run full regression suite, update Status → "Ready for Review"
Validation and handoff (optional)
- Optionally run validation and finalize notes

Allowed Story File Modifications

Only these sections may be changed by this workflow:

Tasks/Subtasks checkboxes
Dev Agent Record (Debug Log, Completion Notes)
File List
Change Log
Status

Files in This Workflow

workflow.yaml — configuration and variables
instructions.md — execution logic and steps
checklist.md — validation checklist for completion

story-context — Build dev context for a single story
story-context-batch — Process multiple stories and update status

README.md

Dev Story

Purpose