External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add documentation guides, simplify folder structure, and major workflow refactoring

Browse Source 
Created two comprehensive guides for v6 features:

**docs/agent-customization-guide.md**
- Complete guide for customizing agent names, personas, memories, and behaviors
- Update-safe customization via bmad/_cfg/agents/ configuration files
- Real-world examples (TDD setup, multilingual agents, custom workflows)
- Troubleshooting and best practices

**docs/web-bundles-gemini-gpt-guide.md**
- Comprehensive guide for using BMad agents in Gemini Gems and Custom GPTs
- Critical setup rules with exact configuration text required
- Cost-saving strategy: web planning → local implementation (60-80% savings)
- Platform comparison (Gemini Gems strongly recommended over Custom GPTs)
- Complete workflow examples showing full planning-to-implementation cycle
- Team bundle guidance (Gemini 2.5 Pro+ only)

**README.md updates**
- Added prominent links in v6 Core Enhancements section
- Created new "Customization & Sharing" documentation category
- Web Bundles feature highlighted with direct guide link

**Unified output folder structure across all modules:**

**Before (confusing):**
- output_folder: Main docs
- game_design_docs: Separate design folder
- tech_docs: Separate technical folder
- dev_ephemeral_location: Separate ephemeral folder outside docs

**After (simplified):**
- output_folder: Single location for ALL AI-generated artifacts (default: "docs")
  - Clearer prompt: "Where should AI Generated Artifacts be saved?"
- sprint_artifacts: Phase 4 ephemeral content now WITHIN output_folder
  - BMM: {output_folder}/stories (stories, context, reports)
  - BMGD: {output_folder}/sprint-artifacts
  - No longer in separate {bmad_folder}-ephemeral location

**Benefits:**
- One clear location for all planning artifacts (PRD, Architecture, UX, etc.)
- Phase 4 ephemeral items logically grouped within output folder
- Eliminated confusing separate folder proliferation
- sprint_artifacts now configurable per module

**Files changed:**
- src/core/_module-installer/install-config.yaml
- src/modules/bmm/_module-installer/install-config.yaml
- src/modules/bmgd/_module-installer/install-config.yaml

**Also cleaned up BMGD config:**
- Renamed: specified_framework → primary_platform (clearer naming)
- Removed: unused data_path variable

Replaced old "project_level" (0-4) system with new "selected_track" terminology:
- **quick-flow**: Bug fixes and small features (replaces Level 0-1)
- **bmad-method**: Full planning track (replaces Level 2-3)
- **enterprise-bmad-method**: Extended planning (replaces Level 4)

**Core workflow updates:**
- solutioning-gate-check: Complete rewrite of validation logic for track-based artifacts
- architecture: Updated context detection, error handling, and messaging for tracks
- workflow-init: Updated artifact detection patterns for track-based paths
- All workflow status paths updated (method-greenfield, method-brownfield, enterprise-*)

Unified variable naming conventions across all workflows:
- {output_folder} → {output-folder} (hyphenated format)
- {dev_ephemeral_location} → {sprint_artifacts} (clearer purpose)
- Hardcoded status file paths → {workflow_status_file} variable

Fixed corrupted variable patterns throughout workflow files:
- {output*folder} → {output-folder}
- {ephemeral*location} → {sprint_artifacts}
- \_prd* → *prd* (escaped underscore artifacts)
- **\*\***\_\_\_**\*\*** → proper field placeholders

Affected patterns included malformed glob patterns, template variables, and markdown formatting artifacts from previous edits.

**Architecture workflow (create-architecture):**
- Fixed: "Decision Architecture" → "Create Architecture" (consistent naming)
- Improved PRD not found handling with exit/continue options
- Better user guidance when running standalone vs. within workflow path
- Removed hardcoded Level checks, now track-aware
- Enhanced validation checklist formatting (□ → - [])
- Typo fixes: "mulitple" → "multiple"

**Solutioning gate check:**
- Complete validation logic rewrite for track-based system
- Removed Level-specific artifact expectations
- Simplified document discovery (track determines what exists)
- Better analysis prompts and user feedback

