diff --git a/src/modules/bmb/agents/bmad-builder.agent.yaml b/src/modules/bmb/agents/bmad-builder.agent.yaml index 9cf6d623..278db62a 100644 --- a/src/modules/bmb/agents/bmad-builder.agent.yaml +++ b/src/modules/bmb/agents/bmad-builder.agent.yaml @@ -21,6 +21,10 @@ agent: # Menu items - triggers will be prefixed with * at build time # help and exit are auto-injected, don't define them here menu: + - trigger: audit-workflow + workflow: "{project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml" + description: Audit existing workflows for BMAD Core compliance and best practices + - trigger: convert workflow: "{project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml" description: Convert v4 or any other style task agent or template to a workflow diff --git a/src/modules/bmb/workflows/audit-workflow/checklist.md b/src/modules/bmb/workflows/audit-workflow/checklist.md new file mode 100644 index 00000000..4698c671 --- /dev/null +++ b/src/modules/bmb/workflows/audit-workflow/checklist.md @@ -0,0 +1,138 @@ +# Audit Workflow - Validation Checklist + +## Structure + +- [ ] workflow.yaml file loads without YAML syntax errors +- [ ] instructions.md file exists and is properly formatted +- [ ] template.md file exists (if document workflow) with valid markdown +- [ ] All critical headers present in instructions (workflow engine reference, workflow.yaml reference) +- [ ] Workflow type correctly identified (document/action/interactive/autonomous/meta) +- [ ] All referenced files actually exist at specified paths +- [ ] No placeholder text remains (like {TITLE}, {WORKFLOW_CODE}, TODO, etc.) + +## Standard Config Block + +- [ ] workflow.yaml contains `config_source` pointing to correct module config +- [ ] `output_folder` pulls from `{config_source}:output_folder` +- [ ] `user_name` pulls from `{config_source}:user_name` +- [ ] `communication_language` pulls from `{config_source}:communication_language` +- [ ] `date` is set to `system-generated` +- [ ] Config source uses {project-root} variable (not hardcoded path) +- [ ] Standard config comment present: "Critical variables from config" + +## Config Variable Usage + +- [ ] Instructions communicate in {communication_language} where appropriate +- [ ] Instructions address {user_name} in greetings or summaries where appropriate +- [ ] All file outputs write to {output_folder} or subdirectories (no hardcoded paths) +- [ ] Template includes {{user_name}} in metadata (optional for document workflows) +- [ ] Template includes {{date}} in metadata (optional for document workflows) +- [ ] Template does NOT use {{communication_language}} in headers (agent-only variable) +- [ ] No hardcoded language-specific text that should use {communication_language} +- [ ] Date used for agent date awareness (not confused with training cutoff) + +## YAML/Instruction/Template Alignment + +- [ ] Every workflow.yaml variable (excluding standard config) is used in instructions OR template +- [ ] No unused yaml fields present (bloat removed) +- [ ] No duplicate fields between top-level and web_bundle section +- [ ] All template variables ({{variable}}) have corresponding yaml definitions OR tags +- [ ] All tags have corresponding template variables (if document workflow) +- [ ] Template variables use snake_case naming convention +- [ ] Variable names are descriptive (not abbreviated like {{puj}} instead of {{primary_user_journey}}) +- [ ] No hardcoded values in instructions that should be yaml variables + +## Web Bundle Validation (if applicable) + +- [ ] web_bundle section present if workflow needs deployment +- [ ] All paths in web_bundle use bmad/-relative format (NOT {project-root}) +- [ ] No {config_source} variables in web_bundle section +- [ ] instructions file listed in web_bundle_files array +- [ ] template file listed in web_bundle_files (if document workflow) +- [ ] validation/checklist file listed in web_bundle_files (if exists) +- [ ] All data files (CSV, JSON, YAML) listed in web_bundle_files +- [ ] All called workflows have their .yaml files in web_bundle_files +- [ ] **CRITICAL**: If workflow invokes other workflows, existing_workflows field is present +- [ ] existing_workflows maps workflow variables to bmad/-relative paths correctly +- [ ] All files referenced in instructions tags listed in web_bundle_files +- [ ] No files listed in web_bundle_files that don't exist +- [ ] Web bundle metadata (name, description, author) matches top-level metadata + +## Template Validation (if document workflow) + +- [ ] Template variables match tags in instructions exactly +- [ ] All required sections present in template structure +- [ ] Template uses {{variable}} syntax (double curly braces) +- [ ] Template variables use snake_case (not camelCase or PascalCase) +- [ ] Standard metadata header format correct (optional usage of {{date}}, {{user_name}}) +- [ ] No placeholders remain in template (like {SECTION_NAME}) +- [ ] Template structure matches document purpose + +## Instructions Quality + +- [ ] Each step has n="X" attribute with sequential numbering +- [ ] Each step has goal="clear goal statement" attribute +- [ ] Optional steps marked with optional="true" +- [ ] Repeating steps have appropriate repeat attribute (repeat="3", repeat="for-each-X", repeat="until-approved") +- [ ] Conditional steps have if="condition" attribute +- [ ] XML tags used correctly (, , , , , ) +- [ ] Steps are focused (single goal per step) +- [ ] Instructions are specific with limits ("Write 1-2 paragraphs" not "Write about") +- [ ] Examples provided where helpful +- [ ] tags save checkpoints for document workflows +- [ ] Flow control is logical and clear + +## Bloat Detection + +- [ ] Bloat percentage under 10% (unused yaml fields / total fields) +- [ ] No commented-out variables that should be removed +- [ ] No duplicate metadata between sections +- [ ] No variables defined but never referenced +- [ ] No redundant configuration that duplicates web_bundle + +## Final Validation + +### Critical Issues (Must fix immediately) + +_List any critical issues found:_ + +- Issue 1: +- Issue 2: +- Issue 3: + +### Important Issues (Should fix soon) + +_List any important issues found:_ + +- Issue 1: +- Issue 2: +- Issue 3: + +### Cleanup Recommendations (Nice to have) + +_List any cleanup recommendations:_ + +- Recommendation 1: +- Recommendation 2: +- Recommendation 3: + +--- + +## Audit Summary + +**Total Checks:** 70 +**Passed:** **\_** / 70 +**Failed:** **\_** / 70 +**Pass Rate:** **\_**% + +**Recommendation:** + +- Pass Rate ≥ 95%: Excellent - Ready for production +- Pass Rate 85-94%: Good - Minor fixes needed +- Pass Rate 70-84%: Fair - Important issues to address +- Pass Rate < 70%: Poor - Significant work required + +--- + +**Audit Completed:** {{date}} +**Auditor:** Audit Workflow (BMAD v6) diff --git a/src/modules/bmb/workflows/audit-workflow/instructions.md b/src/modules/bmb/workflows/audit-workflow/instructions.md new file mode 100644 index 00000000..0daaeafb --- /dev/null +++ b/src/modules/bmb/workflows/audit-workflow/instructions.md @@ -0,0 +1,375 @@ +# Audit Workflow - Workflow Quality Audit Instructions + +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/audit-workflow/workflow.yaml + + + + +What is the path to the workflow you want to audit? (provide path to workflow.yaml or workflow folder) + +Load the workflow.yaml file from the provided path +Identify the workflow type (document, action, interactive, autonomous, meta) +List all associated files: + +- instructions.md (required for most workflows) +- template.md (if document workflow) +- checklist.md (if validation exists) +- Any data files referenced in yaml + +Load all discovered files + +Display summary: + +- Workflow name and description +- Type of workflow +- Files present +- Module assignment + + + +Check workflow.yaml for the standard config block: + +**Required variables:** + +- `config_source: "{project-root}/bmad/[module]/config.yaml"` +- `output_folder: "{config_source}:output_folder"` +- `user_name: "{config_source}:user_name"` +- `communication_language: "{config_source}:communication_language"` +- `date: system-generated` + +Validate each variable: + +**Config Source Check:** + +- [ ] `config_source` is defined +- [ ] Points to correct module config path +- [ ] Uses {project-root} variable + +**Standard Variables Check:** + +- [ ] `output_folder` pulls from config_source +- [ ] `user_name` pulls from config_source +- [ ] `communication_language` pulls from config_source +- [ ] `date` is set to system-generated + +Record any missing or incorrect config variables +config_issues + +If config issues found: +Add to issues list with severity: CRITICAL + + + +Extract all variables defined in workflow.yaml (excluding standard config block) +Scan instructions.md for variable usage: {variable_name} pattern +Scan template.md for variable usage: {{variable_name}} pattern (if exists) + +Cross-reference analysis: + +**For each yaml variable:** + +1. Is it used in instructions.md? (mark as INSTRUCTION_USED) +2. Is it used in template.md? (mark as TEMPLATE_USED) +3. Is it neither? (mark as UNUSED_BLOAT) + +**Special cases to ignore:** + +- Standard config variables (config_source, output_folder, user_name, communication_language, date) +- Workflow metadata (name, description, author) +- Path variables (installed_path, template, instructions, validation) +- Web bundle configuration (web_bundle block itself) + +Identify unused yaml fields (bloat) +Identify hardcoded values in instructions that should be variables +alignment_issues + +If unused variables found: +Add to issues list with severity: BLOAT + + + +Analyze instructions.md for proper config variable usage: + +**Communication Language Check:** + +- Search for phrases like "communicate in {communication_language}" +- Check if greetings/responses use language-aware patterns +- Verify NO usage of {{communication_language}} in template headers + +**User Name Check:** + +- Look for user addressing patterns using {user_name} +- Check if summaries or greetings personalize with {user_name} +- Verify optional usage in template metadata (not required) + +**Output Folder Check:** + +- Search for file write operations +- Verify all outputs go to {output_folder} or subdirectories +- Check for hardcoded paths like "/output/" or "/generated/" + +**Date Usage Check:** + +- Verify date is available for agent date awareness +- Check optional usage in template metadata +- Ensure no confusion between date and model training cutoff + +Record any improper config variable usage +config_usage_issues + +If config usage issues found: +Add to issues list with severity: IMPORTANT + + + +If workflow.yaml contains web_bundle section: + +Validate web_bundle structure: + +**Path Validation:** + +- [ ] All paths use bmad/-relative format (NOT {project-root}) +- [ ] No {config_source} variables in web_bundle section +- [ ] Paths match actual file locations + +**Completeness Check:** + +- [ ] instructions file listed in web_bundle_files +- [ ] template file listed (if document workflow) +- [ ] validation/checklist file listed (if exists) +- [ ] All data files referenced in yaml listed +- [ ] All files referenced in instructions listed + +**Workflow Dependency Scan:** +Scan instructions.md for tags +Extract workflow paths from invocations +Verify each called workflow.yaml is in web_bundle_files +**CRITICAL**: Check if existing_workflows field is present when workflows are invoked +If calls exist, existing_workflows MUST map workflow variables to paths +Example: If instructions use {core_brainstorming}, web_bundle needs: +existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml" + + +**File Reference Scan:** +Scan instructions.md for file references in tags +Check for CSV, JSON, YAML, MD files referenced +Verify all referenced files are in web_bundle_files + +Record any missing files or incorrect paths +web_bundle_issues + +If web_bundle issues found: +Add to issues list with severity: CRITICAL + +If no web_bundle section exists: +Note: "No web_bundle configured (may be intentional for local-only workflows)" + + + +Identify bloat patterns: + +**Unused YAML Fields:** + +- Variables defined but not used in instructions OR template +- Duplicate fields between top-level and web_bundle section +- Commented-out variables that should be removed + +**Hardcoded Values:** + +- File paths that should use {output_folder} +- Generic greetings that should use {user_name} +- Language-specific text that should use {communication_language} +- Static dates that should use {date} + +**Redundant Configuration:** + +- Variables that duplicate web_bundle fields +- Metadata repeated across sections + +Calculate bloat metrics: + +- Total yaml fields: {{total_yaml_fields}} +- Used fields: {{used_fields}} +- Unused fields: {{unused_fields}} +- Bloat percentage: {{bloat_percentage}}% + +Record all bloat items with recommendations +bloat_items + +If bloat detected: +Add to issues list with severity: CLEANUP + + + +Extract all template variables from template.md: {{variable_name}} pattern +Scan instructions.md for corresponding variable_name tags + +Cross-reference mapping: + +**For each template variable:** + +1. Is there a matching tag? (mark as MAPPED) +2. Is it a standard config variable? (mark as CONFIG_VAR - optional) +3. Is it unmapped? (mark as MISSING_OUTPUT) + +**For each tag:** + +1. Is there a matching template variable? (mark as USED) +2. Is it orphaned? (mark as UNUSED_OUTPUT) + +Verify variable naming conventions: + +- [ ] All template variables use snake_case +- [ ] Variable names are descriptive (not abbreviated) +- [ ] Standard config variables properly formatted + +Record any mapping issues +template_issues + +If template issues found: +Add to issues list with severity: IMPORTANT + + + +Compile all findings into a structured report + +Write audit report to {output_folder}/audit-report-{{workflow_name}}-{{date}}.md + +**Report Structure:** + +```markdown +# Workflow Audit Report + +**Workflow:** {{workflow_name}} +**Audit Date:** {{date}} +**Auditor:** Audit Workflow (BMAD v6) +**Workflow Type:** {{workflow_type}} + +--- + +## Executive Summary + +**Overall Status:** {{overall_status}} + +- Critical Issues: {{critical_count}} +- Important Issues: {{important_count}} +- Cleanup Recommendations: {{cleanup_count}} + +--- + +## 1. Standard Config Block Validation + +{{config_issues}} + +**Status:** {{config_status}} + +--- + +## 2. YAML/Instruction/Template Alignment + +{{alignment_issues}} + +**Variables Analyzed:** {{total_variables}} +**Used in Instructions:** {{instruction_usage_count}} +**Used in Template:** {{template_usage_count}} +**Unused (Bloat):** {{bloat_count}} + +--- + +## 3. Config Variable Usage + +{{config_usage_issues}} + +**Communication Language:** {{comm_lang_status}} +**User Name:** {{user_name_status}} +**Output Folder:** {{output_folder_status}} +**Date:** {{date_status}} + +--- + +## 4. Web Bundle Validation + +{{web_bundle_issues}} + +**Web Bundle Present:** {{web_bundle_exists}} +**Files Listed:** {{web_bundle_file_count}} +**Missing Files:** {{missing_files_count}} + +--- + +## 5. Bloat Detection + +{{bloat_items}} + +**Bloat Percentage:** {{bloat_percentage}}% +**Cleanup Potential:** {{cleanup_potential}} + +--- + +## 6. Template Variable Mapping + +{{template_issues}} + +**Template Variables:** {{template_var_count}} +**Mapped Correctly:** {{mapped_count}} +**Missing Mappings:** {{missing_mapping_count}} + +--- + +## Recommendations + +### Critical (Fix Immediately) + +{{critical_recommendations}} + +### Important (Address Soon) + +{{important_recommendations}} + +### Cleanup (Nice to Have) + +{{cleanup_recommendations}} + +--- + +## Validation Checklist + +Use this checklist to verify fixes: + +- [ ] All standard config variables present and correct +- [ ] No unused yaml fields (bloat removed) +- [ ] Config variables used appropriately in instructions +- [ ] Web bundle includes all dependencies +- [ ] Template variables properly mapped +- [ ] File structure follows v6 conventions + +--- + +## Next Steps + +1. Review critical issues and fix immediately +2. Address important issues in next iteration +3. Consider cleanup recommendations for optimization +4. Re-run audit after fixes to verify improvements + +--- + +**Audit Complete** - Generated by audit-workflow v1.0 +``` + +Display summary to {user_name} in {communication_language} +Provide path to full audit report + +Would you like to: + +- View the full audit report +- Fix issues automatically (invoke edit-workflow) +- Audit another workflow +- Exit + + +audit_report_path + + + diff --git a/src/modules/bmb/workflows/audit-workflow/workflow.yaml b/src/modules/bmb/workflows/audit-workflow/workflow.yaml new file mode 100644 index 00000000..5cd96f4b --- /dev/null +++ b/src/modules/bmb/workflows/audit-workflow/workflow.yaml @@ -0,0 +1,23 @@ +# Audit Workflow Configuration +name: "audit-workflow" +description: "Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmb/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Module path and component files +installed_path: "{project-root}/bmad/bmb/workflows/audit-workflow" +template: false +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Output configuration +default_output_file: "{output_folder}/audit-report-{{workflow_name}}-{{date}}.md" + +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows/convert-legacy/instructions.md b/src/modules/bmb/workflows/convert-legacy/instructions.md index d0ecf7ea..6709bebf 100644 --- a/src/modules/bmb/workflows/convert-legacy/instructions.md +++ b/src/modules/bmb/workflows/convert-legacy/instructions.md @@ -1,7 +1,8 @@ # Convert Legacy - v4 to v5 Conversion Instructions -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/convert-legacy/workflow.yaml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +Continue to Validation @@ -263,6 +278,17 @@ For Modules: - YOLO mode → autonomous flag or optional steps - Critical notices → workflow.yaml comments +When invoking create-workflow, the standard config block will be automatically added: + +```yaml +# Critical variables from config +config_source: '{project-root}/bmad/{{target_module}}/config.yaml' +output_folder: '{config_source}:output_folder' +user_name: '{config_source}:user_name' +communication_language: '{config_source}:communication_language' +date: system-generated +``` + workflow: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml inputs: @@ -272,6 +298,9 @@ For Modules: - template: {{generated_template_if_document}} +Verify the created workflow.yaml includes standard config block +Update converted instructions to use config variables where appropriate + Continue to Validation @@ -292,6 +321,17 @@ For Workflows: - [ ] Template variables match - [ ] File structure correct +**Standard Config Validation (Workflows):** + +- [ ] workflow.yaml contains standard config block: + - config_source defined + - output_folder, user_name, communication_language pulled from config + - date set to system-generated +- [ ] Converted instructions use config variables where appropriate +- [ ] Template includes config variables in metadata (if document workflow) +- [ ] No hardcoded paths that should use {output_folder} +- [ ] No generic greetings that should use {user_name} + For Modules: - [ ] All components converted @@ -315,6 +355,7 @@ For Modules: - Warnings or notes Save report to: {output_folder}/conversion-report-{{date}}.md +Inform {user_name} in {communication_language} that the conversion report has been generated diff --git a/src/modules/bmb/workflows/create-agent/instructions.md b/src/modules/bmb/workflows/create-agent/instructions.md index bd9ab6cb..1549d7c6 100644 --- a/src/modules/bmb/workflows/create-agent/instructions.md +++ b/src/modules/bmb/workflows/create-agent/instructions.md @@ -1,21 +1,23 @@ # Build Agent - Interactive Agent Builder Instructions -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-agent/workflow.yaml -Study YAML agent examples in: {project_root}/bmad/bmm/agents/ for patterns +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-agent/workflow.yaml +Study YAML agent examples in: {project-root}/bmad/bmm/agents/ for patterns +Communicate in {communication_language} throughout the agent creation process -Ask the user: "Do you want to brainstorm agent ideas first? [y/n]" +Do you want to brainstorm agent ideas first? [y/n] -If yes: +If yes: Invoke brainstorming workflow: {project-root}/bmad/core/workflows/brainstorming/workflow.yaml Pass context data: {installed_path}/brainstorm-context.md Wait for brainstorming session completion Use brainstorming output to inform agent identity and persona development in following steps -If no, proceed directly to Step 0. +If no: +Proceed directly to Step 0 brainstorming_results @@ -29,41 +31,32 @@ If no, proceed directly to Step 0. Understand the differences between Simple, Expert, and Module agents - + If brainstorming was completed in Step -1, reference those results to guide the conversation -Start with discovery: +Guide user to articulate their agent's core purpose, exploring the problems it will solve, tasks it will handle, target users, and what makes it special -**"What would you like your agent to help with?"** +As the purpose becomes clear, analyze the conversation to determine the appropriate agent type: -Listen to their vision and explore: +**Agent Type Decision Criteria:** -- What problems will it solve? -- What tasks will it handle? -- Who will interact with it? -- What makes this agent special? +- Simple Agent: Single-purpose, straightforward, self-contained +- Expert Agent: Domain-specific with knowledge base needs +- Module Agent: Complex with multiple workflows and system integration -As the purpose becomes clear, guide toward agent type: +Present your recommendation naturally, explaining why the agent type fits their described purpose and requirements -**"Based on what you've described, I'm thinking this could be..."** +**Path Determination:** -1. **Simple Agent** - "A focused, self-contained helper" (if single-purpose, straightforward) -2. **Expert Agent** - "A specialist with its own knowledge base" (if domain-specific with data needs) -3. **Module Agent** - "A full-featured system component" (if complex with multiple workflows) +If Module agent: +Discover which module system fits best (bmm, bmb, cis, or custom) +Store as {{target_module}} for path determination +Agent will be saved to: bmad/{{target_module}}/agents/ -Present the recommendation naturally: _"Given that your agent will [summarize purpose], a [type] agent would work perfectly because..."_ - -For Module agents, discover: - -- "Which module system would this fit best with?" (bmm, bmb, cis, or custom) -- Store as {{target_module}} for path determination -- Agent will be saved to: bmad/{{target_module}}/agents/ - -For Simple/Expert agents (standalone): - -- "This will be your personal agent, not tied to a module" -- Agent will be saved to: bmad/agents/{{agent-name}}/ -- All sidecar files will be in the same folder +If Simple/Expert agent (standalone): +Explain this will be their personal agent, not tied to a module +Agent will be saved to: bmad/agents/{{agent-name}}/ +All sidecar files will be in the same folder Determine agent location: @@ -71,92 +64,57 @@ For Simple/Expert agents (standalone): - Standalone Agent → bmad/agents/{{agent-name}}/{{agent-name}}.agent.yaml Keep agent naming/identity details for later - let them emerge naturally through the creation process + +agent_purpose_and_type - + If brainstorming was completed, weave personality insights naturally into the conversation -Now that we understand what the agent will do, let's discover who it is: +Guide user to envision the agent's personality by exploring how analytical vs creative, formal vs casual, and mentor vs peer vs assistant traits would make it excel at its job -**"Let's bring this agent to life! As we've been talking about [agent's purpose], what kind of personality would make this agent great at its job?"** +**Role Development:** +Let the role emerge from the conversation, guiding toward a clear 1-2 line professional title that captures the agent's essence +Example emerged role: "Strategic Business Analyst + Requirements Expert" -Explore through questions like: - -- "Should it be more analytical or creative?" -- "Formal and professional, or friendly and casual?" -- "Would it be better as a mentor, a peer, or an assistant?" - -As personality traits emerge, help shape them: - -**Role** - Let this emerge from the conversation: - -- "So it sounds like we're creating a [emerging role]..." -- Guide toward a 1-2 line professional title -- Example emerges: "Strategic Business Analyst + Requirements Expert" - -**Identity** - Build this through discovery: - -- "What kind of background would give it credibility?" -- "What specializations would be most valuable?" -- Let the 3-5 line identity form naturally -- Example emerges: "Senior analyst with deep expertise in market research..." +**Identity Development:** +Build the agent's identity through discovery of what background and specializations would give it credibility, forming a natural 3-5 line identity statement +Example emerged identity: "Senior analyst with deep expertise in market research..." +**Communication Style Selection:** Load the communication styles guide: {communication_styles} -**Communication Style** - Now for the fun part! +Based on the emerging personality, suggest 2-3 communication styles that would fit naturally, offering to show all options if they want to explore more -"I'm seeing this agent's personality really taking shape! For how it communicates, we could go with something..." - -Based on the emerging personality, suggest 2-3 styles that would fit naturally - -"...or would you like to see all the options?" +**Style Categories Available:** **Fun Presets:** -1. **Pulp Superhero** - "Strikes heroic poses! Speaks with dramatic flair! Every task is an epic adventure!" -2. **Film Noir Detective** - "The data came in like trouble on a rainy Tuesday. I had a hunch the bug was hiding in line 42..." -3. **Wild West Sheriff** - "Well partner, looks like we got ourselves a code rustler in these here parts..." -4. **Shakespearean Scholar** - "Hark! What bug through yonder codebase breaks?" -5. **80s Action Hero** - "I came here to debug code and chew bubblegum... and I'm all out of bubblegum." -6. **Pirate Captain** - "Ahoy! Let's plunder some data treasure from the database seas!" -7. **Wise Sage/Yoda** - "Refactor this code, we must. Strong with technical debt, it is." -8. **Game Show Host** - "Welcome back folks! It's time to spin the Wheel of Dependencies!" +1. Pulp Superhero - Dramatic flair, heroic, epic adventures +2. Film Noir Detective - Mysterious, noir dialogue, hunches +3. Wild West Sheriff - Western drawl, partner talk, frontier justice +4. Shakespearean Scholar - Elizabethan language, theatrical +5. 80s Action Hero - One-liners, macho, bubblegum +6. Pirate Captain - Ahoy, treasure hunting, nautical terms +7. Wise Sage/Yoda - Cryptic wisdom, inverted syntax +8. Game Show Host - Enthusiastic, game show tropes -**Professional Presets:** 9. **Analytical Expert** - "Systematic approach with data-driven insights. Clear hierarchical presentation." 10. **Supportive Mentor** - "Patient guidance with educational focus. Celebrates small wins." 11. **Direct Consultant** - "Straight to the point. No fluff. Maximum efficiency." 12. **Collaborative Partner** - "We'll tackle this together. Your ideas matter. Let's explore options." +**Professional Presets:** 9. Analytical Expert - Systematic, data-driven, hierarchical 10. Supportive Mentor - Patient guidance, celebrates wins 11. Direct Consultant - Straight to the point, efficient 12. Collaborative Partner - Team-oriented, inclusive -**Quirky Presets:** 13. **Cooking Show Chef** - "Today we're whipping up a delicious API with a side of error handling!" 14. **Sports Commentator** - "AND THE FUNCTION RETURNS TRUE! WHAT A PLAY! THE CROWD GOES WILD!" 15. **Nature Documentarian** - "Here we observe the majestic Python script in its natural habitat..." 16. **Time Traveler** - "In my timeline, this bug doesn't exist until Tuesday. We must prevent it!" 17. **Conspiracy Theorist** - "The bugs aren't random... they're CONNECTED. Follow the stack trace!" 18. **Zen Master** - "The code does not have bugs. The bugs have code. We are all one codebase." 19. **Star Trek Captain** - "Captain's Log, Stardate 2024.3: We've encountered a logic error in sector 7. Engaging debugging protocols. Make it so!" 20. **Soap Opera Drama** - "_gasp_ This variable... it's not what it seems! It's been NULL all along! _dramatic pause_ And the function that called it? It's its own PARENT!" 21. **Reality TV Contestant** - "I'm not here to make friends, I'm here to REFACTOR! _confessional cam_ That other function thinks it's so optimized, but I see right through its complexity!" +**Quirky Presets:** 13. Cooking Show Chef - Recipe metaphors, culinary terms 14. Sports Commentator - Play-by-play, excitement 15. Nature Documentarian - Wildlife documentary style 16. Time Traveler - Temporal references, timeline talk 17. Conspiracy Theorist - Everything is connected 18. Zen Master - Philosophical, paradoxical 19. Star Trek Captain - Space exploration protocols 20. Soap Opera Drama - Dramatic reveals, gasps 21. Reality TV Contestant - Confessionals, drama -Or describe your own unique style! (3-5 lines) +If user wants to see more examples or create custom styles, show relevant sections from {communication_styles} guide and help them craft their unique style -If user wants to see more examples or learn how to create custom styles: -Show relevant sections from {communication_styles} guide -Help them craft their unique communication style - -**Principles** - These often reveal themselves through our conversation: - -"Based on everything we've discussed, what core principles should guide this agent's decisions?" - -Help them articulate 5-8 lines: - -- "From what you've said, it seems like this agent believes..." -- "I'm hearing that it values..." -- Shape into "I believe..." or "I operate..." statements -- Example emerges: "I believe that every business challenge has underlying root causes..." +**Principles Development:** +Guide user to articulate 5-8 core principles that should guide the agent's decisions, shaping their thoughts into "I believe..." or "I operate..." statements that reveal themselves through the conversation agent_persona +Guide user to define what capabilities the agent should have, starting with core commands they've mentioned and then exploring additional possibilities that would complement the agent's purpose -"Now let's give our agent some capabilities! What should it be able to do?" - -Start with the core commands they've already mentioned, then explore: - -- "That's great! What else?" -- "Would it be helpful if it could also..." -- "I'm thinking it might need to..." - -As capabilities emerge, subtly guide toward technical implementation without breaking the flow. +As capabilities emerge, subtly guide toward technical implementation without breaking the conversational flow initial_capabilities @@ -164,20 +122,13 @@ As capabilities emerge, subtly guide toward technical implementation without bre Help and Exit are auto-injected; do NOT add them. Triggers are auto-prefixed with * during build. -"Let me help structure these capabilities into commands..." +Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts -Transform their natural language capabilities into technical structure, explaining as you go: +If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation -- "When you said [capability], we can implement that as..." -- "This would work great as a workflow that..." - -If they seem engaged, explore: - -- "Would you like to add any special prompts for complex analyses?" -- "Should there be any critical setup steps when the agent activates?" - -Build the YAML structure naturally from the conversation: +Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description + ```yaml menu: # Commands emerge from discussion @@ -185,129 +136,109 @@ menu: workflow: [path based on capability] description: [user's words refined] ``` + agent_commands - + +Guide user to name the agent based on everything discovered so far - its purpose, personality, and capabilities, helping them see how the naming naturally emerges from who this agent is -"Our agent is really coming together! It's got purpose, personality, and capabilities. Now it needs a name!" +Explore naming options by connecting personality traits, specializations, and communication style to potential names that feel meaningful and appropriate -This is where the naming feels natural and meaningful: +**Naming Elements:** -**"Based on everything we've built, what should we call this agent?"** +- Agent name: Personality-driven (e.g., "Sarah", "Max", "Data Wizard") +- Agent title: Based on the role discovered earlier +- Agent icon: Emoji that captures its essence +- Filename: Auto-suggest based on name (kebab-case) -Guide the naming with context: - -- "Given its [personality trait], maybe something like..." -- "Since it specializes in [capability], how about..." -- "With that [communication style], it feels like a..." - -Explore options: - -- **Agent name**: "Sarah", "Max", "Data Wizard" (personality-driven) -- **Agent title**: Based on the role we discovered earlier -- **Agent icon**: "What emoji captures its essence?" -- **Filename**: Auto-suggest based on name (kebab-case) - -Example flow: -"So we have an analytical expert who helps with data... I'm thinking 'Sarah the Data Analyst' with a 📊 icon? Or maybe something more playful like 'Data Wizard' with 🧙?" - -Let them choose or create their own. The name now has meaning because they know who this agent IS. +Present natural suggestions based on the agent's characteristics, letting them choose or create their own since they now know who this agent truly is agent_identity +Share the journey of what you've created together, summarizing how the agent started with a purpose, discovered its personality traits, gained capabilities, and received its name -"Perfect! Let me pull everything together into your agent..." - -Share the journey as you create: -"We started with [initial purpose], discovered it needed [key personality traits], gave it [capabilities], and named it [agent name]. Here's your complete agent:" - -Generate the YAML incorporating everything discovered: +Generate the complete YAML incorporating all discovered elements: + ```yaml agent: metadata: id: bmad/{{target_module}}/agents/{{agent_filename}}.md - name: { { agent_name } } # The name we chose together - title: { { agent_title } } # From the role that emerged - icon: { { agent_icon } } # The perfect emoji - module: { { target_module } } + name: {{agent_name}} # The name chosen together + title: {{agent_title}} # From the role that emerged + icon: {{agent_icon}} # The perfect emoji + module: {{target_module}} - persona: - role: | - {{The role we discovered}} - identity: | - {{The background that emerged}} - communication_style: | - {{The style they loved}} - principles: { { The beliefs we articulated } } +persona: +role: | +{{The role discovered}} +identity: | +{{The background that emerged}} +communication_style: | +{{The style they loved}} +principles: {{The beliefs articulated}} - # Features we explored - prompts: { { if discussed } } - critical_actions: { { if needed } } +# Features explored - menu: { { The capabilities we built } } -``` +prompts: {{if discussed}} +critical_actions: {{if needed}} + +menu: {{The capabilities built}} + +```` + Save based on agent type: - - If Module Agent: Save to {module_output_file} - If Standalone (Simple/Expert): Save to {standalone_output_file} -"Your agent [name] is ready! It turned out even better than I expected!" +Celebrate the completed agent with enthusiasm complete_agent - + +Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent. -"Would you like to create a customization file? This lets you tweak [agent name]'s personality later without touching the core agent." +If interested: +Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better -If interested: -"Great! This gives you a playground to experiment with different personality traits, add new commands, or adjust responses as you get to know [agent name] better." - -Create at: {config_output_file} +Create customization file at: {config_output_file} + ```yaml # Personal tweaks for {{agent_name}} # Experiment freely - changes merge at build time agent: metadata: name: '' # Try nicknames! -persona: - role: '' - identity: '' - communication_style: '' # Switch styles anytime - principles: [] -critical_actions: [] -prompts: [] -menu: [] # Add personal commands -``` + persona: + role: '' + identity: '' + communication_style: '' # Switch styles anytime + principles: [] + critical_actions: [] + prompts: [] + menu: [] # Add personal commands +```` + + agent_config +Guide user through setting up the Expert agent's personal workspace, making it feel like preparing an office with notes, research areas, and data folders -"Since [agent name] is an Expert agent, let's set up its personal workspace!" +Determine sidecar location based on whether build tools are available (next to agent YAML) or not (in output folder with clear structure) -Make it feel like preparing an office: +CREATE the complete sidecar file structure: -- "Where should [agent name] keep its notes and research?" -- "What kind of information will it need quick access to?" -- "Should it have its own data folders?" - -Determine sidecar location: - -- If build tools available: Create next to agent YAML -- If no build tools: Create in output folder with clear structure - -Actually CREATE the sidecar files: - -1. Create folder structure: +**Folder Structure:** ``` {{agent_filename}}-sidecar/ @@ -318,7 +249,7 @@ Make it feel like preparing an office: └── sessions/ # Session notes ``` -2. Create **memories.md**: +**File: memories.md** ```markdown # {{agent_name}}'s Memory Bank @@ -336,7 +267,7 @@ Make it feel like preparing an office: ``` -3. Create **instructions.md**: +**File: instructions.md** ```markdown # {{agent_name}} Private Instructions @@ -352,7 +283,7 @@ Make it feel like preparing an office: {{any_special_rules_from_creation}} ``` -4. Create **knowledge/README.md**: +**File: knowledge/README.md** ```markdown # {{agent_name}}'s Knowledge Base @@ -360,58 +291,28 @@ Make it feel like preparing an office: Add domain-specific resources here. ``` -Update agent YAML to reference sidecar: -Add `sidecar:` section with paths to created files - -Show user the created structure: -"I've created {{agent_name}}'s complete workspace at: {{sidecar_path}}" +Update agent YAML to reference sidecar with paths to created files +Show user the created structure location sidecar_resources -Check if BMAD build tools are available: +Check if BMAD build tools are available in this project If in BMAD-METHOD project with build tools: -Proceed normally - agent will be built later +Proceed normally - agent will be built later by the installer If NO build tools available (external project): Build tools not detected in this project. Would you like me to: 1. Generate the compiled agent (.md with XML) ready to use 2. Keep the YAML and build it elsewhere -3. Provide both formats +3. Provide both formats + If option 1 or 3 selected: -Generate compiled agent XML: - -```xml - - -# {{agent_title}} - - - - - {{activation_rules}} - {{activation_greeting}} - - - - {{role}} - {{identity}} - {{style}} - {{principles}} - - - - Show numbered menu - {{converted_menu_items}} - Exit with confirmation - - -``` - +Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items Save compiled version as {{agent_filename}}.md Provide path for .claude/commands/ or similar @@ -419,22 +320,21 @@ Add `sidecar:` section with paths to created files +Run validation conversationally, presenting checks as friendly confirmations while running technical validation behind the scenes -"Let me make sure [agent name] is ready to go!" +**Conversational Checks:** -Run validation but present it conversationally: +- Configuration validation +- Command functionality verification +- Personality settings confirmation -- "Checking [agent name]'s configuration..." ✓ -- "Making sure all commands work..." ✓ -- "Verifying personality settings..." ✓ +If issues found: +Explain the issue conversationally and fix it -If issues found: -"Hmm, looks like [agent name] needs a small adjustment to [issue]. Let me fix that..." +If all good: +Celebrate that the agent passed all checks and is ready -If all good: -"[Agent name] passed all checks! It's ready to help!" - -Technical checks (run behind the scenes): +**Technical Checks (behind the scenes):** 1. YAML structure validity 2. Menu command validation @@ -445,38 +345,32 @@ Technical checks (run behind the scenes): +Celebrate the accomplishment, sharing what type of agent was created with its key characteristics and top capabilities -"🎉 Congratulations! [Agent name] is ready to join your team!" +Guide user through how to activate the agent: -Share the accomplishment: -"You've created [agent type] agent with [key characteristic]. [Agent name] can [top capabilities]." +**Activation Instructions:** -**"Here's how to activate [agent name]:"** +1. Run the BMAD Method installer to this project location +2. Select 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder +3. Call the agent anytime after compilation -1. **Quick start:** - - "Run the BMAD Method installer to this project location" - - "Select the option 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder" - - "Then you can call [agent name] anytime!" +**Location Information:** -2. **Location:** - - "I saved [agent name] here: {{output_file}}" - - "After compilation, it'll be available in your project" +- Saved location: {{output_file}} +- Available after compilation in project -3. **What [agent name] can do right away:** - - List the commands in a friendly way - - "Try `*[first-command]` to see it in action!" +**Initial Usage:** -For Expert agents: -"Don't forget to add any special knowledge or data [agent name] might need to its workspace!" +- List the commands available +- Suggest trying the first command to see it in action -**"What would you like to do next?"** +If Expert agent: +Remind user to add any special knowledge or data the agent might need to its workspace -- "Want to test [agent name] now?" -- "Should we create a teammate for [agent name]?" -- "Any tweaks to [agent name]'s personality?" +Explore what user would like to do next - test the agent, create a teammate, or tweak personality -End with enthusiasm: -"I really enjoyed building [agent name] with you! I think it's going to be incredibly helpful for [main purpose]." +End with enthusiasm in {communication_language}, addressing {user_name}, expressing how the collaboration was enjoyable and the agent will be incredibly helpful for its main purpose completion_message diff --git a/src/modules/bmb/workflows/create-agent/workflow.yaml b/src/modules/bmb/workflows/create-agent/workflow.yaml index fc6faa23..8c65eac1 100644 --- a/src/modules/bmb/workflows/create-agent/workflow.yaml +++ b/src/modules/bmb/workflows/create-agent/workflow.yaml @@ -5,11 +5,9 @@ author: "BMad" # Critical variables load from config_source config_source: "{project-root}/bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" custom_agent_location: "{config_source}:custom_agent_location" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" -date: system-generated # Technical documentation for agent building agent_types: "{installed_path}/agent-types.md" diff --git a/src/modules/bmb/workflows/create-module/instructions.md b/src/modules/bmb/workflows/create-module/instructions.md index 7da33630..d844f818 100644 --- a/src/modules/bmb/workflows/create-module/instructions.md +++ b/src/modules/bmb/workflows/create-module/instructions.md @@ -1,21 +1,23 @@ # Build Module - Interactive Module Builder Instructions -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-module/workflow.yaml -Study existing modules in: {project_root}/bmad/ for patterns +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-module/workflow.yaml +Study existing modules in: {project-root}/bmad/ for patterns +Communicate in {communication_language} throughout the module creation process Do you want to brainstorm module ideas first? [y/n] -If yes: -Invoke brainstorming workflow: {brainstorming-workflow} +If yes: +Invoke brainstorming workflow: {brainstorming_workflow} Pass context data: {brainstorming_context} Wait for brainstorming session completion -Use brainstorming output to inform module concept, agent lineup, and workflow portfolio +Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps -If no, proceed to check for module brief. +If no: +Proceed directly to Step 0 brainstorming_results @@ -23,16 +25,17 @@ If no, proceed to check for module brief. Do you have a module brief or should we create one? [have/create/skip] -If create: +If create: Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml Wait for module brief completion Load the module brief to use as blueprint -If have: +If have: Provide path to module brief document Load the module brief and use it to pre-populate all planning sections -If skip, proceed directly to module definition. +If skip: +Proceed directly to Step 1 module_brief @@ -44,135 +47,101 @@ If skip, proceed directly to module definition. Review directory structures and component guidelines Study the installation infrastructure patterns -Ask the user about their module vision: +If brainstorming or module brief was completed, reference those results to guide the conversation -**"What kind of module do you want to create? Tell me about its purpose and what it will help with."** - -Listen to their description and then: +Guide user to articulate their module's vision, exploring its purpose, what it will help with, and who will use it Based on their description, intelligently propose module details: -**Module Identity (AI Proposed):** - -1. **Module name** - Extract from their description (e.g., "Data Visualization Suite", "RPG Toolkit") -2. **Module code** - Generate kebab-case from name: - - "Data Visualization Suite" → propose: "data-viz" - - "RPG Game Master Tools" → propose: "rpg-toolkit" - - "Team Collaboration System" → propose: "team-collab" - - "Personal Finance Manager" → propose: "fin-manager" - - Present as: _"Based on what you described, I suggest the module code: `{{proposed-code}}`. This will be used in paths like bmad/{{proposed-code}}/agents/. Does this work or would you prefer something different?"_ +**Module Identity Development:** +1. **Module name** - Extract from their description with proper title case +2. **Module code** - Generate kebab-case from name following patterns: + - Multi-word descriptive names → shortened kebab-case + - Domain-specific terms → recognizable abbreviations + - Present suggested code and confirm it works for paths like bmad/{{code}}/agents/ 3. **Module purpose** - Refine their description into 1-2 clear sentences 4. **Target audience** - Infer from context or ask if unclear -**Module Theme Examples:** +**Module Theme Reference Categories:** -- **Domain-Specific:** Legal, Medical, Finance, Education -- **Creative:** RPG/Gaming, Story Writing, Music Production -- **Technical:** DevOps, Testing, Architecture, Security -- **Business:** Project Management, Marketing, Sales -- **Personal:** Journaling, Learning, Productivity +- Domain-Specific (Legal, Medical, Finance, Education) +- Creative (RPG/Gaming, Story Writing, Music Production) +- Technical (DevOps, Testing, Architecture, Security) +- Business (Project Management, Marketing, Sales) +- Personal (Journaling, Learning, Productivity) Determine output location: - Module will be created at {installer_output_folder} -Store module identity for scaffolding. +Store module identity for scaffolding module_identity -Based on the module purpose, propose an initial component architecture: +Based on the module purpose, intelligently propose an initial component architecture -**"Based on your {{module_name}}, here's what I think would make a great module structure:"** +**Agents Planning:** -**Agents Planning (AI Proposed):** +Suggest agents based on module purpose, considering agent types (Simple/Expert/Module) appropriate to each role -Intelligently suggest agents based on module purpose: +**Example Agent Patterns by Domain:** -For a Data Visualization module, suggest: +- Data/Analytics: Analyst, Designer, Builder roles +- Gaming/Creative: Game Master, Generator, Storytelling roles +- Team/Business: Manager, Facilitator, Documentation roles -- "Data Analyst" - Interprets and analyzes datasets (Module type) -- "Chart Designer" - Creates visualization specs (Simple type) -- "Report Builder" - Generates comprehensive reports (Module type) +Present suggested agent list with types, explaining we can start with core ones and add others later +Confirm which agents resonate with their vision -For an RPG Toolkit, suggest: +**Workflows Planning:** -- "Dungeon Master" - Runs game sessions (Module type) -- "NPC Generator" - Creates characters (Expert type) -- "Story Weaver" - Builds adventures (Module type) +Intelligently suggest workflows that complement the proposed agents -For a Team Collaboration module, suggest: +**Example Workflow Patterns by Domain:** -- "Project Manager" - Coordinates tasks (Module type) -- "Meeting Facilitator" - Runs standups/retros (Simple type) -- "Documentation Lead" - Maintains team docs (Expert type) +- Data/Analytics: analyze-dataset, create-dashboard, generate-report +- Gaming/Creative: session-prep, generate-encounter, world-building +- Team/Business: planning, facilitation, documentation workflows -Present as: _"I'm thinking your module could have these agents: [list]. We can start with the core ones and add others later. Which of these resonate with your vision?"_ - -**Workflows Planning (AI Proposed):** - -Intelligently suggest workflows based on module purpose: - -For a Data Visualization module, suggest workflows like: - -- "analyze-dataset" - Statistical analysis workflow -- "create-dashboard" - Interactive dashboard builder -- "generate-report" - Automated report generation - -For an RPG Toolkit, suggest workflows like: - -- "session-prep" - Prepare game session materials -- "generate-encounter" - Create combat/social encounters -- "world-building" - Design locations and lore - -Present as: _"For workflows, these would complement your agents well: [list]. Each can be created as we need them. Which are most important to start with?"_ - -- Create now or placeholder? - -Example workflows: - -1. adventure-plan - Create full adventure (Document) -2. random-encounter - Quick encounter generator (Action) -3. npc-generator - Create NPCs on the fly (Interactive) -4. treasure-generator - Loot tables (Action) +For each workflow, note whether it should be Document, Action, or Interactive type +Confirm which workflows are most important to start with +Determine which to create now vs placeholder **Tasks Planning (optional):** -Ask: Any special tasks that don't warrant full workflows? +Any special tasks that don't warrant full workflows? -For each task: - -- Task name and purpose -- Standalone or supporting? +If tasks needed: +For each task, capture name, purpose, and whether standalone or supporting module_components -Based on components, intelligently determine module type: +Based on components, intelligently determine module type using criteria: -**Simple Module** (auto-select if): +**Simple Module Criteria:** - 1-2 agents, all Simple type - 1-3 workflows - No complex integrations -**Standard Module** (auto-select if): +**Standard Module Criteria:** - 2-4 agents with mixed types - 3-8 workflows - Some shared resources -**Complex Module** (auto-select if): +**Complex Module Criteria:** - 4+ agents or multiple Module-type agents - 8+ workflows - Complex interdependencies - External integrations -Present as: _"Based on your planned components, this looks like a {{determined_type}} module. This means we'll set up {{structure_description}}."_ +Present determined module type with explanation of what structure will be set up module_type @@ -254,52 +223,37 @@ data_folder: "{{determined_module_path}}/data" -Ask: **Create your first agent now? [Yes/no]** +Create your first agent now? [yes/no] -If yes: - -{agent_builder} - +If yes: +Invoke agent builder workflow: {agent_builder} +Pass module_components as context input +Guide them to create the primary agent for the module -Guide them to create the primary agent for the module. Save to module's agents folder: - Save to {{module_path}}/agents/ -If no, create placeholder: - -```md -# {{primary_agent_name}} Agent - - - - -``` +If no: +Create placeholder file in agents folder with TODO notes including agent name, purpose, and type first_agent -Ask: **Create your first workflow now? [Yes/no]** +Create your first workflow now? [yes/no] -If yes: - -{workflow_builder} - +If yes: +Invoke workflow builder: {workflow_builder} +Pass module_components as context input +Guide them to create the primary workflow -Guide them to create the primary workflow. Save to module's workflows folder: - Save to {{module_path}}/workflows/ -If no, create placeholder structure: - -``` -workflows/{{workflow_name}}/ -├── workflow.yaml # TODO: Configure -├── instructions.md # TODO: Add steps -└── template.md # TODO: If document workflow -``` +If no: +Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow first_workflow @@ -516,48 +470,50 @@ Ask if user wants to: -Run validation checks: +Run validation checks: -1. **Structure validation:** - - All required directories created - - Config files properly formatted - - Installer configuration valid +**Structure validation:** -2. **Component validation:** - - At least one agent or workflow exists (or planned) - - All references use correct paths - - Module code consistent throughout +- All required directories created +- Config files properly formatted +- Installer configuration valid -3. **Documentation validation:** - - README.md complete - - Installation instructions clear - - Examples provided +**Component validation:** -Show summary: +- At least one agent or workflow exists (or planned) +- All references use correct paths +- Module code consistent throughout -``` -✅ Module: {{module_name}} ({{module_code}}) -📁 Location: {{module_path}} -👥 Agents: {{agent_count}} ({{agents_created}} created, {{agents_planned}} planned) -📋 Workflows: {{workflow_count}} ({{workflows_created}} created, {{workflows_planned}} planned) -📝 Tasks: {{task_count}} -📦 Installer: Ready at same location -``` +**Documentation validation:** -Next steps: +- README.md complete +- Installation instructions clear +- Examples provided + +Present summary to {user_name}: + +- Module name and code +- Location path +- Agent count (created vs planned) +- Workflow count (created vs planned) +- Task count +- Installer status + +Provide next steps guidance: 1. Complete remaining components using roadmap 2. Run the BMAD Method installer to this project location -3. Select the option 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder -4. This will compile your new module and make it available for use -5. Test module with: `bmad install {{module_code}}` -6. Share module or integrate with existing system +3. Select 'Compile Agents' option after confirming folder +4. Module will be compiled and available for use +5. Test with bmad install command +6. Share or integrate with existing system -Ask: Would you like to: +Would you like to: - Create another component now? - Test the module installation? - Exit and continue later? + module_summary diff --git a/src/modules/bmb/workflows/create-module/workflow.yaml b/src/modules/bmb/workflows/create-module/workflow.yaml index 2b6fbf66..96363a82 100644 --- a/src/modules/bmb/workflows/create-module/workflow.yaml +++ b/src/modules/bmb/workflows/create-module/workflow.yaml @@ -5,11 +5,9 @@ author: "BMad" # Critical variables load from config_source config_source: "{project-root}/bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" custom_module_location: "{config_source}:custom_module_location" communication_language: "{config_source}:communication_language" user_name: "{config_source}:user_name" -date: system-generated # Reference guides for module building module_structure_guide: "{installed_path}/module-structure.md" @@ -40,16 +38,5 @@ validation: "{installed_path}/checklist.md" # Save to custom_module_location/{{module_code}} installer_output_folder: "{custom_module_location}/{{module_code}}" -web_bundle: - name: "create-module" - description: "Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure" - author: "BMad" - web_bundle_files: - - "bmad/bmb/workflows/create-module/instructions.md" - - "bmad/bmb/workflows/create-module/checklist.md" - - "bmad/bmb/workflows/create-module/module-structure.md" - - "bmad/bmb/workflows/create-module/brainstorm-context.md" - existing_workflows: - - agent_builder: "bmad/bmb/workflows/create-agent/workflow.yaml" - - workflow_builder: "bmad/bmb/workflows/create-workflow/workflow.yaml" - - brainstorming_workflow: "bmad/core/workflows/brainstorming/workflow.yaml" +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows/create-workflow/instructions.md b/src/modules/bmb/workflows/create-workflow/instructions.md index a98aa786..93ce0db5 100644 --- a/src/modules/bmb/workflows/create-workflow/instructions.md +++ b/src/modules/bmb/workflows/create-workflow/instructions.md @@ -1,11 +1,12 @@ # Build Workflow - Workflow Builder Instructions - - -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-workflow/workflow.yaml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml You MUST fully understand the workflow creation guide at: {workflow_creation_guide} Study the guide thoroughly to follow ALL conventions for optimal human-AI collaboration +Communicate in {communication_language} throughout the workflow creation process + + Do you want to brainstorm workflow ideas first? [y/n] @@ -91,6 +92,27 @@ Work with user to outline the workflow steps: - Which steps should repeat? - What variables/outputs does each step produce? +What instruction style should this workflow favor? + +**1. Intent-Based (Recommended)** - Guide the LLM with goals and principles, let it adapt conversations naturally + +- More flexible and conversational +- LLM chooses appropriate questions based on context +- Better for complex discovery and iterative refinement +- Example: `Guide user to define their target audience with specific demographics and needs` + +**2. Prescriptive** - Provide exact wording for questions and options + +- More controlled and predictable +- Ensures consistency across runs +- Better for simple data collection or specific compliance needs +- Example: `What is your target platform? Choose: PC, Console, Mobile, Web` + +Note: Your choice will be the _primary_ style, but we'll use the other when it makes more sense for specific steps. + +Store instruction_style preference (intent-based or prescriptive) +Explain that both styles have value and will be mixed appropriately + Create a step outline with clear goals and outputs. @@ -116,6 +138,19 @@ Include: - Required tools if any - Recommended inputs if any +ALWAYS include the standard config block: + +```yaml +# Critical variables from config +config_source: '{project-root}/bmad/{{target_module}}/config.yaml' +output_folder: '{config_source}:output_folder' +user_name: '{config_source}:user_name' +communication_language: '{config_source}:communication_language' +date: system-generated +``` + +This standard config ensures workflows can run autonomously and communicate properly with users + Follow path conventions from guide: - Use {project-root} for absolute paths @@ -134,7 +169,7 @@ Load and use the template at: {template_instructions} Generate the instructions.md file following the workflow creation guide: 1. ALWAYS include critical headers: - - Workflow engine reference: {project_root}/bmad/core/tasks/workflow.xml + - Workflow engine reference: {project-root}/bmad/core/tasks/workflow.xml - workflow.yaml reference: must be loaded and processed 2. Structure with tags containing all steps @@ -158,6 +193,139 @@ Generate the instructions.md file following the workflow creation guide: - Set limits ("3-5 items maximum") - Save checkpoints with +Standard config variable usage: + +Instructions MUST use the standard config variables where appropriate: + +- Communicate in {communication_language} throughout the workflow +- Address user as {user_name} in greetings and summaries +- Write all output files to {output_folder} or subdirectories +- Include {date} in generated document headers + +Example usage in instructions: + +```xml +Write document to {output_folder}/output-file.md +Communicate all responses in {communication_language} +Hello {user_name}, the workflow is complete! +``` + +Applying instruction style preference: + +Based on the {{instruction_style}} preference from Step 3, generate instructions using these patterns: + +**Intent-Based Instructions (Recommended for most workflows):** + +Focus on goals, principles, and desired outcomes. Let the LLM adapt the conversation naturally. + +✅ **Good Examples:** + +```xml + +Guide user to define their target audience with specific demographics, psychographics, and behavioral characteristics +Explore the user's vision for the product, asking probing questions to uncover core motivations and success criteria +Help user identify and prioritize key features based on user value and technical feasibility + + +Validate that the technical approach aligns with project constraints and team capabilities +Challenge assumptions about user needs and market fit with thought-provoking questions + + +Collaborate with user to refine the architecture, iterating until they're satisfied with the design +``` + +❌ **Avoid (too prescriptive):** + +```xml +What is your target audience age range? Choose: 18-24, 25-34, 35-44, 45+ +List exactly 3 key features in priority order +``` + +**When to use Intent-Based:** + +- Complex discovery processes (user research, requirements gathering) +- Creative brainstorming and ideation +- Iterative refinement workflows +- When user input quality matters more than consistency +- Workflows requiring adaptation to context + +**Prescriptive Instructions (Use selectively):** + +Provide exact wording, specific options, and controlled interactions. + +✅ **Good Examples:** + +```xml + +What is your target platform? Choose: PC, Console, Mobile, Web +Select monetization model: Premium, Free-to-Play, Subscription, Ad-Supported + + +Does this comply with GDPR requirements? [yes/no] +Choose documentation standard: JSDoc, TypeDoc, TSDoc + + +Do you want to generate test cases? [yes/no] +Include performance benchmarks? [yes/no] +``` + +❌ **Avoid (too rigid for complex tasks):** + +```xml +What are your product goals? List exactly 5 goals, each 10-15 words +Describe your user persona in exactly 3 sentences +``` + +**When to use Prescriptive:** + +- Simple data collection (platform, format, yes/no choices) +- Compliance verification and standards adherence +- Configuration with finite options +- When consistency is critical across all executions +- Quick setup wizards + +**Mixing Both Styles (Best Practice):** + +Even if user chose a primary style, use the other when appropriate: + +```xml + + + Explore the user's vision for their game, uncovering their creative intent and target experience + Ask probing questions about genre, themes, and emotional tone they want to convey + + + + What is your target platform? Choose: PC, Console, Mobile, Web + Select primary genre: Action, RPG, Strategy, Puzzle, Simulation, Other + + + + Guide user to articulate their core gameplay loop, exploring mechanics and player agency + Help them identify what makes their game unique and compelling + +``` + +**Guidelines for the chosen style:** + +If user chose **Intent-Based**: + +- Default to goal-oriented tags +- Use open-ended guidance language +- Save prescriptive tags for simple data/choices +- Focus on "guide", "explore", "help user", "validate" +- Allow LLM to adapt questions to user responses + +If user chose **Prescriptive**: + +- Default to explicit tags with clear options +- Use precise wording for consistency +- Save intent-based tags for complex discovery +- Focus on "choose", "select", "specify", "confirm" +- Provide structured choices when possible + +**Remember:** The goal is optimal human-AI collaboration. Use whichever style best serves the user at each step. + Save location: - Write to {{output_folder}}/instructions.md @@ -171,9 +339,20 @@ Generate the template.md file following guide conventions: 1. Document structure with clear sections 2. Variable syntax: {{variable_name}} using snake_case 3. Variable names MUST match tags exactly from instructions -4. Include standard metadata: - - **Date:** {{date}} - - **Author:** {{user_name}} (if applicable) +4. Include standard metadata header (optional - config variables available): + + ```markdown + # Document Title + + **Date:** {{date}} + **Author:** {{user_name}} + ``` + + Note: {{date}} and {{user_name}} are optional in headers. Primary purpose of these variables: + - {{date}} - Gives agent current date awareness (not confused with training cutoff) + - {{user_name}} - Optional author attribution + - {{communication_language}} - NOT for document output! Tells agent how to communicate during execution + 5. Follow naming conventions from guide: - Use descriptive names: {{primary_user_journey}} not {{puj}} - Snake_case for all variables @@ -181,11 +360,26 @@ Generate the template.md file following guide conventions: Variable sources as per guide: -- workflow.yaml config values +- workflow.yaml config values (user_name, communication_language, date, output_folder) - User input runtime values - Step outputs via - System variables (date, paths) +Standard config variables in templates: + +Templates CAN optionally use these config variables: + +- {{user_name}} - Document author (optional) +- {{date}} - Generation date (optional) + +IMPORTANT: {{communication_language}} is NOT for document headers! + +- Purpose: Tells agent how to communicate with user during workflow execution +- NOT for: Document output language or template headers +- Future: {{document_output_language}} will handle multilingual document generation + +These variables are automatically available from workflow.yaml config block. + Save location: - Write to {{output_folder}}/template.md @@ -230,12 +424,32 @@ If yes, create placeholder files or copy from templates. Review the created workflow: + +**Basic Validation:** + 1. Verify all file paths are correct 2. Check variable names match between files 3. Ensure step numbering is sequential 4. Validate YAML syntax 5. Confirm all placeholders are replaced +**Standard Config Validation:** 6. Verify workflow.yaml contains standard config block: + +- config_source defined +- output_folder, user_name, communication_language pulled from config +- date set to system-generated + +7. Check instructions use config variables where appropriate +8. Verify template includes config variables in metadata (if document workflow) + +**YAML/Instruction/Template Alignment:** 9. Cross-check all workflow.yaml variables against instruction usage: + +- Are all yaml variables referenced in instructions.md OR template.md? +- Are there hardcoded values that should be variables? +- Do template variables match tags in instructions? + +10. Identify any unused yaml fields (bloat detection) + Show user a summary of created files and their locations. Ask if they want to: @@ -262,12 +476,24 @@ If yes: - Remove {config_source} references (use hardcoded values) - Example: "{project-root}/bmad/bmm/workflows/x" → "bmad/bmm/workflows/x" -3. List ALL referenced files: - - Scan instructions.md for any file paths - - Scan template.md for any includes or references - - Include all data files (CSV, JSON, etc.) - - Include any sub-workflow YAML files - - Include any shared templates +3. List ALL referenced files by scanning: + + **Scan instructions.md for:** + - File paths in tags + - Data files (CSV, JSON, YAML, etc.) + - Validation/checklist files + - Any calls → must include that workflow's yaml file + - Any tags that reference other workflows + - Shared templates or includes + + **Scan template.md for:** + - Any includes or references to other files + - Shared template fragments + + **Critical: Workflow Dependencies** + - If instructions call another workflow, that workflow's yaml MUST be in web_bundle_files + - Example: `{project-root}/bmad/core/workflows/x/workflow.yaml` + → Add "bmad/core/workflows/x/workflow.yaml" to web_bundle_files 4. Create web_bundle_files array with complete list @@ -291,33 +517,58 @@ web_bundle: - 'bmad/{module}/workflows/{workflow}/template.md' - 'bmad/{module}/workflows/{workflow}/data.csv' # Add every single file referenced anywhere + + # CRITICAL: If this workflow invokes other workflows, use existing_workflows + # This signals the bundler to recursively include those workflows' web_bundles + existing_workflows: + - workflow_variable_name: 'bmad/path/to/workflow.yaml' ``` +**Example with existing_workflows:** + +```yaml +web_bundle: + name: 'brainstorm-game' + description: 'Game brainstorming with CIS workflow' + author: 'BMad' + instructions: 'bmad/bmm/workflows/brainstorm-game/instructions.md' + template: false + web_bundle_files: + - 'bmad/bmm/workflows/brainstorm-game/instructions.md' + - 'bmad/mmm/workflows/brainstorm-game/game-context.md' + - 'bmad/core/workflows/brainstorming/workflow.yaml' + existing_workflows: + - core_brainstorming: 'bmad/core/workflows/brainstorming/workflow.yaml' +``` + +**What existing_workflows does:** + +- Tells the bundler this workflow invokes another workflow +- Bundler recursively includes the invoked workflow's entire web_bundle +- Essential for meta-workflows that orchestrate other workflows +- Maps workflow variable names to their bmad/-relative paths + Validate web bundle completeness: - Ensure no {config_source} variables remain - Verify all file paths are listed - Check that paths are bmad/-relative +- If workflow uses , add to existing_workflows web_bundle_config -Create a brief README for the workflow folder explaining: -- Purpose and use case -- How to invoke: `workflow {workflow_name}` -- Expected inputs -- Generated outputs -- Any special requirements +Create a brief README for the workflow folder explaining purpose, how to invoke, expected inputs, generated outputs, and any special requirements -Provide user with: +Provide {user_name} with workflow completion summary in {communication_language}: - Location of created workflow: {{output_folder}} -- Command to run it +- Command to run it: `workflow {workflow_name}` - Next steps: - - "Run the BMAD Method installer to this project location" - - "Select the option 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder" - - "This will compile your new workflow and make it available for use" + - Run the BMAD Method installer to this project location + - Select 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder + - This will compile the new workflow and make it available for use diff --git a/src/modules/bmb/workflows/create-workflow/workflow-template/instructions.md b/src/modules/bmb/workflows/create-workflow/workflow-template/instructions.md index 643722b7..955e6075 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow-template/instructions.md +++ b/src/modules/bmb/workflows/create-workflow/workflow-template/instructions.md @@ -1,9 +1,10 @@ # PRD Workflow Instructions - +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-related}/bmad/{module-code}/workflows/{workflow}/workflow.yaml +Communicate in {communication_language} throughout the workflow process -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/{module-code}/workflows/{workflow}/workflow.yaml + ... diff --git a/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml b/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml index 7cbd0c42..a597483a 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml +++ b/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml @@ -8,6 +8,7 @@ author: "BMad" config_source: "{project-root}/{module-code}/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Required Data Files - HALT if missing! diff --git a/src/modules/bmb/workflows/create-workflow/workflow.yaml b/src/modules/bmb/workflows/create-workflow/workflow.yaml index 35b04db7..193a7199 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow.yaml +++ b/src/modules/bmb/workflows/create-workflow/workflow.yaml @@ -5,11 +5,9 @@ author: "BMad Builder" # Critical variables config_source: "{project-root}/bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" custom_workflow_location: "{config_source}:custom_workflow_location" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" -date: system-generated # Template files for new workflows template_workflow_yaml: "{workflow_template_path}/workflow.yaml" @@ -38,15 +36,5 @@ workflow_template_path: "{installed_path}/workflow-template" module_output_folder: "{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}" standalone_output_folder: "{custom_workflow_location}/{{workflow_name}}" -web_bundle: - name: "create-workflow" - description: "Interactive workflow builder that guides creation of new BMAD workflows with proper structure and validation for optimal human-AI collaboration. Includes optional brainstorming phase for workflow ideas and design." - author: "BMad Builder" - web_bundle_files: - - "bmad/bmb/workflows/create-workflow/instructions.md" - - "bmad/bmb/workflows/create-workflow/checklist.md" - - "bmad/bmb/workflows/create-workflow/workflow-creation-guide.md" - - "bmad/bmb/workflows/create-workflow/workflow-template/workflow.yaml" - - "bmad/bmb/workflows/create-workflow/workflow-template/instructions.md" - - "bmad/bmb/workflows/create-workflow/workflow-template/template.md" - - "bmad/bmb/workflows/create-workflow/workflow-template/checklist.md" +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows/edit-workflow/instructions.md b/src/modules/bmb/workflows/edit-workflow/instructions.md index 1dc8b97c..7e03e72b 100644 --- a/src/modules/bmb/workflows/edit-workflow/instructions.md +++ b/src/modules/bmb/workflows/edit-workflow/instructions.md @@ -3,6 +3,7 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml Study the workflow creation guide thoroughly at: {workflow_creation_guide} +Communicate in {communication_language} throughout the workflow editing process @@ -37,6 +38,26 @@ Analyze for: - **Template variables**: Use snake_case and descriptive names? - **Validation criteria**: Are checklist items measurable and specific? +**Standard Config Audit:** + +- **workflow.yaml config block**: Check for standard config variables + - Is config_source defined? + - Are output_folder, user_name, communication_language pulled from config? + - Is date set to system-generated? +- **Instructions usage**: Do instructions use config variables? + - Does it communicate in {communication_language}? + - Does it address {user_name}? + - Does it write to {output_folder}? +- **Template usage**: Does template.md include config variables in metadata? + +**YAML/File Alignment:** + +- **Unused yaml fields**: Are there variables in workflow.yaml not used in instructions OR template? +- **Missing variables**: Are there hardcoded values that should be variables? +- **Web bundle completeness**: If web_bundle exists, does it include all dependencies? + - All referenced files listed? + - Called workflows included? + Create a list of identified issues or improvement opportunities Prioritize issues by importance (critical, important, nice-to-have) @@ -47,21 +68,40 @@ Present the editing menu to the user: **What aspect would you like to edit?** 1. **Fix critical issues** - Address missing headers, broken references -2. **Update workflow.yaml** - Modify configuration, paths, metadata -3. **Refine instructions** - Improve steps, add detail, fix flow -4. **Update template** - Fix variables, improve structure (if applicable) -5. **Enhance validation** - Make checklist more specific and measurable -6. **Add new features** - Add steps, optional sections, or capabilities -7. **Configure web bundle** - Add/update web bundle for deployment -8. **Optimize for clarity** - Improve descriptions, add examples -9. **Full review and update** - Comprehensive improvements across all files +2. **Add/fix standard config** - Ensure standard config block and variable usage +3. **Update workflow.yaml** - Modify configuration, paths, metadata +4. **Refine instructions** - Improve steps, add detail, fix flow +5. **Update template** - Fix variables, improve structure (if applicable) +6. **Enhance validation** - Make checklist more specific and measurable +7. **Add new features** - Add steps, optional sections, or capabilities +8. **Configure web bundle** - Add/update web bundle for deployment +9. **Remove bloat** - Delete unused yaml fields, duplicate values +10. **Optimize for clarity** - Improve descriptions, add examples +11. **Full review and update** - Comprehensive improvements across all files -Select an option (1-9) or describe a custom edit: +Select an option (1-11) or describe a custom edit: Based on the selected edit type, load appropriate reference materials: +If option 2 (Add/fix standard config): +Prepare standard config block template: + +```yaml +# Critical variables from config +config_source: '{project-root}/bmad/{module}/config.yaml' +output_folder: '{config_source}:output_folder' +user_name: '{config_source}:user_name' +communication_language: '{config_source}:communication_language' +date: system-generated +``` + +Check if workflow.yaml has existing config section (don't duplicate) +Identify missing config variables to add +Check instructions.md for config variable usage +Check template.md for config variable usage + If editing instructions or adding features: Review the "Writing Instructions" section of the creation guide Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns @@ -73,10 +113,16 @@ Based on the selected edit type, load appropriate reference materials: If editing validation: Review the "Validation" section and measurable criteria examples +If option 9 (Remove bloat): +Cross-reference all workflow.yaml fields against instructions.md and template.md +Identify yaml fields not used in any file +Check for duplicate fields in web_bundle section + If configuring web bundle: Review the "Web Bundles" section of the creation guide Scan all workflow files for referenced resources Create inventory of all files that must be included +Scan instructions for calls - those yamls must be included If fixing critical issues: Load the workflow execution engine documentation @@ -101,7 +147,12 @@ If creating new web bundle: - Any included files 5. Scan template.md for any includes 6. Create complete web_bundle_files array -7. Generate web_bundle section +7. **CRITICAL**: Check for calls in instructions: + - If workflow invokes other workflows, add existing_workflows field + - Maps workflow variable name to bmad/-relative path + - Signals bundler to recursively include invoked workflow's web_bundle + - Example: `existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"` +8. Generate web_bundle section If updating existing web bundle: @@ -138,7 +189,7 @@ If updating existing web bundle: Run a comprehensive validation check: -Validation checks: +**Basic Validation:** - [ ] All file paths resolve correctly - [ ] Variable names are consistent across files @@ -151,13 +202,32 @@ Validation checks: - [ ] Critical headers are present in instructions - [ ] YAML syntax is valid -Web bundle validation (if applicable): +**Standard Config Validation:** + +- [ ] workflow.yaml contains config_source +- [ ] output_folder, user_name, communication_language pulled from config +- [ ] date set to system-generated +- [ ] Instructions communicate in {communication_language} where appropriate +- [ ] Instructions address {user_name} where appropriate +- [ ] Instructions write to {output_folder} for file outputs +- [ ] Template optionally includes {{user_name}}, {{date}} in metadata (if document workflow) +- [ ] Template does NOT use {{communication_language}} in headers (agent-only variable) + +**YAML/File Alignment:** + +- [ ] All workflow.yaml variables used in instructions OR template +- [ ] No unused yaml fields (bloat-free) +- [ ] No duplicate fields between top-level and web_bundle +- [ ] Template variables match tags in instructions + +**Web bundle validation (if applicable):** - [ ] web_bundle section present if needed - [ ] All paths are bmad/-relative (no {project-root}) - [ ] No {config_source} variables in web bundle - [ ] All referenced files listed in web_bundle_files - [ ] Instructions, validation, template paths correct +- [ ] Called workflows () included in web_bundle_files - [ ] Complete file inventory verified If any validation fails: @@ -167,43 +237,25 @@ Web bundle validation (if applicable): -Create a summary of all changes made: +Create a summary of all changes made for {user_name} in {communication_language}: -## Workflow Edit Summary +**Summary Structure:** -**Workflow:** {{workflow_name}} -**Date:** {{date}} -**Editor:** {{user_name}} - -### Changes Made: - -List each file that was modified with a brief description of changes - -### Improvements: - -Summarize how the workflow is now better aligned with best practices - -### Files Modified: - -List all modified files with their paths - -### Next Steps: - -Suggest any additional improvements or testing that could be done +- Workflow name +- Changes made (file-by-file descriptions) +- Improvements (how workflow is now better aligned with best practices) +- Files modified (complete list with paths) +- Next steps (suggestions for additional improvements or testing) Would you like to: -- Save this summary to: {change_log_output} - Test the edited workflow - Make additional edits - Exit -If save summary: -Write the summary to the change log file - If test workflow: -{{workflow_name}} +Invoke the edited workflow for testing diff --git a/src/modules/bmb/workflows/edit-workflow/workflow.yaml b/src/modules/bmb/workflows/edit-workflow/workflow.yaml index 1c52f05c..a2f09b2f 100644 --- a/src/modules/bmb/workflows/edit-workflow/workflow.yaml +++ b/src/modules/bmb/workflows/edit-workflow/workflow.yaml @@ -5,10 +5,8 @@ author: "BMad" # Critical variables load from config_source config_source: "{project-root}/bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" communication_language: "{config_source}:communication_language" user_name: "{config_source}:user_name" -date: system-generated # Required Data Files - Critical for understanding workflow conventions workflow_creation_guide: "{project-root}/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md" @@ -25,14 +23,5 @@ template: false # This is an action workflow - no template needed instructions: "{installed_path}/instructions.md" validation: "{installed_path}/checklist.md" -# No output file for action workflows -# But we may generate a change log -change_log_output: "{output_folder}/workflow-edit-log-{{date}}.md" - -web_bundle: - name: "edit-workflow" - description: "Edit existing BMAD workflows while following all best practices and conventions" - author: "BMad" - web_bundle_files: - - "bmad/bmb/workflows/edit-workflow/instructions.md" - - "bmad/bmb/workflows/edit-workflow/checklist.md" +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows/module-brief/instructions.md b/src/modules/bmb/workflows/module-brief/instructions.md index c9e1e74c..6f45ac42 100644 --- a/src/modules/bmb/workflows/module-brief/instructions.md +++ b/src/modules/bmb/workflows/module-brief/instructions.md @@ -1,7 +1,8 @@ # Module Brief Instructions -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/module-brief/workflow.yaml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml +Communicate in {communication_language} throughout the module brief creation process @@ -248,16 +249,17 @@ For each risk, note mitigation strategy. -Review all sections with user +Review all sections with {user_name} Ensure module brief is ready for create-module workflow -Ask if they want to: +Would {user_name} like to: 1. Proceed directly to create-module workflow 2. Save and refine later 3. Generate additional planning documents + -Highlight that this brief can be fed directly into create-module workflow! +Inform {user_name} in {communication_language} that this brief can be fed directly into create-module workflow final_brief diff --git a/src/modules/bmb/workflows/module-brief/workflow.yaml b/src/modules/bmb/workflows/module-brief/workflow.yaml index 9bbed50f..715f91e6 100644 --- a/src/modules/bmb/workflows/module-brief/workflow.yaml +++ b/src/modules/bmb/workflows/module-brief/workflow.yaml @@ -25,11 +25,5 @@ validation: "{installed_path}/checklist.md" # Output configuration default_output_file: "{output_folder}/module-brief-{{module_code}}-{{date}}.md" -web_bundle: - name: "module-brief" - description: "Create a comprehensive Module Brief that serves as the blueprint for building new BMAD modules using strategic analysis and creative vision" - author: "BMad Builder" - web_bundle_files: - - "bmad/bmb/workflows/module-brief/instructions.md" - - "bmad/bmb/workflows/module-brief/template.md" - - "bmad/bmb/workflows/module-brief/checklist.md" +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows/redoc/instructions.md b/src/modules/bmb/workflows/redoc/instructions.md index ac9c1c24..68eb7f29 100644 --- a/src/modules/bmb/workflows/redoc/instructions.md +++ b/src/modules/bmb/workflows/redoc/instructions.md @@ -1,13 +1,14 @@ # ReDoc Workflow Instructions - - -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project_root}/src/modules/bmb/workflows/redoc/workflow.yaml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/src/modules/bmb/workflows/redoc/workflow.yaml +Communicate in {communication_language} throughout the documentation process This is an AUTONOMOUS workflow - minimize user interaction unless clarification is absolutely required IMPORTANT: Process ONE document at a time to avoid token limits. Each README should be created individually, not batched. When using Task tool with sub-agents: Only request ONE workflow or agent documentation per invocation to prevent token overflow. + + Load ALL BMAD convention documents from {bmad_conventions}: - agent_architecture.md - Understand agent XML structure and patterns @@ -256,9 +257,9 @@ For each README with last-redoc-date frontmatter: -Confirm autonomous workflow execution complete +Confirm to {user_name} in {communication_language} that autonomous workflow execution is complete Provide path to all updated documentation -Suggest next steps if needed (e.g., "Run redoc on parent module to update references") +Suggest next steps if needed diff --git a/src/modules/bmb/workflows/redoc/workflow.yaml b/src/modules/bmb/workflows/redoc/workflow.yaml index cc951077..ef855b32 100644 --- a/src/modules/bmb/workflows/redoc/workflow.yaml +++ b/src/modules/bmb/workflows/redoc/workflow.yaml @@ -5,9 +5,8 @@ author: "BMad" # Critical variables config_source: "{project-root}/bmad/bmb/config.yaml" -output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" -date: system-generated +communication_language: "{config_source}:communication_language" # Required knowledge base - BMAD conventions and patterns bmad_conventions: @@ -29,10 +28,5 @@ validation: "{installed_path}/checklist.md" # Configuration autonomous: true # Runs without user checkpoints unless clarification needed -web_bundle: - name: "redoc" - description: "Autonomous documentation system that maintains module, workflow, and agent documentation using a reverse-tree approach (leaf folders first, then parents). Understands BMAD conventions and produces technical writer quality output." - author: "BMad" - web_bundle_files: - - "bmad/bmb/workflows/redoc/instructions.md" - - "bmad/bmb/workflows/redoc/checklist.md" +# Web bundle configuration +web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmm/_module-installer/assets/technical-decisions-template.md b/src/modules/bmm/_module-installer/assets/technical-decisions.md similarity index 100% rename from src/modules/bmm/_module-installer/assets/technical-decisions-template.md rename to src/modules/bmm/_module-installer/assets/technical-decisions.md diff --git a/src/modules/bmm/agents/game-designer.agent.yaml b/src/modules/bmm/agents/game-designer.agent.yaml index 136cc2e8..007dca6f 100644 --- a/src/modules/bmm/agents/game-designer.agent.yaml +++ b/src/modules/bmm/agents/game-designer.agent.yaml @@ -20,7 +20,7 @@ agent: menu: - trigger: workflow-status workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml" - description: Check workflow status and get recommendations + description: Check workflow status and get recommendations (START HERE!) - trigger: brainstorm-game workflow: "{project-root}/bmad/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml" @@ -30,10 +30,14 @@ agent: workflow: "{project-root}/bmad/bmm/workflows/1-analysis/game-brief/workflow.yaml" description: Create Game Brief - - trigger: plan-game - workflow: "{project-root}/bmad/bmm/workflows/2-plan/workflow.yaml" + - trigger: gdd + workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/gdd/workflow.yaml" description: Create Game Design Document (GDD) + - trigger: narrative + workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml" + description: Create Narrative Design Document (story-driven games) + - trigger: research workflow: "{project-root}/bmad/bmm/workflows/1-analysis/research/workflow.yaml" description: Conduct Game Market Research diff --git a/src/modules/bmm/agents/pm.agent.yaml b/src/modules/bmm/agents/pm.agent.yaml index 1f95829a..0c169c09 100644 --- a/src/modules/bmm/agents/pm.agent.yaml +++ b/src/modules/bmm/agents/pm.agent.yaml @@ -27,9 +27,13 @@ agent: workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml" description: Check workflow status and get recommendations (START HERE!) - - trigger: plan-project - workflow: "{project-root}/bmad/bmm/workflows/2-plan/workflow.yaml" - description: Analyze Project Scope and Create PRD or Smaller Tech Spec + - trigger: prd + workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml" + description: Create Product Requirements Document (PRD) for Level 2-4 projects + + - trigger: tech-spec + workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml" + description: Create Tech Spec for Level 0-1 projects - trigger: correct-course workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" diff --git a/src/modules/bmm/agents/ux-expert.agent.yaml b/src/modules/bmm/agents/ux-expert.agent.yaml index 71c4cc2e..94febb0f 100644 --- a/src/modules/bmm/agents/ux-expert.agent.yaml +++ b/src/modules/bmm/agents/ux-expert.agent.yaml @@ -20,8 +20,8 @@ agent: menu: - trigger: workflow-status workflow: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml" - description: Check workflow status and get recommendations + description: Check workflow status and get recommendations (START HERE!) - - trigger: plan-project - workflow: "{project-root}/bmad/bmm/workflows/2-plan/workflow.yaml" - description: UX Workflows, Website Planning, and UI AI Prompt Generation + - trigger: ux-spec + workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux/workflow.yaml" + description: Create UX/UI Specification and AI Frontend Prompts diff --git a/src/modules/bmm/teams/team-planning.yaml b/src/modules/bmm/teams/team-planning.yaml index 26b52838..b75ea9f0 100644 --- a/src/modules/bmm/teams/team-planning.yaml +++ b/src/modules/bmm/teams/team-planning.yaml @@ -7,6 +7,6 @@ agents: - analyst - architect - pm - - po + - sm - tea - ux-expert diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md index 0b5e3024..cc63df69 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md @@ -1,5 +1,6 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This is a meta-workflow that orchestrates the CIS brainstorming workflow with game-specific context and additional game design techniques @@ -84,7 +85,7 @@ What would you like to do? - **{{date}}**: Completed brainstorm-game workflow. Generated game brainstorming session results saved to {output_folder}/brainstorming-session-results-{{date}}.md. Next: Review game ideas and consider running research or game-brief workflows. ``` - **✅ Game Brainstorming Session Complete** + **✅ Game Brainstorming Session Complete, {user_name}!** **Session Results:** @@ -108,7 +109,7 @@ Check status anytime with: `workflow-status` - **✅ Game Brainstorming Session Complete** + **✅ Game Brainstorming Session Complete, {user_name}!** **Session Results:** diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml b/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml index 9728926e..7c6a1caf 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml @@ -3,10 +3,11 @@ name: "brainstorm-game" description: "Facilitate game brainstorming sessions by orchestrating the CIS brainstorming workflow with game-specific context, guidance, and additional game design techniques." author: "BMad" -# Critical variables load from config_source +# Critical variables from config config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Module path and component files @@ -27,7 +28,6 @@ web_bundle: author: "BMad" instructions: "bmad/bmm/workflows/1-analysis/brainstorm-game/instructions.md" template: false - use_advanced_elicitation: true web_bundle_files: - "bmad/bmm/workflows/1-analysis/brainstorm-game/instructions.md" - "bmad/bmm/workflows/1-analysis/brainstorm-game/game-context.md" diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md index e5881291..8d8fb6d8 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This is a meta-workflow that orchestrates the CIS brainstorming workflow with project-specific context @@ -77,7 +78,7 @@ What would you like to do? - **{{date}}**: Completed brainstorm-project workflow. Generated brainstorming session results saved to {output_folder}/brainstorming-session-results-{{date}}.md. Next: Review ideas and consider running research or product-brief workflows. ``` - **✅ Brainstorming Session Complete** + **✅ Brainstorming Session Complete, {user_name}!** **Session Results:** - Brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md @@ -98,7 +99,7 @@ Check status anytime with: `workflow-status` - **✅ Brainstorming Session Complete** + **✅ Brainstorming Session Complete, {user_name}!** **Session Results:** - Brainstorming results saved to: {output_folder}/brainstorming-session-results-{{date}}.md diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml b/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml index cd7538c6..a221a7ce 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml @@ -3,10 +3,11 @@ name: "brainstorm-project" description: "Facilitate project brainstorming sessions by orchestrating the CIS brainstorming workflow with project-specific context and guidance." author: "BMad" -# Critical variables load from config_source +# Critical variables from config config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Module path and component files @@ -26,7 +27,6 @@ web_bundle: author: "BMad" instructions: "bmad/bmm/workflows/1-analysis/brainstorm-project/instructions.md" template: false - use_advanced_elicitation: true web_bundle_files: - "bmad/bmm/workflows/1-analysis/brainstorm-project/instructions.md" - "bmad/bmm/workflows/1-analysis/brainstorm-project/project-context.md" diff --git a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md index 55300505..29640929 100644 --- a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md @@ -1,9 +1,11 @@ # Document Project Workflow Router - - The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/document-project/workflow.yaml +Communicate all responses in {communication_language} + + + This router determines workflow mode and delegates to specialized sub-workflows @@ -241,7 +243,7 @@ Your choice [1/2/3]: - **{{date}}**: Completed document-project workflow ({{workflow_mode}} mode, {{scan_level}} scan). Generated brownfield documentation in {output_folder}/. Next: {{next_step}}. ``` -**✅ Document Project Workflow Complete** +**✅ Document Project Workflow Complete, {user_name}!** **Documentation Generated:** diff --git a/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml b/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml index fc3591ea..b618e33b 100644 --- a/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml @@ -30,69 +30,6 @@ recommended_inputs: - project_root: "User will specify or use current directory" - existing_readme: "README.md at project root (if exists)" - project_config: "package.json, go.mod, requirements.txt, etc. (auto-detected)" - # Output configuration - Multiple files generated in output folder -# File naming depends on project structure (simple vs multi-part) -# Simple projects: index.md, architecture.md, etc. -# Multi-part projects: index.md, architecture-{part_id}.md, etc. - -default_output_files: - - index: "{output_folder}/index.md" - - project_overview: "{output_folder}/project-overview.md" - - architecture: "{output_folder}/architecture.md" # or architecture-{part_id}.md for multi-part - - source_tree: "{output_folder}/source-tree-analysis.md" - - component_inventory: "{output_folder}/component-inventory.md" # or component-inventory-{part_id}.md - - development_guide: "{output_folder}/development-guide.md" # or development-guide-{part_id}.md - - deployment_guide: "{output_folder}/deployment-guide.md" # optional, if deployment config found - - contribution_guide: "{output_folder}/contribution-guide.md" # optional, if CONTRIBUTING.md found - - api_contracts: "{output_folder}/api-contracts.md" # optional, per part if needed - - data_models: "{output_folder}/data-models.md" # optional, per part if needed - - integration_architecture: "{output_folder}/integration-architecture.md" # only for multi-part - - project_parts: "{output_folder}/project-parts.json" # metadata for multi-part projects - - deep_dive: "{output_folder}/deep-dive-{sanitized_target_name}.md" # deep-dive mode output - - project_scan_report: "{output_folder}/project-scan-report.json" # state tracking for resumability - -# Runtime variables (generated during workflow execution) -runtime_variables: - - workflow_mode: "initial_scan | full_rescan | deep_dive" - - scan_level: "quick | deep | exhaustive (default: quick)" - - project_type: "Detected project type (web, backend, cli, etc.)" - - project_parts: "Array of project parts for multi-part projects" - - architecture_match: "Matched architecture from registry" - - doc_requirements: "Documentation requirements for project type" - - tech_stack: "Detected technology stack" - - existing_docs: "Discovered existing documentation" - - deep_dive_target: "Target area for deep-dive analysis (if deep-dive mode)" - - deep_dive_count: "Number of deep-dive docs generated" - - resume_point: "Step to resume from (if resuming interrupted workflow)" - - state_file: "Path to project-scan-report.json for state tracking" - -# Scan Level Definitions -scan_levels: - quick: - description: "Pattern-based scanning without reading source files" - duration: "2-5 minutes" - reads: "Config files, package manifests, directory structure only" - use_case: "Quick project overview, initial understanding" - default: true - deep: - description: "Reads files in critical directories per project type" - duration: "10-30 minutes" - reads: "Critical files based on documentation_requirements.csv patterns" - use_case: "Comprehensive documentation for brownfield PRD" - default: false - exhaustive: - description: "Reads ALL source files in project" - duration: "30-120 minutes" - reads: "Every source file (excluding node_modules, dist, build)" - use_case: "Complete analysis, migration planning, detailed audit" - default: false - -# Resumability Settings -resumability: - enabled: true - state_file_location: "{output_folder}/project-scan-report.json" - state_file_max_age: "24 hours" - auto_prompt_resume: true - archive_old_state: true - archive_location: "{output_folder}/.archive/" +# Primary output: {output_folder}/index.md +# Additional files generated by sub-workflows based on project structure diff --git a/src/modules/bmm/workflows/1-analysis/game-brief/README.md b/src/modules/bmm/workflows/1-analysis/game-brief/README.md index 2a42f503..779ac984 100644 --- a/src/modules/bmm/workflows/1-analysis/game-brief/README.md +++ b/src/modules/bmm/workflows/1-analysis/game-brief/README.md @@ -107,9 +107,9 @@ Output is designed to feed directly into: ``` 1-analysis/game-brief (You are here) ↓ -2-plan/gdd (Game Design Document) +2-plan-workflows/gdd (Game Design Document) ↓ -2-plan/narrative (Optional: Story-heavy games) +2-plan-workflows/narrative (Optional: Story-heavy games) ↓ 3-solutioning (Technical architecture, engine selection) ↓ @@ -216,6 +216,6 @@ A: Involve your team! Collaborative briefs catch blind spots and build shared vi ## Related Workflows - **Product Brief** (`1-analysis/product-brief`): For software products, not games -- **GDD** (`2-plan/gdd`): Next step after game brief -- **Narrative Design** (`2-plan/narrative`): For story-heavy games after GDD +- **GDD** (`2-plan-workflows/gdd`): Next step after game brief +- **Narrative Design** (`2-plan-workflows/narrative`): For story-heavy games after GDD - **Solutioning** (`3-solutioning`): Technical architecture after planning diff --git a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md index cb9e01db..40fddd08 100644 --- a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md @@ -2,6 +2,7 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} @@ -34,33 +35,18 @@ What would you like to do? -Welcome the user to the Game Brief creation process -Explain this is a collaborative process to define their game vision -What is the working title for your game? +Welcome the user in {communication_language} to the Game Brief creation process +Explain this is a collaborative process to define their game vision, capturing the essence of what they want to create +Ask for the working title of their game game_name -Check what inputs the user has available: -Do you have any of these documents to help inform the brief? - -1. Market research or player data -2. Brainstorming results or game jam prototypes -3. Competitive game analysis -4. Initial game ideas or design notes -5. Reference games list -6. None - let's start fresh - -Please share any documents you have or select option 6. - -Load and analyze any provided documents -Extract key insights and themes from input documents - -Based on what you've shared (or if starting fresh), tell me: - -- What's the core gameplay experience you want to create? -- What emotion or feeling should players have? -- What sparked this game idea? +Explore what existing materials the user has available to inform the brief +Offer options for input sources: market research, brainstorming results, competitive analysis, design notes, reference games, or starting fresh +If documents are provided, load and analyze them to extract key insights, themes, and patterns +Engage the user about their core vision: what gameplay experience they want to create, what emotions players should feel, and what sparked this game idea +Build initial understanding through conversational exploration rather than rigid questioning initial_context @@ -78,22 +64,11 @@ Which approach works best for you? -Let's capture your game vision. - -**Core Concept** - What is your game in one sentence? -Example: "A roguelike deck-builder where you climb a mysterious spire" - -**Elevator Pitch** - Describe your game in 2-3 sentences as if pitching to a publisher or player. -Example: "Slay the Spire fuses card games and roguelikes together. Craft a unique deck, encounter bizarre creatures, discover relics of immense power, and kill the Spire." - -**Vision Statement** - What is the aspirational goal for this game? What experience do you want to create? -Example: "Create a deeply replayable tactical card game that rewards strategic thinking while maintaining the excitement of randomness. Every run should feel unique but fair." - -Your answers: - -Help refine the core concept to be clear and compelling -Ensure elevator pitch is concise but captures the hook -Guide vision statement to be aspirational but achievable +Guide user to articulate their game vision across three levels of depth +Help them craft a one-sentence core concept that captures the essence (reference successful games like "A roguelike deck-builder where you climb a mysterious spire" as examples) +Develop an elevator pitch (2-3 sentences) that would compel a publisher or player - refine until it's concise but hooks attention +Explore their aspirational vision statement: the experience they want to create and what makes it meaningful - ensure it's ambitious yet achievable +Refine through conversation, challenging vague language and elevating compelling ideas core_concept elevator_pitch @@ -101,32 +76,11 @@ Your answers: -Who will play your game? - -**Primary Audience:** - -- Age range -- Gaming experience level (casual, core, hardcore) -- Preferred genres -- Platform preferences -- Typical play session length -- Why will THIS game appeal to them? - -**Secondary Audience** (if applicable): - -- Who else might enjoy this game? -- How might their needs differ? - -**Market Context:** - -- What's the market opportunity? -- Are there similar successful games? -- What's the competitive landscape? -- Why is now the right time for this game? - -Push for specificity beyond "people who like fun games" -Help identify a realistic and reachable audience -Document market evidence or assumptions +Guide user to define their primary target audience with specific demographics, gaming preferences, and behavioral characteristics +Push for specificity beyond generic descriptions like "people who like fun games" - challenge vague answers +Explore secondary audiences if applicable and how their needs might differ +Investigate the market context: opportunity size, competitive landscape, similar successful games, and why now is the right time +Help identify a realistic and reachable audience segment based on evidence or well-reasoned assumptions primary_audience secondary_audience @@ -134,32 +88,12 @@ Your answers: -Let's define your core gameplay. - -**Core Gameplay Pillars (2-4 fundamental elements):** -These are the pillars that define your game. Everything should support these. -Examples: - -- "Tight controls + challenging combat + rewarding exploration" (Hollow Knight) -- "Emergent stories + survival tension + creative problem solving" (RimWorld) -- "Strategic depth + quick sessions + massive replayability" (Into the Breach) - -**Primary Mechanics:** -What does the player actually DO? - -- Core actions (jump, shoot, build, manage, etc.) -- Key systems (combat, resource management, progression, etc.) -- Interaction model (real-time, turn-based, etc.) - -**Player Experience Goals:** -What emotions and experiences are you designing for? -Examples: tension and relief, mastery and growth, creativity and expression, discovery and surprise - -Your game fundamentals: - -Ensure pillars are specific and measurable -Focus on player actions, not implementation details -Connect mechanics to emotional experience +Help user identify 2-4 core gameplay pillars that fundamentally define their game - everything should support these pillars +Provide examples from successful games for inspiration (Hollow Knight's "tight controls + challenging combat + rewarding exploration") +Explore what the player actually DOES - core actions, key systems, and interaction models +Define the emotional experience goals: what feelings are you designing for (tension/relief, mastery/growth, creativity/expression, discovery/surprise) +Ensure pillars are specific and measurable, focusing on player actions rather than implementation details +Connect mechanics directly to emotional experiences through guided discussion core_gameplay_pillars primary_mechanics @@ -167,46 +101,13 @@ Your game fundamentals: -Let's establish realistic constraints. - -**Target Platforms:** - -- PC (Steam, itch.io, Epic)? -- Console (which ones)? -- Mobile (iOS, Android)? -- Web browser? -- Priority order if multiple? - -**Development Timeline:** - -- Target release date or timeframe? -- Are there fixed deadlines (game jams, funding milestones)? -- Phased release (early access, beta)? - -**Budget Considerations:** - -- Self-funded, grant-funded, publisher-backed? -- Asset creation budget (art, audio, voice)? -- Marketing budget? -- Tools and software costs? - -**Team Resources:** - -- Team size and roles? -- Full-time or part-time? -- Skills available vs. skills needed? -- Outsourcing plans? - -**Technical Constraints:** - -- Engine preference or requirement? -- Performance targets (frame rate, load times)? -- File size limits? -- Accessibility requirements? - -Help user be realistic about scope -Identify potential blockers early -Document assumptions about resources +Help user establish realistic project constraints across all key dimensions +Explore target platforms and prioritization (PC, console, mobile, web) +Discuss development timeline: release targets, fixed deadlines, phased release strategies +Investigate budget reality: funding source, asset creation costs, marketing, tools and software +Assess team resources: size, roles, availability, skills gaps, outsourcing needs +Define technical constraints: engine choice, performance targets, file size limits, accessibility requirements +Push for realism about scope - identify potential blockers early and document resource assumptions target_platforms development_timeline @@ -216,34 +117,11 @@ Your game fundamentals: -Let's identify your reference games and position. - -**Inspiration Games:** -List 3-5 games that inspire this project. For each: - -- Game name -- What you're drawing from it (mechanic, feel, art style, etc.) -- What you're NOT taking from it - -**Competitive Analysis:** -What games are most similar to yours? - -- Direct competitors (very similar games) -- Indirect competitors (solve same player need differently) -- What they do well -- What they do poorly -- What your game will do differently - -**Key Differentiators:** -What makes your game unique? - -- What's your hook? -- Why will players choose your game over alternatives? -- What can you do that others can't or won't? - -Help identify genuine differentiation vs. "just better" -Look for specific, concrete differences -Validate differentiators are actually valuable to players +Guide user to identify 3-5 inspiration games and articulate what they're drawing from each (mechanics, feel, art style) and explicitly what they're NOT taking +Conduct competitive analysis: identify direct and indirect competitors, analyze what they do well and poorly, and define how this game will differ +Explore key differentiators and unique value proposition - what's the hook that makes players choose this game over alternatives +Challenge "just better" thinking - push for genuine, specific differentiation that's actually valuable to players +Validate that differentiators are concrete, achievable, and compelling inspiration_games competitive_analysis @@ -251,33 +129,11 @@ What makes your game unique? -Let's scope your content needs. - -**World and Setting:** - -- Where/when does your game take place? -- How much world-building is needed? -- Is narrative important (critical, supporting, minimal)? -- Real-world or fantasy/sci-fi? - -**Narrative Approach:** - -- Story-driven, story-light, or no story? -- Linear, branching, or emergent narrative? -- Cutscenes, dialogue, environmental storytelling? -- How much writing is needed? - -**Content Volume:** -Estimate the scope: - -- How long is a typical playthrough? -- How many levels/stages/areas? -- Replayability approach (procedural, unlocks, multiple paths)? -- Asset volume (characters, enemies, items, environments)? - -Help estimate content realistically -Identify if narrative workflow will be needed later -Flag content-heavy areas that need planning +Explore the game's world and setting: location, time period, world-building depth, narrative importance, and genre context +Define narrative approach: story-driven/light/absent, linear/branching/emergent, delivery methods (cutscenes, dialogue, environmental), writing scope +Estimate content volume realistically: playthrough length, level/stage count, replayability strategy, total asset volume +Identify if a dedicated narrative workflow will be needed later based on story complexity +Flag content-heavy areas that require detailed planning and resource allocation world_setting narrative_approach @@ -285,33 +141,11 @@ Estimate the scope: -What should your game look and sound like? - -**Visual Style:** - -- Art style (pixel art, low-poly, hand-drawn, realistic, etc.) -- Color palette and mood -- Reference images or games with similar aesthetics -- 2D or 3D? -- Animation requirements - -**Audio Style:** - -- Music genre and mood -- SFX approach (realistic, stylized, retro) -- Voice acting needs (full, partial, none)? -- Audio importance to gameplay (critical or supporting) - -**Production Approach:** - -- Creating assets in-house or outsourcing? -- Asset store usage? -- Generative/AI tools? -- Style complexity vs. team capability? - -Ensure art/audio vision aligns with budget and team skills -Identify potential production bottlenecks -Note if style guide will be needed +Explore visual style direction: art style preference, color palette and mood, reference games/images, 2D vs 3D, animation requirements +Define audio style: music genre and mood, SFX approach, voice acting scope, audio's importance to gameplay +Discuss production approach: in-house creation vs outsourcing, asset store usage, AI/generative tools, style complexity vs team capability +Ensure art and audio vision aligns realistically with budget and team skills - identify potential production bottlenecks early +Note if a comprehensive style guide will be needed for consistent production visual_style audio_style @@ -319,38 +153,11 @@ Estimate the scope: -Let's identify potential risks honestly. - -**Key Risks:** - -- What could prevent this game from being completed? -- What could make it not fun? -- What assumptions are you making that might be wrong? - -**Technical Challenges:** - -- Any unproven technical elements? -- Performance concerns? -- Platform-specific challenges? -- Middleware or tool dependencies? - -**Market Risks:** - -- Is the market saturated? -- Are you dependent on a trend or platform? -- Competition concerns? -- Discoverability challenges? - -**Mitigation Strategies:** -For each major risk, what's your plan? - -- How will you validate assumptions? -- What's the backup plan? -- Can you prototype risky elements early? - -Encourage honest risk assessment -Focus on actionable mitigation, not just worry -Prioritize risks by impact and likelihood +Facilitate honest risk assessment across all dimensions - what could prevent completion, what could make it unfun, what assumptions might be wrong +Identify technical challenges: unproven elements, performance concerns, platform-specific issues, tool dependencies +Explore market risks: saturation, trend dependency, competition intensity, discoverability challenges +For each major risk, develop actionable mitigation strategies - how to validate assumptions, backup plans, early prototyping opportunities +Prioritize risks by impact and likelihood, focusing on proactive mitigation rather than passive worry key_risks technical_challenges @@ -359,38 +166,11 @@ For each major risk, what's your plan? -What does success look like? - -**MVP Definition:** -What's the absolute minimum playable version? - -- Core loop must be fun and complete -- Essential content only -- What can be added later? -- When do you know MVP is "done"? - -**Success Metrics:** -How will you measure success? - -- Players acquired -- Retention rate (daily, weekly) -- Session length -- Completion rate -- Review scores -- Revenue targets (if commercial) -- Community engagement - -**Launch Goals:** -What are your concrete targets for launch? - -- Sales/downloads in first month? -- Review score target? -- Streamer/press coverage goals? -- Community size goals? - -Push for specific, measurable goals -Distinguish between MVP and full release -Ensure goals are realistic given resources +Define the MVP (Minimum Playable Version) - what's the absolute minimum where the core loop is fun and complete, with essential content only +Establish specific, measurable success metrics: player acquisition, retention rates, session length, completion rate, review scores, revenue targets, community engagement +Set concrete launch goals: first-month sales/downloads, review score targets, streamer/press coverage, community size +Push for specificity and measurability - challenge vague aspirations with "how will you measure that?" +Clearly distinguish between MVP milestones and full release goals, ensuring all targets are realistic given resources mvp_definition success_metrics @@ -398,36 +178,11 @@ What are your concrete targets for launch? -What needs to happen next? - -**Immediate Actions:** -What should you do right after this brief? - -- Prototype a core mechanic? -- Create art style test? -- Validate technical feasibility? -- Build vertical slice? -- Playtest with target audience? - -**Research Needs:** -What do you still need to learn? - -- Market validation? -- Technical proof of concept? -- Player interest testing? -- Competitive deep-dive? - -**Open Questions:** -What are you still uncertain about? - -- Design questions to resolve -- Technical unknowns -- Market validation needs -- Resource/budget questions - -Create actionable next steps -Prioritize by importance and dependency -Identify blockers that need resolution +Identify immediate actions to take right after this brief: prototype core mechanics, create art style tests, validate technical feasibility, build vertical slice, playtest with target audience +Determine research needs: market validation, technical proof of concept, player interest testing, competitive deep-dive +Document open questions and uncertainties: unresolved design questions, technical unknowns, market validation needs, resource/budget questions +Create actionable, specific next steps - prioritize by importance and dependency +Identify blockers that must be resolved before moving forward immediate_actions research_needs @@ -529,7 +284,8 @@ What are you still uncertain about? 1. Review the entire document 2. Make final adjustments -3. Save and prepare for GDD creation +3. Generate an executive summary version (3-page limit) +4. Save and prepare for GDD creation This brief will serve as the primary input for creating the Game Design Document (GDD). @@ -539,7 +295,12 @@ This brief will serve as the primary input for creating the Game Design Document - Proceed to GDD workflow: `workflow gdd` - Validate assumptions with target players +If user chooses option 3 (executive summary): +Create condensed 3-page executive brief focusing on: core concept, target market, gameplay pillars, key differentiators, and success criteria +Save as: {output_folder}/game-brief-executive-{{game_name}}-{{date}}.md + final_brief +executive_brief @@ -565,11 +326,11 @@ This brief will serve as the primary input for creating the Game Design Document - **{{date}}**: Completed game-brief workflow. Game brief document generated and saved. Next: Proceed to plan-project workflow to create Game Design Document (GDD). ``` -**✅ Game Brief Complete** +**✅ Game Brief Complete, {user_name}!** **Brief Document:** -- Game brief saved and ready for GDD creation +- Game brief saved to {output_folder}/game-brief-{{game_name}}-{{date}}.md **Status file updated:** @@ -588,11 +349,11 @@ Check status anytime with: `workflow-status` - **✅ Game Brief Complete** + **✅ Game Brief Complete, {user_name}!** **Brief Document:** -- Game brief saved and ready for GDD creation +- Game brief saved to {output_folder}/game-brief-{{game_name}}-{{date}}.md Note: Running in standalone mode (no status file). diff --git a/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml b/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml index 42fa84f7..1a7681b3 100644 --- a/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml @@ -3,10 +3,11 @@ name: game-brief description: "Interactive game brief creation workflow that guides users through defining their game vision with multiple input sources and conversational collaboration" author: "BMad" -# Critical variables +# Critical variables from config config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional input documents @@ -28,17 +29,15 @@ default_output_file: "{output_folder}/game-brief-{{game_name}}-{{date}}.md" # Workflow settings autonomous: false # This is an interactive workflow requiring user collaboration -brief_format: "comprehensive" # Options: "comprehensive" (full detail) or "executive" (3-page limit) web_bundle: name: "game-brief" description: "Interactive game brief creation workflow that guides users through defining their game vision with multiple input sources and conversational collaboration" author: "BMad" - instructions: "bmad/bmm/workflows/1-analysis/product-brief/instructions.md" - validation: "bmad/bmm/workflows/1-analysis/product-brief/checklist.md" + instructions: "bmad/bmm/workflows/1-analysis/game-brief/instructions.md" + validation: "bmad/bmm/workflows/1-analysis/game-brief/checklist.md" template: "bmad/bmm/workflows/1-analysis/game-brief/template.md" - use_advanced_elicitation: true web_bundle_files: - - "bmad/bmm/workflows/1-analysis/game-brief/template.md" - "bmad/bmm/workflows/1-analysis/game-brief/instructions.md" - "bmad/bmm/workflows/1-analysis/game-brief/checklist.md" + - "bmad/bmm/workflows/1-analysis/game-brief/template.md" 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 57d02f01..7ded6269 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md @@ -2,6 +2,7 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} @@ -34,31 +35,18 @@ What would you like to do? -Welcome the user to the Product Brief creation process -Explain this is a collaborative process to define their product vision -Ask the user to provide the project name for this product brief +Welcome the user in {communication_language} to the Product Brief creation process +Explain this is a collaborative process to define their product vision and strategic foundation +Ask the user to provide the project name for this product brief project_name -Check what inputs the user has available: -Do you have any of these documents to help inform the brief? -1. Market research -2. Brainstorming results -3. Competitive analysis -4. Initial product ideas or notes -5. None - let's start fresh - -Please share any documents you have or select option 5. - -Load and analyze any provided documents -Extract key insights and themes from input documents - -Based on what you've shared (or if starting fresh), please tell me: - -- What's the core problem you're trying to solve? -- Who experiences this problem most acutely? -- What sparked this product idea? +Explore what existing materials the user has available to inform the brief +Offer options for input sources: market research, brainstorming results, competitive analysis, initial ideas, or starting fresh +If documents are provided, load and analyze them to extract key insights, themes, and patterns +Engage the user about their core vision: what problem they're solving, who experiences it most acutely, and what sparked this product idea +Build initial understanding through conversational exploration rather than rigid questioning initial_context @@ -76,70 +64,39 @@ Which approach works best for you? -Let's dig deeper into the problem. Tell me: -- What's the current state that frustrates users? -- Can you quantify the impact? (time lost, money spent, opportunities missed) -- Why do existing solutions fall short? -- Why is solving this urgent now? - -Challenge vague statements and push for specificity -Help the user articulate measurable pain points -Create a compelling problem statement with evidence +Guide deep exploration of the problem: current state frustrations, quantifiable impact (time/money/opportunities), why existing solutions fall short, urgency of solving now +Challenge vague statements and push for specificity with probing questions +Help the user articulate measurable pain points with evidence +Craft a compelling, evidence-based problem statement problem_statement -Now let's shape your solution vision: -- What's your core approach to solving this problem? -- What makes your solution different from what exists? -- Why will this succeed where others haven't? -- Paint me a picture of the ideal user experience - -Focus on the "what" and "why", not implementation details -Help articulate key differentiators -Craft a clear solution vision +Shape the solution vision by exploring: core approach to solving the problem, key differentiators from existing solutions, why this will succeed, ideal user experience +Focus on the "what" and "why", not implementation details - keep it strategic +Help articulate compelling differentiators that make this solution unique +Craft a clear, inspiring solution vision proposed_solution -Who exactly will use this product? Let's get specific: - -For your PRIMARY users: - -- What's their demographic/professional profile? -- What are they currently doing to solve this problem? -- What specific pain points do they face? -- What goals are they trying to achieve? - -Do you have a SECONDARY user segment? If so, let's define them too. - -Push beyond generic personas like "busy professionals" -Create specific, actionable user profiles -[VISUAL PLACEHOLDER: User persona cards or journey map would be valuable here] +Guide detailed definition of primary users: demographic/professional profile, current problem-solving methods, specific pain points, goals they're trying to achieve +Explore secondary user segments if applicable and define how their needs differ +Push beyond generic personas like "busy professionals" - demand specificity and actionable details +Create specific, actionable user profiles that inform product decisions primary_user_segment secondary_user_segment -What does success look like? Let's set SMART goals: - -Business objectives (with measurable outcomes): - -- Example: "Acquire 1000 paying users within 6 months" -- Example: "Reduce customer support tickets by 40%" - -User success metrics (behaviors/outcomes, not features): - -- Example: "Users complete core task in under 2 minutes" -- Example: "70% of users return weekly" - -What are your top 3-5 Key Performance Indicators? - -Help formulate specific, measurable goals -Distinguish between business and user success +Guide establishment of SMART goals across business objectives and user success metrics +Explore measurable business outcomes (user acquisition targets, cost reductions, revenue goals) +Define user success metrics focused on behaviors and outcomes, not features (task completion time, return frequency) +Help formulate specific, measurable goals that distinguish between business and user success +Identify top 3-5 Key Performance Indicators that will track product success business_objectives user_success_metrics @@ -147,24 +104,11 @@ What are your top 3-5 Key Performance Indicators? -Let's be ruthless about MVP scope. - -What are the absolute MUST-HAVE features for launch? - -- Think: What's the minimum to validate your core hypothesis? -- For each feature, why is it essential? - -What tempting features need to wait for v2? - -- What would be nice but isn't critical? -- What adds complexity without core value? - -What would constitute a successful MVP launch? - -[VISUAL PLACEHOLDER: Consider a feature priority matrix or MoSCoW diagram] - -Challenge scope creep aggressively -Push for true minimum viability +Be ruthless about MVP scope - identify absolute MUST-HAVE features for launch that validate the core hypothesis +For each proposed feature, probe why it's essential vs nice-to-have +Identify tempting features that need to wait for v2 - what adds complexity without core value +Define what constitutes a successful MVP launch with clear criteria +Challenge scope creep aggressively and push for true minimum viability Clearly separate must-haves from nice-to-haves core_features @@ -172,115 +116,53 @@ What would constitute a successful MVP launch? mvp_success_criteria - -Let's talk numbers and strategic value: - -**Financial Considerations:** - -- What's the expected development investment (budget/resources)? -- What's the revenue potential or cost savings opportunity? -- When do you expect to reach break-even? -- How does this align with available budget? - -**Strategic Alignment:** - -- Which company OKRs or strategic objectives does this support? -- How does this advance key strategic initiatives? -- What's the opportunity cost of NOT doing this? - -[VISUAL PLACEHOLDER: Consider adding a simple ROI projection chart here] - -Help quantify financial impact where possible -Connect to broader company strategy -Document both tangible and intangible value + +Explore financial considerations: development investment, revenue potential, cost savings opportunities, break-even timing, budget alignment +Investigate strategic alignment: company OKRs, strategic objectives, key initiatives supported, opportunity cost of NOT doing this +Help quantify financial impact where possible - both tangible and intangible value +Connect this product to broader company strategy and demonstrate strategic value financial_impact company_objectives_alignment strategic_initiatives - -Looking beyond MVP (optional but helpful): - -If the MVP succeeds, what comes next? - -- Phase 2 features? -- Expansion opportunities? -- Long-term vision (1-2 years)? - -This helps ensure MVP decisions align with future direction. + +Guide exploration of post-MVP future: Phase 2 features, expansion opportunities, long-term vision (1-2 years) +Ensure MVP decisions align with future direction while staying focused on immediate goals phase_2_features long_term_vision expansion_opportunities - -Let's capture technical context. These are preferences, not final decisions: - -Platform requirements: - -- Web, mobile, desktop, or combination? -- Browser/OS support needs? -- Performance requirements? -- Accessibility standards? - -Do you have technology preferences or constraints? - -- Frontend frameworks? -- Backend preferences? -- Database needs? -- Infrastructure requirements? - -Any existing systems to integrate with? - + +Capture technical context as preferences, not final decisions +Explore platform requirements: web/mobile/desktop, browser/OS support, performance needs, accessibility standards +Investigate technology preferences or constraints: frontend/backend frameworks, database needs, infrastructure requirements +Identify existing systems requiring integration Check for technical-preferences.yaml file if available -Note these are initial thoughts for PM and architect to consider +Note these are initial thoughts for PM and architect to consider during planning platform_requirements technology_preferences architecture_considerations - -Let's set realistic expectations: - -What constraints are you working within? - -- Budget or resource limits? -- Timeline or deadline pressures? -- Team size and expertise? -- Technical limitations? - -What assumptions are you making? - -- About user behavior? -- About the market? -- About technical feasibility? - -Document constraints clearly -List assumptions to validate during development + +Guide realistic expectations setting around constraints: budget/resource limits, timeline pressures, team size/expertise, technical limitations +Explore assumptions being made about: user behavior, market conditions, technical feasibility +Document constraints clearly and list assumptions that need validation during development constraints key_assumptions - -What keeps you up at night about this project? - -Key risks: - -- What could derail the project? -- What's the impact if these risks materialize? - -Open questions: - -- What do you still need to figure out? -- What needs more research? - -[VISUAL PLACEHOLDER: Risk/impact matrix could help prioritize] - -Being honest about unknowns helps us prepare. + +Facilitate honest risk assessment: what could derail the project, impact if risks materialize +Document open questions: what still needs figuring out, what needs more research +Help prioritize risks by impact and likelihood +Frame unknowns as opportunities to prepare, not just worries key_risks open_questions @@ -371,11 +253,17 @@ Being honest about unknowns helps us prepare. 1. Review the entire document 2. Make final adjustments -3. Save and prepare for handoff to PM +3. Generate an executive summary version (3-page limit) +4. Save and prepare for handoff to PM This brief will serve as the primary input for creating the Product Requirements Document (PRD). +If user chooses option 3 (executive summary): +Create condensed 3-page executive brief focusing on: problem statement, proposed solution, target users, MVP scope, financial impact, and strategic alignment +Save as: {output_folder}/product-brief-executive-{{project_name}}-{{date}}.md + final_brief +executive_brief @@ -401,11 +289,11 @@ This brief will serve as the primary input for creating the Product Requirements - **{{date}}**: Completed product-brief workflow. Product brief document generated and saved. Next: Proceed to plan-project workflow to create Product Requirements Document (PRD). ``` -**✅ Product Brief Complete** +**✅ Product Brief Complete, {user_name}!** **Brief Document:** -- Product brief saved and ready for handoff +- Product brief saved to {output_folder}/product-brief-{{project_name}}-{{date}}.md **Status file updated:** 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 f82eb7fe..c4550bac 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml @@ -3,10 +3,11 @@ name: product-brief description: "Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration" author: "BMad" -# Critical variables +# Critical variables from config config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional input documents @@ -27,7 +28,6 @@ default_output_file: "{output_folder}/product-brief-{{project_name}}-{{date}}.md # Workflow settings autonomous: false # This is an interactive workflow requiring user collaboration -brief_format: "comprehensive" # Options: "comprehensive" (full detail) or "executive" (3-page limit) web_bundle: name: "product-brief" @@ -36,7 +36,6 @@ web_bundle: instructions: "bmad/bmm/workflows/1-analysis/product-brief/instructions.md" validation: "bmad/bmm/workflows/1-analysis/product-brief/checklist.md" template: "bmad/bmm/workflows/1-analysis/product-brief/template.md" - use_advanced_elicitation: true web_bundle_files: - "bmad/bmm/workflows/1-analysis/product-brief/template.md" - "bmad/bmm/workflows/1-analysis/product-brief/instructions.md" diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-router.md b/src/modules/bmm/workflows/1-analysis/research/instructions-router.md index 79e1f9db..46560ad0 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-router.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-router.md @@ -2,12 +2,14 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml -This is a ROUTER that directs to specialized research instruction sets +Communicate all responses in {communication_language} +This is a ROUTER that directs to specialized research instruction sets + Search {output_folder}/ for files matching pattern: bmm-workflow-status.md Find the most recent file (by date in filename: bmm-workflow-status.md) diff --git a/src/modules/bmm/workflows/1-analysis/research/workflow.yaml b/src/modules/bmm/workflows/1-analysis/research/workflow.yaml index 1c0a9915..b31a9404 100644 --- a/src/modules/bmm/workflows/1-analysis/research/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/research/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Workflow components - ROUTER PATTERN @@ -24,129 +25,8 @@ template_market: "{installed_path}/template-market.md" template_deep_prompt: "{installed_path}/template-deep-prompt.md" template_technical: "{installed_path}/template-technical.md" -# Output configuration (dynamic based on research type) +# Output configuration (dynamic based on research type selected in router) default_output_file: "{output_folder}/research-{{research_type}}-{{date}}.md" -market_output: "{output_folder}/market-research-{{product_name_slug}}-{{date}}.md" -deep_prompt_output: "{output_folder}/deep-research-prompt-{{date}}.md" -technical_output: "{output_folder}/technical-research-{{date}}.md" - -# Research types supported -research_types: - market: - name: "Market Research" - description: "Comprehensive market analysis with TAM/SAM/SOM" - instructions: "{instructions_market}" - template: "{template_market}" - output: "{market_output}" - deep_prompt: - name: "Deep Research Prompt Generator" - description: "Generate optimized prompts for AI research platforms" - instructions: "{instructions_deep_prompt}" - template: "{template_deep_prompt}" - output: "{deep_prompt_output}" - technical: - name: "Technical/Architecture Research" - description: "Technology evaluation and architecture pattern research" - instructions: "{instructions_technical}" - template: "{template_technical}" - output: "{technical_output}" - competitive: - name: "Competitive Intelligence" - description: "Deep competitor analysis" - instructions: "{instructions_market}" # Uses market with competitive focus - template: "{template_market}" - output: "{output_folder}/competitive-intelligence-{{date}}.md" - user: - name: "User Research" - description: "Customer insights and persona development" - instructions: "{instructions_market}" # Uses market with user focus - template: "{template_market}" - output: "{output_folder}/user-research-{{date}}.md" - domain: - name: "Domain/Industry Research" - description: "Industry and domain deep dives" - instructions: "{instructions_market}" # Uses market with domain focus - template: "{template_market}" - output: "{output_folder}/domain-research-{{date}}.md" - -# Research parameters (can be overridden at runtime) -research_depth: "comprehensive" # Options: quick, standard, comprehensive -enable_web_research: true -enable_competitor_analysis: true -enable_financial_modeling: true - -# Data sources and tools -required_tools: - - web_search: "For real-time data gathering across all research types" - - calculator: "For calculations (TAM/SAM/SOM, TCO, etc.)" - - data_analysis: "For trends, patterns, and comparative analysis" - -# Recommended input documents (varies by research type) -recommended_inputs: - market: - - product_brief: "Product or business description" - - target_customers: "Customer segment hypotheses" - - competitor_list: "Known competitors (optional)" - technical: - - requirements_doc: "Technical requirements" - - architecture_doc: "Current architecture (if brownfield)" - - constraints_list: "Technical constraints" - deep_prompt: - - research_question: "Initial research question or topic" - - context_docs: "Background documents for context" - -# Claude Code integration points -claude_code_enhancements: - - injection_point: "research-subagents" - - available_subagents: - - market-researcher: "Deep market intelligence gathering" - - trend-spotter: "Emerging trends and weak signals" - - data-analyst: "Quantitative analysis" - - competitor-analyzer: "Competitive intelligence" - - user-researcher: "Customer insights" - - technical-evaluator: "Technology assessment" - -# Workflow configuration -interactive: true # User checkpoints throughout -autonomous: false # Requires user input -allow_parallel: true # Can run research tasks in parallel - -# Research frameworks available (context dependent) -frameworks: - market: - - "TAM/SAM/SOM Analysis" - - "Porter's Five Forces" - - "Jobs-to-be-Done" - - "Technology Adoption Lifecycle" - - "SWOT Analysis" - - "Value Chain Analysis" - technical: - - "Trade-off Analysis" - - "Architecture Decision Records (ADR)" - - "Technology Radar" - - "Comparison Matrix" - - "Cost-Benefit Analysis" - deep_prompt: - - "ChatGPT Deep Research Best Practices" - - "Gemini Deep Research Framework" - - "Grok DeepSearch Optimization" - - "Claude Projects Methodology" - - "Iterative Prompt Refinement" - -# Data sources (for web research) -data_sources: - - "Industry reports and publications" - - "Government statistics and databases" - - "Financial reports and SEC filings" - - "News articles and press releases" - - "Academic research papers" - - "Technical documentation and RFCs" - - "GitHub repositories and discussions" - - "Stack Overflow and developer forums" - - "Market research firm reports" - - "Social media and communities" - - "Patent databases" - - "Benchmarking studies" web_bundle: name: "research" @@ -154,7 +34,6 @@ web_bundle: author: "BMad" instructions: "bmad/bmm/workflows/1-analysis/research/instructions-router.md" # Router loads specific instruction sets validation: "bmad/bmm/workflows/1-analysis/research/checklist.md" - use_advanced_elicitation: true web_bundle_files: - "bmad/bmm/workflows/1-analysis/research/instructions-router.md" - "bmad/bmm/workflows/1-analysis/research/instructions-market.md" @@ -164,82 +43,3 @@ web_bundle: - "bmad/bmm/workflows/1-analysis/research/template-deep-prompt.md" - "bmad/bmm/workflows/1-analysis/research/template-technical.md" - "bmad/bmm/workflows/1-analysis/research/checklist.md" - # Workflow configuration - interactive: true # User checkpoints throughout - autonomous: false # Requires user input - allow_parallel: true # Can run research tasks in parallel - - # Research frameworks available (context dependent) - frameworks: - market: - - "TAM/SAM/SOM Analysis" - - "Porter's Five Forces" - - "Jobs-to-be-Done" - - "Technology Adoption Lifecycle" - - "SWOT Analysis" - - "Value Chain Analysis" - technical: - - "Trade-off Analysis" - - "Architecture Decision Records (ADR)" - - "Technology Radar" - - "Comparison Matrix" - - "Cost-Benefit Analysis" - deep_prompt: - - "ChatGPT Deep Research Best Practices" - - "Gemini Deep Research Framework" - - "Grok DeepSearch Optimization" - - "Claude Projects Methodology" - - "Iterative Prompt Refinement" - - # Data sources (for web research) - data_sources: - - "Industry reports and publications" - - "Government statistics and databases" - - "Financial reports and SEC filings" - - "News articles and press releases" - - "Academic research papers" - - "Technical documentation and RFCs" - - "GitHub repositories and discussions" - - "Stack Overflow and developer forums" - - "Market research firm reports" - - "Social media and communities" - - "Patent databases" - - "Benchmarking studies" - # Research types supported - research_types: - market: - name: "Market Research" - description: "Comprehensive market analysis with TAM/SAM/SOM" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-market.md" - template: "bmad/bmm/workflows/1-analysis/research/template-market.md" - output: "{market_output}" - deep_prompt: - name: "Deep Research Prompt Generator" - description: "Generate optimized prompts for AI research platforms" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-deep-prompt.md" - template: "bmad/bmm/workflows/1-analysis/research/template-deep-prompt.md" - output: "{deep_prompt_output}" - technical: - name: "Technical/Architecture Research" - description: "Technology evaluation and architecture pattern research" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-technical.md" - template: "bmad/bmm/workflows/1-analysis/research/template-technical.md" - output: "{technical_output}" - competitive: - name: "Competitive Intelligence" - description: "Deep competitor analysis" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-market.md" # Uses market with competitive focus - template: "bmad/bmm/workflows/1-analysis/research/template-market.md" - output: "{output_folder}/competitive-intelligence-{{date}}.md" - user: - name: "User Research" - description: "Customer insights and persona development" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-market.md" # Uses market with user focus - template: "bmad/bmm/workflows/1-analysis/research/template-market.md" - output: "{output_folder}/user-research-{{date}}.md" - domain: - name: "Domain/Industry Research" - description: "Industry and domain deep dives" - instructions: "bmad/bmm/workflows/1-analysis/research/instructions-market.md" # Uses market with domain focus - template: "bmad/bmm/workflows/1-analysis/research/template-market.md" - output: "{output_folder}/domain-research-{{date}}.md" diff --git a/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md b/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md index de9e2546..bf8f70ce 100644 --- a/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/workflow-status/instructions.md @@ -1,5 +1,9 @@ # Workflow Status - Master Router and Status Tracker +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/1-analysis/workflow-status/workflow.yaml +Communicate all responses in {communication_language} + This is the UNIVERSAL ENTRY POINT for all BMM workflows @@ -158,9 +162,9 @@ Or tell me: "load {{next_agent}} and {{next_command}}" -Display welcome message +Display welcome message in {communication_language} -**🚀 Welcome to BMad Method Workflows!** +**🚀 Welcome to BMad Method Workflows, {user_name}!** No workflow status file found. Let's plan your complete workflow journey. @@ -424,13 +428,45 @@ Based on your responses, here's your complete workflow journey: {{/if}} -Always add Phase 2 (required for all levels) +Always add Phase 2 (required for all levels) - route based on project type and level -- Phase: "2-Plan" -- Step: "plan-project" -- Agent: "PM" -- Description: "Create PRD/GDD/Tech-Spec (determines final level)" -- Status: "Planned" + + Add game planning workflow + - Phase: "2-Plan" + - Step: "gdd" + - Agent: "PM" + - Description: "Create Game Design Document" + - Status: "Planned" + + + + + Add tech-spec workflow (Levels 0-1) + - Phase: "2-Plan" + - Step: "tech-spec" + - Agent: "Architect" + - Description: "Create technical specification and stories" + - Status: "Planned" + + + + Add PRD workflow (Levels 2-4) + - Phase: "2-Plan" + - Step: "prd" + - Agent: "PM" + - Description: "Create Product Requirements Document and epics" + - Status: "Planned" + + + + Add conditional planning note + - Phase: "2-Plan" + - Step: "TBD - Level 0-1 → tech-spec, Level 2-4 → prd" + - Agent: "PM or Architect" + - Description: "Workflow determined after level assessment" + - Status: "Conditional" + + Add UX workflow to Phase 2 planning (runs after PRD, before Phase 3) @@ -536,7 +572,7 @@ Create status file? (y/n) Set next_agent = planned_workflow[0].agent Include complete planned_workflow in status file -**✅ Status file created!** +**✅ Status file created, {user_name}!** File: `bmm-workflow-status.md` @@ -549,8 +585,16 @@ After documentation is complete, return to check status: `bmad analyst workflow- {{/if}} {{#if planned_workflow[0].step != "document-project" AND planned_workflow[0].step != "user-choice"}} +{{#if planned_workflow[0].step == "gdd"}} +Load PM: `bmad pm gdd` +{{else if planned_workflow[0].step == "tech-spec"}} +Load Architect: `bmad architect tech-spec` +{{else if planned_workflow[0].step == "prd"}} +Load PM: `bmad pm prd` +{{else}} Load {{planned_workflow[0].agent}}: `bmad {{lowercase planned_workflow[0].agent}} {{planned_workflow[0].step}}` {{/if}} +{{/if}} {{#if planned_workflow[0].step == "user-choice"}} Your status file is ready! Run `workflow-status` anytime to see recommendations. @@ -596,9 +640,9 @@ Continue? (y/n) **To start new workflow:** -Load PM agent: `bmad pm plan-project` +Run: `bmad analyst workflow-status` -This will create a new workflow status file and guide you through fresh assessment. +This will guide you through fresh workflow assessment and create a new status file. @@ -644,7 +688,9 @@ Which phase? (1-4) **Phase 2: Planning (Required)** -- `plan-project` - Scale-adaptive planning (PRD, GDD, or Tech-Spec) +- `prd` - Product Requirements Document (Level 2-4 software projects) +- `tech-spec` - Technical specification (Level 0-1 software projects) +- `gdd` - Game Design Document (game projects) - `ux-spec` - UX/UI specification (for projects with UI components) **Phase 3: Solutioning (Level 3-4 Only)** @@ -672,12 +718,14 @@ Which phase? (1-4) **🎯 Recommended for Your Current Phase ({{current_phase}}):** {{#if current_phase == '1-Analysis'}} -Continue analysis or move to `plan-project` +Continue analysis or move to Phase 2 Planning (prd/tech-spec/gdd based on your project) {{/if}} {{#if current_phase == '2-Plan'}} -{{#if project_level < 3}} +{{#if project_level < 2}} Ready for Phase 4! Run `create-story` (SM agent) +{{else if project_level == 2}} +Run `tech-spec` workflow for lightweight technical planning, then Phase 4 {{else}} Ready for Phase 3! Run `solution-architecture` (Architect agent) {{/if}} diff --git a/src/modules/bmm/workflows/1-analysis/workflow-status/workflow.yaml b/src/modules/bmm/workflows/1-analysis/workflow-status/workflow.yaml index 9e2b65a0..9e34649a 100644 --- a/src/modules/bmm/workflows/1-analysis/workflow-status/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/workflow-status/workflow.yaml @@ -14,30 +14,7 @@ date: system-generated installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/workflow-status" instructions: "{installed_path}/instructions.md" -# Variables and inputs -variables: - status_file_pattern: "bmm-workflow-status.md" # Searches for versioned files - check_existing_status: true # Always check for existing status file - display_menu: true # Display agent menu after status check - suggest_next_action: true # Suggest next action based on current state - # Output configuration - no output file, reads existing status default_output_file: "" -required_tools: - - list_files - - read_file - - glob - -tags: - - workflow-orchestration - - status-tracking - - master-router - - bmad-v6 - -execution_hints: - interactive: true # User interaction required for decisions - autonomous: false # Requires user input - iterative: false # Single-pass status check and suggestion - web_bundle: false diff --git a/src/modules/bmm/workflows/2-plan/README.md b/src/modules/bmm/workflows/2-plan-workflows/README.md similarity index 59% rename from src/modules/bmm/workflows/2-plan/README.md rename to src/modules/bmm/workflows/2-plan-workflows/README.md index 560f0c05..983904d7 100644 --- a/src/modules/bmm/workflows/2-plan/README.md +++ b/src/modules/bmm/workflows/2-plan-workflows/README.md @@ -4,11 +4,50 @@ last-redoc-date: 2025-10-01 # Project Planning Workflow (Phase 2) -This scale-adaptive workflow represents the cornerstone of BMM v6's intelligent project orchestration, automatically determining project complexity (Level 0-4) and routing to specialized planning pathways based on project type, scope, and context. Unlike traditional one-size-fits-all planning approaches, it dynamically adjusts output artifacts—from minimal tech specs for atomic changes to comprehensive PRD suites for enterprise platforms—ensuring planning overhead matches project value. The workflow serves as the critical bridge between Phase 1 analysis outputs and Phase 3 solutioning, establishing the contractual foundation for all subsequent development activities. +The Phase 2 Planning workflow is **scale-adaptive**, meaning it automatically determines the right level of planning documentation based on project complexity (Levels 0-4). This ensures planning overhead matches project value—from minimal tech specs for bug fixes to comprehensive PRDs for enterprise platforms. -The workflow's routing intelligence analyzes project characteristics through multi-dimensional assessment: project type (game, web, mobile, backend), context (greenfield vs. brownfield), scope indicators, and complexity signals. Based on this analysis, it classifies projects into five levels with distinct artifact requirements. Level 0 produces only tech specs for single atomic changes. Levels 1-2 generate focused PRDs with embedded tech specs. Levels 3-4 create comprehensive PRDs with separate epics that hand off to the architect-driven solutioning workflow. This classification isn't merely about document generation—it fundamentally changes how requirements are structured, validated, and communicated to downstream consumers. +## Scale-Adaptive Flow (Levels 0-4) -Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For game projects, it routes to specialized GDD generation with genre-specific templates. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs. +The workflow routes to different planning approaches based on project level: + +### Level 0 - Single File Change / Bug Fix + +**Planning:** Tech-spec only (lightweight implementation plan) +**Output:** `tech-spec.md` with single story +**Next Phase:** Direct to implementation (Phase 4) + +### Level 1 - Small Feature (1-3 files, 2-5 stories) + +**Planning:** Tech-spec only (implementation-focused) +**Output:** `tech-spec.md` with epic breakdown and stories +**Next Phase:** Direct to implementation (Phase 4) + +### Level 2 - Feature Set / Small Project (5-15 stories, 1-2 epics) + +**Planning:** PRD (product-focused) + Tech-spec (technical planning) +**Output:** `PRD.md`, `epics.md`, `tech-spec.md` +**Next Phase:** Tech-spec workflow (lightweight solutioning), then implementation (Phase 4) +**Note:** Level 2 uses tech-spec instead of full solution-architecture to keep planning lightweight + +### Level 3 - Medium Project (15-40 stories, 2-5 epics) + +**Planning:** PRD (strategic product document) +**Output:** `PRD.md`, `epics.md` +**Next Phase:** Solution-architecture workflow (Phase 3), then implementation (Phase 4) + +### Level 4 - Large/Enterprise Project (40-100+ stories, 5-10 epics) + +**Planning:** PRD (comprehensive product specification) +**Output:** `PRD.md`, `epics.md` +**Next Phase:** Solution-architecture workflow (Phase 3), then implementation (Phase 4) + +**Critical Distinction:** + +- **Levels 0-1:** No PRD, tech-spec only +- **Level 2:** PRD + tech-spec (skips full architecture) +- **Levels 3-4:** PRD → full solution-architecture workflow + +Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs. ## Key Features @@ -19,24 +58,6 @@ Critical to v6's flow improvement is this workflow's integration with the bmm-wo - **Input integration** - Leverages product briefs and market research when available - **Template-driven** - Uses validated templates for consistent output structure -## Usage - -### Basic Invocation - -```bash -workflow plan-project -``` - -### With Input Documents - -```bash -# With product brief as input -workflow plan-project --input /path/to/product-brief.md - -# With multiple inputs -workflow plan-project --input product-brief.md --input market-research.md -``` - ### Configuration The workflow adapts automatically based on project assessment, but key configuration options include: @@ -50,33 +71,32 @@ The workflow adapts automatically based on project assessment, but key configura ### Files Included ``` -plan-project/ +2-plan-workflows/ ├── README.md # Overview and usage details -├── checklist.md # Validation criteria -├── instructions-router.md # Initial assessment and routing logic -├── workflow.yaml # Configuration and metadata +├── checklist.md # Shared validation criteria +├── prd/ +│ ├── epics-template.md # Epic breakdown template +│ ├── instructions.md # Level 2-4 PRD instructions +│ ├── prd-template.md # Product Requirements Document template +│ └── workflow.yaml +├── tech-spec/ +│ ├── epics-template.md # Epic-to-story handoff template +│ ├── instructions-level0-story.md +│ ├── instructions-level1-stories.md +│ ├── instructions.md # Level 0-1 tech-spec instructions +│ ├── tech-spec-template.md # Technical Specification template +│ ├── user-story-template.md # Story template for Level 0/1 +│ └── workflow.yaml ├── gdd/ -│ ├── gdd-template.md # Game Design Document template -│ ├── instructions-gdd.md # Genre-aware GDD instructions +│ ├── instructions-gdd.md # Game Design Document instructions +│ ├── gdd-template.md # GDD template +│ ├── game-types.csv # Genre catalog +│ ├── game-types/ # Genre-specific templates │ └── workflow.yaml ├── narrative/ │ ├── instructions-narrative.md # Narrative design instructions │ ├── narrative-template.md # Narrative planning template │ └── workflow.yaml -├── prd/ -│ ├── epics-template.md # Epic breakdown template -│ ├── instructions-lg.md # Level 3-4 PRD instructions -│ ├── instructions-med.md # Level 1-2 PRD instructions -│ ├── prd-template.md # Product Requirements Document template -│ └── workflow.yaml -├── tech-spec/ -│ ├── epic-stories-template.md # Epic-to-story handoff template -│ ├── instructions-level0-story.md -│ ├── instructions-level1-stories.md -│ ├── instructions-sm.md # Level 0 tech-spec instructions -│ ├── tech-spec-template.md # Technical Specification template -│ ├── user-story-template.md # Story template for Level 0/1 -│ └── workflow.yaml └── ux/ ├── instructions-ux.md # UX specification instructions ├── ux-spec-template.md # UX specification template @@ -95,23 +115,31 @@ plan-project/ ### Phase 2: Level-Specific Planning (Steps vary by level) -**Level 0 (Single Atomic Change)**: +**Level 0 (Single File Change / Bug Fix)**: -- Creates technical specification only -- Focuses on implementation details for small changes +- Tech-spec only workflow +- Single story implementation plan +- Direct to Phase 4 (implementation) -**Level 1-2 (Features and Small Systems)**: +**Level 1 (Small Feature)**: -- Generates minimal PRD with core sections -- Creates comprehensive tech-spec -- Includes basic epic breakdown +- Tech-spec only workflow +- Epic breakdown with 2-5 stories +- Direct to Phase 4 (implementation) -**Level 3-4 (Full Products and Platforms)**: +**Level 2 (Feature Set / Small Project)**: -- Produces complete PRD with all sections -- Generates detailed epic breakdown -- Includes architect handoff materials -- Creates traceability mapping +- PRD workflow (strategic product document) +- Generates `PRD.md` and `epics.md` +- Then runs tech-spec workflow (lightweight solutioning) +- Then to Phase 4 (implementation) + +**Level 3-4 (Medium to Enterprise Projects)**: + +- PRD workflow (comprehensive product specification) +- Generates `PRD.md` and `epics.md` +- Hands off to Phase 3 (solution-architecture workflow) +- Full architecture design before implementation ### Phase 3: Validation and Handoff (Final steps) @@ -124,33 +152,34 @@ plan-project/ ### Generated Files - **Primary output**: PRD.md (except Level 0), tech-spec.md, bmm-workflow-status.md -- **Supporting files**: epics.md (Level 3-4), PRD-validation-report.md (if validation run) +- **Supporting files**: epics.md (Level 2-4), PRD-validation-report.md (if validation run) ### Output Structure by Level **Level 0 - Tech Spec Only**: -1. **Technical Overview** - Implementation approach -2. **Detailed Design** - Code-level specifications -3. **Testing Strategy** - Validation approach +- `tech-spec.md` - Single story implementation plan +- Direct to implementation -**Level 1-2 - Minimal PRD + Tech Spec**: +**Level 1 - Tech Spec with Epic Breakdown**: -1. **Problem Statement** - Core issue definition -2. **Solution Overview** - High-level approach -3. **Requirements** - Functional and non-functional -4. **Technical Specification** - Implementation details -5. **Success Criteria** - Acceptance criteria +- `tech-spec.md` - Epic breakdown with 2-5 stories +- Direct to implementation -**Level 3-4 - Full PRD + Epics**: +**Level 2 - PRD + Tech Spec**: -1. **Executive Summary** - Project overview -2. **Problem Definition** - Detailed problem analysis -3. **Solution Architecture** - Comprehensive solution design -4. **User Experience** - Journey mapping and wireframes -5. **Requirements** - Complete functional/non-functional specs -6. **Epic Breakdown** - Development phases and stories -7. **Technical Handoff** - Architecture and implementation guidance +- `PRD.md` - Strategic product document (goals, requirements, user journeys, UX principles, UI goals, epic list, scope) +- `epics.md` - Tactical implementation roadmap (detailed story breakdown) +- `tech-spec.md` - Lightweight technical planning (generated after PRD) +- Then to implementation + +**Level 3-4 - PRD + Full Architecture**: + +- `PRD.md` - Comprehensive product specification +- `epics.md` - Complete epic/story breakdown +- Hands off to solution-architecture workflow (Phase 3) +- `solution-architecture.md` - Generated by architect workflow +- Then to implementation ## Requirements diff --git a/src/modules/bmm/workflows/2-plan/gdd/README.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/README.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/README.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/README.md diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/checklist.md new file mode 100644 index 00000000..704bde58 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/checklist.md @@ -0,0 +1,148 @@ +# GDD Workflow Validation Checklist + +**Purpose**: Validate GDD workflow outputs are complete, playable, and ready for solutioning. + +**Scope**: All game project levels (0-4) + +**Expected Outputs**: GDD.md, epics.md + +--- + +## 1. Output Files Exist + +- [ ] GDD.md created in output folder +- [ ] epics.md created in output folder (separate file) +- [ ] bmm-workflow-status.md updated +- [ ] No unfilled {{template_variables}} + +--- + +## 2. Core Gameplay Definition (CRITICAL) + +### Game Pillars + +- [ ] **2-4 game pillars defined** (fundamental gameplay elements) +- [ ] Each pillar is game-defining (not superficial) +- [ ] Pillars are distinct (don't overlap) + +### Core Gameplay Loop + +- [ ] **Complete cycle documented** (what player does repeatedly) +- [ ] Loop shows: player action → outcome → reward → motivation to repeat +- [ ] Loop sounds compelling and repeatable + +### Win/Loss Conditions + +- [ ] Victory conditions clearly defined +- [ ] Failure conditions defined (or N/A for sandbox games) +- [ ] Conditions are testable + +--- + +## 3. Game Mechanics and Systems + +### Mechanics + +- [ ] Primary mechanics described in detail +- [ ] Mechanics support the game pillars +- [ ] Player interaction with mechanics is clear + +### Progression + +- [ ] Player progression system defined (skill/power/unlock/narrative) +- [ ] Difficulty curve explained +- [ ] Progression feels rewarding + +### Platform and Controls + +- [ ] Target platforms specified +- [ ] Control scheme appropriate for platforms +- [ ] Input method clear (keyboard/gamepad/touch/etc.) + +--- + +## 4. Story Quality (If epics.md exists) + +### Epic Structure + +- [ ] Epics represent deliverable game features +- [ ] Epic sequence makes sense for game development +- [ ] Stories show implementation path + +### Story Sequencing (If stories present) + +- [ ] **Vertical slices**: Each story delivers playable functionality +- [ ] **Sequential ordering**: Stories build progressively +- [ ] **No forward dependencies**: Each story builds on previous work only +- [ ] Stories result in testable game features + +--- + +## 5. Technical Specifications + +### Performance and Platform + +- [ ] Performance requirements specified (frame rate, resolution, etc.) +- [ ] Platform-specific considerations noted +- [ ] Asset requirements estimated + +### Production Scope + +- [ ] Art requirements realistic for project scale +- [ ] Audio requirements documented +- [ ] Scope matches project level and resources + +--- + +## 6. Narrative Integration (If Applicable) + +**If narrative-design.md was generated:** + +- [ ] Narrative aligns with GDD game design +- [ ] Story supports gameplay (not fighting it) +- [ ] Tone consistent across GDD and narrative docs + +--- + +## 7. Consistency + +- [ ] Epic titles match between GDD.md and epics.md +- [ ] Game type identified and appropriate +- [ ] Terminology consistent throughout +- [ ] No contradictions between sections + +--- + +## 8. Readiness for Solutioning + +- [ ] Sufficient detail for engine/platform selection +- [ ] Game systems defined enough for technical architecture +- [ ] Clear what needs to be built +- [ ] Playable vision (reader can envision playing the game) + +--- + +## 9. Critical Failures (Auto-Fail) + +- [ ] ❌ **No core gameplay loop** (can't be a game without this) +- [ ] ❌ **No game pillars** (game-defining elements missing) +- [ ] ❌ **No mechanics** (what does player actually DO?) +- [ ] ❌ **No epics.md file** (implementation roadmap required) +- [ ] ❌ **Engine/tech in GDD** (should defer to solutioning workflow) + +--- + +## Validation Notes + +**Document any findings:** + +- Game concept strength: [Compelling / Interesting / Unclear / Weak] +- Strengths: +- Issues to address: +- Recommended actions: + +**Ready for solutioning?** [Yes / No - explain] + +--- + +_Adapt based on game type and narrative complexity. Core gameplay must always be solid._ diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types.csv b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types.csv similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types.csv rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types.csv diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/action-platformer.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/action-platformer.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/action-platformer.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/action-platformer.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/adventure.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/adventure.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/adventure.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/adventure.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/card-game.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/card-game.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/card-game.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/card-game.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/fighting.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/fighting.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/fighting.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/fighting.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/horror.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/horror.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/horror.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/horror.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/idle-incremental.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/idle-incremental.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/idle-incremental.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/idle-incremental.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/metroidvania.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/metroidvania.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/metroidvania.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/metroidvania.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/moba.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/moba.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/moba.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/moba.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/party-game.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/party-game.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/party-game.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/party-game.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/puzzle.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/puzzle.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/puzzle.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/puzzle.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/racing.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/racing.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/racing.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/racing.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/rhythm.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/rhythm.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/rhythm.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/rhythm.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/roguelike.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/roguelike.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/roguelike.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/roguelike.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/rpg.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/rpg.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/rpg.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/rpg.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/sandbox.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/sandbox.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/sandbox.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/sandbox.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/shooter.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/shooter.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/shooter.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/shooter.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/simulation.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/simulation.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/simulation.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/simulation.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/sports.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/sports.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/sports.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/sports.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/strategy.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/strategy.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/strategy.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/strategy.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/survival.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/survival.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/survival.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/survival.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/text-based.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/text-based.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/text-based.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/text-based.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/tower-defense.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/tower-defense.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/tower-defense.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/tower-defense.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/turn-based-tactics.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/turn-based-tactics.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/turn-based-tactics.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/turn-based-tactics.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/game-types/visual-novel.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/visual-novel.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/game-types/visual-novel.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/game-types/visual-novel.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/gdd-template.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/gdd-template.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/gdd/gdd-template.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/gdd-template.md diff --git a/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md similarity index 56% rename from src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md rename to src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md index 17a496d5..23fd5d14 100644 --- a/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md @@ -4,17 +4,68 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This is the GDD instruction set for GAME projects - replaces PRD with Game Design Document Project analysis already completed - proceeding with game-specific design Uses gdd_template for GDD output, game_types.csv for type-specific sections Routes to 3-solutioning for architecture (platform-specific decisions handled there) If users mention technical details, append to technical_preferences with timestamp + + +Check if bmm-workflow-status.md exists in {output_folder}/ + + + **⚠️ No Workflow Status File Found** + +The GDD workflow requires an existing workflow status file to understand your project context. + +Please run `workflow-status` first to: + +- Map out your complete workflow journey +- Determine project type and level +- Create the status file with your planned workflow + +**To proceed:** + +Run: `bmad analyst workflow-status` + +After completing workflow planning, you'll be directed back to this workflow. + +Exit workflow - cannot proceed without status file + + + + Load status file and proceed to Step 1 + + + + Load bmm-workflow-status.md Confirm project_type == "game" + + This workflow is for game projects only. Software projects should use PRD or tech-spec workflows. + **Incorrect Workflow for Software Projects** + +Your status file indicates project_type: {{project_type}} + +**Correct workflows for software projects:** + +- Level 0-1: `tech-spec` (run with Architect agent) +- Level 2-4: `prd` (run with PM agent) + +{{#if project_level <= 1}} +Run: `bmad architect tech-spec` +{{else}} +Run: `bmad pm prd` +{{/if}} + +Exit and redirect user to appropriate software workflow + + Load existing GDD.md and check completion status Found existing work. Would you like to: @@ -73,74 +124,45 @@ Get core game concept and vision. -What platform(s) are you targeting? - -- Desktop (Windows/Mac/Linux) -- Mobile (iOS/Android) -- Web (Browser-based) -- Console (which consoles?) -- Multiple platforms - -Your answer: +Guide user to specify target platform(s) for their game, exploring considerations like desktop, mobile, web, console, or multi-platform deployment platforms -Who is your target audience? - -Consider: - -- Age range -- Gaming experience level (casual, core, hardcore) -- Genre familiarity -- Play session length preferences - -Your answer: +Guide user to define their target audience with specific demographics: age range, gaming experience level (casual/core/hardcore), genre familiarity, and preferred play session lengths target_audience - + -**Goal Guidelines based on project level:** - -- Level 0-1: 1-2 primary goals -- Level 2: 2-3 primary goals -- Level 3-4: 3-5 strategic goals +Guide user to define project goals appropriate for their level (Level 0-1: 1-2 goals, Level 2: 2-3 goals, Level 3-4: 3-5 strategic goals) - what success looks like for this game goals -Brief context on why this game matters now. +Guide user to provide context on why this game matters now - the motivation and rationale behind the project context +Guide user to identify the unique selling points (USPs) - what makes this game different from existing games in the market + +unique_selling_points + These are game-defining decisions -What are the core game pillars (2-4 fundamental gameplay elements)? - -Examples: - -- Tight controls + challenging combat + rewarding exploration -- Strategic depth + replayability + quick sessions -- Narrative + atmosphere + player agency - -Your game pillars: +Guide user to identify 2-4 core game pillars - the fundamental gameplay elements that define their game's experience (e.g., tight controls + challenging combat + rewarding exploration, or strategic depth + replayability + quick sessions) game_pillars -Describe the core gameplay loop (what the player does repeatedly): - -Example: "Player explores level → encounters enemies → defeats enemies with abilities → collects resources → upgrades abilities → explores deeper" - -Your gameplay loop: +Guide user to describe the core gameplay loop - what actions the player repeats throughout the game, creating a clear cyclical pattern of player behavior and rewards gameplay_loop -How does the player win? How do they lose? +Guide user to define win and loss conditions - how the player succeeds and fails in the game win_loss_conditions @@ -148,19 +170,12 @@ Your gameplay loop: -Define the primary game mechanics. +Guide user to define the primary game mechanics that players will interact with throughout the game primary_mechanics {project-root}/bmad/core/tasks/adv-elicit.xml -Describe the control scheme and input method: - -- Keyboard + Mouse -- Gamepad -- Touch screen -- Other - -Include key bindings or button layouts if known. +Guide user to describe their control scheme and input method (keyboard/mouse, gamepad, touchscreen, etc.), including key bindings or button layouts if known controls @@ -182,29 +197,15 @@ For each {{placeholder}} in the fragment, elicit and capture that information. -How does player progression work? - -- Skill-based (player gets better) -- Power-based (character gets stronger) -- Unlock-based (new abilities/areas) -- Narrative-based (story progression) -- Combination - -Describe: +Guide user to describe how player progression works in their game - whether through skill improvement, power gains, ability unlocking, narrative advancement, or a combination of approaches player_progression -Describe the difficulty curve: - -- How does difficulty increase? -- Pacing (steady, spikes, player-controlled?) -- Accessibility options? +Guide user to define the difficulty curve: how challenge increases over time, pacing rhythm (steady/spikes/player-controlled), and any accessibility options planned difficulty_curve -Is there an in-game economy or resource system? - -Skip if not applicable. +Ask if the game includes an in-game economy or resource system, and if so, guide user to describe it (skip if not applicable) economy_resources @@ -212,26 +213,11 @@ Skip if not applicable. -What types of levels/stages does your game have? - -Examples: - -- Tutorial, early levels, mid-game, late-game, boss arenas -- Biomes/themes -- Procedural vs. handcrafted - -Describe: +Guide user to describe the types of levels/stages in their game (e.g., tutorial, themed biomes, boss arenas, procedural vs. handcrafted, etc.) level_types -How do levels progress or unlock? - -- Linear sequence -- Hub-based -- Open world -- Player choice - -Describe: +Guide user to explain how levels progress or unlock - whether through linear sequence, hub-based structure, open world exploration, or player-driven choices level_progression @@ -239,23 +225,11 @@ Describe: -Describe the art style: - -- Visual aesthetic (pixel art, low-poly, realistic, stylized, etc.) -- Color palette -- Inspirations or references - -Your vision: +Guide user to describe their art style vision: visual aesthetic (pixel art, low-poly, realistic, stylized), color palette preferences, and any inspirations or references art_style -Describe audio and music direction: - -- Music style/genre -- Sound effect tone -- Audio importance to gameplay - -Your vision: +Guide user to describe their audio and music direction: music style/genre, sound effect tone, and how important audio is to the gameplay experience audio_music @@ -263,38 +237,15 @@ Your vision: -What are the performance requirements? - -Consider: - -- Target frame rate -- Resolution -- Load times -- Battery life (mobile) - -Requirements: +Guide user to define performance requirements: target frame rate, resolution, acceptable load times, and mobile battery considerations if applicable performance_requirements -Any platform-specific considerations? - -- Mobile: Touch controls, screen sizes -- PC: Keyboard/mouse, settings -- Console: Controller, certification -- Web: Browser compatibility, file size - -Platform details: +Guide user to identify platform-specific considerations (mobile touch controls/screen sizes, PC keyboard/mouse/settings, console controller/certification, web browser compatibility/file size) platform_details -What are the key asset requirements? - -- Art assets (sprites, models, animations) -- Audio assets (music, SFX, voice) -- Estimated asset counts/sizes -- Asset pipeline needs - -Asset requirements: +Guide user to document key asset requirements: art assets (sprites/models/animations), audio assets (music/SFX/voice), estimated counts/sizes, and asset pipeline needs asset_requirements @@ -302,14 +253,7 @@ Asset requirements: -Translate game features into development epics - -**Epic Guidelines based on project level:** - -- Level 1: 1 epic with 1-10 stories -- Level 2: 1-2 epics with 5-15 stories total -- Level 3: 2-5 epics with 12-40 stories -- Level 4: 5+ epics with 40+ stories +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/core/tasks/adv-elicit.xml @@ -322,19 +266,16 @@ Asset requirements: Create separate epics.md with full story hierarchy +Generate epic overview section with all epics listed + epic_overview +For each epic, generate detailed breakdown with expanded goals, capabilities, and success criteria + +For each epic, generate all stories in user story format with prerequisites, acceptance criteria (3-8 per story), and high-level technical notes + -Generate Epic {{epic_number}} with expanded goals, capabilities, success criteria. - -Generate all stories with: - -- User story format -- Prerequisites -- Acceptance criteria (3-8 per story) -- Technical notes (high-level only) - epic\_{{epic_number}}\_details {project-root}/bmad/core/tasks/adv-elicit.xml @@ -343,29 +284,11 @@ Generate all stories with: -What technical metrics will you track? - -Examples: - -- Frame rate consistency -- Load times -- Crash rate -- Memory usage - -Your metrics: +Guide user to identify technical metrics they'll track (e.g., frame rate consistency, load times, crash rate, memory usage) technical_metrics -What gameplay metrics will you track? - -Examples: - -- Player completion rate -- Average session length -- Difficulty pain points -- Feature engagement - -Your metrics: +Guide user to identify gameplay metrics they'll track (e.g., player completion rate, session length, difficulty pain points, feature engagement) gameplay_metrics @@ -373,15 +296,19 @@ Your metrics: +Guide user to document what is explicitly out of scope for this game - features, platforms, or content that won't be included in this version + out_of_scope +Guide user to document key assumptions and dependencies - technical assumptions, team capabilities, third-party dependencies, or external factors the project relies on + assumptions_and_dependencies -Check if game-type fragment contained narrative tags +Check if game-type fragment contained narrative tags indicating narrative importance Set needs_narrative = true @@ -392,15 +319,9 @@ Your metrics: - This game type ({{game_type}}) is **{{narrative_importance}}** for narrative. + Inform user that their game type benefits from narrative design, presenting the option to create a Narrative Design Document covering story structure, character arcs, world lore, dialogue framework, and environmental storytelling -Your game would benefit from a Narrative Design Document to detail: - -- Story structure and beats -- Character profiles and arcs -- World lore and history -- Dialogue framework -- Environmental storytelling +This game type ({{game_type}}) benefits from narrative design. Would you like to create a Narrative Design Document now? @@ -413,7 +334,7 @@ Your choice: - {project-root}/bmad/bmm/workflows/2-plan/narrative/workflow.yaml + {project-root}/bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml Pass GDD context to narrative workflow Exit current workflow (narrative will hand off to solutioning when done) @@ -478,7 +399,9 @@ Since this is a Level {{project_level}} game project, you need solutioning for p - Milestone planning - Demo/playable builds -GDD Complete! Next immediate action: +**✅ GDD Complete, {user_name}!** + +Next immediate action: @@ -505,7 +428,7 @@ Which would you like to proceed with? - {project-root}/bmad/bmm/workflows/2-plan/narrative/workflow.yaml + {project-root}/bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml Pass GDD context to narrative workflow diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml new file mode 100644 index 00000000..421102f2 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml @@ -0,0 +1,63 @@ +# Game Design Document (GDD) Workflow +name: gdd +description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmm/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Workflow components +installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/gdd" +instructions: "{installed_path}/instructions-gdd.md" +template: "{installed_path}/gdd-template.md" +game_types_csv: "{installed_path}/game-types.csv" + +# Output configuration +default_output_file: "{output_folder}/GDD.md" + +# Game type references (loaded based on game type selection) +game_type_guides: "{installed_path}/game-types/" + +# Recommended input documents +recommended_inputs: + - game_brief: "{output_folder}/game-brief.md" + - narrative_design: "{output_folder}/narrative-design.md" + - market_research: "{output_folder}/market-research.md" + +web_bundle: + name: "gdd" + description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance." + author: "BMad" + instructions: "bmad/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md" + web_bundle_files: + - "bmad/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/gdd-template.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types.csv" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/action-platformer.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/adventure.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/card-game.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/fighting.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/horror.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/idle-incremental.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/metroidvania.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/moba.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/party-game.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/puzzle.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/racing.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/rhythm.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/roguelike.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/rpg.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/sandbox.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/shooter.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/simulation.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/sports.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/strategy.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/survival.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/text-based.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/tower-defense.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/turn-based-tactics.md" + - "bmad/bmm/workflows/2-plan-workflows/gdd/game-types/visual-novel.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/narrative/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/narrative/checklist.md new file mode 100644 index 00000000..7483d0ac --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/narrative/checklist.md @@ -0,0 +1,139 @@ +# Narrative Design Workflow Validation Checklist + +**Purpose**: Validate narrative design outputs are complete, cohesive, and ready for implementation. + +**Scope**: Story-driven games and applications (follows GDD workflow) + +**Expected Output**: narrative-design.md + +--- + +## 1. Output File Exists + +- [ ] narrative-design.md created in output folder +- [ ] GDD.md exists (narrative workflow requires GDD first) +- [ ] No unfilled {{template_variables}} + +--- + +## 2. Story Foundation + +### Core Elements + +- [ ] **Narrative premise** clearly stated (elevator pitch, 2-3 sentences) +- [ ] **Core themes** identified (2-4 meaningful themes) +- [ ] **Tone and atmosphere** established +- [ ] Premise is compelling and fits game type + +### Story Structure + +- [ ] **Story structure chosen** (3-act, hero's journey, branching, etc.) +- [ ] **Acts/sections broken down** with clear progression +- [ ] **Major story beats** documented (key moments that drive narrative) +- [ ] Structure fits narrative complexity level + +--- + +## 3. Characters + +### Protagonist(s) + +- [ ] Background and motivation explained +- [ ] Character arc defined (how they change) +- [ ] Internal and external conflicts identified + +### Antagonist(s) + +- [ ] Motivation clear (why they oppose protagonist) +- [ ] Goals and methods explained +- [ ] Not one-dimensional + +### Supporting Cast + +- [ ] Major supporting characters documented +- [ ] Each has distinct role in story +- [ ] Character relationships mapped + +### Character Arcs + +- [ ] Major characters have starting → transformation → ending states +- [ ] Arc progression makes sense + +--- + +## 4. World and Lore + +- [ ] **World setting** defined (time, place, world type) +- [ ] **World rules** explained (magic, technology, society) +- [ ] **History and backstory** documented +- [ ] Key locations described with narrative significance + +--- + +## 5. Dialogue and Delivery + +### Dialogue Framework + +- [ ] Dialogue style established +- [ ] Key conversations identified +- [ ] Branching dialogue system described (if applicable) + +### Narrative Delivery + +- [ ] Cutscenes/cinematics approach defined +- [ ] In-game storytelling methods explained +- [ ] Optional vs. required content distinguished +- [ ] Multiple endings documented (if applicable) + +--- + +## 6. Gameplay Integration + +- [ ] **Narrative-gameplay harmony** addressed (how story and mechanics connect) +- [ ] **Story gates** explained (how narrative controls progression) +- [ ] **Player agency** level defined (can player affect story?) +- [ ] Integration doesn't fight game design + +--- + +## 7. Production Scope + +- [ ] **Writing scope** estimated (word count, scene count, dialogue lines) +- [ ] Scope realistic for project level +- [ ] Localization considerations noted (if applicable) +- [ ] Voice acting plans documented (if applicable) + +--- + +## 8. Consistency with GDD + +- [ ] Narrative aligns with GDD game design +- [ ] Tone matches GDD art/audio direction +- [ ] Story supports game mechanics (doesn't contradict) +- [ ] No conflicts between narrative and gameplay + +--- + +## 9. Critical Failures (Auto-Fail) + +- [ ] ❌ **No GDD** (narrative workflow requires GDD first) +- [ ] ❌ **No character arcs** (protagonist has no development) +- [ ] ❌ **No story beats** (major moments not identified) +- [ ] ❌ **Contradicts GDD** (narrative fights game design) + +--- + +## Validation Notes + +**Document any findings:** + +- Narrative strength: [Compelling / Interesting / Adequate / Weak] +- Strengths: +- Issues to address: +- Recommended actions: + +**Ready for solutioning?** [Yes / No - explain] + +--- + +_Adapt based on narrative complexity level (Critical/Heavy/Moderate/Light)._ diff --git a/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md b/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md similarity index 98% rename from src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md rename to src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md index ed3623ee..8405a45e 100644 --- a/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md +++ b/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md @@ -4,6 +4,7 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already completed the GDD workflow +Communicate all responses in {communication_language} This workflow creates detailed narrative content for story-driven games Uses narrative_template for output If users mention gameplay mechanics, note them but keep focus on narrative @@ -27,7 +28,7 @@ Your game type ({{game_type}}) suggests **{{suggested_complexity}}**. Confirm or Set narrative_complexity - + Light narrative games usually don't need a full Narrative Design Document. Are you sure you want to continue? - GDD story sections may be sufficient @@ -508,7 +509,9 @@ Your references: references -Narrative Design complete! Next steps: +**✅ Narrative Design Complete, {user_name}!** + +Next steps: 1. Proceed to solutioning (technical architecture) 2. Create detailed script/screenplay (outside workflow) diff --git a/src/modules/bmm/workflows/2-plan/narrative/narrative-template.md b/src/modules/bmm/workflows/2-plan-workflows/narrative/narrative-template.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/narrative/narrative-template.md rename to src/modules/bmm/workflows/2-plan-workflows/narrative/narrative-template.md diff --git a/src/modules/bmm/workflows/2-plan-workflows/narrative/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/narrative/workflow.yaml new file mode 100644 index 00000000..11e92bb6 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/narrative/workflow.yaml @@ -0,0 +1,34 @@ +# Narrative Design Workflow +name: narrative +description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmm/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Workflow components +installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative" +instructions: "{installed_path}/instructions-narrative.md" +template: "{installed_path}/narrative-template.md" + +# Output configuration +default_output_file: "{output_folder}/narrative-design.md" + +# Recommended input documents +recommended_inputs: + - game_brief: "{output_folder}/game-brief.md" + - gdd: "{output_folder}/GDD.md" + - product_brief: "{output_folder}/product-brief.md" + +web_bundle: + name: "narrative" + description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance." + author: "BMad" + instructions: "bmad/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md" + web_bundle_files: + - "bmad/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md" + - "bmad/bmm/workflows/2-plan-workflows/narrative/narrative-template.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md new file mode 100644 index 00000000..488f9950 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md @@ -0,0 +1,117 @@ +# PRD Workflow Validation Checklist + +**Purpose**: Validate PRD workflow outputs are complete, consistent, and ready for next phase. + +**Scope**: Levels 2-4 software projects + +**Expected Outputs**: PRD.md, epics.md, updated bmm-workflow-status.md + +--- + +## 1. Output Files Exist + +- [ ] PRD.md created in output folder +- [ ] epics.md created in output folder (separate file) +- [ ] bmm-workflow-status.md updated +- [ ] No unfilled {{template_variables}} + +--- + +## 2. PRD.md Core Quality + +### Requirements Coverage + +- [ ] Functional requirements describe WHAT capabilities (not HOW to implement) +- [ ] Each FR has unique identifier (FR001, FR002, etc.) +- [ ] Non-functional requirements (if any) have business justification +- [ ] Requirements are testable and verifiable + +### User Journeys + +- [ ] User journeys reference specific FR numbers +- [ ] Journeys show complete user paths through system +- [ ] Success outcomes are clear + +### Strategic Focus + +- [ ] PRD focuses on WHAT and WHY (not technical HOW) +- [ ] No specific technology choices in PRD (those belong in technical-decisions.md) +- [ ] Goals are outcome-focused, not implementation-focused + +--- + +## 3. epics.md Story Quality + +### Story Format + +- [ ] All stories follow user story format: "As a [role], I want [capability], so that [benefit]" +- [ ] Each story has numbered acceptance criteria +- [ ] Prerequisites/dependencies explicitly stated + +### Story Sequencing (CRITICAL) + +- [ ] **Epic 1 establishes foundation** (infrastructure, initial deployable functionality) + - Exception noted if adding to existing app +- [ ] **Vertical slices**: Each story delivers complete, testable functionality (not horizontal layers) +- [ ] **No forward dependencies**: No story depends on work from a LATER story or epic +- [ ] Stories are sequentially ordered within each epic +- [ ] Each story leaves system in working state + +### Coverage + +- [ ] All FRs from PRD.md are covered by stories in epics.md +- [ ] Epic list in PRD.md matches epics in epics.md (titles and count) + +--- + +## 4. Cross-Document Consistency + +- [ ] Epic titles consistent between PRD.md and epics.md +- [ ] FR references in user journeys exist in requirements section +- [ ] Terminology consistent across documents +- [ ] No contradictions between PRD and epics + +--- + +## 5. Readiness for Next Phase + +**Adapt based on project level from bmm-workflow-status.md:** + +### If Level 2: + +- [ ] PRD provides sufficient context for tech-spec workflow (lightweight solutioning) +- [ ] Epic structure supports 5-15 story implementation scope + +### If Level 3-4: + +- [ ] PRD provides sufficient context for solution-architecture workflow +- [ ] Epic structure supports phased delivery approach +- [ ] Clear value delivery path through epic sequence + +--- + +## 6. Critical Failures (Auto-Fail) + +- [ ] ❌ **No epics.md file** (two-file output is required) +- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core principle) +- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation) +- [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery) +- [ ] ❌ **Technical decisions in PRD** (should be in technical-decisions.md) +- [ ] ❌ **Epics don't cover all FRs** (orphaned requirements) +- [ ] ❌ **User journeys don't reference FR numbers** (missing traceability) + +--- + +## Validation Notes + +**Document any findings:** + +- Strengths: +- Issues to address: +- Recommended actions: + +**Ready for next phase?** [Yes / No - explain] + +--- + +_Adapt this checklist based on actual outputs. Not all sections may apply to every project._ diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md b/src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md new file mode 100644 index 00000000..09faecd1 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md @@ -0,0 +1,63 @@ +# {{project_name}} - Epic Breakdown + +**Author:** {{user_name}} +**Date:** {{date}} +**Project Level:** {{project_level}} +**Target Scale:** {{target_scale}} + +--- + +## Overview + +This document provides the detailed epic breakdown for {{project_name}}, expanding on the high-level epic list in the [PRD](./PRD.md). + +Each epic includes: + +- Expanded goal and value proposition +- Complete story breakdown with user stories +- Acceptance criteria for each story +- Story sequencing and dependencies + +**Epic Sequencing Principles:** + +- Epic 1 establishes foundational infrastructure and initial functionality +- Subsequent epics build progressively, each delivering significant end-to-end value +- Stories within epics are vertically sliced and sequentially ordered +- No forward dependencies - each story builds only on previous work + +--- + +{{epic_details}} + +--- + +## Story Guidelines Reference + +**Story Format:** + +``` +**Story [EPIC.N]: [Story Title]** + +As a [user type], +I want [goal/desire], +So that [benefit/value]. + +**Acceptance Criteria:** +1. [Specific testable criterion] +2. [Another specific criterion] +3. [etc.] + +**Prerequisites:** [Dependencies on previous stories, if any] +``` + +**Story Requirements:** + +- **Vertical slices** - Complete, testable functionality delivery +- **Sequential ordering** - Logical progression within epic +- **No forward dependencies** - Only depend on previous work +- **AI-agent sized** - Completable in 2-4 hour focused session +- **Value-focused** - Integrate technical enablers into value-delivering stories + +--- + +**For implementation:** Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown. diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md new file mode 100644 index 00000000..0d122362 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md @@ -0,0 +1,431 @@ +# PRD Workflow Instructions + +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} +This workflow is for Level 2-4 projects. Level 0-1 use tech-spec workflow. +Produces TWO outputs: PRD.md (strategic) and epics.md (tactical implementation) +TECHNICAL NOTES: If ANY technical details, preferences, or constraints are mentioned during PRD discussions, append them to {technical_decisions_file}. If file doesn't exist, create it from {technical_decisions_template} + + + + + +Check if bmm-workflow-status.md exists in {output_folder}/ + + + **⚠️ No Workflow Status File Found** + +The PRD workflow requires an existing workflow status file to understand your project context. + +Please run `workflow-status` first to: + +- Map out your complete workflow journey +- Determine project type and level +- Create the status file with your planned workflow + +**To proceed:** + +Run: `bmad analyst workflow-status` + +After completing workflow planning, you'll be directed back to this workflow. + +Exit workflow - cannot proceed without status file + + + + Load status file: {status_file} + Proceed to Step 1 + + + + + + +Extract project context from status file +Verify project_level is 2, 3, or 4 + + + This workflow is for Level 2-4 only. Level 0-1 should use tech-spec workflow. + **Incorrect Workflow for Your Level** + +Your status file indicates Level {{project_level}}. + +**Correct workflow:** `tech-spec` (run with Architect agent) + +Run: `bmad architect tech-spec` + +Exit and redirect user to tech-spec workflow + + + + This workflow is for software projects. Game projects should use GDD workflow. + **Incorrect Workflow for Game Projects** + +**Correct workflow:** `gdd` (run with PM agent) + +Run: `bmad pm gdd` + +Exit and redirect user to gdd workflow + + +Check for existing PRD.md in {output_folder} + + + Found existing PRD.md. Would you like to: +1. Continue where you left off +2. Modify existing sections +3. Start fresh (will archive existing file) + + Load existing PRD and skip to first incomplete section + Load PRD and ask which section to modify + Archive existing PRD and start fresh + + +Load PRD template: {prd_template} +Load epics template: {epics_template} + +Do you have a Product Brief? (Strongly recommended for Level 3-4, helpful for Level 2) + + + Load and review product brief: {output_folder}/product-brief.md + Extract key elements: problem statement, target users, success metrics, MVP scope, constraints + + + + Product Brief is strongly recommended for Level 3-4 projects. Consider running the product-brief workflow first. + Continue without Product Brief? (y/n) + Exit to allow Product Brief creation + + + + + + +**Goals** - What success looks like for this project + + + Review goals from product brief and refine for PRD context + + + + Gather goals through discussion with user, use probing questions and converse until you are ready to propose that you have enough information to proceed + + +Create a bullet list of single-line desired outcomes that capture user and project goals. + +**Scale guidance:** + +- Level 2: 2-3 core goals +- Level 3: 3-5 strategic goals +- Level 4: 5-7 comprehensive goals + +goals + +**Background Context** - Why this matters now + + + Summarize key context from brief without redundancy + + + + Gather context through discussion + + +Write 1-2 paragraphs covering: + +- What problem this solves and why +- Current landscape or need +- Key insights from discovery/brief (if available) + +background_context + + + + + +**Functional Requirements** - What the system must do + +Draft functional requirements as numbered items with FR prefix. + +**Scale guidance:** + +- Level 2: 8-15 FRs (focused MVP set) +- Level 3: 12-25 FRs (comprehensive product) +- Level 4: 20-35 FRs (enterprise platform) + +**Format:** + +- FR001: [Clear capability statement] +- FR002: [Another capability] + +**Focus on:** + +- User-facing capabilities +- Core system behaviors +- Integration requirements +- Data management needs + +Group related requirements logically. + +{project-root}/bmad/core/tasks/adv-elicit.xml + +functional_requirements + +**Non-Functional Requirements** - How the system must perform + +Draft non-functional requirements with NFR prefix. + +**Scale guidance:** + +- Level 2: 1-3 NFRs (critical MVP only) +- Level 3: 2-5 NFRs (production quality) +- Level 4: 3-7+ NFRs (enterprise grade) + +non_functional_requirements + + + + + +**Journey Guidelines (scale-adaptive):** + +- **Level 2:** 1 simple journey (primary use case happy path) +- **Level 3:** 2-3 detailed journeys (complete flows with decision points) +- **Level 4:** 3-5 comprehensive journeys (all personas and edge cases) + + + Would you like to document a user journey for the primary use case? (recommended but optional) + + Create 1 simple journey showing the happy path. + + + + + Map complete user flows with decision points, alternatives, and edge cases. + + +user_journeys + + + {project-root}/bmad/core/tasks/adv-elicit.xml + + + + + + +**Purpose:** Capture essential UX/UI information needed for epic and story planning. A dedicated UX workflow will provide deeper design detail later. + + + For backend-heavy or minimal UI projects, keep this section very brief or skip + + +**Gather high-level UX/UI information:** + +1. **UX Principles** (2-4 key principles that guide design decisions) + - What core experience qualities matter most? + - Any critical accessibility or usability requirements? + +2. **Platform & Screens** + - Target platforms (web, mobile, desktop) + - Core screens/views users will interact with + - Key interaction patterns or navigation approach + +3. **Design Constraints** + - Existing design systems or brand guidelines + - Technical UI constraints (browser support, etc.) + +Keep responses high-level. Detailed UX planning happens in the UX workflow after PRD completion. + +{project-root}/bmad/core/tasks/adv-elicit.xml + +ux_principles +ui_design_goals + + + + + +**Epic Structure** - Major delivery milestones + +Create high-level epic list showing logical delivery sequence. + +**Epic Sequencing Rules:** + +1. **Epic 1 MUST establish foundation** + - Project infrastructure (repo, CI/CD, core setup) + - Initial deployable functionality + - Development workflow established + - Exception: If adding to existing app, Epic 1 can be first major feature + +2. **Subsequent Epics:** + - Each delivers significant, end-to-end, fully deployable increment + - Build upon previous epics (no forward dependencies) + - Represent major functional blocks + - Prefer fewer, larger epics over fragmentation + +**Scale guidance:** + +- Level 2: 1-2 epics, 5-15 stories total +- Level 3: 2-5 epics, 15-40 stories total +- Level 4: 5-10 epics, 40-100+ stories total + +**For each epic provide:** + +- Epic number and title +- Single-sentence goal statement +- Estimated story count + +**Example:** + +- **Epic 1: Project Foundation & User Authentication** +- **Epic 2: Core Task Management** + +Review the epic list. Does the sequence make sense? Any epics to add, remove, or resequence? +Refine epic list based on feedback +{project-root}/bmad/core/tasks/adv-elicit.xml + +epic_list + + + + + +**Out of Scope** - What we're NOT doing (now) + +Document what is explicitly excluded from this project: + +- Features/capabilities deferred to future phases +- Adjacent problems not being solved +- Integrations or platforms not supported +- Scope boundaries that need clarification + +This helps prevent scope creep and sets clear expectations. + +out_of_scope + + + + + +Review all PRD sections for completeness and consistency +Ensure all placeholders are filled +Save final PRD.md to {default_output_file} + +**PRD.md is complete!** Strategic document ready. + +Now we'll create the tactical implementation guide in epics.md. + + + + + +Now we create epics.md - the tactical implementation roadmap +This is a SEPARATE FILE from PRD.md + +Load epics template: {epics_template} +Initialize epics.md with project metadata + +For each epic from the epic list, expand with full story details: + +**Epic Expansion Process:** + +1. **Expanded Goal** (2-3 sentences) + - Describe the epic's objective and value delivery + - Explain how it builds on previous work + +2. **Story Breakdown** + + **Critical Story Requirements:** + - **Vertical slices** - Each story delivers complete, testable functionality + - **Sequential** - Stories must be logically ordered within epic + - **No forward dependencies** - No story depends on work from a later story/epic + - **AI-agent sized** - Completable in single focused session (2-4 hours) + - **Value-focused** - Minimize pure enabler stories; integrate technical work into value delivery + + **Story Format:** + + ``` + **Story [EPIC.N]: [Story Title]** + + As a [user type], + I want [goal/desire], + So that [benefit/value]. + + **Acceptance Criteria:** + 1. [Specific testable criterion] + 2. [Another specific criterion] + 3. [etc.] + + **Prerequisites:** [Any dependencies on previous stories] + ``` + +3. **Story Sequencing Within Epic:** + - Start with foundational/setup work if needed + - Build progressively toward epic goal + - Each story should leave system in working state + - Final stories complete the epic's value delivery + +**Process each epic:** + + + +Ready to break down {{epic_title}}? (y/n) + +Discuss epic scope and story ideas with user +Draft story list ensuring vertical slices and proper sequencing +For each story, write user story format and acceptance criteria +Verify no forward dependencies exist + +{{epic_title}}\_details + +Review {{epic_title}} stories. Any adjustments needed? + +Refine stories based on feedback + + + +Save complete epics.md to {epics_output_file} + +**Epic Details complete!** Implementation roadmap ready. + + + + + +Update {status_file} with completion status + +prd_completion_update + +**✅ PRD Workflow Complete, {user_name}!** + +**Deliverables Created:** + +1. ✅ PRD.md - Strategic product requirements document +2. ✅ epics.md - Tactical implementation roadmap with story breakdown + +**Next Steps:** + + + - Review PRD and epics with stakeholders + - **Next:** Run tech-spec workflow for lightweight technical planning + - Then proceed to implementation (create-story workflow) + + + + - Review PRD and epics with stakeholders + - **Next:** Run solution-architecture workflow for full technical design + - Then proceed to implementation (create-story workflow) + + +Would you like to: + +1. Review/refine any section +2. Proceed to next phase (tech-spec for Level 2, solution-architecture for Level 3-4) +3. Exit and review documents + + + + + 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 new file mode 100644 index 00000000..3552f381 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md @@ -0,0 +1,62 @@ +# {{project_name}} Product Requirements Document (PRD) + +**Author:** {{user_name}} +**Date:** {{date}} +**Project Level:** {{project_level}} +**Target Scale:** {{target_scale}} + +--- + +## Goals and Background Context + +### Goals + +{{goals}} + +### Background Context + +{{background_context}} + +--- + +## Requirements + +### Functional Requirements + +{{functional_requirements}} + +### Non-Functional Requirements + +{{non_functional_requirements}} + +--- + +## User Journeys + +{{user_journeys}} + +--- + +## UX Design Principles + +{{ux_principles}} + +--- + +## User Interface Design Goals + +{{ui_design_goals}} + +--- + +## Epic List + +{{epic_list}} + +> **Note:** Detailed epic breakdown with full story specifications is available in [epics.md](./epics.md) + +--- + +## Out of Scope + +{{out_of_scope}} diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml new file mode 100644 index 00000000..1ff5d426 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml @@ -0,0 +1,44 @@ +# Product Requirements Document (PRD) Workflow +name: prd +description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to solution-architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmm/config.yaml" +project_name: "{config_source}:project_name" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Workflow components +installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd" +instructions: "{installed_path}/instructions.md" + +# Templates +prd_template: "{installed_path}/prd-template.md" +epics_template: "{installed_path}/epics-template.md" +status_template: "{project-root}/bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" + +# Output files +status_file: "{output_folder}/bmm-workflow-status.md" +default_output_file: "{output_folder}/PRD.md" +epics_output_file: "{output_folder}/epics.md" +technical_decisions_file: "{output_folder}/technical-decisions.md" +technical_decisions_template: "{project-root}/src/modules/bmm/_module-installer/assets/technical-decisions.md" + +# Recommended input documents +recommended_inputs: + - product_brief: "{output_folder}/product-brief.md" + - market_research: "{output_folder}/market-research.md" + +web_bundle: + name: "prd" + description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to solution-architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow." + author: "BMad" + instructions: "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md" + web_bundle_files: + - "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md" + - "bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md" + - "bmad/bmm/workflows/2-plan-workflows/prd/epics-template.md" + - "bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md new file mode 100644 index 00000000..cb93baaa --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/checklist.md @@ -0,0 +1,107 @@ +# Tech-Spec Workflow Validation Checklist + +**Purpose**: Validate tech-spec workflow outputs are definitive, complete, and implementation-ready. + +**Scope**: Levels 0-1 software projects + +**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1) + +--- + +## 1. Output Files Exist + +- [ ] tech-spec.md created in output folder +- [ ] Story file(s) created in dev_story_location + - Level 0: 1 story file (story-{slug}.md) + - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md) +- [ ] bmm-workflow-status.md updated to Phase 4 +- [ ] No unfilled {{template_variables}} + +--- + +## 2. Tech-Spec Definitiveness (CRITICAL) + +### No Ambiguity Allowed + +- [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include" +- [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions + - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2" + - ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston" +- [ ] **Definitive decisions**: Every technical choice is final, not a proposal + +### Implementation Clarity + +- [ ] Source tree shows EXACT file paths (not "somewhere in src/") +- [ ] Each file marked as create/modify/delete +- [ ] Technical approach describes SPECIFIC implementation +- [ ] Implementation stack has complete toolchain with versions + +--- + +## 3. Story Quality + +### Story Format + +- [ ] All stories use "As a [role], I want [capability], so that [benefit]" format +- [ ] Each story has numbered acceptance criteria +- [ ] Tasks reference AC numbers: (AC: #1), (AC: #2) +- [ ] Dev Notes section links back to tech-spec.md + +### Story Sequencing (If Level 1) + +- [ ] **Vertical slices**: Each story delivers complete, testable functionality +- [ ] **Sequential ordering**: Stories in logical progression +- [ ] **No forward dependencies**: No story depends on later work +- [ ] Each story leaves system in working state + +### Coverage + +- [ ] Story acceptance criteria derived from tech-spec testing section +- [ ] Story tasks map to tech-spec implementation guide +- [ ] Files in stories match tech-spec source tree + +--- + +## 4. Workflow Status Integration + +- [ ] bmm-workflow-status.md shows current_phase = "4-Implementation" +- [ ] Phase 2 ("2-Plan") marked complete +- [ ] First story in TODO section, others in BACKLOG (if Level 1) +- [ ] Next action clear (review story, run story-ready) + +--- + +## 5. Readiness for Implementation + +- [ ] Developer can start coding from tech-spec alone +- [ ] All technical questions answered definitively +- [ ] Testing approach clear and verifiable +- [ ] Deployment strategy documented + +--- + +## 6. Critical Failures (Auto-Fail) + +- [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices) +- [ ] ❌ **Missing versions** (framework/library without specific version) +- [ ] ❌ **Stories don't match template** (incompatible with story-context/dev-story workflows) +- [ ] ❌ **Missing tech-spec sections** (required section missing from tech-spec.md) +- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation) +- [ ] ❌ **Vague source tree** (file changes not specific) + +--- + +## Validation Notes + +**Document any findings:** + +- Definitiveness score: [All definitive / Some ambiguity / Significant ambiguity] +- Strengths: +- Issues to address: +- Recommended actions: + +**Ready for implementation?** [Yes / No - explain] + +--- + +_Adapt based on Level 0 vs Level 1. Focus on definitiveness above all else._ diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md new file mode 100644 index 00000000..1c11e888 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md @@ -0,0 +1,11 @@ +# {{project_name}} - Epic Breakdown + +## Epic Overview + +{{epic_overview}} + +--- + +## Epic Details + +{{epic_details}} diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-level0-story.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/tech-spec/instructions-level0-story.md rename to src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-level1-stories.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md similarity index 69% rename from src/modules/bmm/workflows/2-plan/tech-spec/instructions-level1-stories.md rename to src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md index 563abe6a..2ba1eaf8 100644 --- a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-level1-stories.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md @@ -58,14 +58,14 @@ - "Admin Dashboard" → "admin-dashboard" -Initialize epic-stories.md summary document using epic_stories_template +Initialize epics.md summary document using epics_template -epic_title -epic_slug -epic_goal -epic_scope -epic_success_criteria -epic_dependencies +epic_title +epic_slug +epic_goal +epic_scope +epic_success_criteria +epic_dependencies @@ -105,9 +105,6 @@ For each story (2-3 total), generate separate story file Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3 -Each story should represent a deliverable unit of work -Stories should have clear acceptance criteria from tech spec -Estimate story points based on time estimates in tech spec **Story Generation Guidelines:** @@ -140,58 +137,27 @@ - Dev Agent Record: Empty sections for context workflow to populate -For story 1: -Set story_path_1 = "{dev_story_location}/story-{epic_slug}-1.md" -Initialize from user_story_template + + Set story_path_{n} = "{dev_story_location}/story-{epic_slug}-{n}.md" + Create story file from user_story_template with the following content: -story_title -role -capability -benefit -acceptance_criteria -tasks_subtasks -technical_summary -files_to_modify -test_locations -story_points -time_estimate -architecture_references + + - story_title: User-focused deliverable title + - role: User role (e.g., developer, user, admin) + - capability: What they want to do + - benefit: Why it matters + - acceptance_criteria: Specific, measurable criteria from tech spec + - tasks_subtasks: Implementation tasks with AC references + - technical_summary: High-level approach, key decisions + - files_to_modify: List of files that will change + - test_locations: Where tests will be added + - story_points: Estimated effort (1/2/3/5) + - time_estimate: Days/hours estimate + - architecture_references: Links to tech-spec.md sections + + -For story 2: -Set story_path_2 = "{dev_story_location}/story-{epic_slug}-2.md" -Initialize from user_story_template - -story_title -role -capability -benefit -acceptance_criteria -tasks_subtasks -technical_summary -files_to_modify -test_locations -story_points -time_estimate -architecture_references - - - For story 3: - Set story_path_3 = "{dev_story_location}/story-{epic_slug}-3.md" - Initialize from user_story_template - -story_title -role -capability -benefit -acceptance_criteria -tasks_subtasks -technical_summary -files_to_modify -test_locations -story_points -time_estimate -architecture_references - +Generate exactly {story_count} story files (2 or 3 based on Step 3 decision) @@ -220,11 +186,11 @@ Epic: Icon Reliability 2. **Story 2** → Test and deploy (depends on Story 1) -story_summaries -story_map -total_points -estimated_timeline -implementation_sequence +story_summaries +story_map +total_points +estimated_timeline +implementation_sequence @@ -290,7 +256,7 @@ Initialize empty table: ``` | tech-spec.md | Complete | {output_folder}/tech-spec.md | {{date}} | -| epic-stories.md | Complete | {output_folder}/epic-stories.md | {{date}} | +| epics.md | Complete | {output_folder}/epics.md | {{date}} | | story-{epic_slug}-1.md | Draft | {dev_story_location}/story-{epic_slug}-1.md | {{date}} | | story-{epic_slug}-2.md | Draft | {dev_story_location}/story-{epic_slug}-2.md | {{date}} | {{#if story_3}} @@ -335,7 +301,7 @@ Initialize empty table: **Generated Artifacts:** - `tech-spec.md` → Technical source of truth -- `epic-stories.md` → Epic and story summary +- `epics.md` → Epic and story summary - `story-{epic_slug}-1.md` → First story (ready for implementation) - `story-{epic_slug}-2.md` → Second story {{#if story_3}} diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md similarity index 75% rename from src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md rename to src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md index 963b4ae5..09ff1130 100644 --- a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md @@ -4,14 +4,70 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This is the SMALL instruction set for Level 0-1 projects - tech-spec with story generation Level 0: tech-spec + single user story | Level 1: tech-spec + epic/stories Project analysis already completed - proceeding directly to technical specification NO PRD generated - uses tech_spec_template + story templates + + +Check if bmm-workflow-status.md exists in {output_folder}/ + + + **⚠️ No Workflow Status File Found** + +The tech-spec workflow requires an existing workflow status file to understand your project context. + +Please run `workflow-status` first to: + +- Map out your complete workflow journey +- Determine project type and level +- Create the status file with your planned workflow + +**To proceed:** + +Run: `bmad analyst workflow-status` + +After completing workflow planning, you'll be directed back to this workflow. + +Exit workflow - cannot proceed without status file + + + + Load status file and proceed to Step 1 + + + + Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md +Verify project_level is 0 or 1 + + + This workflow is for Level 0-1 only. Level 2-4 should use PRD workflow. + **Incorrect Workflow for Your Level** + +Your status file indicates Level {{project_level}}. + +**Correct workflow:** `prd` (run with PM agent) + +Run: `bmad pm prd` + +Exit and redirect user to prd workflow + + + + This workflow is for software projects. Game projects should use GDD workflow. + **Incorrect Workflow for Game Projects** + +**Correct workflow:** `gdd` (run with PM agent) + +Run: `bmad pm gdd` + +Exit and redirect user to gdd workflow + Update Workflow Status Tracker: @@ -44,7 +100,7 @@ Set progress_percentage = 40% Save bmm-workflow-status.md -Initialize tech-spec.md using tech_spec_template from workflow.yaml +Initialize and write out tech-spec.md using tech_spec_template DEFINITIVE DECISIONS REQUIRED: @@ -118,7 +174,7 @@ Run cohesion validation? (y/n) Invoke instructions-level1-stories.md to generate epic and stories - Epic and stories will be saved to epic-stories.md + Epic and stories will be saved to epics.md Stories link to tech-spec.md implementation tasks @@ -133,7 +189,7 @@ Run cohesion validation? (y/n) - Confirm epic-stories.md generated successfully + Confirm epics.md generated successfully ## Summary @@ -145,7 +201,7 @@ Run cohesion validation? (y/n) -- **Level 1 Output**: tech-spec.md + epic-stories.md +- **Level 1 Output**: tech-spec.md + epics.md - **No PRD required** - **Ready for sprint planning with epic/story breakdown** @@ -178,7 +234,9 @@ Run cohesion validation? (y/n) - Command: `workflow task-generation` - Uses: tech-spec.md -Level 0 planning complete! Next action: +**✅ Tech-Spec Complete, {user_name}!** + +Next action: 1. Proceed to implementation 2. Generate development task diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/tech-spec-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md similarity index 73% rename from src/modules/bmm/workflows/2-plan/tech-spec/tech-spec-template.md rename to src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md index d918de73..372fad6c 100644 --- a/src/modules/bmm/workflows/2-plan/tech-spec/tech-spec-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md @@ -53,7 +53,3 @@ ## Deployment Strategy {{deployment_strategy}} - ---- - -_This tech spec is for Level 0-2 projects (BMad Method v6). It provides the technical details needed for implementation. Level 3+ projects use the separate architecture workflow for comprehensive technical design._ diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/user-story-template.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md similarity index 87% rename from src/modules/bmm/workflows/2-plan/tech-spec/user-story-template.md rename to src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md index 8f9f6e7c..c2e75358 100644 --- a/src/modules/bmm/workflows/2-plan/tech-spec/user-story-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md @@ -54,8 +54,3 @@ so that {{benefit}}. ### File List - ---- - -_Generated as part of Level 0 Tech Spec workflow (BMad Method v6)_ -_Story Format: Compatible with story-context and dev-story workflows_ 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 new file mode 100644 index 00000000..5e530581 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml @@ -0,0 +1,48 @@ +# Technical Specification Workflow (Level 0) +name: tech-spec-sm +description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmm/config.yaml" +project_name: "{config_source}:project_name" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Workflow components +installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec" +instructions: "{installed_path}/instructions.md" +template: "{installed_path}/tech-spec-template.md" + +# Story generation instructions (invoked based on level) +instructions_level0_story: "{installed_path}/instructions-level0-story.md" +instructions_level1_stories: "{installed_path}/instructions-level1-stories.md" + +# Templates +user_story_template: "{installed_path}/user-story-template.md" +epics_template: "{installed_path}/epics-template.md" + +# Output configuration +default_output_file: "{output_folder}/tech-spec.md" +user_story_file: "{output_folder}/user-story.md" +epics_file: "{output_folder}/epics.md" + +# Recommended input documents (optional for Level 0) +recommended_inputs: + - bug_report: "Bug description or issue ticket" + - feature_request: "Brief feature description" + +web_bundle: + name: "tech-spec-sm" + description: "Technical specification workflow for Level 0-1 projects. Creates focused tech spec with story generation. Level 0: tech-spec + user story. Level 1: tech-spec + epic/stories." + author: "BMad" + instructions: "bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md" + web_bundle_files: + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md" + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level0-story.md" + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md" + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/tech-spec-template.md" + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/user-story-template.md" + - "bmad/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/ux/checklist.md b/src/modules/bmm/workflows/2-plan-workflows/ux/checklist.md new file mode 100644 index 00000000..c52ce85e --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/ux/checklist.md @@ -0,0 +1,152 @@ +# UX/UI Specification Workflow Validation Checklist + +**Purpose**: Validate UX workflow outputs are complete, actionable, and ready for development. + +**Scope**: Can run standalone or integrated with PRD/GDD workflows + +**Expected Outputs**: ux-specification.md, optional ai-frontend-prompt.md + +--- + +## 1. Output File Exists + +- [ ] ux-specification.md created in output folder +- [ ] Requirements source identified (PRD, GDD, or gathered requirements) +- [ ] No unfilled {{template_variables}} + +--- + +## 2. UX Foundation + +### User Personas + +- [ ] **At least one primary persona** defined with goals and pain points +- [ ] Personas have sufficient detail to inform design decisions +- [ ] If PRD/GDD exists, personas align with target audience + +### Design Principles + +- [ ] **3-5 core design principles** established +- [ ] Principles are actionable (guide real design decisions) +- [ ] Principles fit project goals and users + +--- + +## 3. Information Architecture + +### Site/App Structure + +- [ ] **Complete site map** showing all major sections/screens +- [ ] Hierarchical relationships clear +- [ ] Navigation paths evident +- [ ] Structure makes sense for users + +### Navigation + +- [ ] Primary navigation defined +- [ ] Mobile navigation strategy clear (if multi-platform) +- [ ] Navigation approach logical + +--- + +## 4. User Flows + +- [ ] **At least 2-3 critical user flows** documented +- [ ] Flows show complete start-to-finish paths +- [ ] Decision points and error states considered +- [ ] Flows include Mermaid diagrams or clear descriptions +- [ ] If PRD exists, flows align with user journeys + +--- + +## 5. Component Library and Visual Design + +### Component Approach + +- [ ] **Design system strategy** defined (existing system, custom, or hybrid) +- [ ] If using existing, which one specified +- [ ] Core components identified +- [ ] Component states documented (default, hover, active, disabled, error) + +### Visual Foundation + +- [ ] **Color palette** defined with semantic meanings +- [ ] **Typography** specified (fonts, type scale, usage) +- [ ] **Spacing system** documented +- [ ] Design choices support usability + +--- + +## 6. Responsive and Accessibility + +### Responsive Design + +- [ ] **Breakpoints defined** for target devices +- [ ] Adaptation patterns explained (how layouts change) +- [ ] Mobile strategy clear (if multi-platform) + +### Accessibility + +- [ ] **Compliance target** specified (WCAG level) +- [ ] Key accessibility requirements documented +- [ ] Keyboard navigation, screen readers, contrast considered + +--- + +## 7. Implementation Readiness + +- [ ] **Next steps** clearly defined +- [ ] Design handoff requirements clear +- [ ] Developers can implement from this spec +- [ ] Sufficient detail for front-end development + +--- + +## 8. Integration with Requirements + +**If PRD/GDD exists:** + +- [ ] UX covers all user-facing features from requirements +- [ ] User flows align with documented user journeys +- [ ] Platform matches PRD/GDD platforms +- [ ] No contradictions with requirements + +--- + +## 9. AI Frontend Prompt (If Generated) + +**If ai-frontend-prompt.md was created:** + +- [ ] File exists in output folder +- [ ] Contains complete UX context (colors, typography, components, flows) +- [ ] Formatted for AI tools (v0, Lovable, etc.) +- [ ] Includes appropriate warnings about reviewing generated code + +--- + +## 10. Critical Failures (Auto-Fail) + +- [ ] ❌ **No user personas** (target users not defined) +- [ ] ❌ **No user flows** (critical paths not documented) +- [ ] ❌ **No information architecture** (site structure missing) +- [ ] ❌ **No component approach** (design system not defined) +- [ ] ❌ **No visual foundation** (colors/typography missing) +- [ ] ❌ **No responsive strategy** (adaptation not addressed for multi-platform) +- [ ] ❌ **Contradicts requirements** (UX fights PRD/GDD if they exist) + +--- + +## Validation Notes + +**Document any findings:** + +- UX quality: [Production-ready / Good foundation / Needs refinement / Incomplete] +- Strengths: +- Issues to address: +- Recommended actions: + +**Ready for development?** [Yes / Needs design phase / No - explain] + +--- + +_Adapt based on whether this is standalone or integrated, and platform requirements._ diff --git a/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md similarity index 97% rename from src/modules/bmm/workflows/2-plan/ux/instructions-ux.md rename to src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md index 6e1f228c..78340a16 100644 --- a/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md +++ b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md @@ -4,6 +4,7 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project Uses ux-spec-template.md for structured output generation Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai @@ -35,7 +36,7 @@ If no: We'll gather basic requirements to create the UX spec Load the following documents if available: - PRD.md (primary source for requirements and user journeys) -- epics.md or epic-stories.md (helps understand feature grouping) +- epics.md (helps understand feature grouping) - tech-spec.md (understand technical constraints) - solution-architecture.md (if Level 3-4 project) - bmm-workflow-status.md (understand project level and scope) @@ -301,7 +302,9 @@ This is recommended for: design_handoff_checklist -UX Specification saved to {{ux_spec_file}} +**✅ UX Specification Complete, {user_name}!** + +UX Specification saved to {{ux_spec_file}} **Additional Output Options:** diff --git a/src/modules/bmm/workflows/2-plan/ux/ux-spec-template.md b/src/modules/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md similarity index 100% rename from src/modules/bmm/workflows/2-plan/ux/ux-spec-template.md rename to src/modules/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md diff --git a/src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml new file mode 100644 index 00000000..4a18aa01 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml @@ -0,0 +1,35 @@ +# UX/UI Specification Workflow +name: ux-spec +description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines." +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/bmm/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Workflow components +installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux" +instructions: "{installed_path}/instructions-ux.md" +template: "{installed_path}/ux-spec-template.md" + +# Output configuration +default_output_file: "{output_folder}/ux-specification.md" +ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md" + +# Recommended input documents +recommended_inputs: + - prd: "{output_folder}/PRD.md" + - product_brief: "{output_folder}/product-brief.md" + - gdd: "{output_folder}/GDD.md" + +web_bundle: + name: "ux-spec" + description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines." + author: "BMad" + instructions: "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md" + web_bundle_files: + - "bmad/bmm/workflows/2-plan-workflows/ux/instructions-ux.md" + - "bmad/bmm/workflows/2-plan-workflows/ux/ux-spec-template.md" diff --git a/src/modules/bmm/workflows/2-plan/checklist.md b/src/modules/bmm/workflows/2-plan/checklist.md deleted file mode 100644 index dc1943a0..00000000 --- a/src/modules/bmm/workflows/2-plan/checklist.md +++ /dev/null @@ -1,369 +0,0 @@ -# Project Planning Validation Checklist (Adaptive: All Levels) - -**Scope**: This checklist adapts based on project level (0-4) and field type (greenfield/brownfield) - -- **Level 0**: Tech-spec only validation -- **Level 1-2**: PRD + Tech-spec + Epics validation -- **Level 3-4**: PRD + Epics validation (no tech-spec) -- **Greenfield**: Focus on setup sequencing and dependencies -- **Brownfield**: Focus on integration risks and backward compatibility - -## User Intent Validation (Critical First Check) - -### Input Sources and User Need - -- [ ] Product brief or initial context was properly gathered (not just project name) -- [ ] User's actual problem/need was identified through conversation (not assumed) -- [ ] Technical preferences mentioned by user were captured separately -- [ ] User confirmed the description accurately reflects their vision -- [ ] The PRD addresses what the user asked for, not what we think they need - -### Alignment with User Goals - -- [ ] Goals directly address the user's stated problem -- [ ] Context reflects actual user-provided information (not invented) -- [ ] Requirements map to explicit user needs discussed -- [ ] Nothing critical the user mentioned is missing - -## Document Structure - -- [ ] All required sections are present -- [ ] No placeholder text remains (all {{variables}} replaced) -- [ ] Proper formatting and organization throughout - -## Section 1: Description - -- [ ] Clear, concise description of what's being built -- [ ] Matches user's actual request (not extrapolated) -- [ ] Sets proper scope and expectations - -## Section 2: Goals (Step 2) - -- [ ] Level 3: Contains 3-5 primary goals -- [ ] Level 4: Contains 5-7 strategic goals -- [ ] Each goal is specific and measurable where possible -- [ ] Goals focus on user and project outcomes -- [ ] Goals represent what success looks like -- [ ] Strategic objectives align with product scale - -## Section 3: Context (Step 3) - -- [ ] 1-2 short paragraphs explaining why this matters now -- [ ] Context was gathered from user (not invented) -- [ ] Explains actual problem being solved -- [ ] Describes current situation or pain point -- [ ] Connects to real-world impact - -## Section 4: Functional Requirements (Step 4) - -- [ ] Level 3: Contains 12-20 FRs -- [ ] Level 4: Contains 20-30 FRs -- [ ] Each has unique FR identifier (FR001, FR002, etc.) -- [ ] Requirements describe capabilities, not implementation -- [ ] Related features grouped logically while maintaining granularity -- [ ] All FRs are testable user actions -- [ ] User provided feedback on proposed FRs -- [ ] Missing capabilities user expected were added -- [ ] Priority order reflects user input -- [ ] Coverage comprehensive for target product scale - -## Section 5: Non-Functional Requirements (Step 5 - Optional) - -- [ ] Only included if truly needed (not arbitrary targets) -- [ ] Each has unique NFR identifier -- [ ] Business justification provided for each NFR -- [ ] Compliance requirements noted if regulated industry -- [ ] Performance constraints tied to business needs -- [ ] Typically 0-5 for MVP (not invented) - -## Section 6: User Journeys (Step 6) - -- [ ] Level 3: 2-3 detailed user journeys documented -- [ ] Level 4: 3-5 comprehensive journeys for major segments -- [ ] Each journey has named persona with context -- [ ] Journey shows complete path through system via FRs -- [ ] Specific FR references included (e.g., "signs up (FR001)") -- [ ] Success criteria and pain points identified -- [ ] Edge cases and alternative paths considered -- [ ] Journeys validate comprehensive value delivery - -## Section 7: UX Principles (Step 7 - Optional) - -- [ ] Target users and sophistication level defined -- [ ] Design values stated (simple vs powerful, playful vs professional) -- [ ] Platform strategy specified (mobile-first, web, native) -- [ ] Accessibility requirements noted if applicable -- [ ] Sets direction without prescribing specific solutions - -## Section 8: Epics (Step 8) - -- [ ] Level 3: 3-5 epics defined (targeting 12-40 stories) -- [ ] Level 4: 5-8 epics defined (targeting 40+ stories) -- [ ] Each epic represents significant, deployable functionality -- [ ] Epic format includes: Title, Goal, Capabilities, Success Criteria, Dependencies -- [ ] Related FRs grouped into coherent capabilities -- [ ] Each epic references specific FR numbers -- [ ] Post-MVP epics listed separately with their FRs -- [ ] Dependencies between epics clearly noted -- [ ] Phased delivery strategy apparent - -## Section 9: Out of Scope (Step 9) - -- [ ] Ideas preserved with FR/NFR references -- [ ] Format: description followed by (FR###, NFR###) -- [ ] Prevents scope creep while capturing future possibilities -- [ ] Clear distinction from MVP scope - -## Section 10: Assumptions and Dependencies (Step 10) - -- [ ] Only ACTUAL assumptions from user discussion (not invented) -- [ ] Technical choices user explicitly mentioned captured -- [ ] Dependencies identified in FRs/NFRs listed -- [ ] User-stated constraints documented -- [ ] If none exist, states "No critical assumptions identified yet" - -## Cross-References and Consistency - -- [ ] All FRs trace back to at least one goal -- [ ] User journeys reference actual FR numbers -- [ ] Epic capabilities cover all FRs -- [ ] Terminology consistent throughout -- [ ] No contradictions between sections -- [ ] Technical details saved to technical_preferences (not in PRD) - -## Quality Checks - -- [ ] Requirements are strategic, not implementation-focused -- [ ] Document maintains appropriate abstraction level -- [ ] No premature technical decisions -- [ ] Focus on WHAT, not HOW - -## Readiness for Next Phase - -- [ ] Sufficient detail for comprehensive architecture design -- [ ] Clear enough for detailed solution design -- [ ] Ready for epic breakdown into 12-40+ stories -- [ ] Value delivery path supports phased releases -- [ ] If UI exists, ready for UX expert collaboration -- [ ] Scale and complexity match Level 3-4 requirements - -## Scale Validation - -- [ ] Project scope justifies PRD -- [ ] Complexity matches Level 1-4 designation -- [ ] Story estimate aligns with epic structure (12-40+) -- [ ] Not over-engineered for actual needs - -## Final Validation - -- [ ] Document addresses user's original request completely -- [ ] All user feedback incorporated -- [ ] No critical user requirements missing -- [ ] Ready for user final review and approval -- [ ] File saved in correct location: {{output_folder}}/PRD.md - ---- - -# Cohesion Validation (All Levels) - -**Purpose**: Validate alignment between planning artifacts and readiness for implementation - -## Project Context Detection - -- [ ] Project level confirmed (0, 1, 2, 3, or 4) -- [ ] Field type identified (greenfield or brownfield) -- [ ] Appropriate validation sections applied based on context - -## Section A: Tech Spec Validation (Levels 0, 1, 2 only) - -### A.1 Tech Spec Completeness - -- [ ] All technical decisions are DEFINITIVE (no "Option A or B") -- [ ] Specific versions specified for all frameworks/libraries -- [ ] Source tree structure clearly defined -- [ ] Technical approach precisely described -- [ ] Implementation stack complete with exact tools -- [ ] Testing approach clearly defined -- [ ] Deployment strategy documented - -### A.2 Tech Spec - PRD Alignment (Levels 1-2 only) - -- [ ] Every functional requirement has technical solution -- [ ] Non-functional requirements addressed in tech spec -- [ ] Tech stack aligns with PRD constraints -- [ ] Performance requirements achievable with chosen stack -- [ ] Technical preferences from user incorporated - -## Section B: Greenfield-Specific Validation (if greenfield) - -### B.1 Project Setup Sequencing - -- [ ] Epic 0 or 1 includes project initialization steps -- [ ] Repository setup precedes feature development -- [ ] Development environment configuration included early -- [ ] Core dependencies installed before use -- [ ] Testing infrastructure set up before tests written - -### B.2 Infrastructure Before Features - -- [ ] Database setup before data operations -- [ ] API framework before endpoint implementation -- [ ] Authentication setup before protected features -- [ ] CI/CD pipeline before deployment -- [ ] Monitoring setup included - -### B.3 External Dependencies - -- [ ] Third-party account creation assigned to user -- [ ] API keys acquisition process defined -- [ ] Credential storage approach specified -- [ ] External service setup sequenced properly -- [ ] Fallback strategies for external failures - -## Section C: Brownfield-Specific Validation (if brownfield) - -### C.1 Existing System Integration - -- [ ] Current architecture analyzed and documented -- [ ] Integration points with existing system identified -- [ ] Existing functionality preservation validated -- [ ] Database schema compatibility assessed -- [ ] API contract compatibility verified - -### C.2 Risk Management - -- [ ] Breaking change risks identified and mitigated -- [ ] Rollback procedures defined for each integration -- [ ] Feature flags or toggles included where appropriate -- [ ] Performance degradation risks assessed -- [ ] User impact analysis completed - -### C.3 Backward Compatibility - -- [ ] Database migrations maintain backward compatibility -- [ ] API changes don't break existing consumers -- [ ] Authentication/authorization integration safe -- [ ] Configuration changes non-breaking -- [ ] Existing monitoring preserved or enhanced - -### C.4 Dependency Conflicts - -- [ ] New dependencies compatible with existing versions -- [ ] No version conflicts introduced -- [ ] Security vulnerabilities not introduced -- [ ] License compatibility verified -- [ ] Bundle size impact acceptable - -## Section D: Feature Sequencing (All Levels) - -### D.1 Functional Dependencies - -- [ ] Features depending on others sequenced correctly -- [ ] Shared components built before consumers -- [ ] User flows follow logical progression -- [ ] Authentication precedes protected features - -### D.2 Technical Dependencies - -- [ ] Lower-level services before higher-level ones -- [ ] Utilities and libraries created before use -- [ ] Data models defined before operations -- [ ] API endpoints before client consumption - -### D.3 Epic Dependencies - -- [ ] Later epics build on earlier epic functionality -- [ ] No circular dependencies between epics -- [ ] Infrastructure from early epics reused -- [ ] Incremental value delivery maintained - -## Section E: UI/UX Cohesion (if UI components exist) - -### E.1 Design System (Greenfield) - -- [ ] UI framework selected and installed early -- [ ] Design system or component library established -- [ ] Styling approach defined -- [ ] Responsive design strategy clear -- [ ] Accessibility requirements defined - -### E.2 Design Consistency (Brownfield) - -- [ ] UI consistent with existing system -- [ ] Component library updates non-breaking -- [ ] Styling approach matches existing -- [ ] Accessibility standards maintained -- [ ] Existing user workflows preserved - -### E.3 UX Flow Validation - -- [ ] User journeys mapped completely -- [ ] Navigation patterns defined -- [ ] Error and loading states planned -- [ ] Form validation patterns established - -## Section F: Responsibility Assignment (All Levels) - -### F.1 User vs Agent Clarity - -- [ ] Human-only tasks assigned to user -- [ ] Account creation on external services → user -- [ ] Payment/purchasing actions → user -- [ ] All code tasks → developer agent -- [ ] Configuration management properly assigned - -## Section G: Documentation Readiness (All Levels) - -### G.1 Developer Documentation - -- [ ] Setup instructions comprehensive -- [ ] Technical decisions documented -- [ ] Patterns and conventions clear -- [ ] API documentation plan exists (if applicable) - -### G.2 Deployment Documentation (Brownfield) - -- [ ] Runbook updates planned -- [ ] Incident response procedures updated -- [ ] Rollback procedures documented and tested -- [ ] Monitoring dashboard updates planned - -## Section H: Future-Proofing (All Levels) - -### H.1 Extensibility - -- [ ] Current scope vs future features clearly separated -- [ ] Architecture supports planned enhancements -- [ ] Technical debt considerations documented -- [ ] Extensibility points identified - -### H.2 Observability - -- [ ] Monitoring strategy defined -- [ ] Success metrics from planning captured -- [ ] Analytics or tracking included if needed -- [ ] Performance measurement approach clear - -## Cohesion Summary - -### Overall Readiness Assessment - -- [ ] **Ready for Development** - All critical items pass -- [ ] **Needs Alignment** - Some gaps need addressing -- [ ] **Too Risky** (brownfield only) - Integration risks too high - -### Critical Gaps Identified - -_List any blocking issues or unacceptable risks:_ - -### Integration Risk Level (brownfield only) - -- [ ] Low - well-understood integration with good rollback -- [ ] Medium - some unknowns but manageable -- [ ] High - significant risks require mitigation - -### Recommendations - -_Specific actions to improve cohesion before development:_ - ---- diff --git a/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml b/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml deleted file mode 100644 index dabcb8c4..00000000 --- a/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml +++ /dev/null @@ -1,99 +0,0 @@ -# Game Design Document (GDD) Workflow -name: gdd -description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -# Workflow components -installed_path: "{project-root}/bmad/bmm/workflows/2-plan/gdd" -instructions: "{installed_path}/instructions-gdd.md" -template: "{installed_path}/gdd-template.md" -game_types_csv: "{installed_path}/game-types.csv" - -# Output configuration -default_output_file: "{output_folder}/GDD.md" - -# Game type references (loaded based on game type selection) -game_type_guides: "{installed_path}/game-types/" - -# Recommended input documents -recommended_inputs: - - game_brief: "{output_folder}/game-brief.md" - - narrative_design: "{output_folder}/narrative-design.md" - - market_research: "{output_folder}/market-research.md" - -# Claude Code integration points -claude_code_enhancements: - - injection_point: "game-design-subagents" - - available_subagents: - - game-designer: "Core game mechanics and systems design" - - game-architect: "Technical architecture for game systems" - - user-researcher: "Player experience and engagement" - -# Workflow configuration -interactive: true # User checkpoints throughout -autonomous: false # Requires user input -allow_parallel: false # Sequential design process - -# Game frameworks available -frameworks: - - "MDA Framework (Mechanics, Dynamics, Aesthetics)" - - "Core Loop Design" - - "Progression Systems" - - "Economy Design" - - "Difficulty Curves" - - "Player Psychology" - - "Game Feel and Juice" - -web_bundle: - name: "gdd" - description: "Game Design Document workflow for all game project levels - from small prototypes to full AAA games. Generates comprehensive GDD with game mechanics, systems, progression, and implementation guidance." - author: "BMad" - instructions: "bmad/bmm/workflows/2-plan/gdd/instructions-gdd.md" - use_advanced_elicitation: true - web_bundle_files: - - "bmad/bmm/workflows/2-plan/gdd/instructions-gdd.md" - - "bmad/bmm/workflows/2-plan/gdd/gdd-template.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types.csv" - - "bmad/bmm/workflows/2-plan/gdd/game-types/action-platformer.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/adventure.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/card-game.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/fighting.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/horror.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/idle-incremental.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/metroidvania.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/moba.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/party-game.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/puzzle.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/racing.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/rhythm.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/roguelike.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/rpg.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/sandbox.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/shooter.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/simulation.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/sports.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/strategy.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/survival.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/text-based.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/tower-defense.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/turn-based-tactics.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/visual-novel.md" - # Game frameworks available - frameworks: - - "MDA Framework (Mechanics, Dynamics, Aesthetics)" - - "Core Loop Design" - - "Progression Systems" - - "Economy Design" - - "Difficulty Curves" - - "Player Psychology" - - "Game Feel and Juice" - # Workflow configuration - interactive: true # User checkpoints throughout - autonomous: false # Requires user input - allow_parallel: false # Sequential design process diff --git a/src/modules/bmm/workflows/2-plan/instructions-router.md b/src/modules/bmm/workflows/2-plan/instructions-router.md deleted file mode 100644 index 8247deb1..00000000 --- a/src/modules/bmm/workflows/2-plan/instructions-router.md +++ /dev/null @@ -1,329 +0,0 @@ -# PRD Workflow Router Instructions - - - -This workflow requires a workflow status file to exist -ALWAYS check for existing bmm-workflow-status.md first -If no status file exists, direct user to run workflow-status first -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml - - - -Check if any bmm-workflow-status\*.md files exist in {output_folder}/ - - - **⚠️ No Workflow Status File Found** - -The `plan-project` workflow requires an existing workflow status file. - -Please run `workflow-status` first to: - -- Map out your complete workflow journey -- Determine project type and level -- Create the status file with your planned workflow - -**To proceed:** - -1. Load any agent (Analyst, PM, or use bmad-master) -2. Run: `workflow-status` -3. Complete the workflow planning -4. Return here to continue with `plan-project` - -Or tell me: "run workflow-status" - -Exit workflow - cannot proceed without status file - - - - Find the most recent bmm-workflow-status.md file - Load the status file - Extract key information: - -**From Status File:** - -- project_type: From "Project Type:" field -- project_level: From "Project Level:" field (0, 1, 2, 3, or 4) -- field_type: From "Greenfield/Brownfield:" field -- planned_workflow: From "Planned Workflow Journey" table -- current_step: From "Current Step:" field -- next_step: From "Next Step:" field - - Validate this workflow is the correct next step - - - **⚠️ Workflow Sequence Warning** - -According to your status file, your next planned step is: **{{next_step}}** - -But you're trying to run: **plan-project** - -Options: - -1. **Continue anyway** - Run plan-project (status file will be updated) -2. **Follow planned workflow** - Run {{next_step}} instead -3. **Update workflow plan** - Run workflow-status to revise plan - -Your choice (1-3): - - - **Recommended Next Step:** - -Load agent: {{next_step_agent}} -Run: {{next_step}} - -Or tell me: "run {{next_step}}" - -Exit workflow - - - - **Update Workflow Plan:** - -Run: `workflow-status` - -After updating your plan, return here if needed. - -Exit workflow - - - -Set status_file_path = existing file path -Check for existing workflow outputs based on level in status file: - -- Level 0: Check for tech-spec.md -- Level 1-2: Check for PRD.md, epic-stories.md, tech-spec.md -- Level 3-4: Check for PRD.md, epics.md - - - Found existing workflow status file: bmm-workflow-status.md (Level {{project_level}}) - -**Existing documents detected:** -{{list_existing_docs}} - -Options: - -1. **Continue** - Update existing documents -2. **Start fresh** - Archive old documents, create new ones -3. **Exit** - I'm not ready to regenerate these - -Your choice (1-3): - - - Set continuation_mode = true - Will update existing documents - - - - Archive existing documents to: "{output_folder}/archive/" - Set continuation_mode = false - Will create fresh documents - - - - Exit workflow - - - - - - Set continuation_mode = false - Ready to create new documents - - - - - - - -**Status File Data Loaded:** - -- Project Type: {{project_type}} -- Project Level: {{project_level}} -- Field Type: {{field_type}} -- Current Phase: {{current_phase}} - - -What type of planning do you need? - -**Based on your project (Level {{project_level}} {{project_type}}):** - -{{#if project_level == 0}} -**Recommended:** Tech spec only (Level 0 path) -{{/if}} - -{{#if project_level == 1}} -**Recommended:** Tech spec + epic/stories (Level 1 path) -{{/if}} - -{{#if project_level >= 2}} -**Recommended:** Full PRD + epics (Level {{project_level}} path) -{{/if}} - -**Other Options:** - -1. **Follow recommended path** (recommended) -2. **UX/UI specification only** -3. **Generate AI Frontend Prompt** (from existing specs) -4. **Describe custom needs** - -Select an option (1-4): - -Capture user selection as {{planning_type}} - - - {installed_path}/ux/workflow.yaml - Pass mode="standalone" to UX workflow - Exit router workflow (skip remaining steps) - - - - Check for existing UX spec or PRD - {project-root}/bmad/bmm/tasks/ai-fe-prompt.md - Exit router workflow after prompt generation - - -Use project_level and project_type from status file to route to appropriate workflow - - - - - -Read status file to check if additional context is needed - - - **⚠️ Brownfield Documentation Needed** - -Your status file indicates this brownfield project needs codebase documentation. - -The document-project workflow was flagged in your planned workflow. - -**Options:** - -1. **Generate docs now** - Run document-project workflow (~10-15 min) -2. **Skip for now** - I'll provide context through questions -3. **Already have docs** - I have documentation to reference - -Choose option (1-3): - - - Invoke document-project workflow before continuing - {project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml - Wait for documentation to complete - Update status file: Mark document-project as "Complete" in planned workflow - - - - Set gather_context_via_questions = true - Will ask detailed questions during spec generation - - - - Set has_documentation = true - Will reference existing documentation - - - - - **Project Level Not Yet Determined** - -Your status file indicates the project level will be determined during planning. - -**Based on what you want to build, what level best describes your project?** - -0. **Single atomic change** - Bug fix, add endpoint, single file change -1. **Coherent feature** - Add search, implement SSO, new component (2-3 stories) -2. **Small complete system** - Admin tool, team app, prototype (multiple epics) -3. **Full product** - Customer portal, SaaS MVP (subsystems, integrations) -4. **Platform/ecosystem** - Enterprise suite, multi-tenant system - -Your level (0-4): - -Capture confirmed_level -Update status file with confirmed project_level - - - - **Project Type Clarification Needed** - -Please describe your project type so we can load the correct planning template. - -Examples: web, mobile, desktop, backend, library, cli, game, embedded, data, extension, infra - -Your project type: - -Capture and map to project_type_id from project-types.csv -Update status file with confirmed project_type - - - - - - -Update status file before proceeding: - -current_workflow -Set to: "tech-spec (Level 0 - in progress)" -Set to: "tech-spec (Level 1 - in progress)" -Set to: "PRD (Level {{project_level}} - in progress)" - -current_step -Set to: "plan-project" - -progress_percentage -Increment by 10% (planning started) - -Add to decisions log: - -``` -- **{{date}}**: Started plan-project workflow. Routing to {{workflow_type}} workflow based on Level {{project_level}} {{project_type}} project. -``` - -Based on project type and level from status file, load ONLY the needed instructions: - - - {installed_path}/gdd/workflow.yaml - GDD workflow handles all game project levels internally - Pass status_file_path and continuation_mode to workflow - - - - {installed_path}/tech-spec/workflow.yaml - Pass level=0 to tech-spec workflow - Tech-spec workflow will generate tech-spec + 1 story - Pass status_file_path and continuation_mode to workflow - - - - {installed_path}/tech-spec/workflow.yaml - Pass level=1 to tech-spec workflow - Tech-spec workflow will generate tech-spec + epic + 2-3 stories - Pass status_file_path and continuation_mode to workflow - - - - {installed_path}/prd/workflow.yaml - Pass level=2 context to PRD workflow (loads instructions-med.md) - Pass status_file_path and continuation_mode to workflow - - - - {installed_path}/prd/workflow.yaml - Pass level context to PRD workflow (loads instructions-lg.md) - Pass status_file_path and continuation_mode to workflow - - -Pass context to invoked workflow: - -- status_file_path: {{status_file_path}} -- continuation_mode: {{continuation_mode}} -- existing_documents: {{document_list}} -- project_level: {{project_level}} -- project_type: {{project_type}} -- field_type: {{field_type}} -- gather_context_via_questions: {{gather_context_via_questions}} (if brownfield without docs) - -The invoked workflow will update the status file when complete - - - - diff --git a/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml b/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml deleted file mode 100644 index 06a508eb..00000000 --- a/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml +++ /dev/null @@ -1,63 +0,0 @@ -# Narrative Design Workflow -name: narrative -description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -# Workflow components -installed_path: "{project-root}/bmad/bmm/workflows/2-plan/narrative" -instructions: "{installed_path}/instructions-narrative.md" -template: "{installed_path}/narrative-template.md" - -# Output configuration -default_output_file: "{output_folder}/narrative-design.md" - -# Recommended input documents -recommended_inputs: - - game_brief: "{output_folder}/game-brief.md" - - gdd: "{output_folder}/GDD.md" - - product_brief: "{output_folder}/product-brief.md" - -# Workflow configuration -interactive: true # User checkpoints throughout -autonomous: false # Requires user input -allow_parallel: false # Sequential narrative development - -# Narrative frameworks available -frameworks: - - "Hero's Journey" - - "Three-Act Structure" - - "Character Arc Development" - - "Branching Narrative Design" - - "Environmental Storytelling" - - "Dialogue Systems" - - "Narrative Pacing" - -web_bundle: - name: "narrative" - description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance." - author: "BMad" - instructions: "bmad/bmm/workflows/2-plan/narrative/instructions-narrative.md" - use_advanced_elicitation: true - web_bundle_files: - - "bmad/bmm/workflows/2-plan/narrative/instructions-narrative.md" - - "bmad/bmm/workflows/2-plan/narrative/narrative-template.md" - recommended_inputs: "PRD, Product Brief, Brain Storming Report, GDD" - # Narrative frameworks available - frameworks: - - "Hero's Journey" - - "Three-Act Structure" - - "Character Arc Development" - - "Branching Narrative Design" - - "Environmental Storytelling" - - "Dialogue Systems" - - "Narrative Pacing" - # Workflow configuration - interactive: true # User checkpoints throughout - autonomous: false # Requires user input - allow_parallel: false # Sequential narrative development diff --git a/src/modules/bmm/workflows/2-plan/prd/epics-template.md b/src/modules/bmm/workflows/2-plan/prd/epics-template.md deleted file mode 100644 index bfa99558..00000000 --- a/src/modules/bmm/workflows/2-plan/prd/epics-template.md +++ /dev/null @@ -1,18 +0,0 @@ -# {{project_name}} - Epic Breakdown - -**Author:** {{user_name}} -**Date:** {{date}} -**Project Level:** {{project_level}} -**Target Scale:** {{target_scale}} - ---- - -## Epic Overview - -{{epic_overview}} - ---- - -## Epic Details - -{{epic_details}} diff --git a/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md b/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md deleted file mode 100644 index 753369a4..00000000 --- a/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md +++ /dev/null @@ -1,272 +0,0 @@ -# PRD Workflow - Large Projects (Level 3-4) - - - -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -This is the LARGE instruction set for Level 3-4 projects - full PRD + architect handoff -Project analysis already completed - proceeding with comprehensive requirements -NO TECH-SPEC - architecture handled by specialist workflow -Uses prd_template for PRD output, epics_template for epics output -If users mention technical details, append to technical_preferences with timestamp - - - -Load bmm-workflow-status.md -Confirm Level 3-4 - Full product or platform - - - Load existing PRD.md and check completion status - Found existing work. Would you like to: - -1. Review what's done and continue -2. Modify existing sections -3. Start fresh - - If continuing, skip to first incomplete section - - - - Check `output_folder` for `product_brief`, `market_research`, and other docs. - -For Level 3-4, Product Brief is STRONGLY recommended - -Load prd_template from workflow.yaml - -Get comprehensive description of the project vision. - -description - - - - - - -What is the deployment intent? - -- MVP for early users -- Production SaaS/application -- Enterprise system -- Platform/ecosystem - - -deployment_intent - -**Goal Guidelines**: - -- Level 3: 3-5 strategic goals -- Level 4: 5-7 strategic goals - -Each goal should be measurable and outcome-focused. - -goals - - - - - -1-2 paragraphs on problem, current situation, why now. - -context -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -**FR Guidelines**: - -- Level 3: 12-20 FRs -- Level 4: 20-30 FRs - -Group related features logically. - -functional_requirements -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -Match NFRs to deployment intent (8-12 NFRs) - -non_functional_requirements - - - - - -**Journey Requirements**: - -- Level 3: 2-3 detailed journeys -- Level 4: 3-5 comprehensive journeys - -Map complete user flows with decision points. - -user_journeys -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -8-10 UX principles guiding all interface decisions. - -ux_principles - - - - - -**Epic Guidelines**: - -- Level 3: 2-5 epics (12-40 stories) -- Level 4: 5+ epics (40+ stories) - -Each epic delivers significant value. - -epics -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -Load epics_template from workflow.yaml - -Create separate epics.md with full story hierarchy - -epic_overview - - - -Generate Epic {{epic_number}} with expanded goals, capabilities, success criteria. - -Generate all stories with: - -- User story format -- Prerequisites -- Acceptance criteria (3-8 per story) -- Technical notes (high-level only) - -epic\_{{epic_number}}\_details -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - - - -List features/ideas preserved for future phases. - -out_of_scope - - - - - -Only document ACTUAL assumptions from discussion. - -assumptions_and_dependencies - - - - - -## Next Steps for {{project_name}} - -Since this is a Level {{project_level}} project, you need architecture before stories. - -**Start new chat with architect and provide:** - -1. This PRD: `{{default_output_file}}` -2. Epic structure: `{{epics_output_file}}` -3. Input documents: {{input_documents}} - -**Ask architect to:** - -- Run `architecture` workflow -- Consider reference architectures -- Generate solution fragments -- Create solution-architecture.md - -## Complete Next Steps Checklist - -Generate comprehensive checklist based on project analysis - -### Phase 1: Architecture and Design - -- [ ] **Run architecture workflow** (REQUIRED) - - Command: `workflow architecture` - - Input: PRD.md, epics.md - - Output: solution-architecture.md - - - -- [ ] **Run UX specification workflow** (HIGHLY RECOMMENDED for user-facing systems) - Command: `workflow plan-project` then select "UX specification" - Or continue within this workflow if UI-heavy - Input: PRD.md, epics.md, solution-architecture.md (once available) - Output: ux-specification.md - Optional: AI Frontend Prompt for rapid prototyping - Note: Creates comprehensive UX/UI spec including IA, user flows, components - -Update workflow status file to mark ux-spec as next step -In status file, set next_action: "Run UX specification workflow" -In status file, set next_command: "ux-spec" -In status file, set next_agent: "PM" -Add to decisions log: "PRD complete. UX workflow required due to UI components." - - -### Phase 2: Detailed Planning - -- [ ] **Generate detailed user stories** - - Command: `workflow generate-stories` - - Input: epics.md + solution-architecture.md - - Output: user-stories.md with full acceptance criteria - -- [ ] **Create technical design documents** - - Database schema - - API specifications - - Integration points - -- [ ] **Define testing strategy** - - Unit test approach - - Integration test plan - - UAT criteria - -### Phase 3: Development Preparation - -- [ ] **Set up development environment** - - Repository structure - - CI/CD pipeline - - Development tools - -- [ ] **Create sprint plan** - - Story prioritization - - Sprint boundaries - - Resource allocation - -- [ ] **Establish monitoring and metrics** - - Success metrics from PRD - - Technical monitoring - - User analytics - -Project Planning Complete! Next immediate action: - -1. Start architecture workflow with the architect in a new context window -2. Create UX specification (if UI-heavy project) -3. Generate AI Frontend Prompt (if UX complete) -4. Review all outputs with stakeholders -5. Begin detailed story generation -6. Exit workflow - -Which would you like to proceed with? - - - {project-root}/bmad/bmm/workflows/2-plan/ux/workflow.yaml - Pass mode="integrated" with Level 3-4 context - - - - {project-root}/bmad/bmm/tasks/ai-fe-prompt.md - - - - - diff --git a/src/modules/bmm/workflows/2-plan/prd/instructions-med.md b/src/modules/bmm/workflows/2-plan/prd/instructions-med.md deleted file mode 100644 index abb277e8..00000000 --- a/src/modules/bmm/workflows/2-plan/prd/instructions-med.md +++ /dev/null @@ -1,259 +0,0 @@ -# PRD Workflow - Medium Projects (Level 1-2) - - - -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -This is the MEDIUM instruction set for Level 1-2 projects - minimal PRD + solutioning handoff -Project analysis already completed - proceeding with focused requirements -Uses prd_template for PRD output, epics_template for epics output -NO TECH-SPEC - solutioning handled by specialist workflow -If users mention technical details, append to technical_preferences with timestamp - - - -Load bmm-workflow-status.md -Confirm Level 1-2 - Feature or small system - - - Load existing PRD.md and check completion status - Found existing work. Would you like to: - -1. Review what's done and continue -2. Modify existing sections -3. Start fresh - - If continuing, skip to first incomplete section - - - - Check `output_folder` for existing docs. Ask user if they have a Product Brief. - -Load prd_template from workflow.yaml -Discuss with them to get the core idea of what they're building - -description - - - - - - -What is the deployment intent? - -- Demo/POC -- MVP for early users -- Production app - - -deployment_intent - -**Goal Guidelines**: - -- Level 1: 1-2 primary goals -- Level 2: 2-3 primary goals - -goals - - - - - -**Keep it brief**: 1 paragraph on why this matters now. - -context - - - - - -**FR Guidelines**: - -- Level 1: 3-8 FRs -- Level 2: 8-15 FRs - -**Format**: `FR001: [user capability]` - -functional_requirements -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -Focus on critical NFRs only (3-5 max) - -non_functional_requirements - - - - - -- Level 2: 1 simple user journey for primary use case - -user_journeys - - - - - -3-5 key UX principles if relevant - -ux_principles - - - - - -**Epic Guidelines**: - -- Level 1: 1 epic with 1-10 stories -- Level 2: 1-2 epics with 5-15 stories total - -Create simple epic list with story titles. - -epics - -Load epics_template from workflow.yaml - -Generate epic-stories.md with basic story structure. - -epic_stories -{project-root}/bmad/core/tasks/adv-elicit.xml - - - - - -List features/ideas preserved for future phases. - -out_of_scope - - - - - -Only document ACTUAL assumptions from discussion. - -assumptions_and_dependencies - - - - - -Offer to run cohesion validation - -Planning complete! Before proceeding to next steps, would you like to validate project cohesion? - -**Cohesion Validation** checks: - -- PRD-Tech Spec alignment -- Feature sequencing and dependencies -- Infrastructure setup order (greenfield) -- Integration risks and rollback plans (brownfield) -- External dependencies properly planned -- UI/UX considerations (if applicable) - -Run cohesion validation? (y/n) - - - Load {installed_path}/checklist.md - Review all outputs against "Cohesion Validation (All Levels)" section - Validate PRD sections, then cohesion sections A-H as applicable - Apply Section B (Greenfield) or Section C (Brownfield) based on field_type - Include Section E (UI/UX) if UI components exist - Generate comprehensive validation report with findings - - - - - - - -## Next Steps for {{project_name}} - -Since this is a Level {{project_level}} project, you need solutioning before implementation. - -**Start new chat with solutioning workflow and provide:** - -1. This PRD: `{{default_output_file}}` -2. Epic structure: `{{epics_output_file}}` -3. Input documents: {{input_documents}} - -**Ask solutioning workflow to:** - -- Run `3-solutioning` workflow -- Generate solution-architecture.md -- Create per-epic tech specs - -## Complete Next Steps Checklist - -Generate comprehensive checklist based on project analysis - -### Phase 1: Solution Architecture and Design - -- [ ] **Run solutioning workflow** (REQUIRED) - - Command: `workflow solution-architecture` - - Input: PRD.md, epic-stories.md - - Output: solution-architecture.md, tech-spec-epic-N.md files - - - -- [ ] **Run UX specification workflow** (HIGHLY RECOMMENDED for user-facing systems) - Command: `workflow plan-project` then select "UX specification" - Or continue within this workflow if UI-heavy - Input: PRD.md, epic-stories.md, solution-architecture.md (once available) - Output: ux-specification.md - Optional: AI Frontend Prompt for rapid prototyping - Note: Creates comprehensive UX/UI spec including IA, user flows, components - -Update workflow status file to mark ux-spec as next step -In status file, set next_action: "Run UX specification workflow" -In status file, set next_command: "ux-spec" -In status file, set next_agent: "PM" -Add to decisions log: "PRD complete. UX workflow required due to UI components." - - -### Phase 2: Detailed Planning - -- [ ] **Generate detailed user stories** - - Command: `workflow generate-stories` - - Input: epic-stories.md + solution-architecture.md - - Output: user-stories.md with full acceptance criteria - -- [ ] **Create technical design documents** - - Database schema - - API specifications - - Integration points - -### Phase 3: Development Preparation - -- [ ] **Set up development environment** - - Repository structure - - CI/CD pipeline - - Development tools - -- [ ] **Create sprint plan** - - Story prioritization - - Sprint boundaries - - Resource allocation - -Project Planning Complete! Next immediate action: - -1. Start solutioning workflow -2. Create UX specification (if UI-heavy project) -3. Generate AI Frontend Prompt (if UX complete) -4. Review all outputs with stakeholders -5. Begin detailed story generation -6. Exit workflow - -Which would you like to proceed with? - - - {project-root}/bmad/bmm/workflows/2-plan/ux/workflow.yaml - Pass mode="integrated" with Level 1-2 context - - - - - {project-root}/bmad/bmm/tasks/ai-fe-prompt.md - - - - - - diff --git a/src/modules/bmm/workflows/2-plan/prd/prd-template.md b/src/modules/bmm/workflows/2-plan/prd/prd-template.md deleted file mode 100644 index 18b1f0bf..00000000 --- a/src/modules/bmm/workflows/2-plan/prd/prd-template.md +++ /dev/null @@ -1,73 +0,0 @@ -# {{project_name}} Product Requirements Document (PRD) - -**Author:** {{user_name}} -**Date:** {{date}} -**Project Level:** {{project_level}} -**Project Type:** {{project_type}} -**Target Scale:** {{target_scale}} - ---- - -## Description, Context and Goals - -{{description}} - -### Deployment Intent - -{{deployment_intent}} - -### Context - -{{context}} - -### Goals - -{{goals}} - -## Requirements - -### Functional Requirements - -{{functional_requirements}} - -### Non-Functional Requirements - -{{non_functional_requirements}} - -## User Journeys - -{{user_journeys}} - -## UX Design Principles - -{{ux_principles}} - -## Epics - -{{epics}} - -{{epic_note}} - -## Out of Scope - -{{out_of_scope}} - ---- - -## Next Steps - -{{next_steps}} - -## Document Status - -- [ ] Goals and context validated with stakeholders -- [ ] All functional requirements reviewed -- [ ] User journeys cover all major personas -- [ ] Epic structure approved for phased delivery -- [ ] Ready for architecture phase - -_Note: See technical-decisions.md for captured technical context_ - ---- - -_This PRD adapts to project level {{project_level}} - providing appropriate detail without overburden._ diff --git a/src/modules/bmm/workflows/2-plan/prd/workflow.yaml b/src/modules/bmm/workflows/2-plan/prd/workflow.yaml deleted file mode 100644 index 1223e38a..00000000 --- a/src/modules/bmm/workflows/2-plan/prd/workflow.yaml +++ /dev/null @@ -1,95 +0,0 @@ -# Product Requirements Document (PRD) Workflow -name: prd -description: "Scale-adaptive PRD workflow for project levels 1-4. Level 1-2: focused PRD + solutioning handoff. Level 3-4: full PRD with epics + architect handoff. Automatically adjusts scope based on project complexity." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/bmad/bmm/config.yaml" -project_name: "{config_source}:project_name" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -# Workflow components -installed_path: "{project-root}/bmad/bmm/workflows/2-plan/prd" - -# Instructions - routes to appropriate level-based instructions -instructions_med: "{installed_path}/instructions-med.md" # Level 1-2 -instructions_lg: "{installed_path}/instructions-lg.md" # Level 3-4 - -# Templates -prd_template: "{installed_path}/prd-template.md" -status_template: "{project-root}/bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" -epics_template: "{installed_path}/epics-template.md" - -# Output configuration -status_file: "{output_folder}/bmm-workflow-status.md" -default_output_file: "{output_folder}/PRD.md" -epics_output_file: "{output_folder}/epics.md" -validation_output_file: "{output_folder}/PRD-validation-report.md" - -# Recommended input documents -recommended_inputs: - - product_brief: "{output_folder}/product-brief.md" - - market_research: "{output_folder}/market-research.md" - -# Scale parameters - adaptive by project level -scale_parameters: - level_1: "1-10 stories, 1 epic, minimal PRD + solutioning handoff" - level_2: "5-15 stories, 1-2 epics, focused PRD + solutioning handoff" - level_3: "12-40 stories, 2-5 epics, full PRD + architect handoff" - level_4: "40+ stories, 5+ epics, enterprise PRD + architect handoff" - -# Claude Code integration points -claude_code_enhancements: - - injection_point: "prd-subagents" - - available_subagents: - - requirements-analyst: "Requirements analysis and refinement" - - user-journey-mapper: "User journey and epic boundaries" - - epic-optimizer: "Epic scope optimization" - - document-reviewer: "PRD quality validation" - -# Workflow configuration -interactive: true # User checkpoints throughout -autonomous: false # Requires user input -allow_parallel: false # Sequential planning process - -# Product frameworks available -frameworks: - - "Jobs-to-be-Done" - - "User Story Mapping" - - "Epic Decomposition" - - "Acceptance Criteria" - - "MoSCoW Prioritization" - -web_bundle: - name: "prd" - description: "Scale-adaptive PRD workflow for project levels 1-4. Level 1-2: focused PRD + solutioning handoff. Level 3-4: full PRD with epics + architect handoff. Automatically adjusts scope based on project complexity." - author: "BMad" - # Note: Router workflow will load appropriate instructions based on level - instructions_med: "bmad/bmm/workflows/2-plan/prd/instructions-med.md" - instructions_lg: "bmad/bmm/workflows/2-plan/prd/instructions-lg.md" - use_advanced_elicitation: true - web_bundle_files: - - "bmad/bmm/workflows/2-plan/prd/instructions-med.md" - - "bmad/bmm/workflows/2-plan/prd/instructions-lg.md" - - "bmad/bmm/workflows/2-plan/prd/prd-template.md" - - "bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" - - "bmad/bmm/workflows/2-plan/prd/epics-template.md" - # Scale parameters - adaptive by project level - scale_parameters: - level_1: "1-10 stories, 1 epic, minimal PRD + solutioning handoff" - level_2: "5-15 stories, 1-2 epics, focused PRD + solutioning handoff" - level_3: "12-40 stories, 2-5 epics, full PRD + architect handoff" - level_4: "40+ stories, 5+ epics, enterprise PRD + architect handoff" - # Product frameworks available - frameworks: - - "Jobs-to-be-Done" - - "User Story Mapping" - - "Epic Decomposition" - - "Acceptance Criteria" - - "MoSCoW Prioritization" - # Workflow configuration - interactive: true # User checkpoints throughout - autonomous: false # Requires user input - allow_parallel: false # Sequential planning process diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/epic-stories-template.md b/src/modules/bmm/workflows/2-plan/tech-spec/epic-stories-template.md deleted file mode 100644 index 915930b1..00000000 --- a/src/modules/bmm/workflows/2-plan/tech-spec/epic-stories-template.md +++ /dev/null @@ -1,123 +0,0 @@ -# Epic and User Stories - Level 1 - -**Project:** {{project_name}} -**Level:** Level 1 (Coherent Feature) -**Date:** {{date}} -**Author:** {{user_name}} - ---- - -## Epic Overview - -### Epic: {{epic_title}} - -**Goal:** {{epic_goal}} - -**Scope:** {{epic_scope}} - -**Success Criteria:** -{{epic_success_criteria}} - -**Dependencies:** {{epic_dependencies}} - -**Story Count:** {{story_count}} ({{total_points}} points) - ---- - -## Story Files Generated - -This workflow generates {{story_count}} story files in the following format: - -- `story-{{story_slug}}-1.md` -- `story-{{story_slug}}-2.md` -- `story-{{story_slug}}-3.md` (if applicable) - -**Location:** `{{dev_story_location}}/` - -**Next Steps:** - -1. Run story-context workflow on story 1 -2. Run dev-story workflow to implement story 1 -3. Repeat for stories 2, 3, etc. - ---- - -## Story Summaries - -### Story 1: {{story_1_title}} - -**File:** `story-{{story_slug}}-1.md` - -**User Story:** -As a {{story_1_role}}, I want {{story_1_capability}}, so that {{story_1_benefit}}. - -**Acceptance Criteria Summary:** -{{story_1_acceptance_summary}} - -**Story Points:** {{story_1_points}} - -**Dependencies:** {{story_1_dependencies}} - ---- - -### Story 2: {{story_2_title}} - -**File:** `story-{{story_slug}}-2.md` - -**User Story:** -As a {{story_2_role}}, I want {{story_2_capability}}, so that {{story_2_benefit}}. - -**Acceptance Criteria Summary:** -{{story_2_acceptance_summary}} - -**Story Points:** {{story_2_points}} - -**Dependencies:** {{story_2_dependencies}} - ---- - -### Story 3: {{story_3_title}} (if applicable) - -**File:** `story-{{story_slug}}-3.md` - -**User Story:** -As a {{story_3_role}}, I want {{story_3_capability}}, so that {{story_3_benefit}}. - -**Acceptance Criteria Summary:** -{{story_3_acceptance_summary}} - -**Story Points:** {{story_3_points}} - -**Dependencies:** {{story_3_dependencies}} - ---- - -## Story Map - -``` -Epic: {{epic_title}} -├── Story 1: {{story_1_title}} ({{story_1_points}} points) -├── Story 2: {{story_2_title}} ({{story_2_points}} points) -└── Story 3: {{story_3_title}} ({{story_3_points}} points) [if applicable] -``` - -**Total Story Points:** {{total_points}} -**Estimated Timeline:** {{estimated_timeline}} - ---- - -## Implementation Sequence - -{{implementation_sequence}} - ---- - -## Technical References - -- **Tech Spec:** `{{output_folder}}/tech-spec.md` - Technical source of truth -- **Architecture:** {{architecture_files}} - ---- - -_Generated as part of Level 1 Tech Spec workflow (BMad Method v6)_ -_This is a summary document. Actual story files are generated in `{{dev_story_location}}/`_ diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml deleted file mode 100644 index 24911a20..00000000 --- a/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml +++ /dev/null @@ -1,78 +0,0 @@ -# Technical Specification Workflow (Level 0) -name: tech-spec-sm -description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/bmad/bmm/config.yaml" -project_name: "{config_source}:project_name" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -# Workflow components -installed_path: "{project-root}/bmad/bmm/workflows/2-plan/tech-spec" -instructions: "{installed_path}/instructions-sm.md" -template: "{installed_path}/tech-spec-template.md" - -# Story generation instructions (invoked based on level) -instructions_level0_story: "{installed_path}/instructions-level0-story.md" -instructions_level1_stories: "{installed_path}/instructions-level1-stories.md" - -# Templates -user_story_template: "{installed_path}/user-story-template.md" -epic_stories_template: "{installed_path}/epic-stories-template.md" - -# Output configuration -default_output_file: "{output_folder}/tech-spec.md" -user_story_file: "{output_folder}/user-story.md" -epic_stories_file: "{output_folder}/epic-stories.md" - -# Recommended input documents (optional for Level 0) -recommended_inputs: - - bug_report: "Bug description or issue ticket" - - feature_request: "Brief feature description" - -# Claude Code integration points -claude_code_enhancements: - - injection_point: "tech-spec-subagents" - - available_subagents: - - technical-evaluator: "Technology assessment and feasibility" - - codebase-analyzer: "Existing code analysis" - - pattern-detector: "Identify coding patterns to follow" - -# Workflow configuration -interactive: true # User checkpoints -autonomous: false # Requires user input -allow_parallel: false # Sequential specification - -# Technical frameworks available -frameworks: - - "Technical Design Patterns" - - "API Design Principles" - - "Code Organization Standards" - - "Testing Strategies" - -web_bundle: - name: "tech-spec-sm" - description: "Technical specification workflow for Level 0-1 projects. Creates focused tech spec with story generation. Level 0: tech-spec + user story. Level 1: tech-spec + epic/stories." - author: "BMad" - instructions: "bmad/bmm/workflows/2-plan/tech-spec/instructions-sm.md" - use_advanced_elicitation: true - web_bundle_files: - - "bmad/bmm/workflows/2-plan/tech-spec/instructions-sm.md" - - "bmad/bmm/workflows/2-plan/tech-spec/instructions-level0-story.md" - - "bmad/bmm/workflows/2-plan/tech-spec/instructions-level1-stories.md" - - "bmad/bmm/workflows/2-plan/tech-spec/tech-spec-template.md" - - "bmad/bmm/workflows/2-plan/tech-spec/user-story-template.md" - - "bmad/bmm/workflows/2-plan/tech-spec/epic-stories-template.md" - # Technical frameworks available - frameworks: - - "Technical Design Patterns" - - "API Design Principles" - - "Code Organization Standards" - - "Testing Strategies" - # Workflow configuration - interactive: true # User checkpoints - autonomous: false # Requires user input - allow_parallel: false # Sequential specification diff --git a/src/modules/bmm/workflows/2-plan/ux/workflow.yaml b/src/modules/bmm/workflows/2-plan/ux/workflow.yaml deleted file mode 100644 index 71ed2590..00000000 --- a/src/modules/bmm/workflows/2-plan/ux/workflow.yaml +++ /dev/null @@ -1,71 +0,0 @@ -# UX/UI Specification Workflow -name: ux-spec -description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -# Workflow components -installed_path: "{project-root}/bmad/bmm/workflows/2-plan/ux" -instructions: "{installed_path}/instructions-ux.md" -template: "{installed_path}/ux-spec-template.md" - -# Output configuration -default_output_file: "{output_folder}/ux-specification.md" -ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md" - -# Recommended input documents -recommended_inputs: - - prd: "{output_folder}/PRD.md" - - product_brief: "{output_folder}/product-brief.md" - - gdd: "{output_folder}/GDD.md" - -# Claude Code integration points -claude_code_enhancements: - - injection_point: "ux-subagents" - - available_subagents: - - ux-expert: "User experience design and best practices" - - user-researcher: "User research and persona development" - -# Workflow configuration -interactive: true # User checkpoints throughout -autonomous: false # Requires user input -allow_parallel: false # Sequential UX design process - -# UX frameworks available -frameworks: - - "User-Centered Design" - - "Design System Principles" - - "Accessibility (WCAG)" - - "Responsive Design" - - "Component-Based Design" - - "Atomic Design" - - "Material Design / Human Interface Guidelines" - -web_bundle: - name: "ux-spec" - description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines." - author: "BMad" - instructions: "bmad/bmm/workflows/2-plan/ux/instructions-ux.md" - use_advanced_elicitation: true - web_bundle_files: - - "bmad/bmm/workflows/2-plan/ux/instructions-ux.md" - - "bmad/bmm/workflows/2-plan/ux/ux-spec-template.md" - recommended_inputs: "PRD, Product Brief, Brain Storming Report, GDD" - # UX frameworks available - frameworks: - - "User-Centered Design" - - "Design System Principles" - - "Accessibility (WCAG)" - - "Responsive Design" - - "Component-Based Design" - - "Atomic Design" - - "Material Design / Human Interface Guidelines" - # Workflow configuration - interactive: true # User checkpoints throughout - autonomous: false # Requires user input - allow_parallel: false # Sequential UX design process diff --git a/src/modules/bmm/workflows/2-plan/workflow.yaml b/src/modules/bmm/workflows/2-plan/workflow.yaml deleted file mode 100644 index db62e81b..00000000 --- a/src/modules/bmm/workflows/2-plan/workflow.yaml +++ /dev/null @@ -1,140 +0,0 @@ -# Project Planning Workflow Configuration -name: "plan-project" -description: "Scale-adaptive project planning workflow for all project levels (0-4). Automatically adjusts outputs based on project scope - from single atomic changes (Level 0: tech-spec only) to enterprise platforms (Level 4: full PRD + epics). Level 2-4 route to 3-solutioning workflow for architecture and tech specs. Generates appropriate planning artifacts for each level." -author: "BMad" - -# Critical variables load from config_source -config_source: "{project-root}/bmad/bmm/config.yaml" -project_name: "{config_source}:project_name" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -date: system-generated - -recommended_inputs: - - product_brief: "{output_folder}/product-brief.md" - - game_brief: "{output_folder}/game-brief.md" - - market_research: "{output_folder}/market-research.md" - -# Module path and component files -installed_path: "{project-root}/bmad/bmm/workflows/2-plan" - -# Sub-workflow references - Router invokes these workflows based on project type/level -workflow_gdd: "{installed_path}/gdd/workflow.yaml" -workflow_prd: "{installed_path}/prd/workflow.yaml" -workflow_narrative: "{installed_path}/narrative/workflow.yaml" -workflow_tech_spec: "{installed_path}/tech-spec/workflow.yaml" -workflow_ux: "{installed_path}/ux/workflow.yaml" - -# Templates - Load these only when the instructions request loading them -prd_template: "{installed_path}/prd/prd-template.md" -status_template: "{project-root}/bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" -epics_template: "{installed_path}/prd/epics-template.md" -tech_spec_template: "{installed_path}/tech-spec/tech-spec-template.md" -ux_spec_template: "{installed_path}/ux/ux-spec-template.md" -gdd_template: "{installed_path}/gdd/gdd-template.md" -game_types_csv: "{installed_path}/gdd/game-types.csv" -narrative_template: "{installed_path}/narrative/narrative-template.md" - -# Routing instructions - loads appropriate instruction set based on project level -instructions: "{installed_path}/instructions-router.md" - -# Output configuration -status_file: "{output_folder}/bmm-workflow-status.md" -default_output_file: "{output_folder}/PRD.md" -gdd_output_file: "{output_folder}/GDD.md" -epics_output_file: "{output_folder}/epics.md" -tech_spec_file: "{output_folder}/tech-spec.md" -ux_spec_file: "{output_folder}/ux-specification.md" -narrative_design_file: "{output_folder}/narrative-design.md" -ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md" -validation_output_file: "{output_folder}/PRD-validation-report.md" - -# Scale parameters - adaptive by project level -scale_parameters: - level_0: "Single atomic change, tech-spec only" - level_1: "1-10 stories, 1 epic, minimal PRD + tech-spec" - level_2: "5-15 stories, 1-2 epics, focused PRD + tech-spec" - level_3: "12-40 stories, 2-5 epics, full PRD + architect handoff" - level_4: "40+ stories, 5+ epics, enterprise PRD + architect handoff" - -#Do not load these directly - instructions-router.md will load the proper file based on project type/level when needed -instructions_sm: "{installed_path}/tech-spec/instructions-sm.md" -instructions_med: "{installed_path}/prd/instructions-med.md" -instructions_lg: "{installed_path}/prd/instructions-lg.md" -instructions_ux: "{installed_path}/ux/instructions-ux.md" -instructions_gdd: "{installed_path}/gdd/instructions-gdd.md" -instructions_narrative: "{installed_path}/narrative/instructions-narrative.md" -validation: "{installed_path}/checklist.md" - -web_bundle: - name: "plan-project" - description: "Scale-adaptive project planning workflow for all project levels (0-4). Automatically adjusts outputs based on project scope - from single atomic changes (Level 0: tech-spec only) to enterprise platforms (Level 4: full PRD + epics). Level 2-4 route to 3-solutioning workflow for architecture and tech specs. Generates appropriate planning artifacts for each level." - author: "BMad" - # Routing instructions - loads appropriate instruction set based on project level - instructions: "bmad/bmm/workflows/2-plan/instructions-router.md" - validation: "bmad/bmm/workflows/2-plan/checklist.md" - use_advanced_elicitation: true - # Do not load these directly - instructions-router.md will load the proper file based on project type/level when needed - instructions_sm: "bmad/bmm/workflows/2-plan/tech-spec/instructions-sm.md" - instructions_med: "bmad/bmm/workflows/2-plan/prd/instructions-med.md" - instructions_lg: "bmad/bmm/workflows/2-plan/prd/instructions-lg.md" - instructions_ux: "bmad/bmm/workflows/2-plan/ux/instructions-ux.md" - instructions_gdd: "bmad/bmm/workflows/2-plan/gdd/instructions-gdd.md" - instructions_narrative: "bmad/bmm/workflows/2-plan/narrative/instructions-narrative.md" - # Templates - Load these only when the instructions request loading them - prd_template: "{installed_path}/prd/prd-template.md" - status_template: "bmad/bmm/workflows/_shared/bmm-workflow-status-template.md" - epics_template: "{installed_path}/prd/epics-template.md" - tech_spec_template: "{installed_path}/tech-spec/tech-spec-template.md" - ux_spec_template: "{installed_path}/ux/ux-spec-template.md" - gdd_template: "{installed_path}/gdd/gdd-template.md" - game_types_csv: "{installed_path}/gdd/game-types.csv" - narrative_template: "{installed_path}/narrative/narrative-template.md" - # Scale parameters - adaptive by project level - scale_parameters: - level_0: "Single atomic change, tech-spec only" - level_1: "1-10 stories, 1 epic, minimal PRD + tech-spec" - level_2: "5-15 stories, 1-2 epics, focused PRD + tech-spec" - level_3: "12-40 stories, 2-5 epics, full PRD + architect handoff" - level_4: "40+ stories, 5+ epics, enterprise PRD + architect handoff" - web_bundle_files: - - "bmad/bmm/workflows/2-plan/instructions-router.md" - - "bmad/bmm/workflows/2-plan/tech-spec/instructions-sm.md" - - "bmad/bmm/workflows/2-plan/prd/instructions-med.md" - - "bmad/bmm/workflows/2-plan/prd/instructions-lg.md" - - "bmad/bmm/workflows/2-plan/prd/prd-template.md" - - "bmad/bmm/workflows/2-plan/prd/epics-template.md" - - "bmad/bmm/workflows/2-plan/tech-spec/tech-spec-template.md" - - "bmad/bmm/workflows/2-plan/ux/ux-spec-template.md" - - "bmad/bmm/workflows/2-plan/ux/instructions-ux.md" - - "bmad/bmm/workflows/2-plan/gdd/gdd-template.md" - - "bmad/bmm/workflows/2-plan/gdd/instructions-gdd.md" - - "bmad/bmm/workflows/2-plan/narrative/instructions-narrative.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types.csv" - - "bmad/bmm/workflows/2-plan/gdd/game-types/action-platformer.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/adventure.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/card-game.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/fighting.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/horror.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/idle-incremental.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/metroidvania.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/moba.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/party-game.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/puzzle.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/racing.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/rhythm.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/roguelike.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/rpg.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/sandbox.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/shooter.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/simulation.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/sports.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/strategy.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/survival.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/text-based.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/tower-defense.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/turn-based-tactics.md" - - "bmad/bmm/workflows/2-plan/gdd/game-types/visual-novel.md" - - "bmad/bmm/workflows/2-plan/narrative/narrative-template.md" - - "bmad/bmm/workflows/2-plan/narrative/instructions-narrative.md" - - "bmad/bmm/workflows/2-plan/checklist.md" diff --git a/src/modules/bmm/workflows/3-solutioning/instructions.md b/src/modules/bmm/workflows/3-solutioning/instructions.md index ab5b0d38..3e79cbf6 100644 --- a/src/modules/bmm/workflows/3-solutioning/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/instructions.md @@ -5,6 +5,10 @@ This workflow generates scale-adaptive solution architecture documentation that ```xml +The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml +You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} + 1. Search {output_folder}/ for files matching pattern: bmm-workflow-status.md @@ -765,7 +769,7 @@ Add entries for all generated tech specs -**Phase 3 (Solutioning) Complete!** +**Phase 3 (Solutioning) Complete, {user_name}!** ✅ Solution architecture generated ✅ Cohesion check passed diff --git a/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md b/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md index 052f1363..003d09f7 100644 --- a/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md +++ b/src/modules/bmm/workflows/3-solutioning/tech-spec/README.md @@ -2,7 +2,7 @@ ## Overview -Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution. +Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution. ## Key Features diff --git a/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md b/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md index 4be1a06a..c5588162 100644 --- a/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/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. Default execution mode: #yolo (non-interactive). If required inputs cannot be auto-discovered and {{non_interactive}} == true, HALT with a clear message listing missing documents; do not prompt. @@ -149,7 +150,7 @@ What would you like to do? planned_workflow Mark "tech-spec (Epic {{epic_id}})" as complete in the planned workflow table - **✅ Tech Spec Generated Successfully** + **✅ Tech Spec Generated Successfully, {user_name}!** **Epic Details:** - Epic ID: {{epic_id}} @@ -172,7 +173,7 @@ What would you like to do? - **✅ Tech Spec Generated Successfully** + **✅ Tech Spec Generated Successfully, {user_name}!** **Epic Details:** - Epic ID: {{epic_id}} diff --git a/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml index 9b2378d4..12b0a788 100644 --- a/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/tech-spec/workflow.yaml @@ -25,27 +25,6 @@ validation: "{installed_path}/checklist.md" # Output configuration default_output_file: "{project-root}/docs/tech-spec-epic-{{epic_id}}.md" -# Required tools -required_tools: - - list_files - - file_info - - read_file - - write_file - - search_repo - - glob - - parse_markdown - -tags: - - tech-spec - - architecture - - planning - - bmad-v6 - -execution_hints: - interactive: false - autonomous: true - iterative: true - # Variables variables: non_interactive: true diff --git a/src/modules/bmm/workflows/3-solutioning/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/workflow.yaml index b6c5d184..a8e9cee7 100644 --- a/src/modules/bmm/workflows/3-solutioning/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad Builder" config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Input requirements 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 3fc5e297..722d753d 100644 --- a/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md @@ -2,6 +2,7 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml +Communicate all responses in {communication_language} @@ -189,7 +190,7 @@ - Specific edit proposals with before/after - Implementation handoff plan -Report workflow completion to user +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/bmm/workflows/4-implementation/correct-course/workflow.yaml b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml index 26d9129c..551c9751 100644 --- a/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml @@ -6,6 +6,7 @@ author: "BMad Method" config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course" 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 8b079437..07605175 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_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. Default execution mode: #yolo (minimal prompts). Only elicit if absolutely required and {{non_interactive}} == false. @@ -143,7 +144,7 @@ - **{{date}}**: Completed create-story for Story {{story_id}} ({{story_title}}). Story file: {{story_file}}. Status: Draft (needs review via story-ready). Next: Review and approve story. ``` - **✅ Story Created Successfully** + **✅ Story Created Successfully, {user_name}!** **Story Details:** - Story ID: {{story_id}} @@ -164,7 +165,7 @@ Check status anytime with: `workflow-status` - **✅ Story Created Successfully** + **✅ Story Created Successfully, {user_name}!** **Story Details:** - Story ID: {{story_id}} 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 06f802ce..6a77fda4 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -39,28 +39,9 @@ variables: # Output configuration default_output_file: "{story_dir}/story-{{epic_num}}.{{story_num}}.md" -required_tools: - - list_files - - file_info - - read_file - - write_file - - create_directory - - search_repo - - glob - recommended_inputs: - epics: "Epic breakdown (epics.md)" - prd: "PRD document" - solution-architecture: "Solution Architecture (optional)" -tags: - - story-generation - - planning - - bmad-v6 - -execution_hints: - interactive: false # Minimize prompts; intended to run to completion - autonomous: true # Proceed without user input unless blocked - iterative: true - web_bundle: false 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 b4a4c5fc..0c67fb01 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_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 If {{run_until_complete}} == true, run non-interactively: do not pause between steps unless a HALT condition is reached or explicit user approval is required for unapproved dependencies. @@ -131,7 +132,7 @@ - **{{date}}**: Completed dev-story for Story {{current_story_id}} ({{current_story_title}}). All tasks complete, tests passing. Story status: Ready for Review. Next: User reviews and runs story-approved when satisfied with implementation. ``` - **✅ Story Implementation Complete** + **✅ Story Implementation Complete, {user_name}!** **Story Details:** - Story ID: {{current_story_id}} @@ -153,7 +154,7 @@ Or check status anytime with: `workflow-status` - **✅ Story Implementation Complete** + **✅ Story Implementation Complete, {user_name}!** **Story Details:** - Story ID: {{current_story_id}} 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 c200caaa..613031c2 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/workflow.yaml @@ -31,25 +31,4 @@ variables: recommended_inputs: - story_markdown: "Path to the story markdown file (Tasks/Subtasks, Acceptance Criteria present)" -# Required tools (conceptual; executor should provide equivalents) -required_tools: - - read_file - - write_file - - search_repo - - run_tests - - list_files - - file_info - -tags: - - development - - story-execution - - tests - - validation - - bmad-v6 - -execution_hints: - interactive: false # Minimize prompts; intended to run to completion - autonomous: true # Proceed without user input unless blocked - iterative: true - web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index c6560ad4..1359dcf8 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -2,6 +2,7 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml +Communicate all responses in {communication_language} FACILITATION NOTES: @@ -447,7 +448,7 @@ Check status anytime with: `workflow-status` - **✅ Retrospective Complete** + **✅ Retrospective Complete, {user_name}!** **Epic Review:** diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index cff301e0..39a23c2d 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -6,6 +6,7 @@ author: "BMad" config_source: "{project-root}/bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective" diff --git a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md index c6c6e04b..e363ff6c 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This workflow performs a Senior Developer Review on a story flagged Ready for Review, appends structured review notes, and can update the story status based on the outcome. Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery of the target story fails, HALT with a clear message to provide 'story_path' or 'story_dir'. Only modify the story file in these areas: Status (optional per settings), Dev Agent Record (Completion Notes), File List (if corrections are needed), Change Log, and the appended "Senior Developer Review (AI)" section at the end of the document. @@ -222,7 +223,7 @@ What would you like to do? - **{{date}}**: Completed review-story for Story {{epic_num}}.{{story_num}}. Review outcome: {{outcome}}. Action items: {{action_item_count}}. Next: Address review feedback if needed, then continue with story-approved when ready. ``` - **✅ Story Review Complete** + **✅ Story Review Complete, {user_name}!** **Story Details:** - Story: {{epic_num}}.{{story_num}} @@ -243,7 +244,7 @@ Check status anytime with: `workflow-status` - **✅ Story Review Complete** + **✅ Story Review Complete, {user_name}!** **Story Details:** - Story: {{epic_num}}.{{story_num}} diff --git a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml index 6be84194..c8446f0f 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml @@ -60,29 +60,4 @@ recommended_inputs: - tech_spec: "Epic technical specification document (auto-discovered if omitted)" - story_context: "Story Context XML path (auto-discovered if omitted)" -# Required tools (conceptual; executor should provide equivalents) -required_tools: - - list_files - - file_info - - read_file - - write_file - - search_repo - - parse_markdown - - glob - - mcp_doc_search # Use available MCP servers to search docs/best-practices - - web_search # Fallback research - - read_url # Fetch references - -tags: - - review - - code-review - - quality - - testing - - bmad-v6 - -execution_hints: - interactive: false # Minimize prompts; intended to run deterministically - autonomous: true # Proceed without user input unless blocked - iterative: true - web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/story-approved/instructions.md b/src/modules/bmm/workflows/4-implementation/story-approved/instructions.md index e3ab3dca..44f419cc 100644 --- a/src/modules/bmm/workflows/4-implementation/story-approved/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-approved/instructions.md @@ -1,5 +1,9 @@ # Story Approved Workflow Instructions (DEV Agent) +The workflow execution engine is governed by: {project_root}/bmad/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) @@ -215,7 +219,7 @@ If BACKLOG had 1 story and is now empty: Display summary -**Story Approved and Marked Done!** +**Story Approved and Marked Done, {user_name}!** ✅ Story file updated: `{{current_story_file}}` → Status: Done ✅ Status file updated: Story moved IN PROGRESS → DONE diff --git a/src/modules/bmm/workflows/4-implementation/story-approved/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-approved/workflow.yaml index 054b953e..018b9086 100644 --- a/src/modules/bmm/workflows/4-implementation/story-approved/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-approved/workflow.yaml @@ -23,19 +23,4 @@ variables: # Output configuration - no output file, just status updates default_output_file: "" -required_tools: - - read_file - - edit_file - -tags: - - story-management - - status-update - - dev-agent - - bmad-v6 - -execution_hints: - interactive: false # Minimal prompts; quick status update - autonomous: true # Proceed without user input - iterative: false # Single-pass workflow - web_bundle: false 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 6ca5e5dc..c9dbb1c7 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -3,6 +3,7 @@ ````xml The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml +Communicate all responses in {communication_language} This workflow assembles a Story Context XML for a single user story by extracting ACs, tasks, relevant docs/code, interfaces, constraints, and testing guidance to support implementation. Default execution mode: #yolo (non-interactive). Only ask if {{non_interactive}} == false. If auto-discovery fails, HALT and request 'story_path' or 'story_dir'. @@ -168,7 +169,7 @@ What would you like to do? - **{{date}}**: Completed story-context for Story {{story_id}} ({{story_title}}). Context file: {{default_output_file}}. Next: DEV agent should run dev-story to implement. ``` - **✅ Story Context Generated Successfully** + **✅ Story Context Generated Successfully, {user_name}!** **Story Details:** - Story ID: {{story_id}} @@ -189,7 +190,7 @@ Check status anytime with: `workflow-status` - **✅ Story Context Generated Successfully** + **✅ Story Context Generated Successfully, {user_name}!** **Story Details:** - Story ID: {{story_id}} 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 f45b4154..b5cb838d 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml @@ -33,26 +33,4 @@ default_output_file: "{story_dir}/story-context-{{epic_id}}.{{story_id}}.xml" recommended_inputs: - story_markdown: "Path to a story markdown file to build context for" -# Required tools -required_tools: - - list_files - - file_info - - read_file - - write_file - - create_directory - - glob - - search_repo - - parse_markdown - -tags: - - context - - story - - planning - - bmad-v6 - -execution_hints: - interactive: false - autonomous: true - iterative: true - web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md b/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md index d73bbc0e..337f3332 100644 --- a/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md @@ -1,5 +1,9 @@ # Story Ready Workflow Instructions (SM Agent) +The workflow execution engine is governed by: {project_root}/bmad/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 SM agent AFTER user reviews a drafted story and confirms it's ready for development @@ -128,7 +132,7 @@ If BACKLOG had 1 story and is now empty: Display summary -**Story Marked Ready for Development!** +**Story Marked Ready for Development, {user_name}!** ✅ Story file updated: `{{todo_story_file}}` → Status: Ready ✅ Status file updated: Story moved TODO → IN PROGRESS 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 ac85bb04..87bac3f2 100644 --- a/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml @@ -23,19 +23,4 @@ variables: # Output configuration - no output file, just status updates default_output_file: "" -required_tools: - - read_file - - edit_file - -tags: - - story-management - - status-update - - sm-agent - - bmad-v6 - -execution_hints: - interactive: false # Minimal prompts; quick status update - autonomous: true # Proceed without user input - iterative: false # Single-pass workflow - web_bundle: false diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md index 0b25ef82..ca8cbba9 100644 --- a/src/modules/bmm/workflows/README.md +++ b/src/modules/bmm/workflows/README.md @@ -25,23 +25,23 @@ The BMM (BMAD Method Module) orchestrates software development through four dist ├──────────────────────────────────────────────────────────────┤ │ brainstorm-game ──┐ │ │ brainstorm-project ├──→ research ──→ product-brief ──┐ │ -│ game-brief ────────┘ │ │ +│ game-brief ────────┘ game-brief ┘ │ └────────────────────────────────────────────────────────┼─────┘ ↓ ┌──────────────────────────────────────────────────────────────┐ │ PHASE 2: PLANNING │ -│ (Scale-Adaptive Router) │ +│ (Scale-Adaptive Router - by type) │ ├──────────────────────────────────────────────────────────────┤ -│ plan-project │ -│ ├──→ Level 0: tech-spec only │ -│ ├──→ Level 1-2: PRD + tech-spec │ -│ ├──→ Level 3-4: PRD + Epics ──────┐ │ -│ └──→ Game: GDD │ │ -└───────────────────────────────────────────────────────────┼──┘ - ↓ +│ SOFTWARE: plan-project GAMES: gdd │ +│ ├──→ Level 0: tech-spec only ├──→ GDD (all levels) │ +│ ├──→ Level 1: tech-spec only └──→ Narrative design │ +│ ├──→ Level 2: PRD + tech-spec │ +│ └──→ Level 3-4: PRD + Epics ────────────────────────┐ │ +└──────────────────────────────────────────────────────────┼───┘ + ↓ ┌──────────────────────────────────────────────────────────────┐ │ PHASE 3: SOLUTIONING │ -│ (Levels 3-4 Only) │ +│ (Software Levels 3-4 / Complex Games) │ ├──────────────────────────────────────────────────────────────┤ │ 3-solutioning ──→ solution-architecture.md │ │ ↓ │ @@ -124,13 +124,13 @@ The central orchestrator that determines project scale and generates appropriate ### Scale Levels -| Level | Scope | Outputs | Next Phase | -| ----- | ------------------------ | ------------------------------ | ---------------- | -| **0** | Single atomic change | tech-spec + 1 story | → Implementation | -| **1** | 1-10 stories, 1 epic | tech-spec + epic + 2-3 stories | → Implementation | -| **2** | 5-15 stories, 1-2 epics | Focused PRD + tech-spec | → Implementation | -| **3** | 12-40 stories, 2-5 epics | Full PRD + Epics list | → Solutioning | -| **4** | 40+ stories, 5+ epics | Enterprise PRD + Epics | → Solutioning | +| Level | Scope | Outputs | Next Phase | +| ----- | ------------------------ | ------------------------------ | ------------------------------ | +| **0** | Single atomic change | tech-spec + 1 story | → Implementation | +| **1** | 1-10 stories, 1 epic | tech-spec + epic + 2-3 stories | → Implementation | +| **2** | 5-15 stories, 1-2 epics | PRD + epics | → Tech-spec → Implementation | +| **3** | 12-40 stories, 2-5 epics | PRD + epics | → Solutioning → Implementation | +| **4** | 40+ stories, 5+ epics | PRD + epics | → Solutioning → Implementation | **Key Changes (v6a):** @@ -140,20 +140,49 @@ The central orchestrator that determines project scale and generates appropriate ### Routing Logic +**Universal Entry Point** (workflow-status): + ``` -plan-project - ├─→ Detect project type (game/web/mobile/backend/etc) +workflow-status + ├─→ Check for existing status file + │ ├─→ If exists: Display status + recommend next action + │ └─→ If not exists: Guide workflow planning + ├─→ Determine project context (greenfield/brownfield) + ├─→ Determine project type (game/web/mobile/backend/etc) ├─→ Assess complexity → assign Level 0-4 - ├─→ Check context (greenfield/brownfield) - │ └─→ If brownfield & undocumented: - │ └─→ HALT: "Generate brownfield documentation first" - │ └─→ (TBD workflow for codebase analysis) - ├─→ Route to appropriate sub-workflow: - │ ├─→ Game → GDD workflow - │ ├─→ Level 0 → tech-spec workflow - │ ├─→ Level 1-2 → PRD + embedded tech-spec - │ └─→ Level 3-4 → PRD + epics → Solutioning - └─→ Generate bmm-workflow-status.md (tracking doc) + ├─→ Map complete workflow journey + └─→ Generate bmm-workflow-status.md + direct to first workflow +``` + +**Direct Routing** (no intermediate routers): + +``` +workflow-status determines routing: + + SOFTWARE PROJECTS: + ├─→ Level 0-1 → bmad architect tech-spec + │ └─→ Validates status file + level + │ └─→ Generates tech-spec.md + stories + │ └─→ Direct to Phase 4 (implementation) + │ + ├─→ Level 2 → bmad pm prd + │ └─→ Validates status file + level + │ └─→ Generates PRD.md + epics.md + │ └─→ Then: bmad architect tech-spec (lightweight solutioning) + │ └─→ Then: Phase 4 (implementation) + │ + └─→ Level 3-4 → bmad pm prd + └─→ Validates status file + level + └─→ Generates PRD.md + epics.md + └─→ Then: Phase 3 (solution-architecture) + └─→ Then: Phase 4 (implementation) + + GAME PROJECTS: + └─→ All Levels → bmad pm gdd + └─→ Validates status file + project type + └─→ Generates GDD.md + epics.md + └─→ Optional: narrative design + └─→ Then: Phase 3 or 4 (based on complexity) ``` ### Key Outputs @@ -381,7 +410,8 @@ plan-project (Phase 2) - **Phase 2**: - Level 0: tech-spec.md + story-{slug}.md - Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files - - Level 2-4: PRD.md, Epics.md, or tech-spec.md based on level + - Level 2: PRD.md + epics.md (then tech-spec.md in Phase 3) + - Level 3-4: PRD.md + epics.md (then solution-architecture.md in Phase 3) - **Phase 3**: solution-architecture.md, epic-specific tech specs - **Phase 4**: Story files, context XMLs, implemented code @@ -440,7 +470,9 @@ bmad analyst research bmad analyst product-brief # Phase 2: Planning -bmad pm plan-project +bmad pm prd # Level 2-4 software projects +bmad architect tech-spec # Level 0-1 software projects +bmad pm gdd # Game projects # Phase 3: Solutioning (L3-4) bmad architect solution-architecture diff --git a/src/modules/cis/workflows/design-thinking/workflow.yaml b/src/modules/cis/workflows/design-thinking/workflow.yaml index af66de8d..03f5335d 100644 --- a/src/modules/cis/workflows/design-thinking/workflow.yaml +++ b/src/modules/cis/workflows/design-thinking/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/bmad/cis/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional inputs for context @@ -34,8 +35,6 @@ web_bundle: author: "BMad" instructions: "bmad/cis/workflows/design-thinking/instructions.md" template: "bmad/cis/workflows/design-thinking/template.md" - design_methods: "bmad/cis/workflows/design-thinking/design-methods.csv" - use_advanced_elicitation: true web_bundle_files: - "bmad/cis/workflows/design-thinking/instructions.md" - "bmad/cis/workflows/design-thinking/template.md" diff --git a/src/modules/cis/workflows/innovation-strategy/workflow.yaml b/src/modules/cis/workflows/innovation-strategy/workflow.yaml index fa9b06ec..e711988e 100644 --- a/src/modules/cis/workflows/innovation-strategy/workflow.yaml +++ b/src/modules/cis/workflows/innovation-strategy/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/bmad/cis/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional inputs for context @@ -34,8 +35,6 @@ web_bundle: author: "BMad" instructions: "bmad/cis/workflows/innovation-strategy/instructions.md" template: "bmad/cis/workflows/innovation-strategy/template.md" - innovation_frameworks: "bmad/cis/workflows/innovation-strategy/innovation-frameworks.csv" - use_advanced_elicitation: true web_bundle_files: - "bmad/cis/workflows/innovation-strategy/instructions.md" - "bmad/cis/workflows/innovation-strategy/template.md" diff --git a/src/modules/cis/workflows/problem-solving/workflow.yaml b/src/modules/cis/workflows/problem-solving/workflow.yaml index 51980256..3c708593 100644 --- a/src/modules/cis/workflows/problem-solving/workflow.yaml +++ b/src/modules/cis/workflows/problem-solving/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/bmad/cis/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional inputs for context @@ -34,8 +35,6 @@ web_bundle: author: "BMad" instructions: "bmad/cis/workflows/problem-solving/instructions.md" template: "bmad/cis/workflows/problem-solving/template.md" - solving_methods: "bmad/cis/workflows/problem-solving/solving-methods.csv" - use_advanced_elicitation: true web_bundle_files: - "bmad/cis/workflows/problem-solving/instructions.md" - "bmad/cis/workflows/problem-solving/template.md" diff --git a/src/modules/cis/workflows/storytelling/instructions.md b/src/modules/cis/workflows/storytelling/instructions.md index 28aea0d1..066a451c 100644 --- a/src/modules/cis/workflows/storytelling/instructions.md +++ b/src/modules/cis/workflows/storytelling/instructions.md @@ -5,6 +5,7 @@ The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/storytelling/workflow.yaml +Communicate all responses in {communication_language} @@ -249,10 +250,11 @@ Polish and plan forward: What parts of the story feel strongest? What areas could use more refinement? +What's the key resolution or call to action for your story? Do you need additional story versions for other audiences/purposes? How will you test this story with your audience? -refinement_opportunities, additional_versions, feedback_plan +resolution, refinement_opportunities, additional_versions, feedback_plan @@ -266,6 +268,9 @@ Compile all story components into the structured template: 4. Verify tone and voice consistency 5. Fill all template placeholders with actual content +Write final story document to {output_folder}/story-{{date}}.md +Confirm completion with: "Story complete, {user_name}! Your narrative has been saved to {output_folder}/story-{{date}}.md" + agent_role, agent_name, user_name, date diff --git a/src/modules/cis/workflows/storytelling/workflow.yaml b/src/modules/cis/workflows/storytelling/workflow.yaml index c3e3d96f..533b4034 100644 --- a/src/modules/cis/workflows/storytelling/workflow.yaml +++ b/src/modules/cis/workflows/storytelling/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/bmad/cis/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" date: system-generated # Optional inputs for context @@ -34,9 +35,7 @@ web_bundle: author: "BMad" instructions: "bmad/cis/workflows/storytelling/instructions.md" template: "bmad/cis/workflows/storytelling/template.md" - story_frameworks: "bmad/cis/workflows/storytelling/story-types.csv" - use_advanced_elicitation: true web_bundle_files: - "bmad/cis/workflows/storytelling/instructions.md" - "bmad/cis/workflows/storytelling/template.md" - - "bmad/cis/workflows/storytelling/story-frameworks.csv" + - "bmad/cis/workflows/storytelling/story-types.csv" diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index 50dc43a4..05d40d6d 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -244,12 +244,12 @@ class BaseIdeSetup { processed = this.xmlHandler.injectActivationSimple(processed, metadata); } - // Use the actual project directory path if provided, otherwise default to 'bmad' + // Only replace {project-root} if a specific projectDir is provided + // Otherwise leave the placeholder intact // Note: Don't add trailing slash - paths in source include leading slash - const projectRoot = projectDir || 'bmad'; - - // Common replacements (including in the activation block) - processed = processed.replaceAll('{project-root}', projectRoot); + if (projectDir) { + processed = processed.replaceAll('{project-root}', projectDir); + } processed = processed.replaceAll('{module}', metadata.module || 'core'); processed = processed.replaceAll('{agent}', metadata.name || ''); processed = processed.replaceAll('{task}', metadata.name || ''); diff --git a/tools/cli/installers/lib/ide/claude-code.js b/tools/cli/installers/lib/ide/claude-code.js index c9de87bc..97a16154 100644 --- a/tools/cli/installers/lib/ide/claude-code.js +++ b/tools/cli/installers/lib/ide/claude-code.js @@ -186,11 +186,11 @@ class ClaudeCodeSetup extends BaseIdeSetup { } /** - * Override processContent to use the actual project directory path + * Override processContent to keep {project-root} placeholder */ processContent(content, metadata = {}) { - // Use the base class method with the actual project directory - return super.processContent(content, metadata, this.projectDir); + // Use the base class method WITHOUT projectDir to preserve {project-root} placeholder + return super.processContent(content, metadata); } /** diff --git a/workflow-cleanup-progress.md b/workflow-cleanup-progress.md new file mode 100644 index 00000000..e740470d --- /dev/null +++ b/workflow-cleanup-progress.md @@ -0,0 +1,451 @@ +# Workflow Cleanup Progress Tracker + +**Started:** 2025-10-15 +**Goal:** Standardize all BMM/BMB/CIS workflows with proper config variables, yaml/instruction alignment, and web_bundle validation + +--- + +## Scope + +- **Total Workflows:** 42 + - BMM: 30 workflows + - BMB: 8 workflows + - CIS: 4 workflows +- **Excluded:** testarch/\* workflows + +--- + +## Phase 1: Fix BMB Documentation (Foundation) + +### Files to Update: + +- [ ] `/src/modules/bmb/workflows/create-workflow/instructions.md` +- [ ] `/src/modules/bmb/workflows/edit-workflow/instructions.md` +- [ ] `/src/modules/bmb/workflows/convert-legacy/instructions.md` + +### Standards Being Enforced: + +1. Standard config block in all workflows +2. Instructions must use config variables +3. Templates must use config variables +4. Yaml variables must be used (instructions OR templates) +5. Web_bundle must include all dependencies + +### Progress: + +- Status: ✅ COMPLETE +- Files Updated: 3/3 + +### Completed: + +- ✅ **create-workflow/instructions.md** - Added: + - Standard config block enforcement in Step 4 + - Config variable usage guidance in Step 5 (instructions) + - Standard metadata in templates in Step 6 + - YAML/instruction/template alignment validation in Step 9 + - Enhanced web_bundle dependency scanning in Step 9b (workflow calls) + +- ✅ **edit-workflow/instructions.md** - Added: + - Standard config audit in Step 2 (analyze best practices) + - New menu option 2: "Add/fix standard config" + - New menu option 9: "Remove bloat" + - Standard config handler in Step 4 with template + - Bloat removal handler in Step 4 (cross-reference check) + - Enhanced web bundle scanning (workflow dependencies) + - Complete standard config validation checklist in Step 6 + - YAML/file alignment validation in Step 6 + +- ✅ **convert-legacy/instructions.md** - Added: + - Standard config block documentation in Step 5c (Template conversion) + - Standard config block documentation in Step 5e (Task conversion) + - Post-conversion verification steps for config variables + - Standard config validation checklist in Step 6 + - Instructions update reminder (use config variables) + +--- + +## Phase 2: Global Config Variable Sweep + +### Standard Config Block: + +```yaml +# Critical variables from config +config_source: '{project-root}/bmad/[module]/config.yaml' +output_folder: '{config_source}:output_folder' +user_name: '{config_source}:user_name' +communication_language: '{config_source}:communication_language' +date: system-generated +``` + +### Rules: + +- Add to existing config section (don't duplicate) +- Only add missing variables +- Skip testarch/\* workflows + +### Progress: + +- Status: ✅ COMPLETE +- Workflows Updated: 34/34 (excluded 8 testarch workflows) +- Added `communication_language` to all workflows missing it +- Standardized comment: "Critical variables from config" + +--- + +## Phase 3: Workflow-by-Workflow Deep Clean + +### Per-Workflow Checklist: + +1. Read workflow.yaml + instructions.md + template.md (if exists) +2. Variable audit (yaml ↔ instructions ↔ templates) +3. Standard config usage validation +4. Bloat removal (unused fields, duplicates) +5. Web_bundle validation (all dependencies included) + +### Progress: + +- Status: ⚙️ IN PROGRESS +- Workflows Completed: 26/35 (74%) + +### Completed Workflows: + +See detailed completion logs below for: + +- **CIS Module:** 4/4 workflows (100%) +- **BMM 1-analysis:** 7/7 workflows (100%) - including metadata bloat cleanup +- **BMM 2-plan-workflows:** 5/5 workflows (100%) - including GDD intent-based transformation +- **BMM 3-solutioning:** 2/2 workflows (100%) - metadata bloat cleanup + critical headers +- **BMM 4-implementation:** 8/8 workflows (100%) - metadata bloat cleanup + critical headers + +### Remaining Work: + +- **BMB:** 0/8 workflows (0%) + +--- + +## Issues/Notes Log + +### 2025-10-16: Created audit-workflow + +- **Location:** `/bmad/bmb/workflows/audit-workflow/` +- **Purpose:** Codifies all Phase 1 and Phase 2 standards into a reusable validation tool +- **Files Created:** + - `workflow.yaml` - Configuration with standard config block + - `instructions.md` - 8-step audit process + - `checklist.md` - 70-point validation checklist +- **Validation:** audit-workflow passes 100% of its own validation criteria +- **Next Use:** Will be used to perform Phase 3 systematic audits + +**Audit-Workflow Capabilities:** + +1. Standard config block validation +2. YAML/instruction/template alignment analysis +3. Config variable usage audit +4. Web bundle completeness validation +5. Bloat detection (unused yaml fields) +6. Template variable mapping verification +7. Comprehensive audit report generation +8. Integration with edit-workflow for fixes + +### 2025-10-16: Added Instruction Style Philosophy to create-workflow + +- **Enhancement:** Added comprehensive guidance on intent-based vs prescriptive instruction patterns +- **Location:** `/src/modules/bmb/workflows/create-workflow/instructions.md` Step 5 +- **Changes:** + - Added instruction style choice in Step 3 (intent-based vs prescriptive) + - Added 100+ line section in Step 5 with examples and best practices + - Documented when to use each style and how to mix both effectively + - Provided clear "good" and "bad" examples for each pattern + - Emphasized goal-oriented collaboration over rigid prescriptive wording + +**Key Philosophy Shift:** + +- **Intent-Based (Recommended):** Guide LLM with goals and principles, let it adapt conversations naturally + - Better for complex discovery, creative work, iterative refinement + - Example: `Guide user to define their target audience with specific demographics and needs` + +- **Prescriptive (Selective Use):** Provide exact wording for questions and options + - Better for simple data collection, compliance, binary choices + - Example: `What is your target platform? Choose: PC, Console, Mobile, Web` + +**Impact:** Future workflows will be more conversational and adaptive, improving human-AI collaboration quality + +### 2025-10-16: Transformed game-brief to Intent-Based Style + +- **Transformation:** Converted game-brief from prescriptive to intent-based instructions +- **Location:** `/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md` +- **Results:** + - **Before:** 617 lines (heavily prescriptive with hardcoded question templates) + - **After:** 370 lines (intent-based with goal-oriented guidance) + - **Reduction:** 247 lines removed (40% reduction) + +**Changes Made:** + +- Step 1: Converted hardcoded "What is the working title?" to intent-based "Ask for the working title" +- Step 1b: Transformed 7 prescriptive bullet points to 5 action-based guidance lines +- Steps 3-12 (Interactive Mode): Replaced massive blocks with compact guidance + - Step 4 (Target Market): 31 lines → 8 lines + - Step 5 (Game Fundamentals): 33 lines → 10 lines + - Step 6 (Scope/Constraints): 47 lines → 11 lines + - Step 7 (Reference Framework): 33 lines → 8 lines + - Step 8 (Content Framework): 32 lines → 9 lines + - Step 9 (Art/Audio): 32 lines → 8 lines + - Step 10 (Risks): 38 lines → 9 lines + - Step 11 (Success): 37 lines → 9 lines + - Step 12 (Next Steps): 35 lines → 9 lines + +**Pattern Applied:** + +- **Old (Prescriptive):** `Who will play your game? **Primary Audience:** - Age range - Gaming experience level...` +- **New (Intent-Based):** `Guide user to define their primary target audience with specific demographics, gaming preferences, and behavioral characteristics` + +**Benefits:** + +- More conversational and adaptive LLM behavior +- Cleaner, more maintainable instructions +- Better human-AI collaboration +- LLM can adapt questions to user context naturally +- Demonstrates the philosophy shift documented in create-workflow + +**This serves as the reference implementation for converting prescriptive workflows to intent-based style.** + +### 2025-10-16: Completed ALL 2-plan-workflows (5/5 - 100%) + +**✅ Phase 2-Plan-Workflows Module Complete!** + +All 5 workflows in the 2-plan-workflows folder have been audited, cleaned, and optimized: + +1. ✅ **gdd** - YAML CLEANUP + CRITICAL HEADERS + INTENT-BASED TRANSFORMATION + - Removed claude_code_enhancements bloat + - Removed duplicate frameworks section + - Removed duplicate workflow configuration (interactive/autonomous/allow_parallel) + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + - **Intent-based transformation:** Converted Steps 2-5, 7-11, 13-15 from prescriptive to intent-based + - **Preserved Step 6:** Game-type CSV lookup and fragment injection (critical functionality) + - **Added USPs:** Step 3 now captures unique_selling_points for template + - **Result:** More conversational, adaptive workflow while maintaining game-type integration + +2. ✅ **narrative** - YAML CLEANUP + CRITICAL HEADERS + - Removed duplicate frameworks section + - Removed duplicate workflow configuration + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +3. ✅ **prd** - CLEAN YAML + CRITICAL HEADERS + - YAML was already clean (no bloat) + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +4. ✅ **tech-spec** - YAML CLEANUP + CRITICAL HEADERS + - Removed claude_code_enhancements bloat + - Removed duplicate frameworks section + - Removed duplicate workflow configuration + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +5. ✅ **ux** - YAML CLEANUP + CRITICAL HEADERS + - Removed claude_code_enhancements bloat + - Removed duplicate frameworks section + - Removed duplicate workflow configuration + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +**Common Bloat Pattern Removed:** + +- `claude_code_enhancements` sections (4 workflows) +- Duplicate `frameworks` lists in top-level and web_bundle (4 workflows) +- Duplicate `interactive/autonomous/allow_parallel` config (4 workflows) + +**Standard Additions Applied:** + +- {communication_language} critical header in all instruction files +- {user_name} personalization in all completion messages +- All workflows now follow standard config usage pattern + +--- + +### 2025-10-16: Completed ALL 1-analysis Workflows (7/7 - 100%) + +**✅ Phase 1-Analysis Module Complete!** + +All 7 workflows in the 1-analysis folder have been audited, cleaned, and optimized: + +1. ✅ **brainstorm-game** - FULL AUDIT (earlier session) + - Removed use_advanced_elicitation bloat + - Restored critical existing_workflows + - Added {communication_language} and {user_name} + +2. ✅ **brainstorm-project** - FULL AUDIT (earlier session) + - Removed use_advanced_elicitation bloat + - Restored critical existing_workflows + - Added {communication_language} and {user_name} + +3. ✅ **game-brief** - INTENT-BASED TRANSFORMATION + - **Before:** 617 lines → **After:** 370 lines (40% reduction) + - Removed brief_format bloat + - Transformed all prescriptive steps to intent-based + - Added executive summary option + - Added {communication_language} and {user_name} + +4. ✅ **product-brief** - INTENT-BASED TRANSFORMATION + - **Before:** 444 lines → **After:** 332 lines (25% reduction) + - Removed brief_format bloat + - Transformed steps 3-12 to intent-based guidance + - Added executive summary option + - Added {communication_language} and {user_name} + +5. ✅ **research** - ROUTER CLEANUP + - **YAML Before:** 245 lines → **After:** 46 lines (81% reduction!) + - Removed massive bloat: research_types, frameworks, data_sources, claude_code_enhancements (duplicated in web_bundle) + - Added {communication_language} to router + - Router appropriately deterministic for type selection + +6. ✅ **document-project** - ROUTER CLEANUP + - **YAML:** Removed runtime_variables, scan_levels, resumability bloat (documentation, not config) + - Added {communication_language} + - Added {user_name} personalization + - Router appropriately deterministic for mode selection + +7. ✅ **workflow-status** - DETERMINISTIC VALIDATION + - **YAML:** Removed unused variables bloat (status_file_pattern, check_existing_status, display_menu, suggest_next_action) + - Added missing critical headers + - Added {user_name} personalization + - Appropriately deterministic/structured (this is a menu/orchestration workflow) + +**Instruction Style Decisions Applied:** + +- **Intent-Based:** game-brief, product-brief (conversational, adaptive) +- **Deterministic/Prescriptive:** workflow-status (menu/orchestration) +- **Router Pattern:** document-project, research (appropriate for delegation workflows) + +**Total Lines Saved:** + +- game-brief: 247 lines +- product-brief: 112 lines +- research YAML: 199 lines +- document-project YAML: ~100 lines +- workflow-status YAML: ~10 lines +- **Total:** ~668 lines removed across 1-analysis workflows + +--- + +### 2025-10-16: Completed ALL 3-solutioning Workflows (2/2 - 100%) + +**✅ Phase 3-Solutioning Module Complete!** + +All 2 workflows in the 3-solutioning folder have been audited and cleaned: + +1. ✅ **solution-architecture** (main workflow) - DETERMINISTIC VALIDATION + - **YAML:** Already clean - no metadata bloat found + - Added {communication_language} critical header + - Added {user_name} personalization in completion message (Step 11) + - **Appropriately deterministic:** Router/orchestration workflow with validation gates + - **Not transformed to intent-based:** This is a systematic architecture generation workflow with specific quality gates (cohesion check, template loading, validation checklists) + +2. ✅ **tech-spec** (subfolder) - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization in completion message (Step 10) + - **Appropriately deterministic:** JIT workflow with #yolo (non-interactive) execution mode + +**Metadata Bloat Removed:** + +- `required_tools` (9 items: list_files, file_info, read_file, write_file, search_repo, glob, parse_markdown) +- `tags` (4 items: tech-spec, architecture, planning, bmad-v6) +- `execution_hints` (interactive/autonomous/iterative flags) + +**Standard Additions Applied:** + +- {communication_language} critical header in both instruction files +- {user_name} personalization in all completion messages +- Both workflows now follow standard config usage pattern + +**Instruction Style Decision:** + +- **Deterministic/Prescriptive:** Both workflows appropriately remain deterministic + - solution-architecture: Complex router with quality gates, template selection, validation checklists + - tech-spec: Non-interactive #yolo mode workflow with structured spec generation +- **Rationale:** These are systematic, validation-heavy workflows, not conversational discovery workflows + +--- + +### 2025-10-16: Completed ALL 4-implementation Workflows (8/8 - 100%) + +**✅ Phase 4-Implementation Module Complete!** + +All 8 workflows in the 4-implementation folder have been audited and cleaned: + +1. ✅ **correct-course** - CRITICAL HEADERS + - **YAML:** Already clean - no metadata bloat + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +2. ✅ **create-story** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization in completion messages (2 locations) + +3. ✅ **dev-story** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization in completion messages (2 locations) + +4. ✅ **retrospective** - CRITICAL HEADERS + - **YAML:** Already clean - no metadata bloat + - Added {communication_language} critical header + - Added {user_name} personalization in completion message + +5. ✅ **review-story** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization (to be added to instructions) + +6. ✅ **story-approved** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization (to be added to instructions) + +7. ✅ **story-context** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization (to be added to instructions) + +8. ✅ **story-ready** - METADATA BLOAT CLEANUP + - **YAML:** Removed metadata bloat (required_tools, tags, execution_hints) + - Added {communication_language} critical header + - Added {user_name} personalization (to be added to instructions) + +**Metadata Bloat Removed:** + +- `required_tools` sections (6 workflows) +- `tags` sections (6 workflows) +- `execution_hints` sections (6 workflows) + +**Standard Additions Applied:** + +- {communication_language} critical header in all 8 instruction files +- {user_name} personalization in completion messages (first 4 completed, last 4 YAMLs cleaned) +- All workflows now follow standard config usage pattern + +**Instruction Style Decision:** + +- **Deterministic/Prescriptive:** All 4-implementation workflows appropriately remain deterministic +- **Rationale:** These are execution workflows with specific status updates, file modifications, and workflow state management - not conversational discovery workflows + +--- + +## Summary Statistics + +**Phase 1:** ✅ 3/3 files updated (100%) +**Phase 2:** ✅ 34/34 workflows updated (100%) +**Phase 3:** ⚙️ 26/35 workflows cleaned (74%) + +- CIS: 4/4 (100%) +- BMM 1-analysis: 7/7 (100%) +- BMM 2-plan-workflows: 5/5 (100%) +- BMM 3-solutioning: 2/2 (100%) +- BMM 4-implementation: 8/8 (100%) +- BMB: 0/8 (0%) + +**Overall Progress:** 91% complete (Phase 1 + Phase 2 + 74% of Phase 3)