docs updated
This commit is contained in:
Brian Madison
@@ -0,0 +1,38 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Game Brainstorming Workflow
|
||||
|
||||
This workflow employs structured ideation methodologies to generate and refine game concepts through systematic creative exploration. It leverages five distinct brainstorming techniques—SCAMPER, Mind Mapping, Lotus Blossom, Six Thinking Hats, and Random Word Association—each applied in isolation to produce diverse conceptual approaches. The workflow emphasizes iterative refinement where initial concepts are evaluated against design pillars, technical feasibility, and market positioning to identify the most promising directions.
|
||||
|
||||
The system operates through a game-specific context framework that considers platform constraints, target audience characteristics, monetization models, and core gameplay pillars. Each brainstorming method generates distinct artifacts: SCAMPER produces systematic modification analyses, Mind Mapping reveals conceptual hierarchies, Lotus Blossom creates radial expansion patterns, Six Thinking Hats enforces multi-perspective evaluation, and Random Word Association drives lateral thinking breakthroughs. The workflow culminates in a consolidated concept document that synthesizes the strongest elements from each method into cohesive game proposals.
|
||||
|
||||
Critical to this workflow is its emphasis on constraint-driven creativity. The game-context.md framework establishes technical boundaries (platform capabilities, performance targets), market parameters (genre conventions, competitive positioning), and design philosophy (accessibility requirements, monetization ethics) that ground creative exploration in practical realities. This prevents ideation from drifting into infeasible territory while maintaining creative ambition.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
bmad bmm 1-analysis brainstorm-game
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
- **Game Context Document**: Platform specifications, genre preferences, technical constraints, target audience demographics, monetization approach, and core design pillars
|
||||
- **Initial Concept Seed** (optional): High-level game idea or theme to guide brainstorming direction
|
||||
|
||||
## Outputs
|
||||
|
||||
- **Method-Specific Artifacts**: Five separate brainstorming documents, each applying a different ideation methodology to the concept space
|
||||
- **Consolidated Concept Document**: Synthesized game concepts with feasibility assessments, unique value propositions, and recommended next steps
|
||||
- **Design Pillar Alignment Matrix**: Evaluation of each concept against stated design objectives and technical constraints
|
||||
|
||||
## Brainstorming Methods
|
||||
|
||||
| Method | Focus | Output Characteristics |
|
||||
| ----------------------- | ------------------------ | ---------------------------------- |
|
||||
| SCAMPER | Systematic modification | Structured transformation analysis |
|
||||
| Mind Mapping | Hierarchical exploration | Visual concept relationships |
|
||||
| Lotus Blossom | Radial expansion | Layered thematic development |
|
||||
| Six Thinking Hats | Multi-perspective | Balanced evaluation framework |
|
||||
| Random Word Association | Lateral thinking | Unexpected conceptual combinations |
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Project Brainstorming Workflow
|
||||
|
||||
This workflow facilitates structured ideation for non-game software projects through systematic exploration of problem spaces, solution architectures, and implementation strategies. Unlike traditional requirement gathering, it employs creative techniques to uncover non-obvious approaches and identify innovative solutions that address core business needs while considering technical constraints and organizational capabilities.
|
||||
|
||||
The workflow operates through a project-specific context framework that captures business objectives, technical environment, stakeholder needs, and organizational constraints. It generates multiple solution vectors through parallel ideation tracks: architectural approaches, user experience paradigms, integration patterns, and value delivery mechanisms. Each track produces concrete proposals that are evaluated against feasibility, impact, and alignment with strategic objectives.
|
||||
|
||||
Critical differentiators include its focus on solution innovation rather than requirement enumeration, emphasis on technical-business alignment from inception, and structured approach to surfacing hidden assumptions. The workflow produces actionable outputs that directly feed into Product Brief development, ensuring that creative exploration translates into concrete planning artifacts.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
bmad bmm 1-analysis brainstorm-project
|
||||
```
|
||||
|
||||
## Inputs
|
||||
|
||||
- **Project Context Document**: Business objectives, technical environment, stakeholder landscape, organizational constraints, success criteria, and known pain points
|
||||
- **Problem Statement** (optional): Core business challenge or opportunity driving the project
|
||||
|
||||
## Outputs
|
||||
|
||||
- **Solution Architecture Proposals**: Multiple technical approaches with trade-off analysis and feasibility assessments
|
||||
- **Value Delivery Framework**: Prioritized feature concepts aligned with business objectives and user needs
|
||||
- **Risk and Opportunity Analysis**: Identified technical dependencies, integration challenges, and innovation opportunities
|
||||
- **Strategic Recommendation**: Synthesized direction with rationale and implementation considerations
|
||||
@@ -1,8 +1,14 @@
|
||||
# Project Planning Workflow
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
## Overview
|
||||
# Project Planning Workflow (Phase 2)
|
||||
|
||||
Scale-adaptive project planning workflow that automatically adjusts outputs based on project scope - from single atomic changes (Level 0: tech-spec only) to enterprise platforms (Level 4: full PRD + epics). Generates appropriate planning artifacts for each level with intelligent routing and continuation support.
|
||||
This scale-adaptive workflow represents the cornerstone of BMM v6's intelligent project orchestration, automatically determining project complexity (Level 0-4) and routing to specialized planning pathways based on project type, scope, and context. Unlike traditional one-size-fits-all planning approaches, it dynamically adjusts output artifacts—from minimal tech specs for atomic changes to comprehensive PRD suites for enterprise platforms—ensuring planning overhead matches project value. The workflow serves as the critical bridge between Phase 1 analysis outputs and Phase 3 solutioning, establishing the contractual foundation for all subsequent development activities.
|
||||
|
||||
The workflow's routing intelligence analyzes project characteristics through multi-dimensional assessment: project type (game, web, mobile, backend), context (greenfield vs. brownfield), scope indicators, and complexity signals. Based on this analysis, it classifies projects into five levels with distinct artifact requirements. Level 0 produces only tech specs for single atomic changes. Levels 1-2 generate focused PRDs with embedded tech specs. Levels 3-4 create comprehensive PRDs with separate epics that hand off to the architect-driven solutioning workflow. This classification isn't merely about document generation—it fundamentally changes how requirements are structured, validated, and communicated to downstream consumers.
|
||||
|
||||
Critical to v6's flow improvement is this workflow's integration with the project-workflow-analysis.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For game projects, it routes to specialized GDD generation with genre-specific templates. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs.
|
||||
|
||||
## Key Features
|
||||
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
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,42 +1,129 @@
|
||||
# Create Story
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
## Purpose
|
||||
# Create Story Workflow
|
||||
|
||||
Generate the next user story from epics/PRD and architecture context into your configured stories directory using a consistent structure.
|
||||
The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
|
||||
|
||||
## Highlights
|
||||
This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
|
||||
|
||||
- Auto-detects next story id based on existing files
|
||||
- Pulls ACs from `epics.md` (or PRD) when available
|
||||
- Saves to `{dev_story_location}` from `bmad/bmm/config.yaml`
|
||||
- Optional: immediately runs Story Context workflow for the new story
|
||||
- Spec-compliant with core workflow engine at `bmad/core/tasks/workflow.md`
|
||||
- Defaults to non-interactive `#yolo` mode; only asks when strictly necessary
|
||||
- Safeguard: Will NOT create a new story unless epics.md explicitly enumerates it; otherwise halts and instructs to run PM/SM `*correct-course`
|
||||
The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
|
||||
|
||||
## Invoke
|
||||
## Usage
|
||||
|
||||
- By path: `workflow {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml`
|
||||
```bash
|
||||
# SM initiates story creation for the next piece of work
|
||||
bmad sm *create-story
|
||||
```
|
||||
|
||||
## Variables
|
||||
The SM runs this workflow when:
|
||||
|
||||
- `story_dir`: from config `dev_story_location`
|
||||
- `epics_file`: default `{output_folder}/epics.md`
|
||||
- `prd_file`: default `{output_folder}/prd.md`
|
||||
- `hla_file`: default `{output_folder}/high-level-architecture.md`
|
||||
- `auto_run_context`: default `true`
|
||||
- `tech_spec_file`: auto-discovered in `{project-root}/docs` with pattern `tech-spec-epic-<epic_num>-*.md` (latest by modified time)
|
||||
- `execution_mode`: `#yolo` by default to minimize prompts
|
||||
- `arch_docs_search_dirs`: `docs/` and `output_folder` are searched for architecture docs
|
||||
- `arch_docs_file_names`: includes `tech-stack.md`, `unified-project-structure.md`, `coding-standards.md`, `testing-strategy.md`, `backend-architecture.md`, `frontend-architecture.md`, `data-models.md`, `database-schema.md`, `rest-api-spec.md`, `external-apis.md`
|
||||
- The current sprint has capacity for new work
|
||||
- The previous story status is "Done" or "Approved"
|
||||
- The team is ready for the next planned story in the epic
|
||||
- Story preparation is needed before development
|
||||
|
||||
## Output
|
||||
## Inputs
|
||||
|
||||
- New story markdown: `{story_dir}/story-<epic_num>.<story_num>.md`
|
||||
- Status: `Draft`
|
||||
- Guardrail: If `epics.md` lacks the next story under the current epic, the workflow halts with: "No planned next story found in epics.md for epic <epic_num>. Please load either PM (Product Manager) agent at `{project-root}/bmad/bmm/agents/pm.md` or SM (Scrum Master) agent at `{project-root}/bmad/bmm/agents/sm.md` and run `*correct-course` to add/modify epic stories, then rerun create-story."
|
||||
**Required Context Files:**
|
||||
|
||||
## After Creation
|
||||
- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
|
||||
- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
|
||||
- **PRD.md**: Product requirements document (fallback for requirements)
|
||||
- **Architecture Documents**: Automatically discovered from docs/ and output folders:
|
||||
- tech-stack.md, unified-project-structure.md, coding-standards.md
|
||||
- testing-strategy.md, backend-architecture.md, frontend-architecture.md
|
||||
- data-models.md, database-schema.md, rest-api-spec.md, external-apis.md
|
||||
|
||||
- Approve the story when ready (Status → Approved)
|
||||
- Then run the Dev agent `*develop` command (uses the Dev Story workflow)
|
||||
**Workflow Variables:**
|
||||
|
||||
- `story_dir`: From config `dev_story_location` - where stories are saved
|
||||
- `epic_num`: Current epic number (auto-detected from existing stories)
|
||||
- `story_num`: Next story number (incremented from last completed story)
|
||||
- `auto_run_context`: Default true - runs story-context workflow after creation
|
||||
- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
|
||||
|
||||
## Outputs
|
||||
|
||||
**Primary Deliverable:**
|
||||
|
||||
- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
|
||||
- User story statement (role, action, benefit)
|
||||
- Acceptance criteria extracted from tech spec or epics.md
|
||||
- Tasks and subtasks mapped to ACs
|
||||
- Testing requirements per testing strategy
|
||||
- Dev notes with source citations
|
||||
- Status: "Draft" (requires approval before development)
|
||||
|
||||
**Validation Safeguards:**
|
||||
|
||||
- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
|
||||
```
|
||||
"No planned next story found in epics.md for epic {epic_num}.
|
||||
Please load either PM or SM agent and run *correct-course to add/modify epic stories."
|
||||
```
|
||||
- **Status Check**: Won't create new story if current story isn't Done/Approved
|
||||
- **Document Grounding**: All requirements traced to source documents (no invention)
|
||||
|
||||
## Key Features
|
||||
|
||||
**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
|
||||
|
||||
**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
|
||||
|
||||
**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
|
||||
|
||||
**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
|
||||
|
||||
**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
|
||||
|
||||
## Integration with v6 Flow
|
||||
|
||||
The create-story workflow is step 1 in the v6 implementation cycle:
|
||||
|
||||
1. **SM: create-story** ← You are here
|
||||
2. SM: story-context (adds JIT technical expertise)
|
||||
3. DEV: dev-story (implements with generated context)
|
||||
4. DEV/SR: review-story (validates completion)
|
||||
5. If needed: correct-course (adjusts direction)
|
||||
6. After epic: retrospective (captures learnings)
|
||||
|
||||
This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
|
||||
|
||||
## Document Priority Order
|
||||
|
||||
The workflow uses this priority for extracting requirements:
|
||||
|
||||
1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
|
||||
2. **epics_file**: Acceptance criteria and story breakdown
|
||||
3. **prd_file**: Business requirements and constraints
|
||||
4. **Architecture docs**: Constraints, patterns, and technical guidance
|
||||
|
||||
## Workflow Behavior
|
||||
|
||||
**Story Number Management:**
|
||||
|
||||
- Automatically detects next story number from existing files
|
||||
- Won't skip numbers or create duplicates
|
||||
- Maintains epic.story numbering convention
|
||||
|
||||
**Update vs Create:**
|
||||
|
||||
- If latest story status != Done/Approved: Updates existing story
|
||||
- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
|
||||
|
||||
**Epic Advancement:**
|
||||
|
||||
- In non-interactive mode: Stays within current epic
|
||||
- Interactive mode: Can prompt for new epic number
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
|
||||
|
||||
**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
|
||||
|
||||
**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
|
||||
|
||||
**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.
|
||||
|
||||
@@ -1,84 +1,206 @@
|
||||
# Dev Story
|
||||
# Dev Story Workflow
|
||||
|
||||
## Purpose
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
- 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
|
||||
**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.
|
||||
|
||||
## How to Invoke
|
||||
**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.
|
||||
|
||||
- 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`
|
||||
**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.
|
||||
|
||||
## Inputs and Variables
|
||||
**Test-Driven Approach**: For each task, the workflow emphasizes writing tests that verify acceptance criteria before or alongside implementation, ensuring requirements are actually met.
|
||||
|
||||
- `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.
|
||||
**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.
|
||||
|
||||
## Config
|
||||
## Integration with v6 Flow
|
||||
|
||||
Ensure your BMM config defines the stories directory:
|
||||
The dev-story workflow is step 3 in the v6 implementation cycle:
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
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}
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
## Best Practices
|
||||
|
||||
1. 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
|
||||
2. Plan and implement
|
||||
- Log brief plan in Dev Agent Record → Debug Log
|
||||
- Implement task and subtasks, handle edge cases
|
||||
3. Write tests
|
||||
- Add unit, integration, and E2E (as applicable)
|
||||
4. Run validations and tests
|
||||
- Run existing tests for regressions + new tests
|
||||
- Lint/quality checks if configured; ensure ACs met
|
||||
5. 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
|
||||
6. Completion sequence
|
||||
- Verify all tasks done, run full regression suite, update Status → "Ready for Review"
|
||||
7. Validation and handoff (optional)
|
||||
- Optionally run validation and finalize notes
|
||||
**Load Context First**: Always ensure the story-context XML is loaded at the start. This provides the expert guidance needed throughout implementation.
|
||||
|
||||
## Allowed Story File Modifications
|
||||
**Follow Task Order**: Implement tasks in the order listed. Dependencies are typically structured in the task sequence.
|
||||
|
||||
Only these sections may be changed by this workflow:
|
||||
**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.
|
||||
|
||||
- Tasks/Subtasks checkboxes
|
||||
- Dev Agent Record (Debug Log, Completion Notes)
|
||||
- File List
|
||||
- Change Log
|
||||
- Status
|
||||
**Update Incrementally**: Update the story file after each task completion rather than batching updates at the end.
|
||||
|
||||
## Files in This Workflow
|
||||
**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.
|
||||
|
||||
- `workflow.yaml` — configuration and variables
|
||||
- `instructions.md` — execution logic and steps
|
||||
- `checklist.md` — validation checklist for completion
|
||||
**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
|
||||
|
||||
- `story-context` — Build dev context for a single story
|
||||
- `story-context-batch` — Process multiple stories and update status
|
||||
- **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)
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
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.md`): 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
|
||||
349
src/modules/bmm/workflows/README.md
Normal file
349
src/modules/bmm/workflows/README.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# BMM Workflows - The Complete v6 Flow
|
||||
|
||||
The BMM (BMAD Method Module) orchestrates software development through four distinct phases, each with specialized workflows that adapt to project scale (Level 0-4) and context (greenfield vs brownfield). This document serves as the master guide for understanding how these workflows interconnect to deliver the revolutionary v6 methodology.
|
||||
|
||||
## Core v6 Innovations
|
||||
|
||||
**Scale-Adaptive Planning**: Projects automatically route through different workflows based on complexity (Level 0-4), ensuring appropriate documentation and process overhead.
|
||||
|
||||
**Just-In-Time Design**: Technical specifications are created one epic at a time during implementation, not all upfront, incorporating learnings as the project evolves.
|
||||
|
||||
**Dynamic Expertise Injection**: Story-context workflows provide targeted technical guidance per story, replacing static documentation with contextual expertise.
|
||||
|
||||
**Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last.
|
||||
|
||||
## The Four Phases
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 1: ANALYSIS │
|
||||
│ (Optional) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ brainstorm-game ──┐ │
|
||||
│ brainstorm-project ├──→ research ──→ product-brief ──┐ │
|
||||
│ game-brief ────────┘ │ │
|
||||
└────────────────────────────────────────────────────────┼─────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 2: PLANNING │
|
||||
│ (Scale-Adaptive Router) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ plan-project │
|
||||
│ ├──→ Level 0: tech-spec only │
|
||||
│ ├──→ Level 1-2: PRD + tech-spec │
|
||||
│ ├──→ Level 3-4: PRD + Epics ─────┐ │
|
||||
│ └──→ Game: GDD │ │
|
||||
└───────────────────────────────────────────────────────────┼──┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 3: SOLUTIONING │
|
||||
│ (Levels 3-4 Only) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3-solutioning ──→ Architecture.md │
|
||||
│ ↓ │
|
||||
│ tech-spec (per epic, JIT during implementation) │
|
||||
└───────────────────────────────────────────────────────────┬─┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PHASE 4: IMPLEMENTATION │
|
||||
│ (Iterative Cycle) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─→ create-story ──→ story-context ──→ dev-story ──┐ │
|
||||
│ │ ↓ │
|
||||
│ │ retrospective ←── [epic done] ←── review-story │
|
||||
│ │ ↓ │
|
||||
│ └──────────── correct-course ←──[if issues]┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Phase 1: Analysis (Optional)
|
||||
|
||||
Optional workflows for project discovery and requirements gathering. Output feeds into Phase 2 planning.
|
||||
|
||||
### Workflows
|
||||
|
||||
| Workflow | Purpose | Output | When to Use |
|
||||
| ---------------------- | ------------------------------------------- | ---------------------- | --------------------- |
|
||||
| **brainstorm-game** | Game concept ideation using 5 methodologies | Concept proposals | New game projects |
|
||||
| **brainstorm-project** | Software solution exploration | Architecture proposals | New software projects |
|
||||
| **game-brief** | Structured game design foundation | Game brief document | Before GDD creation |
|
||||
| **product-brief** | Strategic product planning culmination | Product brief | End of analysis phase |
|
||||
| **research** | Multi-mode research (market/technical/deep) | Research artifacts | When evidence needed |
|
||||
|
||||
### Flow
|
||||
|
||||
```
|
||||
Brainstorming → Research → Brief → Planning (Phase 2)
|
||||
```
|
||||
|
||||
## Phase 2: Planning (Required)
|
||||
|
||||
The central orchestrator that determines project scale and generates appropriate planning artifacts.
|
||||
|
||||
### Scale Levels
|
||||
|
||||
| Level | Scope | Outputs | Next Phase |
|
||||
| ----- | ------------------------ | ----------------------- | ---------------- |
|
||||
| **0** | Single atomic change | tech-spec only | → Implementation |
|
||||
| **1** | 1-10 stories, 1 epic | Minimal PRD + tech-spec | → Implementation |
|
||||
| **2** | 5-15 stories, 1-2 epics | Focused PRD + tech-spec | → Implementation |
|
||||
| **3** | 12-40 stories, 2-5 epics | Full PRD + Epics list | → Solutioning |
|
||||
| **4** | 40+ stories, 5+ epics | Enterprise PRD + Epics | → Solutioning |
|
||||
|
||||
### Routing Logic
|
||||
|
||||
```
|
||||
plan-project
|
||||
├─→ Detect project type (game/web/mobile/backend/etc)
|
||||
├─→ Assess complexity → assign Level 0-4
|
||||
├─→ Check context (greenfield/brownfield)
|
||||
│ └─→ If brownfield & undocumented:
|
||||
│ └─→ HALT: "Generate brownfield documentation first"
|
||||
│ └─→ (TBD workflow for codebase analysis)
|
||||
├─→ Route to appropriate sub-workflow:
|
||||
│ ├─→ Game → GDD workflow
|
||||
│ ├─→ Level 0 → tech-spec workflow
|
||||
│ ├─→ Level 1-2 → PRD + embedded tech-spec
|
||||
│ └─→ Level 3-4 → PRD + epics → Solutioning
|
||||
└─→ Generate project-workflow-analysis.md (tracking doc)
|
||||
```
|
||||
|
||||
### Key Outputs
|
||||
|
||||
- **PRD.md**: Product Requirements Document (Levels 1-4)
|
||||
- **Epics.md**: Epic breakdown with stories (Levels 2-4)
|
||||
- **tech-spec.md**: Technical specification (Levels 0-2 only)
|
||||
- **GDD.md**: Game Design Document (game projects)
|
||||
- **project-workflow-analysis.md**: Workflow state tracking
|
||||
|
||||
## Phase 3: Solutioning (Levels 3-4 Only)
|
||||
|
||||
Architecture and technical design phase for complex projects.
|
||||
|
||||
### Workflows
|
||||
|
||||
| Workflow | Owner | Purpose | Output | Timing |
|
||||
| ----------------- | --------- | ------------------------------ | ------------------------- | ----------------- |
|
||||
| **3-solutioning** | Architect | Create overall architecture | Architecture.md with ADRs | Once per project |
|
||||
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT |
|
||||
|
||||
### Just-In-Time Tech Specs
|
||||
|
||||
```
|
||||
FOR each epic in sequence:
|
||||
WHEN ready to implement epic:
|
||||
Architect: Run tech-spec workflow for THIS epic only
|
||||
→ Creates tech-spec-epic-N.md
|
||||
→ Hands off to implementation
|
||||
IMPLEMENT epic completely
|
||||
THEN move to next epic
|
||||
```
|
||||
|
||||
**Critical**: Tech specs are created ONE AT A TIME as epics are ready for implementation, not all upfront. This prevents over-engineering and incorporates learning.
|
||||
|
||||
## Phase 4: Implementation (Iterative)
|
||||
|
||||
The core development cycle that transforms requirements into working software.
|
||||
|
||||
### The Implementation Loop
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ SM: create-story │
|
||||
│ (Generate next story from epics.md) │
|
||||
└─────────────────────┬───────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ SM: story-context │
|
||||
│ (Generate expertise injection XML) │
|
||||
└─────────────────────┬───────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ DEV: dev-story │
|
||||
│ (Implement with context injection) │
|
||||
└─────────────────────┬───────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ SR/DEV: review-story │
|
||||
│ (Validate against criteria) │
|
||||
└─────────────────────┬───────────────────┘
|
||||
↓
|
||||
┌─────────┴─────────┐
|
||||
│ Issues Found? │
|
||||
└─────────┬─────────┘
|
||||
┌─────┴─────┐
|
||||
↓ ↓
|
||||
[No: Next Story] [Yes: correct-course]
|
||||
↓
|
||||
[Return to appropriate step]
|
||||
```
|
||||
|
||||
### Workflow Responsibilities
|
||||
|
||||
| Workflow | Agent | Purpose | Key Innovation |
|
||||
| ------------------ | ------ | ---------------------------- | -------------------------- |
|
||||
| **create-story** | SM | Generate ONE story at a time | Enforces epics.md planning |
|
||||
| **story-context** | SM | Create expertise injection | JIT technical guidance |
|
||||
| **dev-story** | DEV | Implement with context | Resumable after review |
|
||||
| **review-story** | SR/DEV | Comprehensive validation | Fresh context review |
|
||||
| **correct-course** | SM | Handle issues/changes | Adaptive response |
|
||||
| **retrospective** | SM | Capture epic learnings | Continuous improvement |
|
||||
|
||||
### Story Flow States
|
||||
|
||||
```
|
||||
Draft (create-story)
|
||||
→ Approved (SM approval)
|
||||
→ In Progress (dev-story)
|
||||
→ Ready for Review (dev complete)
|
||||
→ Done (review passed)
|
||||
OR
|
||||
→ In Progress (review failed, back to dev)
|
||||
```
|
||||
|
||||
## Greenfield vs Brownfield Considerations
|
||||
|
||||
### Greenfield Projects
|
||||
|
||||
- Start with Phase 1 (Analysis) or Phase 2 (Planning)
|
||||
- Clean architecture decisions in Phase 3
|
||||
- Straightforward implementation in Phase 4
|
||||
|
||||
### Brownfield Projects
|
||||
|
||||
```
|
||||
plan-project (Phase 2)
|
||||
├─→ Check: Is existing codebase documented?
|
||||
│ ├─→ YES: Proceed with planning
|
||||
│ └─→ NO: HALT with message:
|
||||
│ "Brownfield project requires documentation.
|
||||
│ Please run codebase-analysis workflow first."
|
||||
│ └─→ [TBD: brownfield-analysis workflow]
|
||||
│ ├─→ Analyzes existing code
|
||||
│ ├─→ Documents current architecture
|
||||
│ ├─→ Identifies technical debt
|
||||
│ └─→ Creates baseline documentation
|
||||
└─→ Continue with scale-adaptive planning
|
||||
```
|
||||
|
||||
**Critical for Brownfield**: Without adequate documentation of the existing system, the planning phase cannot accurately assess scope or create meaningful requirements. The brownfield-analysis workflow (coming soon) will:
|
||||
|
||||
- Map existing architecture
|
||||
- Document current patterns
|
||||
- Identify integration points
|
||||
- Assess technical debt
|
||||
- Create the baseline needed for planning
|
||||
|
||||
## Agent Participation by Phase
|
||||
|
||||
| Phase | Primary Agents | Supporting Agents |
|
||||
| ------------------ | ------------------- | --------------------------- |
|
||||
| **Analysis** | Analyst, Researcher | PM, PO |
|
||||
| **Planning** | PM | Analyst, UX Expert |
|
||||
| **Solutioning** | Architect | PM, Tech Lead |
|
||||
| **Implementation** | SM, DEV | SR, PM (for correct-course) |
|
||||
|
||||
## Key Files and Artifacts
|
||||
|
||||
### Tracking Documents
|
||||
|
||||
- **project-workflow-analysis.md**: Maintains workflow state, level, and progress
|
||||
- **Epics.md**: Master list of epics and stories (source of truth for planning)
|
||||
|
||||
### Phase Outputs
|
||||
|
||||
- **Phase 1**: Briefs and research documents
|
||||
- **Phase 2**: PRD, Epics, or tech-spec based on level
|
||||
- **Phase 3**: Architecture.md, epic-specific tech specs
|
||||
- **Phase 4**: Story files, context XMLs, implemented code
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Respect the Scale
|
||||
|
||||
- Don't create PRDs for Level 0 changes
|
||||
- Don't skip architecture for Level 3-4 projects
|
||||
- Let the workflow determine appropriate artifacts
|
||||
|
||||
### 2. Embrace Just-In-Time
|
||||
|
||||
- Create tech specs one epic at a time
|
||||
- Generate stories as needed, not in batches
|
||||
- Build context injections per story
|
||||
|
||||
### 3. Maintain Flow Integrity
|
||||
|
||||
- Stories must be enumerated in Epics.md
|
||||
- Each phase completes before the next begins
|
||||
- Use fresh context windows for reviews
|
||||
|
||||
### 4. Document Brownfield First
|
||||
|
||||
- Never plan without understanding existing code
|
||||
- Technical debt must be visible in planning
|
||||
- Integration points need documentation
|
||||
|
||||
### 5. Learn Continuously
|
||||
|
||||
- Run retrospectives after each epic
|
||||
- Update workflows based on learnings
|
||||
- Share patterns across teams
|
||||
|
||||
## Common Pitfalls and Solutions
|
||||
|
||||
| Pitfall | Solution |
|
||||
| --------------------------------- | ------------------------------------- |
|
||||
| Creating all tech specs upfront | Use JIT approach - one epic at a time |
|
||||
| Skipping story-context generation | Always run after create-story |
|
||||
| Batching story creation | Create one story at a time |
|
||||
| Ignoring scale levels | Let plan-project determine level |
|
||||
| Planning brownfield without docs | Run brownfield-analysis first |
|
||||
| Not running retrospectives | Schedule after every epic |
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Phase 1: Analysis (Optional)
|
||||
bmad analyst brainstorm-project
|
||||
bmad analyst research
|
||||
bmad analyst product-brief
|
||||
|
||||
# Phase 2: Planning
|
||||
bmad pm plan-project
|
||||
|
||||
# Phase 3: Solutioning (L3-4)
|
||||
bmad architect solution-architecture
|
||||
bmad architect tech-spec # Per epic, JIT
|
||||
|
||||
# Phase 4: Implementation
|
||||
bmad sm create-story # One at a time
|
||||
bmad sm story-context # After each story
|
||||
bmad dev develop # With context loaded
|
||||
bmad dev review-story # Or SR agent
|
||||
bmad sm correct-course # If issues
|
||||
bmad sm retrospective # After epic
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Coming Soon
|
||||
|
||||
- **brownfield-analysis**: Automated codebase documentation generator
|
||||
- **Workflow orchestration**: Automatic phase transitions
|
||||
- **Progress dashboards**: Real-time workflow status
|
||||
- **Team synchronization**: Multi-developer story coordination
|
||||
|
||||
### Under Consideration
|
||||
|
||||
- AI-assisted retrospectives
|
||||
- Automated story sizing
|
||||
- Predictive epic planning
|
||||
- Cross-project learning transfer
|
||||
|
||||
---
|
||||
|
||||
This document supersedes v6-IMPORTANT-BMM-FLOW.md and serves as the authoritative guide to BMM workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.
|
||||
Reference in New Issue
Block a user