ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

path fixes, documentation updates, md-xplodr added to core tools

This commit is contained in:
Brian Madison 2025-10-26 15:03:54 -05:00
parent 8220c819e6
commit 0067fb4880
20 changed files with 650 additions and 1086 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

328
docs/antipattern-audit-2025-10-22.md
View File

@ -1,328 +0,0 @@
# BMAD Workflow Conditional Execution Antipattern Audit
**Date:** 2025-10-22
**Auditor:** Claude Code (BMad Builder Agent)
**Scope:** All markdown files under `src/`
---
## Executive Summary
**Critical Issue Identified:** Invalid self-closing `<check>` tag pattern found throughout BMAD workflow codebase.
**Impact:**
- **98 instances** across **14 workflow files**
- Affects core workflows, builder workflows, and method workflows
- Creates XML parsing ambiguity and unpredictable LLM behavior
- Violates BMAD workflow specification (workflow.xml)
**Severity:** CRITICAL - Invalid XML structure, ambiguous conditional scope
---
## The Antipattern
### Invalid Pattern (Self-Closing Check)
```xml
<!-- ❌ WRONG - Invalid XML structure -->
<check>If condition met:</check>
<action>Do something</action>
<action>Do something else</action>
```
**Problems:**
1. Check tag doesn't wrap anything (invalid XML)
2. Ambiguous scope - unclear which actions are conditional
3. Breaks formatters and parsers
4. Not part of BMAD workflow spec
5. Unpredictable LLM interpretation
### Correct Patterns
**Single conditional action:**
```xml
<!-- ✅ CORRECT - Inline conditional -->
<action if="condition met">Do something</action>
```
**Multiple conditional actions:**
```xml
<!-- ✅ CORRECT - Proper wrapper block -->
<check if="condition met">
<action>Do something</action>
<action>Do something else</action>
</check>
```
---
## Audit Results
### Total Count
- **Total Instances:** 98
- **Affected Files:** 14
- **Modules Affected:** 4 (BMB, BMM, CIS, Core)
### Breakdown by File
| File | Count | Priority |
| -------------------------------------------------------------------- | ----- | ----------- |
| `modules/bmb/workflows/edit-workflow/instructions.md` | 21 | 🔴 CRITICAL |
| `modules/bmm/workflows/4-implementation/dev-story/instructions.md` | 13 | 🔴 CRITICAL |
| `modules/bmb/workflows/convert-legacy/instructions.md` | 13 | 🔴 CRITICAL |
| `modules/bmb/workflows/create-module/instructions.md` | 12 | 🔴 CRITICAL |
| `modules/bmb/workflows/create-agent/instructions.md` | 11 | 🔴 CRITICAL |
| `core/workflows/party-mode/instructions.md` | 7 | 🟡 HIGH |
| `modules/bmm/workflows/4-implementation/correct-course/checklist.md` | 5 | 🟡 HIGH |
| `core/workflows/brainstorming/instructions.md` | 5 | 🟡 HIGH |
| `modules/cis/workflows/storytelling/instructions.md` | 3 | 🟢 MEDIUM |
| `modules/bmb/workflows/audit-workflow/instructions.md` | 3 | 🟢 MEDIUM |
| `modules/bmb/workflows/create-workflow/workflow-creation-guide.md` | 2 | 🟢 MEDIUM |
| `modules/bmm/workflows/1-analysis/product-brief/instructions.md` | 1 | 🟢 LOW |
| `modules/bmm/workflows/1-analysis/game-brief/instructions.md` | 1 | 🟢 LOW |
| `modules/bmb/workflows/redoc/instructions.md` | 1 | 🟢 LOW |
### Breakdown by Module
**BMB (Builder) Module: 63 instances (64%)**
- edit-workflow: 21
- convert-legacy: 13
- create-module: 12
- create-agent: 11
- audit-workflow: 3
- create-workflow: 2
- redoc: 1
**BMM (Method) Module: 20 instances (20%)**
- dev-story: 13
- correct-course: 5
- product-brief: 1
- game-brief: 1
**Core Workflows: 12 instances (12%)**
- party-mode: 7
- brainstorming: 5
**CIS (Creative) Module: 3 instances (3%)**
- storytelling: 3
---
## Example Instances
### Example 1: create-agent/instructions.md (Line 13-20)
**BEFORE (Invalid):**
```xml
<check>If yes:</check>
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
<action>Wait for brainstorming session completion</action>
<check>If no:</check>
<action>Proceed directly to Step 0</action>
```
**AFTER (Correct):**
```xml
<check if="user answered yes">
<action>Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml</action>
<action>Pass context data: {installed_path}/brainstorm-context.md</action>
<action>Wait for brainstorming session completion</action>
</check>
<check if="user answered no">
<action>Proceed directly to Step 0</action>
</check>
```
### Example 2: dev-story/instructions.md (Line 54-55)
**BEFORE (Invalid):**
```xml
<check>If story file inaccessible → HALT: "Cannot develop story without access to story file"</check>
<check>If task requirements ambiguous → ASK user to clarify or HALT</check>
```
**AFTER (Correct):**
```xml
<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
<action if="task requirements ambiguous">ASK user to clarify or HALT</action>
```
---
## Impact Assessment
### Technical Impact
1. **XML Validity:** Invalid structure violates XML parsing rules
2. **Formatter Confusion:** Custom formatters incorrectly indent following content
3. **Scope Ambiguity:** Unclear which actions are inside vs outside conditional
4. **Maintainability:** Future developers confused by ambiguous structure
### LLM Adherence Impact
**Potential Issues:**
- LLM may interpret check as unconditional statement
- Actions may execute when they shouldn't (or vice versa)
- Inconsistent behavior across different LLMs
- Unpredictable results in complex nested conditionals
**Observed Behavior:**
- LLMs often "figure it out" through context and proximity
- Colon (`:`) pattern signals "here's what to do"
- Works in simple cases but risky in complex logic
**Risk Level:** MEDIUM-HIGH
- May work "most of the time" but unreliable
- Fails in edge cases and complex nested logic
- Future LLMs may interpret differently
---
## Root Cause Analysis
### Why This Happened
1. **Implicit convention evolved** - Self-closing check pattern emerged organically
2. **No enforcement** - No linter or validator caught the pattern
3. **Copy-paste propagation** - Pattern copied across workflows
4. **Formatting hid the issue** - Manual indentation made it "look right"
5. **LLM tolerance** - Current LLMs often figured it out despite ambiguity
### Meta-Problem
**The workflows that CREATE workflows have the antipattern:**
- create-workflow: 2 instances
- create-agent: 11 instances
- create-module: 12 instances
- edit-workflow: 21 instances
- convert-legacy: 13 instances
This means NEW workflows were being created WITH the antipattern built-in!
---
## Remediation Plan
### Phase 1: Immediate (High Priority Files)
Fix top 5 offenders (63% of problem):
1. edit-workflow (21 instances)
2. dev-story (13 instances)
3. convert-legacy (13 instances)
4. create-module (12 instances)
5. create-agent (11 instances)
**Total:** 70 instances (71% of problem)
### Phase 2: Core Workflows
Fix core workflows (critical for all modules):
1. party-mode (7 instances)
2. brainstorming (5 instances)
**Total:** 12 instances
### Phase 3: Remaining
Fix remaining 16 instances across 7 files
### Phase 4: Prevention
1. **Update audit-workflow** ✅ DONE
- Added antipattern detection to Step 4
- Flags with CRITICAL severity
- Suggests correct patterns
2. **Update creation guide** ✅ DONE
- Documented antipattern in workflow-creation-guide.md
- Clear examples of correct vs incorrect patterns
- Added to best practices
3. **Update checklist** ✅ DONE
- Added validation criteria to checklist.md
- 3 new checks for conditional execution patterns
4. **Create automated fixer** (TODO)
- Bulk conversion script for remaining instances
- Pattern matching and replacement logic
---
## Specification Reference
From `bmad/core/tasks/workflow.xml`:
```xml
<tag>action if="condition" - Single conditional action (inline, no closing tag needed)</tag>
<tag>check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required)</tag>
```
**Key Point:** Check tags MUST have `if=""` attribute and MUST wrap content with closing tag.
The self-closing pattern `<check>text</check>` is **NOT in the spec** and is **invalid**.
---
## Detection Command
To find all instances:
```bash
grep -r "<check>[^<]*</check>" src --include="*.md" -n
```
To count by file:
```bash
grep -r "<check>[^<]*</check>" src --include="*.md" -c | grep -v ":0$"
```
---
## Next Actions
- [ ] Create bulk-fix script for automated conversion
- [ ] Fix Phase 1 files (70 instances)
- [ ] Fix Phase 2 files (12 instances)
- [ ] Fix Phase 3 files (16 instances)
- [ ] Run audit-workflow on all fixed files to verify
- [ ] Update formatter to detect and warn on antipattern
- [ ] Add pre-commit hook to prevent future instances
---
## References
- **Workflow Spec:** `bmad/core/tasks/workflow.xml`
- **Creation Guide:** `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md`
- **Audit Workflow:** `src/modules/bmb/workflows/audit-workflow/`
- **This Report:** `docs/antipattern-audit-2025-10-22.md`
---
**Report Status:** Complete
**Action Required:** Yes - 98 instances need remediation
**Priority:** CRITICAL - Affects core functionality and workflow creation

19
docs/codebase-flattener.md
View File

