ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc status updates

Browse Source
This commit is contained in:
Brian Madison
2025-10-04 01:29:40 -05:00
parent a747017520
commit 46cabf72cd
315 changed files with 1 additions and 38707 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
bmad/bmm/workflows/4-implementation/dev-story/README.md
View File

@@ -1,206 +0,0 @@
# Dev Story Workflow
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 review-story 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
```bash
# 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 review-story 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 review-story 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:
1. SM: create-story (generates the story specification)
2. SM: story-context (adds JIT technical expertise)
3. **DEV: dev-story** ← You are here (initial implementation)
4. DEV/SR: review-story (validates completion)
5. If issues found: **DEV: dev-story** ← May return here for fixes
6. 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:
1. **Plan**: Log approach in Dev Agent Record
2. **Implement**: Write code following story-context guidance
3. **Test**: Create tests verifying acceptance criteria
4. **Validate**: Run tests and quality checks
5. **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:
```markdown
# 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 review-story 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 review-story found issues, the workflow automatically picks up from incomplete tasks when run again.
## Related Workflows
- **create-story**: Creates the story specification (run by SM)
- **story-context**: Generates the context XML (run by SM)
- **review-story**: Validates implementation (run by SR/DEV)
- **correct-course**: Handles major issues or scope changes (run by SM)

38
bmad/bmm/workflows/4-implementation/dev-story/checklist.md
View File

@@ -1,38 +0,0 @@
---
title: 'Dev Story Completion Checklist'
validation-target: 'Story markdown ({{story_path}})'
required-inputs:
- 'Story markdown file with Tasks/Subtasks, Acceptance Criteria'
optional-inputs:
- 'Test results output (if saved)'
- 'CI logs (if applicable)'
validation-rules:
- 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status'
---
# Dev Story Completion Checklist
## Tasks Completion
- [ ] All tasks and subtasks for this story are marked complete with [x]
- [ ] Implementation aligns with every Acceptance Criterion in the story
## Tests and Quality
- [ ] Unit tests added/updated for core functionality changed by this story
- [ ] Integration tests added/updated when component interactions are affected
- [ ] End-to-end tests created for critical user flows, if applicable
- [ ] All tests pass locally (no regressions introduced)
- [ ] Linting and static checks (if configured) pass
## Story File Updates
- [ ] File List section includes every new/modified/deleted file (paths relative to repo root)
- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work
- [ ] Change Log includes a brief summary of what changed
- [ ] Only permitted sections of the story file were modified
## Final Status
- [ ] Regression suite executed successfully
- [ ] Story Status is set to "Ready for Review"

87
bmad/bmm/workflows/4-implementation/dev-story/instructions.md
View File

@@ -1,87 +0,0 @@
# Develop Story - Workflow Instructions
```xml
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</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>If {{run_until_complete}} == true, run non-interactively: do not pause between steps unless a HALT condition is reached or explicit user approval is required for unapproved dependencies.</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) or a HALT condition is triggered.</critical>
<critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
<workflow>
<step n="1" goal="Load story and select next task">
<action>If {{story_path}} was explicitly provided and is valid → use it. Otherwise, attempt auto-discovery.</action>
<action>Auto-discovery: Read {{story_dir}} from config (dev_story_location). If invalid/missing or contains no .md files, ASK user to provide either: (a) a story file path, or (b) a directory to scan.</action>
<action>If a directory is provided, list story markdown files recursively under that directory matching pattern: "story-*.md".</action>
<action>Sort candidates by last modified time (newest first) and take the top {{story_selection_limit}} items.</action>
<ask>Present the list with index, filename, and modified time. Ask: "Select a story (1-{{story_selection_limit}}) or enter a path:"</ask>
<action>Resolve the selected item into {{story_path}}</action>
<action>Read the COMPLETE story file from {{story_path}}</action>
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks (including subtasks), Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
<action>Identify the first incomplete task (unchecked [ ]) in Tasks/Subtasks; if subtasks exist, treat all subtasks as part of the selected task scope</action>
<check>If no incomplete tasks found → "All tasks completed - proceed to completion sequence" and <goto step="6">Continue</goto></check>
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
<check>If task requirements ambiguous → ASK user to clarify; if unresolved, HALT: "Task requirements must be clear before implementation"</check>
</step>
<step n="2" goal="Plan and implement task">
<action>Review acceptance criteria and dev notes for the selected task</action>
<action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
<action>Implement the task COMPLETELY including all subtasks, following architecture patterns and coding standards in this repo</action>
<action>Handle error conditions and edge cases appropriately</action>
<check>If unapproved dependencies are needed → ASK user for approval before adding</check>
<check>If 3 consecutive implementation failures occur → HALT and request guidance</check>
<check>If required configuration is missing → HALT: "Cannot proceed without necessary configuration files"</check>
<check>If {{run_until_complete}} == true → Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</check>
<check>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</check>
</step>
<step n="3" 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 where applicable</action>
<action>Include end-to-end tests for critical user flows if applicable</action>
<action>Cover edge cases and error handling scenarios noted in the plan</action>
</step>
<step n="4" goal="Run validations and tests">
<action>Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided)</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</action>
<action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
<check>If regression tests fail → STOP and fix before continuing</check>
<check>If new tests fail → STOP and fix before continuing</check>
</step>
<step n="5" goal="Mark task complete and update story">
<action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
<action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
<action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
<action>Append a brief entry to Change Log describing the change</action>
<action>Save the story file</action>
<check>Determine if more incomplete tasks remain</check>
<check>If more tasks remain → <goto step="1">Next task</goto></check>
<check>If no tasks remain → <goto step="6">Completion</goto></check>
</step>
<step n="6" goal="Story completion sequence">
<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 story definition-of-done checklist, if the story includes one</action>
<action>Update the story Status to: Ready for Review</action>
<check>If any task is incomplete → Return to step 1 to complete remaining work (Do NOT finish with partial progress)</check>
<check>If regression failures exist → STOP and resolve before completing</check>
<check>If File List is incomplete → Update it before completing</check>
</step>
<step n="7" goal="Validation and handoff" optional="true">
<action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
<action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
<action>Communicate that the story is Ready for Review</action>
</step>
</workflow>
```

53
bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml
View File

@@ -1,53 +0,0 @@
name: dev-story
description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
author: "BMad"
# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
date: system-generated
# Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/dev-story"
instructions: "{installed_path}/instructions.md"
validation: "{installed_path}/checklist.md"
# This is an action workflow (no output template document)
template: false
# Variables (can be provided by caller)
variables:
story_path: ""
run_tests_command: "auto" # 'auto' = infer from repo, or override with explicit command
strict: true # if true, halt on validation failures
story_dir: "{config_source}:dev_story_location" # Directory containing story markdown files
story_selection_limit: 10
run_until_complete: true # Continue through all tasks without pausing except on HALT conditions
force_yolo: true # Hint executor to activate #yolo: skip optional prompts and elicitation
# Recommended inputs
recommended_inputs:
- story_markdown: "Path to the story markdown file (Tasks/Subtasks, Acceptance Criteria present)"
# Required tools (conceptual; executor should provide equivalents)
required_tools:
- read_file
- write_file
- search_repo
- run_tests
- list_files
- file_info
tags:
- development
- story-execution
- tests
- validation
- bmad-v6
execution_hints:
interactive: false # Minimize prompts; intended to run to completion
autonomous: true # Proceed without user input unless blocked
iterative: true