BMad Agents menu items are logically ordered and marked with optional or recommended and some required tags

src/modules/bmm/agents/analyst.agent.yaml

@@ -20,19 +20,19 @@ agent:
   menu:
     - trigger: brainstorm-project
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml"
-      description: Guided Brainstorming scoped to product development ideation and problem discovery
+      description: Guided Brainstorming session with final report (optional)
 
     - trigger: research
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml"
-      description: Guided Research scoped to market and competitive analysis of a product or feature
+      description: Guided Research scoped to market and competitive analysis (optional)
 
     - trigger: product-brief
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-      description: Create a Product Brief, a great input to then drive a PRD
+      description: Create a Product Brief (recommended input for PRD)
 
     - trigger: document-project
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml"
-      description: Generate comprehensive documentation of an existing codebase, including architecture, data flows, and API contracts, and other details to aid project understanding.
+      description: Document your existing project (optional, but recommended for existing brownfield project efforts)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/architect.agent.yaml

@@ -20,23 +20,23 @@ agent:
   menu:
     - trigger: create-architecture
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture/workflow.yaml"
-      description: Produce a Scale Adaptive Architecture
+      description: Create an Architecture Document to Guide Development of a PRD (required for BMad Method projects)
 
     - trigger: validate-architecture
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture/workflow.yaml"
-      description: Validate Architecture Document
+      description: Validate Architecture Document (Recommended, use another LLM and fresh context for best results)
 
     - trigger: implementation-readiness
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness/workflow.yaml"
-      description: Validate implementation readiness - PRD, UX, Architecture, Epics aligned
+      description: Validate PRD, UX, Architecture, Epics and stories aligned (Optional but recommended before development)
 
     - trigger: create-excalidraw-diagram
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-diagram/workflow.yaml"
-      description: Create system architecture or technical diagram (Excalidraw)
+      description: Create system architecture or technical diagram (Excalidraw) (Use any time you need a diagram)
 
     - trigger: create-excalidraw-dataflow
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-dataflow/workflow.yaml"
-      description: Create data flow diagram (Excalidraw)
+      description: Create data flow diagram (Excalidraw) (Use any time you need a diagram)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/dev.agent.yaml

@@ -39,10 +39,6 @@ agent:
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow (full BMM path with sprint-status)"
 
-    - trigger: story-done
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done/workflow.yaml"
-      description: "Mark story done after DoD complete"
-
     - trigger: code-review
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review/workflow.yaml"
-      description: "Perform a thorough clean context QA code review on a story flagged Ready for Review"
+      description: "Perform a thorough clean context code review (Highly Recommended, use fresh context and different LLM)"

src/modules/bmm/agents/pm.agent.yaml

@@ -21,19 +21,19 @@ agent:
   menu:
     - trigger: create-prd
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
-      description: Create Product Requirements Document (PRD)
+      description: Create Product Requirements Document (PRD) (Required for BMad Method flow)
 
     - trigger: validate-prd
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
-      description: Validate PRD
+      description: Validate PRD (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: create-epics-and-stories
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml"
-      description: Create Epics and User Stories from PRD (Its recommended to not do this until the architecture is complete)
+      description: Create Epics and User Stories from PRD (Required for BMad Method flow AFTER the Architecture is completed)
 
     - trigger: correct-course
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: Course Correction Analysis
+      description: Course Correction Analysis (optional during implementation when things go off track)
       ide-only: true
 
     - trigger: party-mode

src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -21,15 +21,15 @@ agent:
   menu:
     - trigger: create-tech-spec
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml"
-      description: Architect a technical spec with implementation-ready stories
+      description: Architect a technical spec with implementation-ready stories (Required first step)
 
     - trigger: quick-dev
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml"
-      description: Ship features from spec or direct instructions - no handoffs
+      description: Implement the tech spec end-to-end solo (Core of Quick Flow)
 
     - trigger: code-review
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review/workflow.yaml"
-      description: Review code for quality, patterns, and acceptance criteria
+      description: Review code and improve it (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/sm.agent.yaml

@@ -26,24 +26,24 @@ agent:
   menu:
     - trigger: sprint-planning
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
-      description: Generate or update sprint-status.yaml from epic files
+      description: Generate or re-generate sprint-status.yaml from epic files (Required after Epics+Stories are created)
 
     - trigger: create-story
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: Create a Draft Story
+      description: Create a Draft Story (Required to prepare stories for development)
 
     - trigger: validate-create-story
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: (Optional) Validate Story Draft with Independent Review
+      description: Validate Story Draft (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: epic-retrospective
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective/workflow.yaml"
       data: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv"
-      description: (Optional) Facilitate team retrospective after an epic is completed
+      description: Facilitate team retrospective after an epic is completed (Optional)
 
     - trigger: correct-course
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: (Optional) Execute correct-course task
+      description: Execute correct-course task (When implementation is off-track)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/ux-designer.agent.yaml

@@ -25,7 +25,7 @@ agent:
   menu:
     - trigger: create-ux-design
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
-      description: Conduct Design Thinking Workshop to Define the User Specification with PRD as input
+      description: Generate a UX Design and UI Plan from a PRD (Recommended before creating Architecture)
 
     - trigger: validate-design
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"