The dev-story workflow is where v6's just-in-time context approach delivers its primary value, enabling the Developer (DEV) agent to implement stories with expert-level guidance injected directly into their context. This workflow is run EXCLUSIVELY by the DEV agent and operates on a single story that has been prepared by the SM through create-story and enhanced with story-context. The DEV loads both the story specification and the dynamically-generated story context XML, then proceeds through implementation with the combined knowledge of requirements and domain-specific expertise.

The workflow operates with two critical inputs: the story file (created by SM's create-story) containing acceptance criteria, tasks, and requirements; and the story-context XML (generated by SM's story-context) providing just-in-time expertise injection tailored to the story's technical needs. This dual-input approach ensures the developer has both the "what" (from the story) and the "how" (from the context) needed for successful implementation. The workflow iterates through tasks sequentially, implementing code, writing tests, and updating the story document's allowed sections until all tasks are complete.

A critical aspect of v6 flow is that dev-story may be run multiple times for the same story. Initially run to implement the story, it may be run again after code-review identifies issues that need correction. The workflow intelligently resumes from incomplete tasks, making it ideal for both initial implementation and post-review fixes. The DEV agent maintains strict boundaries on what can be modified in the story file—only Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, and Status may be updated, preserving the story's requirements integrity.

Usage

# Developer implements the story with injected context
bmad dev *develop

# Or if returning to fix review issues
bmad dev *develop  # Will resume from incomplete tasks

The DEV runs this workflow:

After SM completes both create-story and story-context
When a story status is "Draft" or "Approved" (ready for development)
After code-review identifies issues requiring fixes
To resume work on a partially completed story

Inputs

Required Files:

Story Document ({story_dir}/story-{epic}.{story}.md): Complete specification including:
- User story statement
- Acceptance criteria (immutable during dev)
- Tasks and subtasks (checkable during implementation)
- Dev Notes section (for context and guidance)
- Status field (Draft → In Progress → Ready for Review)
Story Context XML ({story_dir}/story-{epic}.{story}-context.xml): Domain expertise including:
- Technical patterns and best practices
- Gotchas and common pitfalls
- Testing strategies
- Relevant code references
- Architecture constraints

Configuration:

dev_story_location: Directory containing story files (from bmm/config.yaml)
story_selection_limit: Number of recent stories to show (default: 10)
run_tests_command: Test command (default: auto-detected)
strict: Whether to halt on test failures (default: true)

Outputs

Code Implementation:

Production code satisfying acceptance criteria
Unit, integration, and E2E tests as appropriate
Documentation updates
Migration scripts if needed

Story File Updates (allowed sections only):

Tasks/Subtasks: Checkboxes marked complete as work progresses
Dev Agent Record: Debug log and completion notes
File List: All files created or modified
Change Log: Summary of implementation changes
Status: Updated to "Ready for Review" when complete

Validation:

All tests passing (existing + new)
Acceptance criteria verified
Code quality checks passed
No regression in existing functionality

Key Features

Story-Context Integration: The workflow loads and leverages the story-context XML throughout implementation, providing expert guidance without cluttering the main conversation. This ensures best practices are followed while maintaining developer autonomy.

Task-by-Task Iteration: Implements one task at a time, marking completion before moving to the next. This granular approach enables progress tracking and clean resumption if interrupted or after review feedback.

Strict File Boundaries: Only specific sections of the story file may be modified, preserving requirement integrity. The story's acceptance criteria, main description, and other planning sections remain immutable during development.

Test-Driven Approach: For each task, the workflow emphasizes writing tests that verify acceptance criteria before or alongside implementation, ensuring requirements are actually met.

Resumable Implementation: If the workflow is run again on a story with incomplete tasks (e.g., after code-review finds issues), it intelligently resumes from where it left off rather than starting over.

Integration with v6 Flow

The dev-story workflow is step 3 in the v6 implementation cycle:

SM: create-story (generates the story specification)
SM: story-context (adds JIT technical expertise)
DEV: dev-story ← You are here (initial implementation)
DEV/SR: code-review (validates completion)
If issues found: DEV: dev-story ← May return here for fixes
After epic: retrospective (captures learnings)

This workflow may be executed multiple times for the same story as part of the review-fix cycle. Each execution picks up from incomplete tasks, making it efficient for iterative improvement.

Workflow Process

Phase 1: Story Selection

If story_path provided: Use that story directly
Otherwise: List recent stories from dev_story_location
Parse story structure and validate format
Load corresponding story-context XML

Phase 2: Task Implementation Loop

For each incomplete task:

Plan: Log approach in Dev Agent Record
Implement: Write code following story-context guidance
Test: Create tests verifying acceptance criteria
Validate: Run tests and quality checks
Update: Mark task complete, update File List

Phase 3: Completion

Verify all tasks completed
Run full test suite
Update Status to "Ready for Review"
Add completion notes to Dev Agent Record

Story File Structure

The workflow expects stories with this structure:

# Story {epic}.{story}: {Title}

**Status**: Draft|In Progress|Ready for Review|Done
**Epic**: {epic_number}
**Estimated Effort**: {estimate}

## Story

As a {role}, I want to {action} so that {benefit}

## Acceptance Criteria

- [ ] AC1...
- [ ] AC2...

## Tasks and Subtasks

- [ ] Task 1
  - [ ] Subtask 1.1
- [ ] Task 2

## Dev Notes

{Context and guidance from story creation}

## Dev Agent Record

### Debug Log

{Implementation notes added during development}

### Completion Notes

{Summary added when complete}

## File List

{Files created/modified}

## Change Log

{Implementation summary}

Best Practices

Load Context First: Always ensure the story-context XML is loaded at the start. This provides the expert guidance needed throughout implementation.

Follow Task Order: Implement tasks in the order listed. Dependencies are typically structured in the task sequence.

Test Each Task: Don't wait until the end to write tests. Test each task as you complete it to ensure it meets acceptance criteria.

Update Incrementally: Update the story file after each task completion rather than batching updates at the end.

Respect Boundaries: Never modify acceptance criteria or story description. If they seem wrong, that's a code-review or correct-course issue, not a dev-story fix.

Use Context Guidance: Actively reference the story-context for patterns, gotchas, and best practices. It's there to help you succeed.

Troubleshooting

Story Not Found: Ensure story exists in dev_story_location and follows naming pattern story-{epic}.{story}.md

Context XML Missing: The story-context workflow must be run first. Check for story-{epic}.{story}-context.xml

Tests Failing: If strict mode is on, the workflow halts. Fix tests before continuing or set strict=false for development iteration.

Can't Modify Story Section: Remember only Tasks, Dev Agent Record, File List, Change Log, and Status can be modified. Other sections are immutable.

Resuming After Review: If code-review found issues, the workflow automatically picks up from incomplete tasks when run again.

create-story: Creates the story specification (run by SM)
story-context: Generates the context XML (run by SM)
code-review: Validates implementation (run by SR/DEV)
correct-course: Handles major issues or scope changes (run by SM)

README.md

Dev Story Workflow