Brian Madison
|
2d99833b9e
|
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)
|
2025-11-11 17:30:43 -06:00 |
|
Brian Madison
|
f77babcd5e
|
feat: major overhaul of BMM planning workflows with intent-driven discovery
This comprehensive update transforms the Product Brief and PRD workflows from rigid template-filling exercises into adaptive, context-aware discovery processes. Changes span workflow instructions, templates, agent configurations, and supporting infrastructure.
## Product Brief Workflow (96% audit compliance)
### Intent-Driven Facilitation
- Transform from linear Q&A to natural conversational discovery
- Adaptive questioning based on project context (hobby/startup/enterprise)
- Real-time document building instead of end-of-session generation
- Skill-level aware facilitation (expert/intermediate/beginner)
- Context detection from user responses to guide exploration depth
### Living Document Approach
- Continuous template updates throughout conversation
- Progressive refinement vs batch generation
- Template-output tags aligned with discovery flow
- Better variable mapping between instructions and template
### Enhanced Discovery Areas
- Problem exploration with context-appropriate probing
- Solution vision shaping based on user's mental model
- User understanding through storytelling vs demographics
- Success metrics tailored to project type
- Ruthless MVP scope management with feature prioritization
### Template Improvements
- Added context-aware conditional sections
- Better organization of optional vs required content
- Clearer structure for different project types
- Improved reference material handling
## PRD Workflow (improved from 65% to 85%+ compliance)
### Critical Fixes
- Add missing `date: system-generated` config variable
- Fix status file extension mismatch (.yaml not .md)
- Remove 38% bloat (unused technical_decisions variables)
- Add explicit template-output tags for runtime variables
### Scale-Adaptive Intelligence
- Project type detection (API/Web App/Mobile/SaaS/etc)
- Domain complexity mapping (14 domain types)
- Automatic requirement tailoring based on detected context
- CSV-driven project type and domain knowledge base
### Separated Epic Planning
- Move epic/story breakdown to dedicated child workflow
- Create create-epics-and-stories workflow for Phase 2
- Cleaner separation: PRD defines WHAT, epics define HOW
- Updated PM agent menu with new workflow triggers
### Enhanced Requirements Coverage
- Project-type specific requirement sections (endpoints, auth, platform)
- Domain-specific considerations (healthcare compliance, fintech security)
- UX principles with interaction patterns
- Non-functional requirements with integration needs
- Technical preferences capture
### Template Restructuring
- Separate PRD template from epic planning
- Context-aware conditional sections
- Better scale level indicators (L0-L4)
- Improved reference document handling
- Clearer success criteria sections
## Architecture Workflow Updates
### Template Enhancements
- Add domain complexity context support
- Better integration with PRD outputs
- Improved technical decision capture
- Enhanced system architecture sections
### Instruction Improvements
- Reference new domain-research workflow
- Better handling of PRD inputs
- Clearer architectural decision framework
## Agent Configuration Updates
### BMad Master Agent
- Fix workflow invocation instructions
- Better fuzzy matching guidance
- Clearer menu handler documentation
- Remove workflow invention warnings
### PM Agent
- Add create-prd trigger (renamed from 'prd')
- Add create-epics-and-stories workflow trigger
- Add validate-prd workflow trigger with checklist
- Better workflow status integration
### Game Designer Agent
- Rename triggers for consistency (create-game-brief, create-gdd)
- Align with PM agent naming conventions
## New Supporting Infrastructure
### Domain Research Workflow
- New discovery workflow for domain-specific research
- Complements product brief for complex domains
- Web research integration for domain insights
### Create Epics and Stories Workflow
- Dedicated epic/story breakdown process
- Separates planning (PRD) from decomposition
- Better Epic → Story → Task hierarchy
- Acceptance criteria generation
### Data Files
- project-types.csv: 12 project type definitions with requirements
- domain-complexity.csv: 14 domain types with complexity indicators
## Quality Improvements
### Validation & Compliance
- Product Brief: 96% BMAD v6 compliance (EXCELLENT rating)
- PRD: Improved from 65% to ~85% after critical fixes
- Zero bloat in Product Brief (0%)
- Reduced PRD bloat from 38% to ~15%
### Template Variable Mapping
- All template variables explicitly populated via template-output tags
- Runtime variables properly tracked
- Config variables consistently used
- Better separation of concerns
### Web Bundle Configuration
- Complete web_bundle sections for all workflows
- Proper child workflow references
- Data file inclusions (CSV files)
- Correct bmad/-relative paths
## Breaking Changes
### File Removals
- Delete src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md
(replaced by create-epics-and-stories child workflow)
### Workflow Trigger Changes
- PM agent: 'prd' → 'create-prd'
- PM agent: 'gdd' → 'create-gdd'
- New: 'create-epics-and-stories'
- New: 'validate-prd'
## Impact
This update significantly improves the BMM module's ability to:
- Adapt to different project types and scales
- Guide users through discovery naturally vs mechanically
- Generate higher quality planning documents
- Support complex domains with specialized knowledge
- Scale from Level 0 quick changes to Level 4 enterprise projects
The workflows now feel like collaborative discovery sessions with an expert consultant rather than form-filling exercises.
|
2025-11-01 19:37:20 -05:00 |