diff --git a/src/core/tasks/workflow.xml b/src/core/tasks/workflow.xml index 00e73435..76e0c81d 100644 --- a/src/core/tasks/workflow.xml +++ b/src/core/tasks/workflow.xml @@ -59,7 +59,7 @@ Replace {{variables}} with values (ask user if unknown) action xml tag → Perform the action - check xml tag → Evaluate condition + check if="condition" xml tag → Conditional block wrapping actions (requires closing </check>) ask xml tag → Prompt user and WAIT for response invoke-workflow xml tag → Execute another workflow with given inputs invoke-task xml tag → Execute specified task @@ -114,7 +114,8 @@ action - Required action to perform - check - Condition to evaluate + action if="condition" - Single conditional action (inline, no closing tag needed) + check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required) ask - Get user input (wait for response) goto - Jump to another step invoke-workflow - Call another workflow @@ -128,6 +129,35 @@ + + + One action with a condition + <action if="condition">Do something</action> + <action if="file exists">Load the file</action> + Cleaner and more concise for single items + + + + Multiple actions/tags under same condition + <check if="condition"> + <action>First action</action> + <action>Second action</action> +</check> + <check if="validation fails"> + <action>Log error</action> + <goto step="1">Retry</goto> +</check> + Explicit scope boundaries prevent ambiguity + + + + Else/alternative branches + <check if="condition A">...</check> +<check if="else">...</check> + Clear branching logic with explicit blocks + + + This is the complete workflow execution engine You MUST Follow instructions exactly as written and maintain conversation context between steps diff --git a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md index c68528e3..7e1391a9 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md +++ b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md @@ -186,8 +186,9 @@ Write 1-3 bullet points about project success: ```xml Load validation criteria - If validation fails: - Return to previous step + + Return to previous step + validated_data ``` @@ -257,26 +258,47 @@ _Generated on {{date}}_ ``` -### Branching and Goto +### Conditional Execution + +**Single Action (use `action if=""`):** + +```xml + + Load existing document + Initialize from template + +``` + +**Multiple Actions (use `...`):** ```xml Check requirements - If incomplete: - Return to gathering - If complete: - Proceed + + Log validation errors + Return to gathering + + + Mark as validated + Proceed + ``` +**When to use which:** + +- **``** - Single conditional action (cleaner, more concise) +- **`...`** - Multiple items under same condition (explicit scope) + ### Loops ```xml Generate solution - If criteria met: - Exit loop + + Exit loop + ``` @@ -286,7 +308,8 @@ _Generated on {{date}}_ **Execution:** - `` - Required action -- `` - Conditional check +- `` - Single conditional action (inline) +- `...` - Conditional block for multiple items (requires closing tag) - `` - User prompt - `` - Jump to step - `` - Call another workflow @@ -370,8 +393,9 @@ Check requirements against goals. Run tests - If tests fail: - Fix issues + + Fix issues + ``` @@ -414,6 +438,40 @@ Check requirements against goals. 3. **Set limits** - "3-5 items maximum" 4. **Explain why** - Context helps AI make better decisions +### Conditional Execution Best Practices + +**✅ DO:** + +- Use `` for single conditional actions +- Use `...` for blocks with multiple items +- Always close `` tags explicitly +- Keep conditions simple and readable + +**❌ DON'T:** + +- Wrap single actions in `` blocks (unnecessarily verbose) +- Forget to close `` tags +- Nest too many levels (makes logic hard to follow) + +**Examples:** + +```xml + +Load configuration + + + + Load configuration + + + + + Log error details + Notify user + Retry input + +``` + ### Common Pitfalls - **Missing critical headers** - Always include workflow engine references @@ -421,6 +479,8 @@ Check requirements against goals. - **Too many steps** - Combine related actions - **No checkpoints** - Add `` tags - **Vague instructions** - Be explicit about expectations +- **Unclosed check tags** - Always close `...` blocks +- **Wrong conditional pattern** - Use `` for single items, `` for blocks ## Web Bundles diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md index fedbc6e6..4ed5e3e9 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md @@ -251,35 +251,38 @@ Examples: - [r] Refine with additional context - [o] Optimize for different platform -If edit or refine: -What would you like to adjust? -Regenerate with modifications + + What would you like to adjust? + Regenerate with modifications + Provide platform-specific usage tips based on target platform -If target_platform includes ChatGPT: -**ChatGPT Deep Research Tips:** + + **ChatGPT Deep Research Tips:** - Use clear verbs: "compare," "analyze," "synthesize," "recommend" - Specify keywords explicitly to guide search - Answer clarifying questions thoroughly (requests are more expensive) - You have 25-250 queries/month depending on tier - Review the research plan before it starts searching + -If target_platform includes Gemini: -**Gemini Deep Research Tips:** + + **Gemini Deep Research Tips:** - Keep initial prompt simple - you can adjust the research plan - Be specific and clear - vagueness is the enemy - Review and modify the multi-point research plan before it runs - Use follow-up questions to drill deeper or add sections - Available in 45+ languages globally + -If target_platform includes Grok: -**Grok DeepSearch Tips:** + + **Grok DeepSearch Tips:** - Include date windows: "from Jan-Jun 2025" - Specify output format: "bullet list + citations" @@ -287,15 +290,17 @@ Examples: - Use follow-up commands: "Expand on [topic]" to deepen sections - Verify facts when obscure sources cited - Free tier: 5 queries/24hrs, Premium: 30/2hrs + -If target_platform includes Claude: -**Claude Projects Tips:** + + **Claude Projects Tips:** - Use Chain of Thought prompting for complex reasoning - Break into sub-prompts for multi-step research (prompt chaining) - Add relevant documents to Project for context - Provide explicit instructions and examples - Test iteratively and refine prompts + platform_tips @@ -359,11 +364,13 @@ The output includes: Select option (1-4): -If option 1: -Start with different platform selection + + Start with different platform selection + -If option 2 or 3: -Start new prompt with context from previous + + Start new prompt with context from previous + diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md index f71e2b0f..b7fe5dfe 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md @@ -471,8 +471,8 @@ Provide mitigation strategies. Would you like to create a financial model with revenue projections based on the market analysis? -If yes: -Build 3-year projections: + + Build 3-year projections: - Revenue model based on SOM scenarios - Customer acquisition projections @@ -481,6 +481,8 @@ Build 3-year projections: - Funding requirements financial_projections + + @@ -537,8 +539,8 @@ Create compelling executive summary with: Would you like to include detailed appendices with calculations, full competitor profiles, or raw research data? -If yes: -Create appendices with: + + Create appendices with: - Detailed TAM/SAM/SOM calculations - Full competitor profiles @@ -548,6 +550,8 @@ Create appendices with: - Glossary of terms appendices + + 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 e39a5af4..a7026474 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-router.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-router.md @@ -51,40 +51,49 @@ Present the user with research type options: Based on user selection, load the appropriate instruction set -If research_type == "1" OR "market" OR "market research": -Set research_mode = "market" -LOAD: {installed_path}/instructions-market.md -Continue with market research workflow + + Set research_mode = "market" + LOAD: {installed_path}/instructions-market.md + Continue with market research workflow + -If research_type == "2" OR "prompt" OR "deep research prompt": -Set research_mode = "deep-prompt" -LOAD: {installed_path}/instructions-deep-prompt.md -Continue with deep research prompt generation + + Set research_mode = "deep-prompt" + LOAD: {installed_path}/instructions-deep-prompt.md + Continue with deep research prompt generation + -If research_type == "3" OR "technical" OR "architecture": -Set research_mode = "technical" -LOAD: {installed_path}/instructions-technical.md -Continue with technical research workflow + + Set research_mode = "technical" + LOAD: {installed_path}/instructions-technical.md + Continue with technical research workflow -If research_type == "4" OR "competitive": -Set research_mode = "competitive" -This will use market research workflow with competitive focus -LOAD: {installed_path}/instructions-market.md -Pass mode="competitive" to focus on competitive intelligence + -If research_type == "5" OR "user": -Set research_mode = "user" -This will use market research workflow with user research focus -LOAD: {installed_path}/instructions-market.md -Pass mode="user" to focus on customer insights + + Set research_mode = "competitive" + This will use market research workflow with competitive focus + LOAD: {installed_path}/instructions-market.md + Pass mode="competitive" to focus on competitive intelligence -If research_type == "6" OR "domain" OR "industry": -Set research_mode = "domain" -This will use market research workflow with domain focus -LOAD: {installed_path}/instructions-market.md -Pass mode="domain" to focus on industry/domain analysis + -The loaded instruction set will continue from here with full context + + Set research_mode = "user" + This will use market research workflow with user research focus + LOAD: {installed_path}/instructions-market.md + Pass mode="user" to focus on customer insights + + + + + Set research_mode = "domain" + This will use market research workflow with domain focus + LOAD: {installed_path}/instructions-market.md + Pass mode="domain" to focus on industry/domain analysis + + +The loaded instruction set will continue from here with full context of the {research_type} diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md index edb08972..9ee1bc39 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md @@ -89,12 +89,11 @@ Consider: If you have specific options, list them. Otherwise, I'll research current leading solutions based on your requirements. -If user provides options: -user_provided_options +user_provided_options -If discovering options: -Conduct web research to identify current leading solutions -Search for: + + Conduct web research to identify current leading solutions + Search for: - "[technical_category] best tools 2025" - "[technical_category] comparison [use_case]" @@ -102,11 +101,13 @@ If you have specific options, list them. Otherwise, I'll research current leadin - "State of [technical_category] 2025" - + Present discovered options (typically 3-5 main candidates) technology_options + + @@ -283,7 +284,7 @@ For top 2-3 candidates: Are you researching architecture patterns (microservices, event-driven, etc.)? -If yes: + Research and document: @@ -308,6 +309,7 @@ Research and document: - Operational overhead architecture_pattern_analysis + @@ -433,9 +435,10 @@ Create ADR format documentation: Select option (1-5): -If option 4: -LOAD: {installed_path}/instructions-deep-prompt.md -Pre-populate with technical research context + + LOAD: {installed_path}/instructions-deep-prompt.md + Pre-populate with technical research context + diff --git a/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md b/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md index 49a90171..3df20407 100644 --- a/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md +++ b/src/modules/bmm/workflows/2-plan/gdd/instructions-gdd.md @@ -15,49 +15,48 @@ Load project-workflow-analysis.md Confirm project_type == "game" -If continuation_mode == true: -Load existing GDD.md and check completion status -Found existing work. Would you like to: + + Load existing GDD.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 + -1. Review what's done and continue -2. Modify existing sections -3. Start fresh - - If continuing, skip to first incomplete section +Check or existing game-brief in output_folder -If new or starting fresh: -Check `output_folder` for existing game docs. - -Check for existing game-brief in output_folder - -If game-brief exists: -Found existing game brief! Would you like to: + + Found existing game brief! Would you like to: 1. Use it as input (recommended - I'll extract key info) 2. Ignore it and start fresh + + -Your choice: + + Load and analyze game-brief document + Extract: game_name, core_concept, target_audience, platforms, game_pillars, primary_mechanics + Pre-fill relevant GDD sections with game-brief content + Note which sections were pre-filled from brief -If using game-brief: -Load and analyze game-brief document -Extract: game_name, core_concept, target_audience, platforms, game_pillars, primary_mechanics -Pre-fill relevant GDD sections with game-brief content -Note which sections were pre-filled from brief + -If no game-brief was loaded: -Describe your game in 1-2 sentences: - -What is it about? What does the player do? + + Describe your game. What is it about? What does the player do? What is the Genre or type? Analyze description to determine game type Map to closest game_types.csv id or use "custom" + -Else (game-brief was loaded): -Use game concept from brief to determine game type + + Use game concept from brief to determine game type -I've identified this as a **{{game_type}}** game. Is that correct? - -If not, briefly describe what type it should be: + + I've identified this as a **{{game_type}}** game. Is that correct? + If not, briefly describe what type it should be: + Map selection to game_types.csv id Load corresponding fragment file from game-types/ folder @@ -68,6 +67,7 @@ If not, briefly describe what type it should be: Get core game concept and vision. description + @@ -383,14 +383,16 @@ Your metrics: Check if game-type fragment contained narrative tags -If fragment had or : -Set needs_narrative = true -Extract narrative importance level from tag + + Set needs_narrative = true + Extract narrative importance level from tag ## Next Steps for {{game_name}} -If needs_narrative == true: -This game type ({{game_type}}) is **{{narrative_importance}}** for narrative. + + + + This game type ({{game_type}}) is **{{narrative_importance}}** for narrative. Your game would benefit from a Narrative Design Document to detail: @@ -408,10 +410,12 @@ Would you like to create a Narrative Design Document now? Your choice: -If user selects option 1: -LOAD: {installed_path}/narrative/instructions-narrative.md -Pass GDD context to narrative workflow -Exit current workflow (narrative will hand off to solutioning when done) + + + + {project-root}/bmad/bmm/workflows/2-plan/narrative/workflow.yaml + Pass GDD context to narrative workflow + Exit current workflow (narrative will hand off to solutioning when done) Since this is a Level {{project_level}} game project, you need solutioning for platform/engine architecture. @@ -476,7 +480,9 @@ Since this is a Level {{project_level}} game project, you need solutioning for p GDD Complete! Next immediate action: -If needs_narrative == true: + + + 1. Create Narrative Design Document (recommended for {{game_type}}) 2. Start solutioning workflow (engine/architecture) @@ -485,7 +491,9 @@ Since this is a Level {{project_level}} game project, you need solutioning for p 5. Review GDD with team/stakeholders 6. Exit workflow -Else: + + + 1. Start solutioning workflow (engine/architecture) 2. Create prototype build @@ -494,10 +502,12 @@ Since this is a Level {{project_level}} game project, you need solutioning for p 5. Exit workflow Which would you like to proceed with? + -If user selects narrative option: -LOAD: {installed_path}/narrative/instructions-narrative.md -Pass GDD context to narrative workflow + + {project-root}/bmad/bmm/workflows/2-plan/narrative/workflow.yaml + Pass GDD context to narrative workflow + diff --git a/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml b/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml new file mode 100644 index 00000000..dabcb8c4 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan/gdd/workflow.yaml @@ -0,0 +1,99 @@ +# 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 index b3ce46e7..c3f0f69f 100644 --- a/src/modules/bmm/workflows/2-plan/instructions-router.md +++ b/src/modules/bmm/workflows/2-plan/instructions-router.md @@ -10,9 +10,9 @@ Check if {output_folder}/project-workflow-analysis.md exists -If exists: -Load the analysis file -Check for existing workflow outputs based on level in analysis: + + Load the analysis file + Check for existing workflow outputs based on level in analysis: - Level 0: Check for tech-spec.md - Level 1-2: Check for PRD.md, epic-stories.md, tech-spec.md @@ -30,8 +30,11 @@ Options: 3. Review and modify previous analysis -If not exists or starting fresh: -Proceed to assessment + + + + Proceed to assessment + @@ -49,18 +52,21 @@ Options: Select an option or describe your needs: -If "UX/UI specification only": -LOAD: {installed_path}/ux/instructions-ux.md -Pass mode="standalone" to UX instructions -Skip remaining router steps +Capture user selection as {{planning_type}} -If "Generate AI Frontend Prompt": -Check for existing UX spec or PRD -{project-root}/bmad/bmm/tasks/ai-fe-prompt.md -Exit workflow after prompt generation + + {installed_path}/ux/workflow.yaml + Pass mode="standalone" to UX workflow + Exit router workflow (skip remaining steps) + -If "Tech spec only" or "Full project planning": -Continue to step 3 for project assessment + + Check for existing UX spec or PRD + {project-root}/bmad/bmm/tasks/ai-fe-prompt.md + Exit router workflow after prompt generation + + +Continue to step 3 for project assessment @@ -89,10 +95,11 @@ c. Working with messy/legacy code (needs refactoring) Detect if project_type == "game" -If project_type == "game": -Set workflow_type = "gdd" -Skip level classification (GDD workflow handles all game project levels) -Jump to step 5 for GDD-specific assessment + + Set workflow_type = "gdd" + Skip level classification (GDD workflow handles all game project levels) + Jump to step 5 for GDD-specific assessment + Else, based on their description, analyze and suggest scope level: @@ -174,48 +181,33 @@ Generate comprehensive analysis with all assessment data. Based on project type and level, load ONLY the needed instructions: -If workflow_type == "gdd" (Game projects): -LOAD: {installed_path}/gdd/instructions-gdd.md -If continuing: + + {installed_path}/gdd/workflow.yaml + GDD workflow handles all game project levels internally + -- Load existing GDD.md if present -- Check which sections are complete -- Resume from last completed section -- GDD workflow handles all game project levels internally + + {installed_path}/tech-spec/workflow.yaml + -If Level 0: -LOAD: {installed_path}/tech-spec/instructions-sm.md -If continuing: + + {installed_path}/prd/workflow.yaml + Pass level context to PRD workflow (loads instructions-med.md) + -- Load existing tech-spec.md -- Allow user to review and modify -- Complete any missing sections + + {installed_path}/prd/workflow.yaml + Pass level context to PRD workflow (loads instructions-lg.md) + -If Level 1-2: -LOAD: {installed_path}/prd/instructions-med.md -If continuing: - -- Load existing PRD.md if present -- Check which sections are complete -- Resume from last completed section -- If PRD done, show solutioning handoff instructions - -If Level 3-4: -LOAD: {installed_path}/prd/instructions-lg.md -If continuing: - -- Load existing PRD.md and epics.md -- Identify last completed step (check template variables) -- Resume from incomplete sections -- If all done, show architect handoff instructions - -Pass continuation context to loaded instruction set: +Pass continuation context to invoked workflow: - continuation_mode: true/false - last_completed_step: {{step_number}} - existing_documents: {{document_list}} +- project_level: {{level}} -The loaded instruction set should check continuation_mode and adjust accordingly +The invoked workflow's instruction set should check continuation_mode and adjust accordingly diff --git a/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md b/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md index 87e9fd9f..c12e2155 100644 --- a/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md +++ b/src/modules/bmm/workflows/2-plan/narrative/instructions-narrative.md @@ -7,6 +7,7 @@ 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 +Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO @@ -26,7 +27,7 @@ Your game type ({{game_type}}) suggests **{{suggested_complexity}}**. Confirm or Set narrative_complexity -If complexity == "Light": + 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 @@ -37,6 +38,8 @@ Your choice: Load narrative_template from workflow.yaml + + @@ -304,8 +307,8 @@ Your key conversations: key_conversations -If game has branching dialogue: -Describe your branching dialogue system. + + Describe your branching dialogue system. - How many branches/paths? - What determines branches? (stats, choices, flags) @@ -315,6 +318,7 @@ Your key conversations: Your branching system: branching_dialogue + @@ -397,8 +401,8 @@ Your optional content: optional_content -If multiple endings: -Describe your ending structure. + + Describe your ending structure. - How many endings? - What determines ending? (choices, stats, completion) @@ -408,6 +412,7 @@ Your optional content: Your endings: multiple_endings + diff --git a/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml b/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml new file mode 100644 index 00000000..06a508eb --- /dev/null +++ b/src/modules/bmm/workflows/2-plan/narrative/workflow.yaml @@ -0,0 +1,63 @@ +# 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/instructions-lg.md b/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md index 263d0f4b..d5b806e8 100644 --- a/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md +++ b/src/modules/bmm/workflows/2-plan/prd/instructions-lg.md @@ -15,18 +15,19 @@ Load project-workflow-analysis.md Confirm Level 3-4 - Full product or platform -If continuation_mode == true: -Load existing PRD.md and check completion status -Found existing work. Would you like to: + + 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 + -If new or starting fresh: -Check `output_folder` for `product_brief`, `market_research`, and other docs. + + Check `output_folder` for `product_brief`, `market_research`, and other docs. For Level 3-4, Product Brief is STRONGLY recommended @@ -35,6 +36,7 @@ Check `output_folder` for `product_brief`, `market_research`, and other docs. Get comprehensive description of the project vision. description + @@ -200,15 +202,10 @@ Since this is a Level {{project_level}} project, you need architecture before st - Input: PRD.md, epics.md - Output: architecture.md -If project has significant UX/UI components (Level 3-4 typically does): + -- [ ] **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, 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 +- [ ] **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, 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 + ### Phase 2: Detailed Planning @@ -246,7 +243,7 @@ Since this is a Level {{project_level}} project, you need architecture before st Project Planning Complete! Next immediate action: -1. Start architecture workflow +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 @@ -255,12 +252,14 @@ Since this is a Level {{project_level}} project, you need architecture before st Which would you like to proceed with? -If user selects option 2: -LOAD: {installed_path}/ux/instructions-ux.md -Pass mode="integrated" with Level 3-4 context + + {project-root}/bmad/bmm/workflows/2-plan/ux/workflow.yaml + Pass mode="integrated" with Level 3-4 context + -If user selects option 3: -{project-root}/bmad/bmm/tasks/ai-fe-prompt.md + + {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 index b5a808c4..67b5b7a9 100644 --- a/src/modules/bmm/workflows/2-plan/prd/instructions-med.md +++ b/src/modules/bmm/workflows/2-plan/prd/instructions-med.md @@ -15,24 +15,25 @@ Load project-workflow-analysis.md Confirm Level 1-2 - Feature or small system -If continuation_mode == true: -Load existing PRD.md and check completion status -Found existing work. Would you like to: + + 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 + -If new or starting fresh: -Check `output_folder` for existing docs. Ask user if they have a Product Brief. + + Check `output_folder` for existing docs. Ask user if they have a Product Brief. Load prd_template from workflow.yaml - -Get the core idea of what they're building +Discuss with them to get the core idea of what they're building description + @@ -155,13 +156,15 @@ Only document ACTUAL assumptions from discussion. Run cohesion validation? (y/n) -If yes: -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 + + 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 + + @@ -194,15 +197,10 @@ Since this is a Level {{project_level}} project, you need solutioning before imp - Input: PRD.md, epic-stories.md - Output: solution-architecture.md, tech-spec-epic-N.md files -If project has significant UX/UI components (Level 1-2 with UI): + -- [ ] **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 +- [ ] **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 + ### Phase 2: Detailed Planning @@ -239,12 +237,16 @@ Since this is a Level {{project_level}} project, you need solutioning before imp Which would you like to proceed with? -If user selects option 2: -LOAD: {installed_path}/ux/instructions-ux.md -Pass mode="integrated" with Level 1-2 context + + {project-root}/bmad/bmm/workflows/2-plan/ux/workflow.yaml + Pass mode="integrated" with Level 1-2 context -If user selects option 3: -{project-root}/bmad/bmm/tasks/ai-fe-prompt.md + + + + {project-root}/bmad/bmm/tasks/ai-fe-prompt.md + + diff --git a/src/modules/bmm/workflows/2-plan/prd/workflow.yaml b/src/modules/bmm/workflows/2-plan/prd/workflow.yaml new file mode 100644 index 00000000..67bfdfde --- /dev/null +++ b/src/modules/bmm/workflows/2-plan/prd/workflow.yaml @@ -0,0 +1,95 @@ +# 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" +analysis_template: "{installed_path}/analysis-template.md" +epics_template: "{installed_path}/epics-template.md" + +# Output configuration +analysis_file: "{output_folder}/project-workflow-analysis.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/2-plan/prd/analysis-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/instructions-sm.md b/src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md index 264db46f..7ea3b244 100644 --- a/src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md +++ b/src/modules/bmm/workflows/2-plan/tech-spec/instructions-sm.md @@ -74,12 +74,13 @@ Run cohesion validation? (y/n) -If yes: -Load {installed_path}/checklist.md -Review tech-spec.md against "Cohesion Validation (All Levels)" section -Focus on Section A (Tech Spec), Section D (Feature Sequencing) -Apply Section B (Greenfield) or Section C (Brownfield) based on field_type -Generate validation report with findings + + Load {installed_path}/checklist.md + Review tech-spec.md against "Cohesion Validation (All Levels)" section + Focus on Section A (Tech Spec), Section D (Feature Sequencing) + Apply Section B (Greenfield) or Section C (Brownfield) based on field_type + Generate validation report with findings + @@ -99,19 +100,19 @@ Run cohesion validation? (y/n) Determine appropriate next steps for Level 0 atomic change -If change involves UI components: - **Optional Next Steps:** -- [ ] **Create simple UX documentation** (if UI change is user-facing) - - Note: Full instructions-ux workflow may be overkill for Level 0 - - Consider documenting just the specific UI change + + - [ ] **Create simple UX documentation** (if UI change is user-facing) + - Note: Full instructions-ux workflow may be overkill for Level 0 + - Consider documenting just the specific UI change + - [ ] **Generate implementation task** - Command: `workflow task-generation` - Uses: tech-spec.md -If change is backend/API only: + **Recommended Next Steps:** @@ -132,6 +133,8 @@ Run cohesion validation? (y/n) Select option (1-4): + + diff --git a/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml new file mode 100644 index 00000000..3bda77d7 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan/tech-spec/workflow.yaml @@ -0,0 +1,64 @@ +# 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" + +# Output configuration +default_output_file: "{output_folder}/tech-spec.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 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" + 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/tech-spec-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/instructions-ux.md b/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md index 50f0fe83..f8a3f7d2 100644 --- a/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md +++ b/src/modules/bmm/workflows/2-plan/ux/instructions-ux.md @@ -12,15 +12,16 @@ Determine workflow mode (standalone or integrated) -If mode="standalone": -Do you have an existing PRD or requirements document? (y/n) + + Do you have an existing PRD or requirements document? (y/n) If yes: Provide the path to the PRD If no: We'll gather basic requirements to create the UX spec + -If no PRD in standalone mode: -Let's gather essential information: + + Let's gather essential information: 1. **Project Description**: What are you building? 2. **Target Users**: Who will use this? @@ -28,9 +29,10 @@ If no: We'll gather basic requirements to create the UX spec 4. **Platform**: Web, mobile, desktop, or multi-platform? 5. **Existing Brand/Design**: Any existing style guide or brand to follow? + -If PRD exists or integrated mode: -Load the following documents if available: + + 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) @@ -38,6 +40,8 @@ If no: We'll gather basic requirements to create the UX spec - architecture.md (if Level 3-4 project) - project-workflow-analysis.md (understand project level and scope) + + Analyze project for UX complexity: - Number of user-facing features @@ -225,13 +229,14 @@ This is recommended for: - Complex state transitions -If yes: + Define motion principles motion_principles Define key animations and transitions key_animations + @@ -241,26 +246,26 @@ This is recommended for: **1. Will you be creating high-fidelity designs?** -- [ ] Yes, in Figma -- [ ] Yes, in Sketch -- [ ] Yes, in Adobe XD -- [ ] No, development from spec -- [ ] Other: **\_\_\_\_** +- Yes, in Figma +- Yes, in Sketch +- Yes, in Adobe XD +- No, development from spec +- Other (describe) **2. For key screens, should we:** -- [ ] Reference design file locations -- [ ] Create low-fi wireframe descriptions -- [ ] Skip visual representations - +- Reference design file locations +- Create low-fi wireframe descriptions +- Skip visual representations + -If design files will be created: -design_files +design_files -If wireframe descriptions needed: - -screen*layout*{{screen_number}} - + + + screen*layout*{{screen_number}} + + @@ -281,17 +286,18 @@ This is recommended for: - [ ] Brand guidelines incorporated - [ ] Performance goals established -If Level 3-4 project: + + - [ ] Ready for detailed visual design + - [ ] Frontend architecture can proceed + - [ ] Story generation can include UX details + -- [ ] Ready for detailed visual design -- [ ] Frontend architecture can proceed -- [ ] Story generation can include UX details + + - [ ] Development can proceed with spec + - [ ] Component implementation order defined + - [ ] MVP scope clear -If Level 1-2 project or standalone: - -- [ ] Development can proceed with spec -- [ ] Component implementation order defined -- [ ] MVP scope clear + design_handoff_checklist @@ -307,8 +313,9 @@ This is recommended for: Would you like to generate an AI Frontend Prompt? (y/n): -If user selects yes or option 1: -Generate AI Frontend Prompt + + Generate AI Frontend Prompt + diff --git a/src/modules/bmm/workflows/2-plan/ux/workflow.yaml b/src/modules/bmm/workflows/2-plan/ux/workflow.yaml new file mode 100644 index 00000000..71ed2590 --- /dev/null +++ b/src/modules/bmm/workflows/2-plan/ux/workflow.yaml @@ -0,0 +1,71 @@ +# 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 index adda918b..02e4885d 100644 --- a/src/modules/bmm/workflows/2-plan/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan/workflow.yaml @@ -18,6 +18,13 @@ recommended_inputs: # 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" analysis_template: "{installed_path}/prd/analysis-template.md" diff --git a/src/modules/bmm/workflows/3-solutioning/instructions.md b/src/modules/bmm/workflows/3-solutioning/instructions.md index fee73e29..02f220da 100644 --- a/src/modules/bmm/workflows/3-solutioning/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/instructions.md @@ -529,12 +529,12 @@ Update architecture.md with specialist sections (inline or placeholders) at the - + Did cohesion check or architecture design reveal: - Missing enabler epics (e.g., "Infrastructure Setup")? - Story modifications needed? - New FRs/NFRs discovered? - + Architecture design revealed some PRD updates needed: @@ -587,9 +587,9 @@ Update project-workflow-analysis.md workflow status: - + Is this a polyrepo project (multiple repositories)? - + For polyrepo projects: 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 2fa15ba1..debbbeb0 100644 --- a/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/tech-spec/instructions.md @@ -10,7 +10,9 @@ Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths. If inputs are missing, ask the user for file paths. - If inputs are missing and {{non_interactive}} == true → HALT with a clear message listing missing documents. + + HALT with a clear message listing missing documents and do not proceed until user provides sufficient documents to proceed. + Extract {{epic_title}} and {{epic_id}} from PRD (or ASK if not present). Resolve output file path using workflow variables and initialize by writing the template. 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 e3b4b9e2..3fc5e297 100644 --- a/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/correct-course/instructions.md @@ -6,37 +6,34 @@ -Confirm change trigger and gather user description of the issue -Ask: "What specific issue or change has been identified that requires navigation?" -Verify access to required project documents: - - PRD (Product Requirements Document) - - Current Epics and Stories - - Architecture documentation - - UI/UX specifications -Ask user for mode preference: - - **Incremental** (recommended): Refine each edit collaboratively - - **Batch**: Present all changes at once for review -Store mode selection for use throughout workflow + Confirm change trigger and gather user description of the issue + Ask: "What specific issue or change has been identified that requires navigation?" + Verify access to required project documents: + - PRD (Product Requirements Document) + - Current Epics and Stories + - Architecture documentation + - UI/UX specifications + Ask user for mode preference: + - **Incremental** (recommended): Refine each edit collaboratively + - **Batch**: Present all changes at once for review + Store mode selection for use throughout workflow -If change trigger is unclear: -HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why." +HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why." -If core documents are unavailable: -HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." +HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." -Load and execute the systematic analysis from: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/checklist.md -Work through each checklist section interactively with the user -Record status for each checklist item: - - [x] Done - Item completed successfully - - [N/A] Skip - Item not applicable to this change - - [!] Action-needed - Item requires attention or follow-up -Maintain running notes of findings and impacts discovered -Present checklist progress after each major section + Load and execute the systematic analysis from: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/checklist.md + Work through each checklist section interactively with the user + Record status for each checklist item: + - [x] Done - Item completed successfully + - [N/A] Skip - Item not applicable to this change + - [!] Action-needed - Item requires attention or follow-up + Maintain running notes of findings and impacts discovered + Present checklist progress after each major section -If checklist cannot be completed: -Identify blocking issues and work with user to resolve before continuing +Identify blocking issues and work with user to resolve before continuing @@ -81,13 +78,14 @@ - Show wireframe or flow changes needed - Connect changes to user experience impact -If mode is Incremental: -Present each edit proposal individually -Review and refine this change? Options: Approve [a], Edit [e], Skip [s] -Iterate on each proposal based on user feedback + + Present each edit proposal individually + Review and refine this change? Options: Approve [a], Edit [e], Skip [s] + Iterate on each proposal based on user feedback + + +Collect all edit proposals and present together at end of step -If mode is Batch: -Collect all edit proposals and present together at end of step @@ -138,15 +136,17 @@ Get explicit user approval for complete proposal Do you approve this Sprint Change Proposal for implementation? (yes/no/revise) -If no or revise: -Gather specific feedback on what needs adjustment -Return to appropriate step to address concerns -If changes needed to edit proposals -If changes needed to overall proposal structure + + Gather specific feedback on what needs adjustment + Return to appropriate step to address concerns + If changes needed to edit proposals + If changes needed to overall proposal structure -If yes: -Finalize Sprint Change Proposal document -Determine change scope classification: + + + + Finalize Sprint Change Proposal document + Determine change scope classification: - **Minor**: Can be implemented directly by development team - **Moderate**: Requires backlog reorganization and PO/SM coordination @@ -154,20 +154,26 @@ Provide appropriate handoff based on scope: -If Minor scope: -Route to: Development team for direct implementation -Deliverables: Finalized edit proposals and implementation tasks + -If Moderate scope: -Route to: Product Owner / Scrum Master agents -Deliverables: Sprint Change Proposal + backlog reorganization plan + + Route to: Development team for direct implementation + Deliverables: Finalized edit proposals and implementation tasks + -If Major scope: -Route to: Product Manager / Solution Architect -Deliverables: Complete Sprint Change Proposal + escalation notice + + Route to: Product Owner / Scrum Master agents + Deliverables: Sprint Change Proposal + backlog reorganization plan + + + + Route to: Product Manager / Solution Architect + Deliverables: Complete Sprint Change Proposal + escalation notice Confirm handoff completion and next steps with user Document handoff in workflow execution log + + diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index f6896029..00f1480d 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -5,7 +5,7 @@ FACILITATION NOTES: -- Bob (Scrum Master) facilitates this retrospective +- Scrum Master facilitates this retrospective - Psychological safety is paramount - NO BLAME - Focus on systems, processes, and learning - Everyone contributes with specific examples preferred @@ -20,40 +20,27 @@ FACILITATION NOTES: Which epic has just been completed? (Enter epic number, e.g., "003" or auto-detect from highest completed story) -If auto-detecting: -Check {output_folder}/stories/ for highest numbered completed story -Extract epic number from story file (e.g., "Epic: 003" section) + + Check {output_folder}/stories/ for highest numbered completed story + Extract epic number from story file (e.g., "Epic: 003" section) + Load the completed epic from: {output_folder}/prd/epic-{{epic_number}}.md -Extract epic details: +Extract epic details: - Epic title and goals - Success criteria - Planned stories and story points - Estimated sprint duration - Business objectives + Find all stories for this epic in {output_folder}/stories/ -For each story, extract: +For each story, extract: - Story number and title - Completion status - Story points (if tracked) - Actual completion date - Dev Agent Record notes - TEA Results and testing outcomes - PO Notes and acceptance - Blockers encountered and resolution - Technical debt incurred + -- Story number and title -- Completion status -- Story points (if tracked) -- Actual completion date -- Dev Agent Record notes -- TEA Results and testing outcomes -- PO Notes and acceptance -- Blockers encountered and resolution -- Technical debt incurred - -Calculate epic metrics: - -- Completed stories vs. total planned -- Actual story points delivered vs. planned -- Actual sprints taken vs. estimated -- Velocity (points per sprint) -- Blocker count and resolution time -- Technical debt items logged +Calculate epic metrics: - Completed stories vs. total planned - Actual story points delivered vs. planned - Actual sprints taken vs. estimated - Velocity (points per sprint) - Blocker count - Technical debt items logged + Review epic goals and compare actual outcomes vs. planned Note any scope changes or descoped items @@ -65,43 +52,48 @@ FACILITATION NOTES: Identify the next epic in sequence Load next epic from: {output_folder}/prd/epic-{{next_epic_number}}.md -Analyze next epic for: + +Analyze next epic for: + - Epic title and objectives + - Planned stories and complexity + - Dependencies on completed epic work + - New technical requirements or capabilities needed + - Potential risks or unknowns + -- Epic title and objectives -- Planned stories and complexity -- Dependencies on completed epic work -- New technical requirements or capabilities needed -- Potential risks or unknowns - -Identify dependencies on completed work: +Identify dependencies on completed work: - What components from Epic {{completed_number}} does Epic {{next_number}} rely on? - Are all prerequisites complete and stable? - Any incomplete work that creates blocking dependencies? + -Note potential gaps or preparation needed: +Note potential gaps or preparation needed: - Technical setup required (infrastructure, tools, libraries) - Knowledge gaps to fill (research, training, spikes) - Refactoring needed before starting next epic - Documentation or specifications to create + -Check for technical prerequisites: +Check for technical prerequisites: - APIs or integrations that must be ready - Data migrations or schema changes needed - Testing infrastructure requirements - Deployment or environment setup - + + + -Bob (Scrum Master) opens the retrospective with context -Present formatted retrospective header: +Scrum Master opens the retrospective with context +Present formatted retrospective header: ``` 🔄 TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}} -Bob (Scrum Master) facilitating +Scrum Master facilitating ═══════════════════════════════════════════════════════════ @@ -147,13 +139,14 @@ Focus Areas: 2. Preparing for Epic {{next_number}} success ``` -Load agent configurations from: {project-root}/bmad/\_cfg/agent-party.xml -Identify agents who participated in the completed epic based on story records -Ensure key roles present: Sarah (PO), Bob (SM), James (Dev), Murat (TEA), Winston (Architect), Mary (Analyst) + + +Load agent configurations from {agent-manifest} +Ensure key roles present from the {agent_manifest}: Product Owner, Scrum Master (facilitating the retro), Devs, Testing or QA, Architect, Analyst -Bob facilitates Part 1: Reviewing the completed epic +Scrum Master facilitates Part 1: Reviewing the completed epic Each agent shares in their unique voice, referencing actual story data Maintain psychological safety - focus on learning, not blame @@ -184,21 +177,16 @@ Focus Areas: - Skills or knowledge gained - Process improvements to implement -Agent personality guidance: - -- **Sarah (PO)**: Business value delivery, stakeholder management, requirements clarity -- **Bob (SM)**: Process effectiveness, team dynamics, blocker removal, velocity trends -- **James (Dev)**: Technical execution, code quality, development experience, tooling -- **Murat (TEA)**: Quality outcomes, testing effectiveness, defect prevention, coverage -- **Winston (Architect)**: Architectural decisions, technical strategy, long-term sustainability -- **Mary (Analyst)**: Requirements accuracy, specification quality, edge case handling +Agent personality guidance: +Each agent loaded from {agent_manifest} will interact with their role and personality and communication style best represented and simulated during discussions + Encourage specific examples from story records, metrics, and real outcomes -Bob synthesizes common themes as discussion progresses +Scrum Master synthesizes common themes as discussion progresses -Bob facilitates Part 2: Preparing for the next epic +Scrum Master facilitates Part 2: Preparing for the next epic Each agent addresses preparation needs from their domain For each agent, present forward-looking analysis: @@ -232,12 +220,12 @@ Focus Areas: -Bob identifies patterns across all agent feedback +Scrum Master identifies patterns across all agent feedback Synthesizes common themes into team agreements Creates specific, achievable action items with clear ownership Develops preparation sprint tasks if significant setup needed -Present comprehensive action plan: +Present comprehensive action plan: ``` ═══════════════════════════════════════════════════════════ @@ -295,49 +283,56 @@ Risk Mitigation: - {{risk}}: {{mitigation_strategy}} ``` + + Ensure every action item has clear owner and timeline Prioritize preparation tasks by dependencies and criticality Identify which tasks can run in parallel vs. sequential -Bob leads final verification checks before concluding retrospective +Scrum Master leads final verification checks before concluding retrospective User must confirm readiness before next epic begins Let's verify Epic {{completed_number}} is truly complete. Please confirm each item: **Testing Verification:** Has full regression testing been completed for Epic {{completed_number}}? (yes/no/partial) -If no or partial: -Add to Critical Path: Complete regression testing before Epic {{next_number}} + +Add to Critical Path: Complete regression testing before Epic {{next_number}} **Deployment Status:** + Has Epic {{completed_number}} been deployed to production? (yes/no/scheduled) -If no: -Add to Critical Path: Deploy Epic {{completed_number}} - scheduled for {{date}} +Add to Critical Path: Deploy Epic {{completed_number}} - scheduled for {{date}} **Business Validation:** Have stakeholders reviewed and accepted Epic {{completed_number}} deliverables? (yes/no/pending) -If no or pending: -Add to Critical Path: Obtain stakeholder acceptance before Epic {{next_number}} + +Add to Critical Path: Obtain stakeholder acceptance before Epic {{next_number}} **Technical Health:** Is the codebase in a stable, maintainable state after Epic {{completed_number}}? (yes/no/concerns) -If no or concerns: -Document concerns: {{user_input}} -Add to Preparation Sprint: Address stability concerns + + + Document concerns: {{user_input}} + Add to Preparation Sprint: Address stability concerns + **Blocker Resolution:** Are there any unresolved blockers from Epic {{completed_number}} that will impact Epic {{next_number}}? (yes/no) -If yes: -Document blockers: {{user_input}} -Add to Critical Path with highest priority -Bob summarizes verification results and any critical items added + + Document blockers: {{user_input}} + Add to Critical Path with highest priority + + +Summarize the verification results and any critical items added + -Bob closes the retrospective with summary and next steps +Scrum Master closes the retrospective with summary and next steps Present closure summary: @@ -365,7 +360,7 @@ Critical Path Items: {{critical_count}} 4. Begin Epic {{next_number}} planning when preparation complete ═══════════════════════════════════════════════════════════ -Bob: "Great work team! We learned a lot from Epic {{completed_number}}. +Scrum Master: "Great work team! We learned a lot from Epic {{completed_number}}. Let's use these insights to make Epic {{next_number}} even better. See you at sprint planning once prep work is done!" ``` @@ -378,7 +373,7 @@ See you at sprint planning once prep work is done!" -Bob maintains psychological safety throughout - no blame or judgment +Scrum Master maintains psychological safety throughout - no blame or judgment Focus on systems and processes, not individual performance Encourage specific examples over general statements Balance celebration of wins with honest assessment of challenges diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index eff2d837..cff301e0 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -19,7 +19,7 @@ required_inputs: - completed_epic: "The epic that was just completed" - stories_folder: "{output_folder}/stories/" - epics_folder: "{output_folder}/prd/" - - agent_party_config: "{project-root}/bmad/_cfg/agent-party.xml" + - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv" output_artifacts: - retrospective_summary: "Comprehensive review of what went well and what could improve" 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 3f2c7259..4dfee7af 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md @@ -16,15 +16,15 @@ Resolve {{story_path}} and read the COMPLETE file. Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available. Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log. - If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent). - If story cannot be read → HALT. + HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent). + HALT. Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent. - If no context found → Continue but record a WARNING in review notes: "No Story Context found". + Continue but record a WARNING in review notes: "No Story Context found". Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input. - If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}". + Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}". Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns. @@ -40,12 +40,12 @@ From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks). Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files. For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly. - If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding. + flag as High Severity finding. For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns. - Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, unvalidated redirects, CORS misconfig, dependency vulnerabilities (based on manifests). + Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests). Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns. Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections. @@ -102,15 +102,15 @@ Resolve {{story_path}} and read the COMPLETE file. Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata if available. Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log. - If Status is not one of {{allow_status_values}} → HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent). - If story cannot be read → HALT. + HALT with message: "Story status must be 'Ready for Review' to proceed" (accept 'Review' as equivalent). + HALT. Locate Story Context: Under Dev Agent Record → Context Reference, read referenced path(s). If missing and {{auto_discover_context}}: search {{output_folder}} for files named "story-context-{{epic_num}}.{{story_num}}*.xml"; pick the most recent. - If no context found → Continue but record a WARNING in review notes: "No Story Context found". + Continue but record a WARNING in review notes: "No Story Context found". Locate Epic Tech Spec: If {{auto_discover_tech_spec}}, search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}); else use provided input. - If no tech spec found → Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}". + Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}". Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect any testing, coding standards, security, and architectural patterns. @@ -126,7 +126,7 @@ From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks). Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files. For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly. - If critical architecture constraints are violated (e.g., layering, dependency rules) → flag as High severity finding. + flag as High severity finding. diff --git a/src/modules/cis/workflows/storytelling/instructions.md b/src/modules/cis/workflows/storytelling/instructions.md index f030e29f..28aea0d1 100644 --- a/src/modules/cis/workflows/storytelling/instructions.md +++ b/src/modules/cis/workflows/storytelling/instructions.md @@ -177,8 +177,6 @@ The first moment determines if they keep reading/listening. -Ask if user wants to write or wants AI to write - Would you like to: 1. Draft the story yourself with my guidance @@ -186,13 +184,13 @@ The first moment determines if they keep reading/listening. 3. Co-create it iteratively together - + Provide writing prompts and encouragement Offer feedback on drafts they share Suggest refinements for clarity, emotion, flow - + Synthesize all gathered elements Write complete narrative in appropriate tone/style Structure according to chosen framework @@ -200,7 +198,7 @@ The first moment determines if they keep reading/listening. Present draft for feedback and refinement - + Write opening paragraph Get feedback and iterate Build section by section collaboratively