@ -1,19 +0,0 @@
# Codebase Flattener Tool
BMad-Core includes a powerful codebase flattener for preparing existing projects to the web for AI Analysis
```bash
# Basic usage - creates flattened-codebase.xml
npx bmad-method flatten
# Custom input/output
npx bmad-method flatten --input /path/to/source --output project.xml
```
Features:
- AI-optimized XML output format
- Smart filtering with .gitignore respect
- Binary file detection and exclusion
- Real-time progress tracking
- Comprehensive completion statistics

188
docs/conversion-report-shard-doc-2025-10-26.md Normal file
View File

@ -0,0 +1,188 @@
# Legacy Task Conversion Report
**Generated**: 2025-10-26
**Converted By**: BMad Builder Agent
**Conversion Type**: Legacy Task → v6 XML Task
---
## Source Information
- **Original Location**: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md
- **Original Format**: Markdown task (v4/legacy format)
- **Original Type**: Document sharding utility task
---
## Target Information
- **New Location**: `/Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml`
- **New Format**: v6 XML task format
- **Task ID**: `bmad/core/tasks/shard-doc`
- **Task Name**: Shard Document
---
## Conversion Summary
### Components Converted
✅ **Task Structure**: Converted from markdown to XML format
✅ **Execution Flow**: 6 steps properly structured in `<flow>` section (simplified to tool-only)
✅ **Critical Instructions**: Moved to `<llm critical="true">` section
✅ **Validation Rules**: Extracted to `<validation>` section
✅ **Halt Conditions**: Extracted to `<halt-conditions>` section
✅ **Special Guidelines**: Moved to `<critical-context>` section
✅ **Output Format**: Documented in `<output-format>` section
✅ **Tool Information**: Preserved in `<tool-info>` section
### Key Features Preserved
- **Automated Tool**: Uses @kayvan/markdown-tree-parser exclusively
- **Simplified Flow**: Removed all manual steps, tool handles everything
- **Code Block Awareness**: Tool automatically handles ## inside code blocks
- **Content Preservation**: Tool preserves all markdown formatting and special content
- **Heading Adjustment**: Tool automatically reduces heading levels by one
- **Index Generation**: Tool automatically creates index.md
- **Validation Steps**: Verification of tool installation and output
- **Error Handling**: Halt conditions for tool and file system issues
### v6 Conventions Applied
- ✅ Proper `<task>` wrapper with id and name attributes
- ✅ `<llm critical="true">` section with mandatory instructions
- ✅ `<flow>` section with numbered `<step>` elements
- ✅ Used `<action>` tags for required actions
- ✅ Used `<i>` tags for instruction lists and context
- ✅ Conditional logic with `if` attributes on actions
- ✅ Optional steps marked with `optional="true"`
- ✅ Supporting sections for validation, halt conditions, output format
- ✅ Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml)
---
## Structural Comparison
### Legacy Format (Markdown)
```
# Document Sharding Task
## Primary Method: Automated Approach
## Manual Method (Fallback)
1. Identify target location
2. Parse sections
...
## Critical Guidelines
```
### v6 Format (XML)
```xml
<task id="bmad/core/tasks/shard-doc" name="Shard Document">
<objective>...</objective>
<llm critical="true">...</llm>
<critical-context>...</critical-context>
<flow>
<step n="1" title="...">
<action>...</action>
</step>
</flow>
<halt-conditions>...</halt-conditions>
<validation>...</validation>
</task>
```
---
## Validation Results
### XML Structure
- ✅ Valid XML syntax
- ✅ Properly nested elements
- ✅ All tags closed correctly
- ✅ Attributes properly formatted
### v6 Compliance
- ✅ Matches v6 task conventions
- ✅ Follows existing core task patterns
- ✅ Uses standard v6 tag set
- ✅ Proper section organization
### Content Integrity
- ✅ All original instructions preserved
- ✅ No functionality lost in conversion
- ✅ Critical warnings maintained
- ✅ Tool information preserved
- ✅ Validation logic intact
### File System
- ✅ Saved to correct location: `src/core/tasks/`
- ✅ Proper filename: `shard-doc.xml`
- ✅ Follows core task naming convention
---
## Usage Notes
### How to Invoke This Task
From an agent or workflow, reference:
```xml
<invoke-task>{project-root}/bmad/core/tasks/shard-doc.xml</invoke-task>
```
Or from agent menu:
```yaml
menu:
- trigger: shard
description: 'Split large document into organized files'
exec: '{project-root}/bmad/core/tasks/shard-doc.xml'
```
### Task Capabilities
1. **Automated Mode**: Uses @kayvan/markdown-tree-parser for fast sharding
2. **Manual Mode**: Step-by-step guided process for controlled sharding
3. **Safety Checks**: Validates code blocks aren't treated as headers
4. **Content Preservation**: Maintains all formatting, code, tables, diagrams
5. **Index Generation**: Creates navigable index.md automatically
6. **Validation**: Verifies completeness and integrity
---
## Post-Conversion Actions
### Recommended Next Steps
1. ✅ **Task Created**: File saved to core tasks directory
2. **Test Task**: Invoke from an agent or workflow to verify functionality
3. **Update Documentation**: Reference in core task documentation if needed
4. **Integration**: Add to relevant agent menus if appropriate
### No Manual Adjustments Required
The conversion is complete and ready for use. All legacy functionality has been successfully migrated to v6 XML format.
---
## Notes
- Original legacy file can be archived or left as-is (located on GitHub)
- This task is now a core BMAD task available to all modules
- The task follows v6 conventions and is fully compatible with BMAD-CORE v6 alpha
- **UPDATED 2025-10-26**: Manual fallback steps removed - task now exclusively uses @kayvan/markdown-tree-parser
- Flow simplified from 8 steps to 6 steps (tool installation → execution → verification)
- All manual parsing, file creation, and index generation logic removed (tool handles automatically)
---
**Conversion Status**: ✅ COMPLETE (Updated)
**Ready for Use**: YES
**Manual Adjustments Needed**: NONE
**Approach**: Automated tool only (no manual fallback)

10
docs/installers-bundlers/ide-injections.md
View File

@ -184,13 +184,3 @@ injections:
<cmds>...</cmds> <cmds>...</cmds>
</agent> </agent>
``` ```
## Testing Checklist
- [ ] Injection points are properly named and unique
- [ ] injections.yaml is valid YAML with correct structure
- [ ] Content formatting is preserved after injection
- [ ] Installation works without the IDE (injection points removed)
- [ ] Installation works with the IDE (content properly injected)
- [ ] Subagents/files are copied to correct locations
- [ ] No IDE-specific content remains when different IDE selected

64
docs/installers-bundlers/installers-modules-platforms-reference.md
View File

@ -1,4 +1,4 @@
# BMAD v6 Installation & Module System Reference # BMAD Installation & Module System Reference
## Table of Contents ## Table of Contents
@ -13,63 +13,36 @@
## Overview ## Overview
BMAD v6 is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance. BMad Core is a modular AI agent framework with intelligent installation, platform-agnostic support, and configuration inheritance.
### Key Features ### Key Features
- **Modular Design**: Core + optional modules (BMM, CIS) - **Modular Design**: Core + optional modules (BMB, BMM, CIS)
- **Smart Installation**: Interactive configuration with dependency resolution - **Smart Installation**: Interactive configuration with dependency resolution
- **Multi-Platform**: Supports 15+ AI coding platforms - **Clean Architecture**: Centralized `bmad/` directory add to project, no source pollution with multiple folders added
- **Clean Architecture**: Centralized `bmad/` directory, no source pollution
## Quick Start
```bash
# Interactive installation (recommended)
bmad install
# Install specific modules
bmad install -m bmm cis
# Full installation
bmad install -f
# Check status
bmad status
```
### Installation Options
- `-d <path>`: Target directory (default: current)
- `-m <modules...>`: Specific modules (bmm, cis)
- `-f`: Full installation
- `-c`: Core only
- `-i <ide...>`: Configure specific IDEs
- `--skip-ide`: Skip IDE configuration
- `-v`: Verbose output
## Architecture ## Architecture
### Directory Structure ### Directory Structure upon installation
``` ```
project-root/ project-root/
├── bmad/ # Centralized installation ├── bmad/ # Centralized installation
│ ├── _cfg/ # Configuration │ ├── _cfg/ # Configuration
│ │ ├── agents/ # Agent configs │ │ ├── agents/ # Agent configs
│ │ └── agent-party.xml # Agent manifest │ │ └── agent-manifest.csv # Agent manifest
│ ├── core/ # Core module │ ├── core/ # Core module
│ │ ├── agents/ │ │ ├── agents/
│ │ ├── tasks/ │ │ ├── tasks/
│ │ └── config.yaml │ │ └── config.yaml
│ ├── bmm/ # BMad Method module │ ├── bmm/ # BMad Method module
│ │ ├── agents/ │ │ ├── agents/
│ │ ├── tasks/ │ │ ├── tasks/
│ │ ├── templates/ │ │ ├── workflows/
│ │ └── config.yaml │ │ └── config.yaml
│ └── cis/ # Creative Innovation Studio │ └── cis/ # Creative Innovation Studio
│ └── ... │ └── ...
└── .claude/ # Platform-specific (example) └── .claude/ # Platform-specific (example)
└── agents/ └── agents/
``` ```
@ -78,11 +51,10 @@ project-root/
1. **Detection**: Check existing installation 1. **Detection**: Check existing installation
2. **Selection**: Choose modules interactively or via CLI 2. **Selection**: Choose modules interactively or via CLI
3. **Configuration**: Collect module-specific settings 3. **Configuration**: Collect module-specific settings
4. **Platform Setup**: Configure AI coding platforms 4. **Installation**: Compile Process and copy files
5. **Installation**: Process and copy files 5. **Generation**: Create config files with inheritance
6. **Generation**: Create config files with inheritance 6. **Post-Install**: Run module installers
7. **Post-Install**: Run module installers 7. **Manifest**: Track installed components
8. **Manifest**: Track installed components
### Key Exclusions ### Key Exclusions

