# Augment Code Review Guidelines for BMad-CORE # https://docs.augmentcode.com/codereview/overview # Focus: Workflow validation and quality file_paths_to_ignore: - "node_modules/**" - "build/**" - "dist/**" - "**/*.min.js" - "**/*.generated.*" - "**/*.bundle.md" - "**/validation-report-*.md" - "package-lock.json" - "*.png" - "*.jpg" - "*.svg" - "CHANGELOG.md" areas: # ============================================ # WORKFLOW STRUCTURE RULES # ============================================ workflow_structure: description: "Workflow folder organization and required components" globs: - "src/**/workflows/**" rules: - id: "workflow_entry_point_required" description: "Every workflow folder must have workflow.yaml, workflow.md, or workflow.xml as entry point" severity: "high" - id: "sharded_workflow_steps_folder" description: "Sharded workflows (using workflow.md) must have steps/ folder with numbered files (step-01-*.md, step-02-*.md)" severity: "high" - id: "standard_workflow_instructions" description: "Standard workflows using workflow.yaml must include instructions.md for execution guidance" severity: "medium" - id: "workflow_step_limit" description: "Workflows should have 5-10 steps maximum to prevent context loss in LLM execution" severity: "medium" # ============================================ # WORKFLOW ENTRY FILE RULES # ============================================ workflow_definitions: description: "Workflow entry files (workflow.yaml, workflow.md, workflow.xml)" globs: - "src/**/workflows/**/workflow.yaml" - "src/**/workflows/**/workflow.md" - "src/**/workflows/**/workflow.xml" rules: - id: "workflow_name_required" description: "Workflow entry files must define 'name' field in frontmatter or root element" severity: "high" - id: "workflow_description_required" description: "Workflow entry files must include 'description' explaining the workflow's purpose" severity: "high" - id: "workflow_config_source" description: "Workflows should reference config_source for variable resolution (e.g., {project-root}/_bmad/module/config.yaml)" severity: "medium" - id: "workflow_installed_path" description: "Workflows should define installed_path for relative file references within the workflow" severity: "medium" - id: "valid_step_references" description: "Step file references in workflow entry must point to existing files" severity: "high" # ============================================ # SHARDED WORKFLOW STEP RULES # ============================================ workflow_steps: description: "Individual step files in sharded workflows" globs: - "src/**/workflows/**/steps/step-*.md" rules: - id: "step_goal_required" description: "Each step must clearly state its goal (## STEP GOAL, ## YOUR TASK, or step n='X' goal='...')" severity: "high" - id: "step_mandatory_rules" description: "Step files should include MANDATORY EXECUTION RULES section with universal agent behavior rules" severity: "medium" - id: "step_context_boundaries" description: "Step files should define CONTEXT BOUNDARIES explaining available context and limits" severity: "medium" - id: "step_success_metrics" description: "Step files should include SUCCESS METRICS section with ✅ checkmarks for validation criteria" severity: "medium" - id: "step_failure_modes" description: "Step files should include FAILURE MODES section with ❌ marks for anti-patterns to avoid" severity: "medium" - id: "step_next_step_reference" description: "Step files should reference the next step file path for sequential execution" severity: "medium" - id: "step_no_forward_loading" description: "Steps must NOT load future step files until current step completes - just-in-time loading only" severity: "high" - id: "valid_file_references" description: "File path references using {variable}/filename.md must point to existing files" severity: "high" - id: "step_naming" description: "Step files must be named step-NN-description.md (e.g., step-01-init.md, step-02-context.md)" severity: "medium" - id: "halt_before_menu" description: "Steps presenting user menus ([C] Continue, [a] Advanced, etc.) must HALT and wait for response" severity: "high" # ============================================ # XML WORKFLOW/TASK RULES # ============================================ xml_workflows: description: "XML-based workflows and tasks" globs: - "src/**/workflows/**/*.xml" - "src/**/tasks/**/*.xml" rules: - id: "xml_task_id_required" description: "XML tasks must have unique 'id' attribute on root task element" severity: "high" - id: "xml_llm_instructions" description: "XML workflows should include section with critical execution instructions for the agent" severity: "medium" - id: "xml_step_numbering" description: "XML steps should use n='X' attribute for sequential numbering" severity: "medium" - id: "xml_action_tags" description: "Use for required actions, for user input (must HALT), for jumps, for conditionals" severity: "medium" - id: "xml_ask_must_halt" description: " tags require agent to HALT and wait for user response before continuing" severity: "high" # ============================================ # WORKFLOW CONTENT QUALITY # ============================================ workflow_content: description: "Content quality and consistency rules for all workflow files" globs: - "src/**/workflows/**/*.md" - "src/**/workflows/**/*.yaml" rules: - id: "communication_language_variable" description: "Workflows should use {communication_language} variable for agent output language consistency" severity: "low" - id: "path_placeholders_required" description: "Use path placeholders ({project-root}, {installed_path}, {output_folder}) instead of hardcoded paths" severity: "medium" - id: "no_time_estimates" description: "Workflows should NOT include time estimates - AI development speed varies significantly" severity: "low" - id: "facilitator_not_generator" description: "Workflow agents should act as facilitators (guide user input) not content generators (create without input)" severity: "medium" - id: "no_skip_optimization" description: "Workflows must execute steps sequentially - no skipping or 'optimizing' step order" severity: "high" # ============================================ # AGENT DEFINITIONS # ============================================ agent_definitions: description: "Agent YAML configuration files" globs: - "src/**/*.agent.yaml" rules: - id: "agent_metadata_required" description: "Agent files must have metadata section with id, name, title, icon, and module" severity: "high" - id: "agent_persona_required" description: "Agent files must define persona with role, identity, communication_style, and principles" severity: "high" - id: "agent_menu_valid_workflows" description: "Menu triggers must reference valid workflow paths that exist" severity: "high" # ============================================ # TEMPLATES # ============================================ templates: description: "Template files for workflow outputs" globs: - "src/**/template*.md" - "src/**/templates/**/*.md" rules: - id: "placeholder_syntax" description: "Use {variable_name} or {{variable_name}} syntax consistently for placeholders" severity: "medium" - id: "template_sections_marked" description: "Template sections that need generation should be clearly marked (e.g., )" severity: "low" # ============================================ # DOCUMENTATION # ============================================ documentation: description: "Documentation files" globs: - "docs/**/*.md" - "README.md" - "CONTRIBUTING.md" rules: - id: "valid_internal_links" description: "Internal markdown links must point to existing files" severity: "medium" # ============================================ # BUILD TOOLS # ============================================ build_tools: description: "Build scripts and tooling" globs: - "tools/**" rules: - id: "script_error_handling" description: "Scripts should handle errors gracefully with proper exit codes" severity: "medium"