From 6cb0cc40fce232036f642a2fe320a7c5577f86fa Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sat, 14 Mar 2026 11:02:55 -0600 Subject: [PATCH] refactor(skills): convert create-epics-and-stories workflow to native skill (#1937) * refactor(skills): convert create-epics-and-stories workflow to native skill * fix(skills): normalize create-epics-and-stories metadata * fix: remove workflow_path indirection, use direct relative paths Replace the custom workflow_path variable with direct relative paths (../workflow.md, ../templates/epics-template.md) in all step files. Also remove duplicate epicsTemplate entry in step-01. Co-Authored-By: Claude Opus 4.6 (1M context) * fix: remove unused frontmatter refs from step files Drop thisStepFile, workflowFile, and epicsTemplate (where unused in body) from all step frontmatter. Only keep variables actually referenced in step body content. Co-Authored-By: Claude Opus 4.6 (1M context) * fix: convert partyModeWorkflow to skill ref, drop unused task refs - partyModeWorkflow now uses skill:bmad-party-mode (it is a skill) - remove advancedElicitationTask and partyModeWorkflow from steps 1/4 where they are not referenced in the body Co-Authored-By: Claude Opus 4.6 (1M context) * refactor: inline all frontmatter refs, use canonical skill invocation - Remove all file/task reference variables from step frontmatter - Inline paths directly where used in body text - Use canonical "invoke the skill" phrasing for skill references Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- src/bmm/agents/pm.agent.yaml | 2 +- src/bmm/module-help.csv | 2 +- .../bmad-create-epics-and-stories/SKILL.md | 6 ++++ .../bmad-skill-manifest.yaml | 1 + .../steps/step-01-validate-prerequisites.md | 31 ++++-------------- .../steps/step-02-design-epics.md | 30 ++++------------- .../steps/step-03-create-stories.md | 32 +++++-------------- .../steps/step-04-final-validation.md | 15 --------- .../templates/epics-template.md | 0 .../workflow.md | 7 +--- .../bmad-skill-manifest.yaml | 3 -- 11 files changed, 32 insertions(+), 97 deletions(-) create mode 100644 src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md create mode 100644 src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/bmad-skill-manifest.yaml rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/steps/step-01-validate-prerequisites.md (89%) rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/steps/step-02-design-epics.md (87%) rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/steps/step-03-create-stories.md (88%) rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/steps/step-04-final-validation.md (89%) rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/templates/epics-template.md (100%) rename src/bmm/workflows/3-solutioning/{create-epics-and-stories => bmad-create-epics-and-stories}/workflow.md (90%) delete mode 100644 src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml diff --git a/src/bmm/agents/pm.agent.yaml b/src/bmm/agents/pm.agent.yaml index 9c5d730f1..adbf8d8a7 100644 --- a/src/bmm/agents/pm.agent.yaml +++ b/src/bmm/agents/pm.agent.yaml @@ -32,7 +32,7 @@ agent: description: "[EP] Edit PRD: Update an existing Product Requirements Document" - trigger: CE or fuzzy match on epics-stories - exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md" + exec: "skill:bmad-create-epics-and-stories" description: "[CE] Create Epics and Stories: Create the Epics and Stories Listing, these are the specs that will drive development" - trigger: IR or fuzzy match on implementation-readiness diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv index 2e2c8448b..ab213e019 100644 --- a/src/bmm/module-help.csv +++ b/src/bmm/module-help.csv @@ -20,7 +20,7 @@ bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-pr bmm,2-planning,Edit PRD,EP,25,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md,bmad-bmm-edit-prd,false,pm,Edit Mode,"Improve and enhance an existing PRD",planning_artifacts,"updated prd", bmm,2-planning,Create UX,CU,30,skill:bmad-create-ux-design,bmad-bmm-create-ux-design,false,ux-designer,Create Mode,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project",planning_artifacts,"ux design", bmm,3-solutioning,Create Architecture,CA,10,skill:bmad-create-architecture,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture, -bmm,3-solutioning,Create Epics and Stories,CE,30,_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md,bmad-bmm-create-epics-and-stories,true,pm,Create Mode,"Create the Epics and Stories Listing",planning_artifacts,"epics and stories", +bmm,3-solutioning,Create Epics and Stories,CE,30,skill:bmad-create-epics-and-stories,bmad-bmm-create-epics-and-stories,true,pm,Create Mode,"Create the Epics and Stories Listing",planning_artifacts,"epics and stories", bmm,3-solutioning,Check Implementation Readiness,IR,70,skill:bmad-check-implementation-readiness,bmad-bmm-check-implementation-readiness,true,architect,Validate Mode,"Ensure PRD UX Architecture and Epics Stories are aligned",planning_artifacts,"readiness report", bmm,4-implementation,Sprint Planning,SP,10,_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md,bmad-bmm-sprint-planning,true,sm,Create Mode,"Generate sprint plan for development tasks - this kicks off the implementation phase by producing a plan the implementation agents will follow in sequence for every story in the plan.",implementation_artifacts,"sprint status", bmm,4-implementation,Sprint Status,SS,20,_bmad/bmm/workflows/4-implementation/sprint-status/workflow.md,bmad-bmm-sprint-status,false,sm,Create Mode,"Anytime: Summarize sprint status and route to next workflow",,, diff --git a/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md new file mode 100644 index 000000000..d1ce639b9 --- /dev/null +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-create-epics-and-stories +description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/bmad-skill-manifest.yaml b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md similarity index 89% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md index 60e9f21f4..25969ce95 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md @@ -1,23 +1,6 @@ --- name: 'step-01-validate-prerequisites' description: 'Validate required documents exist and extract all requirements for epic and story creation' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories' - -# File References -thisStepFile: './step-01-validate-prerequisites.md' -nextStepFile: './step-02-design-epics.md' -workflowFile: '{workflow_path}/workflow.md' -outputFile: '{planning_artifacts}/epics.md' -epicsTemplate: '{workflow_path}/templates/epics-template.md' - -# Task References -advancedElicitationTask: 'skill:bmad-advanced-elicitation' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' - -# Template References -epicsTemplate: '{workflow_path}/templates/epics-template.md' --- # Step 1: Validate Prerequisites and Extract Requirements @@ -54,7 +37,7 @@ To validate that all required input documents exist and extract all requirements ## EXECUTION PROTOCOLS: - 🎯 Extract requirements systematically from all documents -- 💾 Populate {outputFile} with extracted requirements +- 💾 Populate {planning_artifacts}/epics.md with extracted requirements - 📖 Update frontmatter with extraction progress - 🚫 FORBIDDEN to load next step until user selects 'C' and requirements are extracted @@ -91,7 +74,7 @@ Search for required documents using these patterns (sharded means a large docume 1. `{planning_artifacts}/*ux*.md` (whole document) 2. `{planning_artifacts}/*ux*/index.md` (sharded version) -Before proceeding, Ask the user if there are any other documents to include for analysis, and if anything found should be excluded. Wait for user confirmation. Once confirmed, create the {outputFile} from the {epicsTemplate} and in the front matter list the files in the array of `inputDocuments: []`. +Before proceeding, Ask the user if there are any other documents to include for analysis, and if anything found should be excluded. Wait for user confirmation. Once confirmed, create the {planning_artifacts}/epics.md from the ../templates/epics-template.md and in the front matter list the files in the array of `inputDocuments: []`. ### 3. Extract Functional Requirements (FRs) @@ -182,9 +165,9 @@ UX-DR2: [Actionable UX design requirement with clear implementation scope] ### 7. Load and Initialize Template -Load {epicsTemplate} and initialize {outputFile}: +Load ../templates/epics-template.md and initialize {planning_artifacts}/epics.md: -1. Copy the entire template to {outputFile} +1. Copy the entire template to {planning_artifacts}/epics.md 2. Replace {{project_name}} with the actual project name 3. Replace placeholder sections with extracted requirements: - {{fr_list}} → extracted FRs @@ -228,7 +211,7 @@ Update the requirements based on user feedback until confirmation is received. ## CONTENT TO SAVE TO DOCUMENT: -After extraction and confirmation, update {outputFile} with: +After extraction and confirmation, update {planning_artifacts}/epics.md with: - Complete FR list in {{fr_list}} section - Complete NFR list in {{nfr_list}} section @@ -247,12 +230,12 @@ Display: `**Confirm the Requirements are complete and correct to [C] continue:** #### Menu Handling Logic: -- IF C: Save all to {outputFile}, update frontmatter, then read fully and follow: {nextStepFile} +- IF C: Save all to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-02-design-epics.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options) ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN C is selected and all requirements are saved to document and frontmatter is updated, will you then read fully and follow: {nextStepFile} to begin epic design step. +ONLY WHEN C is selected and all requirements are saved to document and frontmatter is updated, will you then read fully and follow: ./step-02-design-epics.md to begin epic design step. --- diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.md similarity index 87% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.md index 6453c62ee..925b22e7b 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.md @@ -1,22 +1,6 @@ --- name: 'step-02-design-epics' description: 'Design and approve the epics_list that will organize all requirements into user-value-focused epics' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories' - -# File References -thisStepFile: './step-02-design-epics.md' -nextStepFile: './step-03-create-stories.md' -workflowFile: '{workflow_path}/workflow.md' -outputFile: '{planning_artifacts}/epics.md' - -# Task References -advancedElicitationTask: 'skill:bmad-advanced-elicitation' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' - -# Template References -epicsTemplate: '{workflow_path}/templates/epics-template.md' --- # Step 2: Design Epic List @@ -54,7 +38,7 @@ To design and get approval for the epics_list that will organize all requirement ## EXECUTION PROTOCOLS: - 🎯 Design epics collaboratively based on extracted requirements -- 💾 Update {{epics_list}} in {outputFile} +- 💾 Update {{epics_list}} in {planning_artifacts}/epics.md - 📖 Document the FR coverage mapping - 🚫 FORBIDDEN to load next step until user approves epics_list @@ -62,7 +46,7 @@ To design and get approval for the epics_list that will organize all requirement ### 1. Review Extracted Requirements -Load {outputFile} and review: +Load {planning_artifacts}/epics.md and review: - **Functional Requirements:** Count and review FRs from Step 1 - **Non-Functional Requirements:** Review NFRs that need to be addressed @@ -182,7 +166,7 @@ If user wants changes: ## CONTENT TO UPDATE IN DOCUMENT: -After approval, update {outputFile}: +After approval, update {planning_artifacts}/epics.md: 1. Replace {{epics_list}} placeholder with the approved epic list 2. Replace {{requirements_coverage_map}} with the coverage map @@ -194,9 +178,9 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont #### Menu Handling Logic: -- IF A: Read fully and follow: {advancedElicitationTask} -- IF P: Read fully and follow: {partyModeWorkflow} -- IF C: Save approved epics_list to {outputFile}, update frontmatter, then read fully and follow: {nextStepFile} +- IF A: Invoke the `bmad-advanced-elicitation` skill +- IF P: Invoke the `bmad-party-mode` skill +- IF C: Save approved epics_list to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-03-create-stories.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options) #### EXECUTION RULES: @@ -208,7 +192,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN C is selected and the approved epics_list is saved to document, will you then read fully and follow: {nextStepFile} to begin story creation step. +ONLY WHEN C is selected and the approved epics_list is saved to document, will you then read fully and follow: ./step-03-create-stories.md to begin story creation step. --- diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md similarity index 88% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md index 1bdbb0631..be6c72fe8 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md @@ -1,22 +1,6 @@ --- name: 'step-03-create-stories' description: 'Generate all epics with their stories following the template structure' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories' - -# File References -thisStepFile: './step-03-create-stories.md' -nextStepFile: './step-04-final-validation.md' -workflowFile: '{workflow_path}/workflow.md' -outputFile: '{planning_artifacts}/epics.md' - -# Task References -advancedElicitationTask: 'skill:bmad-advanced-elicitation' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' - -# Template References -epicsTemplate: '{workflow_path}/templates/epics-template.md' --- # Step 3: Generate Epics and Stories @@ -54,7 +38,7 @@ To generate all epics with their stories based on the approved epics_list, follo ## EXECUTION PROTOCOLS: - 🎯 Generate stories collaboratively with user input -- 💾 Append epics and stories to {outputFile} following template +- 💾 Append epics and stories to {planning_artifacts}/epics.md following template - 📖 Process epics one at a time in sequence - 🚫 FORBIDDEN to skip any epic or rush through stories @@ -62,7 +46,7 @@ To generate all epics with their stories based on the approved epics_list, follo ### 1. Load Approved Epic Structure -Load {outputFile} and review: +Load {planning_artifacts}/epics.md and review: - Approved epics_list from Step 2 - FR coverage map @@ -186,7 +170,7 @@ After writing each story: When story is approved: -- Append it to {outputFile} following template structure +- Append it to {planning_artifacts}/epics.md following template structure - Use correct numbering (Epic N, Story M) - Maintain proper markdown formatting @@ -215,7 +199,7 @@ After all epics and stories are generated: ## TEMPLATE STRUCTURE COMPLIANCE: -The final {outputFile} must follow this structure exactly: +The final {planning_artifacts}/epics.md must follow this structure exactly: 1. **Overview** section with project name 2. **Requirements Inventory** with all three subsections populated @@ -235,9 +219,9 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont #### Menu Handling Logic: -- IF A: Read fully and follow: {advancedElicitationTask} -- IF P: Read fully and follow: {partyModeWorkflow} -- IF C: Save content to {outputFile}, update frontmatter, then read fully and follow: {nextStepFile} +- IF A: Invoke the `bmad-advanced-elicitation` skill +- IF P: Invoke the `bmad-party-mode` skill +- IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md - IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options) #### EXECUTION RULES: @@ -249,7 +233,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Cont ## CRITICAL STEP COMPLETION NOTE -ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `{nextStepFile}` to begin final validation phase. +ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `./step-04-final-validation.md` to begin final validation phase. --- diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md similarity index 89% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md index 92bb71277..70cecf711 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md @@ -1,21 +1,6 @@ --- name: 'step-04-final-validation' description: 'Validate complete coverage of all requirements and ensure implementation readiness' - -# Path Definitions -workflow_path: '{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories' - -# File References -thisStepFile: './step-04-final-validation.md' -workflowFile: '{workflow_path}/workflow.md' -outputFile: '{planning_artifacts}/epics.md' - -# Task References -advancedElicitationTask: 'skill:bmad-advanced-elicitation' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' - -# Template References -epicsTemplate: '{workflow_path}/templates/epics-template.md' --- # Step 4: Final Validation diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/templates/epics-template.md similarity index 100% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/templates/epics-template.md diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/workflow.md similarity index 90% rename from src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md rename to src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/workflow.md index 41a6ee106..5845105d7 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md +++ b/src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/workflow.md @@ -1,8 +1,3 @@ ---- -name: create-epics-and-stories -description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"' ---- - # Create Epics and Stories **Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for development teams. @@ -55,4 +50,4 @@ Load and read full config from {project-root}/_bmad/bmm/config.yaml and resolve: ### 2. First Step EXECUTION -Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md` to begin the workflow. +Read fully and follow: `./steps/step-01-validate-prerequisites.md` to begin the workflow. diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml b/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml deleted file mode 100644 index 92b343dd9..000000000 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml +++ /dev/null @@ -1,3 +0,0 @@ -canonicalId: bmad-create-epics-and-stories -type: workflow -description: "Break requirements into epics and user stories"