30
docs/technical-decisions-template.md
View File

@ -1,30 +0,0 @@
# Technical Decisions Log
_Auto-updated during discovery and planning sessions - you can also add information here yourself_
## Purpose
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
## Confirmed Decisions
<!-- Technical choices explicitly confirmed by the team/user -->
## Preferences
<!-- Non-binding preferences mentioned during discussions -->
## Constraints
<!-- Hard requirements from infrastructure, compliance, or integration needs -->
## To Investigate
<!-- Technical questions that need research or architect input -->
## Notes
- This file is automatically updated when technical information is mentioned
- Decisions here are inputs, not final architecture
- Final technical decisions belong in architecture.md
- Implementation details belong in solutions/\*.md and story context or dev notes.

98
src/core/tools/shard-doc.xml Normal file
View File

@ -0,0 +1,98 @@
<tool id="bmad/core/tasks/shard-doc" name="Shard Document">
<objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
<llm critical="true">
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
<i>DO NOT skip steps or change the sequence</i>
<i>HALT immediately when halt-conditions are met</i>
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
<i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
</llm>
<critical-context>
<i>This task ONLY supports automated sharding via @kayvan/markdown-tree-parser</i>
<i>The tool automatically handles: section splitting, heading level adjustment, code block detection, index generation</i>
<i>All markdown formatting is preserved during sharding</i>
</critical-context>
<flow>
<step n="1" title="Verify Tool Installation">
<action>Check if @kayvan/markdown-tree-parser is installed globally</action>
<action>Run: npm list -g @kayvan/markdown-tree-parser</action>
<action if="not installed">Inform user that tool needs to be installed</action>
<action if="not installed">Run: npm install -g @kayvan/markdown-tree-parser</action>
<action if="installation fails">HALT with error message about npm/node requirements</action>
</step>
<step n="2" title="Get Source Document">
<action>Ask user for the source document path if not provided already</action>
<action>Verify file exists and is accessible</action>
<action>Verify file is markdown format (.md extension)</action>
<action if="file not found or not markdown">HALT with error message</action>
</step>
<step n="3" title="Get Destination Folder">
<action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
<action>Example: /path/to/architecture.md → /path/to/architecture/</action>
<action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
<action if="user accepts default">Use the suggested destination path</action>
<action if="user provides custom path">Use the custom destination path</action>
<action>Verify destination folder exists or can be created</action>
<action>Check write permissions for destination</action>
<action if="permission denied">HALT with error message</action>
</step>
<step n="4" title="Execute Sharding">
<action>Inform user that sharding is beginning</action>
<action>Execute command: md-tree explode [source-document] [destination-folder]</action>
<action>Capture command output and any errors</action>
<action if="command fails">HALT and display error to user</action>
</step>
<step n="5" title="Verify Output">
<action>Check that destination folder contains sharded files</action>
<action>Verify index.md was created in destination folder</action>
<action>Count the number of files created</action>
<action if="no files created">HALT with error message</action>
</step>
<step n="6" title="Report Completion">
<action>Display completion report to user including:</action>
<i>- Source document path and name</i>
<i>- Destination folder path</i>
<i>- Number of section files created</i>
<i>- Confirmation that index.md was created</i>
<i>- Any tool output or warnings</i>
<action>Inform user that sharding completed successfully</action>
</step>
</flow>
<halt-conditions critical="true">
<i>HALT if @kayvan/markdown-tree-parser cannot be installed</i>
<i>HALT if Node.js or npm is not available</i>
<i>HALT if source document does not exist or is inaccessible</i>
<i>HALT if source document is not markdown format (.md)</i>
<i>HALT if destination folder cannot be created</i>
<i>HALT if user does not have write permissions to destination</i>
<i>HALT if md-tree explode command fails</i>
<i>HALT if no output files were created</i>
</halt-conditions>
<tool-info>
<name>@kayvan/markdown-tree-parser</name>
<command>md-tree explode [source-document] [destination-folder]</command>
<installation>npm install -g @kayvan/markdown-tree-parser</installation>
<requirements>
<i>Node.js installed</i>
<i>npm package manager</i>
<i>Global npm installation permissions</i>
</requirements>
<features>
<i>Automatic section splitting by level 2 headings</i>
<i>Automatic heading level adjustment</i>
<i>Handles edge cases (code blocks, diagrams)</i>
<i>Generates navigable index.md</i>
<i>Preserves all markdown formatting</i>
</features>
</tool-info>
</tool>

10
src/modules/bmm/README.md
View File