**Workflow-init:**
- Updated artifact detection patterns for new folder structure
- Fixed corrupt glob patterns throughout
- Better sprint_artifacts location detection
- Improved workflow path assignment logic

**Various workflows:**
- Consistent variable naming across 40+ workflow files
- Improved error messages and user guidance
- Better markdown formatting (checkboxes, lists)
- Removed redundant validation criteria files (now inline)

Removed duplicate BMGD 4-production workflows (12 workflows):
- code-review, correct-course, create-story, dev-story
- epic-tech-context, retrospective, sprint-planning
- story-context, story-done, story-ready

**Why:** BMGD now uses shared BMM Phase 4 implementation workflows
**Benefit:** Single source of truth, no duplication to maintain

Also removed:
- validation-criteria.yaml (validation now inline in instructions)
- architecture-patterns.yaml references (patterns now managed differently)
- AUDIT-REPORT.md files (stale audit artifacts)

**BMB workflows:**
- Updated checklists for workflow and module creation
- Improved agent architecture documentation
- Minor instruction clarifications

**Core brainstorming workflow:**
- Updated README with usage examples
- Enhanced instructions and template clarity
- Better integration with other modules

**BMM installer:**
- Updated for track-based system
- sprint_artifacts configuration

**Tech Writer agent:**
- Minor configuration update for documentation workflows

Removed 200+ files that should not be in repository:
- Installed agent markdown files (analyst, architect, dev, pm, sm, tea, etc.)
- Complete workflow instruction copies
- Documentation duplicates (quick-start, agents-guide, workflows-*)
- Test architecture knowledge base (22 files, 14,000+ lines)
- Configuration files (config.yaml, team definitions)

These are generated during installation and should not be version controlled.

Removed 21 pre-generated XML bundles:
- BMM agents (analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer)
- BMGD agents (game-architect, game-designer, game-dev, game-scrum-master)
- CIS agents (brainstorming-coach, creative-problem-solver, etc.)
- Team bundles (team-fullstack, team-gamedev, creative-squad)

**Why:** Users should generate fresh bundles via `npm run bundle` to get latest changes and customizations.

- **2 new documentation files** (comprehensive guides)
- **98 source files modified** (299 insertions, 6,567 deletions)
- **3 installer config files simplified** (major folder structure improvement)
- **200+ .bmad/ artifacts removed** (should not be in repo)
- **21 web-bundle files removed** (users regenerate as needed)
- **12 duplicate workflows removed** (BMGD consolidation)
- **40+ workflows updated** (track system, variable standardization, corruption fixes)
This commit is contained in:
Brian Madison
2025-11-11 12:22:31 -06:00
parent 280652566c
commit 2d99833b9e
318 changed files with 904 additions and 115532 deletions
Download Patch File Download Diff File Expand all files Collapse all files

367
src/modules/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md
View File

