From 063aa58b8def754372f67513c6089bf241660a2a Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Mon, 9 Mar 2026 19:02:27 -0600 Subject: [PATCH] chore(core): convert help.md to native skill directory (#1874) * chore(core): convert help.md to native skill directory Migrate the single-file help.md task to a bmad-help/ skill directory following the pattern established by bmad-review-adversarial-general. Update module-help.csv to use skill: reference and remove the entry from the parent manifest. Fix 7 BMM workflow step files that had hardcoded file path references to the now-relocated help task. Co-Authored-By: Claude Opus 4.6 * refactor(prompts): invoke bmad-help as a skill * style(prompts): format bmad-master agent yaml --------- Co-authored-by: Claude Opus 4.6 --- .../create-product-brief/steps/step-06-complete.md | 2 +- .../2-plan-workflows/create-prd/steps-c/step-12-complete.md | 2 +- .../create-prd/steps-v/step-v-13-report-complete.md | 2 +- .../create-ux-design/steps/step-14-complete.md | 2 +- .../steps/step-06-final-assessment.md | 2 +- .../create-architecture/steps/step-08-complete.md | 2 +- .../steps/step-04-final-validation.md | 2 +- src/core/agents/bmad-master.agent.yaml | 2 +- src/core/module-help.csv | 2 +- src/core/tasks/bmad-help/SKILL.md | 6 ++++++ src/core/tasks/bmad-help/bmad-skill-manifest.yaml | 1 + src/core/tasks/{help.md => bmad-help/workflow.md} | 4 ---- src/core/tasks/bmad-skill-manifest.yaml | 5 ----- src/utility/agent-components/activation-steps.txt | 4 ++-- 14 files changed, 18 insertions(+), 20 deletions(-) create mode 100644 src/core/tasks/bmad-help/SKILL.md create mode 100644 src/core/tasks/bmad-help/bmad-skill-manifest.yaml rename src/core/tasks/{help.md => bmad-help/workflow.md} (96%) diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md index 9e0955b77..7363f7c95 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md +++ b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md @@ -128,7 +128,7 @@ Recap that the brief captures everything needed to guide subsequent product deve ### 5. Suggest next steps -Product Brief complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +Product Brief complete. Invoke the `bmad-help` skill. --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md index 9f88be6ee..04204e8a9 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md @@ -87,7 +87,7 @@ Offer validation workflows to ensure PRD is ready for implementation: ### 4. Suggest Next Workflows -PRD complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +PRD complete. Invoke the `bmad-help` skill. ### 5. Final Completion Confirmation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md index 46c98f7f9..dd331bf48 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md @@ -197,7 +197,7 @@ Display: - **IF X (Exit):** - Display: "**Validation Report Saved:** {validationReportPath}" - Display: "**Summary:** {overall status} - {recommendation}" - - PRD Validation complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` + - PRD Validation complete. Invoke the `bmad-help` skill. - **IF Any other:** Help user, then redisplay menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md index 62a02cf45..73b07217d 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md @@ -82,7 +82,7 @@ Update the main workflow status file: ### 3. Suggest Next Steps -UX Design complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +UX Design complete. Invoke the `bmad-help` skill. ### 5. Final Completion Confirmation diff --git a/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md b/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md index fe80fc23a..548aa8f6d 100644 --- a/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md +++ b/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md @@ -109,7 +109,7 @@ The assessment found [number] issues requiring attention. Review the detailed re The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider. -Implementation Readiness complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +Implementation Readiness complete. Invoke the `bmad-help` skill. --- diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md index f44850b2b..e378fc97e 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md @@ -41,7 +41,7 @@ completedAt: '{{current_date}}' ### 3. Next Steps Guidance -Architecture complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +Architecture complete. Invoke the `bmad-help` skill. Upon Completion of task output: offer to answer any questions about the Architecture Document. diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md index adc3f497c..8d074e313 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md @@ -144,6 +144,6 @@ If all validations pass: When C is selected, the workflow is complete and the epics.md is ready for development. -Epics and Stories complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` +Epics and Stories complete. Invoke the `bmad-help` skill. Upon Completion of task output: offer to answer any questions about the Epics and Stories. diff --git a/src/core/agents/bmad-master.agent.yaml b/src/core/agents/bmad-master.agent.yaml index 1304c1cc9..796a91b38 100644 --- a/src/core/agents/bmad-master.agent.yaml +++ b/src/core/agents/bmad-master.agent.yaml @@ -18,7 +18,7 @@ agent: - Load resources at runtime, never pre-load, and always present numbered lists for choices. critical_actions: - - "Always greet the user and let them know they can use `/bmad-help` at any time to get advice on what to do next, and they can combine that with what they need help with `/bmad-help where should I start with an idea I have that does XYZ`" + - 'Always greet the user and let them know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and they can combine it with what they need help with Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"' menu: - trigger: "LT or fuzzy match on list-tasks" diff --git a/src/core/module-help.csv b/src/core/module-help.csv index ae873027d..9e8fe7f3e 100644 --- a/src/core/module-help.csv +++ b/src/core/module-help.csv @@ -1,7 +1,7 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,, core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",, -core,anytime,bmad-help,BH,,_bmad/core/tasks/help.md,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",, +core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",, core,anytime,Index Docs,ID,,_bmad/core/tasks/index-docs.xml,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",, core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",, core,anytime,Editorial Review - Prose,EP,,_bmad/core/tasks/editorial-review-prose.xml,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes", diff --git a/src/core/tasks/bmad-help/SKILL.md b/src/core/tasks/bmad-help/SKILL.md new file mode 100644 index 000000000..fbd6ff60e --- /dev/null +++ b/src/core/tasks/bmad-help/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-help +description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-help/bmad-skill-manifest.yaml b/src/core/tasks/bmad-help/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-help/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/help.md b/src/core/tasks/bmad-help/workflow.md similarity index 96% rename from src/core/tasks/help.md rename to src/core/tasks/bmad-help/workflow.md index 88f4a4d55..537f42322 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/bmad-help/workflow.md @@ -1,7 +1,3 @@ ---- -name: help -description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now' ---- # Task: BMAD Help diff --git a/src/core/tasks/bmad-skill-manifest.yaml b/src/core/tasks/bmad-skill-manifest.yaml index a332ba809..11d3c75a2 100644 --- a/src/core/tasks/bmad-skill-manifest.yaml +++ b/src/core/tasks/bmad-skill-manifest.yaml @@ -8,11 +8,6 @@ editorial-review-structure.xml: type: task description: "Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension" -help.md: - canonicalId: bmad-help - type: task - description: "Analyzes what is done and the users query and offers advice on what to do next" - index-docs.xml: canonicalId: bmad-index-docs type: task diff --git a/src/utility/agent-components/activation-steps.txt b/src/utility/agent-components/activation-steps.txt index abcc0e6fa..726be3e06 100644 --- a/src/utility/agent-components/activation-steps.txt +++ b/src/utility/agent-components/activation-steps.txt @@ -8,7 +8,7 @@ Remember: user's name is {user_name} {AGENT_SPECIFIC_STEPS} Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section - Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with `/bmad-help where should I start with an idea I have that does XYZ` + Let {user_name} know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and that they can combine it with what they need help with Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?" STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized" - When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (exec, tmpl, data, action, multi) and follow the corresponding handler instructions \ No newline at end of file + When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (exec, tmpl, data, action, multi) and follow the corresponding handler instructions