@ -1,6 +1,6 @@
# BMM - BMad Method Module # BMM - BMad Method Module
The BMM (BMad Method Module) is the core orchestration system for the BMad Method v6a, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks. The BMM (BMad Method Module) is the core orchestration system for the BMad Method, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
## 📚 Essential Reading ## 📚 Essential Reading
@ -120,17 +120,13 @@ BMM integrates seamlessly with the BMad Core framework, leveraging:
- [BMM Workflows Guide](./workflows/README.md) - **Start here!** - [BMM Workflows Guide](./workflows/README.md) - **Start here!**
- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy - [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy
- [Agent Documentation](./agents/README.md) - Individual agent capabilities
- [Team Configurations](./teams/README.md) - Pre-built team setups
- [Task Library](./tasks/README.md) - Reusable task components
## Best Practices ## Best Practices
1. **Always start with the workflows** - Let workflows guide your process 1. **Always start with the workflows** - Let workflows guide your process
2. **Respect the scale** - Don't over-document small projects 2. **Respect the scale** - Don't over-document small projects
3. **Embrace iteration** - Use retrospectives to continuously improve 3. **Trust the process** - The methodology has been carefully designed
4. **Trust the process** - The v6a methodology has been carefully designed
--- ---
For detailed information about the complete BMad Method v6a workflow system, see the [BMM Workflows README](./workflows/README.md). For detailed information about the complete BMad Method workflow system, see the [BMM Workflows README](./workflows/README.md).

8
src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml
View File

@ -4,7 +4,7 @@ description: "Exhaustive deep-dive documentation of specific project areas"
author: "BMad" author: "BMad"
# This is a sub-workflow called by document-project/workflow.yaml # This is a sub-workflow called by document-project/workflow.yaml
parent_workflow: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml" parent_workflow: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml"
# Critical variables inherited from parent # Critical variables inherited from parent
config_source: "{project-root}/bmad/bmb/config.yaml" config_source: "{project-root}/bmad/bmb/config.yaml"
@ -13,13 +13,13 @@ user_name: "{config_source}:user_name"
date: system-generated date: system-generated
# Module path and component files # Module path and component files
installed_path: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/workflows" installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflows"
template: false # Action workflow template: false # Action workflow
instructions: "{installed_path}/deep-dive-instructions.md" instructions: "{installed_path}/deep-dive-instructions.md"
validation: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/checklist.md" validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
# Templates # Templates
deep_dive_template: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/templates/deep-dive-template.md" deep_dive_template: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/templates/deep-dive-template.md"
# Runtime inputs (passed from parent workflow) # Runtime inputs (passed from parent workflow)
workflow_mode: "deep_dive" workflow_mode: "deep_dive"

12
src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml
View File

@ -4,7 +4,7 @@ description: "Complete project documentation workflow (initial scan or full resc
author: "BMad" author: "BMad"
# This is a sub-workflow called by document-project/workflow.yaml # This is a sub-workflow called by document-project/workflow.yaml
parent_workflow: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml" parent_workflow: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml"
# Critical variables inherited from parent # Critical variables inherited from parent
config_source: "{project-root}/bmad/bmb/config.yaml" config_source: "{project-root}/bmad/bmb/config.yaml"
@ -13,15 +13,15 @@ user_name: "{config_source}:user_name"
date: system-generated date: system-generated
# Data files # Data files
project_types_csv: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/data/project-types.csv" project_types_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/project-types.csv"
documentation_requirements_csv: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/data/documentation-requirements.csv" documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/documentation-requirements.csv"
architecture_registry_csv: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/data/architecture-registry.csv" architecture_registry_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/architecture-registry.csv"
# Module path and component files # Module path and component files
installed_path: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/workflows" installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflows"
template: false # Action workflow template: false # Action workflow
instructions: "{installed_path}/full-scan-instructions.md" instructions: "{installed_path}/full-scan-instructions.md"
validation: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/checklist.md" validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
# Runtime inputs (passed from parent workflow) # Runtime inputs (passed from parent workflow)
workflow_mode: "" # "initial_scan" or "full_rescan" workflow_mode: "" # "initial_scan" or "full_rescan"

2
src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
View File

@ -26,7 +26,7 @@ status_file: "{output_folder}/bmm-workflow-status.md"
default_output_file: "{output_folder}/PRD.md" default_output_file: "{output_folder}/PRD.md"
epics_output_file: "{output_folder}/epics.md" epics_output_file: "{output_folder}/epics.md"
technical_decisions_file: "{output_folder}/technical-decisions.md" technical_decisions_file: "{output_folder}/technical-decisions.md"
technical_decisions_template: "{project-root}/src/modules/bmm/_module-installer/assets/technical-decisions.md" technical_decisions_template: "{project-root}/bmad/bmm/_module-installer/assets/technical-decisions.md"
# Recommended input documents # Recommended input documents
recommended_inputs: recommended_inputs:

14
src/modules/bmm/workflows/4-implementation/dev-story/instructions.md
View File

@ -1,7 +1,7 @@
# Develop Story - Workflow Instructions # Develop Story - Workflow Instructions
```xml ```xml
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical> <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical> <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical> <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
<critical>Generate all documents in {document_output_language}</critical> <critical>Generate all documents in {document_output_language}</critical>
@ -52,7 +52,7 @@
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action> <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
<action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.md</action> <action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
<check if="context file exists"> <check if="context file exists">
<action>Read COMPLETE context file</action> <action>Read COMPLETE context file</action>
<action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action> <action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
@ -105,15 +105,15 @@ Expected ready-for-dev or in-progress. Continuing anyway...
<action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action> <action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
<action if="3 consecutive implementation failures occur">HALT and request guidance</action> <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
<action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action> <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
<action if="{{run_until_complete}} == true">Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers</action> <critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
<critical>Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied</critical> <critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
</step> </step>
<step n="3" goal="Author comprehensive tests"> <step n="3" goal="Author comprehensive tests">
<action>Create unit tests for business logic and core functionality introduced/changed by the task</action> <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
<action>Add integration tests for component interactions where applicable</action> <action>Add integration tests for component interactions where desired by test plan or story notes</action>
<action>Include end-to-end tests for critical user flows if applicable</action> <action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
<action>Cover edge cases and error handling scenarios noted in the plan</action> <action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
</step> </step>
<step n="4" goal="Run validations and tests"> <step n="4" goal="Run validations and tests">

9
src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml
View File

@ -7,13 +7,16 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder" output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name" user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language" communication_language: "{config_source}:communication_language"
user_skill_level: "{config_source}:user_skill_level"
document_output_language: "{config_source}:document_output_language"
story_dir: "{config_source}:dev_story_location" story_dir: "{config_source}:dev_story_location"
context_path: "{config_source}:dev_story_location" run_until_complete: "{config_source}:run_until_complete"
run_tests_command: "{config_source}:run_tests_command"
date: system-generated date: system-generated
story_file: "" # Explicit story path; auto-discovered if empty story_file: "" # Explicit story path; auto-discovered if empty
# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.md") # Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
context_file: "{story_dir}/{{story_key}}.context.md" context_file: "{story_dir}/{{story_key}}.context.xml"
# Workflow components # Workflow components
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story" installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"

2
src/modules/bmm/workflows/4-implementation/review-story/instructions.md
View File

@ -55,7 +55,7 @@
</step> </step>
<step n="2" goal="Resolve story context file and specification inputs"> <step n="2" goal="Resolve story context file and specification inputs">
<action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.md" and use the most recent.</action> <action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
<action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action> <action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
<action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action> <action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>

2
src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
View File

@ -49,6 +49,6 @@ variables:
recommended_inputs: recommended_inputs:
- story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')" - story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
- tech_spec: "Epic technical specification document (auto-discovered)" - tech_spec: "Epic technical specification document (auto-discovered)"
- story_context_file: "Story context file (.context.md) (auto-discovered)" - story_context_file: "Story context file (.context.xml) (auto-discovered)"
web_bundle: false web_bundle: false

2
src/modules/bmm/workflows/4-implementation/story-context/instructions.md
View File

@ -9,7 +9,7 @@
<critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical> <critical>If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT.</critical>
<critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical> <critical>Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel.</critical>
<critical>DOCUMENT OUTPUT: Technical context file (.context.md). Concise, structured, project-relative paths only.</critical> <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
<workflow> <workflow>
<step n="1" goal="Find drafted story and check for existing context" tag="sprint-status"> <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">

2
src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml
View File

@ -25,6 +25,6 @@ variables:
# Output configuration # Output configuration
# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication") # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
default_output_file: "{story_dir}/{{story_key}}.context.md" default_output_file: "{story_dir}/{{story_key}}.context.xml"
web_bundle: false web_bundle: false

343
src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md
View File

@ -1,343 +0,0 @@
# Workflow Audit Report
**Workflow:** story-ready
**Audit Date:** 2025-10-25
**Auditor:** Audit Workflow (BMAD v6)
**Workflow Type:** Action (status update workflow)
**Module:** BMM (BMad Method)
---
## Executive Summary
**Overall Status:** EXCELLENT
- Critical Issues: 2
- Important Issues: 2
- Cleanup Recommendations: 0
**Pass Rate:** 94% (66/70 checks passed)
The story-ready workflow is well-structured and follows most BMAD v6 conventions. The workflow correctly uses `web_bundle: false` (intentional for local-only workflow). Critical issues relate to variable inconsistencies and undeclared config variables that are used in instructions.
---
## 1. Standard Config Block Validation
**Status:** ⚠️ CRITICAL ISSUES FOUND
### Required Variables Check:
✅ `config_source` is defined and points to correct module config path
✅ Uses {project-root} variable correctly
✅ `output_folder` pulls from config_source
✅ `user_name` pulls from config_source
✅ `communication_language` pulls from config_source
✅ `date` is set to system-generated
✅ Standard config comment present: "Critical variables from config"
### Critical Issues:
#### Issue 1: Missing Config Variables in YAML
**Severity:** CRITICAL
**Location:** workflow.yaml
The instructions.md file uses the following config variables that are NOT declared in workflow.yaml:
1. `{user_skill_level}` - Used in line 5: "language MUST be tailored to {user_skill_level}"
2. `{document_output_language}` - Used in line 6: "Generate all documents in {document_output_language}"
**Impact:** These variables will not be resolved by the workflow engine, potentially causing confusion or errors.
**Fix Required:**
```yaml
# Critical variables from config
config_source: '{project-root}/bmad/bmm/config.yaml'
output_folder: '{config_source}:output_folder'
user_name: '{config_source}:user_name'
communication_language: '{config_source}:communication_language'
user_skill_level: '{config_source}:user_skill_level' # ADD THIS
document_output_language: '{config_source}:document_output_language' # ADD THIS
date: system-generated
```
#### Issue 2: Variable Path Inconsistency
**Severity:** CRITICAL
**Location:** instructions.md line 3
Instructions reference `{project_root}` (underscore) but workflow.yaml uses `{project-root}` (hyphen).
**Current:** `<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>`
**Should be:** `<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>`
**Impact:** Variable will not resolve correctly, breaking the reference path.
---
## 2. YAML/Instruction/Template Alignment
**Status:** ✅ GOOD (with minor observations)
### Variables Analyzed:
**Workflow.yaml variables (excluding standard config):**
- `story_path` - Used in instructions ✓
- `story_dir` - Used in instructions ✓
**Variables Used in Instructions (not in YAML):**
- `{{story_key}}` - Generated dynamically, output via parsing ✓
- `{{drafted_count}}` - Generated dynamically ✓
- `{{list_of_drafted_story_keys}}` - Generated dynamically ✓
- `{{non_interactive}}` - Conditional logic variable (may be from agent context)
- `{{story_file}}` - Generated dynamically ✓
- `{{story_id}}` - Extracted from story file ✓
- `{{story_title}}` - Extracted from story file ✓
### Summary:
- **Variables in YAML:** 2 (story_path, story_dir)
- **Used in Instructions:** 2/2 (100%)
- **Unused (Bloat):** 0
- **Dynamic Variables:** 7 (appropriate for action workflow)
**Status:** Excellent - No bloat detected, all YAML variables are used appropriately.
---
## 3. Config Variable Usage
**Status:** ⚠️ IMPORTANT ISSUES FOUND
### Communication Language Check:
✅ Instructions use {communication_language} in critical header (line 5)
⚠️ However, the instruction says "Communicate all responses in {communication_language}" but the actual workflow outputs don't explicitly enforce language adaptation
### User Name Check:
✅ User name properly used in final output (line 87): "**Story Marked Ready for Development, {user_name}!**"
✅ Appropriate personalization in workflow completion message
### Output Folder Check:
✅ Output folder referenced correctly: `{{output_folder}}/sprint-status.yaml` (lines 18, 70)
✅ No hardcoded paths detected
✅ All file operations use proper variable references
### Date Usage Check:
✅ Date is available for agent awareness
✅ Not used in outputs (appropriate for action workflow with no document generation)
### User Skill Level Check:
❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 5)
### Document Output Language Check:
❌ **CRITICAL:** Variable used but not declared in workflow.yaml (line 6)
**Config Variable Summary:**
- `communication_language`: ✅ Properly declared and used
- `user_name`: ✅ Properly declared and used
- `output_folder`: ✅ Properly declared and used
- `date`: ✅ Properly declared (available but not used - appropriate)
- `user_skill_level`: ❌ Used but NOT declared
- `document_output_language`: ❌ Used but NOT declared
---
## 4. Web Bundle Validation
**Status:** ✅ CORRECT (N/A)
**Web Bundle Present:** No (`web_bundle: false`)
**Analysis:** The workflow correctly sets `web_bundle: false`. This is appropriate because:
1. This is a local-only action workflow
2. It directly modifies files in the project (sprint-status.yaml, story files)
3. It requires access to the specific project's file system
4. It cannot be executed in a web bundle context where file system access is sandboxed
**Finding:** The absence of web bundle configuration is **EXPECTED and CORRECT** for this workflow type.
**No issues found.**
---
## 5. Bloat Detection
**Status:** ✅ EXCELLENT
### Bloat Analysis:
**Total YAML Fields (excluding metadata and standard config):** 2
- `story_path`
- `story_dir`
**Used Fields:** 2
**Unused Fields:** 0
**Bloat Percentage:** 0%
### Hardcoded Values Check:
✅ No hardcoded file paths (uses {output_folder})
✅ No hardcoded greetings (uses {user_name})
✅ No language-specific text (uses {communication_language})
✅ No static dates (date variable available)
### Redundant Configuration:
✅ No duplicate fields between sections
✅ No commented-out variables
✅ No metadata repetition
**Bloat Summary:** Zero bloat detected. Workflow is lean and efficient.
---
## 6. Template Variable Mapping
**Status:** N/A (Not a document workflow)
This workflow is an action workflow (status update), not a document workflow, so template validation does not apply.
**No template.md file required or expected.**
---
## 7. Additional Quality Checks
### Instruction Quality:
✅ Steps properly numbered (n="1", n="2", n="3")
✅ Each step has clear goal attribute
✅ XML tags used correctly (<action>, <ask>, <check>, <output>, <anchor>)
✅ Conditional logic properly implemented (if attributes)
✅ Flow control is clear and logical
✅ Steps are focused on single goals
✅ Specific, actionable instructions provided
✅ Critical sections properly marked with <critical> tags
### Special Features:
✅ Anchor tag used correctly: `<anchor id="mark_ready" />` (line 59)
✅ Proper GOTO logic: "GOTO mark_ready" (line 15)
✅ Conditional user interaction: `<ask if="{{non_interactive}} == false">` (line 53)
✅ Auto-selection for non-interactive mode (line 54)
### File References:
✅ sprint-status.yaml referenced with proper variable path
✅ Story files referenced with proper directory variable
✅ Preservation instructions included (line 74): "Save file, preserving ALL comments and structure including STATUS DEFINITIONS"
---
## Recommendations
### Critical (Fix Immediately)
**1. Add Missing Config Variables to workflow.yaml**
```yaml
user_skill_level: '{config_source}:user_skill_level'
document_output_language: '{config_source}:document_output_language'
```
**2. Fix Variable Path Inconsistency**
Change line 3 in instructions.md from:
```
{project_root}/bmad/core/tasks/workflow.xml
```
to:
```
{project-root}/bmad/core/tasks/workflow.xml
```
### Important (Address Soon)
**3. Clarify non_interactive Variable Source**
The `{{non_interactive}}` variable is used in line 53-54 but not defined in workflow.yaml. Either:
- Add to workflow.yaml if it's a workflow-specific variable
- Document that it comes from agent context
- Remove if not implemented yet
**4. Document user_skill_level and document_output_language Usage**
If these variables are standard across all BMM workflows:
- Ensure they exist in the module's config.yaml
- Add comments explaining their purpose
- Verify they're actually needed for this action workflow (this workflow generates no documents, so document_output_language may not be necessary)
### Cleanup (Nice to Have)
**No cleanup recommendations** - The workflow is already lean and efficient.
---
## Validation Checklist
Use this checklist to verify fixes:
- [ ] user_skill_level added to workflow.yaml standard config block
- [ ] document_output_language added to workflow.yaml standard config block
- [ ] {project_root} changed to {project-root} in instructions.md line 3
- [ ] non_interactive variable source documented or defined
- [ ] All standard config variables present and correct
- [ ] No unused yaml fields (bloat removed) ✓ (already clean)
- [ ] Config variables used appropriately in instructions ✓
- [ ] Web bundle configuration correct ✓ (intentionally false)
- [ ] File structure follows v6 conventions ✓
---
## Overall Assessment
### Strengths:
1. **Zero bloat** - Every YAML variable is used, no waste
2. **Clear workflow logic** - Simple, focused status update process
3. **Proper file handling** - Uses variables for all paths, preserves file structure
4. **Good UX** - Helpful output messages, clear next steps
5. **Conditional logic** - Supports both interactive and non-interactive modes
6. **Proper web_bundle setting** - Correctly set to false for local-only workflow
### Weaknesses:
1. Uses config variables not declared in workflow.yaml (user_skill_level, document_output_language)
2. Variable naming inconsistency (project_root vs project-root)
3. Unclear source of non_interactive variable
### Overall Grade: **A-** (94%)
This is a well-crafted workflow that follows BMAD v6 conventions closely. The critical issues are minor and easily fixable. Once the missing config variables are added and the path inconsistency is resolved, this workflow will be production-ready.
---
## Next Steps
1. **Immediate:** Add user_skill_level and document_output_language to workflow.yaml
2. **Immediate:** Fix {project_root} → {project-root} in instructions.md
3. **Soon:** Clarify or remove non_interactive variable usage
4. **Soon:** Verify these config variables exist in src/modules/bmm/config.yaml (when it's created)
5. **Optional:** Re-run audit after fixes to verify 100% pass rate
---
**Audit Complete** - Generated by audit-workflow v1.0
**Report Location:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md

591
src/modules/bmm/workflows/README.md
View File

@ -16,47 +16,59 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
**Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last. **Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last.
## The Four Phases ## The Five Phases
``` ```
┌──────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────┐
│ PHASE 0: DOCUMENTATION (Brownfield) │
│ (Conditional - if undocumented) │
├──────────────────────────────────────────────────────────────┤
│ document-project ──→ Codebase documentation │
└────────────────────────────────────────────────────────┼─────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ PHASE 1: ANALYSIS │ │ PHASE 1: ANALYSIS │
│ (Optional) │ │ (Optional) │
├──────────────────────────────────────────────────────────────┤ ├──────────────────────────────────────────────────────────────┤
│ brainstorm-game ──┐ │ │ brainstorm-game ──┐ │
│ brainstorm-project ├──→ research ──→ product-brief ──┐ │ │ brainstorm-project ├──→ research ──→ product-brief ──┐ │
│ game-brief ────────┘ game-brief ┘ │ │ game-brief ────────┘ game-brief │
└────────────────────────────────────────────────────────┼─────┘ └────────────────────────────────────────────────────────┼─────┘
↓ ↓
┌──────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────┐
│ PHASE 2: PLANNING │ │ PHASE 2: PLANNING │
│ (Scale-Adaptive Router - by type) │ │ (Scale-Adaptive Router - by type) │
├──────────────────────────────────────────────────────────────┤ ├──────────────────────────────────────────────────────────────┤
│ SOFTWARE: prd GAMES: gdd │ │ SOFTWARE: prd/tech-spec GAMES: gdd/narrative │
│ ├──→ Level 0: tech-spec only ├──→ GDD (all levels) │ │ ├──→ Level 0: tech-spec only ├──→ GDD (all levels) │
│ ├──→ Level 1: tech-spec only └──→ Narrative design │ │ ├──→ Level 1: tech-spec only └──→ Narrative (opt) │
│ ├──→ Level 2: PRD + tech-spec │ │ ├──→ Level 2: PRD + Epics ──────────────────────────┐ │
│ └──→ Level 3-4: PRD + Epics ────────────────────────┐ │ │ └──→ Level 3-4: PRD + Epics ────────────────────────┼┐ │
└──────────────────────────────────────────────────────────┼───┘ │ UX: create-ux-design (conditional) ││ │
↓ └──────────────────────────────────────────────────────────┼┼──┘
↓↓
┌──────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────┐
│ PHASE 3: SOLUTIONING │ │ PHASE 3: SOLUTIONING │
│ (Software Levels 3-4 / Complex Games) │ │ (Software Levels 2-4 / Complex Games) │
├──────────────────────────────────────────────────────────────┤ ├──────────────────────────────────────────────────────────────┤
│ 3-solutioning ──→ architecture.md │ │ create-architecture ──→ architecture.md │
│ ↓ │ │ validate-architecture (optional) │
│ tech-spec (per epic, JIT during implementation) │ │ solutioning-gate-check (recommended/required) │
└────────────────────────────────────────────────────────────┬─┘ └────────────────────────────────────────────────────────────┬─┘
↓ ↓
┌──────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────┐
│ PHASE 4: IMPLEMENTATION │ │ PHASE 4: IMPLEMENTATION │
│ (Iterative Cycle) │ │ (Sprint-Based Cycle) │
├──────────────────────────────────────────────────────────────┤ ├──────────────────────────────────────────────────────────────┤
│ ┌─→ create-story ──→ story-context ──→ dev-story ──┐ │ │ sprint-planning ──→ sprint-status.yaml │
│ │ ↓ │ │ ↓ │
│ │ retrospective ←── [epic done] ←────── review-story │ │ ┌─→ epic-tech-context (per epic) │
│ │ ↓ │ │ │ ↓ │
│ └──────────── correct-course ←──[if issues]──┘ │ │ │ create-story ──→ story-context ──→ dev-story ─┐ │
│ │ ↓ │
│ │ retrospective ←── [epic done] ←─── review-story │
│ │ ↓ │
│ └──────────── correct-course ←──[if issues]───────┘ │
└──────────────────────────────────────────────────────────────┘ └──────────────────────────────────────────────────────────────┘
``` ```
@ -64,13 +76,7 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
**Before starting any workflow, check your status!** **Before starting any workflow, check your status!**
The `workflow-status` workflow is the **universal entry point** for all BMM workflows: The `workflow-status` workflow is the **universal entry point** for all BMM workflows, if you have not already set up your workflow, run `workflow-init`, but even if you just run the workflow-status and the file does not exist you should still be directed to run workflow-init.
```bash
bmad analyst workflow-status
# or
bmad pm workflow-status
```
**What it does:** **What it does:**
@ -83,8 +89,7 @@ bmad pm workflow-status
**No status file?** It will: **No status file?** It will:
1. Ask about project context (greenfield vs brownfield) 1. Ask about project context (greenfield vs brownfield)
2. Offer analysis options (full analysis, skip to planning, or quick tech spec) 2. Generate your bmm-workflow-status.md file.
3. Guide you to the right first workflow
**Status file exists?** It will: **Status file exists?** It will:
@ -93,7 +98,27 @@ bmad pm workflow-status
3. Recommend exact next action 3. Recommend exact next action
4. Offer to change workflow or display menu 4. Offer to change workflow or display menu
**All agents (bmad-master, analyst, pm) should check workflow-status on load.** **All phase 1-3 workflows should check workflow-status on start of the workflow.**
---
## Phase 0: Documentation (Brownfield Only)
Required for undocumented brownfield projects before planning can begin.
### Workflows
| Workflow | Agent | Purpose | Output | When to Use |
| -------------------- | ------- | -------------------------- | --------------------- | -------------------------------- |
| **document-project** | Analyst | Document existing codebase | Project documentation | Brownfield without adequate docs |
### Flow
```
Brownfield Check → document-project → Analysis/Planning (Phase 1/2)
```
**Critical**: Brownfield projects require adequate documentation before planning. If workflow-init detects an undocumented brownfield project, it will direct you to run document-project first.
--- ---
@ -103,14 +128,15 @@ Optional workflows for project discovery and requirements gathering. Output feed
### Workflows ### Workflows
| Workflow | Purpose | Output | When to Use | | Workflow | Agent | Purpose | Output | When to Use |
| ---------------------- | ------------------------------------------- | ------------------------- | ---------------------- | | ---------------------- | ------------- | ------------------------------------------- | ------------------------- | --------------------- |
| **workflow-status** | Universal entry point and status checker | Status display + guidance | **Always start here!** | | **workflow-status** | Analyst | Universal entry point and status checker | Status display + guidance | **Start here!** |
| **brainstorm-game** | Game concept ideation using 5 methodologies | Concept proposals | New game projects | | **workflow-init** | Analyst | Generate an initial workflow status file | Status display + guidance | **OR start here!** |
| **brainstorm-project** | Software solution exploration | Architecture proposals | New software projects | | **brainstorm-game** | Game Designer | Game concept ideation using 5 methodologies | Concept proposals | New game projects |
| **game-brief** | Structured game design foundation | Game brief document | Before GDD creation | | **brainstorm-project** | Analyst | Software solution exploration | Architecture proposals | New software projects |
| **product-brief** | Strategic product planning culmination | Product brief | End of analysis phase | | **game-brief** | Game Designer | Structured game design foundation | Game brief document | Before GDD creation |
| **research** | Multi-mode research (market/technical/deep) | Research artifacts | When evidence needed | | **product-brief** | Analyst | Strategic product planning culmination | Product brief | End of analysis phase |
| **research** | Analyst | Multi-mode research (market/technical/deep) | Research artifacts | When evidence needed |
### Flow ### Flow
@ -120,140 +146,112 @@ workflow-status (check) → Brainstorming → Research → Brief → Planning (P
## Phase 2: Planning (Required) ## Phase 2: Planning (Required)
The central orchestrator that determines project scale and generates appropriate planning artifacts.
### Scale Levels ### Scale Levels
| Level | Scope | Outputs | Next Phase | | Level | Scope | Outputs | Next Phase |
| ----- | ------------------------ | ------------------------------ | ------------------------------ | | ----- | ------------------------ | ------------------------------ | ------------------------------ |
| **0** | Single atomic change | tech-spec + 1 story | → Implementation | | **0** | Single atomic change | tech-spec + 1 story | → Implementation |
| **1** | 1-10 stories, 1 epic | tech-spec + epic + 2-3 stories | → Implementation | | **1** | 1-10 stories, 1 epic | tech-spec + epic + 2-3 stories | → Implementation |
| **2** | 5-15 stories, 1-2 epics | PRD + epics | → Tech-spec → Implementation | | **2** | 5-15 stories, 1-2 epics | PRD + epics | → Solutioning → Implementation |
| **3** | 12-40 stories, 2-5 epics | PRD + epics | → Solutioning → Implementation | | **3** | 12-40 stories, 2-5 epics | PRD + epics | → Solutioning → Implementation |
| **4** | 40+ stories, 5+ epics | PRD + epics | → Solutioning → Implementation | | **4** | 40+ stories, 5+ epics | PRD + epics | → Solutioning → Implementation |
**Key Changes (v6a):** ### Available Workflows
- **Level 0**: Now generates a single user story in addition to tech-spec | Workflow | Agent | Purpose | Output | Levels |
- **Level 1**: Now generates 2-3 stories as part of planning (prefer longer stories over more stories) | -------------------- | ----------- | ------------------------------------ | -------------- | ----------- |
- Both Level 0/1 skip Phase 3 and populate Phase 4 story backlog automatically | **prd** | PM | Product Requirements Document | PRD.md + epics | 2-4 |
| **tech-spec** | PM | Technical specification | tech-spec.md | 0-1 |
### Routing Logic | **gdd** | PM | Game Design Document | GDD.md | Games (all) |
| **narrative** | PM | Game narrative design | narrative.md | Games (opt) |
**Universal Entry Point** (workflow-status): | **create-ux-design** | UX Designer | User experience and interface design | ux-design.md | Conditional |
```
workflow-status
├─→ Check for existing status file
│ ├─→ If exists: Display status + recommend next action
│ └─→ If not exists: Guide workflow planning
├─→ Determine project context (greenfield/brownfield)
├─→ Determine project type (game/web/mobile/backend/etc)
├─→ Assess complexity → assign Level 0-4
├─→ Map complete workflow journey
└─→ Generate bmm-workflow-status.md + direct to first workflow
```
**Direct Routing** (no intermediate routers):
```
workflow-status determines routing:
SOFTWARE PROJECTS:
├─→ Level 0-1 → bmad architect tech-spec
│ └─→ Validates status file + level
│ └─→ Generates tech-spec.md + stories
│ └─→ Direct to Phase 4 (implementation)
│
├─→ Level 2 → bmad pm prd
│ └─→ Validates status file + level
│ └─→ Generates PRD.md + epics.md
│ └─→ Then: bmad architect tech-spec (lightweight solutioning)
│ └─→ Then: Phase 4 (implementation)
│
└─→ Level 3-4 → bmad pm prd
└─→ Validates status file + level
└─→ Generates PRD.md + epics.md
└─→ Then: Phase 3 (architecture)
└─→ Then: Phase 4 (implementation)
GAME PROJECTS:
└─→ All Levels → bmad pm gdd
└─→ Validates status file + project type
└─→ Generates GDD.md + epics.md
└─→ Optional: narrative design
└─→ Then: Phase 3 or 4 (based on complexity)
```
### Key Outputs ### Key Outputs
- **PRD.md**: Product Requirements Document (Levels 2-4) - **PRD.md**: Product Requirements Document (Levels 2-4)
- **Epics.md**: Epic breakdown with stories (Levels 2-4) - **Epics.md**: Epic breakdown with stories (Levels 2-4)
- **epic-stories.md**: Epic summary with story links (Level 1) - **tech-spec.md**: Technical specification (Levels 0-1)
- **tech-spec.md**: Technical specification (Levels 0-2 only)
- **story-{slug}.md**: Single user story (Level 0) - **story-{slug}.md**: Single user story (Level 0)
- **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1) - **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1)
- **GDD.md**: Game Design Document (game projects) - **GDD.md**: Game Design Document (game projects)
- **bmm-workflow-status.md**: Versioned workflow state tracking with story backlog - **narrative.md**: Narrative design (game projects, optional)
- **ux-design.md**: UX specification (conditional, UI-heavy projects)
- **bmm-workflow-status.md**: Versioned workflow state tracking
## Phase 3: Solutioning (Levels 3-4 Only) ## Phase 3: Solutioning (Levels 2-4)
Architecture and technical design phase for complex projects. Architecture and technical design phase for medium to complex projects.
### Workflows ### Workflows
| Workflow | Owner | Purpose | Output | Timing | | Workflow | Agent | Purpose | Output | When |
| ----------------- | --------- | ------------------------------ | ------------------------- | ----------------- | | -------------------------- | --------- | -------------------------------- | ------------------------- | ----------- |
| **3-solutioning** | Architect | Create overall architecture | architecture.md with ADRs | Once per project | | **create-architecture** | Architect | Create system-wide architecture | architecture.md with ADRs | Levels 2-4 |
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT | | **validate-architecture** | Architect | Validate architecture design | Validation report | Optional |
| **solutioning-gate-check** | Architect | Validate PRD + UX + architecture | Gate check report | Recommended |
### Just-In-Time Tech Specs ### Architecture Scope by Level
``` - **Level 2**: Lightweight architecture document focusing on key technical decisions
FOR each epic in sequence: - **Level 3-4**: Comprehensive architecture with detailed ADRs, system diagrams, integration patterns
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) ## Phase 4: Implementation (Iterative)
The core development cycle that transforms requirements into working software. The core development cycle that transforms requirements into working software through sprint-based iteration.
### The Story State Machine ### Sprint Planning - The Phase 4 Entry Point
Phase 4 uses a 4-state lifecycle to manage story progression, tracked in `bmm-workflow-status.md`: Phase 4 begins with the **sprint-planning** workflow, which generates a `sprint-status.yaml` file that serves as the single source of truth for all implementation tracking.
**What sprint-planning does:**
1. Extracts all epics and stories from epic files
2. Creates ordered status tracking for every work item
3. Auto-detects existing story files and contexts
4. Maintains status through the development lifecycle
### The Sprint Status System
Phase 4 uses a 6-state lifecycle tracked in `sprint-status.yaml`:
**Epic Status Flow:**
``` ```
BACKLOG → TODO → IN PROGRESS → DONE backlog → contexted
``` ```
#### State Definitions **Story Status Flow:**
- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition) ```
- Contains all stories with IDs, titles, and file names backlog → drafted → ready-for-dev → in-progress → review → done
- Order is sequential (Epic 1 stories first, then Epic 2, etc.) ```
- **TODO**: Single story that needs drafting (or drafted, awaiting approval) **Retrospective Status:**
- SM drafts story here using `create-story` workflow
- Story status is "Draft" until user approves
- User runs `story-ready` workflow to approve
- **IN PROGRESS**: Single story approved for development ```
- Moved here by `story-ready` workflow optional ↔ completed
- DEV implements using `dev-story` workflow ```
- Story status is "Ready" or "In Review"
- **DONE**: Completed stories with dates and points #### Status Definitions
- Moved here by `story-done` workflow after DoD complete
- Immutable record of completed work
**Key Innovation**: Agents never search for "next story" - they always read the exact story from the status file. **Epic Statuses:**
- **backlog**: Epic exists in epic file but not yet contexted
- **contexted**: Epic technical context created (prerequisite for drafting stories)
**Story Statuses:**
- **backlog**: Story only exists in epic file, not yet drafted
- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
- **ready-for-dev**: Draft approved + story context created
- **in-progress**: Developer actively working on implementation
- **review**: Under SM review (via review-story workflow)
- **done**: Story completed and deployed
**Retrospective Statuses:**
- **optional**: Can be done but not required
- **completed**: Retrospective has been completed
### The Implementation Loop ### The Implementation Loop
@ -261,44 +259,45 @@ BACKLOG → TODO → IN PROGRESS → DONE
Phase Transition (Phase 2 or 3 → Phase 4) Phase Transition (Phase 2 or 3 → Phase 4)
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ BACKLOG populated with all stories │ │ SM: sprint-planning │
│ TODO initialized with first story │ │ Creates: sprint-status.yaml with all epics/ │
│ stories set to 'backlog' │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ SM: create-story (drafts story in TODO) │ │ SM: epic-tech-context (for current epic) │
│ Reads: status file TODO section │ │ Creates: epic-N-context.md │
│ Output: Story file with Status="Draft" │ │ Updates: Epic status to 'contexted' │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ User reviews story │ │ SM: create-story (drafts next backlog story) │
│ ↓ │ │ Creates: story-{key}.md │
│ SM: story-ready (approves story) │ │ Updates: Story status to 'drafted' │
│ Actions: TODO → IN PROGRESS │
│ BACKLOG → TODO (next story) │
│ Story Status = "Ready" │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ SM: story-context (optional but recommended) │ │ SM: story-context (creates implementation ctx) │
│ Generates expertise injection XML │ │ Creates: story-{key}-context.md │
│ Updates: Story status to 'ready-for-dev' │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ DEV: dev-story (implements story) │ │ DEV: dev-story (implements story) │
│ Reads: status file IN PROGRESS section │ │ Reads: story + context files │
│ Implements with context injection │ │ Updates: Story status to 'in-progress' │
│ then to 'review' when complete │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌─────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ User reviews implementation (DoD check) │ │ SM: review-story (validates implementation) │
│ ↓ │ │ Reviews: Code changes against DoD │
│ DEV: story-done (marks story done) │ │ Feedback: Iteration or approval │
│ Actions: IN PROGRESS → DONE │ └───────────────────┬─────────────────────────────┘
│ TODO → IN PROGRESS (if exists) │ ↓
│ BACKLOG → TODO (if exists) │ ┌─────────────────────────────────────────────────┐
│ Story Status = "Done" │ │ DEV/SM: Updates story status to 'done' │
│ Manual update to sprint-status.yaml │
└───────────────────┬─────────────────────────────┘ └───────────────────┬─────────────────────────────┘
↓ ↓
┌───────┴────────┐ ┌───────┴────────┐
@ -306,157 +305,175 @@ Phase Transition (Phase 2 or 3 → Phase 4)
└───────┬─────────┘ └───────┬─────────┘
┌───┴───┐ ┌───┴───┐
↓ ↓ ↓ ↓
[Yes: Loop] [No: Epic/Project Complete] [Yes: Loop] [No: Epic Complete]
↓ ↓
[retrospective] ┌─────────────────┐
│ SM: retrospective│
│ Updates: epic-N- │
│ retrospective to │
│ 'completed' │
└─────────────────┘
``` ```
### Workflow Responsibilities ### Workflow Responsibilities
| Workflow | Agent | Purpose | State Transition | No Search Required | | Workflow | Agent | Purpose | Status Updates |
| ------------------ | ------ | ------------------------------------- | --------------------- | ------------------------ | | --------------------- | ----- | -------------------------------------- | ------------------------------------------- |
| **create-story** | SM | Draft story from TODO section | (Story stays in TODO) | Reads TODO section | | **sprint-planning** | SM | Initialize sprint status tracking | Creates sprint-status.yaml |
| **story-ready** | SM | Approve drafted story for development | TODO → IN PROGRESS | Reads TODO section | | **epic-tech-context** | SM | Create epic-specific technical context | Epic: backlog → contexted |
| **story-context** | SM | Generate expertise injection XML | (No state change) | Reads IN PROGRESS | | **create-story** | SM | Draft individual story files | Story: backlog → drafted |
| **dev-story** | DEV | Implement story | (No state change) | Reads IN PROGRESS | | **story-context** | SM | Generate implementation context/XML | Story: drafted → ready-for-dev |
| **story-done** | DEV | Mark story done after DoD complete | IN PROGRESS → DONE | Reads IN PROGRESS | | **dev-story** | DEV | Implement story | Story: ready-for-dev → in-progress → review |
| **review-story** | SR/DEV | Quality validation (optional) | (No state change) | Manual story selection | | **review-story** | SM/SR | Quality validation and feedback | (No automatic state change) |
| **correct-course** | SM | Handle issues/changes | (Adaptive) | Manual story selection | | **retrospective** | SM | Capture epic learnings | Retrospective: optional → completed |
| **retrospective** | SM | Capture epic learnings | (No state change) | Manual or epic-triggered | | **correct-course** | SM | Handle issues/scope changes | (Adaptive based on situation) |
### Story File Status Values ### Key Guidelines
Stories have a `Status:` field in their markdown file that reflects their position in the state machine: 1. **Epic Context First**: Epics should be `contexted` before their stories can be `drafted`
2. **Sequential by Default**: Stories are typically worked in order within an epic
3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
4. **Learning Transfer**: SM drafts next story after previous is `done` to incorporate learnings
5. **Flexible Status Updates**: Agents and users can manually update sprint-status.yaml as needed
## Greenfield vs Brownfield Paths
### Greenfield Projects (New Code)
**Path:** Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
- **Level 0-1**: Skip Phase 3, go straight to implementation with tech-spec
- **Level 2-4**: Full solutioning with architecture before implementation
- Clean slate for architectural decisions
- No existing patterns to constrain design
### Brownfield Projects (Existing Code)
**Path:** Phase 0 (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
**Phase 0 - Documentation (Conditional):**
``` ```
Status: Draft (Story created by create-story, awaiting user review) workflow-status/workflow-init
↓
Status: Ready (User approved via story-ready, ready for implementation)
↓
Status: In Review (Implementation complete, awaiting final approval)
↓
Status: Done (User approved via story-done, DoD complete)
```
**Status File Position vs Story File Status:**
| Status File State | Story File Status | Meaning |
| ----------------- | -------------------- | ------------------------------------- |
| BACKLOG | (file doesn't exist) | Story not yet drafted |
| TODO | Draft | Story drafted, awaiting user approval |
| IN PROGRESS | Ready or In Review | Story approved for development |
| DONE | Done | Story complete, DoD met |
## 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
```
workflow-init (Phase 2)
├─→ Check: Is existing codebase documented? ├─→ Check: Is existing codebase documented?
│ ├─→ YES: Proceed with planning │ ├─→ YES: Proceed to Phase 1 or 2
│ └─→ NO: HALT with message: │ └─→ NO: REQUIRED - Run document-project workflow
│ "Brownfield project requires documentation. │ ├─→ Analyzes existing code
│ Please run codebase-analysis workflow first." │ ├─→ Documents current architecture
│ └─→ [TBD: brownfield-analysis workflow] │ ├─→ Identifies technical debt
│ ├─→ Analyzes existing code │ └─→ Creates baseline documentation
│ ├─→ Documents current architecture
│ ├─→ Identifies technical debt
│ └─→ Creates baseline documentation
└─→ Continue with scale-adaptive planning └─→ 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: **Critical for Brownfield**:
- Map existing architecture - Must understand existing patterns before planning
- Document current patterns - Integration points need documentation
- Identify integration points - Technical debt must be visible in planning
- Assess technical debt - Constraints from existing system affect scale decisions
- Create the baseline needed for planning
## Agent Participation by Phase ## Agent Participation by Phase
| Phase | Primary Agents | Supporting Agents | | Phase | Primary Agents | Supporting Agents | Key Workflows |
| ------------------ | ------------------- | --------------------------- | | --------------------- | ---------------------- | -------------------- | ------------------------------------------- |
| **Analysis** | Analyst, Researcher | PM, PO | | **0: Documentation** | Analyst | - | document-project |
| **Planning** | PM | Analyst, UX Designer | | **1: Analysis** | Analyst, Game Designer | PM, Researcher | brainstorm-_, research, _-brief |
| **Solutioning** | Architect | PM, Tech Lead | | **2: Planning** | PM | UX Designer, Analyst | prd, tech-spec, gdd, narrative |
| **Implementation** | SM, DEV | SR, PM (for correct-course) | | **3: Solutioning** | Architect | PM, Tech Lead | create-architecture, solutioning-gate-check |
| **4: Implementation** | SM, DEV | SR (review-story) | sprint-planning, create-story, dev-story |
## Key Files and Artifacts ## Key Files and Artifacts
### Tracking Documents ### Tracking Documents
- **bmm-workflow-status.md**: Versioned workflow state tracking with 4-section story backlog - **bmm-workflow-status.md**: Phase and workflow tracking (updated by workflow-status)
- **BACKLOG**: Ordered list of stories to be drafted - Current phase and progress
- **TODO**: Single story ready for drafting (or drafted, awaiting approval) - Workflow history
- **IN PROGRESS**: Single story approved for development - Next recommended actions
- **DONE**: Completed stories with dates and points - Project metadata and configuration
- Populated automatically at phase transitions
- Single source of truth for story progression
- Agents read (never search) to know what to work on next
- **Epics.md**: Master list of epics and stories (source of truth for planning, Level 2-4) - **sprint-status.yaml**: Implementation tracking (Phase 4 only)
- All epics, stories, and retrospectives
- Current status for each item (backlog → done)
- Single source of truth for Phase 4 progression
- Updated by agents as work progresses
- **Epics.md**: Master epic/story definitions (source of truth for planning, Level 2-4)
### Phase Outputs ### Phase Outputs
- **Phase 1**: Briefs and research documents - **Phase 0**:
- Codebase documentation (project overview, architecture, source tree)
- **Phase 1**:
- Product briefs, game briefs, research documents
- **Phase 2**: - **Phase 2**:
- Level 0: tech-spec.md + story-{slug}.md - Level 0: tech-spec.md + story-{slug}.md
- Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files - Level 1: tech-spec.md + epic breakdown + story-{slug}-N.md files
- Level 2: PRD.md + epics.md (then tech-spec.md in Phase 3) - Level 2-4: PRD.md + epics.md (+ optional ux-design.md, narrative.md)
- Level 3-4: PRD.md + epics.md (then architecture.md in Phase 3)
- **Phase 3**: architecture.md, epic-specific tech specs - **Phase 3**:
- **Phase 4**: Story files, context XMLs, implemented code - architecture.md (with ADRs)
- Validation reports
- Gate check documentation
- **Phase 4**:
- sprint-status.yaml (tracking file)
- epic-N-context.md files (per epic)
- story-{key}.md files (per story)
- story-{key}-context.md files (per story)
- Implemented code and tests
## Best Practices ## Best Practices
### 1. Respect the Scale ### 1. Respect the Scale
- Don't create PRDs for Level 0 changes - Don't create PRDs for Level 0-1 changes (use tech-spec only)
- Don't skip architecture for Level 3-4 projects - Don't skip architecture for Level 2-4 projects
- Let the workflow determine appropriate artifacts - Let the workflow paths determine appropriate artifacts
- Level 2 still requires Phase 3 solutioning (lighter than 3-4)
### 2. Embrace Just-In-Time ### 2. Use Sprint Planning Effectively
- Create tech specs one epic at a time - Run sprint-planning at the start of Phase 4
- Generate stories as needed, not in batches - Context epics before drafting their stories (epic-tech-context)
- Build context injections per story - Update sprint-status.yaml as work progresses
- Re-run sprint-planning to auto-detect new files/contexts
### 3. Maintain Flow Integrity ### 3. Maintain Flow Integrity
- Stories must be enumerated in Epics.md - Stories must be defined in Epics.md before sprint-planning
- Complete epic context before story drafting
- Create story context before implementation
- Each phase completes before the next begins - Each phase completes before the next begins
- Use fresh context windows for reviews
### 4. Document Brownfield First ### 4. Document Brownfield First
- Never plan without understanding existing code - Never plan without understanding existing code
- Run document-project if codebase is undocumented
- Technical debt must be visible in planning - Technical debt must be visible in planning
- Integration points need documentation - Integration points need documentation
### 5. Learn Continuously ### 5. Learn Continuously
- Run retrospectives after each epic - Run retrospectives after each epic
- Update workflows based on learnings - Incorporate learnings into next story drafts
- Update workflows based on team feedback
- Share patterns across teams - Share patterns across teams
## Common Pitfalls and Solutions ## Common Pitfalls and Solutions
| Pitfall | Solution | | Pitfall | Solution |
| --------------------------------- | ------------------------------------- | | ------------------------------------- | ----------------------------------------------------- |
| Creating all tech specs upfront | Use JIT approach - one epic at a time | | Skipping sprint-planning | Always run at Phase 4 start - it creates status file |
| Skipping story-context generation | Always run after create-story | | Creating stories without epic context | Run epic-tech-context before create-story |
| Batching story creation | Create one story at a time | | Skipping story-context generation | Always run after create-story for better dev guidance |
| Ignoring scale levels | Let workflow init determine level | | Not updating sprint-status.yaml | Update statuses as work progresses |
| Planning brownfield without docs | Run brownfield-analysis first | | Thinking Level 2 skips Phase 3 | Level 2 DOES require architecture (just lighter) |
| Not running retrospectives | Schedule after every epic | | Planning brownfield without docs | Run document-project first if undocumented |
| Not running retrospectives | Complete after every epic for learning transfer |
| Manually tracking stories elsewhere | Use sprint-status.yaml as single source of truth |
## Quick Reference Commands ## Quick Reference Commands
@ -464,47 +481,67 @@ workflow-init (Phase 2)
# Universal Entry Point (Start Here!) # Universal Entry Point (Start Here!)
bmad analyst workflow-status # Check status and get recommendations bmad analyst workflow-status # Check status and get recommendations
# Phase 0: Documentation (Brownfield if needed)
bmad analyst document-project
# Phase 1: Analysis (Optional) # Phase 1: Analysis (Optional)
bmad analyst brainstorm-project bmad analyst brainstorm-project # Software ideation
bmad analyst research bmad game-designer brainstorm-game # Game ideation
bmad analyst product-brief bmad analyst research # Market/technical research
bmad analyst product-brief # Software brief
bmad game-designer game-brief # Game brief
# Phase 2: Planning # Phase 2: Planning (Required)
bmad pm prd # Level 2-4 software projects bmad pm prd # Level 2-4 software projects
bmad architect tech-spec # Level 0-1 software projects bmad pm tech-spec # Level 0-1 software projects
bmad pm gdd # Game projects bmad pm gdd # Game projects (all levels)
bmad pm narrative # Game narrative (optional)
bmad ux-designer create-ux-design # UI-heavy projects
# Phase 3: Solutioning (L3-4) # Phase 3: Solutioning (Levels 2-4)
bmad architect architecture bmad architect create-architecture # System architecture
bmad architect tech-spec # Per epic, JIT bmad architect validate-architecture # Validation (optional)
bmad architect solutioning-gate-check # Gate check
# Phase 4: Implementation # Phase 4: Implementation (Sprint-Based)
bmad sm create-story # Draft story from TODO section bmad sm sprint-planning # FIRST: Initialize sprint tracking
bmad sm story-ready # Approve story for development (after user review) bmad sm epic-tech-context # Create epic context (per epic)
bmad sm story-context # Generate context XML (optional but recommended) bmad sm create-story # Draft story file
bmad dev dev-story # Implement story from IN PROGRESS section bmad sm story-context # Create story context
bmad dev story-done # Mark story done (after user confirms DoD) bmad dev dev-story # Implement story
bmad dev review-story # Quality validation (optional) bmad sm review-story # Quality validation
bmad sm correct-course # If issues arise # (Update sprint-status.yaml to 'done' manually or via workflow)
bmad sm retrospective # After epic complete bmad sm retrospective # After epic complete
bmad sm correct-course # If issues arise
``` ```
## Future Enhancements ## Future Enhancements
### Coming Soon ### Coming Soon
- **brownfield-analysis**: Automated codebase documentation generator - **Automated status updates**: Workflows automatically update sprint-status.yaml
- **Workflow orchestration**: Automatic phase transitions - **Workflow orchestration**: Automatic phase transitions and validation
- **Progress dashboards**: Real-time workflow status - **Progress dashboards**: Real-time workflow status visualization
- **Team synchronization**: Multi-developer story coordination - **Team synchronization**: Multi-developer story coordination
### Under Consideration ### Under Consideration
- AI-assisted retrospectives - AI-assisted retrospectives with pattern detection
- Automated story sizing - Automated story sizing based on historical data
- Predictive epic planning - Predictive epic planning with risk assessment
- Cross-project learning transfer - Cross-project learning transfer
- Enhanced brownfield analysis with architectural debt scoring
--- ---
**Version**: v6-alpha
**Last Updated**: 2025-10-26
This document serves as the authoritative guide to BMM v6a workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders. This document serves as the authoritative guide to BMM v6a workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.
## Related Documentation
- **Workflow Paths**: See `workflow-status/paths/` for detailed greenfield/brownfield routing by level
- **Phase 2 Planning**: See `2-plan-workflows/README.md` for scale-adaptive planning details
- **Phase 4 Sprint Planning**: See `4-implementation/sprint-planning/README.md` for sprint status system
- **Individual Workflows**: Each workflow directory contains its own README with specific instructions

2
src/modules/bmm/workflows/workflow-status/init/workflow.yaml
View File

@ -19,7 +19,7 @@ instructions: "{installed_path}/instructions.md"
template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.md" template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.md"
# Path data files # Path data files
path_files: "{project-root}/src/modules/bmm/workflows/workflow-status/paths/" path_files: "{project-root}/bmad/bmm/workflows/workflow-status/paths/"
# Output configuration # Output configuration
default_output_file: "{output_folder}/bmm-workflow-status.md" default_output_file: "{output_folder}/bmm-workflow-status.md"