diff --git a/docs/antipattern-audit-2025-10-22.md b/docs/antipattern-audit-2025-10-22.md deleted file mode 100644 index 1ce2d3e4..00000000 --- a/docs/antipattern-audit-2025-10-22.md +++ /dev/null @@ -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 `` 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 - -If condition met: -Do something -Do something else -``` - -**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 - -Do something -``` - -**Multiple conditional actions:** - -```xml - - - Do something - Do something else - -``` - ---- - -## 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 -If yes: - Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml - Pass context data: {installed_path}/brainstorm-context.md - Wait for brainstorming session completion - - If no: - Proceed directly to Step 0 -``` - -**AFTER (Correct):** - -```xml - - Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml - Pass context data: {installed_path}/brainstorm-context.md - Wait for brainstorming session completion - - - - Proceed directly to Step 0 - -``` - -### Example 2: dev-story/instructions.md (Line 54-55) - -**BEFORE (Invalid):** - -```xml -If story file inaccessible β†’ HALT: "Cannot develop story without access to story file" -If task requirements ambiguous β†’ ASK user to clarify or HALT -``` - -**AFTER (Correct):** - -```xml -HALT: "Cannot develop story without access to story file" -ASK user to clarify or HALT -``` - ---- - -## 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 -action if="condition" - Single conditional action (inline, no closing tag needed) -check if="condition">... - Conditional block wrapping multiple items (closing tag required) -``` - -**Key Point:** Check tags MUST have `if=""` attribute and MUST wrap content with closing tag. - -The self-closing pattern `text` is **NOT in the spec** and is **invalid**. - ---- - -## Detection Command - -To find all instances: - -```bash -grep -r "[^<]*" src --include="*.md" -n -``` - -To count by file: - -```bash -grep -r "[^<]*" 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 diff --git a/docs/codebase-flattener.md b/docs/codebase-flattener.md deleted file mode 100644 index 26a10924..00000000 --- a/docs/codebase-flattener.md +++ /dev/null @@ -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 diff --git a/docs/conversion-report-shard-doc-2025-10-26.md b/docs/conversion-report-shard-doc-2025-10-26.md new file mode 100644 index 00000000..dcf7c382 --- /dev/null +++ b/docs/conversion-report-shard-doc-2025-10-26.md @@ -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 `` section (simplified to tool-only) +βœ… **Critical Instructions**: Moved to `` section +βœ… **Validation Rules**: Extracted to `` section +βœ… **Halt Conditions**: Extracted to `` section +βœ… **Special Guidelines**: Moved to `` section +βœ… **Output Format**: Documented in `` section +βœ… **Tool Information**: Preserved in `` 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 `` wrapper with id and name attributes +- βœ… `` section with mandatory instructions +- βœ… `` section with numbered `` elements +- βœ… Used `` tags for required actions +- βœ… Used `` 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 + + ... + ... + ... + + + ... + + + ... + ... + +``` + +--- + +## 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 +{project-root}/bmad/core/tasks/shard-doc.xml +``` + +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) diff --git a/docs/installers-bundlers/ide-injections.md b/docs/installers-bundlers/ide-injections.md index 4b8a87ed..c09b8ba1 100644 --- a/docs/installers-bundlers/ide-injections.md +++ b/docs/installers-bundlers/ide-injections.md @@ -184,13 +184,3 @@ injections: ... ``` - -## 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 diff --git a/docs/installers-bundlers/installers-modules-platforms-reference.md b/docs/installers-bundlers/installers-modules-platforms-reference.md index 101e7206..f9437d74 100644 --- a/docs/installers-bundlers/installers-modules-platforms-reference.md +++ b/docs/installers-bundlers/installers-modules-platforms-reference.md @@ -1,4 +1,4 @@ -# BMAD v6 Installation & Module System Reference +# BMAD Installation & Module System Reference ## Table of Contents @@ -13,63 +13,36 @@ ## 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 -- **Modular Design**: Core + optional modules (BMM, CIS) +- **Modular Design**: Core + optional modules (BMB, BMM, CIS) - **Smart Installation**: Interactive configuration with dependency resolution -- **Multi-Platform**: Supports 15+ AI coding platforms -- **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 `: Target directory (default: current) -- `-m `: Specific modules (bmm, cis) -- `-f`: Full installation -- `-c`: Core only -- `-i `: Configure specific IDEs -- `--skip-ide`: Skip IDE configuration -- `-v`: Verbose output +- **Clean Architecture**: Centralized `bmad/` directory add to project, no source pollution with multiple folders added ## Architecture -### Directory Structure +### Directory Structure upon installation ``` project-root/ -β”œβ”€β”€ bmad/ # Centralized installation -β”‚ β”œβ”€β”€ _cfg/ # Configuration -β”‚ β”‚ β”œβ”€β”€ agents/ # Agent configs -β”‚ β”‚ └── agent-party.xml # Agent manifest -β”‚ β”œβ”€β”€ core/ # Core module +β”œβ”€β”€ bmad/ # Centralized installation +β”‚ β”œβ”€β”€ _cfg/ # Configuration +β”‚ β”‚ β”œβ”€β”€ agents/ # Agent configs +β”‚ β”‚ └── agent-manifest.csv # Agent manifest +β”‚ β”œβ”€β”€ core/ # Core module β”‚ β”‚ β”œβ”€β”€ agents/ β”‚ β”‚ β”œβ”€β”€ tasks/ β”‚ β”‚ └── config.yaml -β”‚ β”œβ”€β”€ bmm/ # BMad Method module +β”‚ β”œβ”€β”€ bmm/ # BMad Method module β”‚ β”‚ β”œβ”€β”€ agents/ β”‚ β”‚ β”œβ”€β”€ tasks/ -β”‚ β”‚ β”œβ”€β”€ templates/ +β”‚ β”‚ β”œβ”€β”€ workflows/ β”‚ β”‚ └── config.yaml -β”‚ └── cis/ # Creative Innovation Studio +β”‚ └── cis/ # Creative Innovation Studio β”‚ └── ... -└── .claude/ # Platform-specific (example) +└── .claude/ # Platform-specific (example) └── agents/ ``` @@ -78,11 +51,10 @@ project-root/ 1. **Detection**: Check existing installation 2. **Selection**: Choose modules interactively or via CLI 3. **Configuration**: Collect module-specific settings -4. **Platform Setup**: Configure AI coding platforms -5. **Installation**: Process and copy files -6. **Generation**: Create config files with inheritance -7. **Post-Install**: Run module installers -8. **Manifest**: Track installed components +4. **Installation**: Compile Process and copy files +5. **Generation**: Create config files with inheritance +6. **Post-Install**: Run module installers +7. **Manifest**: Track installed components ### Key Exclusions diff --git a/docs/technical-decisions-template.md b/docs/technical-decisions-template.md deleted file mode 100644 index ceac48fb..00000000 --- a/docs/technical-decisions-template.md +++ /dev/null @@ -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 - - - -## Preferences - - - -## Constraints - - - -## To Investigate - - - -## 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. diff --git a/src/core/tools/shard-doc.xml b/src/core/tools/shard-doc.xml new file mode 100644 index 00000000..70a9c669 --- /dev/null +++ b/src/core/tools/shard-doc.xml @@ -0,0 +1,98 @@ + + Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool + + + MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER + DO NOT skip steps or change the sequence + HALT immediately when halt-conditions are met + Each action xml tag within step xml tag is a REQUIRED action to complete that step + Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution + + + + This task ONLY supports automated sharding via @kayvan/markdown-tree-parser + The tool automatically handles: section splitting, heading level adjustment, code block detection, index generation + All markdown formatting is preserved during sharding + + + + + Check if @kayvan/markdown-tree-parser is installed globally + Run: npm list -g @kayvan/markdown-tree-parser + Inform user that tool needs to be installed + Run: npm install -g @kayvan/markdown-tree-parser + HALT with error message about npm/node requirements + + + + Ask user for the source document path if not provided already + Verify file exists and is accessible + Verify file is markdown format (.md extension) + HALT with error message + + + + Determine default destination: same location as source file, folder named after source file without .md extension + Example: /path/to/architecture.md β†’ /path/to/architecture/ + Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path) + Use the suggested destination path + Use the custom destination path + Verify destination folder exists or can be created + Check write permissions for destination + HALT with error message + + + + Inform user that sharding is beginning + Execute command: md-tree explode [source-document] [destination-folder] + Capture command output and any errors + HALT and display error to user + + + + Check that destination folder contains sharded files + Verify index.md was created in destination folder + Count the number of files created + HALT with error message + + + + Display completion report to user including: + - Source document path and name + - Destination folder path + - Number of section files created + - Confirmation that index.md was created + - Any tool output or warnings + Inform user that sharding completed successfully + + + + + HALT if @kayvan/markdown-tree-parser cannot be installed + HALT if Node.js or npm is not available + HALT if source document does not exist or is inaccessible + HALT if source document is not markdown format (.md) + HALT if destination folder cannot be created + HALT if user does not have write permissions to destination + HALT if md-tree explode command fails + HALT if no output files were created + + + + @kayvan/markdown-tree-parser + md-tree explode [source-document] [destination-folder] + npm install -g @kayvan/markdown-tree-parser + + Node.js installed + npm package manager + Global npm installation permissions + + + Automatic section splitting by level 2 headings + Automatic heading level adjustment + Handles edge cases (code blocks, diagrams) + Generates navigable index.md + Preserves all markdown formatting + + + \ No newline at end of file diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md index a5f3a1bc..e63369f1 100644 --- a/src/modules/bmm/README.md +++ b/src/modules/bmm/README.md @@ -1,6 +1,6 @@ # 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 @@ -120,17 +120,13 @@ BMM integrates seamlessly with the BMad Core framework, leveraging: - [BMM Workflows Guide](./workflows/README.md) - **Start here!** - [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 1. **Always start with the workflows** - Let workflows guide your process 2. **Respect the scale** - Don't over-document small projects -3. **Embrace iteration** - Use retrospectives to continuously improve -4. **Trust the process** - The v6a methodology has been carefully designed +3. **Trust the process** - The 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). diff --git a/src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml b/src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml index 2ad5c71c..e56b0db8 100644 --- a/src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml +++ b/src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml @@ -4,7 +4,7 @@ description: "Exhaustive deep-dive documentation of specific project areas" author: "BMad" # 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 config_source: "{project-root}/bmad/bmb/config.yaml" @@ -13,13 +13,13 @@ user_name: "{config_source}:user_name" date: system-generated # 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 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 -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) workflow_mode: "deep_dive" diff --git a/src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml b/src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml index 64d6861a..c53ca2fa 100644 --- a/src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml +++ b/src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml @@ -4,7 +4,7 @@ description: "Complete project documentation workflow (initial scan or full resc author: "BMad" # 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 config_source: "{project-root}/bmad/bmb/config.yaml" @@ -13,15 +13,15 @@ user_name: "{config_source}:user_name" date: system-generated # Data files -project_types_csv: "{project-root}/src/modules/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" -architecture_registry_csv: "{project-root}/src/modules/bmm/workflows/1-analysis/document-project/data/architecture-registry.csv" +project_types_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/project-types.csv" +documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/documentation-requirements.csv" +architecture_registry_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/architecture-registry.csv" # 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 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) workflow_mode: "" # "initial_scan" or "full_rescan" diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml index 706c9344..f7083109 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml @@ -26,7 +26,7 @@ status_file: "{output_folder}/bmm-workflow-status.md" default_output_file: "{output_folder}/PRD.md" epics_output_file: "{output_folder}/epics.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_inputs: diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md index 7f1e1094..723be762 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md @@ -1,7 +1,7 @@ # Develop Story - Workflow Instructions ```xml -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} @@ -52,7 +52,7 @@ Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status - Check if context file exists at: {{story_dir}}/{{story_key}}.context.md + Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml Read COMPLETE context file Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests @@ -105,15 +105,15 @@ Expected ready-for-dev or in-progress. Continuing anyway... ASK user for approval before adding HALT and request guidance HALT: "Cannot proceed without necessary configuration files" - Do not stop after partial progress; continue iterating tasks until all ACs are satisfied or a HALT condition triggers - Do NOT propose to pause for review, standups, or validation until Step 6 gates are satisfied + Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers + Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied Create unit tests for business logic and core functionality introduced/changed by the task - Add integration tests for component interactions where applicable - Include end-to-end tests for critical user flows if applicable - Cover edge cases and error handling scenarios noted in the plan + Add integration tests for component interactions where desired by test plan or story notes + Include end-to-end tests for critical user flows where desired by test plan or story notes + Cover edge cases and error handling scenarios noted in the test plan or story notes diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml index 4598aefb..4b4b6611 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml @@ -7,13 +7,16 @@ 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" +document_output_language: "{config_source}:document_output_language" 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 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: "{story_dir}/{{story_key}}.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.xml" # Workflow components installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story" diff --git a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md index 6d58dae9..1968e8d1 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md @@ -55,7 +55,7 @@ - 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. + 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. Continue but record a WARNING in review notes: "No story context file found" Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}) diff --git a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml index 18bf344f..4a8ef0ba 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml @@ -49,6 +49,6 @@ variables: recommended_inputs: - story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')" - 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 diff --git a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md index 8dc4ef77..d38ea30b 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -9,7 +9,7 @@ If story_path is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT. Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel. -DOCUMENT OUTPUT: Technical context file (.context.md). Concise, structured, project-relative paths only. +DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only. diff --git a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml index 8943173b..a9e10d8a 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml @@ -25,6 +25,6 @@ variables: # Output configuration # 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 diff --git a/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md b/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md deleted file mode 100644 index 15028943..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-ready/AUDIT-REPORT.md +++ /dev/null @@ -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:** `The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml` - -**Should be:** `The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml` - -**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 (, , , , ) -βœ… 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 tags - -### Special Features: - -βœ… Anchor tag used correctly: `` (line 59) -βœ… Proper GOTO logic: "GOTO mark_ready" (line 15) -βœ… Conditional user interaction: `` (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 diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md index e96c91c0..825c622e 100644 --- a/src/modules/bmm/workflows/README.md +++ b/src/modules/bmm/workflows/README.md @@ -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. -## The Four Phases +## The Five Phases ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PHASE 0: DOCUMENTATION (Brownfield) β”‚ +β”‚ (Conditional - if undocumented) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ document-project ──→ Codebase documentation β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ PHASE 1: ANALYSIS β”‚ β”‚ (Optional) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ brainstorm-game ──┐ β”‚ +β”‚ brainstorm-game ──┐ β”‚ β”‚ brainstorm-project β”œβ”€β”€β†’ research ──→ product-brief ──┐ β”‚ -β”‚ game-brief β”€β”€β”€β”€β”€β”€β”€β”€β”˜ game-brief β”˜ β”‚ +β”‚ game-brief β”€β”€β”€β”€β”€β”€β”€β”€β”˜ game-brief β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ PHASE 2: PLANNING β”‚ β”‚ (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 1: tech-spec only └──→ Narrative design β”‚ -β”‚ β”œβ”€β”€β†’ Level 2: PRD + tech-spec β”‚ -β”‚ └──→ Level 3-4: PRD + Epics ────────────────────────┐ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”˜ - ↓ +β”‚ β”œβ”€β”€β†’ Level 1: tech-spec only └──→ Narrative (opt) β”‚ +β”‚ β”œβ”€β”€β†’ Level 2: PRD + Epics ──────────────────────────┐ β”‚ +β”‚ └──→ Level 3-4: PRD + Epics ────────────────────────┼┐ β”‚ +β”‚ UX: create-ux-design (conditional) β”‚β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”Όβ”€β”€β”˜ + ↓↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ PHASE 3: SOLUTIONING β”‚ -β”‚ (Software Levels 3-4 / Complex Games) β”‚ +β”‚ (Software Levels 2-4 / Complex Games) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ 3-solutioning ──→ architecture.md β”‚ -β”‚ ↓ β”‚ -β”‚ tech-spec (per epic, JIT during implementation) β”‚ +β”‚ create-architecture ──→ architecture.md β”‚ +β”‚ validate-architecture (optional) β”‚ +β”‚ solutioning-gate-check (recommended/required) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ PHASE 4: IMPLEMENTATION β”‚ -β”‚ (Iterative Cycle) β”‚ +β”‚ (Sprint-Based Cycle) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ β”Œβ”€β†’ create-story ──→ story-context ──→ dev-story ──┐ β”‚ -β”‚ β”‚ ↓ β”‚ -β”‚ β”‚ retrospective ←── [epic done] ←────── review-story β”‚ -β”‚ β”‚ ↓ β”‚ -β”‚ └──────────── correct-course ←──[if issues]β”€β”€β”˜ β”‚ +β”‚ sprint-planning ──→ sprint-status.yaml β”‚ +β”‚ ↓ β”‚ +β”‚ β”Œβ”€β†’ epic-tech-context (per epic) β”‚ +β”‚ β”‚ ↓ β”‚ +β”‚ β”‚ 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!** -The `workflow-status` workflow is the **universal entry point** for all BMM workflows: - -```bash -bmad analyst workflow-status -# or -bmad pm workflow-status -``` +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. **What it does:** @@ -83,8 +89,7 @@ bmad pm workflow-status **No status file?** It will: 1. Ask about project context (greenfield vs brownfield) -2. Offer analysis options (full analysis, skip to planning, or quick tech spec) -3. Guide you to the right first workflow +2. Generate your bmm-workflow-status.md file. **Status file exists?** It will: @@ -93,7 +98,27 @@ bmad pm workflow-status 3. Recommend exact next action 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 -| Workflow | Purpose | Output | When to Use | -| ---------------------- | ------------------------------------------- | ------------------------- | ---------------------- | -| **workflow-status** | Universal entry point and status checker | Status display + guidance | **Always start here!** | -| **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 | +| Workflow | Agent | Purpose | Output | When to Use | +| ---------------------- | ------------- | ------------------------------------------- | ------------------------- | --------------------- | +| **workflow-status** | Analyst | Universal entry point and status checker | Status display + guidance | **Start here!** | +| **workflow-init** | Analyst | Generate an initial workflow status file | Status display + guidance | **OR start here!** | +| **brainstorm-game** | Game Designer | Game concept ideation using 5 methodologies | Concept proposals | New game projects | +| **brainstorm-project** | Analyst | Software solution exploration | Architecture proposals | New software projects | +| **game-brief** | Game Designer | Structured game design foundation | Game brief document | Before GDD creation | +| **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 @@ -120,140 +146,112 @@ workflow-status (check) β†’ Brainstorming β†’ Research β†’ Brief β†’ Planning (P ## 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 + 1 story | β†’ 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 | | **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 -- **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 - -### Routing Logic - -**Universal Entry Point** (workflow-status): - -``` -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) -``` +| Workflow | Agent | Purpose | Output | Levels | +| -------------------- | ----------- | ------------------------------------ | -------------- | ----------- | +| **prd** | PM | Product Requirements Document | PRD.md + epics | 2-4 | +| **tech-spec** | PM | Technical specification | tech-spec.md | 0-1 | +| **gdd** | PM | Game Design Document | GDD.md | Games (all) | +| **narrative** | PM | Game narrative design | narrative.md | Games (opt) | +| **create-ux-design** | UX Designer | User experience and interface design | ux-design.md | Conditional | ### Key Outputs - **PRD.md**: Product Requirements Document (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-2 only) +- **tech-spec.md**: Technical specification (Levels 0-1) - **story-{slug}.md**: Single user story (Level 0) - **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1) - **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 -| 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 | +| Workflow | Agent | Purpose | Output | When | +| -------------------------- | --------- | -------------------------------- | ------------------------- | ----------- | +| **create-architecture** | Architect | Create system-wide architecture | architecture.md with ADRs | Levels 2-4 | +| **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 -``` -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. +- **Level 2**: Lightweight architecture document focusing on key technical decisions +- **Level 3-4**: Comprehensive architecture with detailed ADRs, system diagrams, integration patterns ## 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 - - Order is sequential (Epic 1 stories first, then Epic 2, etc.) +``` +backlog β†’ drafted β†’ ready-for-dev β†’ in-progress β†’ review β†’ done +``` -- **TODO**: Single story that needs drafting (or drafted, awaiting approval) - - SM drafts story here using `create-story` workflow - - Story status is "Draft" until user approves - - User runs `story-ready` workflow to approve +**Retrospective Status:** -- **IN PROGRESS**: Single story approved for development - - Moved here by `story-ready` workflow - - DEV implements using `dev-story` workflow - - Story status is "Ready" or "In Review" +``` +optional ↔ completed +``` -- **DONE**: Completed stories with dates and points - - Moved here by `story-done` workflow after DoD complete - - Immutable record of completed work +#### Status Definitions -**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 @@ -261,44 +259,45 @@ BACKLOG β†’ TODO β†’ IN PROGRESS β†’ DONE Phase Transition (Phase 2 or 3 β†’ Phase 4) ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ BACKLOG populated with all stories β”‚ -β”‚ TODO initialized with first story β”‚ +β”‚ SM: sprint-planning β”‚ +β”‚ Creates: sprint-status.yaml with all epics/ β”‚ +β”‚ stories set to 'backlog' β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SM: create-story (drafts story in TODO) β”‚ -β”‚ Reads: status file TODO section β”‚ -β”‚ Output: Story file with Status="Draft" β”‚ +β”‚ SM: epic-tech-context (for current epic) β”‚ +β”‚ Creates: epic-N-context.md β”‚ +β”‚ Updates: Epic status to 'contexted' β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ User reviews story β”‚ -β”‚ ↓ β”‚ -β”‚ SM: story-ready (approves story) β”‚ -β”‚ Actions: TODO β†’ IN PROGRESS β”‚ -β”‚ BACKLOG β†’ TODO (next story) β”‚ -β”‚ Story Status = "Ready" β”‚ +β”‚ SM: create-story (drafts next backlog story) β”‚ +β”‚ Creates: story-{key}.md β”‚ +β”‚ Updates: Story status to 'drafted' β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SM: story-context (optional but recommended) β”‚ -β”‚ Generates expertise injection XML β”‚ +β”‚ SM: story-context (creates implementation ctx) β”‚ +β”‚ Creates: story-{key}-context.md β”‚ +β”‚ Updates: Story status to 'ready-for-dev' β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ DEV: dev-story (implements story) β”‚ -β”‚ Reads: status file IN PROGRESS section β”‚ -β”‚ Implements with context injection β”‚ +β”‚ Reads: story + context files β”‚ +β”‚ Updates: Story status to 'in-progress' β”‚ +β”‚ then to 'review' when complete β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ↓ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ User reviews implementation (DoD check) β”‚ -β”‚ ↓ β”‚ -β”‚ DEV: story-done (marks story done) β”‚ -β”‚ Actions: IN PROGRESS β†’ DONE β”‚ -β”‚ TODO β†’ IN PROGRESS (if exists) β”‚ -β”‚ BACKLOG β†’ TODO (if exists) β”‚ -β”‚ Story Status = "Done" β”‚ +β”‚ SM: review-story (validates implementation) β”‚ +β”‚ Reviews: Code changes against DoD β”‚ +β”‚ Feedback: Iteration or approval β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + ↓ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 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 | Agent | Purpose | State Transition | No Search Required | -| ------------------ | ------ | ------------------------------------- | --------------------- | ------------------------ | -| **create-story** | SM | Draft story from TODO section | (Story stays in TODO) | Reads TODO section | -| **story-ready** | SM | Approve drafted story for development | TODO β†’ IN PROGRESS | Reads TODO section | -| **story-context** | SM | Generate expertise injection XML | (No state change) | Reads IN PROGRESS | -| **dev-story** | DEV | Implement story | (No state change) | Reads IN PROGRESS | -| **story-done** | DEV | Mark story done after DoD complete | IN PROGRESS β†’ DONE | Reads IN PROGRESS | -| **review-story** | SR/DEV | Quality validation (optional) | (No state change) | Manual story selection | -| **correct-course** | SM | Handle issues/changes | (Adaptive) | Manual story selection | -| **retrospective** | SM | Capture epic learnings | (No state change) | Manual or epic-triggered | +| Workflow | Agent | Purpose | Status Updates | +| --------------------- | ----- | -------------------------------------- | ------------------------------------------- | +| **sprint-planning** | SM | Initialize sprint status tracking | Creates sprint-status.yaml | +| **epic-tech-context** | SM | Create epic-specific technical context | Epic: backlog β†’ contexted | +| **create-story** | SM | Draft individual story files | Story: backlog β†’ drafted | +| **story-context** | SM | Generate implementation context/XML | Story: drafted β†’ ready-for-dev | +| **dev-story** | DEV | Implement story | Story: ready-for-dev β†’ in-progress β†’ review | +| **review-story** | SM/SR | Quality validation and feedback | (No automatic state change) | +| **retrospective** | SM | Capture epic learnings | Retrospective: optional β†’ completed | +| **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) - ↓ -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) +workflow-status/workflow-init β”œβ”€β†’ 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 + β”‚ β”œβ”€β†’ YES: Proceed to Phase 1 or 2 + β”‚ └─→ NO: REQUIRED - Run document-project 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: +**Critical for Brownfield**: -- Map existing architecture -- Document current patterns -- Identify integration points -- Assess technical debt -- Create the baseline needed for planning +- Must understand existing patterns before planning +- Integration points need documentation +- Technical debt must be visible in planning +- Constraints from existing system affect scale decisions ## Agent Participation by Phase -| Phase | Primary Agents | Supporting Agents | -| ------------------ | ------------------- | --------------------------- | -| **Analysis** | Analyst, Researcher | PM, PO | -| **Planning** | PM | Analyst, UX Designer | -| **Solutioning** | Architect | PM, Tech Lead | -| **Implementation** | SM, DEV | SR, PM (for correct-course) | +| Phase | Primary Agents | Supporting Agents | Key Workflows | +| --------------------- | ---------------------- | -------------------- | ------------------------------------------- | +| **0: Documentation** | Analyst | - | document-project | +| **1: Analysis** | Analyst, Game Designer | PM, Researcher | brainstorm-_, research, _-brief | +| **2: Planning** | PM | UX Designer, Analyst | prd, tech-spec, gdd, narrative | +| **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 ### Tracking Documents -- **bmm-workflow-status.md**: Versioned workflow state tracking with 4-section story backlog - - **BACKLOG**: Ordered list of stories to be drafted - - **TODO**: Single story ready for drafting (or drafted, awaiting approval) - - **IN PROGRESS**: Single story approved for development - - **DONE**: Completed stories with dates and points - - Populated automatically at phase transitions - - Single source of truth for story progression - - Agents read (never search) to know what to work on next +- **bmm-workflow-status.md**: Phase and workflow tracking (updated by workflow-status) + - Current phase and progress + - Workflow history + - Next recommended actions + - Project metadata and configuration -- **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 1**: Briefs and research documents +- **Phase 0**: + - Codebase documentation (project overview, architecture, source tree) + +- **Phase 1**: + - Product briefs, game briefs, research documents + - **Phase 2**: - Level 0: tech-spec.md + story-{slug}.md - - Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files - - Level 2: PRD.md + epics.md (then tech-spec.md in Phase 3) - - Level 3-4: PRD.md + epics.md (then architecture.md in Phase 3) -- **Phase 3**: architecture.md, epic-specific tech specs -- **Phase 4**: Story files, context XMLs, implemented code + - Level 1: tech-spec.md + epic breakdown + story-{slug}-N.md files + - Level 2-4: PRD.md + epics.md (+ optional ux-design.md, narrative.md) + +- **Phase 3**: + - 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 ### 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 +- Don't create PRDs for Level 0-1 changes (use tech-spec only) +- Don't skip architecture for Level 2-4 projects +- 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 -- Generate stories as needed, not in batches -- Build context injections per story +- Run sprint-planning at the start of Phase 4 +- Context epics before drafting their stories (epic-tech-context) +- Update sprint-status.yaml as work progresses +- Re-run sprint-planning to auto-detect new files/contexts ### 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 -- Use fresh context windows for reviews ### 4. Document Brownfield First - Never plan without understanding existing code +- Run document-project if codebase is undocumented - Technical debt must be visible in planning - Integration points need documentation ### 5. Learn Continuously - 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 ## 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 workflow init determine level | -| Planning brownfield without docs | Run brownfield-analysis first | -| Not running retrospectives | Schedule after every epic | +| Pitfall | Solution | +| ------------------------------------- | ----------------------------------------------------- | +| Skipping sprint-planning | Always run at Phase 4 start - it creates status file | +| Creating stories without epic context | Run epic-tech-context before create-story | +| Skipping story-context generation | Always run after create-story for better dev guidance | +| Not updating sprint-status.yaml | Update statuses as work progresses | +| Thinking Level 2 skips Phase 3 | Level 2 DOES require architecture (just lighter) | +| 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 @@ -464,47 +481,67 @@ workflow-init (Phase 2) # Universal Entry Point (Start Here!) bmad analyst workflow-status # Check status and get recommendations +# Phase 0: Documentation (Brownfield if needed) +bmad analyst document-project + # Phase 1: Analysis (Optional) -bmad analyst brainstorm-project -bmad analyst research -bmad analyst product-brief +bmad analyst brainstorm-project # Software ideation +bmad game-designer brainstorm-game # Game ideation +bmad analyst research # Market/technical research +bmad analyst product-brief # Software brief +bmad game-designer game-brief # Game brief -# Phase 2: Planning -bmad pm prd # Level 2-4 software projects -bmad architect tech-spec # Level 0-1 software projects -bmad pm gdd # Game projects +# Phase 2: Planning (Required) +bmad pm prd # Level 2-4 software projects +bmad pm tech-spec # Level 0-1 software 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) -bmad architect architecture -bmad architect tech-spec # Per epic, JIT +# Phase 3: Solutioning (Levels 2-4) +bmad architect create-architecture # System architecture +bmad architect validate-architecture # Validation (optional) +bmad architect solutioning-gate-check # Gate check -# Phase 4: Implementation -bmad sm create-story # Draft story from TODO section -bmad sm story-ready # Approve story for development (after user review) -bmad sm story-context # Generate context XML (optional but recommended) -bmad dev dev-story # Implement story from IN PROGRESS section -bmad dev story-done # Mark story done (after user confirms DoD) -bmad dev review-story # Quality validation (optional) -bmad sm correct-course # If issues arise -bmad sm retrospective # After epic complete +# Phase 4: Implementation (Sprint-Based) +bmad sm sprint-planning # FIRST: Initialize sprint tracking +bmad sm epic-tech-context # Create epic context (per epic) +bmad sm create-story # Draft story file +bmad sm story-context # Create story context +bmad dev dev-story # Implement story +bmad sm review-story # Quality validation +# (Update sprint-status.yaml to 'done' manually or via workflow) +bmad sm retrospective # After epic complete +bmad sm correct-course # If issues arise ``` ## Future Enhancements ### Coming Soon -- **brownfield-analysis**: Automated codebase documentation generator -- **Workflow orchestration**: Automatic phase transitions -- **Progress dashboards**: Real-time workflow status +- **Automated status updates**: Workflows automatically update sprint-status.yaml +- **Workflow orchestration**: Automatic phase transitions and validation +- **Progress dashboards**: Real-time workflow status visualization - **Team synchronization**: Multi-developer story coordination ### Under Consideration -- AI-assisted retrospectives -- Automated story sizing -- Predictive epic planning +- AI-assisted retrospectives with pattern detection +- Automated story sizing based on historical data +- Predictive epic planning with risk assessment - 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. + +## 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 diff --git a/src/modules/bmm/workflows/workflow-status/init/workflow.yaml b/src/modules/bmm/workflows/workflow-status/init/workflow.yaml index 60f48368..d2d08efb 100644 --- a/src/modules/bmm/workflows/workflow-status/init/workflow.yaml +++ b/src/modules/bmm/workflows/workflow-status/init/workflow.yaml @@ -19,7 +19,7 @@ instructions: "{installed_path}/instructions.md" template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.md" # 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 default_output_file: "{output_folder}/bmm-workflow-status.md"