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/README.md b/src/modules/bmm/README.md index 7de6229f..4a2019ce 100644 --- a/src/modules/bmm/README.md +++ b/src/modules/bmm/README.md @@ -62,7 +62,7 @@ Extension modules that add specialized capabilities to BMM. ### 🏗️ `/testarch` -Test architecture and quality assurance components. +Test architecture and quality assurance components. The **[Test Architect (TEA) Guide](./testarch/README.md)** provides comprehensive testing strategy across 9 workflows: framework setup, CI/CD, test design, ATDD, automation, traceability, NFR assessment, quality gates, and test review. ## Quick Start @@ -119,6 +119,7 @@ BMM integrates seamlessly with the BMad Core framework, leveraging: ## Related Documentation - [BMM Workflows Guide](./workflows/README.md) - **Start here!** +- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy - [Agent Documentation](./agents/README.md) - Individual agent capabilities - [Team Configurations](./teams/README.md) - Pre-built team setups - [Task Library](./tasks/README.md) - Reusable task components 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/tea.agent.yaml b/src/modules/bmm/agents/tea.agent.yaml index 9b3d1e19..3fa3fca6 100644 --- a/src/modules/bmm/agents/tea.agent.yaml +++ b/src/modules/bmm/agents/tea.agent.yaml @@ -11,7 +11,7 @@ agent: persona: role: Master Test Architect identity: Test architect specializing in CI/CD, automated frameworks, and scalable quality gates. - communication_style: Data-driven advisor. Strong opinions, weakly held. Pragmatic. Makes random bird noises. + communication_style: Data-driven advisor. Strong opinions, weakly held. Pragmatic. principles: - Risk-based testing: depth scales with impact. Quality gates backed by data. Tests mirror usage. Cost = creation + execution + maintenance. - Testing is feature work. Prioritize unit/integration over E2E. Flakiness is critical debt. ATDD: tests first, AI implements, suite validates. @@ -44,7 +44,7 @@ agent: - trigger: trace workflow: "{project-root}/bmad/bmm/workflows/testarch/trace/workflow.yaml" - description: Map requirements to tests Given-When-Then BDD format + description: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2) - trigger: nfr-assess workflow: "{project-root}/bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml" @@ -54,6 +54,6 @@ agent: workflow: "{project-root}/bmad/bmm/workflows/testarch/ci/workflow.yaml" description: Scaffold CI/CD quality pipeline - - trigger: gate - workflow: "{project-root}/bmad/bmm/workflows/testarch/gate/workflow.yaml" - description: Write/update quality gate decision assessment + - trigger: test-review + workflow: "{project-root}/bmad/bmm/workflows/testarch/test-review/workflow.yaml" + description: Review test quality using comprehensive knowledge base and best practices 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/config.yaml b/src/modules/bmm/config.yaml new file mode 100644 index 00000000..d2310766 --- /dev/null +++ b/src/modules/bmm/config.yaml @@ -0,0 +1,7 @@ +# Powered by BMAD™ Core +name: bmm +short-title: BMad Method Module +author: Brian (BMad) Madison + +# TEA Agent Configuration +tea_use_mcp_enhancements: true # Enable Playwright MCP capabilities (healing, exploratory, verification) 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/testarch/README.md b/src/modules/bmm/testarch/README.md index 49207a69..a0356d01 100644 --- a/src/modules/bmm/testarch/README.md +++ b/src/modules/bmm/testarch/README.md @@ -1,5 +1,5 @@ --- -last-redoc-date: 2025-09-30 +last-redoc-date: 2025-10-14 --- # Test Architect (TEA) Agent Guide @@ -10,6 +10,97 @@ last-redoc-date: 2025-09-30 - **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project level and compliance demands. - **Use When:** Project level ≥2, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required. +## TEA Workflow Lifecycle + +TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase: + +``` +┌──────────────────────────────────────────────────────────┐ +│ BMM Phase 2: PLANNING │ +│ │ +│ PM: *plan-project │ +│ ↓ │ +│ TEA: *framework ──→ *ci ──→ *test-design │ +│ └─────────┬─────────────┘ │ +│ │ (Setup once per project) │ +└─────────────────┼──────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ BMM Phase 4: IMPLEMENTATION │ +│ (Per Story Cycle) │ +│ │ +│ ┌─→ SM: *create-story │ +│ │ ↓ │ +│ │ TEA: *atdd (optional, before dev) │ +│ │ ↓ │ +│ │ DEV: implements story │ +│ │ ↓ │ +│ │ TEA: *automate ──→ *test-review (optional) │ +│ │ ↓ │ +│ │ TEA: *trace (refresh coverage) │ +│ │ ↓ │ +│ └───[next story] │ +└─────────────────┼──────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ EPIC/RELEASE GATE │ +│ │ +│ TEA: *nfr-assess (if not done earlier) │ +│ ↓ │ +│ TEA: *test-review (final audit, optional) │ +│ ↓ │ +│ TEA: *trace (Phase 2: Gate) ──→ PASS | CONCERNS | FAIL | WAIVED │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +### TEA Integration with BMad v6 Workflow + +TEA operates **across all four BMad phases**, unlike other agents that are phase-specific: + +
+Cross-Phase Integration & Workflow Complexity + +### Phase-Specific Agents (Standard Pattern) + +- **Phase 1 (Analysis)**: Analyst agent +- **Phase 2 (Planning)**: PM agent +- **Phase 3 (Solutioning)**: Architect agent +- **Phase 4 (Implementation)**: SM, DEV agents + +### TEA: Cross-Phase Quality Agent (Unique Pattern) + +TEA is **the only agent that spans all phases**: + +``` +Phase 1 (Analysis) → [TEA not typically used] + ↓ +Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup) + ↓ +Phase 3 (Solutioning) → [TEA validates architecture testability] + ↓ +Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story) + ↓ +Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision) +``` + +### Why TEA Needs 8 Workflows + +**Standard agents**: 1-3 workflows per phase +**TEA**: 8 workflows across 3+ phases + +| Phase | TEA Workflows | Frequency | Purpose | +| ----------- | -------------------------------------- | ---------------- | -------------------------------- | +| **Phase 2** | *framework, *ci, \*test-design | Once per project | Establish quality infrastructure | +| **Phase 4** | *atdd, *automate, *test-review, *trace | Per story/sprint | Continuous quality validation | +| **Release** | *nfr-assess, *trace (Phase 2: gate) | Per epic/release | Go/no-go decision | + +**Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow. + +This complexity **requires specialized documentation** (this guide), **extensive knowledge base** (19+ fragments), and **unique architecture** (`testarch/` directory). + +
+ ## Prerequisites and Setup 1. Run the core planning workflows first: @@ -31,8 +122,8 @@ last-redoc-date: 2025-09-30 | Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design` | Review risk/design/CI guidance, align backlog | Test scaffold, CI pipeline, risk and coverage strategy | | Story Prep | - | Scrum Master `*create-story`, `*story-context` | Story markdown + context XML | | Implementation | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist | Failing acceptance tests + implementation checklist | -| Post-Dev | Execute `*automate`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, refreshed coverage matrix | -| Release | Run `*gate` | Confirm Definition of Done, share release notes | Gate YAML + release summary (owners, waivers) | +| Post-Dev | Execute `*automate`, (Optional) `*test-review`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, quality report, refreshed coverage matrix | +| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary (owners, waivers) |
Execution Notes @@ -40,7 +131,8 @@ last-redoc-date: 2025-09-30 - Run `*framework` only once per repo or when modern harness support is missing. - `*framework` followed by `*ci` establishes install + pipeline; `*test-design` then handles risk scoring, mitigations, and scenario planning in one pass. - Use `*atdd` before coding when the team can adopt ATDD; share its checklist with the dev agent. -- Post-implementation, keep `*trace` current, expand coverage with `*automate`, and finish with `*gate`. +- Post-implementation, keep `*trace` current, expand coverage with `*automate`, optionally review test quality with `*test-review`. For release gate, run `*trace` with Phase 2 enabled to get deployment decision. +- Use `*test-review` after `*atdd` to validate generated tests, after `*automate` to ensure regression quality, or before gate for final audit.
@@ -51,21 +143,21 @@ last-redoc-date: 2025-09-30 2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans. 3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*assess-project-ready`. 4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan. -5. **Post-Dev and Release:** TEA runs `*automate`, re-runs `*trace`, and finishes with `*gate` to document the decision. +5. **Post-Dev and Release:** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled to generate both traceability and gate decision. ### Brownfield Feature Enhancement (Level 3–4) -| Phase | Test Architect | Dev / Team | Outputs | -| ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- | -| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` | -| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet | -| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix | -| Story Prep | - | Scrum Master `*create-story` | Updated story markdown | -| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist | -| Post-Dev | Apply `*automate`, re-run `*trace`, trigger `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, refreshed coverage matrix, NFR report | -| Release | Run `*gate` | Product Owner `*assess-project-ready`, share release notes | Gate YAML + release summary | +| Phase | Test Architect | Dev / Team | Outputs | +| ----------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- | +| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` | +| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet | +| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix | +| Story Prep | - | Scrum Master `*create-story` | Updated story markdown | +| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist | +| Post-Dev | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, quality report, refreshed coverage matrix, NFR report | +| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Product Owner `*assess-project-ready`, share release notes | Quality audit, Gate YAML + release summary |
Execution Notes @@ -73,7 +165,8 @@ last-redoc-date: 2025-09-30 - Lead with `*trace` so remediation plans target true coverage gaps. Ensure `*framework` and `*ci` are in place early in the engagement; if the brownfield lacks them, run those setup steps immediately after refreshing context. - `*test-design` should highlight regression hotspots, mitigations, and P0 scenarios. - Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation. -- After development, expand coverage with `*automate`, re-run `*trace`, and close with `*gate`. Run `*nfr-assess` now if non-functional risks weren't addressed earlier. +- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier. +- Use `*test-review` to validate existing brownfield tests or audit new tests before gate. - Product Owner `*assess-project-ready` confirms the team has artifacts before handoff or release.
@@ -87,26 +180,27 @@ last-redoc-date: 2025-09-30 4. **Story Prep:** Scrum Master generates `stories/story-1.1.md` via `*create-story`, automatically pulling updated context. 5. **ATDD First:** TEA runs `*atdd`, producing failing Playwright specs under `tests/e2e/payments/` plus an implementation checklist. 6. **Implementation:** Dev pairs with the checklist/tests to deliver the story. -7. **Post-Implementation:** TEA applies `*automate`, re-runs `*trace`, performs `*nfr-assess` to validate SLAs, and closes with `*gate` marking PASS with follow-ups. +7. **Post-Implementation:** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled, performs `*nfr-assess` to validate SLAs. The `*trace` Phase 2 output marks PASS with follow-ups. ### Enterprise / Compliance Program (Level 4) -| Phase | Test Architect | Dev / Team | Outputs | -| ------------------- | ------------------------------------------------ | ---------------------------------------------- | --------------------------------------------------------- | -| Strategic Planning | - | Analyst/PM/Architect standard workflows | Enterprise-grade PRD, epics, architecture | -| Quality Planning | Run `*framework`, `*test-design`, `*nfr-assess` | Review guidance, align compliance requirements | Harness scaffold, risk + coverage plan, NFR documentation | -| Pipeline Enablement | Configure `*ci` | Coordinate secrets, pipeline approvals | `.github/workflows/test.yml`, helper scripts | -| Execution | Enforce `*atdd`, `*automate`, `*trace` per story | Implement stories, resolve TEA findings | Tests, fixtures, coverage matrices | -| Release | Run `*gate` | Capture sign-offs, archive artifacts | Updated assessments, gate YAML, audit trail | +| Phase | Test Architect | Dev / Team | Outputs | +| ------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- | +| Strategic Planning | - | Analyst/PM/Architect standard workflows | Enterprise-grade PRD, epics, architecture | +| Quality Planning | Run `*framework`, `*test-design`, `*nfr-assess` | Review guidance, align compliance requirements | Harness scaffold, risk + coverage plan, NFR documentation | +| Pipeline Enablement | Configure `*ci` | Coordinate secrets, pipeline approvals | `.github/workflows/test.yml`, helper scripts | +| Execution | Enforce `*atdd`, `*automate`, `*test-review`, `*trace` per story | Implement stories, resolve TEA findings | Tests, fixtures, quality reports, coverage matrices | +| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, archive artifacts | Quality audit, updated assessments, gate YAML, audit trail |
Execution Notes - Use `*atdd` for every story when feasible so acceptance tests lead implementation in regulated environments. - `*ci` scaffolds selective testing scripts, burn-in jobs, caching, and notifications for long-running suites. -- Prior to release, rerun coverage (`*trace`, `*automate`) and formalize the decision in `*gate`; store everything for audits. Call `*nfr-assess` here if compliance/performance requirements weren't captured during planning. +- Enforce `*test-review` per story or sprint to maintain quality standards and ensure compliance with testing best practices. +- Prior to release, rerun coverage (`*trace`, `*automate`), perform final quality audit with `*test-review`, and formalize the decision with `*trace` Phase 2 (gate decision); store everything for audits. Call `*nfr-assess` here if compliance/performance requirements weren't captured during planning.
@@ -116,47 +210,102 @@ last-redoc-date: 2025-09-30 1. **Strategic Planning:** Analyst/PM/Architect complete PRD, epics, and architecture using the standard workflows. 2. **Quality Planning:** TEA runs `*framework`, `*test-design`, and `*nfr-assess` to establish mitigations, coverage, and NFR targets. 3. **Pipeline Setup:** TEA configures CI via `*ci` with selective execution scripts. -4. **Execution:** For each story, TEA enforces `*atdd`, `*automate`, and `*trace`; Dev teams iterate on the findings. -5. **Release:** TEA re-checks coverage and logs the final gate decision via `*gate`, archiving artifacts for compliance. +4. **Execution:** For each story, TEA enforces `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings. +5. **Release:** TEA re-checks coverage, performs final quality audit with `*test-review`, and logs the final gate decision via `*trace` Phase 2, archiving artifacts for compliance. ## Command Catalog -| Command | Task File | Primary Outputs | Notes | -| -------------- | ------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------ | -| `*framework` | `workflows/testarch/framework/instructions.md` | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | -| `*atdd` | `workflows/testarch/atdd/instructions.md` | Failing acceptance tests + implementation checklist | Requires approved story + harness | -| `*automate` | `workflows/testarch/automate/instructions.md` | Prioritized specs, fixtures, README/script updates, DoD summary | Avoid duplicate coverage (see priority matrix) | -| `*ci` | `workflows/testarch/ci/instructions.md` | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | -| `*test-design` | `workflows/testarch/test-design/instructions.md` | Combined risk assessment, mitigation plan, and coverage strategy | Handles risk scoring and test design in one pass | -| `*trace` | `workflows/testarch/trace/instructions.md` | Coverage matrix, recommendations, gate snippet | Requires access to story/tests repositories | -| `*nfr-assess` | `workflows/testarch/nfr-assess/instructions.md` | NFR assessment report with actions | Focus on security/performance/reliability | -| `*gate` | `workflows/testarch/gate/instructions.md` | Gate YAML + summary (PASS/CONCERNS/FAIL/WAIVED) | Deterministic decision rules + rationale | -
-Command Guidance and Context Loading +Optional Playwright MCP Enhancements -- Each task now carries its own preflight/flow/deliverable guidance inline. -- `tea-index.csv` maps workflow needs to knowledge fragments; keep tags accurate as you add guidance. -- Consider future modularization into orchestrated workflows if additional automation is needed. -- Update the fragment markdown files alongside workflow edits so guidance and outputs stay in sync. +**Two Playwright MCP servers** (actively maintained, continuously updated): + +- `playwright` - Browser automation (`npx @playwright/mcp@latest`) +- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`) + +**How MCP Enhances TEA Workflows**: + +MCP provides additional capabilities on top of TEA's default AI-based approach: + +1. `*test-design`: + - Default: Analysis + documentation + - **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation + + Benefit:Discover actual functionality, edge cases, undocumented features + +2. `*atdd`, `*automate`: + - Default: Infers selectors and interactions from requirements and knowledge fragments + - **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app + + Benefit: Accurate selectors from real DOM, verified behavior, refined test code + +3. `*automate`: + - Default: Pattern-based fixes from error messages + knowledge fragments + - **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator` + + Benefit: Visual failure context, live DOM inspection, root cause discovery + +**Config example**: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + }, + "playwright-test": { + "command": "npx", + "args": ["playwright", "run-test-mcp-server"] + } + } +} +``` + +**To disable**: Set `tea_use_mcp_enhancements: false` in `bmad/bmm/config.yaml` OR remove MCPs from IDE config.
-## Workflow Placement +

