mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
@@ -1,221 +0,0 @@
|
||||
# Phase 4: Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 4 is where planning transitions into actual development. This phase manages the iterative implementation of stories defined in the epic files, tracking their progress through a well-defined status workflow.
|
||||
|
||||
## Status Definitions
|
||||
|
||||
### Epic Status
|
||||
|
||||
Epics progress through a simple two-state flow:
|
||||
|
||||
| Status | Description | Next Status |
|
||||
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
||||
| **backlog** | Epic exists in epic file but technical context has not been created | contexted |
|
||||
| **contexted** | Epic technical context has been created via `epic-tech-context` workflow. This is a prerequisite before any stories in the epic can be drafted. | - |
|
||||
|
||||
**File Indicators:**
|
||||
|
||||
- `backlog`: No `epic-{n}-context.md` file exists
|
||||
- `contexted`: `{output_folder}/epic-{n}-context.md` file exists
|
||||
|
||||
### Story Status
|
||||
|
||||
Stories progress through a six-state flow representing their journey from idea to implementation:
|
||||
|
||||
| Status | Description | Set By | Next Status |
|
||||
| ----------------- | ---------------------------------------------------------------------------------- | ------------- | ------------- |
|
||||
| **backlog** | Story only exists in the epic file, no work has begun | Initial state | drafted |
|
||||
| **drafted** | Story file has been created via `create-story` workflow | SM Agent | ready-for-dev |
|
||||
| **ready-for-dev** | Story has been drafted, approved, and context created via `story-context` workflow | SM Agent | in-progress |
|
||||
| **in-progress** | Developer is actively implementing the story | Dev Agent | review |
|
||||
| **review** | Implementation complete, under SM review via `code-review` workflow | Dev Agent | done |
|
||||
| **done** | Story has been reviewed and completed | Dev Agent | - |
|
||||
|
||||
**File Indicators:**
|
||||
|
||||
- `backlog`: No story file exists
|
||||
- `drafted`: `{story_dir}/{story-key}.md` file exists (e.g., `1-1-user-auth.md`)
|
||||
- `ready-for-dev`: Both story file and context exist (e.g., `1-1-user-auth-context.md`)
|
||||
- `in-progress`, `review`, `done`: Manual status updates in sprint-status.yaml
|
||||
|
||||
### Retrospective Status
|
||||
|
||||
Optional retrospectives can be completed after an epic:
|
||||
|
||||
| Status | Description |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| **optional** | Retrospective can be completed but is not required |
|
||||
| **completed** | Retrospective has been completed |
|
||||
|
||||
## Status Transitions
|
||||
|
||||
### Epic Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
backlog --> contexted[contexted via epic-tech-context]
|
||||
```
|
||||
|
||||
### Story Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
backlog --> drafted[drafted via create-story]
|
||||
drafted --> ready[ready-for-dev via story-context]
|
||||
ready --> progress[in-progress - dev starts]
|
||||
progress --> review[review via code-review]
|
||||
review --> done[done - dev completes]
|
||||
```
|
||||
|
||||
## Sprint Status Management
|
||||
|
||||
The `sprint-status.yaml` file is the single source of truth for tracking all work items. It contains:
|
||||
|
||||
- All epics with their current status
|
||||
- All stories with their current status
|
||||
- Retrospective placeholders for each epic
|
||||
- Clear documentation of status definitions
|
||||
|
||||
### Example Sprint Status File
|
||||
|
||||
```yaml
|
||||
development_status:
|
||||
epic-1: contexted
|
||||
1-1-project-foundation: done
|
||||
1-2-app-shell: done
|
||||
1-3-user-authentication: in-progress
|
||||
1-4-plant-data-model: ready-for-dev
|
||||
1-5-add-plant-manual: drafted
|
||||
1-6-photo-identification: backlog
|
||||
1-7-plant-naming: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
epic-2: backlog
|
||||
2-1-personality-system: backlog
|
||||
2-2-chat-interface: backlog
|
||||
2-3-llm-integration: backlog
|
||||
epic-2-retrospective: optional
|
||||
```
|
||||
|
||||
## Workflows in Phase 4
|
||||
|
||||
### Core Workflows
|
||||
|
||||
| Workflow | Purpose | Updates Status |
|
||||
| --------------------- | -------------------------------------------------- | ----------------------------------- |
|
||||
| **sprint-planning** | Generate/update sprint-status.yaml from epic files | Auto-detects file-based statuses |
|
||||
| **epic-tech-context** | Create technical context for an epic | epic: backlog → contexted |
|
||||
| **create-story** | Draft a story from epics/PRD | story: backlog → drafted |
|
||||
| **story-context** | Add implementation context to story | story: drafted → ready-for-dev |
|
||||
| **dev-story** | Developer implements the story | story: ready-for-dev → in-progress |
|
||||
| **code-review** | SM reviews implementation | story: in-progress → review |
|
||||
| **retrospective** | Conduct epic retrospective | retrospective: optional → completed |
|
||||
| **correct-course** | Course correction when needed | Various status updates |
|
||||
|
||||
### Sprint Planning Workflow
|
||||
|
||||
The `sprint-planning` workflow is the foundation of Phase 4. It:
|
||||
|
||||
1. **Parses all epic files** (`epic*.md` or `epics.md`)
|
||||
2. **Extracts all epics and stories** maintaining their order
|
||||
3. **Auto-detects current status** based on existing files:
|
||||
- Checks for epic context files
|
||||
- Checks for story files
|
||||
- Checks for story context files
|
||||
4. **Generates sprint-status.yaml** with current reality
|
||||
5. **Preserves manual status updates** (won't downgrade statuses)
|
||||
|
||||
Run this workflow:
|
||||
|
||||
- Initially after Phase 3 completion
|
||||
- After creating epic contexts
|
||||
- Periodically to sync file-based status
|
||||
- To verify current project state
|
||||
|
||||
### Workflow Guidelines
|
||||
|
||||
1. **Epic Context First**: Epics should be contexted before drafting their stories
|
||||
2. **Flexible Parallelism**: Multiple stories can be in-progress based on team capacity
|
||||
3. **Sequential Default**: Stories within an epic are typically worked in order
|
||||
4. **Learning Transfer**: SM drafts next story after previous is done, incorporating learnings
|
||||
5. **Review Flow**: Dev moves to review, SM reviews, Dev moves to done
|
||||
|
||||
## Agent Responsibilities
|
||||
|
||||
### SM (Scrum Master) Agent
|
||||
|
||||
- Run `sprint-planning` to generate initial status
|
||||
- Create epic contexts (`epic-tech-context`)
|
||||
- Draft stories (`create-story`)
|
||||
- Create story contexts (`story-context`)
|
||||
- Review completed work (`code-review`)
|
||||
- Update status in sprint-status.yaml
|
||||
|
||||
### Developer Agent
|
||||
|
||||
- Check sprint-status.yaml for `ready-for-dev` stories
|
||||
- Update status to `in-progress` when starting
|
||||
- Implement stories (`dev-story`)
|
||||
- Move to `review` when complete
|
||||
- Address review feedback
|
||||
- Update to `done` after approval
|
||||
|
||||
### Test Architect
|
||||
|
||||
- Monitor stories entering `review` status
|
||||
- Track epic progress
|
||||
- Identify when retrospectives needed
|
||||
- Validate implementation quality
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always run sprint-planning first** to establish current state
|
||||
2. **Update status immediately** as work progresses
|
||||
3. **Check sprint-status.yaml** before starting any work
|
||||
4. **Preserve learning** by drafting stories sequentially when possible
|
||||
5. **Document decisions** in story and context files
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Story File Naming
|
||||
|
||||
- Format: `{epic}-{story}-{kebab-title}.md`
|
||||
- Example: `1-1-user-authentication.md`
|
||||
- Avoids YAML float parsing issues (1.1 vs 1.10)
|
||||
- Makes files self-descriptive
|
||||
|
||||
### Git Branch Naming
|
||||
|
||||
- Format: `feat/{epic}-{story}-{kebab-title}`
|
||||
- Example: `feat/1-1-user-authentication`
|
||||
- Consistent with story file naming
|
||||
- Clean for branch management
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
{output_folder}/
|
||||
├── sprint-status.yaml # Sprint status tracking
|
||||
├── epic*.md or epics.md # Epic definitions
|
||||
├── epic-1-context.md # Epic technical contexts
|
||||
├── epic-2-context.md
|
||||
└── stories/
|
||||
├── 1-1-user-authentication.md # Story drafts
|
||||
├── 1-1-user-authentication-context.md # Story contexts
|
||||
├── 1-2-account-management.md
|
||||
├── 1-2-account-management-context.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After Phase 4 implementation, projects typically move to:
|
||||
|
||||
- Deployment and release
|
||||
- User acceptance testing
|
||||
- Production monitoring
|
||||
- Maintenance and updates
|
||||
|
||||
The sprint-status.yaml file provides a complete audit trail of the development process and can be used for project reporting and retrospectives.
|
||||
@@ -1,69 +0,0 @@
|
||||
# Review Story (Senior Developer Code Review)
|
||||
|
||||
Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
|
||||
|
||||
## What It Does
|
||||
|
||||
- Auto-discovers the target story or accepts an explicit `story_path`
|
||||
- Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
|
||||
- Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
|
||||
- Locates the epic Tech Spec and relevant architecture/standards docs
|
||||
- Uses MCP servers for best-practices and security references; falls back to web search
|
||||
- Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
|
||||
- Evaluates code quality, security, and test coverage
|
||||
- Appends a "Senior Developer Review (AI)" section to the story with findings and action items
|
||||
- Optionally updates story Status based on outcome
|
||||
|
||||
## How to Invoke
|
||||
|
||||
- Tell the Dev Agent to perform a \*code-review after loading the dev agent. This is a context intensive operation so this should not be done in the same context as a just completed dev session - clear the context, reload the dev, then run code-review!
|
||||
|
||||
## Inputs and Variables
|
||||
|
||||
- `story_path` (optional): Explicit path to a story file
|
||||
- `story_dir` (from config): `{project-root}/bmad/bmm/config.yaml` → `dev_story_location`
|
||||
- `allow_status_values`: Defaults include `Ready for Review`, `Review`
|
||||
- `auto_discover_context` (default: true)
|
||||
- `auto_discover_tech_spec` (default: true)
|
||||
- `tech_spec_glob_template`: `tech-spec-epic-{{epic_num}}*.md`
|
||||
- `arch_docs_search_dirs`: Defaults to `docs/` and `outputs/`
|
||||
- `enable_mcp_doc_search` (default: true)
|
||||
- `enable_web_fallback` (default: true)
|
||||
- `update_status_on_result` (default: false)
|
||||
|
||||
## Story Updates
|
||||
|
||||
- Appends a section titled: `Senior Developer Review (AI)` at the end
|
||||
- Adds a Change Log entry: "Senior Developer Review notes appended"
|
||||
- If enabled, updates `Status` based on outcome
|
||||
|
||||
## Persistence and Backlog
|
||||
|
||||
To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):
|
||||
|
||||
- Story tasks: Inserts unchecked items under `Tasks / Subtasks` in a "Review Follow-ups (AI)" subsection so `dev-story` can pick them up next.
|
||||
- Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
|
||||
- Backlog file: Appends normalized rows to `docs/backlog.md` (created if missing) for cross-cutting or longer-term improvements.
|
||||
- Epic follow-ups: If an epic Tech Spec is found, appends to its `Post-Review Follow-ups` section.
|
||||
|
||||
Configure via `workflow.yaml` variables:
|
||||
|
||||
- `persist_action_items` (default: true)
|
||||
- `persist_targets`: `story_tasks`, `story_review_section`, `backlog_file`, `epic_followups`
|
||||
- `backlog_file` (default: `{project-root}/docs/backlog.md`)
|
||||
- `update_epic_followups` (default: true)
|
||||
- `epic_followups_section_title` (default: `Post-Review Follow-ups`)
|
||||
|
||||
Routing guidance:
|
||||
|
||||
- Put must-fix items to ship the story into the story’s tasks.
|
||||
- Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
|
||||
- Put cross-cutting, future, or refactor work into the backlog file.
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- `dev-story` — Implements tasks/subtasks and can act on review action items
|
||||
- `story-context` — Generates Story Context for a single story
|
||||
- `tech-spec` — Generates epic Tech Spec documents
|
||||
|
||||
_Part of the BMAD Method v6 — Implementation Phase_
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Correct Course Workflow
|
||||
|
||||
The correct-course workflow is v6's adaptive response mechanism for stories that encounter issues during development or review, enabling intelligent course correction without restarting from scratch. Run by the Scrum Master (SM) or Team Lead, this workflow analyzes why a story is blocked or has issues, determines whether the story scope needs adjustment, requirements need clarification, technical approach needs revision, or the story needs to be split or reconsidered. This represents the agile principle of embracing change even late in the development cycle, but doing so in a structured way that captures learning and maintains project coherence.
|
||||
|
||||
Unlike simply abandoning failed work or blindly pushing forward, correct-course provides a systematic approach to diagnosing issues and determining appropriate remediation. The workflow examines the original story specification, what was actually implemented, what issues arose during development or review, and the broader epic context to recommend the best path forward. This might involve clarifying requirements, adjusting acceptance criteria, revising technical approach, splitting the story into smaller pieces, or even determining the story should be deprioritized.
|
||||
|
||||
The critical value of this workflow is that it prevents thrashing—endless cycles of implementation and rework without clear direction. By stepping back to analyze what went wrong and charting a clear path forward, the correct-course workflow enables teams to learn from difficulties and adapt intelligently rather than stubbornly proceeding with a flawed approach.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Analyze issues and recommend course correction
|
||||
bmad run correct-course
|
||||
```
|
||||
|
||||
The workflow should be run when:
|
||||
|
||||
- Review identifies critical issues requiring rethinking
|
||||
- Developer encounters blocking issues during implementation
|
||||
- Acceptance criteria prove infeasible or unclear
|
||||
- Technical approach needs significant revision
|
||||
- Story scope needs adjustment based on discoveries
|
||||
|
||||
## Inputs
|
||||
|
||||
**Required Context:**
|
||||
|
||||
- **Story Document**: Original story specification
|
||||
- **Implementation Attempts**: Code changes and approaches tried
|
||||
- **Review Feedback**: Issues and concerns identified
|
||||
- **Epic Context**: Overall epic goals and current progress
|
||||
- **Technical Constraints**: Architecture decisions and limitations discovered
|
||||
|
||||
**Analysis Focus:**
|
||||
|
||||
- Root cause of issues or blockages
|
||||
- Feasibility of current story scope
|
||||
- Clarity of requirements and acceptance criteria
|
||||
- Appropriateness of technical approach
|
||||
- Whether story should be split or revised
|
||||
|
||||
## Outputs
|
||||
|
||||
**Primary Deliverable:**
|
||||
|
||||
- **Course Correction Report** (`[story-id]-correction.md`): Analysis and recommendations including:
|
||||
- Issue root cause analysis
|
||||
- Impact assessment on epic and project
|
||||
- Recommended corrective actions with rationale
|
||||
- Revised story specification if applicable
|
||||
- Updated acceptance criteria if needed
|
||||
- Technical approach adjustments
|
||||
- Timeline and effort implications
|
||||
|
||||
**Possible Outcomes:**
|
||||
|
||||
1. **Clarify Requirements**: Update story with clearer acceptance criteria
|
||||
2. **Revise Scope**: Adjust story scope to be more achievable
|
||||
3. **Split Story**: Break into multiple smaller stories
|
||||
4. **Change Approach**: Recommend different technical approach
|
||||
5. **Deprioritize**: Determine story should be deferred or cancelled
|
||||
6. **Unblock**: Identify and address blocking dependencies
|
||||
|
||||
**Artifacts:**
|
||||
|
||||
- Updated story document if revision needed
|
||||
- New story documents if splitting story
|
||||
- Updated epic backlog reflecting changes
|
||||
- Lessons learned for retrospective
|
||||
@@ -1,146 +0,0 @@
|
||||
# Create Story Workflow
|
||||
|
||||
Just-in-time story generation creating one story at a time based on epic backlog state. Run by Scrum Master (SM) agent to ensure planned stories align with approved epics.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Usage](#usage)
|
||||
- [Key Features](#key-features)
|
||||
- [Inputs & Outputs](#inputs--outputs)
|
||||
- [Workflow Behavior](#workflow-behavior)
|
||||
- [Integration](#integration)
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# SM initiates next story creation
|
||||
bmad sm *create-story
|
||||
```
|
||||
|
||||
**When to run:**
|
||||
|
||||
- Sprint has capacity for new work
|
||||
- Previous story is Done/Approved
|
||||
- Team ready for next planned story
|
||||
|
||||
## Key Features
|
||||
|
||||
### Strict Planning Enforcement
|
||||
|
||||
- **Only creates stories enumerated in epics.md**
|
||||
- Halts if story not found in epic plan
|
||||
- Prevents scope creep through validation
|
||||
|
||||
### Intelligent Document Discovery
|
||||
|
||||
- Auto-finds tech spec: `tech-spec-epic-{N}-*.md`
|
||||
- Discovers architecture docs across directories
|
||||
- Builds prioritized requirement sources
|
||||
|
||||
### Source Document Grounding
|
||||
|
||||
- Every requirement traced to source
|
||||
- No invention of domain facts
|
||||
- Citations included in output
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
- Default "#yolo" mode minimizes prompts
|
||||
- Smooth automated story preparation
|
||||
- Only prompts when critical
|
||||
|
||||
## Inputs & Outputs
|
||||
|
||||
### Required Files
|
||||
|
||||
| File | Purpose | Priority |
|
||||
| ------------------------ | ----------------------------- | -------- |
|
||||
| epics.md | Story enumeration (MANDATORY) | Critical |
|
||||
| tech-spec-epic-{N}-\*.md | Epic technical spec | High |
|
||||
| PRD.md | Product requirements | Medium |
|
||||
| Architecture docs | Technical constraints | Low |
|
||||
|
||||
### Auto-Discovered Docs
|
||||
|
||||
- `tech-stack.md`, `unified-project-structure.md`
|
||||
- `testing-strategy.md`, `backend/frontend-architecture.md`
|
||||
- `data-models.md`, `database-schema.md`, `api-specs.md`
|
||||
|
||||
### Output
|
||||
|
||||
**Story Document:** `{story_dir}/story-{epic}.{story}.md`
|
||||
|
||||
- User story statement (role, action, benefit)
|
||||
- Acceptance criteria from tech spec/epics
|
||||
- Tasks mapped to ACs
|
||||
- Testing requirements
|
||||
- Dev notes with sources
|
||||
- Status: "Draft"
|
||||
|
||||
## Workflow Behavior
|
||||
|
||||
### Story Number Management
|
||||
|
||||
- Auto-detects next story number
|
||||
- No duplicates or skipped numbers
|
||||
- Maintains epic.story convention
|
||||
|
||||
### Update vs Create
|
||||
|
||||
- **If current story not Done:** Updates existing
|
||||
- **If current story Done:** Creates next (if planned)
|
||||
|
||||
### Validation Safeguards
|
||||
|
||||
**No Story Found:**
|
||||
|
||||
```
|
||||
"No planned next story found in epics.md for epic {N}.
|
||||
Run *correct-course to add/modify epic stories."
|
||||
```
|
||||
|
||||
**Missing Config:**
|
||||
Ensure `dev_story_location` set in config.yaml
|
||||
|
||||
## Integration
|
||||
|
||||
### v6 Implementation Cycle
|
||||
|
||||
1. **create-story** ← Current step (defines "what")
|
||||
2. story-context (adds technical "how")
|
||||
3. dev-story (implementation)
|
||||
4. code-review (validation)
|
||||
5. correct-course (if needed)
|
||||
6. retrospective (after epic)
|
||||
|
||||
### Document Priority
|
||||
|
||||
1. **tech_spec_file** - Epic-specific spec
|
||||
2. **epics_file** - Story breakdown
|
||||
3. **prd_file** - Business requirements
|
||||
4. **architecture_docs** - Technical guidance
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# bmad/bmm/config.yaml
|
||||
dev_story_location: ./stories
|
||||
output_folder: ./output
|
||||
|
||||
# workflow.yaml defaults
|
||||
non_interactive: true
|
||||
auto_run_context: true
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
| ----------------------- | ------------------------------------------ |
|
||||
| "No planned next story" | Run `*correct-course` to add story to epic |
|
||||
| Missing story_dir | Set `dev_story_location` in config |
|
||||
| Tech spec not found | Use naming: `tech-spec-epic-{N}-*.md` |
|
||||
| No architecture docs | Add docs to docs/ or output/ folder |
|
||||
|
||||
---
|
||||
|
||||
For workflow details, see [instructions.md](./instructions.md) and [checklist.md](./checklist.md).
|
||||
@@ -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 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
|
||||
|
||||
```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 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:
|
||||
|
||||
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: code-review (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 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.
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **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)
|
||||
@@ -1,195 +0,0 @@
|
||||
# Technical Specification Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **PRD-Architecture Integration** - Synthesizes business requirements with technical constraints
|
||||
- **Traceability Mapping** - Links acceptance criteria to technical components and tests
|
||||
- **Multi-Input Support** - Leverages PRD, architecture, front-end specs, and brownfield notes
|
||||
- **Implementation Focus** - Provides concrete technical guidance for development teams
|
||||
- **Testing Integration** - Includes test strategy aligned with acceptance criteria
|
||||
- **Validation Ready** - Generates specifications suitable for architectural review
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow tech-spec
|
||||
```
|
||||
|
||||
### With Input Documents
|
||||
|
||||
```bash
|
||||
# With specific PRD and architecture
|
||||
workflow tech-spec --input PRD.md --input architecture.md
|
||||
|
||||
# With comprehensive inputs
|
||||
workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec.md
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **output_folder**: Location for generated technical specification
|
||||
- **epic_id**: Used in output filename (extracted from PRD or prompted)
|
||||
- **recommended_inputs**: PRD, architecture, front-end spec, brownfield notes
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
tech-spec/
|
||||
├── workflow.yaml # Configuration and metadata
|
||||
├── instructions.md # Step-by-step execution guide
|
||||
├── template.md # Technical specification structure
|
||||
├── checklist.md # Validation criteria
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Input Collection and Analysis (Steps 1-2)
|
||||
|
||||
- **Document Discovery**: Locates PRD and Architecture documents
|
||||
- **Epic Extraction**: Identifies epic title and ID from PRD content
|
||||
- **Template Initialization**: Creates tech-spec document from template
|
||||
- **Context Analysis**: Reviews complete PRD and architecture for alignment
|
||||
|
||||
### Phase 2: Technical Design Specification (Step 3)
|
||||
|
||||
- **Service Architecture**: Defines services/modules with responsibilities and interfaces
|
||||
- **Data Modeling**: Specifies entities, schemas, and relationships
|
||||
- **API Design**: Documents endpoints, request/response models, and error handling
|
||||
- **Workflow Definition**: Details sequence flows and data processing patterns
|
||||
|
||||
### Phase 3: Non-Functional Requirements (Step 4)
|
||||
|
||||
- **Performance Specs**: Defines measurable latency, throughput, and scalability targets
|
||||
- **Security Requirements**: Specifies authentication, authorization, and data protection
|
||||
- **Reliability Standards**: Documents availability, recovery, and degradation behavior
|
||||
- **Observability Framework**: Defines logging, metrics, and tracing requirements
|
||||
|
||||
### Phase 4: Dependencies and Integration (Step 5)
|
||||
|
||||
- **Dependency Analysis**: Scans repository for package manifests and frameworks
|
||||
- **Integration Mapping**: Identifies external systems and API dependencies
|
||||
- **Version Management**: Documents version constraints and compatibility requirements
|
||||
- **Infrastructure Needs**: Specifies deployment and runtime dependencies
|
||||
|
||||
### Phase 5: Acceptance and Testing (Step 6)
|
||||
|
||||
- **Criteria Normalization**: Extracts and refines acceptance criteria from PRD
|
||||
- **Traceability Matrix**: Maps acceptance criteria to technical components
|
||||
- **Test Strategy**: Defines testing approach for each acceptance criterion
|
||||
- **Component Mapping**: Links requirements to specific APIs and modules
|
||||
|
||||
### Phase 6: Risk and Validation (Steps 7-8)
|
||||
|
||||
- **Risk Assessment**: Identifies technical risks, assumptions, and open questions
|
||||
- **Mitigation Planning**: Provides strategies for addressing identified risks
|
||||
- **Quality Validation**: Ensures specification meets completeness criteria
|
||||
- **Checklist Verification**: Validates against workflow quality standards
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: tech-spec-{epic_id}-{date}.md
|
||||
- **Traceability data**: Embedded mapping tables linking requirements to implementation
|
||||
|
||||
### Output Structure
|
||||
|
||||
1. **Overview and Scope** - Project context and boundaries
|
||||
2. **System Architecture Alignment** - Connection to architecture
|
||||
3. **Detailed Design** - Services, data models, APIs, and workflows
|
||||
4. **Non-Functional Requirements** - Performance, security, reliability, observability
|
||||
5. **Dependencies and Integrations** - External systems and technical dependencies
|
||||
6. **Acceptance Criteria** - Testable requirements from PRD
|
||||
7. **Traceability Mapping** - Requirements-to-implementation mapping
|
||||
8. **Test Strategy** - Testing approach and framework alignment
|
||||
9. **Risks and Assumptions** - Technical risks and mitigation strategies
|
||||
|
||||
## Requirements
|
||||
|
||||
- **PRD Document**: Product Requirements Document with clear acceptance criteria
|
||||
- **Architecture Document**: architecture or technical design
|
||||
- **Repository Access**: For dependency analysis and framework detection
|
||||
- **Epic Context**: Clear epic identification and scope definition
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Validate Inputs**: Ensure PRD and architecture documents are complete and current
|
||||
2. **Review Requirements**: Confirm acceptance criteria are specific and testable
|
||||
3. **Check Dependencies**: Verify repository structure supports automated dependency analysis
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Maintain Traceability**: Ensure every acceptance criterion maps to implementation
|
||||
2. **Be Implementation-Specific**: Provide concrete technical guidance, not high-level concepts
|
||||
3. **Consider Constraints**: Factor in existing system limitations and brownfield challenges
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Architect Review**: Have technical lead validate design decisions
|
||||
2. **Developer Walkthrough**: Ensure implementation team understands specifications
|
||||
3. **Test Planning**: Use traceability matrix for test case development
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Missing or incomplete technical details
|
||||
|
||||
- **Solution**: Review architecture document for implementation specifics
|
||||
- **Check**: Ensure PRD contains sufficient functional requirements detail
|
||||
|
||||
**Issue**: Acceptance criteria don't map cleanly to technical components
|
||||
|
||||
- **Solution**: Break down complex criteria into atomic, testable statements
|
||||
- **Check**: Verify PRD acceptance criteria are properly structured
|
||||
|
||||
**Issue**: Dependency analysis fails or is incomplete
|
||||
|
||||
- **Solution**: Check repository structure and manifest file locations
|
||||
- **Check**: Verify repository contains standard dependency files (package.json, etc.)
|
||||
|
||||
**Issue**: Non-functional requirements are too vague
|
||||
|
||||
- **Solution**: Extract specific performance and quality targets from architecture
|
||||
- **Check**: Ensure architecture document contains measurable NFR specifications
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Template**: Update template.md to match organizational technical spec standards
|
||||
2. **Extend Dependencies**: Add support for additional package managers or frameworks
|
||||
3. **Enhance Validation**: Extend checklist.md with company-specific technical criteria
|
||||
4. **Add Sections**: Include additional technical concerns like DevOps or monitoring
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - Comprehensive technical specification with traceability
|
||||
- PRD-Architecture integration
|
||||
- Automated dependency detection
|
||||
- Traceability mapping
|
||||
- Test strategy alignment
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Ensure PRD and architecture documents are complete before starting
|
||||
- Consult BMAD documentation for technical specification standards
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Retrospective Workflow
|
||||
|
||||
The retrospective workflow is v6's learning capture mechanism, run by the Scrum Master (SM) after epic completion to systematically harvest insights, patterns, and improvements discovered during implementation. Unlike traditional retrospectives that focus primarily on process and team dynamics, this workflow performs deep technical and methodological analysis of the entire epic journey—from story creation through implementation to review—identifying what worked well, what could improve, and what patterns emerged. The retrospective produces actionable intelligence that informs future epics, improves workflow templates, and evolves the team's shared knowledge.
|
||||
|
||||
This workflow represents a critical feedback loop in the v6 methodology. Each epic is an experiment in adaptive software development, and the retrospective is where we analyze the results of that experiment. The SM examines completed stories, review feedback, course corrections made, story-context effectiveness, technical decisions, and team collaboration patterns to extract transferable learning. This learning manifests as updates to workflow templates, new story-context patterns, refined estimation approaches, and documented best practices.
|
||||
|
||||
The retrospective is not just a compliance ritual but a genuine opportunity for continuous improvement. By systematically analyzing what happened during the epic, the team builds institutional knowledge that makes each subsequent epic smoother, faster, and higher quality. The insights captured here directly improve future story creation, context generation, development efficiency, and review effectiveness.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Conduct retrospective after epic completion
|
||||
bmad run retrospective
|
||||
```
|
||||
|
||||
The SM should run this workflow:
|
||||
|
||||
- After all stories in an epic are completed
|
||||
- Before starting the next major epic
|
||||
- When significant learning has accumulated
|
||||
- As preparation for improving future epic execution
|
||||
|
||||
## Inputs
|
||||
|
||||
**Required Context:**
|
||||
|
||||
- **Epic Document**: Complete epic specification and goals
|
||||
- **All Story Documents**: Every story created for the epic
|
||||
- **Review Reports**: All review feedback and findings
|
||||
- **Course Corrections**: Any correct-course actions taken
|
||||
- **Story Contexts**: Generated expert guidance for each story
|
||||
- **Implementation Artifacts**: Code commits, test results, deployment records
|
||||
|
||||
**Analysis Targets:**
|
||||
|
||||
- Story creation accuracy and sizing
|
||||
- Story-context effectiveness and relevance
|
||||
- Implementation challenges and solutions
|
||||
- Review findings and patterns
|
||||
- Technical decisions and outcomes
|
||||
- Estimation accuracy
|
||||
- Team collaboration and communication
|
||||
- Workflow effectiveness
|
||||
|
||||
## Outputs
|
||||
|
||||
**Primary Deliverable:**
|
||||
|
||||
- **Retrospective Report** (`[epic-id]-retrospective.xml`): Comprehensive analysis including:
|
||||
- Executive summary of epic outcomes
|
||||
- Story-by-story analysis of what was learned
|
||||
- Technical insights and architecture learnings
|
||||
- Story-context effectiveness assessment
|
||||
- Process improvements identified
|
||||
- Patterns discovered (good and bad)
|
||||
- Recommendations for future epics
|
||||
- Metrics and statistics (velocity, cycle time, etc.)
|
||||
|
||||
**Actionable Outputs:**
|
||||
|
||||
- **Template Updates**: Improvements to workflow templates based on learning
|
||||
- **Pattern Library**: New story-context patterns for common scenarios
|
||||
- **Best Practices**: Documented approaches that worked well
|
||||
- **Gotchas**: Issues to avoid in future work
|
||||
- **Estimation Refinements**: Better story sizing guidance
|
||||
- **Process Changes**: Workflow adjustments for next epic
|
||||
|
||||
**Artifacts:**
|
||||
|
||||
- Epic marked as complete with retrospective attached
|
||||
- Knowledge base updated with new patterns
|
||||
- Workflow templates updated if needed
|
||||
- Team learning captured for onboarding
|
||||
@@ -1,156 +0,0 @@
|
||||
# Sprint Planning Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
The sprint-planning workflow generates and manages the sprint status tracking file that serves as the single source of truth for Phase 4 implementation. It extracts all epics and stories from epic files and tracks their progress through the development lifecycle.
|
||||
|
||||
In Agile terminology, this workflow facilitates **Sprint Planning** or **Sprint 0 Kickoff** - the transition from planning/architecture into actual development execution.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow creates a `sprint-status.yaml` file that:
|
||||
|
||||
- Lists all epics, stories, and retrospectives in order
|
||||
- Tracks the current status of each item
|
||||
- Provides a clear view of what needs to be worked on next
|
||||
- Ensures only one story is in progress at a time
|
||||
- Maintains the development flow from backlog to done
|
||||
|
||||
## When to Use
|
||||
|
||||
Run this workflow:
|
||||
|
||||
1. **Initially** - After Phase 3 (solutioning) is complete and epics are finalized
|
||||
2. **After epic context creation** - To update epic status to 'contexted'
|
||||
3. **Periodically** - To auto-detect newly created story files
|
||||
4. **For status checks** - To see overall project progress
|
||||
|
||||
## Status State Machine
|
||||
|
||||
### Epic Flow
|
||||
|
||||
```
|
||||
backlog → contexted
|
||||
```
|
||||
|
||||
### Story Flow
|
||||
|
||||
```
|
||||
backlog → drafted → ready-for-dev → in-progress → review → done
|
||||
```
|
||||
|
||||
### Retrospective Flow
|
||||
|
||||
```
|
||||
optional ↔ completed
|
||||
```
|
||||
|
||||
## Key Guidelines
|
||||
|
||||
1. **Epic Context Recommended**: Epics should be `contexted` before their stories can be `drafted`
|
||||
2. **Flexible Parallelism**: Multiple stories can be `in-progress` based on team capacity
|
||||
3. **Sequential Default**: Stories within an epic are typically worked in order, but parallel work is supported
|
||||
4. **Review Flow**: Stories should go through `review` before `done`
|
||||
5. **Learning Transfer**: SM typically drafts next story after previous is `done`, incorporating learnings
|
||||
|
||||
## File Locations
|
||||
|
||||
### Input Files
|
||||
|
||||
- **Epic Files**: `{output_folder}/epic*.md` or `{output_folder}/epics.md`
|
||||
- **Epic Context**: `{output_folder}/epic-{n}-context.md`
|
||||
- **Story Files**: `{story_dir}/{epic}-{story}-{title}.md`
|
||||
- Example: `stories/1-1-user-authentication.md`
|
||||
- **Story Context**: `{story_dir}/{epic}-{story}-{title}-context.md`
|
||||
- Example: `stories/1-1-user-authentication-context.md`
|
||||
|
||||
### Output File
|
||||
|
||||
- **Status File**: `{output_folder}/sprint-status.yaml`
|
||||
|
||||
## Usage by Agents
|
||||
|
||||
### SM (Scrum Master) Agent
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Check sprint-status.yaml for stories in 'done' status
|
||||
- Identify next 'backlog' story to draft
|
||||
- Run create-story workflow
|
||||
- Update status to 'drafted'
|
||||
- Create story context
|
||||
- Update status to 'ready-for-dev'
|
||||
```
|
||||
|
||||
### Developer Agent
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Find stories with 'ready-for-dev' status
|
||||
- Update to 'in-progress' when starting
|
||||
- Implement the story
|
||||
- Update to 'review' when complete
|
||||
- Address review feedback
|
||||
- Update to 'done' after review
|
||||
```
|
||||
|
||||
### Test Architect
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Monitor stories entering 'review'
|
||||
- Track epic progress
|
||||
- Identify when retrospectives are needed
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
```yaml
|
||||
# Sprint Status
|
||||
# Generated: 2025-01-20
|
||||
# Project: MyPlantFamily
|
||||
|
||||
development_status:
|
||||
epic-1: contexted
|
||||
1-1-project-foundation: done
|
||||
1-2-app-shell: done
|
||||
1-3-user-authentication: in-progress
|
||||
1-4-plant-data-model: ready-for-dev
|
||||
1-5-add-plant-manual: drafted
|
||||
1-6-photo-identification: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
epic-2: contexted
|
||||
2-1-personality-system: in-progress
|
||||
2-2-chat-interface: drafted
|
||||
2-3-llm-integration: backlog
|
||||
2-4-reminder-system: backlog
|
||||
epic-2-retrospective: optional
|
||||
```
|
||||
|
||||
## Integration with BMM Workflow
|
||||
|
||||
This workflow is part of Phase 4 (Implementation) and integrates with:
|
||||
|
||||
1. **epic-tech-context** - Creates technical context for epics
|
||||
2. **create-story** - Drafts individual story files
|
||||
3. **story-context** - Adds implementation context to stories
|
||||
4. **dev-story** - Developer implements the story
|
||||
5. **code-review** - SM reviews implementation
|
||||
6. **retrospective** - Optional epic retrospective
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Clear Visibility**: Everyone knows what's being worked on
|
||||
- **Flexible Capacity**: Supports both sequential and parallel work patterns
|
||||
- **Learning Transfer**: SM can incorporate learnings when drafting next story
|
||||
- **Progress Tracking**: Easy to see overall project status
|
||||
- **Automation Friendly**: Simple YAML format for agent updates
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Initial Generation**: Run immediately after epics are finalized
|
||||
2. **Regular Updates**: Agents should update status as they work
|
||||
3. **Manual Override**: You can manually edit the file if needed
|
||||
4. **Backup First**: The workflow backs up existing status before regenerating
|
||||
5. **Validation**: The workflow validates legal status transitions
|
||||
@@ -1,234 +0,0 @@
|
||||
# Story Context Assembly Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Assembles a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story. Creates comprehensive development context for AI agents and developers working on specific stories.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Automated Context Discovery** - Scans documentation and codebase for relevant artifacts
|
||||
- **XML Output Format** - Structured context optimized for LLM consumption
|
||||
- **Dependency Detection** - Identifies frameworks, packages, and technical dependencies
|
||||
- **Interface Mapping** - Locates existing APIs and interfaces to reuse
|
||||
- **Testing Integration** - Includes testing standards and generates test ideas
|
||||
- **Status Tracking** - Updates story status and maintains context references
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow story-context
|
||||
```
|
||||
|
||||
### With Specific Story
|
||||
|
||||
```bash
|
||||
# Process specific story file
|
||||
workflow story-context --input /path/to/story.md
|
||||
|
||||
# Using story path variable
|
||||
workflow story-context --story_path "docs/stories/1.2.feature-name.md"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **story_path**: Path to target story markdown file (defaults to latest.md)
|
||||
- **auto_update_status**: Whether to automatically update story status (default: false)
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
story-context/
|
||||
├── workflow.yaml # Configuration and metadata
|
||||
├── instructions.md # Step-by-step execution guide
|
||||
├── context-template.xml # XML structure template
|
||||
├── checklist.md # Validation criteria
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Story Analysis (Steps 1-2)
|
||||
|
||||
- **Story Location**: Finds and loads target story markdown file
|
||||
- **Content Parsing**: Extracts epic ID, story ID, title, acceptance criteria, and tasks
|
||||
- **Template Initialization**: Creates initial XML context structure
|
||||
- **User Story Extraction**: Parses "As a... I want... So that..." components
|
||||
|
||||
### Phase 2: Documentation Discovery (Step 3)
|
||||
|
||||
- **Keyword Analysis**: Identifies relevant terms from story content
|
||||
- **Document Scanning**: Searches docs and module documentation
|
||||
- **Authority Prioritization**: Prefers PRDs, architecture docs, and specs
|
||||
- **Context Extraction**: Captures relevant sections with snippets
|
||||
|
||||
### Phase 3: Code Analysis (Step 4)
|
||||
|
||||
- **Symbol Search**: Finds relevant modules, functions, and components
|
||||
- **Interface Identification**: Locates existing APIs and interfaces
|
||||
- **Constraint Extraction**: Identifies development patterns and requirements
|
||||
- **Reuse Opportunities**: Highlights existing code to leverage
|
||||
|
||||
### Phase 4: Dependency Analysis (Step 5)
|
||||
|
||||
- **Manifest Detection**: Scans for package.json, requirements.txt, go.mod, etc.
|
||||
- **Framework Identification**: Identifies Unity, Node.js, Python, Go ecosystems
|
||||
- **Version Tracking**: Captures dependency versions where available
|
||||
- **Configuration Discovery**: Finds relevant project configurations
|
||||
|
||||
### Phase 5: Testing Context (Step 6)
|
||||
|
||||
- **Standards Extraction**: Identifies testing frameworks and patterns
|
||||
- **Location Mapping**: Documents where tests should be placed
|
||||
- **Test Ideas**: Generates initial test concepts for acceptance criteria
|
||||
- **Framework Integration**: Links to existing test infrastructure
|
||||
|
||||
### Phase 6: Validation and Updates (Steps 7-8)
|
||||
|
||||
- **XML Validation**: Ensures proper structure and completeness
|
||||
- **Status Updates**: Changes story status from Draft to ContextReadyDraft
|
||||
- **Reference Tracking**: Adds context file reference to story document
|
||||
- **Quality Assurance**: Validates against workflow checklist
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: story-context-{epic_id}.{story_id}-{date}.xml
|
||||
- **Story updates**: Modified original story file with context references
|
||||
|
||||
### Output Structure
|
||||
|
||||
```xml
|
||||
<storyContext>
|
||||
<story>
|
||||
<basicInfo>
|
||||
<epicId>...</epicId>
|
||||
<storyId>...</storyId>
|
||||
<title>...</title>
|
||||
<status>...</status>
|
||||
</basicInfo>
|
||||
<userStory>
|
||||
<asA>...</asA>
|
||||
<iWant>...</iWant>
|
||||
<soThat>...</soThat>
|
||||
</userStory>
|
||||
<acceptanceCriteria>
|
||||
<criterion id="1">...</criterion>
|
||||
</acceptanceCriteria>
|
||||
<tasks>
|
||||
<task>...</task>
|
||||
</tasks>
|
||||
</story>
|
||||
|
||||
<artifacts>
|
||||
<docs>
|
||||
<doc path="..." title="..." section="..." snippet="..."/>
|
||||
</docs>
|
||||
<code>
|
||||
<file path="..." kind="..." symbol="..." lines="..." reason="..."/>
|
||||
</code>
|
||||
<dependencies>
|
||||
<node>
|
||||
<package name="..." version="..."/>
|
||||
</node>
|
||||
</dependencies>
|
||||
</artifacts>
|
||||
|
||||
<interfaces>
|
||||
<interface name="..." kind="..." signature="..." path="..."/>
|
||||
</interfaces>
|
||||
|
||||
<constraints>
|
||||
<constraint>...</constraint>
|
||||
</constraints>
|
||||
|
||||
<tests>
|
||||
<standards>...</standards>
|
||||
<locations>
|
||||
<location>...</location>
|
||||
</locations>
|
||||
<ideas>
|
||||
<idea ac="1">...</idea>
|
||||
</ideas>
|
||||
</tests>
|
||||
</storyContext>
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Story File**: Valid story markdown with proper structure (epic.story.title.md format)
|
||||
- **Repository Access**: Ability to scan documentation and source code
|
||||
- **Documentation**: Project documentation in standard locations (docs/, src/, etc.)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Ensure Story Quality**: Verify story has clear acceptance criteria and tasks
|
||||
2. **Update Documentation**: Ensure relevant docs are current and discoverable
|
||||
3. **Clean Repository**: Remove obsolete code that might confuse context assembly
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Review Extracted Context**: Verify that discovered artifacts are actually relevant
|
||||
2. **Check Interface Accuracy**: Ensure identified APIs and interfaces are current
|
||||
3. **Validate Dependencies**: Confirm dependency information matches project state
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Review XML Output**: Validate the generated context makes sense
|
||||
2. **Test with Developer**: Have a developer review context usefulness
|
||||
3. **Update Story Status**: Verify story status was properly updated
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Context contains irrelevant or outdated information
|
||||
|
||||
- **Solution**: Review keyword extraction and document filtering logic
|
||||
- **Check**: Ensure story title and acceptance criteria are specific and clear
|
||||
|
||||
**Issue**: Missing relevant code or interfaces
|
||||
|
||||
- **Solution**: Verify code search patterns and symbol extraction
|
||||
- **Check**: Ensure relevant code follows project naming conventions
|
||||
|
||||
**Issue**: Dependency information is incomplete or wrong
|
||||
|
||||
- **Solution**: Check for multiple package manifests or unusual project structure
|
||||
- **Check**: Verify dependency files are in expected locations and formats
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Search Patterns**: Update instructions.md to adjust code and doc discovery
|
||||
2. **Extend XML Schema**: Customize context-template.xml for additional context types
|
||||
3. **Add Validation**: Extend checklist.md with project-specific quality criteria
|
||||
4. **Configure Dependencies**: Adjust dependency detection for specific tech stacks
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - XML-based context assembly with comprehensive artifact discovery
|
||||
- Multi-ecosystem dependency detection
|
||||
- Interface and constraint extraction
|
||||
- Testing context integration
|
||||
- Story status management
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Ensure story files follow expected markdown structure
|
||||
- Check that repository structure supports automated discovery
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
Reference in New Issue
Block a user