@@ -1,367 +0,0 @@
# Workflow Audit Report
**Workflow:** dev-story
**Audit Date:** 2025-10-25
**Auditor:** Audit Workflow (BMAD v6)
**Workflow Type:** Action Workflow
**Module:** BMM (BMad Method)
---
## Executive Summary
**Overall Status:** GOOD - Minor issues to address
- Critical Issues: 0
- Important Issues: 3
- Cleanup Recommendations: 2
The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
---
## 1. Standard Config Block Validation
**Status:** PASS ✓
The workflow.yaml contains all required standard config variables:
- ✓ `config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"` - Correctly defined
- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
- ✓ `date: system-generated` - Correctly set
All standard config variables are present and properly formatted using {project-root} variable syntax.
---
## 2. YAML/Instruction/Template Alignment
**Variables Analyzed:** 9 (excluding standard config)
**Used in Instructions:** 6
**Unused (Bloat):** 3
### YAML Variables Defined
1. `story_dir` - USED in instructions (file paths)
2. `context_path` - UNUSED (appears to duplicate story_dir)
3. `story_file` - USED in instructions
4. `context_file` - USED in instructions
5. `installed_path` - USED in instructions (workflow.xml reference)
6. `instructions` - USED in instructions (self-reference in critical tag)
7. `validation` - USED in instructions (checklist reference)
8. `web_bundle` - CONFIGURATION (correctly set to false)
9. `date` - USED in instructions (config variable)
### Variables Used in Instructions But NOT Defined in YAML
**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
2. `{document_output_language}` - Used 1 time (line 7)
3. `{run_until_complete}` - Used 1 time (line 108)
4. `{run_tests_command}` - Used 1 time (line 120)
These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
### Unused Variables (Bloat)
1. **context_path** - Defined as `"{config_source}:dev_ephemeral_location"` but never used. This duplicates `story_dir` functionality.
---
## 3. Config Variable Usage
**Communication Language:** PASS ✓
**User Name:** PASS ✓
**Output Folder:** PASS ✓
**Date:** PASS ✓
### Detailed Analysis
**Communication Language:**
- ✓ Used in line 6: "Communicate all responses in {communication_language}"
- ✓ Properly used as agent instruction variable (not in template)
**User Name:**
- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
- ✓ Appropriately used for personalization
**Output Folder:**
- ✓ Used multiple times for sprint-status.yaml file paths
- ✓ All file operations target {output_folder} correctly
- ✓ No hardcoded paths detected
**Date:**
- ✓ Available for agent use (system-generated)
- ✓ Used appropriately in context of workflow execution
### Additional Config Variables
**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
1. `{user_skill_level}` - Used to tailor communication style
2. `{document_output_language}` - Used for document generation
3. `{run_until_complete}` - Used for execution control
4. `{run_tests_command}` - Used for test execution
These should either be:
- Added to workflow.yaml with proper config_source references, OR
- Documented as optional config variables with defaults
---
## 4. Web Bundle Validation
**Web Bundle Present:** No (Intentional)
**Status:** EXPECTED ✓
The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
- Run locally in the development environment
- Don't need to be bundled for web deployment
- Are IDE-integrated workflows
**No issues found** - This is the correct configuration for dev-story.
---
## 5. Bloat Detection
**Bloat Percentage:** 11% (1 unused field / 9 total fields)
**Cleanup Potential:** Low
### Unused YAML Fields
1. **context_path** (line 11 in workflow.yaml)
- Defined as: `"{config_source}:dev_ephemeral_location"`
- Never referenced in instructions.md
- Duplicates functionality of `story_dir` variable
- **Recommendation:** Remove this variable as `story_dir` serves the same purpose
### Hardcoded Values
No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
- File paths ({output_folder}, {story_dir})
- User personalization ({user_name})
- Communication style ({communication_language}, {user_skill_level})
### Calculation
- Total yaml fields: 9 (excluding standard config and metadata)
- Used fields: 8
- Unused fields: 1 (context_path)
- Bloat percentage: 11%
**Status:** Acceptable (under 15% threshold)
---
## 6. Template Variable Mapping
**Not Applicable** - This is an action workflow, not a document workflow.
No template.md file exists, which is correct for action-type workflows.
---
## 7. Instructions Quality Analysis
### Structure
- ✓ Steps numbered sequentially (1, 1.5, 2-7)
- ✓ Each step has clear goal attributes
- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
- ✓ Logical flow control with anchors and conditional checks
- ✓ Repeat patterns used appropriately (step 2-5 loop)
### Critical Tags
- ✓ Critical blocks present and well-defined
- ✓ Clear references to workflow execution engine
- ✓ Workflow.yaml load requirement specified
- ✓ Communication preferences documented
### Variable Usage Consistency
**ISSUE:** Inconsistent variable syntax found:
1. Lines 4, 5 use `{project_root}` (underscore)
2. Line 166 uses `{project-root}` (hyphen)
**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
### Step Quality
**Excellent:**
- Steps are focused and single-purpose
- Clear HALT conditions defined
- Comprehensive validation checks
- Good error handling patterns
- Iterative execution model well-structured
**Areas for improvement:**
- Step 1 is complex and could potentially be split
- Some <action if="..."> conditionals could be clearer with <check> blocks
---
## Recommendations
### Critical (Fix Immediately)
None - No critical issues detected.
### Important (Address Soon)
1. **Document or Define Missing Variables**
- Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
- OR document these as optional config variables with defaults
- These variables are used in instructions but not defined in YAML
- **Impact:** Reduces clarity and may cause confusion about variable sources
2. **Standardize project-root Variable Syntax**
- Change line 4 `{project_root}` to `{project-root}` (hyphen)
- Ensure consistency with BMAD v6 standard naming convention
- **Impact:** Maintains consistency with framework standards
3. **Remove or Use context_path Variable**
- Variable `context_path` is defined but never used
- Since `story_dir` serves the same purpose, remove `context_path`
- OR if there's a semantic difference, document why both exist
- **Impact:** Reduces bloat and potential confusion
### Cleanup (Nice to Have)
1. **Consider Splitting Step 1**
- Step 1 handles both story discovery AND file loading
- Could be split into "1. Find Story" and "2. Load Story Files"
- Would improve clarity and maintainability
- **Impact:** Minor improvement to workflow structure
2. **Add Variable Documentation Comment**
- Add a comment block in workflow.yaml listing all variables used by this workflow
- Include both explicit YAML variables and config-pulled variables
- Example format:
```yaml
# Workflow-specific variables
# - story_file: Path to story markdown
# - story_dir: Directory containing stories
#
# Config-pulled variables (from bmm/config.yaml)
# - user_skill_level: User's technical skill level
# - document_output_language: Language for generated docs
```
- **Impact:** Improves developer understanding and maintenance
---
## Validation Checklist
### Structure ✓
- [x] workflow.yaml loads without YAML syntax errors
- [x] instructions.md exists and is properly formatted
- [x] No template.md (correct for action workflow)
- [x] All critical headers present in instructions
- [x] Workflow type correctly identified (action)
- [x] All referenced files exist
- [x] No placeholder text remains
### Standard Config Block ✓
- [x] config_source points to correct module config
- [x] output_folder pulls from config_source
- [x] user_name pulls from config_source
- [x] communication_language pulls from config_source
- [x] date is system-generated
- [x] Config source uses {project-root} variable
- [x] Standard config comment present
### Config Variable Usage ✓
- [x] Instructions communicate in {communication_language}
- [x] Instructions address {user_name}
- [x] All file outputs use {output_folder}
- [x] No hardcoded paths
- [x] Date available for agent awareness
### YAML/Instruction/Template Alignment ⚠️
- [⚠️] Some variables used in instructions not defined in YAML
- [x] Template variables N/A (action workflow)
- [x] Variable names are descriptive
- [⚠️] One unused yaml field (context_path)
### Web Bundle Validation ✓
- [x] web_bundle: false is correct for this workflow
- [x] No web_bundle section needed
- [x] Workflow is local/IDE-integrated only
### Instructions Quality ✓
- [x] Steps numbered sequentially
- [x] Clear goal attributes
- [x] Proper XML tag usage
- [x] Logical flow control
- [⚠️] Minor inconsistency: {project_root} vs {project-root}
### Bloat Detection ✓
- [x] Bloat percentage: 11% (acceptable, under 15%)
- [x] No significant hardcoded values
- [x] No redundant configuration
- [x] One cleanup recommendation (context_path)
---
## Next Steps
1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
3. **Remove context_path** - Clean up unused variable
4. **Re-run audit** - Verify improvements after fixes
---
## Additional Notes
### Strengths
1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
2. **Config Integration:** Excellent use of config variables for user personalization and output management
3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
### Workflow Purpose
This workflow executes user stories by:
- Finding ready-for-dev stories from sprint status
- Implementing tasks and subtasks incrementally
- Writing comprehensive tests
- Validating against acceptance criteria
- Updating story status through sprint lifecycle
- Supporting different user skill levels with adaptive communication
The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
---
**Audit Complete** - Generated by audit-workflow v1.0
**Pass Rate:** 89% (62 passed / 70 total checks)
**Recommendation:** Good - Minor fixes needed
The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.

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

@@ -9,9 +9,7 @@ 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_ephemeral_location"
run_until_complete: "{config_source}:run_until_complete"
run_tests_command: "{config_source}:run_tests_command"
story_dir: "{config_source}:sprint_artifacts"
date: system-generated
story_file: "" # Explicit story path; auto-discovered if empty