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

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

View File

@@ -14,21 +14,21 @@
**Check for BMM planning artifacts:**
- PRD files: {output*folder}/\_prd*.md or {output*folder}/\_prd*/index.md
- Tech-spec files: {output*folder}/\_tech-spec*.md or {output*folder}/\_spec*.md
- Epic files: {output*folder}/\_epic*.md or {output*folder}/\_epic*/index.md
- Architecture: {output*folder}/\_architecture*.md or {output*folder}/\_arch*.md
- UX Design: {output*folder}/\_ux*.md or {output*folder}/\_design*.md
- Product Brief: {output*folder}/\_brief*.md
- Research docs: {output*folder}/\_research*.md
- Brainstorm docs: {output*folder}/\_brainstorm*.md
- PRD files: {output-folder}/\_prd*.md or {output-folder}/\_prd*/index.md
- Tech-spec files: {output-folder}/\_tech-spec*.md or {output-folder}/\_spec*.md
- Epic files: {output-folder}/\_epic*.md or {output-folder}/\_epic*/index.md
- Architecture: {output-folder}/\_architecture*.md or {output-folder}/\_arch*.md
- UX Design: {output-folder}/\_ux*.md or {output-folder}/\_design*.md
- Product Brief: {output-folder}/\_brief\*.md
- Research docs: {output-folder}/\_research\*.md
- Brainstorm docs: {output-folder}/\_brainstorm\*.md
**Check for implementation artifacts:**
- The following could be in or nested under {output_folder} OR {ephemeral_location} - CHECK BOTH LOCATIONS
- Story files: {output*folder}/stories/*.md or {ephemeral*location}/stories/*.md
- Sprint status: {output_folder}/sprint-status.yaml or {ephemeral_location}/sprint-status.yaml
- Existing workflow status: {output_folder}/bmm-workflow-status.yaml or {ephemeral_location}/bmm-workflow-status.yaml
- The following could be in or nested under {output_folder} OR {sprint_artifacts} - CHECK BOTH LOCATIONS
- Story files: {output-folder}/stories/*.md or {ephemeral*location}/stories/\*.md
- Sprint status: {output_folder}/sprint-status.yaml or {sprint_artifacts}/sprint-status.yaml
- Existing workflow status: {output_folder}/bmm-workflow-status.yaml or {sprint_artifacts}/bmm-workflow-status.yaml
**Check for codebase:**
@@ -660,13 +660,13 @@ For each phase in path file:
- Brainstorm: {output_folder}/brainstorm\*.md
- Research: {output_folder}/research\*.md
- Product Brief: {output*folder}/\_brief*.md
- PRD: {output*folder}/\_prd*.md or {output*folder}/\_prd*/index.md
- Tech-spec: {output*folder}/\_tech-spec*.md or {output*folder}/\_spec*.md
- Epics: {output*folder}/\_epic*.md or {output*folder}/\_epic*/index.md
- UX Design: {output*folder}/\_ux*.md or {output*folder}/\_design*.md
- Architecture: {output*folder}/\_architecture*.md or {output*folder}/\_arch*.md
- Sprint Planning: {output*folder}/\_sprint*.yaml
- Product Brief: {output-folder}/\_brief\*.md
- PRD: {output-folder}/\_prd*.md or {output-folder}/\_prd*/index.md
- Tech-spec: {output-folder}/\_tech-spec*.md or {output-folder}/\_spec*.md
- Epics: {output-folder}/\_epic*.md or {output-folder}/\_epic*/index.md
- UX Design: {output-folder}/\_ux*.md or {output-folder}/\_design*.md
- Architecture: {output-folder}/\_architecture*.md or {output-folder}/\_arch*.md
- Sprint Planning: {output-folder}/\_sprint\*.yaml
**CRITICAL:** If file exists, replace workflow status with ONLY the file path, preserving agent comment.
Example: `prd: docs/prd.md # agent: pm` (NOT "completed - docs/prd.md")

View File

@@ -6,7 +6,7 @@ author: "BMad"
# Critical variables from config
config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
ephemeral_location: "{config_source}:dev_ephemeral_location"
sprint_artifacts: "{config_source}:sprint_artifacts"
user_name: "{config_source}:user_name"
project_name: "{config_source}:project_name"
communication_language: "{config_source}:communication_language"

View File

@@ -2,7 +2,7 @@
# Extended enterprise planning for complex brownfield with security/devops/test (30+ stories typically)
method_name: "BMad Enterprise Method"
track: "enterprise"
track: "enterprise-bmad-method"
field_type: "brownfield"
description: "Enterprise-grade planning for complex brownfield additions with extended requirements"

View File

@@ -1,8 +1,8 @@
# BMad Enterprise Method - Greenfield
# Extended enterprise planning with security/devops/test for greenfield (30+ stories typically)
method_name: "BMad Enterprise Method"
track: "enterprise"
method_name: "Enterprise BMad Method"
track: "enterprise-bmad-method"
field_type: "greenfield"
description: "Complete enterprise-grade planning with security, devops, and test strategy"

View File

@@ -2,7 +2,7 @@
# Full product + architecture planning for complex brownfield additions (10-50+ stories typically)
method_name: "BMad Method"
track: "method"
track: "bmad-method"
field_type: "brownfield"
description: "Complete product and system design for complex brownfield work"

View File

@@ -2,7 +2,7 @@
# Full product + architecture planning for greenfield projects (10-50+ stories typically)
method_name: "BMad Method"
track: "method"
track: "bmad-method"
field_type: "greenfield"
description: "Complete product and system design methodology for greenfield projects"

View File

@@ -1,49 +0,0 @@
# Workflow Status Template
# This tracks progress through phases 1-3 of the BMM methodology
# Phase 4 (Implementation) is tracked separately in sprint-status.yaml
# generated: 2025-10-29
# project: Enterprise Customer Portal
# project_type: software
# project_level: 3
# field_type: greenfield
# workflow_path: greenfield-level-3.yaml
# STATUS DEFINITIONS:
# ==================
# Initial Status (before completion):
# - required: Must be completed to progress
# - optional: Can be completed but not required
# - recommended: Strongly suggested but not required
# - conditional: Required only if certain conditions met (e.g., if_has_ui)
#
# Completion Status:
# - {file-path}: File created/found (e.g., "docs/product-brief.md")
# - skipped: Optional/conditional workflow that was skipped
generated: 2025-10-29
project: Enterprise Customer Portal
project_type: software
project_level: 3
field_type: greenfield
workflow_path: greenfield-level-3.yaml
workflow_status:
# Phase 1: Analysis
brainstorm-project: docs/brainstorm-session-2025-10-15.md
research: docs/research-api-patterns.md
product-brief: docs/product-brief.md
# Phase 2: Planning
prd: docs/prd.md
validate-prd: skipped
create-design: docs/ux-design.md
# Phase 3: Solutioning
create-architecture: required
validate-architecture: optional
solutioning-gate-check: recommended
# Phase 4: Implementation
sprint-planning: required
# Note: Subsequent implementation workflows tracked in sprint-status.yaml