3d4ea5ffd2
feat: add universal document sharding support with dual-strategy loading
...
Implement comprehensive document sharding system across all BMM workflows enabling 90%+ token savings for large multi-epic projects through selective loading optimization.
## Document Sharding System
### Core Features
- **Universal Support**: All 12 BMM workflows (Phase 1-4) handle both whole and sharded documents
- **Dual Loading Strategy**: Full Load (Phase 1-3) vs Selective Load (Phase 4)
- **Automatic Discovery**: Workflows detect format transparently (whole → sharded priority)
- **Efficiency Optimization**: 90%+ token reduction for 10+ epic projects in Phase 4
### Implementation Details
**Phase 1-3 Workflows (7 workflows) - Full Load Strategy:**
- product-brief, prd, gdd, create-ux-design, tech-spec, architecture, solutioning-gate-check
- Load entire sharded documents when present
- Transparent to user experience
- Better organization for large projects
**Phase 4 Workflows (5 workflows) - Selective Load Strategy:**
- sprint-planning (Full Load exception - needs all epics)
- epic-tech-context, create-story, story-context, code-review (Selective Load)
- Load ONLY the specific epic needed (e.g., epic-3.md for Epic 3 stories)
- Massive efficiency: Skip loading 9 other epics in 10-epic project
### Workflow Enhancements
**Added to all workflows:**
- `input_file_patterns` in workflow.yaml with wildcard discovery
- Document Discovery section in instructions.md
- Support for sharded index + section files
- Brownfield `docs/index.md` support
**Pattern standardization:**
```yaml
input_file_patterns:
document:
whole: "{output_folder}/*doc*.md"
sharded: "{output_folder}/*doc*/index.md"
sharded_single: "{output_folder}/*doc*/section-{{id}}.md" # Selective load
```
### Retrospective Workflow Major Overhaul
Transformed retrospective into immersive, interactive team experience:
**Epic Discovery Priority (Fixed):**
- Priority 1: Check sprint-status.yaml for last completed epic
- Priority 2: Ask user directly
- Priority 3: Scan stories folder (last resort)
**New Capabilities:**
- Deep story analysis: Extract dev notes, mistakes, review feedback, lessons learned
- Previous retro integration: Track action items, verify lessons applied
- Significant change detection: Alert when discoveries require epic updates
- Intent-based facilitation: Natural conversation vs scripted phrases
- Party mode protocol: Clear speaker identification (Name (Role): dialogue)
- Team dynamics: Drama, disagreements, diverse perspectives, authentic conflict
**Structure:**
- 12 whole-number steps (no decimals)
- Highly interactive with constant user engagement
- Cross-references previous retro for accountability
- Synthesizes patterns across all stories
- Detects architectural assumption changes
## Documentation
**Created:**
- `docs/document-sharding-guide.md` - Comprehensive 300+ line guide
- What is sharding, when to use it (token thresholds)
- How sharding works (discovery system, loading strategies)
- Using shard-doc tool
- Full Load vs Selective Load patterns
- Complete examples and troubleshooting
- Custom workflow integration patterns
**Updated:**
- `README.md` - Added Document Sharding feature section
- `docs/index.md` - Added under Advanced Topics → Optimization
- `src/modules/bmm/workflows/README.md` - Added sharding section with usage
- `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md` - Added complete implementation patterns for workflow builders
**Documentation levels:**
1. Overview (README.md) - Quick feature highlight
2. User guide (BMM workflows README) - Practical usage
3. Reference (document-sharding-guide.md) - Complete details
4. Builder guide (workflow-creation-guide.md) - Implementation patterns
## Efficiency Gains
**Example: 10-Epic Project**
Before sharding:
- epic-tech-context for Epic 3: Load all 10 epics (~50k tokens)
- create-story for Epic 3: Load all 10 epics (~50k tokens)
- story-context for Epic 3: Load all 10 epics (~50k tokens)
After sharding with selective load:
- epic-tech-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- create-story for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- story-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
## Breaking Changes
None - fully backward compatible. Workflows work with existing whole documents.
## Files Changed
**Workflows Updated (25 files):**
- 7 Phase 1-3 workflows: Added full load sharding support
- 5 Phase 4 workflows: Added selective load sharding support
- 1 retrospective workflow: Complete overhaul with sharding support
**Documentation (5 files):**
- Created: document-sharding-guide.md
- Updated: README.md, docs/index.md, BMM workflows README, BMB workflow-creation-guide
- Removed: Old conversion report (obsolete)
## Future Extensibility
- BMB workflows now aware of sharding patterns
- Custom modules can easily implement sharding support
- Standard patterns documented for consistency
- No need to explain concept in future development
2025-11-02 00:13:33 -05:00
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
4f4b191e8f
research will use the web more, use system date to understand what the read current date is.
2025-11-01 00:14:41 -05:00
a1be5d7292
rename deep research options for chatgpt
2025-10-31 19:43:13 -05:00
b056b42892
fixed installer note
2025-10-31 19:39:06 -05:00
1c9fcbb73b
shard doc uses npx command
2025-10-31 16:51:25 -05:00
88e7ede452
remove voice hooks
2025-10-30 15:34:21 -05:00
d4879d373b
6.0.0-alpha.3
2025-10-30 11:37:03 -05:00
663b76a072
docs updates
2025-10-30 11:26:15 -05:00
ec111972a0
some output should be improved and not run together in chat windows
2025-10-30 08:13:18 -05:00
6d7f42dbec
v6 greenfield quickstart guide
2025-10-29 22:39:13 -05:00
519e2f3d59
manifest version comes from package
2025-10-29 20:04:04 -05:00
d6036e18dd
docs: fix v4 branch link in readme
2025-10-29 09:38:26 -05:00
6d2b6810c2
fix: preserve user's cwd when running via npx
2025-10-29 09:31:38 -05:00
06dab16a75
6.0.0-alpha.2
2025-10-29 09:14:03 -05:00
5a70512a30
chore: remove version prompt from npx installer
2025-10-29 09:12:27 -05:00
b05f4751d7
6.0.0-alpha.1
2025-10-29 08:35:02 -05:00
b5262f78ee
still alpha
2025-10-29 08:34:48 -05:00
5ee57ea8df
cleanup a few more items
2025-10-29 08:19:11 -05:00
fd620d0183
marked sm menu items as optional that are optional
2025-10-28 23:47:48 -05:00
ad8717845d
cline workflows added to support slash commands
2025-10-28 23:16:48 -05:00
503a394218
party mode fix
2025-10-28 22:52:03 -05:00
8376ca0ba2
fix: add CommonMark-compliant markdown formatting rules ( #830 )
...
* fix: add CommonMark-compliant markdown formatting rules to workflow
Problem:
--------
BMAD generates markdown that violates CommonMark specification by omitting
required blank lines around lists, tables, and code blocks. While GitHub's
renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app
break completely, rendering lists as plain text and losing document structure.
Solution:
---------
Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that
enforce proper spacing and consistency:
1. ALWAYS add blank line before and after bullet lists
2. ALWAYS add blank line before and after numbered lists
3. ALWAYS add blank line before and after tables
4. ALWAYS add blank line before and after code blocks
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences
Impact:
-------
- Makes BMAD output CommonMark compliant
- Ensures compatibility with ALL markdown parsers, not just GitHub
- Follows industry best practices for professional documentation
- Future-proofs against stricter parser implementations
- Zero content changes - only formatting improved
Testing:
--------
Comprehensive three-phase testing completed:
- Phase 1: Synthetic test validating fix mechanism
- Phase 2: Fresh install end-to-end test (API Gateway project)
- Phase 3: GitHub validation with visual proof
Results: 1,112 lines of formatting improvements, 0 content changes,
100% CommonMark compliance achieved.
Test Evidence:
--------------
Complete test repository with before/after comparison, Mac Markdown.app
screenshot proving the issue, and comprehensive documentation:
https://github.com/jheyworth/bmad-markdown-formatting-test
See TEST.md for full documentation, test methodology, and evidence.
🤖 Generated with Claude Code (https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com>
* Remove TEST.md per maintainer feedback
As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository.
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
2025-10-28 22:27:48 -05:00
44bc96fadc
readme update
2025-10-28 22:27:23 -05:00
7710d9941d
document-project moved out of phase 1 to right below workflows and documents updated to clarify its not a phase-0 but a prereq and also a post project tool to use.
2025-10-28 22:21:13 -05:00
1cfd58ebb1
installer for delete and replace fixed
2025-10-28 21:44:04 -05:00
1c5b30f361
some v5 references lingered - change to v6
2025-10-28 20:32:08 -05:00
d9c7980b1d
remove unused csv columns from cis
2025-10-28 19:17:44 -05:00
95b875792b
remove tts again
2025-10-28 19:12:10 -05:00
0ee4fa920a
installer fixed to not add game assets to slash commands in some ides that read from the manifest. and fixed the manifest.
2025-10-28 19:09:43 -05:00
e93b208902
file cleanup
2025-10-28 17:22:31 -05:00
3fff30ca61
opencode moved agents back to agent folder
2025-10-28 17:18:53 -05:00
ee58586f39
installer improvements
2025-10-28 12:47:45 -05:00
ed3603f7b2
vast improvements to create story, review story, draft story checklist validation, sm menu items and dev agent menu items fixed
2025-10-28 10:03:19 -05:00
0354d1ae45
story review was missing detailed instructions to review AC and task adherance.
2025-10-28 08:51:58 -05:00
0dab278e7b
story-review renamed code-review and dev-agent performs this
2025-10-28 08:30:44 -05:00
66c66f602d
all workflows can optionally run without a workflow
2025-10-27 23:51:22 -05:00
7ad841964d
installer for bmm includes option to include game assets or not when adding to a project.
2025-10-27 22:38:34 -05:00
f55e822338
brownfield guide draft
2025-10-27 21:18:55 -05:00
24a2271520
update open items list
2025-10-27 18:27:10 -05:00
a484b9975c
claude code flattened commands
2025-10-27 15:18:22 -05:00
913ec47123
fix: CSV column mismatch when upgrading manifest schemas
...
When preserving CSV rows from existing manifest files during module updates,
rows from older schema versions (without the 'standalone' column) were being
added to CSVs with new schema headers, causing "Invalid Record Length" errors
during parsing.
Added schema upgrade logic to detect old column structure and upgrade preserved
rows by adding missing columns with appropriate default values. This ensures all
CSV rows match the header column count, fixing installation errors.
Fixes column count mismatch in:
- workflow-manifest.csv (added standalone column)
- task-manifest.csv (added standalone column)
- tool-manifest.csv (added standalone column)
- agent-manifest.csv (schema validation for future-proofing)
2025-10-27 15:00:57 -05:00
8ed721d029
npx with version selector
2025-10-26 23:42:56 -05:00
334e24823a
doc updates
2025-10-26 23:25:48 -05:00
b753fb293b
workflows tasks and tools can be configured wether they are able to be run standalone from agents with ide commands
2025-10-26 20:06:34 -05:00
63ef5b7bc6
installer fixes
2025-10-26 19:38:38 -05:00
1cb88728e8
installer fixes
2025-10-26 17:04:27 -05:00
8d81edf847
install quick updates
2025-10-26 16:17:37 -05:00
0067fb4880
path fixes, documentation updates, md-xplodr added to core tools
2025-10-26 15:40:43 -05:00
8220c819e6
Add Opencode IDE installer ( #820 )
...
- Added docs/ide-info/opencode.md
- Added tool/cli/installers/lib/ide/opencode.js
- Modified tools/installers/lib/ide/core/detector.js to include
detection for opencode command dir
- Modified tools/cli/platform-codes.yaml to include opencode config
- Modified tools/cli/installers/lib/ide/workflow-command-template.md to
include frontmatter with description as opencode requires this for
commands and adding it to the template by default does not seem to
impact other IDEs
- Modified src/modules/bmm/workflows/workflow-status/workflow.yaml
description so that it properly escapes quotes when interpolated in the
teplate
2025-10-26 11:16:57 -05:00
Brian Madison
jheyworth
Cameron Pitt