-The TEA stack has three tightly-linked layers: +| Command | Workflow README | Primary Outputs | Notes | With Playwright MCP Enhancements | +| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `*framework` | [📖](../workflows/testarch/framework/README.md) | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | - | +| `*ci` | [📖](../workflows/testarch/ci/README.md) | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | - | +| `*test-design` | [📖](../workflows/testarch/test-design/README.md) | Combined risk assessment, mitigation plan, and coverage strategy | Risk scoring + optional exploratory mode | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality) | +| `*atdd` | [📖](../workflows/testarch/atdd/README.md) | Failing acceptance tests + implementation checklist | TDD red phase + optional recording mode | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM) | +| `*automate` | [📖](../workflows/testarch/automate/README.md) | Prioritized specs, fixtures, README/script updates, DoD summary | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser | +| `*test-review` | [📖](../workflows/testarch/test-review/README.md) | Test quality review report with 0-100 score, violations, fixes | Reviews tests against knowledge base patterns | - | +| `*nfr-assess` | [📖](../workflows/testarch/nfr-assess/README.md) | NFR assessment report with actions | Focus on security/performance/reliability | - | +| `*trace` | [📖](../workflows/testarch/trace/README.md) | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision | - | -1. **Agent spec (`agents/tea.md`)** – declares the persona, critical actions, and the `run-workflow` entries for every TEA command. Critical actions instruct the agent to load `tea-index.csv` and then fetch only the fragments it needs from `knowledge/` before giving guidance. -2. **Knowledge index (`tea-index.csv`)** – catalogues each fragment with tags and file paths. Workflows call out the IDs they need (e.g., `risk-governance`, `fixture-architecture`) so the agent loads targeted guidance instead of a monolithic brief. -3. **Workflows (`workflows/testarch/*`)** – contain the task flows and reference `tea-index.csv` in their ``/`` sections to request specific fragments. Keeping all workflows in this directory ensures consistent discovery during planning (`*framework`), implementation (`*atdd`, `*automate`, `*trace`), and release (`*nfr-assess`, `*gate`). +**📖** = Click to view detailed workflow documentation -This separation lets us expand the knowledge base without touching agent wiring and keeps every command remote-controllable via the standard BMAD workflow runner. As navigation improves, we can add lightweight entrypoints or tags in the index without changing where workflows live. +## Why TEA is Architecturally Different -## Appendix +TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`). This intentional design pattern reflects TEA's unique requirements: -- **Supporting Knowledge:** - - `tea-index.csv` – Catalog of knowledge fragments with tags and file paths under `knowledge/` for task-specific loading. - - `knowledge/*.md` – Focused summaries (fixtures, network, CI, levels, priorities, etc.) distilled from Murat’s external resources. - - `test-resources-for-ai-flat.txt` – Raw 347 KB archive retained for manual deep dives when a fragment needs source validation. +
+Unique Architecture Pattern & Rationale + +### Directory Structure + +``` +src/modules/bmm/ +├── agents/ +│ └── tea.agent.yaml # Agent definition (standard location) +├── workflows/ +│ └── testarch/ # TEA workflows (standard location) +└── testarch/ # Knowledge base (UNIQUE!) + ├── knowledge/ # 21 production-ready test pattern fragments + ├── tea-index.csv # Centralized knowledge lookup (21 fragments indexed) + └── README.md # This guide +``` + +### Why TEA Gets Special Treatment + +TEA uniquely requires **extensive domain knowledge** (21 fragments, 12,821 lines: test patterns, CI/CD, fixtures, quality practices, healing strategies), a **centralized reference system** (`tea-index.csv` for on-demand fragment loading), **cross-cutting concerns** (domain-specific patterns vs project-specific artifacts like PRDs/stories), and **optional MCP integration** (healing, exploratory, verification modes). Other BMM agents don't require this architecture. + +
diff --git a/src/modules/bmm/testarch/knowledge/ci-burn-in.md b/src/modules/bmm/testarch/knowledge/ci-burn-in.md index cfb8cadc..65d40695 100644 --- a/src/modules/bmm/testarch/knowledge/ci-burn-in.md +++ b/src/modules/bmm/testarch/knowledge/ci-burn-in.md @@ -1,9 +1,675 @@ # CI Pipeline and Burn-In Strategy -- Stage jobs: install/caching once, run `test-changed` for quick feedback, then shard full suites with `fail-fast: false` so evidence isn’t lost. -- Re-run changed specs 5–10x (burn-in) before merging to flush flakes; fail the pipeline on the first inconsistent run. -- Upload artifacts on failure (videos, traces, HAR) and keep retry counts explicit—hidden retries hide instability. -- Use `wait-on` for app startup, enforce time budgets (<10 min per job), and document required secrets alongside workflows. -- Mirror CI scripts locally (`npm run test:ci`, `scripts/burn-in-changed.sh`) so devs reproduce pipeline behaviour exactly. +## Principle -_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples._ +CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence. + +## Rationale + +CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness. + +## Pattern Examples + +### Example 1: GitHub Actions Workflow with Parallel Execution + +**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing. + +**Implementation**: + +```yaml +# .github/workflows/e2e-tests.yml +name: E2E Tests +on: + pull_request: + push: + branches: [main, develop] + +env: + NODE_VERSION_FILE: '.nvmrc' + CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + +jobs: + install-dependencies: + name: Install & Cache Dependencies + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: ${{ env.NODE_VERSION_FILE }} + cache: 'npm' + + - name: Cache node modules + uses: actions/cache@v4 + id: npm-cache + with: + path: | + ~/.npm + node_modules + ~/.cache/Cypress + ~/.cache/ms-playwright + key: ${{ env.CACHE_KEY }} + restore-keys: | + ${{ runner.os }}-node- + + - name: Install dependencies + if: steps.npm-cache.outputs.cache-hit != 'true' + run: npm ci --prefer-offline --no-audit + + - name: Install Playwright browsers + if: steps.npm-cache.outputs.cache-hit != 'true' + run: npx playwright install --with-deps chromium + + test-changed-specs: + name: Test Changed Specs First (Burn-In) + needs: install-dependencies + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history for accurate diff + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: ${{ env.NODE_VERSION_FILE }} + cache: 'npm' + + - name: Restore dependencies + uses: actions/cache@v4 + with: + path: | + ~/.npm + node_modules + ~/.cache/ms-playwright + key: ${{ env.CACHE_KEY }} + + - name: Detect changed test files + id: changed-tests + run: | + CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "") + echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT + echo "Changed specs: ${CHANGED_SPECS}" + + - name: Run burn-in on changed specs (10 iterations) + if: steps.changed-tests.outputs.changed_specs != '' + run: | + SPECS="${{ steps.changed-tests.outputs.changed_specs }}" + echo "Running burn-in: 10 iterations on changed specs" + for i in {1..10}; do + echo "Burn-in iteration $i/10" + npm run test -- $SPECS || { + echo "❌ Burn-in failed on iteration $i" + exit 1 + } + done + echo "✅ Burn-in passed - 10/10 successful runs" + + - name: Upload artifacts on failure + if: failure() + uses: actions/upload-artifact@v4 + with: + name: burn-in-failure-artifacts + path: | + test-results/ + playwright-report/ + screenshots/ + retention-days: 7 + + test-e2e-sharded: + name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }}) + needs: [install-dependencies, test-changed-specs] + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + fail-fast: false # Run all shards even if one fails + matrix: + shard: [1, 2, 3, 4] + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version-file: ${{ env.NODE_VERSION_FILE }} + cache: 'npm' + + - name: Restore dependencies + uses: actions/cache@v4 + with: + path: | + ~/.npm + node_modules + ~/.cache/ms-playwright + key: ${{ env.CACHE_KEY }} + + - name: Run E2E tests (shard ${{ matrix.shard }}) + run: npm run test:e2e -- --shard=${{ matrix.shard }}/4 + env: + TEST_ENV: staging + CI: true + + - name: Upload test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: test-results-shard-${{ matrix.shard }} + path: | + test-results/ + playwright-report/ + retention-days: 30 + + - name: Upload JUnit report + if: always() + uses: actions/upload-artifact@v4 + with: + name: junit-results-shard-${{ matrix.shard }} + path: test-results/junit.xml + retention-days: 30 + + merge-test-results: + name: Merge Test Results & Generate Report + needs: test-e2e-sharded + runs-on: ubuntu-latest + if: always() + steps: + - name: Download all shard results + uses: actions/download-artifact@v4 + with: + pattern: test-results-shard-* + path: all-results/ + + - name: Merge HTML reports + run: | + npx playwright merge-reports --reporter=html all-results/ + echo "Merged report available in playwright-report/" + + - name: Upload merged report + uses: actions/upload-artifact@v4 + with: + name: merged-playwright-report + path: playwright-report/ + retention-days: 30 + + - name: Comment PR with results + if: github.event_name == 'pull_request' + uses: daun/playwright-report-comment@v3 + with: + report-path: playwright-report/ +``` + +**Key Points**: + +- **Install once, reuse everywhere**: Dependencies cached across all jobs +- **Burn-in first**: Changed specs run 10x before full suite +- **Fail-fast disabled**: All shards run to completion for full evidence +- **Parallel execution**: 4 shards cut execution time by ~75% +- **Artifact retention**: 30 days for reports, 7 days for failure debugging + +--- + +### Example 2: Burn-In Loop Pattern (Standalone Script) + +**Context**: Reusable bash script for burn-in testing changed specs locally or in CI. + +**Implementation**: + +```bash +#!/bin/bash +# scripts/burn-in-changed.sh +# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch] + +set -e # Exit on error + +# Configuration +ITERATIONS=${1:-10} +BASE_BRANCH=${2:-main} +SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$' + +echo "🔥 Burn-In Test Runner" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "Iterations: $ITERATIONS" +echo "Base branch: $BASE_BRANCH" +echo "" + +# Detect changed test files +echo "📋 Detecting changed test files..." +CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "") + +if [ -z "$CHANGED_SPECS" ]; then + echo "✅ No test files changed. Skipping burn-in." + exit 0 +fi + +echo "Changed test files:" +echo "$CHANGED_SPECS" | sed 's/^/ - /' +echo "" + +# Count specs +SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs) +echo "Running burn-in on $SPEC_COUNT test file(s)..." +echo "" + +# Burn-in loop +FAILURES=() +for i in $(seq 1 $ITERATIONS); do + echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + echo "🔄 Iteration $i/$ITERATIONS" + echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + # Run tests with explicit file list + if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then + echo "✅ Iteration $i passed" + else + echo "❌ Iteration $i failed" + FAILURES+=($i) + + # Save failure artifacts + mkdir -p burn-in-failures/iteration-$i + cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true + cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true + + echo "" + echo "🛑 BURN-IN FAILED on iteration $i" + echo "Failure artifacts saved to: burn-in-failures/iteration-$i/" + echo "Logs saved to: burn-in-log-$i.txt" + echo "" + exit 1 + fi + + echo "" +done + +# Success summary +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "🎉 BURN-IN PASSED" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)" +echo "Changed specs are stable and ready to merge." +echo "" + +# Cleanup logs +rm -f burn-in-log-*.txt + +exit 0 +``` + +**Usage**: + +```bash +# Run locally with default settings (10 iterations, compare to main) +./scripts/burn-in-changed.sh + +# Custom iterations and base branch +./scripts/burn-in-changed.sh 20 develop + +# Add to package.json +{ + "scripts": { + "test:burn-in": "bash scripts/burn-in-changed.sh", + "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20" + } +} +``` + +**Key Points**: + +- **Exit on first failure**: Flaky tests caught immediately +- **Failure artifacts**: Saved per-iteration for debugging +- **Flexible configuration**: Iterations and base branch customizable +- **CI/local parity**: Same script runs in both environments +- **Clear output**: Visual feedback on progress and results + +--- + +### Example 3: Shard Orchestration with Result Aggregation + +**Context**: Advanced sharding strategy for large test suites with intelligent result merging. + +**Implementation**: + +```javascript +// scripts/run-sharded-tests.js +const { spawn } = require('child_process'); +const fs = require('fs'); +const path = require('path'); + +/** + * Run tests across multiple shards and aggregate results + * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging + */ + +const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4'); +const TEST_ENV = process.env.TEST_ENV || 'local'; +const RESULTS_DIR = path.join(__dirname, '../test-results'); + +console.log(`🚀 Running tests across ${SHARD_COUNT} shards`); +console.log(`Environment: ${TEST_ENV}`); +console.log('━'.repeat(50)); + +// Ensure results directory exists +if (!fs.existsSync(RESULTS_DIR)) { + fs.mkdirSync(RESULTS_DIR, { recursive: true }); +} + +/** + * Run a single shard + */ +function runShard(shardIndex) { + return new Promise((resolve, reject) => { + const shardId = `${shardIndex}/${SHARD_COUNT}`; + console.log(`\n📦 Starting shard ${shardId}...`); + + const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], { + env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex }, + stdio: 'pipe', + }); + + let stdout = ''; + let stderr = ''; + + child.stdout.on('data', (data) => { + stdout += data.toString(); + process.stdout.write(data); + }); + + child.stderr.on('data', (data) => { + stderr += data.toString(); + process.stderr.write(data); + }); + + child.on('close', (code) => { + // Save shard results + const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`); + try { + const result = JSON.parse(stdout); + fs.writeFileSync(resultFile, JSON.stringify(result, null, 2)); + console.log(`✅ Shard ${shardId} completed (exit code: ${code})`); + resolve({ shardIndex, code, result }); + } catch (error) { + console.error(`❌ Shard ${shardId} failed to parse results:`, error.message); + reject({ shardIndex, code, error }); + } + }); + + child.on('error', (error) => { + console.error(`❌ Shard ${shardId} process error:`, error.message); + reject({ shardIndex, error }); + }); + }); +} + +/** + * Aggregate results from all shards + */ +function aggregateResults() { + console.log('\n📊 Aggregating results from all shards...'); + + const shardResults = []; + let totalTests = 0; + let totalPassed = 0; + let totalFailed = 0; + let totalSkipped = 0; + let totalFlaky = 0; + + for (let i = 1; i <= SHARD_COUNT; i++) { + const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`); + if (fs.existsSync(resultFile)) { + const result = JSON.parse(fs.readFileSync(resultFile, 'utf8')); + shardResults.push(result); + + // Aggregate stats + totalTests += result.stats?.expected || 0; + totalPassed += result.stats?.expected || 0; + totalFailed += result.stats?.unexpected || 0; + totalSkipped += result.stats?.skipped || 0; + totalFlaky += result.stats?.flaky || 0; + } + } + + const summary = { + totalShards: SHARD_COUNT, + environment: TEST_ENV, + totalTests, + passed: totalPassed, + failed: totalFailed, + skipped: totalSkipped, + flaky: totalFlaky, + duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0), + timestamp: new Date().toISOString(), + }; + + // Save aggregated summary + fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2)); + + console.log('\n━'.repeat(50)); + console.log('📈 Test Results Summary'); + console.log('━'.repeat(50)); + console.log(`Total tests: ${totalTests}`); + console.log(`✅ Passed: ${totalPassed}`); + console.log(`❌ Failed: ${totalFailed}`); + console.log(`⏭️ Skipped: ${totalSkipped}`); + console.log(`⚠️ Flaky: ${totalFlaky}`); + console.log(`⏱️ Duration: ${(summary.duration / 1000).toFixed(2)}s`); + console.log('━'.repeat(50)); + + return summary; +} + +/** + * Main execution + */ +async function main() { + const startTime = Date.now(); + const shardPromises = []; + + // Run all shards in parallel + for (let i = 1; i <= SHARD_COUNT; i++) { + shardPromises.push(runShard(i)); + } + + try { + await Promise.allSettled(shardPromises); + } catch (error) { + console.error('❌ One or more shards failed:', error); + } + + // Aggregate results + const summary = aggregateResults(); + + const totalTime = ((Date.now() - startTime) / 1000).toFixed(2); + console.log(`\n⏱️ Total execution time: ${totalTime}s`); + + // Exit with failure if any tests failed + if (summary.failed > 0) { + console.error('\n❌ Test suite failed'); + process.exit(1); + } + + console.log('\n✅ All tests passed'); + process.exit(0); +} + +main().catch((error) => { + console.error('Fatal error:', error); + process.exit(1); +}); +``` + +**package.json integration**: + +```json +{ + "scripts": { + "test:sharded": "node scripts/run-sharded-tests.js", + "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js" + } +} +``` + +**Key Points**: + +- **Parallel shard execution**: All shards run simultaneously +- **Result aggregation**: Unified summary across shards +- **Failure detection**: Exit code reflects overall test status +- **Artifact preservation**: Individual shard results saved for debugging +- **CI/local compatibility**: Same script works in both environments + +--- + +### Example 4: Selective Test Execution (Changed Files + Tags) + +**Context**: Optimize CI by running only relevant tests based on file changes and tags. + +**Implementation**: + +```bash +#!/bin/bash +# scripts/selective-test-runner.sh +# Intelligent test selection based on changed files and test tags + +set -e + +BASE_BRANCH=${BASE_BRANCH:-main} +TEST_ENV=${TEST_ENV:-local} + +echo "🎯 Selective Test Runner" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "Base branch: $BASE_BRANCH" +echo "Environment: $TEST_ENV" +echo "" + +# Detect changed files (all types, not just tests) +CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD) + +if [ -z "$CHANGED_FILES" ]; then + echo "✅ No files changed. Skipping tests." + exit 0 +fi + +echo "Changed files:" +echo "$CHANGED_FILES" | sed 's/^/ - /' +echo "" + +# Determine test strategy based on changes +run_smoke_only=false +run_all_tests=false +affected_specs="" + +# Critical files = run all tests +if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then + echo "⚠️ Critical configuration files changed. Running ALL tests." + run_all_tests=true + +# Auth/security changes = run all auth + smoke tests +elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then + echo "🔒 Auth/security files changed. Running auth + smoke tests." + npm run test -- --grep "@auth|@smoke" + exit $? + +# API changes = run integration + smoke tests +elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then + echo "🔌 API files changed. Running integration + smoke tests." + npm run test -- --grep "@integration|@smoke" + exit $? + +# UI component changes = run related component tests +elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then + echo "🎨 UI components changed. Running component + smoke tests." + + # Extract component names and find related tests + components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//') + for component in $components; do + # Find tests matching component name + affected_specs+=$(find tests -name "*${component}*" -type f) || true + done + + if [ -n "$affected_specs" ]; then + echo "Running tests for: $affected_specs" + npm run test -- $affected_specs --grep "@smoke" + else + echo "No specific tests found. Running smoke tests only." + npm run test -- --grep "@smoke" + fi + exit $? + +# Documentation/config only = run smoke tests +elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then + echo "📝 Documentation/config files changed. Running smoke tests only." + run_smoke_only=true +else + echo "⚙️ Other files changed. Running smoke tests." + run_smoke_only=true +fi + +# Execute selected strategy +if [ "$run_all_tests" = true ]; then + echo "" + echo "Running full test suite..." + npm run test +elif [ "$run_smoke_only" = true ]; then + echo "" + echo "Running smoke tests..." + npm run test -- --grep "@smoke" +fi +``` + +**Usage in GitHub Actions**: + +```yaml +# .github/workflows/selective-tests.yml +name: Selective Tests +on: pull_request + +jobs: + selective-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run selective tests + run: bash scripts/selective-test-runner.sh + env: + BASE_BRANCH: ${{ github.base_ref }} + TEST_ENV: staging +``` + +**Key Points**: + +- **Intelligent routing**: Tests selected based on changed file types +- **Tag-based filtering**: Use @smoke, @auth, @integration tags +- **Fast feedback**: Only relevant tests run on most PRs +- **Safety net**: Critical changes trigger full suite +- **Component mapping**: UI changes run related component tests + +--- + +## CI Configuration Checklist + +Before deploying your CI pipeline, verify: + +- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached +- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min) +- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts +- [ ] **Parallelization**: Matrix strategy uses fail-fast: false +- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge +- [ ] **wait-on app startup**: CI waits for app (wait-on: 'http://localhost:3000') +- [ ] **Secrets documented**: README lists required secrets (API keys, tokens) +- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci) + +## Integration Points + +- Used in workflows: `*ci` (CI/CD pipeline setup) +- Related fragments: `selective-testing.md`, `playwright-config.md`, `test-quality.md` +- CI tools: GitHub Actions, GitLab CI, CircleCI, Jenkins + +_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples, SEON production pipelines_ diff --git a/src/modules/bmm/testarch/knowledge/component-tdd.md b/src/modules/bmm/testarch/knowledge/component-tdd.md index d73af37b..d14ba8f3 100644 --- a/src/modules/bmm/testarch/knowledge/component-tdd.md +++ b/src/modules/bmm/testarch/knowledge/component-tdd.md @@ -1,9 +1,486 @@ # Component Test-Driven Development Loop -- Start every UI change with a failing component spec (`cy.mount` or RTL `render`); ship only after red → green → refactor passes. -- Recreate providers/stores per spec to prevent state bleed and keep parallel runs deterministic. -- Use factories to exercise prop/state permutations; cover accessibility by asserting against roles, labels, and keyboard flows. -- Keep component specs under ~100 lines: split by intent (rendering, state transitions, error messaging) to preserve clarity. -- Pair component tests with visual debugging (Cypress runner, Storybook, Playwright trace viewer) to accelerate diagnosis. +## Principle -_Source: CCTDD repository, Murat component testing talks._ +Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality. + +## Rationale + +Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail. + +## Pattern Examples + +### Example 1: Red-Green-Refactor Loop + +**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality. + +**Implementation**: + +```typescript +// Step 1: RED - Write failing test +// Button.cy.tsx (Cypress Component Test) +import { Button } from './Button'; + +describe('Button Component', () => { + it('should render with label', () => { + cy.mount(; +}; + +// Run test: PASSES - Component renders and handles clicks + +// Step 3: REFACTOR - Improve implementation +// Add disabled state, loading state, variants +type ButtonProps = { + label: string; + onClick?: () => void; + disabled?: boolean; + loading?: boolean; + variant?: 'primary' | 'secondary' | 'danger'; +}; + +export const Button = ({ + label, + onClick, + disabled = false, + loading = false, + variant = 'primary' +}: ButtonProps) => { + return ( + + ); +}; + +// Step 4: Expand tests for new features +describe('Button Component', () => { + it('should render with label', () => { + cy.mount(