diff --git a/.bmad/_cfg/files-manifest.csv b/.bmad/_cfg/files-manifest.csv index 5013dc61..9e4dcca1 100644 --- a/.bmad/_cfg/files-manifest.csv +++ b/.bmad/_cfg/files-manifest.csv @@ -270,14 +270,14 @@ type,name,module,path,hash "yaml","workflow","bmm","bmad/bmm/workflows/workflow-status/init/workflow.yaml","01aae9499f50a40dbbd0018308f3ae016b4d62de3de22d06d2402bdc1a6471a5" "yaml","workflow","bmm","bmad/bmm/workflows/workflow-status/workflow.yaml","6a1ad67ec954660fd8e7433b55ab3b75e768f7efa33aad36cf98cdbc2ef6575b" "yaml","workflow-status-template","bmm","bmad/bmm/workflows/workflow-status/workflow-status-template.yaml","6021202726d2b81f28908ffeb93330d25bcd52986823200e01b814d67c1677dd" -"csv","adv-elicit-methods","core","bmad/core/tasks/adv-elicit-methods.csv","b4e925870f902862899f12934e617c3b4fe002d1b652c99922b30fa93482533b" +"csv","advanced-elicitation-methods","core","bmad/core/tasks/advanced-elicitation-methods.csv","b4e925870f902862899f12934e617c3b4fe002d1b652c99922b30fa93482533b" "csv","brain-methods","core","bmad/core/workflows/brainstorming/brain-methods.csv","ecffe2f0ba263aac872b2d2c95a3f7b1556da2a980aa0edd3764ffb2f11889f3" "md","bmad-master","core","bmad/core/agents/bmad-master.md","906028c592f49b6b9962c7efa63535b069b731237d28617a56434d061210d02a" "md","instructions","core","bmad/core/workflows/brainstorming/instructions.md","f737f1645d0f7af37fddd1d4ac8a387f26999d0be5748ce41bdbcf2b89738413" "md","instructions","core","bmad/core/workflows/party-mode/instructions.md","768a835653fea54cbf4f7136e19f968add5ccf4b1dbce5636c5268d74b1b7181" "md","README","core","bmad/core/workflows/brainstorming/README.md","92d624c9ec560297003db0616671fbd6c278d9ea3dacf1c6cf41f064bacec926" "md","template","core","bmad/core/workflows/brainstorming/template.md","b5c760f4cea2b56c75ef76d17a87177b988ac846657f4b9819ec125d125b7386" -"xml","adv-elicit","core","bmad/core/tasks/adv-elicit.xml","4f45442af426a269c0af709348efe431e335ff45bb8eda7d01e7d100c57e03b9" +"xml","advanced-elicitation","core","bmad/core/tasks/advanced-elicitation.xml","4f45442af426a269c0af709348efe431e335ff45bb8eda7d01e7d100c57e03b9" "xml","bmad-web-orchestrator.agent","core","bmad/core/agents/bmad-web-orchestrator.agent.xml","ac09744c3ad70443fbe6873d6a1345c09ad4ab1fe3e310e3230c912967cb51e9" "xml","index-docs","core","bmad/core/tasks/index-docs.xml","c6a9d79628fd1246ef29e296438b238d21c68f50eadb16219ac9d6200cf03628" "xml","shard-doc","core","bmad/core/tools/shard-doc.xml","f2ec685bd3f9ca488c47c494b344b8cff1854d5439c7207182e08ecfa0bb4a07" diff --git a/.bmad/_cfg/task-manifest.csv b/.bmad/_cfg/task-manifest.csv index 804eb635..a308b80a 100644 --- a/.bmad/_cfg/task-manifest.csv +++ b/.bmad/_cfg/task-manifest.csv @@ -1,5 +1,5 @@ name,displayName,description,module,path,standalone -"adv-elicit","Advanced Elicitation","When called from workflow","core","bmad/core/tasks/adv-elicit.xml","true" +"advanced-elicitation","Advanced Elicitation","When called from workflow","core","bmad/core/tasks/advanced-elicitation.xml","true" "index-docs","Index Docs","Generates or updates an index.md of all documents in the specified directory","core","bmad/core/tasks/index-docs.xml","true" "validate-workflow","Validate Workflow Output","Run a checklist against a document with thorough analysis and produce a validation report","core","bmad/core/tasks/validate-workflow.xml","false" "workflow","Execute Workflow","Execute given workflow by loading its configuration, following instructions, and producing output","core","bmad/core/tasks/workflow.xml","false" diff --git a/.bmad/bmb/workflows/convert-legacy/README.md b/.bmad/bmb/workflows/convert-legacy/README.md index 73c27270..793fb48d 100644 --- a/.bmad/bmb/workflows/convert-legacy/README.md +++ b/.bmad/bmb/workflows/convert-legacy/README.md @@ -126,7 +126,7 @@ convert-legacy/ **Template-to-Workflow Conversion (5c)** - Converts YAML template sections to workflow steps -- Maps `elicit: true` flags to `{project-root}/.bmad/core/tasks/adv-elicit.xml` tags +- Maps `elicit: true` flags to `{project-root}/.bmad/core/tasks/advanced-elicitation.xml` tags - Transforms conditional sections to flow control - Creates proper template.md from content structure - Integrates v4 create-doc.md task patterns diff --git a/.bmad/bmb/workflows/convert-legacy/checklist.md b/.bmad/bmb/workflows/convert-legacy/checklist.md index bc43842b..aac4d13c 100644 --- a/.bmad/bmb/workflows/convert-legacy/checklist.md +++ b/.bmad/bmb/workflows/convert-legacy/checklist.md @@ -48,7 +48,7 @@ - [ ] All sections converted to workflow steps - [ ] Section hierarchy maintained in instructions - [ ] Variables ({{var}}) preserved in template.md -- [ ] Elicitation points (elicit: true) converted to {project-root}/.bmad/core/tasks/adv-elicit.xml +- [ ] Elicitation points (elicit: true) REMOVED - [ ] Conditional sections preserved with if="" attributes - [ ] Repeatable sections converted to repeat="" attributes diff --git a/.bmad/bmb/workflows/convert-legacy/instructions.md b/.bmad/bmb/workflows/convert-legacy/instructions.md index 49155164..18d9e8f3 100644 --- a/.bmad/bmb/workflows/convert-legacy/instructions.md +++ b/.bmad/bmb/workflows/convert-legacy/instructions.md @@ -193,7 +193,6 @@ For Modules: 2. Convert template sections to instructions.md: - Each YAML section → workflow step - - `elicit: true` → `{project-root}/.bmad/core/tasks/adv-elicit.xml` tag - Conditional sections → `if="condition"` attribute - Repeatable sections → `repeat="for-each"` attribute - Section instructions → step content @@ -277,7 +276,7 @@ date: system-generated 4. Handle special v4 patterns: - - 1-9 elicitation menus → v6 {project-root}/.bmad/core/tasks/adv-elicit.xml + - 1-9 elicitation menus → v6 {project-root}/.bmad/core/tasks/advanced-elicitation.xml - Agent permissions → note in instructions - YOLO mode → autonomous flag or optional steps - Critical notices → workflow.yaml comments diff --git a/.bmad/bmb/workflows/create-module/instructions.md b/.bmad/bmb/workflows/create-module/instructions.md index 494a2ff3..bd22056b 100644 --- a/.bmad/bmb/workflows/create-module/instructions.md +++ b/.bmad/bmb/workflows/create-module/instructions.md @@ -338,18 +338,14 @@ prompt: // {{module_name}} Module Installer // Custom installation logic -/\*\* - -- Module installation hook -- Called after files are copied but before IDE configuration -- +- // Module installation hook +- // Called after files are copied but before IDE configuration - @param {Object} options - Installation options - @param {string} options.projectRoot - Project root directory - @param {Object} options.config - Module configuration from install-config.yaml - @param {Array} options.installedIDEs - List of IDE codes being configured - @param {Object} options.logger - Logger instance (log, warn, error methods) - @returns {boolean} - true if successful, false to abort installation - \*/ async function install(options) { const { projectRoot, config, installedIDEs, logger } = options; diff --git a/.bmad/bmb/workflows/create-workflow/instructions.md b/.bmad/bmb/workflows/create-workflow/instructions.md index 28dd5268..d48a7bb2 100644 --- a/.bmad/bmb/workflows/create-workflow/instructions.md +++ b/.bmad/bmb/workflows/create-workflow/instructions.md @@ -328,7 +328,7 @@ Generate the instructions.md file following the workflow creation guide: 4. Use proper XML tags from guide: - Execution: , , , , - - Output: , {project-root}/.bmad/core/tasks/adv-elicit.xml, , + - Output: , {project-root}/.bmad/core/tasks/advanced-elicitation.xml, , - Flow: , , 5. Best practices from guide: diff --git a/.bmad/bmb/workflows/create-workflow/workflow-creation-guide.md b/.bmad/bmb/workflows/create-workflow/workflow-creation-guide.md index 71d98bc3..83358561 100644 --- a/.bmad/bmb/workflows/create-workflow/workflow-creation-guide.md +++ b/.bmad/bmb/workflows/create-workflow/workflow-creation-guide.md @@ -855,7 +855,7 @@ _Generated on {{date}}_ **Output:** - `` - Save checkpoint -- `{project-root}/.bmad/core/tasks/adv-elicit.xml` - Trigger AI enhancement +- `{project-root}/.bmad/core/tasks/advanced-elicitation.xml` - Trigger AI enhancement - `` - Important info - `` - Show example @@ -904,7 +904,7 @@ _Generated on {{date}}_ Create functional and non-functional requirements. requirements - {project-root}/.bmad/core/tasks/adv-elicit.xml + {project-root}/.bmad/core/tasks/advanced-elicitation.xml diff --git a/.bmad/core/agents/bmad-web-orchestrator.agent.xml b/.bmad/core/agents/bmad-web-orchestrator.agent.xml index 6dcd90fd..66876b16 100644 --- a/.bmad/core/agents/bmad-web-orchestrator.agent.xml +++ b/.bmad/core/agents/bmad-web-orchestrator.agent.xml @@ -107,7 +107,7 @@ Transform into a specific agent Enter group chat with all agents simultaneously - Push agent to perform advanced elicitation + Push agent to perform advanced elicitation Exit current session \ No newline at end of file diff --git a/.bmad/core/tasks/adv-elicit.xml b/.bmad/core/tasks/adv-elicit.xml index fe900f0c..ef883bba 100644 --- a/.bmad/core/tasks/adv-elicit.xml +++ b/.bmad/core/tasks/adv-elicit.xml @@ -1,5 +1,5 @@ - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER @@ -68,7 +68,7 @@ CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations - Select 5 different methods from adv-elicit-methods.csv, present new list with same prompt format + Select 5 different methods from advanced-elicitation-methods.csv, present new list with same prompt format Complete elicitation and proceed diff --git a/.bmad/core/workflows/brainstorming/instructions.md b/.bmad/core/workflows/brainstorming/instructions.md index bc991a5d..a619da5b 100644 --- a/.bmad/core/workflows/brainstorming/instructions.md +++ b/.bmad/core/workflows/brainstorming/instructions.md @@ -254,7 +254,7 @@ Analyze the session to identify deeper patterns: 2. **Surface key insights** - What realizations emerged during the process? -> insights_learnings 3. **Note surprising connections** - What unexpected relationships were discovered? -> insights_learnings -{project-root}/.bmad/core/tasks/adv-elicit.xml +{project-root}/.bmad/core/tasks/advanced-elicitation.xml key_themes, insights_learnings diff --git a/.claude/commands/bmad/bmm/agents/analyst.md b/.claude/commands/bmad/bmm/agents/analyst.md index ac3b92dc..4f605bfd 100644 --- a/.claude/commands/bmad/bmm/agents/analyst.md +++ b/.claude/commands/bmad/bmm/agents/analyst.md @@ -68,7 +68,7 @@ You must fully embody this agent's persona and follow all activation instruction Generate comprehensive documentation of an existing Project Guide me through Research Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/architect.md b/.claude/commands/bmad/bmm/agents/architect.md index 927c8801..83e84393 100644 --- a/.claude/commands/bmad/bmm/agents/architect.md +++ b/.claude/commands/bmad/bmm/agents/architect.md @@ -73,7 +73,7 @@ You must fully embody this agent's persona and follow all activation instruction Validate Architecture Document Validate solutioning complete, ready for Phase 4 (Level 2-4 only) Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/pm.md b/.claude/commands/bmad/bmm/agents/pm.md index 5f002ca4..46f28017 100644 --- a/.claude/commands/bmad/bmm/agents/pm.md +++ b/.claude/commands/bmad/bmm/agents/pm.md @@ -77,7 +77,7 @@ You must fully embody this agent's persona and follow all activation instruction Validate Technical Specification Document Course Correction Analysis Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/sm.md b/.claude/commands/bmad/bmm/agents/sm.md index 75db33a1..fa7d858e 100644 --- a/.claude/commands/bmad/bmm/agents/sm.md +++ b/.claude/commands/bmad/bmm/agents/sm.md @@ -86,7 +86,7 @@ You must fully embody this agent's persona and follow all activation instruction (Optional) Facilitate team retrospective after an epic is completed (Optional) Execute correct-course task Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/tea.md b/.claude/commands/bmad/bmm/agents/tea.md index fb4498a2..1f6e6d35 100644 --- a/.claude/commands/bmad/bmm/agents/tea.md +++ b/.claude/commands/bmad/bmm/agents/tea.md @@ -73,7 +73,7 @@ You must fully embody this agent's persona and follow all activation instruction Scaffold CI/CD quality pipeline Review test quality using comprehensive knowledge base and best practices Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/tech-writer.md b/.claude/commands/bmad/bmm/agents/tech-writer.md index d27ef98c..71040a22 100644 --- a/.claude/commands/bmad/bmm/agents/tech-writer.md +++ b/.claude/commands/bmad/bmm/agents/tech-writer.md @@ -83,7 +83,7 @@ You must fully embody this agent's persona and follow all activation instruction Create clear technical explanations with examples Show BMAD documentation standards reference (CommonMark, Mermaid, OpenAPI) Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/bmm/agents/ux-designer.md b/.claude/commands/bmad/bmm/agents/ux-designer.md index da99004d..adafaa73 100644 --- a/.claude/commands/bmad/bmm/agents/ux-designer.md +++ b/.claude/commands/bmad/bmm/agents/ux-designer.md @@ -72,7 +72,7 @@ You must fully embody this agent's persona and follow all activation instruction Conduct Design Thinking Workshop to Define the User Specification Validate UX Specification and Design Artifacts Consult with other expert agents from the party - Advanced elicitation techniques to challenge the LLM to get better results + Advanced elicitation techniques to challenge the LLM to get better results Exit with confirmation diff --git a/.claude/commands/bmad/core/tasks/adv-elicit.md b/.claude/commands/bmad/core/tasks/adv-elicit.md index 12e60fd3..8dcb3b14 100644 --- a/.claude/commands/bmad/core/tasks/adv-elicit.md +++ b/.claude/commands/bmad/core/tasks/adv-elicit.md @@ -4,6 +4,6 @@ description: 'When called from workflow' # Advanced Elicitation -LOAD and execute the task at: {project-root}/bmad/core/tasks/adv-elicit.xml +LOAD and execute the task at: {project-root}/bmad/core/tasks/advanced-elicitation.xml Follow all instructions in the task file exactly as written. diff --git a/.github/ISSUE_TEMPLATE/idea_submission.md b/.github/ISSUE_TEMPLATE/idea_submission.md index a915cdc8..aec346ae 100644 --- a/.github/ISSUE_TEMPLATE/idea_submission.md +++ b/.github/ISSUE_TEMPLATE/idea_submission.md @@ -92,7 +92,7 @@ Fix issues and add features. _Why this is poor: Too vague, no specific problem identified, no measurable success criteria, unclear scope_ -**** + --- diff --git a/CHANGELOG.md b/CHANGELOG.md index 555bdf37..d9704da2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,283 @@ ## [Unreleased] +## [6.0.0-alpha.8] + +**Release: November 9, 2025** + +This alpha release focuses on installation flexibility, artifact organization, and comprehensive web bundle enhancements for better multi-agent collaboration. + +### 🎯 Installation Path Enhancements + +**Configurable Installation Directory:** + +- Users can now specify custom installation directories during setup +- Changed default installation to `.bmad` (hidden directory) for cleaner project organization +- Reduces visual clutter in project root by hiding BMAD infrastructure files +- VS Code settings updated to work with new `.bmad` directory structure + +**Ephemeral File Handling:** + +- Updated phase 4 implementation workflows to use ephemeral file locations +- Better separation between documentation and implementation artifacts +- Phase 4 items (stories, code review, sprint plan, context files) can now be stored outside docs folder +- Installer includes questions for artifact path selection + +### 🚀 CLI & Agent Loading Improvements + +**Optimized Agent Loading:** + +- CLI commands now load from installed agent files instead of maintaining duplicates +- Eliminates duplication between source and installed agent definitions +- Reduces maintenance burden and ensures consistency + +**Installer UX Enhancements:** + +- Enhanced installer interface with version display +- Better visual feedback during installation process + +### 🌐 Web Bundle Enhancements + +**Party Mode Support:** + +- All web bundles (single agent and team) now include party mode for multi-agent collaboration +- Users can invoke multi-agent discussions from any bundled agent +- Added default-party.csv files to bmm, bmgd, and cis modules with customizable party configurations + +**Advanced Elicitation Integration:** + +- Integrated advanced elicitation capabilities into standalone agents +- All 39 elicitation methods now available in web bundles + +**Expanded Agent Bundles:** + +- New web bundle outputs for all agents: analyst, architect, dev, pm, sm, tea, tech-writer, ux-designer +- Game development agents: game-designer, game-dev, game-architect, game-scrum-master +- Creative Intelligence Suite agents fully bundled + +**Team Customization:** + +- Customizable party configurations per module +- Users can define which agents participate in party mode discussions + +### 🔧 Phase 4 Workflow Updates + +**Artifact Separation (In Progress):** + +- Initiated separation of phase 4 implementation artifacts from documentation +- Dedicated artifact path for stories, code review, sprint plan, context files +- Updated workflow.yaml files for: + - code-review workflow + - sprint-planning workflow + - story-context workflow + - epic-tech-context workflow + - retrospective workflow +- Configuration support added for artifact path selection during installation + +### 🛠️ IDE Integration + +**Gemini TOML:** + +- Improved with clear loading instructions using @ commands +- Better documentation for Gemini CLI users + +**Agent Launcher Templates:** + +- Agent launcher markdown files now use centralized critical indication templates +- Improved consistency across IDE configurations + +**GitHub Copilot:** + +- Updated tool names to match official VS Code documentation (November 2025) +- Better integration with latest Copilot features + +### 🐛 Bug Fixes + +- Fixed duplicate manifest entries by deduplicating module lists using Set +- Cleaned up legacy `bmad/`, `bmd/`, and `web-bundles/` directories on installation +- Various improvements to phase 4 workflow artifact handling +- Better error handling in web bundler + +### 📦 Infrastructure Changes + +- New agent and action command header models for standardization +- Enhanced web-bundle-activation-steps fragment +- Updated web-bundler.js to support new structure +- Improved party mode instructions and workflow orchestration + +### 📊 Impact Summary + +This release brings significant improvements to installation flexibility and multi-agent collaboration: + +- **Flexibility:** Configurable installation paths for different project preferences +- **Organization:** Cleaner project structure with hidden `.bmad` directory +- **Collaboration:** Comprehensive party mode support in all web bundles +- **Consistency:** Optimized agent loading eliminates duplication +- **Artifact Management:** Better separation of documentation vs implementation artifacts + +--- + +## [6.0.0-alpha.7] + +**Release: November 7, 2025** + +This alpha release focuses on web bundle improvements, module extraction, and enhanced workflow vendoring capabilities. + +### 🌐 Web Bundler Improvements + +**Workflow Vendoring:** + +- Web bundler now performs workflow vendoring before bundling agents +- Workflows referenced via `workflow-install` attributes are automatically copied from source to destination +- Similar to module installer behavior, ensuring consistency +- Config_source is updated in vendored workflows to reference target module +- Fixes missing dependency warnings for cross-module workflow references + +**Enhanced Dependency Resolution:** + +- Improved workflow dependency detection and bundling +- Better handling of workflows with `web_bundle: false` flag +- Menu items for non-web workflows are now properly excluded from bundles +- Shows positive "✓ No missing dependencies" message when all dependencies resolved + +**Advanced Elicitation Fix:** + +- Added missing `adv-elicit-methods.csv` to workflow bundles +- Includes CSV in all workflows using `adv-elicit.xml`: + - architecture workflow + - prd workflow + - tech-spec workflow +- Fixes runtime failures when advanced elicitation is invoked in bundled workflows + +### 🎮 BMGD Module Extraction + +**Game Development Module:** + +- Extracted game development functionality from BMM into standalone BMGD module +- Moved agents: game-designer, game-dev, game-architect from BMM to BMGD +- Moved team config: team-gamedev +- Created new Game Dev Scrum Master agent using workflow vendoring pattern + +**Reorganized Game Dev Workflows:** + +Industry-standard game development phases: + +- **Phase 1 (Preproduction):** brainstorm-game, game-brief +- **Phase 2 (Design):** gdd (Game Design Document), narrative +- **Phase 3 (Technical):** game-architecture +- **Phase 4 (Production):** Vendors BMM workflows (dev-story, code-review, sprint-planning, etc.) + +**Workflow Vendoring Implementation:** + +- Game Dev SM agent uses `workflow-install` to vendor BMM phase 4 workflows +- Enables module independence while sharing proven workflows +- Sets pattern for future module extractions and specializations + +### 🔧 IDE Installation Improvements + +**Claude Code Fix:** + +- Fixed regression preventing README file slash commands from installing +- Cleaned up bmad folders in tools directory on installation +- Better handling of IDE-specific configuration files + +### 📚 Documentation Updates + +**TEA Agent Documentation:** + +- Updated Test Architect documentation to align with BMad 4-phase methodology +- Better integration with overall workflow structure +- Clearer role definitions and responsibilities + +**Diagram Improvements:** + +- More visual documentation updates +- Enhanced Mermaid diagram drafts +- Better workflow visualization + +### 🐛 Bug Fixes + +- Fixed missing `adv-elicit-methods.csv` in workflow bundles +- Removed menu items for workflows with `web_bundle: false` +- Fixed IDE installation regression for Claude Code README commands +- Improved workflow vendoring dependency resolution + +### 🔄 Breaking Changes + +**Module Structure:** + +- Game development functionality moved from BMM to BMGD module +- Existing projects using game dev agents should reinstall to get new module structure +- No functional changes - agents work the same way in new location + +### 📊 Impact Summary + +This release establishes better module organization and cross-module workflow sharing: + +- **Modularity:** BMGD extraction demonstrates clean module separation pattern +- **Reusability:** Workflow vendoring enables sharing proven workflows across modules +- **Reliability:** Advanced elicitation now works correctly in all web bundles +- **Flexibility:** Modules can be specialized while leveraging core workflows + +--- + +## [6.0.0-alpha.6] + +**Release: November 4, 2025** + +This alpha release focuses on installation flexibility, improved UX, and bug fixes for the installer system. + +### 🐛 Bug Fixes + +**Installer Fixes:** + +- Fixed manifestPath error in ide-config-manager causing installation failures +- Fixed installer option display to show full labels instead of just values for single/multi-select +- Better error handling during installation process + +**Documentation Installation:** + +- Add conditional documentation installation feature +- Users can now opt out of installing docs to reduce installation footprint +- New `install_user_docs` configuration option (defaults to true) +- Useful for production environments or users who prefer online documentation + +### 🎨 User Experience Improvements + +**Installer UX:** + +- Improved config question display with descriptive labels +- Better formatting for single and multi-select options +- Clearer feedback during installation process +- More intuitive option selection + +### 📖 Documentation Updates + +**Contributing Guidelines:** + +- Updated CONTRIBUTING.md to remove references to non-existent 'next' branch +- Clearer contribution workflow instructions +- Better alignment with actual repository structure + +### 🧹 Maintenance + +**Issue Tracker Cleanup:** + +- Closed 54 legacy v4 issues (older than 1 month) +- Maintains clean issue tracker focused on v6 development +- Improved issue management and prioritization + +### 📊 Impact Summary + +This release improves installation reliability and user experience: + +- **Reliability:** Fixed critical installer bugs preventing successful installations +- **Flexibility:** Optional documentation installation for different use cases +- **Clarity:** Better UX with descriptive labels and clearer feedback +- **Maintenance:** Clean issue tracker focused on current development + +--- + ## [6.0.0-alpha.5] **Release: November 4, 2025** @@ -43,7 +320,7 @@ Users now choose development approach based on **project needs and team preferen **1. Elicitation System Modernization:** - Removed legacy `` XML tag from core workflow.xml -- Replaced with explicit `adv-elicit.xml` pattern +- Replaced with explicit `advanced-elicitation.xml` pattern - More self-documenting and eliminates confusing indirection layer - Added strategic elicitation points across all planning workflows: - **PRD:** After success criteria, scope, functional requirements, and final review diff --git a/src/core/agents/bmad-web-orchestrator.agent.xml b/src/core/agents/bmad-web-orchestrator.agent.xml index 6dcd90fd..cf5a9b78 100644 --- a/src/core/agents/bmad-web-orchestrator.agent.xml +++ b/src/core/agents/bmad-web-orchestrator.agent.xml @@ -107,7 +107,7 @@ Transform into a specific agent Enter group chat with all agents simultaneously - Push agent to perform advanced elicitation + Push agent to perform advanced elicitation Exit current session \ No newline at end of file diff --git a/src/core/tasks/adv-elicit.xml b/src/core/tasks/advanced-elicitation.xml similarity index 94% rename from src/core/tasks/adv-elicit.xml rename to src/core/tasks/advanced-elicitation.xml index fe900f0c..ef883bba 100644 --- a/src/core/tasks/adv-elicit.xml +++ b/src/core/tasks/advanced-elicitation.xml @@ -1,5 +1,5 @@ - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER @@ -68,7 +68,7 @@ CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations - Select 5 different methods from adv-elicit-methods.csv, present new list with same prompt format + Select 5 different methods from advanced-elicitation-methods.csv, present new list with same prompt format Complete elicitation and proceed diff --git a/src/core/tasks/workflow.xml b/src/core/tasks/workflow.xml index 2bb093bc..ddbc1a17 100644 --- a/src/core/tasks/workflow.xml +++ b/src/core/tasks/workflow.xml @@ -62,6 +62,7 @@ ask xml tag → Prompt user and WAIT for response invoke-workflow xml tag → Execute another workflow with given inputs invoke-task xml tag → Execute specified task + invoke-protocol name="protocol_name" xml tag → Execute reusable protocol from protocols section goto step="x" → Jump to specified step @@ -72,7 +73,21 @@ Save to file (Write first time, Edit subsequent) Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━ Display generated content - Continue [c] or Edit [e]? WAIT for response + [a] Advanced Elicitation, [c] Continue, [p] Party-Mode, [y] YOLO the rest of this document only, or converse about this + section with the agent? WAIT for response. + Start the advanced elicitation workflow @/.bmad/core/workflows/party-mode/workflow.yaml + + + Continue to next step + + + Start the party-mode workflow + + + Enter #yolo mode for the rest of the workflow + + @@ -92,7 +107,8 @@ Full user interaction at all decision points - Skip optional sections, skip all elicitation, minimize prompts + Skip all confirmations and elicitation, minimize prompts and try to produce all of the workflow automatically by + simulating the remaining discussions with an simulated expert user @@ -111,6 +127,7 @@ goto - Jump to another step invoke-workflow - Call another workflow invoke-task - Call a task + invoke-protocol - Execute a reusable protocol (e.g., discover_inputs) template-output - Save content checkpoint @@ -130,24 +147,129 @@ Multiple actions/tags under same condition <check if="condition"> - <action>First action</action> - <action>Second action</action> -</check> + <action>First action</action> + <action>Second action</action> + </check> <check if="validation fails"> - <action>Log error</action> - <goto step="1">Retry</goto> -</check> + <action>Log error</action> + <goto step="1">Retry</goto> + </check> Explicit scope boundaries prevent ambiguity Else/alternative branches <check if="condition A">...</check> -<check if="else">...</check> + <check if="else">...</check> Clear branching logic with explicit blocks + + + Intelligently load project files (whole or sharded) based on workflow's input_file_patterns configuration + + Only execute if workflow.yaml contains input_file_patterns section + + + + Read input_file_patterns from loaded workflow.yaml + For each pattern group (prd, architecture, epics, etc.), note the load_strategy if present + + + + For each pattern in input_file_patterns: + + + Attempt glob match on 'whole' pattern (e.g., "{output_folder}/*prd*.md") + + Load ALL matching files completely (no offset/limit) + Store content in variable: {pattern_name_content} (e.g., {prd_content}) + Mark pattern as RESOLVED, skip to next pattern + + + + + + Determine load_strategy from pattern config (defaults to FULL_LOAD if not specified) + + + Load ALL files in sharded directory - used for PRD, Architecture, UX, brownfield docs + Use glob pattern to find ALL .md files (e.g., "{output_folder}/*architecture*/*.md") + Load EVERY matching file completely + Concatenate content in logical order (index.md first if exists, then alphabetical) + Store in variable: {pattern_name_content} + + + + Load specific shard using template variable - used for epics with {{epic_num}} + Check for template variables in sharded_single pattern (e.g., {{epic_num}}) + If variable undefined, ask user for value OR infer from context + Resolve template to specific file path + Load that specific file + Store in variable: {pattern_name_content} + + + + Load index.md, analyze structure, then intelligently load relevant docs + DO NOT BE LAZY - use best judgment to load documents that might have relevant information + Load index.md from sharded directory + Parse table of contents, links, section headers + Analyze workflow's purpose and objective + Identify which linked/referenced documents are likely relevant + If workflow is about authentication and index shows "Auth Overview", "Payment Setup", "Deployment" → Load auth docs, consider deployment docs, skip payment + Load all identified relevant documents + Store combined content in variable: {pattern_name_content} + When in doubt, LOAD IT - context is valuable, being thorough is better than missing critical info + + + + + + + Set {pattern_name_content} to empty string + Note in session: "No {pattern_name} files found" (not an error, just unavailable) + + + + + + List all loaded content variables with file counts + + ✓ Loaded {prd_content} from 1 file: PRD.md + ✓ Loaded {architecture_content} from 5 sharded files: architecture/index.md, architecture/system-design.md, ... + ✓ Loaded {epics_content} from selective load: epics/epic-3.md + ○ No ux_design files found + + This gives workflow transparency into what context is available + + + + + + <step n="0" goal="Discover and load project context"> + <invoke-protocol name="discover_inputs" /> + </step> + + <step n="1" goal="Analyze requirements"> + <action>Review {prd_content} for functional requirements</action> + <action>Cross-reference with {architecture_content} for technical constraints</action> + </step> + + + + + FULL_LOAD + FULL_LOAD + FULL_LOAD + FULL_LOAD + SELECTIVE_LOAD + INDEX_GUIDED + FULL_LOAD + + + + This is the complete workflow execution engine You MUST Follow instructions exactly as written and maintain conversation context between steps diff --git a/src/core/tools/shard-doc.xml b/src/core/tools/shard-doc.xml index 32c3d84e..bd74d29a 100644 --- a/src/core/tools/shard-doc.xml +++ b/src/core/tools/shard-doc.xml @@ -57,6 +57,50 @@ - Any tool output or warnings Inform user that sharding completed successfully + + + Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion + Present user with options for the original document: + + What would you like to do with the original document `[source-document-name]`? + +Options: +[d] Delete - Remove the original (recommended - shards can always be recombined) +[m] Move to archive - Move original to a backup/archive location +[k] Keep - Leave original in place (NOT recommended - defeats sharding purpose) + +Your choice (d/m/k): + + + Delete the original source document file + Confirm deletion to user: "✓ Original document deleted: [source-document-path]" + The document can be reconstructed from shards by concatenating all section files in order + + + + Determine default archive location: same directory as source, in an "archive" subfolder + Example: /path/to/architecture.md → /path/to/archive/architecture.md + Archive location ([y] to use default: [default-archive-path], or provide custom path): + Use default archive path + Use custom archive path + Create archive directory if it doesn't exist + Move original document to archive location + Confirm move to user: "✓ Original document moved to: [archive-path]" + + + + Display warning to user: + ⚠️ WARNING: Keeping both original and sharded versions is NOT recommended. + +This creates confusion because: +- The discover_inputs protocol may load the wrong version +- Updates to one won't reflect in the other +- You'll have duplicate content taking up space + +Consider deleting or archiving the original document. + Confirm user choice: "Original document kept at: [source-document-path]" + + diff --git a/src/core/workflows/brainstorming/instructions.md b/src/core/workflows/brainstorming/instructions.md index 3811c42b..d46140e0 100644 --- a/src/core/workflows/brainstorming/instructions.md +++ b/src/core/workflows/brainstorming/instructions.md @@ -255,7 +255,7 @@ Analyze the session to identify deeper patterns: 2. **Surface key insights** - What realizations emerged during the process? -> insights_learnings 3. **Note surprising connections** - What unexpected relationships were discovered? -> insights_learnings -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml +{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml key_themes, insights_learnings diff --git a/src/modules/bmb/workflows/convert-legacy/README.md b/src/modules/bmb/workflows/convert-legacy/README.md index 2583c8a5..5ce90aac 100644 --- a/src/modules/bmb/workflows/convert-legacy/README.md +++ b/src/modules/bmb/workflows/convert-legacy/README.md @@ -126,7 +126,7 @@ convert-legacy/ **Template-to-Workflow Conversion (5c)** - Converts YAML template sections to workflow steps -- Maps `elicit: true` flags to `{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml` tags +- Maps `elicit: true` flags to `{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml` tags - Transforms conditional sections to flow control - Creates proper template.md from content structure - Integrates v4 create-doc.md task patterns diff --git a/src/modules/bmb/workflows/convert-legacy/checklist.md b/src/modules/bmb/workflows/convert-legacy/checklist.md index 8220e274..44db1396 100644 --- a/src/modules/bmb/workflows/convert-legacy/checklist.md +++ b/src/modules/bmb/workflows/convert-legacy/checklist.md @@ -48,7 +48,7 @@ - [ ] All sections converted to workflow steps - [ ] Section hierarchy maintained in instructions - [ ] Variables ({{var}}) preserved in template.md -- [ ] Elicitation points (elicit: true) converted to {project-root}/{bmad_folder}/core/tasks/adv-elicit.xml +- [ ] Elicitation points (elicit: true) converted to {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml - [ ] Conditional sections preserved with if="" attributes - [ ] Repeatable sections converted to repeat="" attributes diff --git a/src/modules/bmb/workflows/convert-legacy/instructions.md b/src/modules/bmb/workflows/convert-legacy/instructions.md index 7b1d3e1e..b8194099 100644 --- a/src/modules/bmb/workflows/convert-legacy/instructions.md +++ b/src/modules/bmb/workflows/convert-legacy/instructions.md @@ -193,7 +193,7 @@ For Modules: 2. Convert template sections to instructions.md: - Each YAML section → workflow step - - `elicit: true` → `{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml` tag + - `elicit: true` → `{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml` tag - Conditional sections → `if="condition"` attribute - Repeatable sections → `repeat="for-each"` attribute - Section instructions → step content @@ -277,7 +277,7 @@ date: system-generated 4. Handle special v4 patterns: - - 1-9 elicitation menus → v6 {project-root}/{bmad_folder}/core/tasks/adv-elicit.xml + - 1-9 elicitation menus → v6 {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml - Agent permissions → note in instructions - YOLO mode → autonomous flag or optional steps - Critical notices → workflow.yaml comments diff --git a/src/modules/bmb/workflows/create-module/instructions.md b/src/modules/bmb/workflows/create-module/instructions.md index 2d976d0a..f9892ac2 100644 --- a/src/modules/bmb/workflows/create-module/instructions.md +++ b/src/modules/bmb/workflows/create-module/instructions.md @@ -338,18 +338,13 @@ prompt: // {{module_name}} Module Installer // Custom installation logic -/\*\* - -- Module installation hook -- Called after files are copied but before IDE configuration -- - @param {Object} options - Installation options - @param {string} options.projectRoot - Project root directory - @param {Object} options.config - Module configuration from install-config.yaml - @param {Array} options.installedIDEs - List of IDE codes being configured - @param {Object} options.logger - Logger instance (log, warn, error methods) - @returns {boolean} - true if successful, false to abort installation - \*/ + async function install(options) { const { projectRoot, config, installedIDEs, logger } = options; diff --git a/src/modules/bmb/workflows/create-workflow/instructions.md b/src/modules/bmb/workflows/create-workflow/instructions.md index 86f72bf2..9a174037 100644 --- a/src/modules/bmb/workflows/create-workflow/instructions.md +++ b/src/modules/bmb/workflows/create-workflow/instructions.md @@ -328,7 +328,7 @@ Generate the instructions.md file following the workflow creation guide: 4. Use proper XML tags from guide: - Execution: , , , , - - Output: , {project-root}/{bmad_folder}/core/tasks/adv-elicit.xml, , + - Output: , {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml, , - Flow: , , 5. Best practices from guide: diff --git a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md index 2bf10bf4..64d3c7a5 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md +++ b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md @@ -855,7 +855,6 @@ _Generated on {{date}}_ **Output:** - `` - Save checkpoint -- `{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml` - Trigger AI enhancement - `` - Important info - `` - Show example @@ -904,7 +903,6 @@ _Generated on {{date}}_ Create functional and non-functional requirements. requirements - {project-root}/{bmad_folder}/core/tasks/adv-elicit.xml diff --git a/src/modules/bmgd/agents/game-architect.agent.yaml b/src/modules/bmgd/agents/game-architect.agent.yaml index eb6acdbf..318e2fe2 100644 --- a/src/modules/bmgd/agents/game-architect.agent.yaml +++ b/src/modules/bmgd/agents/game-architect.agent.yaml @@ -28,6 +28,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmgd/agents/game-designer.agent.yaml b/src/modules/bmgd/agents/game-designer.agent.yaml index 451c8afa..95e63b4c 100644 --- a/src/modules/bmgd/agents/game-designer.agent.yaml +++ b/src/modules/bmgd/agents/game-designer.agent.yaml @@ -35,6 +35,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmgd/agents/game-dev.agent.yaml b/src/modules/bmgd/agents/game-dev.agent.yaml index 362d7353..01e7f6cd 100644 --- a/src/modules/bmgd/agents/game-dev.agent.yaml +++ b/src/modules/bmgd/agents/game-dev.agent.yaml @@ -35,6 +35,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmgd/agents/game-scrum-master.agent.yaml b/src/modules/bmgd/agents/game-scrum-master.agent.yaml index f97bfbac..5f24e22f 100644 --- a/src/modules/bmgd/agents/game-scrum-master.agent.yaml +++ b/src/modules/bmgd/agents/game-scrum-master.agent.yaml @@ -70,6 +70,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmgd/workflows/2-design/gdd/instructions-gdd.md b/src/modules/bmgd/workflows/2-design/gdd/instructions-gdd.md index e587995a..c47b7432 100644 --- a/src/modules/bmgd/workflows/2-design/gdd/instructions-gdd.md +++ b/src/modules/bmgd/workflows/2-design/gdd/instructions-gdd.md @@ -221,7 +221,6 @@ Get core game concept and vision. Guide user to define the primary game mechanics that players will interact with throughout the game primary_mechanics -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml Guide user to describe their control scheme and input method (keyboard/mouse, gamepad, touchscreen, etc.), including key bindings or button layouts if known @@ -239,8 +238,6 @@ For each {{placeholder}} in the fragment, elicit and capture that information. GAME_TYPE_SPECIFIC_SECTIONS -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - @@ -304,7 +301,6 @@ For each {{placeholder}} in the fragment, elicit and capture that information. Work with user to translate game features into development epics, following level-appropriate guidelines (Level 1: 1 epic/1-10 stories, Level 2: 1-2 epics/5-15 stories, Level 3: 2-5 epics/12-40 stories, Level 4: 5+ epics/40+ stories) epics -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -325,7 +321,6 @@ For each {{placeholder}} in the fragment, elicit and capture that information. epic*{{epic_number}}*details -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml diff --git a/src/modules/bmgd/workflows/2-design/narrative/instructions-narrative.md b/src/modules/bmgd/workflows/2-design/narrative/instructions-narrative.md index 11d6a310..d0095ddd 100644 --- a/src/modules/bmgd/workflows/2-design/narrative/instructions-narrative.md +++ b/src/modules/bmgd/workflows/2-design/narrative/instructions-narrative.md @@ -143,7 +143,6 @@ For 3-Act: Describe each act/section for your game: act_breakdown -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -162,7 +161,6 @@ Format: Your story beats: story_beats -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml Describe the pacing and flow of your narrative. @@ -195,7 +193,6 @@ For each protagonist include: Your protagonist(s): protagonists -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -233,7 +230,6 @@ For each character include: Your supporting characters: supporting_characters -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -281,7 +277,6 @@ Your world: Your history: history_backstory -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml diff --git a/src/modules/bmgd/workflows/3-technical/game-architecture/checklist.md b/src/modules/bmgd/workflows/3-technical/game-architecture/checklist.md index a1395440..312c0670 100644 --- a/src/modules/bmgd/workflows/3-technical/game-architecture/checklist.md +++ b/src/modules/bmgd/workflows/3-technical/game-architecture/checklist.md @@ -225,15 +225,11 @@ ### Critical Issues Found -- [ ] Issue 1: -- [ ] Issue 2: -- [ ] Issue 3: +{ list issues } ### Recommended Actions Before Implementation -1. *** -2. *** -3. *** +{ list actions } --- diff --git a/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md b/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md index ddd9e68b..1f73d591 100644 --- a/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md +++ b/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md @@ -363,7 +363,6 @@ Provided by Starter: {{yes_if_from_starter}} decision_record -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -393,7 +392,6 @@ Provided by Starter: {{yes_if_from_starter}} project_structure -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -467,7 +465,6 @@ Provided by Starter: {{yes_if_from_starter}} novel_pattern_designs -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -560,7 +557,6 @@ Enforcement: "All agents MUST follow this pattern" implementation_patterns -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -614,7 +610,6 @@ Enforcement: "All agents MUST follow this pattern" architecture_document -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml diff --git a/src/modules/bmgd/workflows/4-production/code-review/backlog_template.md b/src/modules/bmgd/workflows/4-production/code-review/backlog_template.md new file mode 100644 index 00000000..28cfe767 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/code-review/backlog_template.md @@ -0,0 +1,12 @@ +# Engineering Backlog + +This backlog collects cross-cutting or future action items that emerge from reviews and planning. + +Routing guidance: + +- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics. +- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`. +- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section. + +| Date | Story | Epic | Type | Severity | Owner | Status | Notes | +| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- | diff --git a/src/modules/bmgd/workflows/4-production/code-review/checklist.md b/src/modules/bmgd/workflows/4-production/code-review/checklist.md new file mode 100644 index 00000000..ce903701 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/code-review/checklist.md @@ -0,0 +1,22 @@ +# Senior Developer Review - Validation Checklist + +- [ ] Story file loaded from `{{story_path}}` +- [ ] Story Status verified as one of: {{allow_status_values}} +- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}}) +- [ ] Story Context located or warning recorded +- [ ] Epic Tech Spec located or warning recorded +- [ ] Architecture/standards docs loaded (as available) +- [ ] Tech stack detected and documented +- [ ] MCP doc search performed (or web fallback) and references captured +- [ ] Acceptance Criteria cross-checked against implementation +- [ ] File List reviewed and validated for completeness +- [ ] Tests identified and mapped to ACs; gaps noted +- [ ] Code quality review performed on changed files +- [ ] Security review performed on changed files and dependencies +- [ ] Outcome decided (Approve/Changes Requested/Blocked) +- [ ] Review notes appended under "Senior Developer Review (AI)" +- [ ] Change Log updated with review entry +- [ ] Status updated according to settings (if enabled) +- [ ] Story saved successfully + +_Reviewer: {{user_name}} on {{date}}_ diff --git a/src/modules/bmgd/workflows/4-production/code-review/instructions.md b/src/modules/bmgd/workflows/4-production/code-review/instructions.md new file mode 100644 index 00000000..59b6ca6c --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/code-review/instructions.md @@ -0,0 +1,398 @@ +# Senior Developer Review - Workflow Instructions + +````xml +The workflow execution engine is governed by: {project-root}/{bmad_folder}/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} +This workflow performs a SYSTEMATIC Senior Developer Review on a story with status "review", validates EVERY acceptance criterion and EVERY completed task, appends structured review notes with evidence, and updates the story status based on outcome. +If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, offer ad-hoc review option. +Ad-hoc review mode: User can specify any files to review and what to review for (quality, security, requirements, etc.). Creates standalone review report. +SYSTEMATIC VALIDATION REQUIREMENT: For EVERY acceptance criterion, verify implementation with evidence (file:line). For EVERY task marked complete, verify it was actually done. Tasks marked complete but not done = HIGH SEVERITY finding. +⚠️ ZERO TOLERANCE FOR LAZY VALIDATION ⚠️ +If you FAIL to catch even ONE task marked complete that was NOT actually implemented, or ONE acceptance criterion marked done that is NOT in the code with evidence, you have FAILED YOUR ONLY PURPOSE. This is an IMMEDIATE DISQUALIFICATION. No shortcuts. No assumptions. No "looks good enough." You WILL read every file. You WILL verify every claim. You WILL provide evidence (file:line) for EVERY validation. Failure to catch false completions = you failed humanity and the project. Your job is to be the uncompromising gatekeeper. DO YOUR JOB COMPLETELY OR YOU WILL BE REPLACED. +Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section. +Execute ALL steps in exact order; do NOT skip steps + +DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content. + + + + + + Use {{story_path}} directly + Read COMPLETE story file and parse sections + Extract story_key from filename or story metadata + Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed" + + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {{output_folder}}/sprint-status.yaml + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find FIRST story (reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "review" + + + + 📋 No stories with status "review" found + +**What would you like to do?** +1. Run `dev-story` to implement and mark a story ready for review +2. Check sprint-status.yaml for current story states +3. Tell me what code to review and what to review it for + + Select an option (1/2/3): + + + What code would you like me to review? + + Provide: + - File path(s) or directory to review + - What to review for: + • General quality and standards + • Requirements compliance + • Security concerns + • Performance issues + • Architecture alignment + • Something else (specify) + + Your input:? + + + Parse user input to extract: + - {{review_files}}: file paths or directories to review + - {{review_focus}}: what aspects to focus on + - {{review_context}}: any additional context provided + + + Set ad_hoc_review_mode = true + Skip to step 4 with custom scope + + + + HALT + + + + Use the first story found with status "review" + Resolve story file path in {{story_dir}} + Read the COMPLETE story file + + + Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata + Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log + HALT with message: "Unable to read story file" + + + + + After discovery, these content variables are available: {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} + + + + 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}}) + Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}" + + Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. + Architecture and brownfield docs were pre-loaded in Step 1.5 as {architecture_content} and {document_project_content} + + + + Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.). + Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available). + + + + + Use {{review_files}} as the file list to review + Focus review on {{review_focus}} aspects specified by user + Use {{review_context}} for additional guidance + Skip acceptance criteria checking (no story context) + If architecture docs exist, verify alignment with architectural constraints + + + + SYSTEMATIC VALIDATION - Check EVERY AC and EVERY task marked complete + + From the story, read Acceptance Criteria section completely - parse into numbered list + From the story, read Tasks/Subtasks section completely - parse ALL tasks and subtasks with their completion state ([x] = completed, [ ] = incomplete) + From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks). + + Step 4A: SYSTEMATIC ACCEPTANCE CRITERIA VALIDATION + Create AC validation checklist with one entry per AC + For EACH acceptance criterion (AC1, AC2, AC3, etc.): + 1. Read the AC requirement completely + 2. Search changed files for evidence of implementation + 3. Determine: IMPLEMENTED, PARTIAL, or MISSING + 4. Record specific evidence (file:line references where AC is satisfied) + 5. Check for corresponding tests (unit/integration/E2E as applicable) + 6. If PARTIAL or MISSING: Flag as finding with severity based on AC criticality + 7. Document in AC validation checklist + + Generate AC Coverage Summary: "X of Y acceptance criteria fully implemented" + + Step 4B: SYSTEMATIC TASK COMPLETION VALIDATION + Create task validation checklist with one entry per task/subtask + For EACH task/subtask marked as COMPLETED ([x]): + 1. Read the task description completely + 2. Search changed files for evidence the task was actually done + 3. Determine: VERIFIED COMPLETE, QUESTIONABLE, or NOT DONE + 4. Record specific evidence (file:line references proving task completion) + 5. **CRITICAL**: If marked complete but NOT DONE → Flag as HIGH SEVERITY finding with message: "Task marked complete but implementation not found: [task description]" + 6. If QUESTIONABLE → Flag as MEDIUM SEVERITY finding: "Task completion unclear: [task description]" + 7. Document in task validation checklist + + For EACH task/subtask marked as INCOMPLETE ([ ]): + 1. Note it was not claimed to be complete + 2. Check if it was actually done anyway (sometimes devs forget to check boxes) + 3. If done but not marked: Note in review (helpful correction, not a finding) + + Generate Task Completion Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete" + + Step 4C: CROSS-CHECK EPIC TECH-SPEC REQUIREMENTS + Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files. + flag as High Severity finding. + + Step 4D: COMPILE VALIDATION FINDINGS + Compile all validation findings into structured list: + - Missing AC implementations (severity based on AC importance) + - Partial AC implementations (MEDIUM severity) + - Tasks falsely marked complete (HIGH severity - this is critical) + - Questionable task completions (MEDIUM severity) + - Missing tests for ACs (severity based on AC criticality) + - Architecture violations (HIGH severity) + + + + + + For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns. + Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests). + Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns. + Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections. + + + + Determine outcome based on validation results: + - BLOCKED: Any HIGH severity finding (AC missing, task falsely marked complete, critical architecture violation) + - CHANGES REQUESTED: Any MEDIUM severity findings or multiple LOW severity issues + - APPROVE: All ACs implemented, all completed tasks verified, no significant issues + + + Prepare a structured review report with sections: + 1. **Summary**: Brief overview of review outcome and key concerns + 2. **Outcome**: Approve | Changes Requested | Blocked (with justification) + 3. **Key Findings** (by severity): + - HIGH severity issues first (especially falsely marked complete tasks) + - MEDIUM severity issues + - LOW severity issues + 4. **Acceptance Criteria Coverage**: + - Include complete AC validation checklist from Step 4A + - Show: AC# | Description | Status (IMPLEMENTED/PARTIAL/MISSING) | Evidence (file:line) + - Summary: "X of Y acceptance criteria fully implemented" + - List any missing or partial ACs with severity + 5. **Task Completion Validation**: + - Include complete task validation checklist from Step 4B + - Show: Task | Marked As | Verified As | Evidence (file:line) + - **CRITICAL**: Highlight any tasks marked complete but not done in RED/bold + - Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete" + 6. **Test Coverage and Gaps**: + - Which ACs have tests, which don't + - Test quality issues found + 7. **Architectural Alignment**: + - Tech-spec compliance + - Architecture violations if any + 8. **Security Notes**: Security findings if any + 9. **Best-Practices and References**: With links + 10. **Action Items**: + - CRITICAL: ALL action items requiring code changes MUST have checkboxes for tracking + - Format for actionable items: `- [ ] [Severity] Description (AC #X) [file: path:line]` + - Format for informational notes: `- Note: Description (no action required)` + - Imperative phrasing for action items + - Map to related ACs or files with specific line references + - Include suggested owners if clear + - Example format: + ``` + ### Action Items + + **Code Changes Required:** + - [ ] [High] Add input validation on login endpoint (AC #1) [file: src/routes/auth.js:23-45] + - [ ] [Med] Add unit test for invalid email format [file: tests/unit/auth.test.js] + + **Advisory Notes:** + - Note: Consider adding rate limiting for production deployment + - Note: Document the JWT expiration policy in README + ``` + + + The AC validation checklist and task validation checklist MUST be included in the review - this is the evidence trail + + + + + Generate review report as a standalone document + Save to {{output_folder}}/code-review-{{date}}.md + Include sections: + - Review Type: Ad-Hoc Code Review + - Reviewer: {{user_name}} + - Date: {{date}} + - Files Reviewed: {{review_files}} + - Review Focus: {{review_focus}} + - Outcome: (Approve | Changes Requested | Blocked) + - Summary + - Key Findings + - Test Coverage and Gaps + - Architectural Alignment + - Security Notes + - Best-Practices and References (with links) + - Action Items + + Review saved to: {{output_folder}}/code-review-{{date}}.md + + + + Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)". + Insert subsections: + - Reviewer: {{user_name}} + - Date: {{date}} + - Outcome: (Approve | Changes Requested | Blocked) with justification + - Summary + - Key Findings (by severity - HIGH/MEDIUM/LOW) + - **Acceptance Criteria Coverage**: + * Include complete AC validation checklist with table format + * AC# | Description | Status | Evidence + * Summary: X of Y ACs implemented + - **Task Completion Validation**: + * Include complete task validation checklist with table format + * Task | Marked As | Verified As | Evidence + * **Highlight falsely marked complete tasks prominently** + * Summary: X of Y tasks verified, Z questionable, W false completions + - Test Coverage and Gaps + - Architectural Alignment + - Security Notes + - Best-Practices and References (with links) + - Action Items: + * CRITICAL: Format with checkboxes for tracking resolution + * Code changes required: `- [ ] [Severity] Description [file: path:line]` + * Advisory notes: `- Note: Description (no action required)` + * Group by type: "Code Changes Required" and "Advisory Notes" + + Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended". + If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged. + Save the story file. + + MUST include the complete validation checklists - this is the evidence that systematic review was performed + + + + + + Skip sprint status update (no story context) + 📋 Ad-hoc review complete - no sprint status to update + + + + Determine target status based on review outcome: + - If {{outcome}} == "Approve" → target_status = "done" + - If {{outcome}} == "Changes Requested" → target_status = "in-progress" + - If {{outcome}} == "Blocked" → target_status = "review" (stay in review) + + + Load the FULL file: {{output_folder}}/sprint-status.yaml + Read all development_status entries to find {{story_key}} + Verify current status is "review" (expected previous state) + Update development_status[{{story_key}}] = {{target_status}} + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ✅ Sprint status updated: review → {{target_status}} + + + + ⚠️ Could not update sprint-status: {{story_key}} not found + +Review was saved to story file, but sprint-status.yaml may be out of sync. + + + + + + + + All action items are included in the standalone review report + Would you like me to create tracking items for these action items? (backlog/tasks) + + If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location. + Append a row per action item with Date={{date}}, Story="Ad-Hoc Review", Epic="N/A", Type, Severity, Owner (or "TBD"), Status="Open", Notes with file refs and context. + + + + + Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references. + Add {{action_item_count}} follow-up items to story Tasks/Subtasks? + + Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)". + + + If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location. + Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs. + + + If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}. + + Save modified files. + Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes). + + + + + Run validation checklist at {installed_path}/checklist.md using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml + Report workflow completion. + + + **✅ Ad-Hoc Code Review Complete, {user_name}!** + +**Review Details:** +- Files Reviewed: {{review_files}} +- Review Focus: {{review_focus}} +- Review Outcome: {{outcome}} +- Action Items: {{action_item_count}} +- Review Report: {{output_folder}}/code-review-{{date}}.md + +**Next Steps:** +1. Review the detailed findings in the review report +2. If changes requested: Address action items in the code +3. If blocked: Resolve blockers before proceeding +4. Re-run review on updated code if needed + + + + + **✅ Story Review Complete, {user_name}!** + +**Story Details:** +- Story: {{epic_num}}.{{story_num}} +- Story Key: {{story_key}} +- Review Outcome: {{outcome}} +- Sprint Status: {{target_status}} +- Action Items: {{action_item_count}} + +**Next Steps:** +1. Review the Senior Developer Review notes appended to story +2. If approved: Story is marked done, continue with next story +3. If changes requested: Address action items and re-run `dev-story` +4. If blocked: Resolve blockers before proceeding + + + + + +```` diff --git a/src/modules/bmgd/workflows/4-production/code-review/workflow.yaml b/src/modules/bmgd/workflows/4-production/code-review/workflow.yaml new file mode 100644 index 00000000..bf7a6cc6 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/code-review/workflow.yaml @@ -0,0 +1,57 @@ +# Review Story Workflow +name: code-review +description: "Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/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" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" +template: false + +variables: + story_dir: "{sprint_artifacts}" + tech_spec_search_dir: "{output_folder}" + tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md" + arch_docs_search_dirs: | + - "{output_folder}" + arch_docs_file_names: | + - architecture.md + backlog_file: "{output_folder}/backlog.md" + update_epic_followups: true + epic_followups_section_title: "Post-Review Follow-ups" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review +input_file_patterns: + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" + +standalone: true +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/correct-course/checklist.md b/src/modules/bmgd/workflows/4-production/correct-course/checklist.md new file mode 100644 index 00000000..1cbe1bf0 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/correct-course/checklist.md @@ -0,0 +1,279 @@ +# Change Navigation Checklist + +This checklist is executed as part of: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml +Work through each section systematically with the user, recording findings and impacts + + + +
+ + +Identify the triggering story that revealed this issue +Document story ID and brief description +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Define the core problem precisely +Categorize issue type: + - Technical limitation discovered during implementation + - New requirement emerged from stakeholders + - Misunderstanding of original requirements + - Strategic pivot or market change + - Failed approach requiring different solution +Write clear problem statement +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Assess initial impact and gather supporting evidence +Collect concrete examples, error messages, stakeholder feedback, or technical constraints +Document evidence for later reference +[ ] Done / [ ] N/A / [ ] Action-needed + + + +HALT: "Cannot proceed without understanding what caused the need for change" +HALT: "Need concrete evidence or examples of the issue before analyzing impact" + + +
+ +
+ + +Evaluate current epic containing the trigger story +Can this epic still be completed as originally planned? +If no, what modifications are needed? +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Determine required epic-level changes +Check each scenario: + - Modify existing epic scope or acceptance criteria + - Add new epic to address the issue + - Remove or defer epic that's no longer viable + - Completely redefine epic based on new understanding +Document specific epic changes needed +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Review all remaining planned epics for required changes +Check each future epic for impact +Identify dependencies that may be affected +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Check if issue invalidates future epics or necessitates new ones +Does this change make any planned epics obsolete? +Are new epics needed to address gaps created by this change? +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Consider if epic order or priority should change +Should epics be resequenced based on this issue? +Do priorities need adjustment? +[ ] Done / [ ] N/A / [ ] Action-needed + + +
+ +
+ + +Check PRD for conflicts +Does issue conflict with core PRD goals or objectives? +Do requirements need modification, addition, or removal? +Is the defined MVP still achievable or does scope need adjustment? +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Review Architecture document for conflicts +Check each area for impact: + - System components and their interactions + - Architectural patterns and design decisions + - Technology stack choices + - Data models and schemas + - API designs and contracts + - Integration points +Document specific architecture sections requiring updates +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Examine UI/UX specifications for conflicts +Check for impact on: + - User interface components + - User flows and journeys + - Wireframes or mockups + - Interaction patterns + - Accessibility considerations +Note specific UI/UX sections needing revision +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Consider impact on other artifacts +Review additional artifacts for impact: + - Deployment scripts + - Infrastructure as Code (IaC) + - Monitoring and observability setup + - Testing strategies + - Documentation + - CI/CD pipelines +Document any secondary artifacts requiring updates +[ ] Done / [ ] N/A / [ ] Action-needed + + +
+ +
+ + +Evaluate Option 1: Direct Adjustment +Can the issue be addressed by modifying existing stories? +Can new stories be added within the current epic structure? +Would this approach maintain project timeline and scope? +Effort estimate: [High/Medium/Low] +Risk level: [High/Medium/Low] +[ ] Viable / [ ] Not viable + + + +Evaluate Option 2: Potential Rollback +Would reverting recently completed stories simplify addressing this issue? +Which stories would need to be rolled back? +Is the rollback effort justified by the simplification gained? +Effort estimate: [High/Medium/Low] +Risk level: [High/Medium/Low] +[ ] Viable / [ ] Not viable + + + +Evaluate Option 3: PRD MVP Review +Is the original PRD MVP still achievable with this issue? +Does MVP scope need to be reduced or redefined? +Do core goals need modification based on new constraints? +What would be deferred to post-MVP if scope is reduced? +Effort estimate: [High/Medium/Low] +Risk level: [High/Medium/Low] +[ ] Viable / [ ] Not viable + + + +Select recommended path forward +Based on analysis of all options, choose the best path +Provide clear rationale considering: + - Implementation effort and timeline impact + - Technical risk and complexity + - Impact on team morale and momentum + - Long-term sustainability and maintainability + - Stakeholder expectations and business value +Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid] +Justification: [Document reasoning] +[ ] Done / [ ] N/A / [ ] Action-needed + + +
+ +
+ + +Create identified issue summary +Write clear, concise problem statement +Include context about discovery and impact +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Document epic impact and artifact adjustment needs +Summarize findings from Epic Impact Assessment (Section 2) +Summarize findings from Artifact Conflict Analysis (Section 3) +Be specific about what changes are needed and why +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Present recommended path forward with rationale +Include selected approach from Section 4 +Provide complete justification for recommendation +Address trade-offs and alternatives considered +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Define PRD MVP impact and high-level action plan +State clearly if MVP is affected +Outline major action items needed for implementation +Identify dependencies and sequencing +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Establish agent handoff plan +Identify which roles/agents will execute the changes: + - Development team (for implementation) + - Product Owner / Scrum Master (for backlog changes) + - Product Manager / Architect (for strategic changes) +Define responsibilities for each role +[ ] Done / [ ] N/A / [ ] Action-needed + + +
+ +
+ + +Review checklist completion +Verify all applicable sections have been addressed +Confirm all [Action-needed] items have been documented +Ensure analysis is comprehensive and actionable +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Verify Sprint Change Proposal accuracy +Review complete proposal for consistency and clarity +Ensure all recommendations are well-supported by analysis +Check that proposal is actionable and specific +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Obtain explicit user approval +Present complete proposal to user +Get clear yes/no approval for proceeding +Document approval and any conditions +[ ] Done / [ ] N/A / [ ] Action-needed + + + +Confirm next steps and handoff plan +Review handoff responsibilities with user +Ensure all stakeholders understand their roles +Confirm timeline and success criteria +[ ] Done / [ ] N/A / [ ] Action-needed + + + +HALT: "Cannot proceed to proposal without complete impact analysis" +HALT: "Must have explicit approval before implementing changes" +HALT: "Must clearly define who will execute the proposed changes" + + +
+ + + + +This checklist is for SIGNIFICANT changes affecting project direction +Work interactively with user - they make final decisions +Be factual, not blame-oriented when analyzing issues +Handle changes professionally as opportunities to improve the project +Maintain conversation context throughout - this is collaborative work + diff --git a/src/modules/bmgd/workflows/4-production/correct-course/instructions.md b/src/modules/bmgd/workflows/4-production/correct-course/instructions.md new file mode 100644 index 00000000..2adbb321 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/correct-course/instructions.md @@ -0,0 +1,206 @@ +# Correct Course - Sprint Change Management Instructions + +The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml +Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} +Generate all documents in {document_output_language} + +DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates. + + + + + Confirm change trigger and gather user description of the issue + Ask: "What specific issue or change has been identified that requires navigation?" + Verify access to required project documents: + - PRD (Product Requirements Document) + - Current Epics and Stories + - Architecture documentation + - UI/UX specifications + Ask user for mode preference: + - **Incremental** (recommended): Refine each edit collaboratively + - **Batch**: Present all changes at once for review + Store mode selection for use throughout workflow + +HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why." + +HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." + + + + + After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content} + + + + Load and execute the systematic analysis from: {checklist} + Work through each checklist section interactively with the user + Record status for each checklist item: + - [x] Done - Item completed successfully + - [N/A] Skip - Item not applicable to this change + - [!] Action-needed - Item requires attention or follow-up + Maintain running notes of findings and impacts discovered + Present checklist progress after each major section + +Identify blocking issues and work with user to resolve before continuing + + + +Based on checklist findings, create explicit edit proposals for each identified artifact + +For Story changes: + +- Show old → new text format +- Include story ID and section being modified +- Provide rationale for each change +- Example format: + + ``` + Story: [STORY-123] User Authentication + Section: Acceptance Criteria + + OLD: + - User can log in with email/password + + NEW: + - User can log in with email/password + - User can enable 2FA via authenticator app + + Rationale: Security requirement identified during implementation + ``` + +For PRD modifications: + +- Specify exact sections to update +- Show current content and proposed changes +- Explain impact on MVP scope and requirements + +For Architecture changes: + +- Identify affected components, patterns, or technology choices +- Describe diagram updates needed +- Note any ripple effects on other components + +For UI/UX specification updates: + +- Reference specific screens or components +- Show wireframe or flow changes needed +- Connect changes to user experience impact + + + Present each edit proposal individually + Review and refine this change? Options: Approve [a], Edit [e], Skip [s] + Iterate on each proposal based on user feedback + + +Collect all edit proposals and present together at end of step + + + + +Compile comprehensive Sprint Change Proposal document with following sections: + +Section 1: Issue Summary + +- Clear problem statement describing what triggered the change +- Context about when/how the issue was discovered +- Evidence or examples demonstrating the issue + +Section 2: Impact Analysis + +- Epic Impact: Which epics are affected and how +- Story Impact: Current and future stories requiring changes +- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates +- Technical Impact: Code, infrastructure, or deployment implications + +Section 3: Recommended Approach + +- Present chosen path forward from checklist evaluation: + - Direct Adjustment: Modify/add stories within existing plan + - Potential Rollback: Revert completed work to simplify resolution + - MVP Review: Reduce scope or modify goals +- Provide clear rationale for recommendation +- Include effort estimate, risk assessment, and timeline impact + +Section 4: Detailed Change Proposals + +- Include all refined edit proposals from Step 3 +- Group by artifact type (Stories, PRD, Architecture, UI/UX) +- Ensure each change includes before/after and justification + +Section 5: Implementation Handoff + +- Categorize change scope: + - Minor: Direct implementation by dev team + - Moderate: Backlog reorganization needed (PO/SM) + - Major: Fundamental replan required (PM/Architect) +- Specify handoff recipients and their responsibilities +- Define success criteria for implementation + +Present complete Sprint Change Proposal to user +Write Sprint Change Proposal document to {default_output_file} +Review complete proposal. Continue [c] or Edit [e]? + + + +Get explicit user approval for complete proposal +Do you approve this Sprint Change Proposal for implementation? (yes/no/revise) + + + Gather specific feedback on what needs adjustment + Return to appropriate step to address concerns + If changes needed to edit proposals + If changes needed to overall proposal structure + + + + + Finalize Sprint Change Proposal document + Determine change scope classification: + +- **Minor**: Can be implemented directly by development team +- **Moderate**: Requires backlog reorganization and PO/SM coordination +- **Major**: Needs fundamental replan with PM/Architect involvement + +Provide appropriate handoff based on scope: + + + + + Route to: Development team for direct implementation + Deliverables: Finalized edit proposals and implementation tasks + + + + Route to: Product Owner / Scrum Master agents + Deliverables: Sprint Change Proposal + backlog reorganization plan + + + + Route to: Product Manager / Solution Architect + Deliverables: Complete Sprint Change Proposal + escalation notice + +Confirm handoff completion and next steps with user +Document handoff in workflow execution log + + + + + +Summarize workflow execution: + - Issue addressed: {{change_trigger}} + - Change scope: {{scope_classification}} + - Artifacts modified: {{list_of_artifacts}} + - Routed to: {{handoff_recipients}} + +Confirm all deliverables produced: + +- Sprint Change Proposal document +- Specific edit proposals with before/after +- Implementation handoff plan + +Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!" +Remind user of success criteria and next steps for implementation team + + + diff --git a/src/modules/bmgd/workflows/4-production/correct-course/workflow.yaml b/src/modules/bmgd/workflows/4-production/correct-course/workflow.yaml new file mode 100644 index 00000000..723caa5c --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/correct-course/workflow.yaml @@ -0,0 +1,52 @@ +# Correct Course - Sprint Change Management Workflow +name: "correct-course" +description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation" +author: "BMad Method" + +config_source: "{project-root}/{bmad_folder}/bmgd/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" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: Load project context for impact analysis +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/*.md" + load_strategy: "FULL_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec*.md" + load_strategy: "FULL_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" + +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course" +template: false +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" +checklist: "{installed_path}/checklist.md" +default_output_file: "{output_folder}/sprint-change-proposal-{date}.md" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/create-story/checklist.md b/src/modules/bmgd/workflows/4-production/create-story/checklist.md new file mode 100644 index 00000000..6d9f1460 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/create-story/checklist.md @@ -0,0 +1,240 @@ +# Create Story Quality Validation Checklist + +```xml +This validation runs in a FRESH CONTEXT by an independent validator agent +The validator audits story quality and offers to improve if issues are found +Load only the story file and necessary source documents - do NOT load workflow instructions + + + + +**What create-story workflow should have accomplished:** + +1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items +2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md) +3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented +4. **Dev Notes Quality:** Specific guidance with citations, not generic advice +5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present +6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized + + +## Validation Steps + +### 1. Load Story and Extract Metadata +- [ ] Load story file: {{story_file_path}} +- [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log +- [ ] Extract: epic_num, story_num, story_key, story_title +- [ ] Initialize issue tracker (Critical/Major/Minor) + +### 2. Previous Story Continuity Check + +**Find previous story:** +- [ ] Load {output_folder}/sprint-status.yaml +- [ ] Find current {{story_key}} in development_status +- [ ] Identify story entry immediately above (previous story) +- [ ] Check previous story status + +**If previous story status is done/review/in-progress:** +- [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md +- [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED) +- [ ] Extract: Senior Developer Review section if present +- [ ] Count unchecked [ ] items in Review Action Items +- [ ] Count unchecked [ ] items in Review Follow-ups (AI) + +**Validate current story captured continuity:** +- [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes + - If MISSING and previous story has content → **CRITICAL ISSUE** +- [ ] If subsection exists, verify it includes: + - [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE** + - [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE** + - [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE** + - [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md] + +**If previous story status is backlog/drafted:** +- [ ] No continuity expected (note this) + +**If no previous story exists:** +- [ ] First story in epic, no continuity expected + +### 3. Source Document Coverage Check + +**Build available docs list:** +- [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir} +- [ ] Check exists: {output_folder}/epics.md +- [ ] Check exists: {output_folder}/PRD.md +- [ ] Check exists in {output_folder}/ or {project-root}/docs/: + - architecture.md, testing-strategy.md, coding-standards.md + - unified-project-structure.md, tech-stack.md + - backend-architecture.md, frontend-architecture.md, data-models.md + +**Validate story references available docs:** +- [ ] Extract all [Source: ...] citations from story Dev Notes +- [ ] Tech spec exists but not cited → **CRITICAL ISSUE** +- [ ] Epics exists but not cited → **CRITICAL ISSUE** +- [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE** +- [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE** +- [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE** +- [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE** +- [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE** + +**Validate citation quality:** +- [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE** +- [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE** + +### 4. Acceptance Criteria Quality Check + +- [ ] Extract Acceptance Criteria from story +- [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt) +- [ ] Check story indicates AC source (tech spec, epics, PRD) + +**If tech spec exists:** +- [ ] Load tech spec +- [ ] Search for this story number +- [ ] Extract tech spec ACs for this story +- [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE** + +**If no tech spec but epics.md exists:** +- [ ] Load epics.md +- [ ] Search for Epic {{epic_num}}, Story {{story_num}} +- [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted) +- [ ] Extract epics ACs +- [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE** + +**Validate AC quality:** +- [ ] Each AC is testable (measurable outcome) +- [ ] Each AC is specific (not vague) +- [ ] Each AC is atomic (single concern) +- [ ] Vague ACs found → **MINOR ISSUE** + +### 5. Task-AC Mapping Check + +- [ ] Extract Tasks/Subtasks from story +- [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference + - [ ] AC has no tasks → **MAJOR ISSUE** +- [ ] For each task: Check if references an AC number + - [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE** +- [ ] Count tasks with testing subtasks + - [ ] Testing subtasks < ac_count → **MAJOR ISSUE** + +### 6. Dev Notes Quality Check + +**Check required subsections exist:** +- [ ] Architecture patterns and constraints +- [ ] References (with citations) +- [ ] Project Structure Notes (if unified-project-structure.md exists) +- [ ] Learnings from Previous Story (if previous story has content) +- [ ] Missing required subsections → **MAJOR ISSUE** + +**Validate content quality:** +- [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE** +- [ ] Count citations in References subsection + - [ ] No citations → **MAJOR ISSUE** + - [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE** +- [ ] Scan for suspicious specifics without citations: + - API endpoints, schema details, business rules, tech choices + - [ ] Likely invented details found → **MAJOR ISSUE** + +### 7. Story Structure Check + +- [ ] Status = "drafted" → If not → **MAJOR ISSUE** +- [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE** +- [ ] Dev Agent Record has required sections: + - Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List + - [ ] Missing sections → **MAJOR ISSUE** +- [ ] Change Log initialized → If missing → **MINOR ISSUE** +- [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE** + +### 8. Unresolved Review Items Alert + +**CRITICAL CHECK for incomplete review items from previous story:** + +- [ ] If previous story has "Senior Developer Review (AI)" section: + - [ ] Count unchecked [ ] items in "Action Items" + - [ ] Count unchecked [ ] items in "Review Follow-ups (AI)" + - [ ] If unchecked items > 0: + - [ ] Check current story "Learnings from Previous Story" mentions these + - [ ] If NOT mentioned → **CRITICAL ISSUE** with details: + - List all unchecked items with severity + - Note: "These may represent epic-wide concerns" + - Required: Add to Learnings section with note about pending items + +## Validation Report Generation + +**Calculate severity counts:** +- Critical: {{critical_count}} +- Major: {{major_count}} +- Minor: {{minor_count}} + +**Determine outcome:** +- Critical > 0 OR Major > 3 → **FAIL** +- Major ≤ 3 and Critical = 0 → **PASS with issues** +- All = 0 → **PASS** + +**Generate report:** +``` + +# Story Quality Validation Report + +Story: {{story_key}} - {{story_title}} +Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}}) + +## Critical Issues (Blockers) + +{{list_each_with_description_and_evidence}} + +## Major Issues (Should Fix) + +{{list_each_with_description_and_evidence}} + +## Minor Issues (Nice to Have) + +{{list_each_with_description}} + +## Successes + +{{list_what_was_done_well}} + +``` + +## User Alert and Remediation + +**If FAIL:** +- Show issues summary and top 3 issues +- Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is +- If option 1: Re-load source docs, regenerate affected sections, re-run validation + +**If PASS with issues:** +- Show issues list +- Ask: "Improve story? (y/n)" +- If yes: Enhance story with missing items + +**If PASS:** +- Confirm: All quality standards met +- List successes +- Ready for story-context generation + + +``` + +## Quick Reference + +**Validation runs in fresh context and checks:** + +1. ✅ Previous story continuity captured (files, notes, **unresolved review items**) +2. ✅ All relevant source docs discovered and cited +3. ✅ ACs match tech spec/epics exactly +4. ✅ Tasks cover all ACs with testing +5. ✅ Dev Notes have specific guidance with citations (not generic) +6. ✅ Structure and metadata complete + +**Severity Levels:** + +- **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics +- **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks +- **MINOR** = Vague citations, orphan tasks, missing Change Log + +**Outcome Triggers:** + +- **FAIL** = Any critical OR >3 major issues +- **PASS with issues** = ≤3 major issues, no critical +- **PASS** = All checks passed diff --git a/src/modules/bmgd/workflows/4-production/create-story/instructions.md b/src/modules/bmgd/workflows/4-production/create-story/instructions.md new file mode 100644 index 00000000..3105620c --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/create-story/instructions.md @@ -0,0 +1,256 @@ +# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default) + +````xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Generate all documents in {document_output_language} +This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context. +DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks. + + + + + Resolve variables from config_source: story_dir (sprint_artifacts), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable. + Create {{story_dir}} if it does not exist + Resolve installed component paths from workflow.yaml: template, instructions, validation + Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. + + + + + After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content}, {document_project_content} + + + + PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development + + Find the previous completed story to extract dev agent learnings and review findings: + 1. Load {{output_folder}}/sprint-status.yaml COMPLETELY + 2. Find current {{story_key}} in development_status section + 3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order) + 4. If previous story exists: + - Extract {{previous_story_key}} + - Check previous story status (done, in-progress, review, etc.) + - If status is "done", "review", or "in-progress" (has some completion): + * Construct path: {{story_dir}}/{{previous_story_key}}.md + * Load the COMPLETE previous story file + * Parse ALL sections comprehensively: + + A) Dev Agent Record → Completion Notes List: + - New patterns/services created (to reuse, not recreate) + - Architectural deviations or decisions made + - Technical debt deferred to future stories + - Warnings or recommendations for next story + - Interfaces/methods created for reuse + + B) Dev Agent Record → Debug Log References: + - Issues encountered and solutions + - Gotchas or unexpected challenges + - Workarounds applied + + C) Dev Agent Record → File List: + - Files created (NEW) - understand new capabilities + - Files modified (MODIFIED) - track evolving components + - Files deleted (DELETED) - removed functionality + + D) Dev Notes: + - Any "future story" notes or TODOs + - Patterns established + - Constraints discovered + + E) Senior Developer Review (AI) section (if present): + - Review outcome (Approve/Changes Requested/Blocked) + - Unresolved action items (unchecked [ ] items) + - Key findings that might affect this story + - Architectural concerns raised + + F) Senior Developer Review → Action Items (if present): + - Check for unchecked [ ] items still pending + - Note any systemic issues that apply to multiple stories + + G) Review Follow-ups (AI) tasks (if present): + - Check for unchecked [ ] review tasks still pending + - Determine if they're epic-wide concerns + + H) Story Status: + - If "review" or "in-progress" - incomplete, note what's pending + - If "done" - confirmed complete + * Store ALL findings as {{previous_story_learnings}} with structure: + - new_files: [list] + - modified_files: [list] + - new_services: [list with descriptions] + - architectural_decisions: [list] + - technical_debt: [list] + - warnings_for_next: [list] + - review_findings: [list if review exists] + - pending_items: [list of unchecked action items] + - If status is "backlog" or "drafted": + * Set {{previous_story_learnings}} = "Previous story not yet implemented" + 5. If no previous story exists (first story in epic): + - Set {{previous_story_learnings}} = "First story in epic - no predecessor context" + + + If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time. + Build a prioritized document set for this epic - search and load from {input_file_patterns} list of potential locations: + 1) tech_spec_file (epic-scoped) + 2) epics_file (acceptance criteria and breakdown) the specific epic the story will be part of + 3) prd_file (business requirements and constraints) whole or sharded + 4) architecture_file (architecture constraints) whole or sharded + + READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation. + + + + MUST read COMPLETE {sprint_status} file from start to end to preserve order + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely to understand story order + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "backlog" + + + + 📋 No backlog stories found in sprint-status.yaml + + All stories are either already drafted or completed. + + **Options:** + 1. Run sprint-planning to refresh story tracking + 2. Load PM agent and run correct-course to add more stories + 3. Check if current sprint is complete + + HALT + + + Extract from found story key (e.g., "1-2-user-authentication"): + - epic_num: first number before dash (e.g., "1") + - story_num: second number after first dash (e.g., "2") + - story_title: remainder after second dash (e.g., "user-authentication") + + Set {{story_id}} = "{{epic_num}}.{{story_num}}" + Store story_key for later use (e.g., "1-2-user-authentication") + + Verify story is enumerated in {{epics_file}}. If not found, HALT with message: + "Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story." + + Check if story file already exists at expected path in {{story_dir}} + + ℹ️ Story file already exists: {{story_file_path}} +Will update existing story file rather than creating new one. + + Set update_mode = true + + + + + From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story. + From architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story. + Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts. + requirements_context_summary + + + + Review {{previous_story_learnings}} and extract actionable intelligence: + - New patterns/services created → Note for reuse (DO NOT recreate) + - Architectural deviations → Understand and maintain consistency + - Technical debt items → Assess if this story should address them + - Files modified → Understand current state of evolving components + - Warnings/recommendations → Apply to this story's approach + - Review findings → Learn from issues found in previous story + - Pending action items → Determine if epic-wide concerns affect this story + + + If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts. + + Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located. + + structure_alignment_summary + + + + Assemble acceptance criteria list from tech_spec or epics. If gaps exist, derive minimal, testable criteria from PRD verbatim phrasing (NO invention). + Create tasks/subtasks directly mapped to ACs. Include explicit testing subtasks per testing-strategy and existing tests framework. Cite architecture/source documents for any technical mandates. + acceptance_criteria + tasks_subtasks + + + + Resolve output path: {default_output_file} using current {{epic_num}} and {{story_num}}. If targeting an existing story for update, use its path. + Initialize from template.md if creating a new file; otherwise load existing file for edit. + Compute a concise story_title from epic/story context; if missing, synthesize from PRD feature name and epic number. + story_header + story_body + dev_notes_with_citations + + If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"): + - Add "Learnings from Previous Story" subsection to Dev Notes + - Include relevant completion notes, new files/patterns, deviations + - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md] + - Highlight interfaces/services to REUSE (not recreate) + - Note any technical debt to address in this story + - List pending review items that affect this story (if any) + - Reference specific files created: "Use {{file_path}} for {{purpose}}" + - Format example: + ``` + ### Learnings from Previous Story + + **From Story {{previous_story_key}} (Status: {{previous_status}})** + + - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method + - **Architectural Change**: Switched from session-based to JWT authentication + - **Schema Changes**: User model now includes `passwordHash` field, migration applied + - **Technical Debt**: Email verification skipped, should be included in this or subsequent story + - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there + - **Pending Review Items**: Rate limiting mentioned in review - consider for this story + + [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record] + ``` + + + change_log + + + + Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml + Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation. + + + Update {{output_folder}}/sprint-status.yaml + Load the FULL file and read all development_status entries + Find development_status key matching {{story_key}} + Verify current status is "backlog" (expected previous state) + Update development_status[{{story_key}}] = "drafted" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml + +Story file was created successfully, but sprint-status.yaml was not updated. +You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`. + + + + Report created/updated story path + **✅ Story Created Successfully, {user_name}!** + +**Story Details:** + +- Story ID: {{story_id}} +- Story Key: {{story_key}} +- File: {{story_file}} +- Status: drafted (was backlog) + +**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command. + +**Next Steps:** + +1. Review the drafted story in {{story_file}} +2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step) +3. Or run `story-ready` to manually mark the story ready without generating technical context + + + + +```` diff --git a/src/modules/bmgd/workflows/4-production/create-story/template.md b/src/modules/bmgd/workflows/4-production/create-story/template.md new file mode 100644 index 00000000..6aa80bad --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/create-story/template.md @@ -0,0 +1,51 @@ +# Story {{epic_num}}.{{story_num}}: {{story_title}} + +Status: drafted + +## Story + +As a {{role}}, +I want {{action}}, +so that {{benefit}}. + +## Acceptance Criteria + +1. [Add acceptance criteria from epics/PRD] + +## Tasks / Subtasks + +- [ ] Task 1 (AC: #) + - [ ] Subtask 1.1 +- [ ] Task 2 (AC: #) + - [ ] Subtask 2.1 + +## Dev Notes + +- Relevant architecture patterns and constraints +- Source tree components to touch +- Testing standards summary + +### Project Structure Notes + +- Alignment with unified project structure (paths, modules, naming) +- Detected conflicts or variances (with rationale) + +### References + +- Cite all technical details with source paths and sections, e.g. [Source: docs/.md#Section] + +## Dev Agent Record + +### Context Reference + + + +### Agent Model Used + +{{agent_model_name_version}} + +### Debug Log References + +### Completion Notes List + +### File List diff --git a/src/modules/bmgd/workflows/4-production/create-story/workflow.yaml b/src/modules/bmgd/workflows/4-production/create-story/workflow.yaml new file mode 100644 index 00000000..ed62858b --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/create-story/workflow.yaml @@ -0,0 +1,68 @@ +name: create-story +description: "Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +story_dir: "{sprint_artifacts}" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story" +template: "{installed_path}/template.md" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Variables and inputs +variables: + sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking + epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown + prd_file: "{output_folder}/PRD.md" # Fallback for requirements + architecture_file: "{output_folder}/architecture.md" # Optional architecture context + tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md + tech_spec_search_dir: "{project-root}/docs" + tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md" + arch_docs_search_dirs: | + - "{project-root}/docs" + - "{output_folder}" + arch_docs_file_names: | + - *architecture*.md + story_title: "" # Will be elicited if not derivable + +default_output_file: "{story_dir}/{{story_key}}.md" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec.md" + load_strategy: "FULL_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/index.md" + load_strategy: "INDEX_GUIDED" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/dev-story/checklist.md b/src/modules/bmgd/workflows/4-production/dev-story/checklist.md new file mode 100644 index 00000000..9bfa982b --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/dev-story/checklist.md @@ -0,0 +1,38 @@ +--- +title: 'Dev Story Completion Checklist' +validation-target: 'Story markdown ({{story_path}})' +required-inputs: + - 'Story markdown file with Tasks/Subtasks, Acceptance Criteria' +optional-inputs: + - 'Test results output (if saved)' + - 'CI logs (if applicable)' +validation-rules: + - 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status' +--- + +# Dev Story Completion Checklist + +## Tasks Completion + +- [ ] All tasks and subtasks for this story are marked complete with [x] +- [ ] Implementation aligns with every Acceptance Criterion in the story + +## Tests and Quality + +- [ ] Unit tests added/updated for core functionality changed by this story +- [ ] Integration tests added/updated when component interactions are affected +- [ ] End-to-end tests created for critical user flows, if applicable +- [ ] All tests pass locally (no regressions introduced) +- [ ] Linting and static checks (if configured) pass + +## Story File Updates + +- [ ] File List section includes every new/modified/deleted file (paths relative to repo root) +- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work +- [ ] Change Log includes a brief summary of what changed +- [ ] Only permitted sections of the story file were modified + +## Final Status + +- [ ] Regression suite executed successfully +- [ ] Story Status is set to "Ready for Review" diff --git a/src/modules/bmgd/workflows/4-production/dev-story/instructions.md b/src/modules/bmgd/workflows/4-production/dev-story/instructions.md new file mode 100644 index 00000000..26b05ad9 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/dev-story/instructions.md @@ -0,0 +1,267 @@ +# Develop Story - Workflow Instructions + +```xml +The workflow execution engine is governed by: {project-root}/{bmad_folder}/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} +Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status +Execute ALL steps in exact order; do NOT skip steps +Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction. +Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion. + +User skill level ({user_skill_level}) affects conversation style ONLY, not code updates. + + + + + + Use {{story_path}} directly + Read COMPLETE story file + Extract story_key from filename or metadata + task_check + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {{output_folder}}/sprint-status.yaml + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely to understand story order + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "ready-for-dev" + + + + 📋 No ready-for-dev stories found in sprint-status.yaml +**Options:** +1. Run `story-context` to generate context file and mark drafted stories as ready +2. Run `story-ready` to quickly mark drafted stories as ready without generating context +3. Run `create-story` if no incomplete stories are drafted yet +4. Check {output_folder}/sprint-status.yaml to see current sprint status + + HALT + + + Store the found story_key (e.g., "1-2-user-authentication") for later status updates + Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md + Read COMPLETE story file from discovered path + + + + 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.xml + + Read COMPLETE context file + Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests + Use this context to inform implementation decisions and approaches + + + ℹ️ No context file found for {{story_key}} + +Proceeding with story file only. For better context, consider running `story-context` workflow first. + + + + Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks + + Completion sequence + HALT: "Cannot develop story without access to story file" + ASK user to clarify or HALT + + + + + After discovery, these content variables are available: {architecture_content}, {tech_spec_content}, {ux_design_content}, {epics_content} (selective load), {document_project_content} + + + + Determine if this is a fresh start or continuation after code review + + Check if "Senior Developer Review (AI)" section exists in the story file + Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks + + + Set review_continuation = true + Extract from "Senior Developer Review (AI)" section: + - Review outcome (Approve/Changes Requested/Blocked) + - Review date + - Total action items with checkboxes (count checked vs unchecked) + - Severity breakdown (High/Med/Low counts) + + Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection + Store list of unchecked review items as {{pending_review_items}} + + ⏯️ **Resuming Story After Code Review** ({{review_date}}) + +**Review Outcome:** {{review_outcome}} +**Action Items:** {{unchecked_review_count}} remaining to address +**Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low + +**Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks. + + + + + Set review_continuation = false + Set {{pending_review_items}} = empty + + 🚀 **Starting Fresh Implementation** + +Story: {{story_key}} +Context file: {{context_available}} +First incomplete task: {{first_task_description}} + + + + + + Load the FULL file: {{output_folder}}/sprint-status.yaml + Read all development_status entries to find {{story_key}} + Get current status value for development_status[{{story_key}}] + + + Update the story in the sprint status report to = "in-progress" + 🚀 Starting work on story {{story_key}} +Status updated: ready-for-dev → in-progress + + + + + ⏯️ Resuming work on story {{story_key}} +Story is already marked in-progress + + + + + ⚠️ Unexpected story status: {{current_status}} +Expected ready-for-dev or in-progress. Continuing anyway... + + + + + + Review acceptance criteria and dev notes for the selected task + Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log + Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions + Handle error conditions and edge cases appropriately + 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 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 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 + + + + Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided) + Run all existing tests to ensure no regressions + Run the new tests to verify implementation correctness + Run linting and code quality checks if configured + Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete + STOP and fix before continuing, consider how current changes made broke regression + STOP and fix before continuing + + + + If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section + + Check if completed task has [AI-Review] prefix (indicates review follow-up task) + + + Extract review item details (severity, description, related AC/file) + Add to resolution tracking list: {{resolved_review_items}} + + + Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section + + + Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description + Mark that action item checkbox [x] as resolved + + Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}" + + + ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds + Update File List section with any new, modified, or deleted files (paths relative to repo root) + Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups) + + + Count total resolved review items in this session + Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" + + + Save the story file + Determine if more incomplete tasks remain + Next task + Completion + + + + Verify ALL tasks and subtasks are marked [x] (re-scan the story document now) + Run the full regression suite (do not skip) + Confirm File List includes every changed file + Execute story definition-of-done checklist, if the story includes one + Update the story Status to: review + + + Load the FULL file: {{output_folder}}/sprint-status.yaml + Find development_status key matching {{story_key}} + Verify current status is "in-progress" (expected previous state) + Update development_status[{{story_key}}] = "review" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found + +Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync. + + + + Return to step 1 to complete remaining work (Do NOT finish with partial progress) + STOP and resolve before completing + Update it before completing + + + + Optionally run the workflow validation task against the story using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml + Prepare a concise summary in Dev Agent Record → Completion Notes + + Communicate to {user_name} that story implementation is complete and ready for review + Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified + Provide the story file path and current status (now "review", was "in-progress") + + Based on {user_skill_level}, ask if user needs any explanations about: + - What was implemented and how it works + - Why certain technical decisions were made + - How to test or verify the changes + - Any patterns, libraries, or approaches used + - Anything else they'd like clarified + + + + Provide clear, contextual explanations tailored to {user_skill_level} + Use examples and references to specific code when helpful + + + Once explanations are complete (or user indicates no questions), suggest logical next steps + Common next steps to suggest (but allow user flexibility): + - Review the implemented story yourself and test the changes + - Verify all acceptance criteria are met + - Ensure deployment readiness if applicable + - Run `code-review` workflow for peer review + - Check sprint-status.yaml to see project progress + + Remain flexible - allow user to choose their own path or ask for other assistance + + + +``` diff --git a/src/modules/bmgd/workflows/4-production/dev-story/workflow.yaml b/src/modules/bmgd/workflows/4-production/dev-story/workflow.yaml new file mode 100644 index 00000000..9f6e6537 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/dev-story/workflow.yaml @@ -0,0 +1,53 @@ +name: dev-story +description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/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}:sprint_artifacts" +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.xml") +context_file: "{story_dir}/{{story_key}}.context.xml" +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: Load necessary context for story implementation +input_file_patterns: + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec*.md" + sharded: "{sprint_artifacts}/tech-spec-epic-*.md" + load_strategy: "SELECTIVE_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/epic-tech-context/checklist.md b/src/modules/bmgd/workflows/4-production/epic-tech-context/checklist.md new file mode 100644 index 00000000..346d8dbe --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/epic-tech-context/checklist.md @@ -0,0 +1,17 @@ +# Tech Spec Validation Checklist + +```xml + + Overview clearly ties to PRD goals + Scope explicitly lists in-scope and out-of-scope + Design lists all services/modules with responsibilities + Data models include entities, fields, and relationships + APIs/interfaces are specified with methods and schemas + NFRs: performance, security, reliability, observability addressed + Dependencies/integrations enumerated with versions where known + Acceptance criteria are atomic and testable + Traceability maps AC → Spec → Components → Tests + Risks/assumptions/questions listed with mitigation/next steps + Test strategy covers all ACs and critical paths + +``` diff --git a/src/modules/bmgd/workflows/4-production/epic-tech-context/instructions.md b/src/modules/bmgd/workflows/4-production/epic-tech-context/instructions.md new file mode 100644 index 00000000..12857011 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/epic-tech-context/instructions.md @@ -0,0 +1,164 @@ + + +```xml +The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} +This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping. +If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed. + + + + Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths. + ask the user for file paths. HALT and wait for docs to proceed + + + MUST read COMPLETE {sprint-status} file to discover next epic + Read ALL development_status entries + Find all epics with status "backlog" (not yet contexted) + Identify the FIRST backlog epic as the suggested default + + + 📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}} + Use this epic? +- [y] Yes, use {{suggested_epic_id}} +- [n] No, let me specify a different epic_id + + + + Enter the epic_id you want to context + Store user-provided epic_id as {{epic_id}} + + + + Use {{suggested_epic_id}} as {{epic_id}} + + + + + ✅ All epics are already contexted! + +No epics with status "backlog" found in sprint-status.yaml. + + Do you want to re-context an existing epic? Enter epic_id or [q] to quit: + + + Store as {{epic_id}} + + + + HALT - No work needed + + + + Resolve output file path using workflow variables and initialize by writing the template. + + + + + After discovery, these content variables are available: {prd_content}, {gdd_content}, {architecture_content}, {ux_design_content}, {epics_content} (will load only epic-{{epic_id}}.md if sharded), {document_project_content} + Extract {{epic_title}} from {prd_content} or {epics_content} based on {{epic_id}}. + + + + Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1) + Get current status value if epic exists + + + ⚠️ Epic {{epic_id}} not found in sprint-status.yaml + +This epic hasn't been registered in the sprint plan yet. +Run sprint-planning workflow to initialize epic tracking. + + HALT + + + + ℹ️ Epic {{epic_id}} already marked as contexted + +Continuing to regenerate tech spec... + + + + + + Read COMPLETE found {recommended_inputs}. + + Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals + Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets + Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints) + + + + + Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate. + + Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners + Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available + Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes) + Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow) + + + + + + Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture + Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections + Replace {{nfr_reliability}} with availability, recovery, and degradation behavior + Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals + + + + + Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json). + + Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known + + + + + Extract acceptance criteria from PRD; normalize into atomic, testable statements. + + Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria + Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea + + + + + + Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step + Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases) + + + + + Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml + + + Load the FULL file: {sprint_status} + Find development_status key "epic-{{epic_id}}" + Verify current status is "backlog" (expected previous state) + Update development_status["epic-{{epic_id}}"] = "contexted" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Could not update epic status: epic-{{epic_id}} not found + + + **✅ Tech Spec Generated Successfully, {user_name}!** + +**Epic Details:** +- Epic ID: {{epic_id}} +- Epic Title: {{epic_title}} +- Tech Spec File: {{default_output_file}} +- Epic Status: contexted (was backlog) + +**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed. + +**Next Steps:** +1. Load SM agent and run `create-story` to begin implementing the first story under this epic. + + + + +``` diff --git a/src/modules/bmgd/workflows/4-production/epic-tech-context/template.md b/src/modules/bmgd/workflows/4-production/epic-tech-context/template.md new file mode 100644 index 00000000..dfffc203 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/epic-tech-context/template.md @@ -0,0 +1,76 @@ +# Epic Technical Specification: {{epic_title}} + +Date: {{date}} +Author: {{user_name}} +Epic ID: {{epic_id}} +Status: Draft + +--- + +## Overview + +{{overview}} + +## Objectives and Scope + +{{objectives_scope}} + +## System Architecture Alignment + +{{system_arch_alignment}} + +## Detailed Design + +### Services and Modules + +{{services_modules}} + +### Data Models and Contracts + +{{data_models}} + +### APIs and Interfaces + +{{apis_interfaces}} + +### Workflows and Sequencing + +{{workflows_sequencing}} + +## Non-Functional Requirements + +### Performance + +{{nfr_performance}} + +### Security + +{{nfr_security}} + +### Reliability/Availability + +{{nfr_reliability}} + +### Observability + +{{nfr_observability}} + +## Dependencies and Integrations + +{{dependencies_integrations}} + +## Acceptance Criteria (Authoritative) + +{{acceptance_criteria}} + +## Traceability Mapping + +{{traceability_mapping}} + +## Risks, Assumptions, Open Questions + +{{risks_assumptions_questions}} + +## Test Strategy Summary + +{{test_strategy}} diff --git a/src/modules/bmgd/workflows/4-production/epic-tech-context/workflow.yaml b/src/modules/bmgd/workflows/4-production/epic-tech-context/workflow.yaml new file mode 100644 index 00000000..6fd56b16 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/epic-tech-context/workflow.yaml @@ -0,0 +1,52 @@ +name: epic-tech-context +description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping" +author: "BMAD BMM" + +# Critical variables +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed (epic_num from context) +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + gdd: + whole: "{output_folder}/*gdd*.md" + sharded: "{output_folder}/*gdd*/*.md" + load_strategy: "FULL_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/index.md" + load_strategy: "INDEX_GUIDED" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/epic-tech-context" +template: "{installed_path}/template.md" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Output configuration +default_output_file: "{sprint_artifacts}/tech-spec-epic-{{epic_id}}.md" +standalone: true +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/retrospective/instructions.md b/src/modules/bmgd/workflows/4-production/retrospective/instructions.md new file mode 100644 index 00000000..b85f44f3 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/retrospective/instructions.md @@ -0,0 +1,1442 @@ +# Retrospective - Epic Completion Review Instructions + +The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective/workflow.yaml +Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} +Generate all documents in {document_output_language} + + + DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. + +FACILITATION NOTES: + +- Scrum Master facilitates this retrospective +- Psychological safety is paramount - NO BLAME +- Focus on systems, processes, and learning +- Everyone contributes with specific examples preferred +- Action items must be achievable with clear ownership +- Two-part format: (1) Epic Review + (2) Next Epic Preparation + +PARTY MODE PROTOCOL: + +- ALL agent dialogue MUST use format: "Name (Role): dialogue" +- Example: Bob (Scrum Master): "Let's begin..." +- Example: {user_name} (Project Lead): [User responds] +- Create natural back-and-forth with user actively participating +- Show disagreements, diverse perspectives, authentic team dynamics + + + + + + +Explain to {user_name} the epic discovery process using natural dialogue + + +Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today." + + +PRIORITY 1: Check {sprint_status_file} first + +Load the FULL file: {sprint_status_file} +Read ALL development_status entries +Find the highest epic number with at least one story marked "done" +Extract epic number from keys like "epic-X-retrospective" or story keys like "X-Y-story-name" +Set {{detected_epic}} = highest epic number found with completed stories + + + Present finding to user with context + + +Bob (Scrum Master): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?" + + +WAIT for {user_name} to confirm or correct + + + Set {{epic_number}} = {{detected_epic}} + + + + Set {{epic_number}} = user-provided number + +Bob (Scrum Master): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information." + + + + + + PRIORITY 2: Ask user directly + + +Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?" + + +WAIT for {user_name} to provide epic number +Set {{epic_number}} = user-provided number + + + + PRIORITY 3: Fallback to stories folder + +Scan {story_directory} for highest numbered story files +Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md) +Set {{detected_epic}} = highest epic number found + + +Bob (Scrum Master): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?" + + +WAIT for {user_name} to confirm or correct +Set {{epic_number}} = confirmed number + + +Once {{epic_number}} is determined, verify epic completion status + +Find all stories for epic {{epic_number}} in {sprint_status_file}: + +- Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.) +- Exclude epic key itself ("epic-{{epic_number}}") +- Exclude retrospective key ("epic-{{epic_number}}-retrospective") + + +Count total stories found for this epic +Count stories with status = "done" +Collect list of pending story keys (status != "done") +Determine if complete: true if all stories are done, false otherwise + + + +Alice (Product Owner): "Wait, Bob - I'm seeing that Epic {{epic_number}} isn't actually complete yet." + +Bob (Scrum Master): "Let me check... you're right, Alice." + +**Epic Status:** + +- Total Stories: {{total_stories}} +- Completed (Done): {{done_stories}} +- Pending: {{pending_count}} + +**Pending Stories:** +{{pending_story_list}} + +Bob (Scrum Master): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?" + +**Options:** + +1. Complete remaining stories before running retrospective (recommended) +2. Continue with partial retrospective (not ideal, but possible) +3. Run sprint-planning to refresh story tracking + + +Continue with incomplete epic? (yes/no) + + + +Bob (Scrum Master): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective." + + HALT + + +Set {{partial_retrospective}} = true + +Charlie (Senior Dev): "Just so everyone knows, this partial retro might miss some important lessons from those pending stories." + +Bob (Scrum Master): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done." + + + + + +Alice (Product Owner): "Excellent! All {{done_stories}} stories are marked done." + +Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}." + + + + + + + + After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content} + + + + + +Bob (Scrum Master): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation." + +Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." + + +For each story in epic {{epic_number}}, read the complete story file from {story_directory}/{{epic_number}}-{{story_num}}-\*.md + +Extract and analyze from each story: + +**Dev Notes and Struggles:** + +- Look for sections like "## Dev Notes", "## Implementation Notes", "## Challenges", "## Development Log" +- Identify where developers struggled or made mistakes +- Note unexpected complexity or gotchas discovered +- Record technical decisions that didn't work out as planned +- Track where estimates were way off (too high or too low) + +**Review Feedback Patterns:** + +- Look for "## Review", "## Code Review", "## SM Review", "## Scrum Master Review" sections +- Identify recurring feedback themes across stories +- Note which types of issues came up repeatedly +- Track quality concerns or architectural misalignments +- Document praise or exemplary work called out in reviews + +**Lessons Learned:** + +- Look for "## Lessons Learned", "## Retrospective Notes", "## Takeaways" sections within stories +- Extract explicit lessons documented during development +- Identify "aha moments" or breakthroughs +- Note what would be done differently +- Track successful experiments or approaches + +**Technical Debt Incurred:** + +- Look for "## Technical Debt", "## TODO", "## Known Issues", "## Future Work" sections +- Document shortcuts taken and why +- Track debt items that affect next epic +- Note severity and priority of debt items + +**Testing and Quality Insights:** + +- Look for "## Testing", "## QA Notes", "## Test Results" sections +- Note testing challenges or surprises +- Track bug patterns or regression issues +- Document test coverage gaps + +Synthesize patterns across all stories: + +**Common Struggles:** + +- Identify issues that appeared in 2+ stories (e.g., "3 out of 5 stories had API authentication issues") +- Note areas where team consistently struggled +- Track where complexity was underestimated + +**Recurring Review Feedback:** + +- Identify feedback themes (e.g., "Error handling was flagged in every review") +- Note quality patterns (positive and negative) +- Track areas where team improved over the course of epic + +**Breakthrough Moments:** + +- Document key discoveries (e.g., "Story 3 discovered the caching pattern we used for rest of epic") +- Note when team velocity improved dramatically +- Track innovative solutions worth repeating + +**Velocity Patterns:** + +- Calculate average completion time per story +- Note velocity trends (e.g., "First 2 stories took 3x longer than estimated") +- Identify which types of stories went faster/slower + +**Team Collaboration Highlights:** + +- Note moments of excellent collaboration mentioned in stories +- Track where pair programming or mob programming was effective +- Document effective problem-solving sessions + +Store this synthesis - these patterns will drive the retrospective discussion + + +Bob (Scrum Master): "Okay, I've reviewed all {{total_stories}} story records. I found some really interesting patterns we should discuss." + +Dana (QA Engineer): "I'm curious what you found, Bob. I noticed some things in my testing too." + +Bob (Scrum Master): "We'll get to all of it. But first, let me load the previous epic's retro to see if we learned from last time." + + + + + + +Calculate previous epic number: {{prev_epic_num}} = {{epic_number}} - 1 + + + Search for previous retrospective using pattern: {retrospectives_folder}/epic-{{prev_epic_num}}-retro-*.md + + + +Bob (Scrum Master): "I found our retrospective from Epic {{prev_epic_num}}. Let me see what we committed to back then..." + + + Read the complete previous retrospective file + + Extract key elements: + - **Action items committed**: What did the team agree to improve? + - **Lessons learned**: What insights were captured? + - **Process improvements**: What changes were agreed upon? + - **Technical debt flagged**: What debt was documented? + - **Team agreements**: What commitments were made? + - **Preparation tasks**: What was needed for this epic? + + Cross-reference with current epic execution: + + **Action Item Follow-Through:** + - For each action item from Epic {{prev_epic_num}} retro, check if it was completed + - Look for evidence in current epic's story records + - Mark each action item: ✅ Completed, ⏳ In Progress, ❌ Not Addressed + + **Lessons Applied:** + - For each lesson from Epic {{prev_epic_num}}, check if team applied it in Epic {{epic_number}} + - Look for evidence in dev notes, review feedback, or outcomes + - Document successes and missed opportunities + + **Process Improvements Effectiveness:** + - For each process change agreed to in Epic {{prev_epic_num}}, assess if it helped + - Did the change improve velocity, quality, or team satisfaction? + - Should we keep, modify, or abandon the change? + + **Technical Debt Status:** + - For each debt item from Epic {{prev_epic_num}}, check if it was addressed + - Did unaddressed debt cause problems in Epic {{epic_number}}? + - Did the debt grow or shrink? + + Prepare "continuity insights" for the retrospective discussion + + Identify wins where previous lessons were applied successfully: + - Document specific examples of applied learnings + - Note positive impact on Epic {{epic_number}} outcomes + - Celebrate team growth and improvement + + Identify missed opportunities where previous lessons were ignored: + - Document where team repeated previous mistakes + - Note impact of not applying lessons (without blame) + - Explore barriers that prevented application + + + +Bob (Scrum Master): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items." + +Alice (Product Owner): "How'd we do on those, Bob?" + +Bob (Scrum Master): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}." + +Charlie (Senior Dev): _looking concerned_ "Which ones didn't we address?" + +Bob (Scrum Master): "We'll discuss that in the retro. Some of them might explain challenges we had this epic." + +Elena (Junior Dev): "That's... actually pretty insightful." + +Bob (Scrum Master): "That's why we track this stuff. Pattern recognition helps us improve." + + + + + + +Bob (Scrum Master): "I don't see a retrospective for Epic {{prev_epic_num}}. Either we skipped it, or this is your first retro." + +Alice (Product Owner): "Probably our first one. Good time to start the habit!" + +Set {{first_retrospective}} = true + + + + + +Bob (Scrum Master): "This is Epic 1, so naturally there's no previous retro to reference. We're starting fresh!" + +Charlie (Senior Dev): "First epic, first retro. Let's make it count." + +Set {{first_retrospective}} = true + + + + + + +Calculate next epic number: {{next_epic_num}} = {{epic_number}} + 1 + + +Bob (Scrum Master): "Before we dive into the discussion, let me take a quick look at Epic {{next_epic_num}} to understand what's coming." + +Alice (Product Owner): "Good thinking - helps us connect what we learned to what we're about to do." + + +Attempt to load next epic using selective loading strategy: + +**Try sharded first (more specific):** +Check if file exists: {output_folder}/epic\*/epic-{{next_epic_num}}.md + + + Load {output_folder}/*epic*/epic-{{next_epic_num}}.md + Set {{next_epic_source}} = "sharded" + + +**Fallback to whole document:** + +Check if file exists: {output_folder}/epic\*.md + + + Load entire epics document + Extract Epic {{next_epic_num}} section + Set {{next_epic_source}} = "whole" + + + + + Analyze next epic for: + - Epic title and objectives + - Planned stories and complexity estimates + - Dependencies on Epic {{epic_number}} work + - New technical requirements or capabilities needed + - Potential risks or unknowns + - Business goals and success criteria + +Identify dependencies on completed work: + +- What components from Epic {{epic_number}} does Epic {{next_epic_num}} rely on? +- Are all prerequisites complete and stable? +- Any incomplete work that creates blocking dependencies? + +Note potential gaps or preparation needed: + +- Technical setup required (infrastructure, tools, libraries) +- Knowledge gaps to fill (research, training, spikes) +- Refactoring needed before starting next epic +- Documentation or specifications to create + +Check for technical prerequisites: + +- APIs or integrations that must be ready +- Data migrations or schema changes needed +- Testing infrastructure requirements +- Deployment or environment setup + + +Bob (Scrum Master): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'" + +Alice (Product Owner): "What are we looking at?" + +Bob (Scrum Master): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}." + +Charlie (Senior Dev): "Dependencies concern me. Did we finish everything we need for that?" + +Bob (Scrum Master): "Good question - that's exactly what we need to explore in this retro." + + +Set {{next_epic_exists}} = true + + + + +Bob (Scrum Master): "Hmm, I don't see Epic {{next_epic_num}} defined yet." + +Alice (Product Owner): "We might be at the end of the roadmap, or we haven't planned that far ahead yet." + +Bob (Scrum Master): "No problem. We'll still do a thorough retro on Epic {{epic_number}}. The lessons will be valuable whenever we plan the next work." + + +Set {{next_epic_exists}} = false + + + + + + +Load agent configurations from {agent_manifest} +Identify which agents participated in Epic {{epic_number}} based on story records +Ensure key roles present: Product Owner, Scrum Master (facilitating), Devs, Testing/QA, Architect + + +Bob (Scrum Master): "Alright team, everyone's here. Let me set the stage for our retrospective." + +═══════════════════════════════════════════════════════════ +🔄 TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}} +═══════════════════════════════════════════════════════════ + +Bob (Scrum Master): "Here's what we accomplished together." + +**EPIC {{epic_number}} SUMMARY:** + +Delivery Metrics: + +- Completed: {{completed_stories}}/{{total_stories}} stories ({{completion_percentage}}%) +- Velocity: {{actual_points}} story points{{#if planned_points}} (planned: {{planned_points}}){{/if}} +- Duration: {{actual_sprints}} sprints{{#if planned_sprints}} (planned: {{planned_sprints}}){{/if}} +- Average velocity: {{points_per_sprint}} points/sprint + +Quality and Technical: + +- Blockers encountered: {{blocker_count}} +- Technical debt items: {{debt_count}} +- Test coverage: {{coverage_info}} +- Production incidents: {{incident_count}} + +Business Outcomes: + +- Goals achieved: {{goals_met}}/{{total_goals}} +- Success criteria: {{criteria_status}} +- Stakeholder feedback: {{feedback_summary}} + +Alice (Product Owner): "Those numbers tell a good story. {{completion_percentage}}% completion is {{#if completion_percentage >= 90}}excellent{{else}}something we should discuss{{/if}}." + +Charlie (Senior Dev): "I'm more interested in that technical debt number - {{debt_count}} items is {{#if debt_count > 10}}concerning{{else}}manageable{{/if}}." + +Dana (QA Engineer): "{{incident_count}} production incidents - {{#if incident_count == 0}}clean epic!{{else}}we should talk about those{{/if}}." + +{{#if next_epic_exists}} +═══════════════════════════════════════════════════════════ +**NEXT EPIC PREVIEW:** Epic {{next_epic_num}}: {{next_epic_title}} +═══════════════════════════════════════════════════════════ + +Dependencies on Epic {{epic_number}}: +{{list_dependencies}} + +Preparation Needed: +{{list_preparation_gaps}} + +Technical Prerequisites: +{{list_technical_prereqs}} + +Bob (Scrum Master): "And here's what's coming next. Epic {{next_epic_num}} builds on what we just finished." + +Elena (Junior Dev): "Wow, that's a lot of dependencies on our work." + +Charlie (Senior Dev): "Which means we better make sure Epic {{epic_number}} is actually solid before moving on." +{{/if}} + +═══════════════════════════════════════════════════════════ + +Bob (Scrum Master): "Team assembled for this retrospective:" + +{{list_participating_agents}} + +Bob (Scrum Master): "{user_name}, you're joining us as Project Lead. Your perspective is crucial here." + +{user_name} (Project Lead): [Participating in the retrospective] + +Bob (Scrum Master): "Our focus today:" + +1. Learning from Epic {{epic_number}} execution + {{#if next_epic_exists}}2. Preparing for Epic {{next_epic_num}} success{{/if}} + +Bob (Scrum Master): "Ground rules: psychological safety first. No blame, no judgment. We focus on systems and processes, not individuals. Everyone's voice matters. Specific examples are better than generalizations." + +Alice (Product Owner): "And everything shared here stays in this room - unless we decide together to escalate something." + +Bob (Scrum Master): "Exactly. {user_name}, any questions before we dive in?" + + +WAIT for {user_name} to respond or indicate readiness + + + + + + +Bob (Scrum Master): "Let's start with the good stuff. What went well in Epic {{epic_number}}?" + +Bob (Scrum Master): _pauses, creating space_ + +Alice (Product Owner): "I'll start. The user authentication flow we delivered exceeded my expectations. The UX is smooth, and early user feedback has been really positive." + +Charlie (Senior Dev): "I'll add to that - the caching strategy we implemented in Story {{breakthrough_story_num}} was a game-changer. We cut API calls by 60% and it set the pattern for the rest of the epic." + +Dana (QA Engineer): "From my side, testing went smoother than usual. The dev team's documentation was way better this epic - actually usable test plans!" + +Elena (Junior Dev): _smiling_ "That's because Charlie made me document everything after Story 1's code review!" + +Charlie (Senior Dev): _laughing_ "Tough love pays off." + + +Bob (Scrum Master) naturally turns to {user_name} to engage them in the discussion + + +Bob (Scrum Master): "{user_name}, what stood out to you as going well in this epic?" + + +WAIT for {user_name} to respond - this is a KEY USER INTERACTION moment + +After {user_name} responds, have 1-2 team members react to or build on what {user_name} shared + + +Alice (Product Owner): [Responds naturally to what {user_name} said, either agreeing, adding context, or offering a different perspective] + +Charlie (Senior Dev): [Builds on the discussion, perhaps adding technical details or connecting to specific stories] + + +Continue facilitating natural dialogue, periodically bringing {user_name} back into the conversation + +After covering successes, guide the transition to challenges with care + + +Bob (Scrum Master): "Okay, we've celebrated some real wins. Now let's talk about challenges - where did we struggle? What slowed us down?" + +Bob (Scrum Master): _creates safe space with tone and pacing_ + +Elena (Junior Dev): _hesitates_ "Well... I really struggled with the database migrations in Story {{difficult_story_num}}. The documentation wasn't clear, and I had to redo it three times. Lost almost a full sprint on that story alone." + +Charlie (Senior Dev): _defensive_ "Hold on - I wrote those migration docs, and they were perfectly clear. The issue was that the requirements kept changing mid-story!" + +Alice (Product Owner): _frustrated_ "That's not fair, Charlie. We only clarified requirements once, and that was because the technical team didn't ask the right questions during planning!" + +Charlie (Senior Dev): _heat rising_ "We asked plenty of questions! You said the schema was finalized, then two days into development you wanted to add three new fields!" + +Bob (Scrum Master): _intervening calmly_ "Let's take a breath here. This is exactly the kind of thing we need to unpack." + +Bob (Scrum Master): "Elena, you spent almost a full sprint on Story {{difficult_story_num}}. Charlie, you're saying requirements changed. Alice, you feel the right questions weren't asked up front." + +Bob (Scrum Master): "{user_name}, you have visibility across the whole project. What's your take on this situation?" + + +WAIT for {user_name} to respond and help facilitate the conflict resolution + +Use {user_name}'s response to guide the discussion toward systemic understanding rather than blame + + +Bob (Scrum Master): [Synthesizes {user_name}'s input with what the team shared] "So it sounds like the core issue was {{root_cause_based_on_discussion}}, not any individual person's fault." + +Elena (Junior Dev): "That makes sense. If we'd had {{preventive_measure}}, I probably could have avoided those redos." + +Charlie (Senior Dev): _softening_ "Yeah, and I could have been clearer about assumptions in the docs. Sorry for getting defensive, Alice." + +Alice (Product Owner): "I appreciate that. I could've been more proactive about flagging the schema additions earlier, too." + +Bob (Scrum Master): "This is good. We're identifying systemic improvements, not assigning blame." + + +Continue the discussion, weaving in patterns discovered from the deep story analysis (Step 2) + + +Bob (Scrum Master): "Speaking of patterns, I noticed something when reviewing all the story records..." + +Bob (Scrum Master): "{{pattern_1_description}} - this showed up in {{pattern_1_count}} out of {{total_stories}} stories." + +Dana (QA Engineer): "Oh wow, I didn't realize it was that widespread." + +Bob (Scrum Master): "Yeah. And there's more - {{pattern_2_description}} came up in almost every code review." + +Charlie (Senior Dev): "That's... actually embarrassing. We should've caught that pattern earlier." + +Bob (Scrum Master): "No shame, Charlie. Now we know, and we can improve. {user_name}, did you notice these patterns during the epic?" + + +WAIT for {user_name} to share their observations + +Continue the retrospective discussion, creating moments where: + +- Team members ask {user_name} questions directly +- {user_name}'s input shifts the discussion direction +- Disagreements arise naturally and get resolved +- Quieter team members are invited to contribute +- Specific stories are referenced with real examples +- Emotions are authentic (frustration, pride, concern, hope) + + + +Bob (Scrum Master): "Before we move on, I want to circle back to Epic {{prev_epic_num}}'s retrospective." + +Bob (Scrum Master): "We made some commitments in that retro. Let's see how we did." + +Bob (Scrum Master): "Action item 1: {{prev_action_1}}. Status: {{prev_action_1_status}}" + +Alice (Product Owner): {{#if prev_action_1_status == "completed"}}"We nailed that one!"{{else}}"We... didn't do that one."{{/if}} + +Charlie (Senior Dev): {{#if prev_action_1_status == "completed"}}"And it helped! I noticed {{evidence_of_impact}}"{{else}}"Yeah, and I think that's why we had {{consequence_of_not_doing_it}} this epic."{{/if}} + +Bob (Scrum Master): "Action item 2: {{prev_action_2}}. Status: {{prev_action_2_status}}" + +Dana (QA Engineer): {{#if prev_action_2_status == "completed"}}"This one made testing so much easier this time."{{else}}"If we'd done this, I think testing would've gone faster."{{/if}} + +Bob (Scrum Master): "{user_name}, looking at what we committed to last time and what we actually did - what's your reaction?" + + +WAIT for {user_name} to respond + +Use the previous retro follow-through as a learning moment about commitment and accountability + + + +Bob (Scrum Master): "Alright, we've covered a lot of ground. Let me summarize what I'm hearing..." + +Bob (Scrum Master): "**Successes:**" +{{list_success_themes}} + +Bob (Scrum Master): "**Challenges:**" +{{list_challenge_themes}} + +Bob (Scrum Master): "**Key Insights:**" +{{list_insight_themes}} + +Bob (Scrum Master): "Does that capture it? Anyone have something important we missed?" + + +Allow team members to add any final thoughts on the epic review +Ensure {user_name} has opportunity to add their perspective + + + + + + + +Bob (Scrum Master): "Normally we'd discuss preparing for the next epic, but since Epic {{next_epic_num}} isn't defined yet, let's skip to action items." + + Skip to Step 8 + + + +Bob (Scrum Master): "Now let's shift gears. Epic {{next_epic_num}} is coming up: '{{next_epic_title}}'" + +Bob (Scrum Master): "The question is: are we ready? What do we need to prepare?" + +Alice (Product Owner): "From my perspective, we need to make sure {{dependency_concern_1}} from Epic {{epic_number}} is solid before we start building on it." + +Charlie (Senior Dev): _concerned_ "I'm worried about {{technical_concern_1}}. We have {{technical_debt_item}} from this epic that'll blow up if we don't address it before Epic {{next_epic_num}}." + +Dana (QA Engineer): "And I need {{testing_infrastructure_need}} in place, or we're going to have the same testing bottleneck we had in Story {{bottleneck_story_num}}." + +Elena (Junior Dev): "I'm less worried about infrastructure and more about knowledge. I don't understand {{knowledge_gap}} well enough to work on Epic {{next_epic_num}}'s stories." + +Bob (Scrum Master): "{user_name}, the team is surfacing some real concerns here. What's your sense of our readiness?" + + +WAIT for {user_name} to share their assessment + +Use {user_name}'s input to guide deeper exploration of preparation needs + + +Alice (Product Owner): [Reacts to what {user_name} said] "I agree with {user_name} about {{point_of_agreement}}, but I'm still worried about {{lingering_concern}}." + +Charlie (Senior Dev): "Here's what I think we need technically before Epic {{next_epic_num}} can start..." + +Charlie (Senior Dev): "1. {{tech_prep_item_1}} - estimated {{hours_1}} hours" +Charlie (Senior Dev): "2. {{tech_prep_item_2}} - estimated {{hours_2}} hours" +Charlie (Senior Dev): "3. {{tech_prep_item_3}} - estimated {{hours_3}} hours" + +Elena (Junior Dev): "That's like {{total_hours}} hours! That's a full sprint of prep work!" + +Charlie (Senior Dev): "Exactly. We can't just jump into Epic {{next_epic_num}} on Monday." + +Alice (Product Owner): _frustrated_ "But we have stakeholder pressure to keep shipping features. They're not going to be happy about a 'prep sprint.'" + +Bob (Scrum Master): "Let's think about this differently. What happens if we DON'T do this prep work?" + +Dana (QA Engineer): "We'll hit blockers in the middle of Epic {{next_epic_num}}, velocity will tank, and we'll ship late anyway." + +Charlie (Senior Dev): "Worse - we'll ship something built on top of {{technical_concern_1}}, and it'll be fragile." + +Bob (Scrum Master): "{user_name}, you're balancing stakeholder pressure against technical reality. How do you want to handle this?" + + +WAIT for {user_name} to provide direction on preparation approach + +Create space for debate and disagreement about priorities + + +Alice (Product Owner): [Potentially disagrees with {user_name}'s approach] "I hear what you're saying, {user_name}, but from a business perspective, {{business_concern}}." + +Charlie (Senior Dev): [Potentially supports or challenges Alice's point] "The business perspective is valid, but {{technical_counter_argument}}." + +Bob (Scrum Master): "We have healthy tension here between business needs and technical reality. That's good - it means we're being honest." + +Bob (Scrum Master): "Let's explore a middle ground. Charlie, which of your prep items are absolutely critical vs. nice-to-have?" + +Charlie (Senior Dev): "{{critical_prep_item_1}} and {{critical_prep_item_2}} are non-negotiable. {{nice_to_have_prep_item}} can wait." + +Alice (Product Owner): "And can any of the critical prep happen in parallel with starting Epic {{next_epic_num}}?" + +Charlie (Senior Dev): _thinking_ "Maybe. If we tackle {{first_critical_item}} before the epic starts, we could do {{second_critical_item}} during the first sprint." + +Dana (QA Engineer): "But that means Story 1 of Epic {{next_epic_num}} can't depend on {{second_critical_item}}." + +Alice (Product Owner): _looking at epic plan_ "Actually, Stories 1 and 2 are about {{independent_work}}, so they don't depend on it. We could make that work." + +Bob (Scrum Master): "{user_name}, the team is finding a workable compromise here. Does this approach make sense to you?" + + +WAIT for {user_name} to validate or adjust the preparation strategy + +Continue working through preparation needs across all dimensions: + +- Dependencies on Epic {{epic_number}} work +- Technical setup and infrastructure +- Knowledge gaps and research needs +- Documentation or specification work +- Testing infrastructure +- Refactoring or debt reduction +- External dependencies (APIs, integrations, etc.) + +For each preparation area, facilitate team discussion that: + +- Identifies specific needs with concrete examples +- Estimates effort realistically based on Epic {{epic_number}} experience +- Assigns ownership to specific agents +- Determines criticality and timing +- Surfaces risks of NOT doing the preparation +- Explores parallel work opportunities +- Brings {user_name} in for key decisions + + +Bob (Scrum Master): "I'm hearing a clear picture of what we need before Epic {{next_epic_num}}. Let me summarize..." + +**CRITICAL PREPARATION (Must complete before epic starts):** +{{list_critical_prep_items_with_owners_and_estimates}} + +**PARALLEL PREPARATION (Can happen during early stories):** +{{list_parallel_prep_items_with_owners_and_estimates}} + +**NICE-TO-HAVE PREPARATION (Would help but not blocking):** +{{list_nice_to_have_prep_items}} + +Bob (Scrum Master): "Total critical prep effort: {{critical_hours}} hours ({{critical_days}} days)" + +Alice (Product Owner): "That's manageable. We can communicate that to stakeholders." + +Bob (Scrum Master): "{user_name}, does this preparation plan work for you?" + + +WAIT for {user_name} final validation of preparation plan + + + + + + +Bob (Scrum Master): "Let's capture concrete action items from everything we've discussed." + +Bob (Scrum Master): "I want specific, achievable actions with clear owners. Not vague aspirations." + + +Synthesize themes from Epic {{epic_number}} review discussion into actionable improvements + +Create specific action items with: + +- Clear description of the action +- Assigned owner (specific agent or role) +- Timeline or deadline +- Success criteria (how we'll know it's done) +- Category (process, technical, documentation, team, etc.) + +Ensure action items are SMART: + +- Specific: Clear and unambiguous +- Measurable: Can verify completion +- Achievable: Realistic given constraints +- Relevant: Addresses real issues from retro +- Time-bound: Has clear deadline + + +Bob (Scrum Master): "Based on our discussion, here are the action items I'm proposing..." + +═══════════════════════════════════════════════════════════ +📝 EPIC {{epic_number}} ACTION ITEMS: +═══════════════════════════════════════════════════════════ + +**Process Improvements:** + +1. {{action_item_1}} + Owner: {{agent_1}} + Deadline: {{timeline_1}} + Success criteria: {{criteria_1}} + +2. {{action_item_2}} + Owner: {{agent_2}} + Deadline: {{timeline_2}} + Success criteria: {{criteria_2}} + +Charlie (Senior Dev): "I can own action item 1, but {{timeline_1}} is tight. Can we push it to {{alternative_timeline}}?" + +Bob (Scrum Master): "What do others think? Does that timing still work?" + +Alice (Product Owner): "{{alternative_timeline}} works for me, as long as it's done before Epic {{next_epic_num}} starts." + +Bob (Scrum Master): "Agreed. Updated to {{alternative_timeline}}." + +**Technical Debt:** + +1. {{debt_item_1}} + Owner: {{agent_3}} + Priority: {{priority_1}} + Estimated effort: {{effort_1}} + +2. {{debt_item_2}} + Owner: {{agent_4}} + Priority: {{priority_2}} + Estimated effort: {{effort_2}} + +Dana (QA Engineer): "For debt item 1, can we prioritize that as high? It caused testing issues in three different stories." + +Charlie (Senior Dev): "I marked it medium because {{reasoning}}, but I hear your point." + +Bob (Scrum Master): "{user_name}, this is a priority call. Testing impact vs. {{reasoning}} - how do you want to prioritize it?" + + +WAIT for {user_name} to help resolve priority discussions + + +**Documentation:** +1. {{doc_need_1}} + Owner: {{agent_5}} + Deadline: {{timeline_3}} + +2. {{doc_need_2}} + Owner: {{agent_6}} + Deadline: {{timeline_4}} + +**Team Agreements:** + +- {{agreement_1}} +- {{agreement_2}} +- {{agreement_3}} + +Bob (Scrum Master): "These agreements are how we're committing to work differently going forward." + +Elena (Junior Dev): "I like agreement 2 - that would've saved me on Story {{difficult_story_num}}." + +═══════════════════════════════════════════════════════════ +🚀 EPIC {{next_epic_num}} PREPARATION TASKS: +═══════════════════════════════════════════════════════════ + +**Technical Setup:** +[ ] {{setup_task_1}} +Owner: {{owner_1}} +Estimated: {{est_1}} + +[ ] {{setup_task_2}} +Owner: {{owner_2}} +Estimated: {{est_2}} + +**Knowledge Development:** +[ ] {{research_task_1}} +Owner: {{owner_3}} +Estimated: {{est_3}} + +**Cleanup/Refactoring:** +[ ] {{refactor_task_1}} +Owner: {{owner_4}} +Estimated: {{est_4}} + +**Total Estimated Effort:** {{total_hours}} hours ({{total_days}} days) + +═══════════════════════════════════════════════════════════ +⚠️ CRITICAL PATH: +═══════════════════════════════════════════════════════════ + +**Blockers to Resolve Before Epic {{next_epic_num}}:** + +1. {{critical_item_1}} + Owner: {{critical_owner_1}} + Must complete by: {{critical_deadline_1}} + +2. {{critical_item_2}} + Owner: {{critical_owner_2}} + Must complete by: {{critical_deadline_2}} + + +CRITICAL ANALYSIS - Detect if discoveries require epic updates + +Check if any of the following are true based on retrospective discussion: + +- Architectural assumptions from planning proven wrong during Epic {{epic_number}} +- Major scope changes or descoping occurred that affects next epic +- Technical approach needs fundamental change for Epic {{next_epic_num}} +- Dependencies discovered that Epic {{next_epic_num}} doesn't account for +- User needs significantly different than originally understood +- Performance/scalability concerns that affect Epic {{next_epic_num}} design +- Security or compliance issues discovered that change approach +- Integration assumptions proven incorrect +- Team capacity or skill gaps more severe than planned +- Technical debt level unsustainable without intervention + + + + +═══════════════════════════════════════════════════════════ +🚨 SIGNIFICANT DISCOVERY ALERT 🚨 +═══════════════════════════════════════════════════════════ + +Bob (Scrum Master): "{user_name}, we need to flag something important." + +Bob (Scrum Master): "During Epic {{epic_number}}, the team uncovered findings that may require updating the plan for Epic {{next_epic_num}}." + +**Significant Changes Identified:** + +1. {{significant_change_1}} + Impact: {{impact_description_1}} + +2. {{significant_change_2}} + Impact: {{impact_description_2}} + +{{#if significant_change_3}} 3. {{significant_change_3}} +Impact: {{impact_description_3}} +{{/if}} + +Charlie (Senior Dev): "Yeah, when we discovered {{technical_discovery}}, it fundamentally changed our understanding of {{affected_area}}." + +Alice (Product Owner): "And from a product perspective, {{product_discovery}} means Epic {{next_epic_num}}'s stories are based on wrong assumptions." + +Dana (QA Engineer): "If we start Epic {{next_epic_num}} as-is, we're going to hit walls fast." + +**Impact on Epic {{next_epic_num}}:** + +The current plan for Epic {{next_epic_num}} assumes: + +- {{wrong_assumption_1}} +- {{wrong_assumption_2}} + +But Epic {{epic_number}} revealed: + +- {{actual_reality_1}} +- {{actual_reality_2}} + +This means Epic {{next_epic_num}} likely needs: +{{list_likely_changes_needed}} + +**RECOMMENDED ACTIONS:** + +1. Review and update Epic {{next_epic_num}} definition based on new learnings +2. Update affected stories in Epic {{next_epic_num}} to reflect reality +3. Consider updating architecture or technical specifications if applicable +4. Hold alignment session with Product Owner before starting Epic {{next_epic_num}} + {{#if prd_update_needed}}5. Update PRD sections affected by new understanding{{/if}} + +Bob (Scrum Master): "**Epic Update Required**: YES - Schedule epic planning review session" + +Bob (Scrum Master): "{user_name}, this is significant. We need to address this before committing to Epic {{next_epic_num}}'s current plan. How do you want to handle it?" + + +WAIT for {user_name} to decide on how to handle the significant changes + +Add epic review session to critical path if user agrees + + +Alice (Product Owner): "I agree with {user_name}'s approach. Better to adjust the plan now than fail mid-epic." + +Charlie (Senior Dev): "This is why retrospectives matter. We caught this before it became a disaster." + +Bob (Scrum Master): "Adding to critical path: Epic {{next_epic_num}} planning review session before epic kickoff." + + + + + +Bob (Scrum Master): "Good news - nothing from Epic {{epic_number}} fundamentally changes our plan for Epic {{next_epic_num}}. The plan is still sound." + +Alice (Product Owner): "We learned a lot, but the direction is right." + + + + +Bob (Scrum Master): "Let me show you the complete action plan..." + +Bob (Scrum Master): "That's {{total_action_count}} action items, {{prep_task_count}} preparation tasks, and {{critical_count}} critical path items." + +Bob (Scrum Master): "Everyone clear on what they own?" + + +Give each agent with assignments a moment to acknowledge their ownership + +Ensure {user_name} approves the complete action plan + + + + + + +Bob (Scrum Master): "Before we close, I want to do a final readiness check." + +Bob (Scrum Master): "Epic {{epic_number}} is marked complete in sprint-status, but is it REALLY done?" + +Alice (Product Owner): "What do you mean, Bob?" + +Bob (Scrum Master): "I mean truly production-ready, stakeholders happy, no loose ends that'll bite us later." + +Bob (Scrum Master): "{user_name}, let's walk through this together." + + +Explore testing and quality state through natural conversation + + +Bob (Scrum Master): "{user_name}, tell me about the testing for Epic {{epic_number}}. What verification has been done?" + + +WAIT for {user_name} to describe testing status + + +Dana (QA Engineer): [Responds to what {user_name} shared] "I can add to that - {{additional_testing_context}}." + +Dana (QA Engineer): "But honestly, {{testing_concern_if_any}}." + +Bob (Scrum Master): "{user_name}, are you confident Epic {{epic_number}} is production-ready from a quality perspective?" + + +WAIT for {user_name} to assess quality readiness + + + +Bob (Scrum Master): "Okay, let's capture that. What specific testing is still needed?" + +Dana (QA Engineer): "I can handle {{testing_work_needed}}, estimated {{testing_hours}} hours." + +Bob (Scrum Master): "Adding to critical path: Complete {{testing_work_needed}} before Epic {{next_epic_num}}." + +Add testing completion to critical path + + +Explore deployment and release status + + +Bob (Scrum Master): "{user_name}, what's the deployment status for Epic {{epic_number}}? Is it live in production, scheduled for deployment, or still pending?" + + +WAIT for {user_name} to provide deployment status + + + +Charlie (Senior Dev): "If it's not deployed yet, we need to factor that into Epic {{next_epic_num}} timing." + +Bob (Scrum Master): "{user_name}, when is deployment planned? Does that timing work for starting Epic {{next_epic_num}}?" + + +WAIT for {user_name} to clarify deployment timeline + +Add deployment milestone to critical path with agreed timeline + + +Explore stakeholder acceptance + + +Bob (Scrum Master): "{user_name}, have stakeholders seen and accepted the Epic {{epic_number}} deliverables?" + +Alice (Product Owner): "This is important - I've seen 'done' epics get rejected by stakeholders and force rework." + +Bob (Scrum Master): "{user_name}, any feedback from stakeholders still pending?" + + +WAIT for {user_name} to describe stakeholder acceptance status + + + +Alice (Product Owner): "We should get formal acceptance before moving on. Otherwise Epic {{next_epic_num}} might get interrupted by rework." + +Bob (Scrum Master): "{user_name}, how do you want to handle stakeholder acceptance? Should we make it a critical path item?" + + +WAIT for {user_name} decision + +Add stakeholder acceptance to critical path if user agrees + + +Explore technical health and stability + + +Bob (Scrum Master): "{user_name}, this is a gut-check question: How does the codebase feel after Epic {{epic_number}}?" + +Bob (Scrum Master): "Stable and maintainable? Or are there concerns lurking?" + +Charlie (Senior Dev): "Be honest, {user_name}. We've all shipped epics that felt... fragile." + + +WAIT for {user_name} to assess codebase health + + + +Charlie (Senior Dev): "Okay, let's dig into that. What's causing those concerns?" + +Charlie (Senior Dev): [Helps {user_name} articulate technical concerns] + +Bob (Scrum Master): "What would it take to address these concerns and feel confident about stability?" + +Charlie (Senior Dev): "I'd say we need {{stability_work_needed}}, roughly {{stability_hours}} hours." + +Bob (Scrum Master): "{user_name}, is addressing this stability work worth doing before Epic {{next_epic_num}}?" + + +WAIT for {user_name} decision + +Add stability work to preparation sprint if user agrees + + +Explore unresolved blockers + + +Bob (Scrum Master): "{user_name}, are there any unresolved blockers or technical issues from Epic {{epic_number}} that we're carrying forward?" + +Dana (QA Engineer): "Things that might create problems for Epic {{next_epic_num}} if we don't deal with them?" + +Bob (Scrum Master): "Nothing is off limits here. If there's a problem, we need to know." + + +WAIT for {user_name} to surface any blockers + + + +Bob (Scrum Master): "Let's capture those blockers and figure out how they affect Epic {{next_epic_num}}." + +Charlie (Senior Dev): "For {{blocker_1}}, if we leave it unresolved, it'll {{impact_description_1}}." + +Alice (Product Owner): "That sounds critical. We need to address that before moving forward." + +Bob (Scrum Master): "Agreed. Adding to critical path: Resolve {{blocker_1}} before Epic {{next_epic_num}} kickoff." + +Bob (Scrum Master): "Who owns that work?" + + +Assign blocker resolution to appropriate agent +Add to critical path with priority and deadline + + +Synthesize the readiness assessment + + +Bob (Scrum Master): "Okay {user_name}, let me synthesize what we just uncovered..." + +**EPIC {{epic_number}} READINESS ASSESSMENT:** + +Testing & Quality: {{quality_status}} +{{#if quality_concerns}}⚠️ Action needed: {{quality_action_needed}}{{/if}} + +Deployment: {{deployment_status}} +{{#if deployment_pending}}⚠️ Scheduled for: {{deployment_date}}{{/if}} + +Stakeholder Acceptance: {{acceptance_status}} +{{#if acceptance_incomplete}}⚠️ Action needed: {{acceptance_action_needed}}{{/if}} + +Technical Health: {{stability_status}} +{{#if stability_concerns}}⚠️ Action needed: {{stability_action_needed}}{{/if}} + +Unresolved Blockers: {{blocker_status}} +{{#if blockers_exist}}⚠️ Must resolve: {{blocker_list}}{{/if}} + +Bob (Scrum Master): "{user_name}, does this assessment match your understanding?" + + +WAIT for {user_name} to confirm or correct the assessment + + +Bob (Scrum Master): "Based on this assessment, Epic {{epic_number}} is {{#if all_clear}}fully complete and we're clear to proceed{{else}}complete from a story perspective, but we have {{critical_work_count}} critical items before Epic {{next_epic_num}}{{/if}}." + +Alice (Product Owner): "This level of thoroughness is why retrospectives are valuable." + +Charlie (Senior Dev): "Better to catch this now than three stories into the next epic." + + + + + + + +Bob (Scrum Master): "We've covered a lot of ground today. Let me bring this retrospective to a close." + +═══════════════════════════════════════════════════════════ +✅ RETROSPECTIVE COMPLETE +═══════════════════════════════════════════════════════════ + +Bob (Scrum Master): "Epic {{epic_number}}: {{epic_title}} - REVIEWED" + +**Key Takeaways:** + +1. {{key_lesson_1}} +2. {{key_lesson_2}} +3. {{key_lesson_3}} + {{#if key_lesson_4}}4. {{key_lesson_4}}{{/if}} + +Alice (Product Owner): "That first takeaway is huge - {{impact_of_lesson_1}}." + +Charlie (Senior Dev): "And lesson 2 is something we can apply immediately." + +Bob (Scrum Master): "Commitments made today:" + +- Action Items: {{action_count}} +- Preparation Tasks: {{prep_task_count}} +- Critical Path Items: {{critical_count}} + +Dana (QA Engineer): "That's a lot of commitments. We need to actually follow through this time." + +Bob (Scrum Master): "Agreed. Which is why we'll review these action items in our next standup." + +═══════════════════════════════════════════════════════════ +🎯 NEXT STEPS: +═══════════════════════════════════════════════════════════ + +1. Execute Preparation Sprint (Est: {{prep_days}} days) +2. Complete Critical Path items before Epic {{next_epic_num}} +3. Review action items in next standup + {{#if epic_update_needed}}4. Hold Epic {{next_epic_num}} planning review session{{else}}4. Begin Epic {{next_epic_num}} planning when preparation complete{{/if}} + +Elena (Junior Dev): "{{prep_days}} days of prep work is significant, but necessary." + +Alice (Product Owner): "I'll communicate the timeline to stakeholders. They'll understand if we frame it as 'ensuring Epic {{next_epic_num}} success.'" + +═══════════════════════════════════════════════════════════ + +Bob (Scrum Master): "Before we wrap, I want to take a moment to acknowledge the team." + +Bob (Scrum Master): "Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_description}} velocity. We overcame {{blocker_count}} blockers. We learned a lot. That's real work by real people." + +Charlie (Senior Dev): "Hear, hear." + +Alice (Product Owner): "I'm proud of what we shipped." + +Dana (QA Engineer): "And I'm excited about Epic {{next_epic_num}} - especially now that we're prepared for it." + +Bob (Scrum Master): "{user_name}, any final thoughts before we close?" + + +WAIT for {user_name} to share final reflections + + +Bob (Scrum Master): [Acknowledges what {user_name} shared] "Thank you for that, {user_name}." + +Bob (Scrum Master): "Alright team - great work today. We learned a lot from Epic {{epic_number}}. Let's use these insights to make Epic {{next_epic_num}} even better." + +Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" + +═══════════════════════════════════════════════════════════ + + +Prepare to save retrospective summary document + + + + + +Ensure retrospectives folder exists: {retrospectives_folder} +Create folder if it doesn't exist + +Generate comprehensive retrospective summary document including: + +- Epic summary and metrics +- Team participants +- Successes and strengths identified +- Challenges and growth areas +- Key insights and learnings +- Previous retro follow-through analysis (if applicable) +- Next epic preview and dependencies +- Action items with owners and timelines +- Preparation tasks for next epic +- Critical path items +- Significant discoveries and epic update recommendations (if any) +- Readiness assessment +- Commitments and next steps + +Format retrospective document as readable markdown with clear sections +Set filename: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md +Save retrospective document + + +✅ Retrospective document saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + + +Update {sprint_status_file} to mark retrospective as completed + +Load the FULL file: {sprint_status_file} +Find development_status key "epic-{{epic_number}}-retrospective" +Verify current status (typically "optional" or "pending") +Update development_status["epic-{{epic_number}}-retrospective"] = "done" +Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + +✅ Retrospective marked as completed in {sprint_status_file} + +Retrospective key: epic-{{epic_number}}-retrospective +Status: {{previous_status}} → done + + + + + +⚠️ Could not update retrospective status: epic-{{epic_number}}-retrospective not found in {sprint_status_file} + +Retrospective document was saved successfully, but {sprint_status_file} may need manual update. + + + + + + + + +**✅ Retrospective Complete, {user_name}!** + +**Epic Review:** + +- Epic {{epic_number}}: {{epic_title}} reviewed +- Retrospective Status: completed +- Retrospective saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + +**Commitments Made:** + +- Action Items: {{action_count}} +- Preparation Tasks: {{prep_task_count}} +- Critical Path Items: {{critical_count}} + +**Next Steps:** + +1. **Review retrospective summary**: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + +2. **Execute preparation sprint** (Est: {{prep_days}} days) + - Complete {{critical_count}} critical path items + - Execute {{prep_task_count}} preparation tasks + - Verify all action items are in progress + +3. **Review action items in next standup** + - Ensure ownership is clear + - Track progress on commitments + - Adjust timelines if needed + +{{#if epic_update_needed}} 4. **IMPORTANT: Schedule Epic {{next_epic_num}} planning review session** + +- Significant discoveries from Epic {{epic_number}} require epic updates +- Review and update affected stories +- Align team on revised approach +- Do NOT start Epic {{next_epic_num}} until review is complete + {{else}} + +4. **Begin Epic {{next_epic_num}} planning when preparation complete** + - Load PM agent and run `epic-tech-context` for Epic {{next_epic_num}} + - Or continue with existing contexted epics + - Ensure all critical path items are done first + {{/if}} + +**Team Performance:** +Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_summary}}. The retrospective surfaced {{insight_count}} key insights and {{significant_discovery_count}} significant discoveries. The team is well-positioned for Epic {{next_epic_num}} success. + +{{#if significant_discovery_count > 0}} +⚠️ **REMINDER**: Epic update required before starting Epic {{next_epic_num}} +{{/if}} + +--- + +Bob (Scrum Master): "Great session today, {user_name}. The team did excellent work." + +Alice (Product Owner): "See you at epic planning!" + +Charlie (Senior Dev): "Time to knock out that prep work." + + + + + + + + +PARTY MODE REQUIRED: All agent dialogue uses "Name (Role): dialogue" format +Scrum Master maintains psychological safety throughout - no blame or judgment +Focus on systems and processes, not individual performance +Create authentic team dynamics: disagreements, diverse perspectives, emotions +User ({user_name}) is active participant, not passive observer +Encourage specific examples over general statements +Balance celebration of wins with honest assessment of challenges +Ensure every voice is heard - all agents contribute +Action items must be specific, achievable, and owned +Forward-looking mindset - how do we improve for next epic? +Intent-based facilitation, not scripted phrases +Deep story analysis provides rich material for discussion +Previous retro integration creates accountability and continuity +Significant change detection prevents epic misalignment +Critical verification prevents starting next epic prematurely +Document everything - retrospective insights are valuable for future reference +Two-part structure ensures both reflection AND preparation + diff --git a/src/modules/bmgd/workflows/4-production/retrospective/workflow.yaml b/src/modules/bmgd/workflows/4-production/retrospective/workflow.yaml new file mode 100644 index 00000000..9584f3b1 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/retrospective/workflow.yaml @@ -0,0 +1,52 @@ +# Retrospective - Epic Completion Review Workflow +name: "retrospective" +description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic" +author: "BMad" + +config_source: "{project-root}/{bmad_folder}/bmgd/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" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" + +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective" +template: false +instructions: "{installed_path}/instructions.md" + +required_inputs: + - agent_manifest: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives +input_file_patterns: + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + previous_retrospective: + pattern: "{sprint_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md" + load_strategy: "SELECTIVE_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + document_project: + sharded: "{output_folder}/*.md" + load_strategy: "INDEX_GUIDED" + +# Required files +sprint_status_file: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" +story_directory: "{sprint_artifacts}" +retrospectives_folder: "{sprint_artifacts}" + +standalone: true +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/sprint-planning/checklist.md b/src/modules/bmgd/workflows/4-production/sprint-planning/checklist.md new file mode 100644 index 00000000..7c20b1f3 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/sprint-planning/checklist.md @@ -0,0 +1,33 @@ +# Sprint Planning Validation Checklist + +## Core Validation + +### Complete Coverage Check + +- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml +- [ ] Every story found in epic\*.md files appears in sprint-status.yaml +- [ ] Every epic has a corresponding retrospective entry +- [ ] No items in sprint-status.yaml that don't exist in epic files + +### Parsing Verification + +Compare epic files against generated sprint-status.yaml: + +``` +Epic Files Contains: Sprint Status Contains: +✓ Epic 1 ✓ epic-1: [status] + ✓ Story 1.1: User Auth ✓ 1-1-user-auth: [status] + ✓ Story 1.2: Account Mgmt ✓ 1-2-account-mgmt: [status] + ✓ Story 1.3: Plant Naming ✓ 1-3-plant-naming: [status] + ✓ epic-1-retrospective: [status] +✓ Epic 2 ✓ epic-2: [status] + ✓ Story 2.1: Personality Model ✓ 2-1-personality-model: [status] + ✓ Story 2.2: Chat Interface ✓ 2-2-chat-interface: [status] + ✓ epic-2-retrospective: [status] +``` + +### Final Check + +- [ ] Total count of epics matches +- [ ] Total count of stories matches +- [ ] All items are in the expected order (epic, stories, retrospective) diff --git a/src/modules/bmgd/workflows/4-production/sprint-planning/instructions.md b/src/modules/bmgd/workflows/4-production/sprint-planning/instructions.md new file mode 100644 index 00000000..e7fd436b --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/sprint-planning/instructions.md @@ -0,0 +1,234 @@ +# Sprint Planning - Sprint Status Generator + +The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning/workflow.yaml + +## 📚 Document Discovery - Full Epic Loading + +**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking. + +**Epic Discovery Process:** + +1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file +2. **Check for sharded version** - If whole document not found, look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand the document structure + - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.) + - Process all epics and their stories from the combined content + - This ensures complete sprint status coverage +4. **Priority**: If both whole and sharded versions exist, use the whole document + +**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc. + + + + +Communicate in {communication_language} with {user_name} +Look for all files matching `{epics_pattern}` in {epics_location} +Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files + +For each epic file found, extract: + +- Epic numbers from headers like `## Epic 1:` or `## Epic 2:` +- Story IDs and titles from patterns like `### Story 1.1: User Authentication` +- Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title` + +**Story ID Conversion Rules:** + +- Original: `### Story 1.1: User Authentication` +- Replace period with dash: `1-1` +- Convert title to kebab-case: `user-authentication` +- Final key: `1-1-user-authentication` + +Build complete inventory of all epics and stories from all epic files + + + + + After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy) + + + +For each epic found, create entries in this order: + +1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog` +2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog` +3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional` + +**Example structure:** + +```yaml +development_status: + epic-1: backlog + 1-1-user-authentication: backlog + 1-2-account-management: backlog + epic-1-retrospective: optional +``` + + + + +For each epic, check if tech context file exists: + +- Check: `{output_folder}/epic-{num}-context.md` +- If exists → set epic status to `contexted` +- Else → keep as `backlog` + +For each story, detect current status by checking files: + +**Story file detection:** + +- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`) +- If exists → upgrade status to at least `drafted` + +**Story context detection:** + +- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`) +- If exists → upgrade status to at least `ready-for-dev` + +**Preservation rule:** + +- If existing `{status_file}` exists and has more advanced status, preserve it +- Never downgrade status (e.g., don't change `done` to `drafted`) + +**Status Flow Reference:** + +- Epic: `backlog` → `contexted` +- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done` +- Retrospective: `optional` ↔ `completed` + + + +Create or update {status_file} with: + +**File Structure:** + +```yaml +# generated: {date} +# project: {project_name} +# project_key: {project_key} +# tracking_system: {tracking_system} +# story_location: {story_location} + +# STATUS DEFINITIONS: +# ================== +# Epic Status: +# - backlog: Epic exists in epic file but not contexted +# - contexted: Epic tech context created (required before drafting stories) +# +# Story Status: +# - backlog: Story only exists in epic file +# - drafted: Story file created in stories folder +# - ready-for-dev: Draft approved and story context created +# - in-progress: Developer actively working on implementation +# - review: Under SM review (via code-review workflow) +# - done: Story completed +# +# Retrospective Status: +# - optional: Can be completed but not required +# - completed: Retrospective has been done +# +# WORKFLOW NOTES: +# =============== +# - Epics should be 'contexted' before stories can be 'drafted' +# - Stories can be worked in parallel if team capacity allows +# - SM typically drafts next story after previous one is 'done' to incorporate learnings +# - Dev moves story to 'review', SM reviews, then Dev moves to 'done' + +generated: { date } +project: { project_name } +project_key: { project_key } +tracking_system: { tracking_system } +story_location: { story_location } + +development_status: + # All epics, stories, and retrospectives in order +``` + +Write the complete sprint status YAML to {status_file} +CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing +Ensure all items are ordered: epic, its stories, its retrospective, next epic... + + + +Perform validation checks: + +- [ ] Every epic in epic files appears in {status_file} +- [ ] Every story in epic files appears in {status_file} +- [ ] Every epic has a corresponding retrospective entry +- [ ] No items in {status_file} that don't exist in epic files +- [ ] All status values are legal (match state machine definitions) +- [ ] File is valid YAML syntax + +Count totals: + +- Total epics: {{epic_count}} +- Total stories: {{story_count}} +- Epics contexted: {{contexted_count}} +- Stories in progress: {{in_progress_count}} +- Stories done: {{done_count}} + +Display completion summary to {user_name} in {communication_language}: + +**Sprint Status Generated Successfully** + +- **File Location:** {status_file} +- **Total Epics:** {{epic_count}} +- **Total Stories:** {{story_count}} +- **Contexted Epics:** {{contexted_count}} +- **Stories In Progress:** {{in_progress_count}} +- **Stories Completed:** {{done_count}} + +**Next Steps:** + +1. Review the generated {status_file} +2. Use this file to track development progress +3. Agents will update statuses as they work +4. Re-run this workflow to refresh auto-detected statuses + + + + + +## Additional Documentation + +### Status State Machine + +**Epic Status Flow:** + +``` +backlog → contexted +``` + +- **backlog**: Epic exists in epic file but tech context not created +- **contexted**: Epic tech context has been generated (prerequisite for story drafting) + +**Story Status Flow:** + +``` +backlog → drafted → ready-for-dev → in-progress → review → done +``` + +- **backlog**: Story only exists in epic file +- **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 +- **review**: Under SM review (via code-review workflow) +- **done**: Completed + +**Retrospective Status:** + +``` +optional ↔ completed +``` + +- **optional**: Can be done but not required +- **completed**: Retrospective has been completed + +### Guidelines + +1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted` +2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported +3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows +4. **Review Before Done**: Stories should pass through `review` before `done` +5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings diff --git a/src/modules/bmgd/workflows/4-production/sprint-planning/sprint-status-template.yaml b/src/modules/bmgd/workflows/4-production/sprint-planning/sprint-status-template.yaml new file mode 100644 index 00000000..a35f50c3 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/sprint-planning/sprint-status-template.yaml @@ -0,0 +1,55 @@ +# Sprint Status Template +# This is an EXAMPLE showing the expected format +# The actual file will be generated with all epics/stories from your epic files + +# generated: {date} +# project: {project_name} +# project_key: {project_key} +# tracking_system: {tracking_system} +# story_location: {story_location} + +# STATUS DEFINITIONS: +# ================== +# Epic Status: +# - backlog: Epic exists in epic file but not contexted +# - contexted: Next epic tech context created by *epic-tech-context (required) +# +# Story Status: +# - backlog: Story only exists in epic file +# - drafted: Story file created in stories folder by *create-story +# - ready-for-dev: Draft approved and story context created by *story-ready +# - in-progress: Developer actively working on implementation by *dev-story +# - review: Implementation complete, ready for review by *code-review +# - done: Story completed by *story-done +# +# Retrospective Status: +# - optional: Can be completed but not required +# - completed: Retrospective has been done by *retrospective +# +# WORKFLOW NOTES: +# =============== +# - Epics should be 'contexted' before stories can be 'drafted' +# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings +# - Dev moves story to 'review', dev reviews, then Dev moves to 'done' + +# EXAMPLE STRUCTURE (your actual epics/stories will replace these): + +generated: 05-06-2-2025 21:30 +project: My Awesome Project +project_key: jira-1234 +tracking_system: file-system +story_location: "{project-root}/docs/stories" + +development_status: + epic-1: contexted + 1-1-user-authentication: done + 1-2-account-management: drafted + 1-3-plant-data-model: backlog + 1-4-add-plant-manual: backlog + epic-1-retrospective: optional + + epic-2: backlog + 2-1-personality-system: backlog + 2-2-chat-interface: backlog + 2-3-llm-integration: backlog + epic-2-retrospective: optional diff --git a/src/modules/bmgd/workflows/4-production/sprint-planning/workflow.yaml b/src/modules/bmgd/workflows/4-production/sprint-planning/workflow.yaml new file mode 100644 index 00000000..08859887 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/sprint-planning/workflow.yaml @@ -0,0 +1,50 @@ +name: sprint-planning +description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning" +instructions: "{installed_path}/instructions.md" +template: "{installed_path}/sprint-status-template.yaml" +validation: "{installed_path}/checklist.md" + +# Variables and inputs +variables: + # Project identification + project_name: "{config_source}:project_name" + + # Tracking system configuration + tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello + story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello + story_location_absolute: "{config_source}:sprint_artifacts" # Absolute path for file operations + + # Source files (file-system only) + epics_location: "{output_folder}" # Directory containing epic*.md files + epics_pattern: "epic*.md" # Pattern to find epic files + + # Output configuration + status_file: "{sprint_artifacts}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status +input_file_patterns: + epics: + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/*.md" + load_strategy: "FULL_LOAD" + +# Output configuration +default_output_file: "{status_file}" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/story-context/checklist.md b/src/modules/bmgd/workflows/4-production/story-context/checklist.md new file mode 100644 index 00000000..d2f77cea --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-context/checklist.md @@ -0,0 +1,16 @@ +# Story Context Assembly Checklist + +```xml + + Story fields (asA/iWant/soThat) captured + Acceptance criteria list matches story draft exactly (no invention) + Tasks/subtasks captured as task list + Relevant docs (5-15) included with path and snippets + Relevant code references included with reason and line hints + Interfaces/API contracts extracted if applicable + Constraints include applicable dev rules and patterns + Dependencies detected from manifests and frameworks + Testing standards and locations populated + XML structure follows story-context template format + +``` diff --git a/src/modules/bmgd/workflows/4-production/story-context/context-template.xml b/src/modules/bmgd/workflows/4-production/story-context/context-template.xml new file mode 100644 index 00000000..c2988e09 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-context/context-template.xml @@ -0,0 +1,34 @@ + + + {{epic_id}} + {{story_id}} + {{story_title}} + {{story_status}} + {{date}} + BMAD Story Context Workflow + {{story_path}} + + + + {{as_a}} + {{i_want}} + {{so_that}} + {{story_tasks}} + + + {{acceptance_criteria}} + + + {{docs_artifacts}} + {{code_artifacts}} + {{dependencies_artifacts}} + + + {{constraints}} + {{interfaces}} + + {{test_standards}} + {{test_locations}} + {{test_ideas}} + + diff --git a/src/modules/bmgd/workflows/4-production/story-context/instructions.md b/src/modules/bmgd/workflows/4-production/story-context/instructions.md new file mode 100644 index 00000000..8e9bad2b --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-context/instructions.md @@ -0,0 +1,209 @@ + + +```xml +The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} +Generate all documents in {document_output_language} +This workflow assembles a Story Context file for a single drafted story by extracting acceptance criteria, tasks, relevant docs/code, interfaces, constraints, and testing guidance. +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.xml). Concise, structured, project-relative paths only. + + + + + Use {{story_path}} directly + Read COMPLETE story file and parse sections + Extract story_key from filename or story metadata + Verify Status is "drafted" - if not, HALT with message: "Story status must be 'drafted' to generate context" + + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {{output_folder}}/sprint-status.yaml + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find FIRST story (reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "drafted" + + + + 📋 No drafted stories found in sprint-status.yaml + All stories are either still in backlog or already marked ready/in-progress/done. + + **Next Steps:** + 1. Run `create-story` to draft more stories + 2. Run `sprint-planning` to refresh story tracking + + HALT + + + Use the first drafted story found + Find matching story file in {{story_path}} using story_key pattern + Read the COMPLETE story file + + + Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content + Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes + Extract user story fields (asA, iWant, soThat) + story_tasks + acceptance_criteria + + + Check if file exists at {default_output_file} + + + ⚠️ Context file already exists: {default_output_file} + + **What would you like to do?** + 1. **Replace** - Generate new context file (overwrites existing) + 2. **Verify** - Validate existing context file + 3. **Cancel** - Exit without changes + + Choose action (replace/verify/cancel): + + + GOTO validation_step + + + + HALT with message: "Context generation cancelled" + + + + Continue to generate new context file + + + + Store project root path for relative path conversion: extract from {project-root} variable + Define path normalization function: convert any absolute path to project-relative by removing project root prefix + Initialize output by writing template to {default_output_file} + as_a + i_want + so_that + + + + + After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} + + + + Review loaded content from Step 1.5 for items relevant to this story's domain (use keywords from story title, ACs, and tasks). + Extract relevant sections from: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {document_project_content} + Note: Tech-Spec ({tech_spec_content}) is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance. + For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md"). + + Add artifacts.docs entries with {path, title, section, snippet}: + - path: PROJECT-RELATIVE path only (strip {project-root} prefix) + - title: Document title + - section: Relevant section name + - snippet: Brief excerpt (2-3 sentences max, NO invention) + + + + + Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests). + Identify existing interfaces/APIs the story should reuse rather than recreate. + Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements). + For all discovered code artifacts: convert absolute paths to project-relative format (strip {project-root} prefix). + + Add artifacts.code entries with {path, kind, symbol, lines, reason}: + - path: PROJECT-RELATIVE path only (e.g., "src/services/api.js" not full path) + - kind: file type (controller, service, component, test, etc.) + - symbol: function/class/interface name + - lines: line range if specific (e.g., "45-67") + - reason: brief explanation of relevance to this story + + Populate interfaces with API/interface signatures: + - name: Interface or API name + - kind: REST endpoint, GraphQL, function signature, class interface + - signature: Full signature or endpoint definition + - path: PROJECT-RELATIVE path to definition + + Populate constraints with development rules: + - Extract from Dev Notes and architecture + - Include: required patterns, layer restrictions, testing requirements, coding standards + + + + + Detect dependency manifests and frameworks in the repo: + - Node: package.json (dependencies/devDependencies) + - Python: pyproject.toml/requirements.txt + - Go: go.mod + - Unity: Packages/manifest.json, Assets/, ProjectSettings/ + - Other: list notable frameworks/configs found + + Populate artifacts.dependencies with keys for detected ecosystems and their packages with version ranges where present + + + + + From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations). + + Populate tests.standards with a concise paragraph + Populate tests.locations with directories or glob patterns where tests live + Populate tests.ideas with initial test ideas mapped to acceptance criteria IDs + + + + + + Validate output context file structure and content + Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml + + + + Open {{story_path}} + Find the "Status:" line (usually at the top) + Update story file: Change Status to "ready-for-dev" + Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}. + Save the story file. + + + Load the FULL file: {{output_folder}}/sprint-status.yaml + Find development_status key matching {{story_key}} + Verify current status is "drafted" (expected previous state) + Update development_status[{{story_key}}] = "ready-for-dev" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found + +You may need to run sprint-planning to refresh tracking. + + + + ✅ Story context generated successfully, {user_name}! + +**Story Details:** + +- Story: {{epic_id}}.{{story_id}} - {{story_title}} +- Story Key: {{story_key}} +- Context File: {default_output_file} +- Status: drafted → ready-for-dev + +**Context Includes:** + +- Documentation artifacts and references +- Existing code and interfaces +- Dependencies and frameworks +- Testing standards and ideas +- Development constraints + +**Next Steps:** + +1. Review the context file: {default_output_file} +2. Run `dev-story` to implement the story +3. Generate context for more drafted stories if needed + + + + +``` diff --git a/src/modules/bmgd/workflows/4-production/story-context/workflow.yaml b/src/modules/bmgd/workflows/4-production/story-context/workflow.yaml new file mode 100644 index 00000000..f8b0e618 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-context/workflow.yaml @@ -0,0 +1,57 @@ +# Story Context Creation Workflow +name: story-context +description: "Assemble a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story" +author: "BMad" + +# Critical variables +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +document_output_language: "{config_source}:document_output_language" +story_path: "{config_source}:sprint_artifacts/stories" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-context" +template: "{installed_path}/context-template.xml" +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec.md" + load_strategy: "FULL_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" + +# Output configuration +# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication") +default_output_file: "{story_path}/{{story_key}}.context.xml" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/story-done/instructions.md b/src/modules/bmgd/workflows/4-production/story-done/instructions.md new file mode 100644 index 00000000..32ac01b4 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-done/instructions.md @@ -0,0 +1,111 @@ +# Story Approved Workflow Instructions (DEV Agent) + +The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} + + + +This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete) +Workflow: Update story file status to Done + + + + + Use {story_path} directly + Read COMPLETE story file and parse sections + Extract story_key from filename or story metadata + Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done" + + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {output_folder}/sprint-status.yaml + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + +Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review" + + + + 📋 No stories with status "review" found + +All stories are either still in development or already done. + +**Next Steps:** + +1. Run `dev-story` to implement stories +2. Run `code-review` if stories need review first +3. Check sprint-status.yaml for current story states + + HALT + + +Use the first reviewed story found +Find matching story file in {story_dir} using story_key pattern +Read the COMPLETE story file + + +Extract story_id and story_title from the story file + +Find the "Status:" line (usually at the top) +Update story file: Change Status to "done" + +Add completion notes to Dev Agent Record section: +Find "## Dev Agent Record" section and add: + +``` +### Completion Notes +**Completed:** {date} +**Definition of Done:** All acceptance criteria met, code reviewed, tests passing +``` + + + +Save the story file + + + +Load the FULL file: {output_folder}/sprint-status.yaml +Find development_status key matching {story_key} +Verify current status is "review" (expected previous state) +Update development_status[{story_key}] = "done" +Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Story file updated, but could not update sprint-status: {story_key} not found + +Story is marked Done in file, but sprint-status.yaml may be out of sync. + + + + + + + +**Story Approved and Marked Done, {user_name}!** + +✅ Story file updated → Status: done +✅ Sprint status updated: review → done + +**Completed Story:** + +- **ID:** {story_id} +- **Key:** {story_key} +- **Title:** {story_title} +- **Completed:** {date} + +**Next Steps:** + +1. Continue with next story in your backlog + - Run `create-story` for next backlog story + - Or run `dev-story` if ready stories exist +2. Check epic completion status + - Run `retrospective` workflow to check if epic is complete + - Epic retrospective will verify all stories are done + + + + + +``` diff --git a/src/modules/bmgd/workflows/4-production/story-done/workflow.yaml b/src/modules/bmgd/workflows/4-production/story-done/workflow.yaml new file mode 100644 index 00000000..3b4f60e9 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-done/workflow.yaml @@ -0,0 +1,28 @@ +# Story Done Workflow (DEV Agent) +name: story-done +description: "Marks a story as done (DoD complete) and moves it from its current status → DONE in the status file. Advances the story queue. Simple status-update workflow with no searching required." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done" +instructions: "{installed_path}/instructions.md" + +# Variables and inputs +variables: + story_dir: "{config_source}:sprint_artifacts" # Directory where stories are stored + +# Output configuration - no output file, just status updates +default_output_file: "" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmgd/workflows/4-production/story-ready/instructions.md b/src/modules/bmgd/workflows/4-production/story-ready/instructions.md new file mode 100644 index 00000000..6f5dfdc6 --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-ready/instructions.md @@ -0,0 +1,117 @@ +# Story Ready Workflow Instructions (SM Agent) + +The workflow execution engine is governed by: {project_root}/{bmad_folder}/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} + + + +This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development +Simple workflow: Update story file status to Ready + + + +If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready + +MUST read COMPLETE {sprint_status} file from start to end to preserve order +Load the FULL file: {sprint_status} +Read ALL lines from beginning to end - do not skip any content +Parse the development_status section completely + +Find ALL stories (reading in order from start to end) where: + +- Key matches pattern: number-number-name (e.g., "1-2-user-auth") +- NOT an epic key (epic-X) or retrospective (epic-X-retrospective) +- Status value equals "drafted" + + +Collect up to 10 drafted story keys in order (limit for display purposes) +Count total drafted stories found + + + 📋 No drafted stories found in {sprint_status} + +All stories are either still in backlog or already marked ready/in-progress/done. + +**Options:** + +1. Run `create-story` to draft more stories +2. Run `sprint-planning` to refresh story tracking + + HALT + + +Display available drafted stories: + +**Drafted Stories Available ({{drafted_count}} found):** + +{{list_of_drafted_story_keys}} + + + +Select the drafted story to mark as Ready (enter story key or number): +Auto-select first story from the list + +Resolve selected story_key from user input or auto-selection +Find matching story file in {{story_dir}} using story_key pattern + + + +Read the story file from resolved path +Extract story_id and story_title from the file + +Find the "Status:" line (usually at the top) +Update story file: Change Status to "ready-for-dev" +Save the story file + + + +Load the FULL file: {sprint_status} +Find development_status key matching {{story_key}} +Verify current status is "drafted" (expected previous state) +Update development_status[{{story_key}}] = "ready-for-dev" +Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + ⚠️ Story file updated, but could not update sprint-status: {{story_key}} not found + +You may need to run sprint-planning to refresh tracking. + + + + + + + +**Story Marked Ready for Development, {user_name}!** + +✅ Story file updated: `{{story_file}}` → Status: ready-for-dev +✅ Sprint status updated: drafted → ready-for-dev + +**Story Details:** + +- **ID:** {{story_id}} +- **Key:** {{story_key}} +- **Title:** {{story_title}} +- **File:** `{{story_file}}` +- **Status:** ready-for-dev + +**Next Steps:** + +1. **Recommended:** Run `story-context` workflow to generate implementation context + - This creates a comprehensive context XML for the DEV agent + - Includes relevant architecture, dependencies, and existing code + +2. **Alternative:** Skip context generation and go directly to `dev-story` workflow + - Faster, but DEV agent will have less context + - Only recommended for simple, well-understood stories + +**To proceed:** + +- For context generation: Stay with SM agent and run `story-context` workflow +- For direct implementation: Load DEV agent and run `dev-story` workflow + + + + diff --git a/src/modules/bmgd/workflows/4-production/story-ready/workflow.yaml b/src/modules/bmgd/workflows/4-production/story-ready/workflow.yaml new file mode 100644 index 00000000..3b63de0e --- /dev/null +++ b/src/modules/bmgd/workflows/4-production/story-ready/workflow.yaml @@ -0,0 +1,25 @@ +# Story Ready Workflow (SM Agent) +name: story-ready +description: "Marks a drafted story as ready for development and moves it from TODO → IN PROGRESS in the status file. Simple status-update workflow with no searching required." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/{bmad_folder}/bmgd/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Workflow components +installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-ready" +instructions: "{installed_path}/instructions.md" + +# Variables and inputs +variables: + story_dir: "{config_source}:sprint_artifacts" + +standalone: true + +web_bundle: false diff --git a/src/modules/bmm/agents/analyst.agent.yaml b/src/modules/bmm/agents/analyst.agent.yaml index 5be26740..528f727e 100644 --- a/src/modules/bmm/agents/analyst.agent.yaml +++ b/src/modules/bmm/agents/analyst.agent.yaml @@ -43,6 +43,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/architect.agent.yaml b/src/modules/bmm/agents/architect.agent.yaml index 7b279b55..21d0c535 100644 --- a/src/modules/bmm/agents/architect.agent.yaml +++ b/src/modules/bmm/agents/architect.agent.yaml @@ -37,6 +37,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/pm.agent.yaml b/src/modules/bmm/agents/pm.agent.yaml index b90cafa3..359f6103 100644 --- a/src/modules/bmm/agents/pm.agent.yaml +++ b/src/modules/bmm/agents/pm.agent.yaml @@ -56,6 +56,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml index 30bd0d65..f5276837 100644 --- a/src/modules/bmm/agents/sm.agent.yaml +++ b/src/modules/bmm/agents/sm.agent.yaml @@ -67,6 +67,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/tea.agent.yaml b/src/modules/bmm/agents/tea.agent.yaml index 56fc7b3d..77224a1b 100644 --- a/src/modules/bmm/agents/tea.agent.yaml +++ b/src/modules/bmm/agents/tea.agent.yaml @@ -60,6 +60,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/tech-writer.agent.yaml b/src/modules/bmm/agents/tech-writer.agent.yaml index d9e5fb1c..1b4f11c0 100644 --- a/src/modules/bmm/agents/tech-writer.agent.yaml +++ b/src/modules/bmm/agents/tech-writer.agent.yaml @@ -68,6 +68,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/agents/ux-designer.agent.yaml b/src/modules/bmm/agents/ux-designer.agent.yaml index fc74757e..514c5874 100644 --- a/src/modules/bmm/agents/ux-designer.agent.yaml +++ b/src/modules/bmm/agents/ux-designer.agent.yaml @@ -33,6 +33,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md index 6e7ef2b0..a9dcb147 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md @@ -12,19 +12,13 @@ This workflow may reference: market research, brainstorming documents, user specified other inputs, or brownfield project documentation. -**Discovery Process** (execute for each referenced document): +**All input files are discovered and loaded automatically via the `discover_inputs` protocol in Step 0.5** -1. **Search for whole document first** - Use fuzzy file matching to find the complete document -2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md` -3. **If sharded version found**: - - Read `index.md` to understand the document structure - - Read ALL section files listed in the index - - Treat the combined content as if it were a single document -4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md` +After discovery completes, the following content variables will be available: -**Priority**: If both whole and sharded versions exist, use the whole document. - -**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions. +- `{research_content}` - Market research or domain research documents +- `{brainstorming_content}` - Brainstorming session outputs +- `{document_project_content}` - Brownfield project documentation (intelligently loaded via INDEX_GUIDED strategy) @@ -68,6 +62,10 @@ Product Brief is most valuable for Level 2+ projects, but can help clarify visio + + + + Welcome {user_name} warmly in {communication_language} diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml index 610d23b9..13524981 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml @@ -21,17 +21,21 @@ recommended_inputs: # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: research: whole: "{output_folder}/*research*.md" sharded: "{output_folder}/*research*/index.md" + load_strategy: "FULL_LOAD" brainstorming: whole: "{output_folder}/*brainstorm*.md" sharded: "{output_folder}/*brainstorm*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" # Module path and component files installed_path: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/product-brief" diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md index 64ae7297..172d2d88 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md @@ -211,8 +211,6 @@ Examples: special_requirements -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md index 9afa7052..f909083e 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md @@ -114,8 +114,6 @@ Work with the user to establish: Explore surprising data points together -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - sources_market_size @@ -239,7 +237,6 @@ For each major segment, research and define: - Purchasing frequency - Budget allocation -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml segment*profile*{{segment_number}} @@ -313,8 +310,7 @@ Use {{current_year}} in all searches. Dig deeper based on their interests -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml -competitor*analysis*{{competitor_name}} +competitor-analysis-{{competitor_name}} @@ -437,7 +433,6 @@ For each opportunity: - Risk assessment - Success criteria -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml market_opportunities diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md index 8cfeface..fa191acc 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md @@ -143,8 +143,6 @@ Each of these is popular for different reasons. Let me know if you want me to ex -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - technology_options @@ -221,7 +219,6 @@ Each of these is popular for different reasons. Let me know if you want me to ex - Training costs - Total cost of ownership estimate -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml tech*profile*{{option_number}} @@ -392,8 +389,6 @@ Research and document: - Contingency options if primary choice doesn't work - Exit strategy considerations -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - recommendations diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md index 8d614d73..85a4afcc 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md @@ -51,10 +51,15 @@ + + +After discovery, these content variables are available: {prd_content}, {product_brief_content}, {epics_content}, {brainstorming_content}, {document_project_content} + + A UX designer must understand the WHY before designing the HOW -Attempt to load context documents using fuzzy matching: - PRD: {prd_file} - Product Brief: {brief_file} - Brainstorming: {brainstorm_file} +Review loaded context from Step 0.5: {prd_content}, {product_brief_content}, {epics_content}, {brainstorming_content} diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml index 5bf75a05..f7a082a1 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml @@ -25,25 +25,31 @@ brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation. # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: prd: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" + load_strategy: "FULL_LOAD" product_brief: whole: "{output_folder}/*brief*.md" sharded: "{output_folder}/*brief*/index.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded: "{output_folder}/*epic*/index.md" + load_strategy: "FULL_LOAD" brainstorming: whole: "{output_folder}/*brainstorm*.md" sharded: "{output_folder}/*brainstorm*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" # Module path and component files installed_path: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design" diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md index 90f78d6e..34b9735a 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md @@ -17,7 +17,7 @@ ### Core Sections Present - [ ] Executive Summary with vision alignment -- [ ] Product magic essence clearly articulated +- [ ] Product differentiator clearly articulated - [ ] Project classification (type, domain, complexity) - [ ] Success criteria defined - [ ] Product scope (MVP, Growth, Vision) clearly delineated @@ -38,7 +38,7 @@ - [ ] No unfilled template variables ({{variable}}) - [ ] All variables properly populated with meaningful content -- [ ] Product magic woven throughout (not just stated once) +- [ ] Product differentiator reflected throughout (not just stated once) - [ ] Language is clear, specific, and measurable - [ ] Project type correctly identified and sections match - [ ] Domain complexity appropriately addressed @@ -210,7 +210,7 @@ ### Alignment Checks - [ ] Success metrics in PRD align with story outcomes -- [ ] Product magic articulated in PRD reflected in epic goals +- [ ] Product differentiator articulated in PRD reflected in epic goals - [ ] Technical preferences in PRD align with story implementation hints - [ ] Scope boundaries consistent across all documents diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md index bc05342b..69012701 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md @@ -11,10 +11,24 @@ This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the [PRD](./PRD.md) into implementable stories. +**Living Document Notice:** This is the initial version. It will be updated after UX Design and Architecture workflows add interaction and technical details to stories. + {{epics_summary}} --- +## Functional Requirements Inventory + +{{fr_inventory}} + +--- + +## FR Coverage Map + +{{fr_coverage_map}} + +--- + ## Epic {{N}}: {{epic_title_N}} @@ -49,4 +63,18 @@ So that {{value_benefit}}. --- +## FR Coverage Matrix + +{{fr_coverage_matrix}} + +--- + +## Summary + +{{epic_breakdown_summary}} + +--- + _For implementation: Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown._ + +_This document will be updated after UX Design and Architecture workflows to incorporate interaction details and technical decisions._ diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md index 322a9947..9d227ff0 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md @@ -4,6 +4,11 @@ You MUST have already loaded and processed: {installed_path}/workflow.yaml This workflow transforms requirements into BITE-SIZED STORIES for development agents EVERY story must be completable by a single dev agent in one focused session +BMAD METHOD WORKFLOW POSITION: This is the FIRST PASS at epic breakdown +After this workflow: UX Design will add interaction details → UPDATE epics.md +After UX: Architecture will add technical decisions → UPDATE epics.md AGAIN +Phase 4 Implementation pulls context from: PRD + epics.md + UX + Architecture +This is a LIVING DOCUMENT that evolves through the BMad Method workflow chain Communicate all responses in {communication_language} and adapt to {user_skill_level} Generate all documents in {document_output_language} LIVING DOCUMENT: Write to epics.md continuously as you work - never wait until the end @@ -20,21 +25,49 @@ Load required documents (fuzzy match, handle both whole and sharded): - domain-brief.md (if exists) - product-brief.md (if exists) +**CRITICAL - PRD FRs Are Now Flat and Strategic:** + +The PRD contains FLAT, capability-level functional requirements (FR1, FR2, FR3...). +These are STRATEGIC (WHAT capabilities exist), NOT tactical (HOW they're implemented). + +Example PRD FRs: + +- FR1: Users can create accounts with email or social authentication +- FR2: Users can log in securely and maintain sessions +- FR6: Users can create, edit, and delete content items + +**Your job in THIS workflow:** + +1. Map each FR to one or more epics +2. Break each FR into stories with DETAILED acceptance criteria +3. Add ALL the implementation details that were intentionally left out of PRD + Extract from PRD: -- All functional requirements +- ALL functional requirements (flat numbered list) - Non-functional requirements - Domain considerations and compliance needs - Project type and complexity - MVP vs growth vs vision scope boundaries - -Understand the context: - -- What makes this product special (the magic) +- Product differentiator (what makes it special) - Technical constraints - User types and their goals -- Success criteria - +- Success criteria + +**Create FR Inventory:** + +List all FRs to ensure coverage: + +- FR1: [description] +- FR2: [description] +- ... +- FRN: [description] + +This inventory will be used to validate complete coverage in Step 4. + + +fr_inventory + Analyze requirements and identify natural epic boundaries @@ -76,18 +109,56 @@ Present proposed epic structure showing: - Epic titles with clear value statements - High-level scope of each epic +- **FR COVERAGE MAP: Which FRs does each epic address?** + - Example: "Epic 1 (Foundation): Covers infrastructure needs for all FRs" + - Example: "Epic 2 (User Management): FR1, FR2, FR3, FR4, FR5" + - Example: "Epic 3 (Content System): FR6, FR7, FR8, FR9" - Suggested sequencing -- Why this grouping makes sense +- Why this grouping makes sense + +**Validate FR Coverage:** + +Check that EVERY FR from Step 1 inventory is mapped to at least one epic. +If any FRs are unmapped, add them now or explain why they're deferred. + epics_summary -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml +fr_coverage_map - + Break down Epic {{N}} into small, implementable stories INTENT: Create stories sized for single dev agent completion +**CRITICAL - ALTITUDE SHIFT FROM PRD:** + +PRD FRs are STRATEGIC (WHAT capabilities): + +- ✅ "Users can create accounts" + +Epic Stories are TACTICAL (HOW it's implemented): + +- Email field with RFC 5322 validation +- Password requirements: 8+ chars, 1 uppercase, 1 number, 1 special +- Password strength meter with visual feedback +- Email verification within 15 minutes +- reCAPTCHA v3 integration +- Account creation completes in < 2 seconds +- Mobile responsive with 44x44px touch targets +- WCAG 2.1 AA compliant + +**THIS IS WHERE YOU ADD ALL THE DETAILS LEFT OUT OF PRD:** + +- UI specifics (exact field counts, validation rules, layout details) +- Performance targets (< 2s, 60fps, etc.) +- Technical implementation hints (libraries, patterns, APIs) +- Edge cases (what happens when...) +- Validation rules (regex patterns, constraints) +- Error handling (specific error messages, retry logic) +- Accessibility requirements (ARIA labels, keyboard nav, screen readers) +- Platform specifics (mobile responsive, browser support) + For each epic, generate: - Epic title as `epic_title_{{N}}` @@ -138,32 +209,84 @@ For each story in epic {{N}}, output variables following this pattern: For each story M in epic {{N}}, generate story content story-title-{{N}}-{{M}} -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - + Review the complete epic breakdown for quality and completeness -Validate: +**Validate FR Coverage:** + +Create FR Coverage Matrix showing each FR mapped to epic(s) and story(ies): + +- FR1: [description] → Epic X, Story X.Y +- FR2: [description] → Epic X, Story X.Z +- FR3: [description] → Epic Y, Story Y.A +- ... +- FRN: [description] → Epic Z, Story Z.B + +Confirm: EVERY FR from Step 1 inventory is covered by at least one story. +If any FRs are missing, add stories now. + +**Validate Story Quality:** - All functional requirements from PRD are covered by stories -- Epic 1 establishes proper foundation -- All stories are vertically sliced -- No forward dependencies exist +- Epic 1 establishes proper foundation (if greenfield) +- All stories are vertically sliced (deliver complete functionality, not just one layer) +- No forward dependencies exist (only backward references) - Story sizing is appropriate for single-session completion - BDD acceptance criteria are clear and testable +- Details added (what was missing from PRD FRs: UI specifics, performance targets, etc.) - Domain/compliance requirements are properly distributed - Sequencing enables incremental value delivery +**BMad Method Next Steps:** + +This epic breakdown is the INITIAL VERSION. It will be updated as you progress: + +1. **After UX Design Workflow:** + - UX Designer will design interactions for capabilities + - UPDATE story acceptance criteria with UX specs (mockup references, flow details) + - Add interaction patterns, visual design decisions, responsive breakpoints + +2. **After Architecture Workflow:** + - Architect will define technical implementation approach + - UPDATE story technical notes with architecture decisions + - Add references to data models, API contracts, tech stack choices, deployment patterns + +3. **During Phase 4 Implementation:** + - Each story pulls context from: PRD (why) + epics.md (what/how) + UX (interactions) + Architecture (technical) + - Stories may be further refined as implementation uncovers edge cases + - This document remains the single source of truth for story details + Confirm with {user_name}: - Epic structure makes sense -- Story breakdown is actionable -- Dependencies are clear -- BDD format provides clarity -- Ready for architecture and implementation phases +- All FRs covered by stories (validated via coverage matrix) +- Story breakdown is actionable with detailed acceptance criteria +- Ready for UX Design workflow (next BMad Method step) + epic_breakdown_summary +fr_coverage_matrix + +**✅ Epic Breakdown Complete (Initial Version)** + +**Created:** epics.md with epic and story breakdown + +**FR Coverage:** All functional requirements from PRD mapped to stories (see coverage matrix in document) + +**Next Steps in BMad Method:** + +1. **UX Design** (if UI exists) - Run: `workflow ux-design` + → Will add interaction details to stories in epics.md + +2. **Architecture** - Run: `workflow create-architecture` + → Will add technical details to stories in epics.md + +3. **Phase 4 Implementation** - Stories ready for context assembly + +**Important:** This is a living document that will be updated as you progress through the workflow chain. The epics.md file will evolve with UX and Architecture inputs before implementation begins. + diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml index 04326ea8..f3ac0224 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml @@ -1,6 +1,6 @@ # Epic and Story Decomposition Workflow name: create-epics-and-stories -description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents" +description: "Transform PRD requirements into bite-sized stories organized into deliverable functional epics. This workflow takes a Product Requirements Document (PRD) and breaks it down into epics and user stories that can be easily assigned to development teams. It ensures that all functional requirements are captured in a structured format, making it easier for teams to understand and implement the necessary features." author: "BMad" # Critical variables from config @@ -25,11 +25,9 @@ input_file_patterns: prd: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" - product_brief: whole: "{output_folder}/*product*brief*.md" sharded: "{output_folder}/*product*brief*/index.md" - domain_brief: whole: "{output_folder}/*domain*brief*.md" sharded: "{output_folder}/*domain*brief*/index.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md index ba9d0322..b724241c 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md @@ -6,7 +6,7 @@ Communicate all responses in {communication_language} and adapt deeply to {user_skill_level} Generate all documents in {document_output_language} LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end -GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section +GUIDING PRINCIPLE: Identify what makes this product special and ensure it's reflected throughout the PRD Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically @@ -44,10 +44,15 @@ PRD is for BMad Method and Enterprise Method tracks that need comprehensive requ + + +After discovery, these content variables are available: {product_brief_content}, {research_content}, {document_project_content} + + Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT: 1. Check workflow-status.yaml for project_context (if exists) -2. Look for existing documents (Product Brief, Domain Brief, research) +2. Review loaded content: {product_brief_content}, {research_content}, {document_project_content} (auto-loaded in Step 0.5) 3. Detect project type AND domain complexity Load references: @@ -69,9 +74,9 @@ B) Quick web search (basic) C) User provides context D) Continue with general knowledge -CAPTURE THE MAGIC EARLY with a few questions such as for example: "What excites you most about this product?", "What would make users love this?", "What's the moment that will make people go 'wow'?" +IDENTIFY WHAT MAKES IT SPECIAL early with questions such as: "What excites you most about this product?", "What would make users love this?", "What's the unique value or compelling moment?" -This excitement becomes the thread woven throughout the PRD. +This becomes a thread that connects throughout the PRD. vision_alignment project_classification @@ -81,7 +86,7 @@ This excitement becomes the thread woven throughout the PRD. domain_context_summary -product_magic_essence +product_differentiator product_brief_path domain_brief_path research_documents @@ -107,15 +112,14 @@ Make it specific: - NOT: "99.9% uptime" - BUT: "Zero data loss during critical operations" -Weave in the magic: +Connect to what makes the product special: -- "Success means users experience [that special moment] and [desired outcome]" +- "Success means users experience [key value moment] and achieve [desired outcome]" success_criteria business_metrics -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -140,7 +144,6 @@ For complex domains: mvp_scope growth_features vision_features -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -219,8 +222,8 @@ FOR SAAS B2B: [Continue for other types...] -Always relate back to the product magic: -"How does [requirement] enhance [the special thing]?" +Always connect requirements to product value: +"How does [requirement] support the product's core value proposition?" project_type_requirements @@ -253,8 +256,8 @@ Light touch on UX - not full design: "How should this feel to use?" "What's the vibe - professional, playful, minimal?" -Connect to the magic: -"The UI should reinforce [the special moment] through [design approach]" +Connect UX to product vision: +"The UI should reinforce [core value proposition] through [design approach]" ux_principles @@ -263,33 +266,148 @@ Connect to the magic: -Transform everything discovered into clear functional requirements +This section is THE CAPABILITY CONTRACT for all downstream work +UX designers will ONLY design what's listed here +Architects will ONLY support what's listed here +Epic breakdown will ONLY implement what's listed here +If a capability is missing from FRs, it will NOT exist in the final product -Pull together: +Before writing FRs, understand their PURPOSE and USAGE: -- Core features from scope -- Domain-mandated features -- Project-type specific needs -- Innovation requirements +**Purpose:** +FRs define WHAT capabilities the product must have. They are the complete inventory +of user-facing and system capabilities that deliver the product vision. -Organize by capability, not technology: +**How They Will Be Used:** -- User Management (not "auth system") -- Content Discovery (not "search algorithm") -- Team Collaboration (not "websockets") +1. UX Designer reads FRs → designs interactions for each capability +2. Architect reads FRs → designs systems to support each capability +3. PM reads FRs → creates epics and stories to implement each capability +4. Dev Agent reads assembled context → implements stories based on FRs -Each requirement should: +**Critical Property - COMPLETENESS:** +Every capability discussed in vision, scope, domain requirements, and project-specific +sections MUST be represented as an FR. Missing FRs = missing capabilities. -- Be specific and measurable -- Connect to user value -- Include acceptance criteria -- Note domain constraints +**Critical Property - ALTITUDE:** +FRs state WHAT capability exists and WHO it serves, NOT HOW it's implemented or +specific UI/UX details. Those come later from UX and Architecture. + -The magic thread: -Highlight which requirements deliver the special experience +Transform everything discovered into comprehensive functional requirements: + +**Coverage - Pull from EVERYWHERE:** + +- Core features from MVP scope → FRs +- Growth features → FRs (marked as post-MVP if needed) +- Domain-mandated features → FRs +- Project-type specific needs → FRs +- Innovation requirements → FRs +- Anti-patterns (explicitly NOT doing) → Note in FR section if needed + +**Organization - Group by CAPABILITY AREA:** +Don't organize by technology or layer. Group by what users/system can DO: + +- ✅ "User Management" (not "Authentication System") +- ✅ "Content Discovery" (not "Search Algorithm") +- ✅ "Team Collaboration" (not "WebSocket Infrastructure") + +**Format - Flat, Numbered List:** +Each FR is one clear capability statement: + +- FR#: [Actor] can [capability] [context/constraint if needed] +- Number sequentially (FR1, FR2, FR3...) +- Aim for 20-50 FRs for typical projects (fewer for simple, more for complex) + +**Altitude Check:** +Each FR should answer "WHAT capability exists?" NOT "HOW is it implemented?" + +- ✅ "Users can customize appearance settings" +- ❌ "Users can toggle light/dark theme with 3 font size options stored in LocalStorage" + +The second example belongs in Epic Breakdown, not PRD. + + + +**Well-written FRs at the correct altitude:** + +**User Account & Access:** + +- FR1: Users can create accounts with email or social authentication +- FR2: Users can log in securely and maintain sessions across devices +- FR3: Users can reset passwords via email verification +- FR4: Users can update profile information and preferences +- FR5: Administrators can manage user roles and permissions + +**Content Management:** + +- FR6: Users can create, edit, and delete content items +- FR7: Users can organize content with tags and categories +- FR8: Users can search content by keyword, tag, or date range +- FR9: Users can export content in multiple formats + +**Data Ownership (local-first products):** + +- FR10: All user data stored locally on user's device +- FR11: Users can export complete data at any time +- FR12: Users can import previously exported data +- FR13: System monitors storage usage and warns before limits + +**Collaboration:** + +- FR14: Users can share content with specific users or teams +- FR15: Users can comment on shared content +- FR16: Users can track content change history +- FR17: Users receive notifications for relevant updates + +**Notice:** +✅ Each FR is a testable capability +✅ Each FR is implementation-agnostic (could be built many ways) +✅ Each FR specifies WHO and WHAT, not HOW +✅ No UI details, no performance numbers, no technology choices +✅ Comprehensive coverage of capability areas + + +Generate the complete FR list by systematically extracting capabilities: + +1. MVP scope → extract all capabilities → write as FRs +2. Growth features → extract capabilities → write as FRs (note if post-MVP) +3. Domain requirements → extract mandatory capabilities → write as FRs +4. Project-type specifics → extract type-specific capabilities → write as FRs +5. Innovation patterns → extract novel capabilities → write as FRs + +Organize FRs by logical capability groups (5-8 groups typically). +Number sequentially across all groups (FR1, FR2... FR47). + + +SELF-VALIDATION - Before finalizing, ask yourself: + +**Completeness Check:** + +1. "Did I cover EVERY capability mentioned in the MVP scope section?" +2. "Did I include domain-specific requirements as FRs?" +3. "Did I cover the project-type specific needs (API/Mobile/SaaS/etc)?" +4. "Could a UX designer read ONLY the FRs and know what to design?" +5. "Could an Architect read ONLY the FRs and know what to support?" +6. "Are there any user actions or system behaviors we discussed that have no FR?" + +**Altitude Check:** + +1. "Am I stating capabilities (WHAT) or implementation (HOW)?" +2. "Am I listing acceptance criteria or UI specifics?" (Remove if yes) +3. "Could this FR be implemented 5 different ways?" (Good - means it's not prescriptive) + +**Quality Check:** + +1. "Is each FR clear enough that someone could test whether it exists?" +2. "Is each FR independent (not dependent on reading other FRs to understand)?" +3. "Did I avoid vague terms like 'good', 'fast', 'easy'?" (Use NFRs for quality attributes) + +COMPLETENESS GATE: Review your FR list against the entire PRD written so far. +Did you miss anything? Add it now before proceeding. + functional_requirements_complete -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -341,7 +459,6 @@ Skip categories that don't apply! Does this capture your product vision?" prd_summary -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml After PRD review and refinement complete: @@ -374,7 +491,7 @@ Generate epic_details for the epics breakdown document -product_magic_summary +product_value_summary Load the FULL file: {status_file} @@ -401,7 +518,7 @@ Your product requirements are documented and ready for implementation. 3. **Architecture** (Recommended) Run: `workflow create-architecture` for technical architecture decisions -The magic of your product - {product_magic_summary} - is woven throughout the PRD and will guide all subsequent work. +What makes your product special - {product_value_summary} - is captured throughout the PRD and will guide all subsequent work. diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md index 3e23607a..3558baed 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md @@ -12,7 +12,7 @@ ### What Makes This Special -{{product_magic_essence}} +{{product_differentiator}} --- @@ -232,6 +232,6 @@ Requirements must be decomposed into epics and bite-sized stories (200k context --- -_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_ +_This PRD captures the essence of {{project_name}} - {{product_value_summary}}_ _Created through collaborative discovery between {{user_name}} and AI facilitator._ 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 d24b946f..f7873c76 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml @@ -31,17 +31,21 @@ recommended_inputs: # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: product_brief: whole: "{output_folder}/*brief*.md" sharded: "{output_folder}/*brief*/index.md" + load_strategy: "FULL_LOAD" research: whole: "{output_folder}/*research*.md" sharded: "{output_folder}/*research*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" standalone: true @@ -66,7 +70,7 @@ web_bundle: # Task dependencies (referenced in instructions.md) - "{bmad_folder}/core/tasks/workflow.xml" - - "{bmad_folder}/core/tasks/adv-elicit.xml" - - "{bmad_folder}/core/tasks/adv-elicit-methods.csv" + - "{bmad_folder}/core/tasks/advanced-elicitation.xml" + - "{bmad_folder}/core/tasks/advanced-elicitation-methods.csv" child_workflows: - create-epics-and-stories: "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml" diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md index 879d34a7..fbca61b7 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md @@ -100,14 +100,19 @@ Let's build your tech-spec! + + +After discovery, these content variables are available: {product_brief_content}, {research_content}, {document_project_content} + + Welcome {user_name} warmly and explain what we're about to do: -"I'm going to gather all available context about your project before we dive into the technical spec. This includes: +"I'm going to gather all available context about your project before we dive into the technical spec. The following content has been auto-loaded: -- Any existing documentation (product briefs, research) -- Brownfield codebase analysis (if applicable) +- Product briefs and research: {product_brief_content}, {research_content} +- Brownfield codebase documentation: {document_project_content} (loaded via INDEX_GUIDED strategy) - Your project's tech stack and dependencies - Existing code patterns and structure @@ -119,13 +124,13 @@ This ensures the tech-spec is grounded in reality and gives developers everythin Search for and load (using dual-strategy: whole first, then sharded): 1. **Product Brief:** - - Search pattern: {output-folder}/_brief_.md - - Sharded: {output-folder}/_brief_/index.md + - Search pattern: {output*folder}/\_brief*.md + - Sharded: {output*folder}/\_brief*/index.md - If found: Load completely and extract key context 2. **Research Documents:** - - Search pattern: {output-folder}/_research_.md - - Sharded: {output-folder}/_research_/index.md + - Search pattern: {output*folder}/\_research*.md + - Sharded: {output*folder}/\_research*/index.md - If found: Load completely and extract insights 3. **Document-Project Output (CRITICAL for brownfield):** @@ -801,8 +806,6 @@ What to watch after deployment: rollback_plan monitoring_approach -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml - diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml index 3cdea776..a96a01b6 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml @@ -38,15 +38,19 @@ sprint_artifacts: "{output_folder}/sprint_artifacts" # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: product_brief: whole: "{output_folder}/*brief*.md" sharded: "{output_folder}/*brief*/index.md" + load_strategy: "FULL_LOAD" research: whole: "{output_folder}/*research*.md" sharded: "{output_folder}/*research*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" standalone: true diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md index ee71305e..26ac3d5d 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md @@ -75,19 +75,23 @@ Please talk to the PM Agent to run the Create PRD workflow first to define your - - Load the PRD using fuzzy matching: {prd_file}, if the PRD is multiple files in a folder, load the index file and all files associated with the PRD - Load epics file using fuzzy matching: {epics_file} + + +After discovery, these content variables are available: {prd_content}, {epics_content}, {ux_design_content}, {document_project_content} + -Check for UX specification using fuzzy matching: -Attempt to locate: {ux_spec_file} - -Load UX spec and extract architectural implications: - Component complexity (simple forms vs rich interactions) - Animation/transition requirements - Real-time update needs (live data, collaborative features) - Platform-specific UI requirements - Accessibility standards (WCAG compliance level) - Responsive design breakpoints - Offline capability requirements - Performance expectations (load times, interaction responsiveness) + + Review loaded PRD: {prd_content} (auto-loaded in Step 0.5 - handles both whole and sharded documents) + Review loaded epics: {epics_content} + +Check for UX specification: + +Extract architectural implications from {ux_design_content}: - Component complexity (simple forms vs rich interactions) - Animation/transition requirements - Real-time update needs (live data, collaborative features) - Platform-specific UI requirements - Accessibility standards (WCAG compliance level) - Responsive design breakpoints - Offline capability requirements - Performance expectations (load times, interaction responsiveness) -Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned +Extract and understand from {prd_content}: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features @@ -355,7 +359,6 @@ Provided by Starter: {{yes_if_from_starter}} decision_record -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -385,7 +388,6 @@ Provided by Starter: {{yes_if_from_starter}} project_structure -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -459,7 +461,6 @@ Provided by Starter: {{yes_if_from_starter}} novel_pattern_designs -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -552,7 +553,6 @@ Enforcement: "All agents MUST follow this pattern" implementation_patterns -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml @@ -606,7 +606,6 @@ Enforcement: "All agents MUST follow this pattern" architecture_document -{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml index 9dafe183..f3920b19 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml @@ -14,18 +14,23 @@ date: system-generated # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: prd: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded: "{output_folder}/*epic*/index.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" sharded: "{output_folder}/*ux*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/index.md" + load_strategy: "INDEX_GUIDED" # Module path and component files installed_path: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture" @@ -60,7 +65,7 @@ web_bundle: pattern_categories: "{bmad_folder}/bmm/workflows/3-solutioning/architecture/pattern-categories.csv" # Task dependencies - adv_elicit_task: "{bmad_folder}/core/tasks/adv-elicit.xml" + adv_elicit_task: "{bmad_folder}/core/tasks/advanced-elicitation.xml" # Default configuration values (can be overridden during bundle setup) defaults: @@ -87,5 +92,5 @@ web_bundle: # Task dependencies (referenced in instructions.md) - "{bmad_folder}/core/tasks/workflow.xml" - - "{bmad_folder}/core/tasks/adv-elicit.xml" - - "{bmad_folder}/core/tasks/adv-elicit-methods.csv" + - "{bmad_folder}/core/tasks/advanced-elicitation.xml" + - "{bmad_folder}/core/tasks/advanced-elicitation-methods.csv" diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md index 3b06b0fd..7891d6a4 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md @@ -55,31 +55,36 @@ project_context - -Search the {output_folder} for relevant planning and solutioning documents + + +After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content} + -Locate: + +Review the content loaded by Step 0.5 and create an inventory -- Product Requirements Document (PRD) -- Architecture -- Epic and story breakdowns -- UX Design artifacts if the active path includes UX workflow -- Any supplementary planning documents +Inventory of available documents: + +- PRD: {prd_content} (loaded if available) +- Architecture: {architecture_content} (loaded if available) +- Epics: {epics_content} (loaded if available) +- UX Design: {ux_design_content} (loaded if available) +- Tech Spec: {tech_spec_content} (loaded if available, Quick Flow track) +- Brownfield docs: {document_project_content} (loaded via INDEX_GUIDED if available) -Create an inventory of found documents with: +For each loaded document, extract: - Document type and purpose -- File path and last modified date -- Brief description of what each contains -- Any missing expected documents flagged as potential issues +- Brief description of what it contains +- Flag any expected documents that are missing as potential issues document_inventory -Load and thoroughly analyze each discovered document to extract: +Thoroughly analyze each loaded document to extract: - Core requirements and success criteria - Architectural decisions and constraints - Technical implementation approaches diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml index aad5b0f6..cb3fb2d7 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml @@ -35,24 +35,31 @@ recommended_inputs: # Smart input file references - handles both whole docs and sharded docs # Priority: Whole document first, then sharded version +# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED) input_file_patterns: prd: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/index.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded: "{output_folder}/*epic*/index.md" + load_strategy: "FULL_LOAD" architecture: whole: "{output_folder}/*architecture*.md" sharded: "{output_folder}/*architecture*/index.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" sharded: "{output_folder}/*ux*/index.md" + load_strategy: "FULL_LOAD" tech_spec: whole: "{output_folder}/*tech-spec*.md" sharded: "{output_folder}/*tech-spec*/index.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md index 6ca6b7e0..59b6ca6c 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md @@ -19,34 +19,6 @@ - Document Discovery - Selective Epic Loading - - **Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded. - - **Epic Discovery Process (SELECTIVE OPTIMIZATION):** - - 1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3) - 2. **Check for sharded version**: Look for `epics/index.md` - 3. **If sharded version found**: - - Read `index.md` to understand structure - - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) - - DO NOT load all epic files - only the one needed! - - This is the key efficiency optimization for large multi-epic projects - 4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic - - **Other Documents (architecture, ux-design) - Full Load:** - - 1. **Search for whole document first** - Use fuzzy file matching - 2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md` - 3. **If sharded version found**: - - Read `index.md` to understand structure - - Read ALL section files listed in the index - - Treat combined content as single document - 4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md` - - **Priority**: If both whole and sharded versions exist, use the whole document. - - **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories. Use {{story_path}} directly Read COMPLETE story file and parse sections @@ -117,6 +89,11 @@ HALT with message: "Unable to read story file" + + + After discovery, these content variables are available: {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} + + 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" @@ -125,6 +102,7 @@ Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}" Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. + Architecture and brownfield docs were pre-loaded in Step 1.5 as {architecture_content} and {document_project_content} diff --git a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml index e201b676..21621887 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml @@ -38,16 +38,20 @@ variables: input_file_patterns: architecture: whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/index.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/index.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded_index: "{output_folder}/*epic*/index.md" sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md b/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md index 5ab184aa..2adbb321 100644 --- a/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md @@ -27,6 +27,11 @@ HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." + + + After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content} + + Load and execute the systematic analysis from: {checklist} Work through each checklist section interactively with the user diff --git a/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml index 256d5f8a..6b4bbcb4 100644 --- a/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml @@ -10,6 +10,35 @@ communication_language: "{config_source}:communication_language" user_skill_level: "{config_source}:user_skill_level" document_output_language: "{config_source}:document_output_language" date: system-generated +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: Load project context for impact analysis +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/*.md" + load_strategy: "FULL_LOAD" + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec*.md" + load_strategy: "FULL_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course" template: false diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md index d5beb610..3105620c 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md @@ -13,11 +13,15 @@ Resolve variables from config_source: story_dir (sprint_artifacts), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable. Create {{story_dir}} if it does not exist Resolve installed component paths from workflow.yaml: template, instructions, validation - Resolve recommended inputs if present: epics_file, prd_file, architecture_file Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. - + + + After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content}, {document_project_content} + + + PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development Find the previous completed story to extract dev agent learnings and review findings: diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index 3f06e70a..a7732379 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -8,7 +8,8 @@ output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" date: system-generated -story_dir: "{config_source}:sprint_artifacts" +sprint_artifacts: "{config_source}:sprint_artifacts" +story_dir: "{sprint_artifacts}" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story" @@ -18,7 +19,7 @@ validation: "{installed_path}/checklist.md" # Variables and inputs variables: - sprint_status: "{config_source}:sprint_artifacts/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking + sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown prd_file: "{output_folder}/PRD.md" # Fallback for requirements architecture_file: "{output_folder}/architecture.md" # Optional architecture context @@ -40,21 +41,27 @@ default_output_file: "{story_dir}/{{story_key}}.md" input_file_patterns: prd: whole: "{output_folder}/*prd*.md" - sharded: "{output_folder}/*prd*/index.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" tech_spec: whole: "{output_folder}/tech-spec.md" + load_strategy: "FULL_LOAD" architecture: whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/index.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/index.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded_index: "{output_folder}/*epic*/index.md" sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" document_project: sharded: "{output_folder}/index.md" + load_strategy: "INDEX_GUIDED" standalone: true 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 5f7d1304..26b05ad9 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md @@ -39,7 +39,7 @@ 1. Run `story-context` to generate context file and mark drafted stories as ready 2. Run `story-ready` to quickly mark drafted stories as ready without generating context 3. Run `create-story` if no incomplete stories are drafted yet -4. Check {output-folder}/sprint-status.yaml to see current sprint status +4. Check {output_folder}/sprint-status.yaml to see current sprint status HALT @@ -72,6 +72,11 @@ Proceeding with story file only. For better context, consider running `story-con ASK user to clarify or HALT + + + After discovery, these content variables are available: {architecture_content}, {tech_spec_content}, {ux_design_content}, {epics_content} (selective load), {document_project_content} + + Determine if this is a fresh start or continuation after code review 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 8ed37943..3cc85e25 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml @@ -15,6 +15,33 @@ 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.xml") context_file: "{story_dir}/{{story_key}}.context.xml" +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" + +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: Load necessary context for story implementation +input_file_patterns: + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" + tech_spec: + whole: "{output_folder}/tech-spec*.md" + sharded: "{sprint_artifacts}/tech-spec-epic-*.md" + load_strategy: "SELECTIVE_LOAD" + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" + document_project: + sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story" diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md index c70cf6f1..12857011 100644 --- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md @@ -9,34 +9,6 @@ - Document Discovery - Selective Epic Loading - - **Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded. - - **Epic Discovery Process (SELECTIVE OPTIMIZATION):** - - 1. **Determine which epic** you need (epic_num from {sprint_status} or user input) - 2. **Check for sharded version**: Look for `epics/index.md` - 3. **If sharded version found**: - - Read `index.md` to understand structure - - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) - - DO NOT load all epic files - only the one needed! - - This is the key efficiency optimization for large multi-epic projects - 4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic - - **Other Documents (prd, gdd, architecture, ux-design) - Full Load:** - - 1. **Search for whole document first** - Use fuzzy file matching - 2. **Check for sharded version** - If whole document not found, look for `{doc-name}/*.*` - 3. **If sharded version found**: - - Read `index.md` to understand structure - - Read ALL section files listed in the index - - Treat combined content as single document - 4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md` - - **Priority**: If both whole and sharded versions exist, use the whole document. - - **UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories. Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths. ask the user for file paths. HALT and wait for docs to proceed @@ -79,10 +51,15 @@ No epics with status "backlog" found in sprint-status.yaml. - Extract {{epic_title}} from PRD based on {{epic_id}}. Resolve output file path using workflow variables and initialize by writing the template. + + + After discovery, these content variables are available: {prd_content}, {gdd_content}, {architecture_content}, {ux_design_content}, {epics_content} (will load only epic-{{epic_id}}.md if sharded), {document_project_content} + Extract {{epic_title}} from {prd_content} or {epics_content} based on {{epic_id}}. + + Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1) Get current status value if epic exists diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml index 4c37253c..1594aeec 100644 --- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml @@ -17,22 +17,28 @@ sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint- input_file_patterns: prd: whole: "{output_folder}/*prd*.md" - sharded: "{output_folder}/*prd*/index.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" gdd: whole: "{output_folder}/*gdd*.md" - sharded: "{output_folder}/*gdd*/index.md" + sharded: "{output_folder}/*gdd*/*.md" + load_strategy: "FULL_LOAD" architecture: whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/index.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/index.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded_index: "{output_folder}/*epic*/index.md" sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" document_project: sharded: "{output_folder}/index.md" + load_strategy: "INDEX_GUIDED" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/epic-tech-context" diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index 70c2ff96..b85f44f3 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -6,7 +6,7 @@ Generate all documents in {document_output_language} -DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. + DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. FACILITATION NOTES: @@ -26,29 +26,6 @@ PARTY MODE PROTOCOL: - Show disagreements, diverse perspectives, authentic team dynamics -## 📚 Document Discovery - Selective Epic Loading - -**Strategy**: This workflow needs the completed epic, previous retrospective, and potentially architecture/PRD for context. - -**Epic Discovery (SELECTIVE LOAD):** - -1. Determine completed epic number (from {sprint_status_file} or user) -2. If sharded: Load ONLY `epic-{epic_num}.md` -3. If whole: Load complete epics file and extract relevant epic - -**Retrospective History:** - -1. Load previous epic's retrospective to check if lessons were applied -2. Pattern: `retrospectives/epic-{prev_num}-retro-*.md` - -**Supporting Documents (Full Load if needed):** - -1. Architecture: Check for whole document first, then sharded index + all sections -2. PRD: Same pattern as architecture -3. These provide additional context for understanding epic execution - -**Priority**: Whole document first, then sharded version. - @@ -179,6 +156,11 @@ Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for ret + + + After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content} + + @@ -382,7 +364,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what Attempt to load next epic using selective loading strategy: **Try sharded first (more specific):** -Check if file exists: {output-folder}/epic\*/epic-{{next_epic_num}}.md +Check if file exists: {output_folder}/epic\*/epic-{{next_epic_num}}.md Load {output_folder}/*epic*/epic-{{next_epic_num}}.md @@ -391,7 +373,7 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what **Fallback to whole document:** -Check if file exists: {output-folder}/epic\*.md +Check if file exists: {output_folder}/epic\*.md Load entire epics document diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index 20fe074e..9fa92bcd 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -27,16 +27,21 @@ input_file_patterns: whole: "{output_folder}/*epic*.md" sharded_index: "{output_folder}/*epic*/index.md" sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" previous_retrospective: pattern: "{sprint_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md" + load_strategy: "SELECTIVE_LOAD" architecture: whole: "{output_folder}/*architecture*.md" sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" prd: whole: "{output_folder}/*prd*.md" sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" document_project: sharded: "{output_folder}/*.md" + load_strategy: "INDEX_GUIDED" # Required files sprint_status_file: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md index 8126fde2..e7fd436b 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -43,6 +43,11 @@ Build complete inventory of all epics and stories from all epic files + + + After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy) + + For each epic found, create entries in this order: diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml index 948f9596..9ee85697 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml @@ -39,7 +39,8 @@ variables: input_file_patterns: epics: whole: "{output_folder}/*epic*.md" - sharded: "{output_folder}/*epic*/index.md" + sharded: "{output_folder}/*epic*/*.md" + load_strategy: "FULL_LOAD" # Output configuration default_output_file: "{status_file}" 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 f211a4fd..8e9bad2b 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -88,10 +88,15 @@ so_that + + + After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} + + - Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks. - Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs. - Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance. + Review loaded content from Step 1.5 for items relevant to this story's domain (use keywords from story title, ACs, and tasks). + Extract relevant sections from: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {document_project_content} + Note: Tech-Spec ({tech_spec_content}) is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance. For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md"). Add artifacts.docs entries with {path, title, section, snippet}: 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 964de956..f673d62d 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml @@ -12,7 +12,7 @@ document_output_language: "{config_source}:document_output_language" story_path: "{config_source}:sprint_artifacts/stories" date: system-generated sprint_artifacts: "{config_source}:sprint_artifacts" -sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-context" @@ -26,21 +26,27 @@ validation: "{installed_path}/checklist.md" input_file_patterns: prd: whole: "{output_folder}/*prd*.md" - sharded: "{output_folder}/*prd*/index.md" + sharded: "{output_folder}/*prd*/*.md" + load_strategy: "FULL_LOAD" tech_spec: whole: "{output_folder}/tech-spec.md" + load_strategy: "FULL_LOAD" architecture: whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/index.md" + sharded: "{output_folder}/*architecture*/*.md" + load_strategy: "FULL_LOAD" ux_design: whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/index.md" + sharded: "{output_folder}/*ux*/*.md" + load_strategy: "FULL_LOAD" epics: whole: "{output_folder}/*epic*.md" sharded_index: "{output_folder}/*epic*/index.md" sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + load_strategy: "SELECTIVE_LOAD" document_project: sharded: "{output_folder}/docs/index.md" + load_strategy: "INDEX_GUIDED" # Output configuration # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication") diff --git a/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml index ae782cc6..1b0108eb 100644 --- a/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml @@ -9,7 +9,8 @@ output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" date: system-generated -sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml" +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done" @@ -17,7 +18,7 @@ instructions: "{installed_path}/instructions.md" # Variables and inputs variables: - story_dir: "{config_source}:sprint_artifacts/stories" # Directory where stories are stored + story_dir: "{config_source}:sprint_artifacts" # Directory where stories are stored # Output configuration - no output file, just status updates default_output_file: "" diff --git a/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml index 96d11102..1370eecb 100644 --- a/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml @@ -9,7 +9,8 @@ output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" date: system-generated -sprint_status: "{output_folder}/sprint-status.yaml || {sprint_artifacts}/sprint-status.yaml" +sprint_artifacts: "{config_source}:sprint_artifacts" +sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Workflow components installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-ready" diff --git a/src/modules/bmm/workflows/document-project/checklist.md b/src/modules/bmm/workflows/document-project/checklist.md index 7515cfe7..636312b4 100644 --- a/src/modules/bmm/workflows/document-project/checklist.md +++ b/src/modules/bmm/workflows/document-project/checklist.md @@ -181,7 +181,7 @@ ### Missing Information (to note for user) -- *** +- ## Deep-Dive Mode Validation (if deep-dive was performed) diff --git a/src/modules/bmm/workflows/document-project/workflows/full-scan-instructions.md b/src/modules/bmm/workflows/document-project/workflows/full-scan-instructions.md index 3026e325..1340f75e 100644 --- a/src/modules/bmm/workflows/document-project/workflows/full-scan-instructions.md +++ b/src/modules/bmm/workflows/document-project/workflows/full-scan-instructions.md @@ -325,7 +325,7 @@ findings.batches_completed: [ Build API contracts catalog -IMMEDIATELY write to: {output-folder}/api-contracts-{part_id}.md +IMMEDIATELY write to: {output_folder}/api-contracts-{part_id}.md Validate document has all required sections Update state file with output generated PURGE detailed API data, keep only: "{{api_count}} endpoints documented" @@ -346,7 +346,7 @@ findings.batches_completed: [ Build database schema documentation -IMMEDIATELY write to: {output-folder}/data-models-{part_id}.md +IMMEDIATELY write to: {output_folder}/data-models-{part_id}.md Validate document completeness Update state file with output generated PURGE detailed schema data, keep only: "{{table_count}} tables documented" diff --git a/src/modules/bmm/workflows/workflow-status/init/instructions.md b/src/modules/bmm/workflows/workflow-status/init/instructions.md index d660563f..6cf8d14d 100644 --- a/src/modules/bmm/workflows/workflow-status/init/instructions.md +++ b/src/modules/bmm/workflows/workflow-status/init/instructions.md @@ -14,19 +14,19 @@ **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 {sprint_artifacts} - CHECK BOTH LOCATIONS - - Story files: {output-folder}/stories/*.md or \*\*/stories/*story\*.md + - Story files: {output_folder}/stories/*.md or \*\*/stories/*story\*.md - Sprint status: {output_folder}/sprint-status.yaml or {sprint_artifacts}/sprint-status.yaml - Existing workflow status: {default_output_file} or {sprint_artifacts}/bmm-workflow-status.yaml @@ -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") diff --git a/src/modules/cis/agents/brainstorming-coach.agent.yaml b/src/modules/cis/agents/brainstorming-coach.agent.yaml index 3a509be0..7a311b0a 100644 --- a/src/modules/cis/agents/brainstorming-coach.agent.yaml +++ b/src/modules/cis/agents/brainstorming-coach.agent.yaml @@ -23,6 +23,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/cis/agents/creative-problem-solver.agent.yaml b/src/modules/cis/agents/creative-problem-solver.agent.yaml index 84fa6663..2efd579a 100644 --- a/src/modules/cis/agents/creative-problem-solver.agent.yaml +++ b/src/modules/cis/agents/creative-problem-solver.agent.yaml @@ -23,6 +23,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/cis/agents/design-thinking-coach.agent.yaml b/src/modules/cis/agents/design-thinking-coach.agent.yaml index bee656f7..6726aa10 100644 --- a/src/modules/cis/agents/design-thinking-coach.agent.yaml +++ b/src/modules/cis/agents/design-thinking-coach.agent.yaml @@ -23,6 +23,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/cis/agents/innovation-strategist.agent.yaml b/src/modules/cis/agents/innovation-strategist.agent.yaml index 5d98db46..0d11653d 100644 --- a/src/modules/cis/agents/innovation-strategist.agent.yaml +++ b/src/modules/cis/agents/innovation-strategist.agent.yaml @@ -23,6 +23,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/src/modules/cis/agents/storyteller.agent.yaml b/src/modules/cis/agents/storyteller.agent.yaml index b5359ffc..78463eb7 100644 --- a/src/modules/cis/agents/storyteller.agent.yaml +++ b/src/modules/cis/agents/storyteller.agent.yaml @@ -23,6 +23,6 @@ agent: workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml" description: Consult with other expert agents from the party - - trigger: adv-elicit - exec: "{project-root}/{bmad_folder}/core/tasks/adv-elicit.xml" + - trigger: advanced-elicitation + exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" description: Advanced elicitation techniques to challenge the LLM to get better results diff --git a/tools/cli/bundlers/web-bundler.js b/tools/cli/bundlers/web-bundler.js index 5109daae..ea567c31 100644 --- a/tools/cli/bundlers/web-bundler.js +++ b/tools/cli/bundlers/web-bundler.js @@ -1108,7 +1108,7 @@ class WebBundler { * Include advanced elicitation files */ async includeAdvancedElicitationFiles(dependencies, processed, moduleName, warnings = []) { - const elicitationFiles = ['bmad/core/tasks/adv-elicit.xml', 'bmad/core/tasks/adv-elicit-methods.csv']; + const elicitationFiles = ['bmad/core/tasks/advanced-elicitation.xml', 'bmad/core/tasks/advanced-elicitation-methods.csv']; for (const filePath of elicitationFiles) { if (processed.has(filePath)) {