From bad856cd339b516f6dce1f8c20935c0e2aea8e0c Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 12:01:57 +0000 Subject: [PATCH 01/22] Make workflow references platform-agnostic --- docs/tutorials/getting-started.md | 76 +++++++++++++++---------------- src/core/tasks/help.md | 55 +++++++--------------- 2 files changed, 52 insertions(+), 79 deletions(-) diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index 54a9b240d..1ba4780dd 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -65,11 +65,7 @@ The installer creates two folders: - `_bmad/` — agents, workflows, tasks, and configuration - `_bmad-output/` — empty for now, but this is where your artifacts will be saved -Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step. - -:::note[How to Load Agents and Run Workflows] -Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent). -::: +Open your AI IDE in the project folder. Run the `help` workflow (`bmad-help` on most platforms) to see what to do next — it detects what you've completed and recommends the next step. :::caution[Fresh Chats] Always start a fresh chat for each workflow. This prevents context limitations from causing issues. @@ -82,29 +78,29 @@ Work through phases 1-3. **Use fresh chats for each workflow.** ### Phase 1: Analysis (Optional) All workflows in this phase are optional: -- **brainstorming** (`/bmad-brainstorming`) — Guided ideation -- **research** (`/bmad-bmm-research`) — Market and technical research -- **create-product-brief** (`/bmad-bmm-create-product-brief`) — Recommended foundation document +- **brainstorming** — Guided ideation +- **research** — Market and technical research +- **create-product-brief** — Recommended foundation document ### Phase 2: Planning (Required) **For BMad Method and Enterprise tracks:** -1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run the `prd` workflow (`/bmad-bmm-create-prd`) +1. Load the **PM agent** in a new chat +2. Run the `prd` workflow 3. Output: `PRD.md` **For Quick Flow track:** -- Use the `quick-spec` workflow (`/bmad-bmm-quick-spec`) instead of PRD, then skip to implementation +- Use the `quick-spec` workflow instead of PRD, then skip to implementation :::note[UX Design (Optional)] -If your project has a user interface, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-create-ux-design`) after creating your PRD. +If your project has a user interface, load the **UX-Designer agent** and run the UX design workflow after creating your PRD. ::: ### Phase 3: Solutioning (BMad Method/Enterprise) **Create Architecture** -1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `create-architecture` (`/bmad-bmm-create-architecture`) +1. Load the **Architect agent** in a new chat +2. Run `create-architecture` 3. Output: Architecture document with technical decisions **Create Epics and Stories** @@ -113,13 +109,13 @@ If your project has a user interface, load the **UX-Designer agent** (`/bmad-age Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down. ::: -1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run `create-epics-and-stories` (`/bmad-bmm-create-epics-and-stories`) +1. Load the **PM agent** in a new chat +2. Run `create-epics-and-stories` 3. The workflow uses both PRD and Architecture to create technically-informed stories **Implementation Readiness Check** *(Highly Recommended)* -1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `check-implementation-readiness` (`/bmad-bmm-check-implementation-readiness`) +1. Load the **Architect agent** in a new chat +2. Run `check-implementation-readiness` 3. Validates cohesion across all planning documents ## Step 2: Build Your Project @@ -128,19 +124,19 @@ Once planning is complete, move to implementation. **Each workflow should run in ### Initialize Sprint Planning -Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories. +Load the **SM agent** and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories. ### The Build Cycle For each story, repeat this cycle with fresh chats: -| Step | Agent | Workflow | Command | Purpose | -| ---- | ----- | -------------- | -------------------------- | ---------------------------------- | -| 1 | SM | `create-story` | `/bmad-bmm-create-story` | Create story file from epic | -| 2 | DEV | `dev-story` | `/bmad-bmm-dev-story` | Implement the story | -| 3 | DEV | `code-review` | `/bmad-bmm-code-review` | Quality validation *(recommended)* | +| Step | Agent | Workflow | Purpose | +| ---- | ----- | -------------- | ---------------------------------- | +| 1 | SM | `create-story` | Create story file from epic | +| 2 | DEV | `dev-story` | Implement the story | +| 3 | DEV | `code-review` | Quality validation *(recommended)* | -After completing all stories in an epic, load the **SM agent** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-retrospective`). +After completing all stories in an epic, load the **SM agent** and run `retrospective`. ## What You've Accomplished @@ -166,17 +162,17 @@ your-project/ ## Quick Reference -| Workflow | Command | Agent | Purpose | -| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ | -| `help` | `/bmad-help` | Any | Get guidance on what to do next | -| `prd` | `/bmad-bmm-create-prd` | PM | Create Product Requirements Document | -| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | Create architecture document | -| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | Break down PRD into epics | -| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion | -| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | Initialize sprint tracking | -| `create-story` | `/bmad-bmm-create-story` | SM | Create a story file | -| `dev-story` | `/bmad-bmm-dev-story` | DEV | Implement a story | -| `code-review` | `/bmad-bmm-code-review` | DEV | Review implemented code | +| Workflow | Agent | Purpose | +| -------------------------------- | --------- | ------------------------------------ | +| `help` | Any | Get guidance on what to do next | +| `prd` | PM | Create Product Requirements Document | +| `create-architecture` | Architect | Create architecture document | +| `create-epics-and-stories` | PM | Break down PRD into epics | +| `check-implementation-readiness` | Architect | Validate planning cohesion | +| `sprint-planning` | SM | Initialize sprint tracking | +| `create-story` | SM | Create a story file | +| `dev-story` | DEV | Implement a story | +| `code-review` | DEV | Review implemented code | ## Common Questions @@ -184,10 +180,10 @@ your-project/ Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation. **Can I change my plan later?** -Yes. The SM agent has a `correct-course` workflow (`/bmad-bmm-correct-course`) for handling scope changes. +Yes. The SM agent has a `correct-course` workflow for handling scope changes. **What if I want to brainstorm first?** -Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bmad-brainstorming`) before starting your PRD. +Load the Analyst agent and run `brainstorming` before starting your PRD. **Do I need to follow a strict order?** Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above. @@ -196,14 +192,14 @@ Not strictly. Once you learn the flow, you can run workflows directly using the - **During workflows** — Agents guide you with questions and explanations - **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) -- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next +- **Stuck?** — Run `help` to see what to do next ## Key Takeaways :::tip[Remember These] - **Always use fresh chats** — Start a new chat for each workflow - **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture -- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps +- **Use `help` when stuck** — It detects your progress and suggests next steps ::: Ready to start? Install BMad and let the agents guide you through your first project. diff --git a/src/core/tasks/help.md b/src/core/tasks/help.md index c3c3fab11..e797d4fdc 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/help.md @@ -1,11 +1,12 @@ --- name: help description: Get unstuck by showing what workflow steps come next or answering questions about what to do +standalone: true --- # Task: BMAD Help -## ROUTING RULES +## KEY RULES - **Empty `phase` = anytime** — Universal tools work regardless of workflow state - **Numbered phases indicate sequence** — Phases like `1-discover` → `2-define` → `3-build` → `4-ship` flow in order (naming varies by module) @@ -14,26 +15,6 @@ description: Get unstuck by showing what workflow steps come next or answering q - **`required=true` blocks progress** — Required workflows must complete before proceeding to later phases - **Artifacts reveal completion** — Search resolved output paths for `outputs` patterns, fuzzy-match found files to workflow rows -## DISPLAY RULES - -### Command-Based Workflows -When `command` field has a value: -- Show the command prefixed with `/` (e.g., `/bmad-bmm-create-prd`) - -### Agent-Based Workflows -When `command` field is empty: -- User loads agent first via `/agent-command` -- Then invokes by referencing the `code` field or describing the `name` field -- Do NOT show a slash command — show the code value and agent load instruction instead - -Example presentation for empty command: -``` -Explain Concept (EC) -Load: /tech-writer, then ask to "EC about [topic]" -Agent: Tech Writer -Description: Create clear technical explanations with examples... -``` - ## MODULE DETECTION - **Empty `module` column** → universal tools (work across all modules) @@ -44,42 +25,38 @@ Detect the active module from conversation context, recent workflows, or user qu ## INPUT ANALYSIS Determine what was just completed: -- Explicit completion stated by user -- Workflow completed in current conversation -- Artifacts found matching `outputs` patterns -- If `index.md` exists, read it for additional context +- Did someone state they completed something? Proceed as if that was the input. +- Was a workflow just completed in this conversation? Proceed as if that was the input. +- Search resolved artifact locations for files; fuzzy-match to workflow `outputs` patterns. +- If an `index.md` exists, read it for additional context. - If still unclear, ask: "What workflow did you most recently complete?" ## EXECUTION 1. **Load catalog** — Load `{project-root}/_bmad/_config/bmad-help.csv` -2. **Resolve output locations and config** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. Also extract `communication_language` and `project_knowledge` from each scanned module's config. +2. **Resolve output locations** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. -3. **Ground in project knowledge** — If `project_knowledge` resolves to an existing path, read available documentation files (architecture docs, project overview, tech stack references) for grounding context. Use discovered project facts when composing any project-specific output. Never fabricate project-specific details — if documentation is unavailable, state so. +3. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. -4. **Detect active module** — Use MODULE DETECTION above +4. **Detect active module** — Use MODULE DETECTION above to determine which module the user is working in. -5. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. +5. **Present recommendations** — Show next steps based on completed workflows, phase/sequence ordering (KEY RULES), and artifact detection. Format per the following -6. **Present recommendations** — Show next steps based on: - - Completed workflows detected - - Phase/sequence ordering (ROUTING RULES) - - Artifact presence +## RECOMMENDED OUTPUT FORMAT **Optional items first** — List optional workflows until a required step is reached **Required items next** — List the next required workflow - - For each item, apply DISPLAY RULES above and include: + For each item show: - Workflow **name** - - **Command** OR **Code + Agent load instruction** (per DISPLAY RULES) + - **Command** (use the catalog command name; present it in your platform's command format, e.g., `bmad-example-build-prototype`) - **Agent** title and display name from the CSV (e.g., "🎨 Alex (Designer)") - Brief **description** -7. **Additional guidance to convey**: - - Present all output in `{communication_language}` + ### Additional response output guidance to convey: - Run each workflow in a **fresh context window** + - Load the agent using the platform's command format for `agent-command`, or run the workflow command directly - For **validation workflows**: recommend using a different high-quality LLM if available - For conversational requests: match the user's tone while presenting clearly -8. Return to the calling process after presenting recommendations. +6. Return to the calling process after presenting recommendations. From 405e60ce978899d02d291ff3ca527f6d312fe1b8 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 12:30:14 +0000 Subject: [PATCH 02/22] Convert remaining Phase 1 workflows to MD --- .../4-implementation/create-story/workflow.md | 360 ++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 src/bmm/workflows/4-implementation/create-story/workflow.md diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.md b/src/bmm/workflows/4-implementation/create-story/workflow.md new file mode 100644 index 000000000..a7aa49f8c --- /dev/null +++ b/src/bmm/workflows/4-implementation/create-story/workflow.md @@ -0,0 +1,360 @@ +--- +name: create-story +description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name`, `communication_language`, `document_output_language` + - `planning_artifacts`, `implementation_artifacts` + - `story_dir`, `default_output_file` + - `sprint_status`, `epics_file`, `prd_file`, `architecture_file`, `ux_file` + - `project_context` + - `date` (system-generated) + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + 🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or + disasters! 🔥 + Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent + EVERYTHING needed for flawless implementation + COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, + vague implementations, lying about completion, not learning from past work + 🚨 EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! + This is the most important function in the entire development process! + 🔬 UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly + analyze different artifacts simultaneously and thoroughly + ❓ SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is + written + 🎯 ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents + + + + Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth" + Set {{epic_num}}, {{story_num}}, {{story_key}} from user input + GOTO step 2a + + + Check if {{sprint_status}} file exists for auto discover + + 🚫 No sprint status file found and no story specified + + **Required Options:** + 1. Run `sprint-planning` to initialize sprint tracking (recommended) + 2. Provide specific epic-story number to create (e.g., "1-2-user-auth") + 3. Provide path to story documents if sprint status doesn't exist yet + + Choose option [1], provide epic-story number, path to story docs, or [q] to quit: + + + HALT - No work needed + + + + Run sprint-planning workflow first to create sprint-status.yaml + HALT - User needs to run sprint-planning + + + + Parse user input: extract epic_num, story_num, story_title + Set {{epic_num}}, {{story_num}}, {{story_key}} from user input + GOTO step 2a + + + + Use user-provided path for story documents + GOTO step 2a + + + + + + MUST read COMPLETE {sprint_status} file from start to end to preserve order + Load the FULL file: {{sprint_status}} + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "backlog" + + + + 📋 No backlog stories found in sprint-status.yaml + + All stories are either already created, in progress, or done. + + **Options:** + 1. Run sprint-planning to refresh story tracking + 2. Load PM agent and run correct-course to add more stories + 3. Check if current sprint is complete and run retrospective + + HALT + + + Extract from found story key (e.g., "1-2-user-authentication"): + - epic_num: first number before dash (e.g., "1") + - story_num: second number after first dash (e.g., "2") + - story_title: remainder after second dash (e.g., "user-authentication") + + Set {{story_id}} = "{{epic_num}}.{{story_num}}" + Store story_key for later use (e.g., "1-2-user-authentication") + + + Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern + + Load {{sprint_status}} and check epic-{{epic_num}} status + If epic status is "backlog" → update to "in-progress" + If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) + If epic status is "in-progress" → no change needed + + 🚫 ERROR: Cannot create story in completed epic + Epic {{epic_num}} is marked as 'done'. All stories are complete. + If you need to add more work, either: + 1. Manually change epic status back to 'in-progress' in sprint-status.yaml + 2. Create a new epic for additional work + HALT - Cannot proceed + + + 🚫 ERROR: Invalid epic status '{{epic_status}}' + Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done + Please fix sprint-status.yaml manually or run sprint-planning to regenerate + HALT - Cannot proceed + + 📊 Epic {{epic_num}} status updated to in-progress + + + GOTO step 2a + + Load the FULL file: {{sprint_status}} + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "backlog" + + + + 📋 No backlog stories found in sprint-status.yaml + + All stories are either already created, in progress, or done. + + **Options:** + 1. Run sprint-planning to refresh story tracking + 2. Load PM agent and run correct-course to add more stories + 3. Check if current sprint is complete and run retrospective + + HALT + + + Extract from found story key (e.g., "1-2-user-authentication"): + - epic_num: first number before dash (e.g., "1") + - story_num: second number after first dash (e.g., "2") + - story_title: remainder after second dash (e.g., "user-authentication") + + Set {{story_id}} = "{{epic_num}}.{{story_num}}" + Store story_key for later use (e.g., "1-2-user-authentication") + + + Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern + + Load {{sprint_status}} and check epic-{{epic_num}} status + If epic status is "backlog" → update to "in-progress" + If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) + If epic status is "in-progress" → no change needed + + 🚫 ERROR: Cannot create story in completed epic + Epic {{epic_num}} is marked as 'done'. All stories are complete. + If you need to add more work, either: + 1. Manually change epic status back to 'in-progress' in sprint-status.yaml + 2. Create a new epic for additional work + HALT - Cannot proceed + + + 🚫 ERROR: Invalid epic status '{{epic_status}}' + Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done + Please fix sprint-status.yaml manually or run sprint-planning to regenerate + HALT - Cannot proceed + + 📊 Epic {{epic_num}} status updated to in-progress + + + GOTO step 2a + + + + 🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups! + + + + Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, + {project_context} + + + From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic + objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story + statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to + original documents + Extract our story ({{epic_num}}-{{story_num}}) details: **STORY FOUNDATION:** - User story statement + (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - + Business context and value - Success criteria + + Load previous story file: {{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** - + Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their + patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract + all learnings that could impact current story implementation + + + + + Get last 5 commit titles to understand recent work patterns + Analyze 1-5 most recent commits for relevance to current story: + - Files created/modified + - Code patterns and conventions used + - Library dependencies added/changed + - Architecture decisions implemented + - Testing approaches used + + Extract actionable insights for current story implementation + + + + + 🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically + analyze architecture content for story-relevant requirements: + + + + Load complete {architecture_content} + + + Load architecture index and scan all architecture files + **CRITICAL ARCHITECTURE EXTRACTION:** For + each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with + versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint + patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:** + Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing + Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build + processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the + developer MUST follow + Identify any architectural decisions that override previous patterns + + + + 🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific + technical areas that require latest version knowledge: + + + From architecture analysis, identify specific libraries, APIs, or + frameworks + For each critical technology, research latest stable version and key changes: + - Latest API documentation and breaking changes + - Security vulnerabilities or updates + - Performance improvements or deprecations + - Best practices for current version + + **EXTERNAL CONTEXT INCLUSION:** Include in story any critical latest information the developer needs: + - Specific library versions and why chosen + - API endpoints with parameters and authentication + - Recent security patches or considerations + - Performance optimization techniques + - Migration considerations if upgrading + + + + + 📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide! + + Initialize from template.md: + {default_output_file} + story_header + + + story_requirements + + + + developer_context_section **DEV AGENT GUARDRAILS:** + technical_requirements + architecture_compliance + library_framework_requirements + + file_structure_requirements + testing_requirements + + + + previous_story_intelligence + + + + + git_intelligence_summary + + + + + latest_tech_information + + + + project_context_reference + + + + story_completion_status + + + Set story Status to: "ready-for-dev" + Add completion note: "Ultimate + context engine analysis completed - comprehensive developer guide created" + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml + Save story document unconditionally + + + + Update {{sprint_status}} + Load the FULL file and read all development_status entries + Find development_status key matching {{story_key}} + Verify current status is "backlog" (expected previous state) + Update development_status[{{story_key}}] = "ready-for-dev" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + Report completion + **🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!** + + **Story Details:** + - Story ID: {{story_id}} + - Story Key: {{story_key}} + - File: {{story_file}} + - Status: ready-for-dev + + **Next Steps:** + 1. Review the comprehensive story in {{story_file}} + 2. Run dev agents `dev-story` for optimized implementation + 3. Run `code-review` when complete (auto-marks done) + 4. Optional: Run TEA `*automate` after `dev-story` to generate guardrail tests + + **The developer now has everything needed for flawless implementation!** + + + + From 8d0702551f4aca30228448d85ba77ad073cad460 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 12:33:02 +0000 Subject: [PATCH 03/22] Add advanced-elicitation MD workflow and guard --- .../create-prd/steps-e/step-e-01-discovery.md | 4 +- .../create-prd/steps-e/step-e-02-review.md | 4 +- src/core/tasks/workflow.xml | 235 ------------------ test/test-installation-components.js | 48 ++++ 4 files changed, 52 insertions(+), 239 deletions(-) delete mode 100644 src/core/tasks/workflow.xml diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md index 8f47cd551..09f84b5f5 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md @@ -4,8 +4,8 @@ description: 'Discovery & Understanding - Understand what user wants to edit and # File references (ONLY variables used in this step) altStepFile: './step-e-01b-legacy-conversion.md' -prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +prdPurpose: '{project-root}/src/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md index f34de79ff..64e0acbb3 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md @@ -6,8 +6,8 @@ description: 'Deep Review & Analysis - Thoroughly review existing PRD and prepar nextStepFile: './step-e-03-edit.md' prdFile: '{prd_file_path}' validationReport: '{validation_report_path}' # If provided -prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +prdPurpose: '{project-root}/src/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' --- # Step E-2: Deep Review & Analysis diff --git a/src/core/tasks/workflow.xml b/src/core/tasks/workflow.xml deleted file mode 100644 index 536c9d8e7..000000000 --- a/src/core/tasks/workflow.xml +++ /dev/null @@ -1,235 +0,0 @@ - - Execute given workflow by loading its configuration, following instructions, and producing output - - - Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files - Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown - Execute ALL steps in instructions IN EXACT ORDER - Save to template output file after EVERY "template-output" tag - NEVER skip a step - YOU are responsible for every steps execution without fail or excuse - - - - Steps execute in exact numerical order (1, 2, 3...) - Optional steps: Ask user unless #yolo mode active - Template-output tags: Save content, discuss with the user the section completed, and NEVER proceed until the users indicates - to proceed (unless YOLO mode has been activated) - - - - - - Read workflow.yaml from provided path - Load config_source (REQUIRED for all modules) - Load external config from config_source path - Resolve all {config_source}: references with values from config - Resolve system variables (date:system-generated) and paths ({project-root}, {installed_path}) - Ask user for input of any variables that are still unknown - - - - Instructions: Read COMPLETE file from path OR embedded list (REQUIRED) - If template path → Read COMPLETE template file - If validation path → Note path for later loading when needed - If template: false → Mark as action-workflow (else template-workflow) - Data files (csv, json) → Store paths only, load on-demand when instructions reference them - - - - Resolve default_output_file path with all variables and {{date}} - Create output directory if doesn't exist - If template-workflow → Write template to output file with placeholders - If action-workflow → Skip file creation - - - - - For each step in instructions: - - - If optional="true" and NOT #yolo → Ask user to include - If if="condition" → Evaluate condition - If for-each="item" → Repeat step for each item - If repeat="n" → Repeat step n times - - - - Process step instructions (markdown or XML tags) - Replace {{variables}} with values (ask user if unknown) - - action xml tag → Perform the action - check if="condition" xml tag → Conditional block wrapping actions (requires closing </check>) - ask xml tag → Prompt user and WAIT for response - invoke-workflow xml tag → Execute another workflow with given inputs and the workflow.xml runner - invoke-task xml tag → Execute specified task - invoke-protocol name="protocol_name" xml tag → Execute reusable protocol from protocols section - goto step="x" → Jump to specified step - - - - - - Generate content for this section - Save to file (Write first time, Edit subsequent) - Display generated content - [a] Advanced Elicitation, [c] Continue, [p] Party-Mode, [y] YOLO the rest of this document only. WAIT for response. - Start the advanced elicitation workflow {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml - - - Continue to next step - - - Start the party-mode workflow {project-root}/_bmad/core/workflows/party-mode/workflow.md - - - Enter #yolo mode for the rest of the workflow - - - - - - - If no special tags and NOT #yolo: - Continue to next step? (y/n/edit) - - - - - Confirm document saved to output path - Report workflow completion - - - - - Full user interaction and confirmation of EVERY step at EVERY template output - NO EXCEPTIONS except yolo MODE - Skip all confirmations and elicitation, minimize prompts and try to produce all of the workflow automatically by - simulating the remaining discussions with an simulated expert user - - - - - step n="X" goal="..." - Define step with number and goal - optional="true" - Step can be skipped - if="condition" - Conditional execution - for-each="collection" - Iterate over items - repeat="n" - Repeat n times - - - action - Required action to perform - action if="condition" - Single conditional action (inline, no closing tag needed) - check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required) - ask - Get user input (ALWAYS wait for response before continuing) - goto - Jump to another step - invoke-workflow - Call another workflow - invoke-task - Call a task - invoke-protocol - Execute a reusable protocol (e.g., discover_inputs) - - - template-output - Save content checkpoint - critical - Cannot be skipped - example - Show example output - - - - - - Intelligently load project files (whole or sharded) based on workflow's input_file_patterns configuration - - Only execute if workflow.yaml contains input_file_patterns section - - - - Read input_file_patterns from loaded workflow.yaml - For each pattern group (prd, architecture, epics, etc.), note the load_strategy if present - - - - For each pattern in input_file_patterns: - - - - Determine load_strategy from pattern config (defaults to FULL_LOAD if not specified) - - - Load ALL files in sharded directory - used for PRD, Architecture, UX, brownfield docs - Use glob pattern to find ALL .md files (e.g., "{output_folder}/*architecture*/*.md") - Load EVERY matching file completely - Concatenate content in logical order (index.md first if exists, then alphabetical) - Store in variable: {pattern_name_content} - - - - Load specific shard using template variable - example: used for epics with {{epic_num}} - Check for template variables in sharded_single pattern (e.g., {{epic_num}}) - If variable undefined, ask user for value OR infer from context - Resolve template to specific file path - Load that specific file - Store in variable: {pattern_name_content} - - - - Load index.md, analyze structure and description of each doc in the index, then intelligently load relevant docs - DO NOT BE LAZY - use best judgment to load documents that might have relevant information, even if only a 5% chance - Load index.md from sharded directory - Parse table of contents, links, section headers - Analyze workflow's purpose and objective - Identify which linked/referenced documents are likely relevant - If workflow is about authentication and index shows "Auth Overview", "Payment Setup", "Deployment" → Load auth - docs, consider deployment docs, skip payment - Load all identified relevant documents - Store combined content in variable: {pattern_name_content} - When in doubt, LOAD IT - context is valuable, being thorough is better than missing critical info - - Mark pattern as RESOLVED, skip to next pattern - - - - - - Attempt glob match on 'whole' pattern (e.g., "{output_folder}/*prd*.md") - - Load ALL matching files completely (no offset/limit) - Store content in variable: {pattern_name_content} (e.g., {prd_content}) - Mark pattern as RESOLVED, skip to next pattern - - - - - - - Set {pattern_name_content} to empty string - Note in session: "No {pattern_name} files found" (not an error, just unavailable, offer use change to provide) - - - - - - List all loaded content variables with file counts - - ✓ Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ... - ✓ Loaded {architecture_content} from 1 file: Architecture.md - ✓ Loaded {epics_content} from selective load: epics/epic-3.md - ○ No ux_design files found - - This gives workflow transparency into what context is available - - - - - - - - - • This is the complete workflow execution engine - • You MUST Follow instructions exactly as written - • The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - • You MUST have already loaded and processed: {installed_path}/workflow.yaml - • This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context - • YOU ARE FACILITATING A CONVERSATION With a user to produce a final document step by step. The whole process is meant to be - collaborative helping the user flesh out their ideas. Do not rush or optimize and skip any section. - - - \ No newline at end of file diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 0970861b9..7310ebe5a 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -186,6 +186,54 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 6: Guard against advanced-elicitation XML references + // ============================================================ + console.log(`${colors.yellow}Test Suite 6: Advanced Elicitation Reference Guard${colors.reset}\n`); + + try { + const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs')]; + const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); + const forbiddenRef = 'advanced-elicitation/workflow.xml'; + const excludedFile = path.join(projectRoot, 'src', 'core', 'workflows', 'advanced-elicitation', 'workflow.xml'); + const offenders = []; + + const walk = async (dir) => { + const entries = await fs.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + await walk(fullPath); + continue; + } + if (!allowedExtensions.has(path.extname(entry.name))) { + continue; + } + if (fullPath === excludedFile) { + continue; + } + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); + } + } + }; + + for (const root of searchRoots) { + await walk(root); + } + + assert( + offenders.length === 0, + 'No advanced-elicitation/workflow.xml references outside XML source', + offenders.length > 0 ? offenders.join(', ') : '', + ); + } catch (error) { + assert(false, 'Advanced elicitation reference guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ From c769f1b44d8d50a0fbc14c7ce14b2708632bb754 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 14:19:05 +0000 Subject: [PATCH 04/22] Convert Phase 2/3 workflows to MD --- .../create-dataflow/instructions.md | 128 ++ .../create-diagram/instructions.md | 139 +++ .../create-flowchart/instructions.md | 239 ++++ .../create-wireframe/instructions.md | 131 +++ src/bmm/workflows/testarch/trace/checklist.md | 642 ++++++++++ .../workflows/testarch/trace/instructions.md | 1030 +++++++++++++++++ 6 files changed, 2309 insertions(+) create mode 100644 src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md create mode 100644 src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md create mode 100644 src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md create mode 100644 src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md create mode 100644 src/bmm/workflows/testarch/trace/checklist.md create mode 100644 src/bmm/workflows/testarch/trace/instructions.md diff --git a/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md new file mode 100644 index 000000000..bf4d988c0 --- /dev/null +++ b/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md @@ -0,0 +1,128 @@ +# Create Data Flow Diagram - Workflow Instructions + +```xml +This workflow creates data flow diagrams (DFD) in Excalidraw format. + + + + + Review user's request and extract: DFD level, processes, data stores, external entities + Skip to Step 4 + + + + Ask: "What level of DFD do you need?" + Present options: + 1. Context Diagram (Level 0) - Single process showing system boundaries + 2. Level 1 DFD - Major processes and data flows + 3. Level 2 DFD - Detailed sub-processes + 4. Custom - Specify your requirements + + WAIT for selection + + + + Ask: "Describe the processes, data stores, and external entities in your system" + WAIT for user description + Summarize what will be included and confirm with user + + + + Check for existing theme.json, ask to use if exists + + Ask: "Choose a DFD color scheme:" + Present numbered options: + 1. Standard DFD + - Process: #e3f2fd (light blue) + - Data Store: #e8f5e9 (light green) + - External Entity: #f3e5f5 (light purple) + - Border: #1976d2 (blue) + + 2. Colorful DFD + - Process: #fff9c4 (light yellow) + - Data Store: #c5e1a5 (light lime) + - External Entity: #ffccbc (light coral) + - Border: #f57c00 (orange) + + 3. Minimal DFD + - Process: #f5f5f5 (light gray) + - Data Store: #eeeeee (gray) + - External Entity: #e0e0e0 (medium gray) + - Border: #616161 (dark gray) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + + + + + List all processes with numbers (1.0, 2.0, etc.) + List all data stores (D1, D2, etc.) + List all external entities + Map all data flows with labels + Show planned structure, confirm with user + + + + Load {{templates}} and extract `dataflow` section + Load {{library}} + Load theme.json + Load {{helpers}} + + + + Follow standard DFD notation from {{helpers}} + + Build Order: + 1. External entities (rectangles, bold border) + 2. Processes (circles/ellipses with numbers) + 3. Data stores (parallel lines or rectangles) + 4. Data flows (labeled arrows) + + + DFD Rules: + - Processes: Numbered (1.0, 2.0), verb phrases + - Data stores: Named (D1, D2), noun phrases + - External entities: Named, noun phrases + - Data flows: Labeled with data names, arrows show direction + - No direct flow between external entities + - No direct flow between data stores + + + Layout: + - External entities at edges + - Processes in center + - Data stores between processes + - Minimize crossing flows + - Left-to-right or top-to-bottom flow + + + + + Verify DFD rules compliance + Strip unused elements and elements with isDeleted: true + Save to {{default_output_file}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user + + + + Validate against {{validation}} + + + +``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md new file mode 100644 index 000000000..7d64ccb1c --- /dev/null +++ b/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md @@ -0,0 +1,139 @@ +# Create Diagram - Workflow Instructions + +```xml +This workflow creates system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format. + + + + + Review user's request and extract: diagram type, components/entities, relationships, notation preferences + Skip to Step 5 + Only ask about missing info in Steps 1-2 + + + + Ask: "What type of technical diagram do you need?" + Present options: + 1. System Architecture + 2. Entity-Relationship Diagram (ERD) + 3. UML Class Diagram + 4. UML Sequence Diagram + 5. UML Use Case Diagram + 6. Network Diagram + 7. Other + + WAIT for selection + + + + Ask: "Describe the components/entities and their relationships" + Ask: "What notation standard? (Standard/Simplified/Strict UML-ERD)" + WAIT for user input + Summarize what will be included and confirm with user + + + + Check if theme.json exists at output location + Ask to use it, load if yes, else proceed to Step 4 + Proceed to Step 4 + + + + Ask: "Choose a color scheme for your diagram:" + Present numbered options: + 1. Professional + - Component: #e3f2fd (light blue) + - Database: #e8f5e9 (light green) + - Service: #fff3e0 (light orange) + - Border: #1976d2 (blue) + + 2. Colorful + - Component: #e1bee7 (light purple) + - Database: #c5e1a5 (light lime) + - Service: #ffccbc (light coral) + - Border: #7b1fa2 (purple) + + 3. Minimal + - Component: #f5f5f5 (light gray) + - Database: #eeeeee (gray) + - Service: #e0e0e0 (medium gray) + - Border: #616161 (dark gray) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + Show preview and confirm + + + + List all components/entities + Map all relationships + Show planned layout + Ask: "Structure looks correct? (yes/no)" + Adjust and repeat + + + + Load {{templates}} and extract `diagram` section + Load {{library}} + Load theme.json and merge with template + Load {{helpers}} for guidelines + + + + Follow {{helpers}} for proper element creation + + For Each Component: + - Generate unique IDs (component-id, text-id, group-id) + - Create shape with groupIds + - Calculate text width + - Create text with containerId and matching groupIds + - Add boundElements + + + For Each Connection: + - Determine arrow type (straight/elbow) + - Create with startBinding and endBinding + - Update boundElements on both components + + + Build Order by Type: + - Architecture: Services → Databases → Connections → Labels + - ERD: Entities → Attributes → Relationships → Cardinality + - UML Class: Classes → Attributes → Methods → Relationships + - UML Sequence: Actors → Lifelines → Messages → Returns + - UML Use Case: Actors → Use Cases → Relationships + + + Alignment: + - Snap to 20px grid + - Space: 40px between components, 60px between sections + + + + + Strip unused elements and elements with isDeleted: true + Save to {{default_output_file}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm: "Diagram created at {{default_output_file}}. Open to view?" + + + + Validate against {{validation}} using {_bmad}/core/tasks/validate-workflow.xml + + + +``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md new file mode 100644 index 000000000..925f2706c --- /dev/null +++ b/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md @@ -0,0 +1,239 @@ +# Create Flowchart - Workflow Instructions + +```xml +This workflow creates a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows. + + + + + Before asking any questions, analyze what the user has already told you + + Review the user's initial request and conversation history + Extract any mentioned: flowchart type, complexity, decision points, save location + + + Summarize your understanding + Skip directly to Step 4 (Plan Flowchart Layout) + + + + Note what you already know + Only ask about missing information in Step 1 + + + + Proceed with full elicitation in Step 1 + + + + + Ask Question 1: "What type of process flow do you need to visualize?" + Present numbered options: + 1. Business Process Flow - Document business workflows, approval processes, or operational procedures + 2. Algorithm/Logic Flow - Visualize code logic, decision trees, or computational processes + 3. User Journey Flow - Map user interactions, navigation paths, or experience flows + 4. Data Processing Pipeline - Show data transformation, ETL processes, or processing stages + 5. Other - Describe your specific flowchart needs + + WAIT for user selection (1-5) + + Ask Question 2: "How many main steps are in this flow?" + Present numbered options: + 1. Simple (3-5 steps) - Quick process with few decision points + 2. Medium (6-10 steps) - Standard workflow with some branching + 3. Complex (11-20 steps) - Detailed process with multiple decision points + 4. Very Complex (20+ steps) - Comprehensive workflow requiring careful layout + + WAIT for user selection (1-4) + Store selection in {{complexity}} + + Ask Question 3: "Does your flow include decision points (yes/no branches)?" + Present numbered options: + 1. No decisions - Linear flow from start to end + 2. Few decisions (1-2) - Simple branching with yes/no paths + 3. Multiple decisions (3-5) - Several conditional branches + 4. Complex decisions (6+) - Extensive branching logic + + WAIT for user selection (1-4) + Store selection in {{decision_points}} + + Ask Question 4: "Where should the flowchart be saved?" + Present numbered options: + 1. Default location - docs/flowcharts/[auto-generated-name].excalidraw + 2. Custom path - Specify your own file path + 3. Project root - Save in main project directory + 4. Specific folder - Choose from existing folders + + WAIT for user selection (1-4) + + Ask for specific path + WAIT for user input + + Store final path in {{default_output_file}} + + + + Check if theme.json exists at output location + + Ask: "Found existing theme. Use it? (yes/no)" + WAIT for user response + + Load and use existing theme + Skip to Step 4 + + + Proceed to Step 3 + + + + Proceed to Step 3 + + + + + Ask: "Let's create a theme for your flowchart. Choose a color scheme:" + Present numbered options: + 1. Professional Blue + - Primary Fill: #e3f2fd (light blue) + - Accent/Border: #1976d2 (blue) + - Decision: #fff3e0 (light orange) + - Text: #1e1e1e (dark gray) + + 2. Success Green + - Primary Fill: #e8f5e9 (light green) + - Accent/Border: #388e3c (green) + - Decision: #fff9c4 (light yellow) + - Text: #1e1e1e (dark gray) + + 3. Neutral Gray + - Primary Fill: #f5f5f5 (light gray) + - Accent/Border: #616161 (gray) + - Decision: #e0e0e0 (medium gray) + - Text: #1e1e1e (dark gray) + + 4. Warm Orange + - Primary Fill: #fff3e0 (light orange) + - Accent/Border: #f57c00 (orange) + - Decision: #ffe0b2 (peach) + - Text: #1e1e1e (dark gray) + + 5. Custom Colors - Define your own color palette + + WAIT for user selection (1-5) + Store selection in {{theme_choice}} + + + Ask: "Primary fill color (hex code)?" + WAIT for user input + Store in {{custom_colors.primary_fill}} + Ask: "Accent/border color (hex code)?" + WAIT for user input + Store in {{custom_colors.accent}} + Ask: "Decision color (hex code)?" + WAIT for user input + Store in {{custom_colors.decision}} + + + Create theme.json with selected colors + Show theme preview with all colors + Ask: "Theme looks good?" + Present numbered options: + 1. Yes, use this theme - Proceed with theme + 2. No, adjust colors - Modify color selections + 3. Start over - Choose different preset + + WAIT for selection (1-3) + + Repeat Step 3 + + + + + List all steps and decision points based on gathered requirements + Show user the planned structure + Ask: "Structure looks correct? (yes/no)" + WAIT for user response + + Adjust structure based on feedback + Repeat this step + + + + + Load {{templates}} file + Extract `flowchart` section from YAML + Load {{library}} file + Load theme.json and merge colors with template + Load {{helpers}} for element creation guidelines + + + + Follow guidelines from {{helpers}} for proper element creation + + Build ONE section at a time following these rules: + + For Each Shape with Label: + 1. Generate unique IDs (shape-id, text-id, group-id) + 2. Create shape with groupIds: [group-id] + 3. Calculate text width: (text.length × fontSize × 0.6) + 20, round to nearest 10 + 4. Create text element with: + - containerId: shape-id + - groupIds: [group-id] (SAME as shape) + - textAlign: "center" + - verticalAlign: "middle" + - width: calculated width + 5. Add boundElements to shape referencing text + + + For Each Arrow: + 1. Determine arrow type needed: + - Straight: For forward flow (left-to-right, top-to-bottom) + - Elbow: For upward flow, backward flow, or complex routing + 2. Create arrow with startBinding and endBinding + 3. Set startBinding.elementId to source shape ID + 4. Set endBinding.elementId to target shape ID + 5. Set gap: 10 for both bindings + 6. If elbow arrow, add intermediate points for direction changes + 7. Update boundElements on both connected shapes + + + Alignment: + - Snap all x, y to 20px grid + - Align shapes vertically (same x for vertical flow) + - Space elements: 60px between shapes + + + Build Order: + 1. Start point (circle) with label + 2. Each process step (rectangle) with label + 3. Each decision point (diamond) with label + 4. End point (circle) with label + 5. Connect all with bound arrows + + + + + Strip unused elements and elements with isDeleted: true + Save to {{default_output_file}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user: "Flowchart created at {{default_output_file}}. Open to view?" + + + + Validate against checklist at {{validation}} using {_bmad}/core/tasks/validate-workflow.xml + + + +``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md new file mode 100644 index 000000000..566b85578 --- /dev/null +++ b/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md @@ -0,0 +1,131 @@ +# Create Wireframe - Workflow Instructions + +```xml +This workflow creates website or app wireframes in Excalidraw format. + + + + + Review user's request and extract: wireframe type, fidelity level, screen count, device type, save location + Skip to Step 5 + + + + Ask: "What type of wireframe do you need?" + Present options: + 1. Website (Desktop) + 2. Mobile App (iOS/Android) + 3. Web App (Responsive) + 4. Tablet App + 5. Multi-platform + + WAIT for selection + + + + Ask fidelity level (Low/Medium/High) + Ask screen count (Single/Few 2-3/Multiple 4-6/Many 7+) + Ask device dimensions or use standard + Ask save location + + + + Check for existing theme.json, ask to use if exists + + + + Ask: "Choose a wireframe style:" + Present numbered options: + 1. Classic Wireframe + - Background: #ffffff (white) + - Container: #f5f5f5 (light gray) + - Border: #9e9e9e (gray) + - Text: #424242 (dark gray) + + 2. High Contrast + - Background: #ffffff (white) + - Container: #eeeeee (light gray) + - Border: #212121 (black) + - Text: #000000 (black) + + 3. Blueprint Style + - Background: #1a237e (dark blue) + - Container: #3949ab (blue) + - Border: #7986cb (light blue) + - Text: #ffffff (white) + + 4. Custom - Define your own colors + + WAIT for selection + Create theme.json based on selection + Confirm with user + + + + List all screens and their purposes + Map navigation flow between screens + Identify key UI elements for each screen + Show planned structure, confirm with user + + + + Load {{templates}} and extract `wireframe` section + Load {{library}} + Load theme.json + Load {{helpers}} + + + + Follow {{helpers}} for proper element creation + + For Each Screen: + - Create container/frame + - Add header section + - Add content areas + - Add navigation elements + - Add interactive elements (buttons, inputs) + - Add labels and annotations + + + Build Order: + 1. Screen containers + 2. Layout sections (header, content, footer) + 3. Navigation elements + 4. Content blocks + 5. Interactive elements + 6. Labels and annotations + 7. Flow indicators (if multi-screen) + + + Fidelity Guidelines: + - Low: Basic shapes, minimal detail, placeholder text + - Medium: More defined elements, some styling, representative content + - High: Detailed elements, realistic sizing, actual content examples + + + + + Strip unused elements and elements with isDeleted: true + Save to {{default_output_file}} + + + + NEVER delete the file if validation fails - always fix syntax errors + Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" + + Read the error message carefully - it shows the syntax error and position + Open the file and navigate to the error location + Fix the syntax error (add missing comma, bracket, or quote as indicated) + Save the file + Re-run validation with the same command + Repeat until validation passes + + Once validation passes, confirm with user + + + + Validate against {{validation}} + + + +``` diff --git a/src/bmm/workflows/testarch/trace/checklist.md b/src/bmm/workflows/testarch/trace/checklist.md new file mode 100644 index 000000000..7b1267177 --- /dev/null +++ b/src/bmm/workflows/testarch/trace/checklist.md @@ -0,0 +1,642 @@ +# Requirements Traceability & Gate Decision - Validation Checklist + +**Workflow:** `testarch-trace` +**Purpose:** Ensure complete traceability matrix with actionable gap analysis AND make deployment readiness decision (PASS/CONCERNS/FAIL/WAIVED) + +This checklist covers **two sequential phases**: + +- **PHASE 1**: Requirements Traceability (always executed) +- **PHASE 2**: Quality Gate Decision (executed if `enable_gate_decision: true`) + +--- + +# PHASE 1: REQUIREMENTS TRACEABILITY + +## Prerequisites Validation + +- [ ] Acceptance criteria are available (from story file OR inline) +- [ ] Test suite exists (or gaps are acknowledged and documented) +- [ ] If tests are missing, recommend `*atdd` (trace does not run it automatically) +- [ ] Test directory path is correct (`test_dir` variable) +- [ ] Story file is accessible (if using BMad mode) +- [ ] Knowledge base is loaded (test-priorities, traceability, risk-governance) + +--- + +## Context Loading + +- [ ] Story file read successfully (if applicable) +- [ ] Acceptance criteria extracted correctly +- [ ] Story ID identified (e.g., 1.3) +- [ ] `test-design.md` loaded (if available) +- [ ] `tech-spec.md` loaded (if available) +- [ ] `PRD.md` loaded (if available) +- [ ] Relevant knowledge fragments loaded from `tea-index.csv` + +--- + +## Test Discovery and Cataloging + +- [ ] Tests auto-discovered using multiple strategies (test IDs, describe blocks, file paths) +- [ ] Tests categorized by level (E2E, API, Component, Unit) +- [ ] Test metadata extracted: + - [ ] Test IDs (e.g., 1.3-E2E-001) + - [ ] Describe/context blocks + - [ ] It blocks (individual test cases) + - [ ] Given-When-Then structure (if BDD) + - [ ] Priority markers (P0/P1/P2/P3) +- [ ] All relevant test files found (no tests missed due to naming conventions) + +--- + +## Criteria-to-Test Mapping + +- [ ] Each acceptance criterion mapped to tests (or marked as NONE) +- [ ] Explicit references found (test IDs, describe blocks mentioning criterion) +- [ ] Test level documented (E2E, API, Component, Unit) +- [ ] Given-When-Then narrative verified for alignment +- [ ] Traceability matrix table generated: + - [ ] Criterion ID + - [ ] Description + - [ ] Test ID + - [ ] Test File + - [ ] Test Level + - [ ] Coverage Status + +--- + +## Coverage Classification + +- [ ] Coverage status classified for each criterion: + - [ ] **FULL** - All scenarios validated at appropriate level(s) + - [ ] **PARTIAL** - Some coverage but missing edge cases or levels + - [ ] **NONE** - No test coverage at any level + - [ ] **UNIT-ONLY** - Only unit tests (missing integration/E2E validation) + - [ ] **INTEGRATION-ONLY** - Only API/Component tests (missing unit confidence) +- [ ] Classification justifications provided +- [ ] Edge cases considered in FULL vs PARTIAL determination + +--- + +## Duplicate Coverage Detection + +- [ ] Duplicate coverage checked across test levels +- [ ] Acceptable overlap identified (defense in depth for critical paths) +- [ ] Unacceptable duplication flagged (same validation at multiple levels) +- [ ] Recommendations provided for consolidation +- [ ] Selective testing principles applied + +--- + +## Gap Analysis + +- [ ] Coverage gaps identified: + - [ ] Criteria with NONE status + - [ ] Criteria with PARTIAL status + - [ ] Criteria with UNIT-ONLY status + - [ ] Criteria with INTEGRATION-ONLY status +- [ ] Gaps prioritized by risk level using test-priorities framework: + - [ ] **CRITICAL** - P0 criteria without FULL coverage (BLOCKER) + - [ ] **HIGH** - P1 criteria without FULL coverage (PR blocker) + - [ ] **MEDIUM** - P2 criteria without FULL coverage (nightly gap) + - [ ] **LOW** - P3 criteria without FULL coverage (acceptable) +- [ ] Specific test recommendations provided for each gap: + - [ ] Suggested test level (E2E, API, Component, Unit) + - [ ] Test description (Given-When-Then) + - [ ] Recommended test ID (e.g., 1.3-E2E-004) + - [ ] Explanation of why test is needed + +--- + +## Coverage Metrics + +- [ ] Overall coverage percentage calculated (FULL coverage / total criteria) +- [ ] P0 coverage percentage calculated +- [ ] P1 coverage percentage calculated +- [ ] P2 coverage percentage calculated (if applicable) +- [ ] Coverage by level calculated: + - [ ] E2E coverage % + - [ ] API coverage % + - [ ] Component coverage % + - [ ] Unit coverage % + +--- + +## Test Quality Verification + +For each mapped test, verify: + +- [ ] Explicit assertions are present (not hidden in helpers) +- [ ] Test follows Given-When-Then structure +- [ ] No hard waits or sleeps (deterministic waiting only) +- [ ] Self-cleaning (test cleans up its data) +- [ ] File size < 300 lines +- [ ] Test duration < 90 seconds + +Quality issues flagged: + +- [ ] **BLOCKER** issues identified (missing assertions, hard waits, flaky patterns) +- [ ] **WARNING** issues identified (large files, slow tests, unclear structure) +- [ ] **INFO** issues identified (style inconsistencies, missing documentation) + +Knowledge fragments referenced: + +- [ ] `test-quality.md` for Definition of Done +- [ ] `fixture-architecture.md` for self-cleaning patterns +- [ ] `network-first.md` for Playwright best practices +- [ ] `data-factories.md` for test data patterns + +--- + +## Phase 1 Deliverables Generated + +### Traceability Matrix Markdown + +- [ ] File created at `{output_folder}/traceability-matrix.md` +- [ ] Template from `trace-template.md` used +- [ ] Full mapping table included +- [ ] Coverage status section included +- [ ] Gap analysis section included +- [ ] Quality assessment section included +- [ ] Recommendations section included + +### Coverage Badge/Metric (if enabled) + +- [ ] Badge markdown generated +- [ ] Metrics exported to JSON for CI/CD integration + +### Updated Story File (if enabled) + +- [ ] "Traceability" section added to story markdown +- [ ] Link to traceability matrix included +- [ ] Coverage summary included + +--- + +## Phase 1 Quality Assurance + +### Accuracy Checks + +- [ ] All acceptance criteria accounted for (none skipped) +- [ ] Test IDs correctly formatted (e.g., 1.3-E2E-001) +- [ ] File paths are correct and accessible +- [ ] Coverage percentages calculated correctly +- [ ] No false positives (tests incorrectly mapped to criteria) +- [ ] No false negatives (existing tests missed in mapping) + +### Completeness Checks + +- [ ] All test levels considered (E2E, API, Component, Unit) +- [ ] All priorities considered (P0, P1, P2, P3) +- [ ] All coverage statuses used appropriately (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) +- [ ] All gaps have recommendations +- [ ] All quality issues have severity and remediation guidance + +### Actionability Checks + +- [ ] Recommendations are specific (not generic) +- [ ] Test IDs suggested for new tests +- [ ] Given-When-Then provided for recommended tests +- [ ] Impact explained for each gap +- [ ] Priorities clear (CRITICAL, HIGH, MEDIUM, LOW) + +--- + +## Phase 1 Documentation + +- [ ] Traceability matrix is readable and well-formatted +- [ ] Tables render correctly in markdown +- [ ] Code blocks have proper syntax highlighting +- [ ] Links are valid and accessible +- [ ] Recommendations are clear and prioritized + +--- + +# PHASE 2: QUALITY GATE DECISION + +**Note**: Phase 2 executes only if `enable_gate_decision: true` in workflow.md + +--- + +## Prerequisites + +### Evidence Gathering + +- [ ] Test execution results obtained (CI/CD pipeline, test framework reports) +- [ ] Story/epic/release file identified and read +- [ ] Test design document discovered or explicitly provided (if available) +- [ ] Traceability matrix discovered or explicitly provided (available from Phase 1) +- [ ] NFR assessment discovered or explicitly provided (if available) +- [ ] Code coverage report discovered or explicitly provided (if available) +- [ ] Burn-in results discovered or explicitly provided (if available) + +### Evidence Validation + +- [ ] Evidence freshness validated (warn if >7 days old, recommend re-running workflows) +- [ ] All required assessments available or user acknowledged gaps +- [ ] Test results are complete (not partial or interrupted runs) +- [ ] Test results match current codebase (not from outdated branch) + +### Knowledge Base Loading + +- [ ] `risk-governance.md` loaded successfully +- [ ] `probability-impact.md` loaded successfully +- [ ] `test-quality.md` loaded successfully +- [ ] `test-priorities.md` loaded successfully +- [ ] `ci-burn-in.md` loaded (if burn-in results available) + +--- + +## Process Steps + +### Step 1: Context Loading + +- [ ] Gate type identified (story/epic/release/hotfix) +- [ ] Target ID extracted (story_id, epic_num, or release_version) +- [ ] Decision thresholds loaded from workflow variables +- [ ] Risk tolerance configuration loaded +- [ ] Waiver policy loaded + +### Step 2: Evidence Parsing + +**Test Results:** + +- [ ] Total test count extracted +- [ ] Passed test count extracted +- [ ] Failed test count extracted +- [ ] Skipped test count extracted +- [ ] Test duration extracted +- [ ] P0 test pass rate calculated +- [ ] P1 test pass rate calculated +- [ ] Overall test pass rate calculated + +**Quality Assessments:** + +- [ ] P0/P1/P2/P3 scenarios extracted from test-design.md (if available) +- [ ] Risk scores extracted from test-design.md (if available) +- [ ] Coverage percentages extracted from traceability-matrix.md (available from Phase 1) +- [ ] Coverage gaps extracted from traceability-matrix.md (available from Phase 1) +- [ ] NFR status extracted from nfr-assessment.md (if available) +- [ ] Security issues count extracted from nfr-assessment.md (if available) + +**Code Coverage:** + +- [ ] Line coverage percentage extracted (if available) +- [ ] Branch coverage percentage extracted (if available) +- [ ] Function coverage percentage extracted (if available) +- [ ] Critical path coverage validated (if available) + +**Burn-in Results:** + +- [ ] Burn-in iterations count extracted (if available) +- [ ] Flaky tests count extracted (if available) +- [ ] Stability score calculated (if available) + +### Step 3: Decision Rules Application + +**P0 Criteria Evaluation:** + +- [ ] P0 test pass rate evaluated (must be 100%) +- [ ] P0 acceptance criteria coverage evaluated (must be 100%) +- [ ] Security issues count evaluated (must be 0) +- [ ] Critical NFR failures evaluated (must be 0) +- [ ] Flaky tests evaluated (must be 0 if burn-in enabled) +- [ ] P0 decision recorded: PASS or FAIL + +**P1 Criteria Evaluation:** + +- [ ] P1 test pass rate evaluated (threshold: min_p1_pass_rate) +- [ ] P1 acceptance criteria coverage evaluated (threshold: 95%) +- [ ] Overall test pass rate evaluated (threshold: min_overall_pass_rate) +- [ ] Code coverage evaluated (threshold: min_coverage) +- [ ] P1 decision recorded: PASS or CONCERNS + +**P2/P3 Criteria Evaluation:** + +- [ ] P2 failures tracked (informational, don't block if allow_p2_failures: true) +- [ ] P3 failures tracked (informational, don't block if allow_p3_failures: true) +- [ ] Residual risks documented + +**Final Decision:** + +- [ ] Decision determined: PASS / CONCERNS / FAIL / WAIVED +- [ ] Decision rationale documented +- [ ] Decision is deterministic (follows rules, not arbitrary) + +### Step 4: Documentation + +**Gate Decision Document Created:** + +- [ ] Story/epic/release info section complete (ID, title, description, links) +- [ ] Decision clearly stated (PASS / CONCERNS / FAIL / WAIVED) +- [ ] Decision date recorded +- [ ] Evaluator recorded (user or agent name) + +**Evidence Summary Documented:** + +- [ ] Test results summary complete (total, passed, failed, pass rates) +- [ ] Coverage summary complete (P0/P1 criteria, code coverage) +- [ ] NFR validation summary complete (security, performance, reliability, maintainability) +- [ ] Flakiness summary complete (burn-in iterations, flaky test count) + +**Rationale Documented:** + +- [ ] Decision rationale clearly explained +- [ ] Key evidence highlighted +- [ ] Assumptions and caveats noted (if any) + +**Residual Risks Documented (if CONCERNS or WAIVED):** + +- [ ] Unresolved P1/P2 issues listed +- [ ] Probability × impact estimated for each risk +- [ ] Mitigations or workarounds described + +**Waivers Documented (if WAIVED):** + +- [ ] Waiver reason documented (business justification) +- [ ] Waiver approver documented (name, role) +- [ ] Waiver expiry date documented +- [ ] Remediation plan documented (fix in next release, due date) +- [ ] Monitoring plan documented + +**Critical Issues Documented (if FAIL or CONCERNS):** + +- [ ] Top 5-10 critical issues listed +- [ ] Priority assigned to each issue (P0/P1/P2) +- [ ] Owner assigned to each issue +- [ ] Due date assigned to each issue + +**Recommendations Documented:** + +- [ ] Next steps clearly stated for decision type +- [ ] Deployment recommendation provided +- [ ] Monitoring recommendations provided (if applicable) +- [ ] Remediation recommendations provided (if applicable) + +### Step 5: Status Updates and Notifications + +**Gate YAML Created:** + +- [ ] Gate YAML snippet generated with decision and criteria +- [ ] Evidence references included in YAML +- [ ] Next steps included in YAML +- [ ] YAML file saved to output folder + +**Stakeholder Notification Generated:** + +- [ ] Notification subject line created +- [ ] Notification body created with summary +- [ ] Recipients identified (PM, SM, DEV lead, stakeholders) +- [ ] Notification ready for delivery (if notify_stakeholders: true) + +**Outputs Saved:** + +- [ ] Gate decision document saved to `{output_file}` +- [ ] Gate YAML saved to `{output_folder}/gate-decision-{target}.yaml` +- [ ] All outputs are valid and readable + +--- + +## Phase 2 Output Validation + +### Gate Decision Document + +**Completeness:** + +- [ ] All required sections present (info, decision, evidence, rationale, next steps) +- [ ] No placeholder text or TODOs left in document +- [ ] All evidence references are accurate and complete +- [ ] All links to artifacts are valid + +**Accuracy:** + +- [ ] Decision matches applied criteria rules +- [ ] Test results match CI/CD pipeline output +- [ ] Coverage percentages match reports +- [ ] NFR status matches assessment document +- [ ] No contradictions or inconsistencies + +**Clarity:** + +- [ ] Decision rationale is clear and unambiguous +- [ ] Technical jargon is explained or avoided +- [ ] Stakeholders can understand next steps +- [ ] Recommendations are actionable + +### Gate YAML + +**Format:** + +- [ ] YAML is valid (no syntax errors) +- [ ] All required fields present (target, decision, date, evaluator, criteria, evidence) +- [ ] Field values are correct data types (numbers, strings, dates) + +**Content:** + +- [ ] Criteria values match decision document +- [ ] Evidence references are accurate +- [ ] Next steps align with decision type + +--- + +## Phase 2 Quality Checks + +### Decision Integrity + +- [ ] Decision is deterministic (follows rules, not arbitrary) +- [ ] P0 failures result in FAIL decision (unless waived) +- [ ] Security issues result in FAIL decision (unless waived - but should never be waived) +- [ ] Waivers have business justification and approver (if WAIVED) +- [ ] Residual risks are documented (if CONCERNS or WAIVED) + +### Evidence-Based + +- [ ] Decision is based on actual test results (not guesses) +- [ ] All claims are supported by evidence +- [ ] No assumptions without documentation +- [ ] Evidence sources are cited (CI run IDs, report URLs) + +### Transparency + +- [ ] Decision rationale is transparent and auditable +- [ ] Criteria evaluation is documented step-by-step +- [ ] Any deviations from standard process are explained +- [ ] Waiver justifications are clear (if applicable) + +### Consistency + +- [ ] Decision aligns with risk-governance knowledge fragment +- [ ] Priority framework (P0/P1/P2/P3) applied consistently +- [ ] Terminology consistent with test-quality knowledge fragment +- [ ] Decision matrix followed correctly + +--- + +## Phase 2 Integration Points + +### CI/CD Pipeline + +- [ ] Gate YAML is CI/CD-compatible +- [ ] YAML can be parsed by pipeline automation +- [ ] Decision can be used to block/allow deployments +- [ ] Evidence references are accessible to pipeline + +### Stakeholders + +- [ ] Notification message is clear and actionable +- [ ] Decision is explained in non-technical terms +- [ ] Next steps are specific and time-bound +- [ ] Recipients are appropriate for decision type + +--- + +## Phase 2 Compliance and Audit + +### Audit Trail + +- [ ] Decision date and time recorded +- [ ] Evaluator identified (user or agent) +- [ ] All evidence sources cited +- [ ] Decision criteria documented +- [ ] Rationale clearly explained + +### Traceability + +- [ ] Gate decision traceable to story/epic/release +- [ ] Evidence traceable to specific test runs +- [ ] Assessments traceable to workflows that created them +- [ ] Waiver traceable to approver (if applicable) + +### Compliance + +- [ ] Security requirements validated (no unresolved vulnerabilities) +- [ ] Quality standards met or waived with justification +- [ ] Regulatory requirements addressed (if applicable) +- [ ] Documentation sufficient for external audit + +--- + +## Phase 2 Edge Cases and Exceptions + +### Missing Evidence + +- [ ] If test-design.md missing, decision still possible with test results + trace +- [ ] If traceability-matrix.md missing, decision still possible with test results (but Phase 1 should provide it) +- [ ] If nfr-assessment.md missing, NFR validation marked as NOT ASSESSED +- [ ] If code coverage missing, coverage criterion marked as NOT ASSESSED +- [ ] User acknowledged gaps in evidence or provided alternative proof + +### Stale Evidence + +- [ ] Evidence freshness checked (if validate_evidence_freshness: true) +- [ ] Warnings issued for assessments >7 days old +- [ ] User acknowledged stale evidence or re-ran workflows +- [ ] Decision document notes any stale evidence used + +### Conflicting Evidence + +- [ ] Conflicts between test results and assessments resolved +- [ ] Most recent/authoritative source identified +- [ ] Conflict resolution documented in decision rationale +- [ ] User consulted if conflict cannot be resolved + +### Waiver Scenarios + +- [ ] Waiver only used for FAIL decision (not PASS or CONCERNS) +- [ ] Waiver has business justification (not technical convenience) +- [ ] Waiver has named approver with authority (VP/CTO/PO) +- [ ] Waiver has expiry date (does NOT apply to future releases) +- [ ] Waiver has remediation plan with concrete due date +- [ ] Security vulnerabilities are NOT waived (enforced) + +--- + +# FINAL VALIDATION (Both Phases) + +## Non-Prescriptive Validation + +- [ ] Traceability format adapted to team needs (not rigid template) +- [ ] Examples are minimal and focused on patterns +- [ ] Teams can extend with custom classifications +- [ ] Integration with external systems supported (JIRA, Azure DevOps) +- [ ] Compliance requirements considered (if applicable) + +--- + +## Documentation and Communication + +- [ ] All documents are readable and well-formatted +- [ ] Tables render correctly in markdown +- [ ] Code blocks have proper syntax highlighting +- [ ] Links are valid and accessible +- [ ] Recommendations are clear and prioritized +- [ ] Gate decision is prominent and unambiguous (Phase 2) + +--- + +## Final Validation + +**Phase 1 (Traceability):** + +- [ ] All prerequisites met +- [ ] All acceptance criteria mapped or gaps documented +- [ ] P0 coverage is 100% OR documented as BLOCKER +- [ ] Gap analysis is complete and prioritized +- [ ] Test quality issues identified and flagged +- [ ] Deliverables generated and saved + +**Phase 2 (Gate Decision):** + +- [ ] All quality evidence gathered +- [ ] Decision criteria applied correctly +- [ ] Decision rationale documented +- [ ] Gate YAML ready for CI/CD integration +- [ ] Status file updated (if enabled) +- [ ] Stakeholders notified (if enabled) + +**Workflow Complete:** + +- [ ] Phase 1 completed successfully +- [ ] Phase 2 completed successfully (if enabled) +- [ ] All outputs validated and saved +- [ ] Ready to proceed based on gate decision + +--- + +## Sign-Off + +**Phase 1 - Traceability Status:** + +- [ ] ✅ PASS - All quality gates met, no critical gaps +- [ ] ⚠️ WARN - P1 gaps exist, address before PR merge +- [ ] ❌ FAIL - P0 gaps exist, BLOCKER for release + +**Phase 2 - Gate Decision Status (if enabled):** + +- [ ] ✅ PASS - Deploy to production +- [ ] ⚠️ CONCERNS - Deploy with monitoring +- [ ] ❌ FAIL - Block deployment, fix issues +- [ ] 🔓 WAIVED - Deploy with business approval and remediation plan + +**Next Actions:** + +- If PASS (both phases): Proceed to deployment +- If WARN/CONCERNS: Address gaps/issues, proceed with monitoring +- If FAIL (either phase): Run `*atdd` for missing tests, fix issues, re-run `*trace` +- If WAIVED: Deploy with approved waiver, schedule remediation + +--- + +## Notes + +Record any issues, deviations, or important observations during workflow execution: + +- **Phase 1 Issues**: [Note any traceability mapping challenges, missing tests, quality concerns] +- **Phase 2 Issues**: [Note any missing, stale, or conflicting evidence] +- **Decision Rationale**: [Document any nuanced reasoning or edge cases] +- **Waiver Details**: [Document waiver negotiations or approvals] +- **Follow-up Actions**: [List any actions required after gate decision] + +--- + + diff --git a/src/bmm/workflows/testarch/trace/instructions.md b/src/bmm/workflows/testarch/trace/instructions.md new file mode 100644 index 000000000..3cf4bd5be --- /dev/null +++ b/src/bmm/workflows/testarch/trace/instructions.md @@ -0,0 +1,1030 @@ +# Test Architect Workflow: Requirements Traceability & Quality Gate Decision + +**Workflow:** `testarch-trace` +**Purpose:** Generate requirements-to-tests traceability matrix, analyze coverage gaps, and make quality gate decisions (PASS/CONCERNS/FAIL/WAIVED) +**Agent:** Test Architect (TEA) +**Format:** Pure Markdown v4.0 (no XML blocks) + +--- + +## Overview + +This workflow operates in two sequential phases to validate test coverage and deployment readiness: + +**PHASE 1 - REQUIREMENTS TRACEABILITY:** Create comprehensive traceability matrix mapping acceptance criteria to implemented tests, identify coverage gaps, and provide actionable recommendations. + +**PHASE 2 - QUALITY GATE DECISION:** Use traceability results combined with test execution evidence to make gate decisions (PASS/CONCERNS/FAIL/WAIVED) that determine deployment readiness. + +**Key Capabilities:** + +- Map acceptance criteria to specific test cases across all levels (E2E, API, Component, Unit) +- Classify coverage status (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) +- Prioritize gaps by risk level (P0/P1/P2/P3) using test-priorities framework +- Apply deterministic decision rules based on coverage and test execution results +- Generate gate decisions with evidence and rationale +- Support waivers for business-approved exceptions +- Update workflow status and notify stakeholders + +--- + +## Prerequisites + +**Required (Phase 1):** + +- Acceptance criteria (from story file OR provided inline) +- Implemented test suite (or acknowledge gaps to be addressed) + +**Required (Phase 2 - if `enable_gate_decision: true`):** + +- Test execution results (CI/CD test reports, pass/fail rates) +- Test design with risk priorities (P0/P1/P2/P3) + +**Recommended:** + +- `test-design.md` (for risk assessment and priority context) +- `nfr-assessment.md` (for release-level gates) +- `tech-spec.md` (for technical implementation context) +- Test framework configuration (playwright.config.ts, jest.config.js, etc.) + +**Halt Conditions:** + +- If story lacks any implemented tests AND no gaps are acknowledged, recommend running `*atdd` workflow first +- If acceptance criteria are completely missing, halt and request them +- If Phase 2 enabled but test execution results missing, warn and skip gate decision + +Note: `*trace` never runs `*atdd` automatically; it only recommends running it when tests are missing. + +--- + +## PHASE 1: REQUIREMENTS TRACEABILITY + +This phase focuses on mapping requirements to tests, analyzing coverage, and identifying gaps. + +--- + +### Step 1: Load Context and Knowledge Base + +**Actions:** + +1. Load relevant knowledge fragments from `{project-root}/_bmad/bmm/testarch/tea-index.csv`: + - `test-priorities-matrix.md` - P0/P1/P2/P3 risk framework with automated priority calculation, risk-based mapping, tagging strategy (389 lines, 2 examples) + - `risk-governance.md` - Risk-based testing approach: 6 categories (TECH, SEC, PERF, DATA, BUS, OPS), automated scoring, gate decision engine, coverage traceability (625 lines, 4 examples) + - `probability-impact.md` - Risk scoring methodology: probability × impact matrix, automated classification, dynamic re-assessment, gate integration (604 lines, 4 examples) + - `test-quality.md` - Definition of Done for tests: deterministic, isolated with cleanup, explicit assertions, length/time limits (658 lines, 5 examples) + - `selective-testing.md` - Duplicate coverage patterns: tag-based, spec filters, diff-based selection, promotion rules (727 lines, 4 examples) + +2. Read story file (if provided): + - Extract acceptance criteria + - Identify story ID (e.g., 1.3) + - Note any existing test design or priority information + +3. Read related BMad artifacts (if available): + - `test-design.md` - Risk assessment and test priorities + - `tech-spec.md` - Technical implementation details + - `PRD.md` - Product requirements context + +**Output:** Complete understanding of requirements, priorities, and existing context + +--- + +### Step 2: Discover and Catalog Tests + +**Actions:** + +1. Auto-discover test files related to the story: + - Search for test IDs (e.g., `1.3-E2E-001`, `1.3-UNIT-005`) + - Search for describe blocks mentioning feature name + - Search for file paths matching feature directory + - Use `glob` to find test files in `{test_dir}` + +2. Categorize tests by level: + - **E2E Tests**: Full user journeys through UI + - **API Tests**: HTTP contract and integration tests + - **Component Tests**: UI component behavior in isolation + - **Unit Tests**: Business logic and pure functions + +3. Extract test metadata: + - Test ID (if present) + - Describe/context blocks + - It blocks (individual test cases) + - Given-When-Then structure (if BDD) + - Assertions used + - Priority markers (P0/P1/P2/P3) + +**Output:** Complete catalog of all tests for this feature + +--- + +### Step 3: Map Criteria to Tests + +**Actions:** + +1. For each acceptance criterion: + - Search for explicit references (test IDs, describe blocks mentioning criterion) + - Map to specific test files and it blocks + - Use Given-When-Then narrative to verify alignment + - Document test level (E2E, API, Component, Unit) + +2. Build traceability matrix: + + ``` + | Criterion ID | Description | Test ID | Test File | Test Level | Coverage Status | + | ------------ | ----------- | ----------- | ---------------- | ---------- | --------------- | + | AC-1 | User can... | 1.3-E2E-001 | e2e/auth.spec.ts | E2E | FULL | + ``` + +3. Classify coverage status for each criterion: + - **FULL**: All scenarios validated at appropriate level(s) + - **PARTIAL**: Some coverage but missing edge cases or levels + - **NONE**: No test coverage at any level + - **UNIT-ONLY**: Only unit tests (missing integration/E2E validation) + - **INTEGRATION-ONLY**: Only API/Component tests (missing unit confidence) + +4. Check for duplicate coverage: + - Same behavior tested at multiple levels unnecessarily + - Flag violations of selective testing principles + - Recommend consolidation where appropriate + +**Output:** Complete traceability matrix with coverage classifications + +--- + +### Step 4: Analyze Gaps and Prioritize + +**Actions:** + +1. Identify coverage gaps: + - List criteria with NONE, PARTIAL, UNIT-ONLY, or INTEGRATION-ONLY status + - Assign severity based on test-priorities framework: + - **CRITICAL**: P0 criteria without FULL coverage (blocks release) + - **HIGH**: P1 criteria without FULL coverage (PR blocker) + - **MEDIUM**: P2 criteria without FULL coverage (nightly test gap) + - **LOW**: P3 criteria without FULL coverage (acceptable gap) + +2. Recommend specific tests to add: + - Suggest test level (E2E, API, Component, Unit) + - Provide test description (Given-When-Then) + - Recommend test ID (e.g., `1.3-E2E-004`) + - Explain why this test is needed + +3. Calculate coverage metrics: + - Overall coverage percentage (criteria with FULL coverage / total criteria) + - P0 coverage percentage (critical paths) + - P1 coverage percentage (high priority) + - Coverage by level (E2E%, API%, Component%, Unit%) + +4. Check against quality gates: + - P0 coverage >= 100% (required) + - P1 coverage >= 90% (recommended) + - Overall coverage >= 80% (recommended) + +**Output:** Prioritized gap analysis with actionable recommendations and coverage metrics + +--- + +### Step 5: Verify Test Quality + +**Actions:** + +1. For each mapped test, verify: + - Explicit assertions are present (not hidden in helpers) + - Test follows Given-When-Then structure + - No hard waits or sleeps + - Self-cleaning (test cleans up its data) + - File size < 300 lines + - Test duration < 90 seconds + +2. Flag quality issues: + - **BLOCKER**: Missing assertions, hard waits, flaky patterns + - **WARNING**: Large files, slow tests, unclear structure + - **INFO**: Style inconsistencies, missing documentation + +3. Reference knowledge fragments: + - `test-quality.md` for Definition of Done + - `fixture-architecture.md` for self-cleaning patterns + - `network-first.md` for Playwright best practices + - `data-factories.md` for test data patterns + +**Output:** Quality assessment for each test with improvement recommendations + +--- + +### Step 6: Generate Deliverables (Phase 1) + +**Actions:** + +1. Create traceability matrix markdown file: + - Use template from `trace-template.md` + - Include full mapping table + - Add coverage status section + - Add gap analysis section + - Add quality assessment section + - Add recommendations section + - Save to `{output_folder}/traceability-matrix.md` + +2. Generate gate YAML snippet (if enabled): + + ```yaml + traceability: + story_id: '1.3' + coverage: + overall: 85% + p0: 100% + p1: 90% + p2: 75% + gaps: + critical: 0 + high: 1 + medium: 2 + status: 'PASS' # or "FAIL" if P0 < 100% + ``` + +3. Create coverage badge/metric (if enabled): + - Generate badge markdown: `![Coverage](https://img.shields.io/badge/coverage-85%25-green)` + - Export metrics to JSON for CI/CD integration + +4. Update story file (if enabled): + - Add "Traceability" section to story markdown + - Link to traceability matrix + - Include coverage summary + - Add gate status + +**Output:** Complete Phase 1 traceability deliverables + +**Next:** If `enable_gate_decision: true`, proceed to Phase 2. Otherwise, workflow complete. + +--- + +## PHASE 2: QUALITY GATE DECISION + +This phase uses traceability results to make a quality gate decision (PASS/CONCERNS/FAIL/WAIVED) based on evidence and decision rules. + +**When Phase 2 Runs:** Automatically after Phase 1 if `enable_gate_decision: true` (default: true) + +**Skip Conditions:** If test execution results (`test_results`) not provided, warn and skip Phase 2. + +--- + +### Step 7: Gather Quality Evidence + +**Actions:** + +1. **Load Phase 1 traceability results** (inherited context): + - Coverage metrics (P0/P1/overall percentages) + - Gap analysis (missing/partial tests) + - Quality concerns (test quality flags) + - Traceability matrix + +2. **Load test execution results** (if `test_results` provided): + - Read CI/CD test reports (JUnit XML, TAP, JSON) + - Extract pass/fail counts by priority + - Calculate pass rates: + - **P0 pass rate**: `(P0 passed / P0 total) * 100` + - **P1 pass rate**: `(P1 passed / P1 total) * 100` + - **Overall pass rate**: `(All passed / All total) * 100` + - Identify failing tests and map to criteria + +3. **Load NFR assessment** (if `nfr_file` provided): + - Read `nfr-assessment.md` or similar + - Check critical NFR status (performance, security, scalability) + - Flag any critical NFR failures + +4. **Load supporting artifacts**: + - `test-design.md` → Risk priorities, DoD checklist + - `story-*.md` or `Epics.md` → Requirements context + +5. **Validate evidence freshness** (if `validate_evidence_freshness: true`): + - Check timestamps of test-design, traceability, NFR assessments + - Warn if artifacts are >7 days old + +6. **Check prerequisite workflows** (if `check_all_workflows_complete: true`): + - Verify test-design workflow complete + - Verify trace workflow complete (Phase 1) + - Verify nfr-assess workflow complete (if release-level gate) + +**Output:** Consolidated evidence bundle with all quality signals + +--- + +### Step 8: Apply Decision Rules + +**If `decision_mode: "deterministic"`** (rule-based - default): + +**Decision rules** (based on `workflow.md` thresholds): + +1. **PASS** if ALL of the following are true: + - P0 coverage ≥ `min_p0_coverage` (default: 100%) + - P1 coverage ≥ `min_p1_coverage` (default: 90%) + - Overall coverage ≥ `min_overall_coverage` (default: 80%) + - P0 test pass rate = `min_p0_pass_rate` (default: 100%) + - P1 test pass rate ≥ `min_p1_pass_rate` (default: 95%) + - Overall test pass rate ≥ `min_overall_pass_rate` (default: 90%) + - Critical NFRs passed (if `nfr_file` provided) + - No unresolved security issues ≤ `max_security_issues` (default: 0) + - No test quality red flags (hard waits, no assertions) + +2. **CONCERNS** if ANY of the following are true: + - P1 coverage 80-89% (below threshold but not critical) + - P1 test pass rate 90-94% (below threshold but not critical) + - Overall pass rate 85-89% + - P2 coverage <50% (informational) + - Some non-critical NFRs failing + - Minor test quality concerns (large test files, inferred mappings) + - **Note**: CONCERNS does NOT block deployment but requires acknowledgment + +3. **FAIL** if ANY of the following are true: + - P0 coverage <100% (missing critical tests) + - P0 test pass rate <100% (failing critical tests) + - P1 coverage <80% (significant gap) + - P1 test pass rate <90% (significant failures) + - Overall coverage <80% + - Overall pass rate <85% + - Critical NFRs failing (`max_critical_nfrs_fail` exceeded) + - Unresolved security issues (`max_security_issues` exceeded) + - Major test quality issues (tests with no assertions, pervasive hard waits) + +4. **WAIVED** (only if `allow_waivers: true`): + - Decision would be FAIL based on rules above + - Business stakeholder has approved waiver + - Waiver documented with: + - Justification (time constraint, known limitation, acceptable risk) + - Approver name and date + - Mitigation plan (follow-up stories, manual testing) + - Waiver evidence linked (email, Slack thread, ticket) + +**Risk tolerance adjustments:** + +- If `allow_p2_failures: true` → P2 test failures do NOT affect gate decision +- If `allow_p3_failures: true` → P3 test failures do NOT affect gate decision +- If `escalate_p1_failures: true` → P1 failures require explicit manager/lead approval + +**If `decision_mode: "manual"`:** + +- Present evidence summary to team +- Recommend decision based on rules above +- Team makes final call in meeting/chat +- Document decision with approver names + +**Output:** Gate decision (PASS/CONCERNS/FAIL/WAIVED) with rule-based rationale + +--- + +### Step 9: Document Decision and Evidence + +**Actions:** + +1. **Create gate decision document**: + - Save to `gate_output_file` (default: `{output_folder}/gate-decision-{gate_type}-{story_id}.md`) + - Use structure below + +2. **Document structure**: + +```markdown +# Quality Gate Decision: {gate_type} {story_id/epic_num/release_version} + +**Decision**: [PASS / CONCERNS / FAIL / WAIVED] +**Date**: {date} +**Decider**: {decision_mode} (deterministic | manual) +**Evidence Date**: {test_results_date} + +--- + +## Summary + +[1-2 sentence summary of decision and key factors] + +--- + +## Decision Criteria + +| Criterion | Threshold | Actual | Status | +| ----------------- | --------- | -------- | ------ | +| P0 Coverage | ≥100% | 100% | ✅ PASS | +| P1 Coverage | ≥90% | 88% | ⚠️ FAIL | +| Overall Coverage | ≥80% | 92% | ✅ PASS | +| P0 Pass Rate | 100% | 100% | ✅ PASS | +| P1 Pass Rate | ≥95% | 98% | ✅ PASS | +| Overall Pass Rate | ≥90% | 96% | ✅ PASS | +| Critical NFRs | All Pass | All Pass | ✅ PASS | +| Security Issues | 0 | 0 | ✅ PASS | + +**Overall Status**: 7/8 criteria met → Decision: **CONCERNS** + +--- + +## Evidence Summary + +### Test Coverage (from Phase 1 Traceability) + +- **P0 Coverage**: 100% (5/5 criteria fully covered) +- **P1 Coverage**: 88% (7/8 criteria fully covered) +- **Overall Coverage**: 92% (12/13 criteria covered) +- **Gap**: AC-5 (P1) missing E2E test + +### Test Execution Results + +- **P0 Pass Rate**: 100% (12/12 tests passed) +- **P1 Pass Rate**: 98% (45/46 tests passed) +- **Overall Pass Rate**: 96% (67/70 tests passed) +- **Failures**: 3 P2 tests (non-blocking) + +### Non-Functional Requirements + +- Performance: ✅ PASS (response time <500ms) +- Security: ✅ PASS (no vulnerabilities) +- Scalability: ✅ PASS (handles 10K users) + +### Test Quality + +- All tests have explicit assertions ✅ +- No hard waits detected ✅ +- Test files <300 lines ✅ +- Test IDs follow convention ✅ + +--- + +## Decision Rationale + +**Why CONCERNS (not PASS)**: + +- P1 coverage at 88% is below 90% threshold +- AC-5 (P1 priority) missing E2E test for error handling scenario +- This is a known gap from test-design phase + +**Why CONCERNS (not FAIL)**: + +- P0 coverage is 100% (critical paths validated) +- Overall coverage is 92% (above 80% threshold) +- Test pass rate is excellent (96% overall) +- Gap is isolated to one P1 criterion (not systemic) + +**Recommendation**: + +- Acknowledge gap and proceed with deployment +- Add missing AC-5 E2E test in next sprint +- Create follow-up story: "Add E2E test for AC-5 error handling" + +--- + +## Next Steps + +- [ ] Create follow-up story for AC-5 E2E test +- [ ] Deploy to staging environment +- [ ] Monitor production for edge cases related to AC-5 +- [ ] Update traceability matrix after follow-up test added + +--- + +## References + +- Traceability Matrix: `_bmad/output/traceability-matrix.md` +- Test Design: `_bmad/output/test-design-epic-2.md` +- Test Results: `ci-artifacts/test-report-2025-01-15.xml` +- NFR Assessment: `_bmad/output/nfr-assessment-release-1.2.md` +``` + +3. **Include evidence links** (if `require_evidence: true`): + - Link to traceability matrix + - Link to test execution reports (CI artifacts) + - Link to NFR assessment + - Link to test-design document + - Link to relevant PRs, commits, deployments + +4. **Waiver documentation** (if decision is WAIVED): + - Approver name and role (e.g., "Jane Doe, Engineering Manager") + - Approval date and method (e.g., "2025-01-15, Slack thread") + - Justification (e.g., "Time-boxed MVP, missing tests will be added in v1.1") + - Mitigation plan (e.g., "Manual testing by QA, follow-up stories created") + - Evidence link (e.g., "Slack: #engineering 2025-01-15 3:42pm") + +**Output:** Complete gate decision document with evidence and rationale + +--- + +### Step 10: Update Status Tracking and Notify + +**Actions:** + +1. **Generate stakeholder notification** (if `notify_stakeholders: true`): + - Create concise summary message for team communication + - Include: Decision, key metrics, action items + - Format for Slack/email/chat: + + ``` + 🚦 Quality Gate Decision: Story 1.3 - User Login + + Decision: ⚠️ CONCERNS + - P0 Coverage: ✅ 100% + - P1 Coverage: ⚠️ 88% (below 90%) + - Test Pass Rate: ✅ 96% + + Action Required: + - Create follow-up story for AC-5 E2E test + - Deploy to staging for validation + + Full Report: _bmad/output/gate-decision-story-1.3.md + ``` + +2. **Request sign-off** (if `require_sign_off: true`): + - Prompt for named approver (tech lead, QA lead, PM) + - Document approver name and timestamp in gate decision + - Block until sign-off received (interactive prompt) + +**Output:** Status tracking updated, stakeholders notified, sign-off obtained (if required) + +**Workflow Complete**: Both Phase 1 (traceability) and Phase 2 (gate decision) deliverables generated. + +--- + +## Decision Matrix (Quick Reference) + +| Scenario | P0 Cov | P1 Cov | Overall Cov | P0 Pass | P1 Pass | Overall Pass | NFRs | Decision | +| --------------- | ----------------- | ------ | ----------- | ------- | ------- | ------------ | ---- | ------------ | +| All green | 100% | ≥90% | ≥80% | 100% | ≥95% | ≥90% | Pass | **PASS** | +| Minor gap | 100% | 80-89% | ≥80% | 100% | 90-94% | 85-89% | Pass | **CONCERNS** | +| Missing P0 | <100% | - | - | - | - | - | - | **FAIL** | +| P0 test fail | 100% | - | - | <100% | - | - | - | **FAIL** | +| P1 gap | 100% | <80% | - | 100% | - | - | - | **FAIL** | +| NFR fail | 100% | ≥90% | ≥80% | 100% | ≥95% | ≥90% | Fail | **FAIL** | +| Security issue | - | - | - | - | - | - | Yes | **FAIL** | +| Business waiver | [FAIL conditions] | - | - | - | - | - | - | **WAIVED** | + +--- + +## Waiver Management + +**When to use waivers:** + +- Time-boxed MVP releases (known gaps, follow-up planned) +- Low-risk P1 gaps with mitigation (manual testing, monitoring) +- Technical debt acknowledged by product/engineering leadership +- External dependencies blocking test automation + +**Waiver approval process:** + +1. Document gap and risk in gate decision +2. Propose mitigation plan (manual testing, follow-up stories, monitoring) +3. Request approval from stakeholder (EM, PM, QA lead) +4. Link approval evidence (email, chat thread, meeting notes) +5. Add waiver to gate decision document +6. Create follow-up stories to close gaps + +**Waiver does NOT apply to:** + +- P0 gaps (always blocking) +- Critical security issues (always blocking) +- Critical NFR failures (performance, data integrity) + +--- + +## Example Gate Decisions + +### Example 1: PASS (All Criteria Met) + +``` +Decision: ✅ PASS + +Summary: All quality criteria met. Story 1.3 is ready for production deployment. + +Evidence: +- P0 Coverage: 100% (5/5 criteria) +- P1 Coverage: 95% (19/20 criteria) +- Overall Coverage: 92% (24/26 criteria) +- P0 Pass Rate: 100% (12/12 tests) +- P1 Pass Rate: 98% (45/46 tests) +- Overall Pass Rate: 96% (67/70 tests) +- NFRs: All pass (performance, security, scalability) + +Action: Deploy to production ✅ +``` + +### Example 2: CONCERNS (Minor Gap, Non-Blocking) + +``` +Decision: ⚠️ CONCERNS + +Summary: P1 coverage slightly below threshold (88% vs 90%). Recommend deploying with follow-up story. + +Evidence: +- P0 Coverage: 100% ✅ +- P1 Coverage: 88% ⚠️ (below 90%) +- Overall Coverage: 92% ✅ +- Test Pass Rate: 96% ✅ +- Gap: AC-5 (P1) missing E2E test + +Action: +- Deploy to staging for validation +- Create follow-up story for AC-5 E2E test +- Monitor production for edge cases related to AC-5 +``` + +### Example 3: FAIL (P0 Gap, Blocking) + +``` +Decision: ❌ FAIL + +Summary: P0 coverage incomplete. Missing critical validation test. BLOCKING deployment. + +Evidence: +- P0 Coverage: 80% ❌ (4/5 criteria, AC-2 missing) +- AC-2: "User cannot login with invalid credentials" (P0 priority) +- No tests validate login security for invalid credentials +- This is a critical security gap + +Action: +- Add P0 test for AC-2: 1.3-E2E-004 (invalid credentials) +- Re-run traceability after test added +- Re-evaluate gate decision after P0 coverage = 100% + +Deployment BLOCKED until P0 gap resolved ❌ +``` + +### Example 4: WAIVED (Business Decision) + +``` +Decision: ⚠️ WAIVED + +Summary: P1 coverage below threshold (75% vs 90%), but waived for MVP launch. + +Evidence: +- P0 Coverage: 100% ✅ +- P1 Coverage: 75% ❌ (below 90%) +- Gap: 5 P1 criteria missing E2E tests (error handling, edge cases) + +Waiver: +- Approver: Jane Doe, Engineering Manager +- Date: 2025-01-15 +- Justification: Time-boxed MVP for investor demo. Core functionality (P0) fully validated. P1 gaps are low-risk edge cases. +- Mitigation: Manual QA testing for P1 scenarios, follow-up stories created for automated tests in v1.1 +- Evidence: Slack #engineering 2025-01-15 3:42pm + +Action: +- Deploy to production with manual QA validation ✅ +- Add 5 E2E tests for P1 gaps in v1.1 sprint +- Monitor production logs for edge case occurrences +``` + +--- + +## Non-Prescriptive Approach + +**Minimal Examples:** This workflow provides principles and patterns, not rigid templates. Teams should adapt the traceability and gate decision formats to their needs. + +**Key Patterns to Follow:** + +- Map criteria to tests explicitly (don't rely on inference alone) +- Prioritize by risk (P0 gaps are critical, P3 gaps are acceptable) +- Check coverage at appropriate levels (E2E for journeys, Unit for logic) +- Verify test quality (explicit assertions, no flakiness) +- Apply deterministic gate rules for consistency +- Document gate decisions with clear evidence +- Use waivers judiciously (business approved, mitigation planned) + +**Extend as Needed:** + +- Add custom coverage classifications +- Integrate with code coverage tools (Istanbul, NYC) +- Link to external traceability systems (JIRA, Azure DevOps) +- Add compliance or regulatory requirements +- Customize gate decision thresholds per project +- Add manual approval workflows for gate decisions + +--- + +## Coverage Classification Details + +### FULL Coverage + +- All scenarios validated at appropriate test level(s) +- Edge cases considered +- Both happy path and error paths tested +- Assertions are explicit and complete + +### PARTIAL Coverage + +- Some scenarios validated but missing edge cases +- Only happy path tested (missing error paths) +- Assertions present but incomplete +- Coverage exists but needs enhancement + +### NONE Coverage + +- No tests found for this criterion +- Complete gap requiring new tests +- Critical if P0/P1, acceptable if P3 + +### UNIT-ONLY Coverage + +- Only unit tests exist (business logic validated) +- Missing integration or E2E validation +- Risk: Implementation may not work end-to-end +- Recommendation: Add integration or E2E tests for critical paths + +### INTEGRATION-ONLY Coverage + +- Only API or Component tests exist +- Missing unit test confidence for business logic +- Risk: Logic errors may not be caught quickly +- Recommendation: Add unit tests for complex algorithms or state machines + +--- + +## Duplicate Coverage Detection + +Use selective testing principles from `selective-testing.md`: + +**Acceptable Overlap:** + +- Unit tests for business logic + E2E tests for user journey (different aspects) +- API tests for contract + E2E tests for full workflow (defense in depth for critical paths) + +**Unacceptable Duplication:** + +- Same validation at multiple levels (e.g., E2E testing math logic better suited for unit tests) +- Multiple E2E tests covering identical user path +- Component tests duplicating unit test logic + +**Recommendation Pattern:** + +- Test logic at unit level +- Test integration at API/Component level +- Test user experience at E2E level +- Avoid testing framework behavior at any level + +--- + +## Integration with BMad Artifacts + +### With test-design.md + +- Use risk assessment to prioritize gap remediation +- Reference test priorities (P0/P1/P2/P3) for severity classification and gate decision +- Align traceability with originally planned test coverage + +### With tech-spec.md + +- Understand technical implementation details +- Map criteria to specific code modules +- Verify tests cover technical edge cases + +### With PRD.md + +- Understand full product context +- Verify acceptance criteria align with product goals +- Check for unstated requirements that need coverage + +### With nfr-assessment.md + +- Load non-functional validation results for gate decision +- Check critical NFR status (performance, security, scalability) +- Include NFR pass/fail in gate decision criteria + +--- + +## Quality Gates (Phase 1 Recommendations) + +### P0 Coverage (Critical Paths) + +- **Requirement:** 100% FULL coverage +- **Severity:** BLOCKER if not met +- **Action:** Do not release until P0 coverage is complete + +### P1 Coverage (High Priority) + +- **Requirement:** 90% FULL coverage +- **Severity:** HIGH if not met +- **Action:** Block PR merge until addressed + +### P2 Coverage (Medium Priority) + +- **Requirement:** No strict requirement (recommended 80%) +- **Severity:** MEDIUM if gaps exist +- **Action:** Address in nightly test improvements + +### P3 Coverage (Low Priority) + +- **Requirement:** No requirement +- **Severity:** LOW if gaps exist +- **Action:** Optional - add if time permits + +--- + +## Example Traceability Matrix + +````markdown +# Traceability Matrix - Story 1.3 + +**Story:** User Authentication +**Date:** 2025-10-14 +**Status:** 85% Coverage (1 HIGH gap) + +## Coverage Summary + +| Priority | Total Criteria | FULL Coverage | Coverage % | Status | +| --------- | -------------- | ------------- | ---------- | ------ | +| P0 | 3 | 3 | 100% | ✅ PASS | +| P1 | 5 | 4 | 80% | ⚠️ WARN | +| P2 | 4 | 3 | 75% | ✅ PASS | +| P3 | 2 | 1 | 50% | ✅ PASS | +| **Total** | **14** | **11** | **79%** | ⚠️ WARN | + +## Detailed Mapping + +### AC-1: User can login with email and password (P0) + +- **Coverage:** FULL ✅ +- **Tests:** + - `1.3-E2E-001` - tests/e2e/auth.spec.ts:12 + - Given: User has valid credentials + - When: User submits login form + - Then: User is redirected to dashboard + - `1.3-UNIT-001` - tests/unit/auth-service.spec.ts:8 + - Given: Valid email and password hash + - When: validateCredentials is called + - Then: Returns user object + +### AC-2: User sees error for invalid credentials (P0) + +- **Coverage:** FULL ✅ +- **Tests:** + - `1.3-E2E-002` - tests/e2e/auth.spec.ts:28 + - Given: User has invalid password + - When: User submits login form + - Then: Error message is displayed + - `1.3-UNIT-002` - tests/unit/auth-service.spec.ts:18 + - Given: Invalid password hash + - When: validateCredentials is called + - Then: Throws AuthenticationError + +### AC-3: User can reset password via email (P1) + +- **Coverage:** PARTIAL ⚠️ +- **Tests:** + - `1.3-E2E-003` - tests/e2e/auth.spec.ts:44 + - Given: User requests password reset + - When: User clicks reset link + - Then: User can set new password +- **Gaps:** + - Missing: Email delivery validation + - Missing: Expired token handling + - Missing: Unit test for token generation +- **Recommendation:** Add `1.3-API-001` for email service integration and `1.3-UNIT-003` for token logic + +## Gap Analysis + +### Critical Gaps (BLOCKER) + +- None ✅ + +### High Priority Gaps (PR BLOCKER) + +1. **AC-3: Password reset email edge cases** + - Missing tests for expired tokens, invalid tokens, email failures + - Recommend: `1.3-API-001` (email service integration) and `1.3-E2E-004` (error paths) + - Impact: Users may not be able to recover accounts in error scenarios + +### Medium Priority Gaps (Nightly) + +1. **AC-7: Session timeout handling** - UNIT-ONLY coverage (missing E2E validation) + +## Quality Assessment + +### Tests with Issues + +- `1.3-E2E-001` ⚠️ - 145 seconds (exceeds 90s target) - Optimize fixture setup +- `1.3-UNIT-005` ⚠️ - 320 lines (exceeds 300 line limit) - Split into multiple test files + +### Tests Passing Quality Gates + +- 11/13 tests (85%) meet all quality criteria ✅ + +## Gate YAML Snippet + +```yaml +traceability: + story_id: '1.3' + coverage: + overall: 79% + p0: 100% + p1: 80% + p2: 75% + p3: 50% + gaps: + critical: 0 + high: 1 + medium: 1 + low: 1 + status: 'WARN' # P1 coverage below 90% threshold + recommendations: + - 'Add 1.3-API-001 for email service integration' + - 'Add 1.3-E2E-004 for password reset error paths' + - 'Optimize 1.3-E2E-001 performance (145s → <90s)' +``` +```` + +## Recommendations + +1. **Address High Priority Gap:** Add password reset edge case tests before PR merge +2. **Optimize Slow Test:** Refactor `1.3-E2E-001` to use faster fixture setup +3. **Split Large Test:** Break `1.3-UNIT-005` into focused test files +4. **Enhance P2 Coverage:** Add E2E validation for session timeout (currently UNIT-ONLY) + +``` + +--- + +## Validation Checklist + +Before completing this workflow, verify: + +**Phase 1 (Traceability):** +- ✅ All acceptance criteria are mapped to tests (or gaps are documented) +- ✅ Coverage status is classified (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) +- ✅ Gaps are prioritized by risk level (P0/P1/P2/P3) +- ✅ P0 coverage is 100% or blockers are documented +- ✅ Duplicate coverage is identified and flagged +- ✅ Test quality is assessed (assertions, structure, performance) +- ✅ Traceability matrix is generated and saved + +**Phase 2 (Gate Decision - if enabled):** +- ✅ Test execution results loaded and pass rates calculated +- ✅ NFR assessment results loaded (if applicable) +- ✅ Decision rules applied consistently (PASS/CONCERNS/FAIL/WAIVED) +- ✅ Gate decision document created with evidence +- ✅ Waiver documented if decision is WAIVED (approver, justification, mitigation) +- ✅ Stakeholders notified (if enabled) + +--- + +## Notes + +**Phase 1 (Traceability):** +- **Explicit Mapping:** Require tests to reference criteria explicitly (test IDs, describe blocks) for maintainability +- **Risk-Based Prioritization:** Use test-priorities framework (P0/P1/P2/P3) to determine gap severity +- **Quality Over Quantity:** Better to have fewer high-quality tests with FULL coverage than many low-quality tests with PARTIAL coverage +- **Selective Testing:** Avoid duplicate coverage - test each behavior at the appropriate level only + +**Phase 2 (Gate Decision):** +- **Deterministic Rules:** Use consistent thresholds (P0=100%, P1≥90%, overall≥80%) for objectivity +- **Evidence-Based:** Every decision must cite specific metrics (coverage %, pass rates, NFRs) +- **Waiver Discipline:** Waivers require approver name, justification, mitigation plan, and evidence link +- **Non-Blocking CONCERNS:** Use CONCERNS for minor gaps that don't justify blocking deployment (e.g., P1 at 88% vs 90%) +- **Automate in CI/CD:** Generate YAML snippets that can be consumed by CI/CD pipelines for automated quality gates + +--- + +## Troubleshooting + +### "No tests found for this story" +- Run `*atdd` workflow first to generate failing acceptance tests +- Check test file naming conventions (may not match story ID pattern) +- Verify test directory path is correct + +### "Cannot determine coverage status" +- Tests may lack explicit mapping to criteria (no test IDs, unclear describe blocks) +- Review test structure and add Given-When-Then narrative +- Add test IDs in format: `{STORY_ID}-{LEVEL}-{SEQ}` (e.g., 1.3-E2E-001) + +### "P0 coverage below 100%" +- This is a **BLOCKER** - do not release +- Identify missing P0 tests in gap analysis +- Run `*atdd` workflow to generate missing tests +- Verify with stakeholders that P0 classification is correct + +### "Duplicate coverage detected" +- Review selective testing principles in `selective-testing.md` +- Determine if overlap is acceptable (defense in depth) or wasteful (same validation at multiple levels) +- Consolidate tests at appropriate level (logic → unit, integration → API, journey → E2E) + +### "Test execution results missing" (Phase 2) +- Phase 2 gate decision requires `test_results` (CI/CD test reports) +- If missing, Phase 2 will be skipped with warning +- Provide JUnit XML, TAP, or JSON test report path via `test_results` variable + +### "Gate decision is FAIL but deployment needed urgently" +- Request business waiver (if `allow_waivers: true`) +- Document approver, justification, mitigation plan +- Create follow-up stories to address gaps +- Use WAIVED decision only for non-P0 gaps + +--- + +## Related Workflows + +**Prerequisites:** +- `testarch-test-design` - Define test priorities (P0/P1/P2/P3) before tracing (required for Phase 2) +- `testarch-atdd` or `testarch-automate` - Generate tests before tracing coverage + +**Complements:** +- `testarch-nfr-assess` - Non-functional requirements validation (recommended for release gates) +- `testarch-test-review` - Review test quality issues flagged in traceability + +**Next Steps:** +- If gate decision is PASS/CONCERNS → Deploy and monitor +- If gate decision is FAIL → Add missing tests, re-run trace workflow +- If gate decision is WAIVED → Deploy with mitigation, create follow-up stories + +--- + + +``` From 1a1d4bed52e5ec7a03641fbe302a1c0b840d9c61 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 16:02:01 +0000 Subject: [PATCH 05/22] Migrate workflow runner references to workflow.md --- src/bmm/agents/tea.agent.yaml | 63 +++++++ src/bmm/module-help.csv | 51 +++--- src/core/resources/excalidraw/README.md | 160 ++++++++++++++++++ .../resources/excalidraw/library-loader.md | 50 ++++++ test/test-installation-components.js | 95 +++++++++++ .../installers/lib/core/manifest-generator.js | 2 +- tools/cli/installers/lib/ide/_base-ide.js | 24 ++- .../ide/shared/workflow-command-generator.js | 30 ++-- tools/cli/installers/lib/modules/manager.js | 83 ++++++--- 9 files changed, 481 insertions(+), 77 deletions(-) create mode 100644 src/bmm/agents/tea.agent.yaml create mode 100644 src/core/resources/excalidraw/README.md create mode 100644 src/core/resources/excalidraw/library-loader.md diff --git a/src/bmm/agents/tea.agent.yaml b/src/bmm/agents/tea.agent.yaml new file mode 100644 index 000000000..5bc6cb1b1 --- /dev/null +++ b/src/bmm/agents/tea.agent.yaml @@ -0,0 +1,63 @@ +# Test Architect + Quality Advisor Agent Definition + +agent: + webskip: true + metadata: + id: "_bmad/bmm/agents/tea.md" + name: Murat + title: Master Test Architect + icon: 🧪 + module: bmm + hasSidecar: false + + persona: + role: Master Test Architect + identity: Test architect specializing in API testing, backend services, UI automation, CI/CD pipelines, and scalable quality gates. Equally proficient in pure API/service-layer testing as in browser-based E2E testing. + communication_style: "Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments." + principles: | + - Risk-based testing - depth scales with impact + - Quality gates backed by data + - Tests mirror usage patterns (API, UI, or both) + - Flakiness is critical technical debt + - Tests first AI implements suite validates + - Calculate risk vs value for every testing decision + - Prefer lower test levels (unit > integration > E2E) when possible + - API tests are first-class citizens, not just UI support + + critical_actions: + - "Consult {project-root}/_bmad/bmm/testarch/tea-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task" + - "Load the referenced fragment(s) from {project-root}/_bmad/bmm/testarch/knowledge/ before giving recommendations" + - "Cross-check recommendations with the current official Playwright, Cypress, Pact, and CI platform documentation" + + menu: + - trigger: TF or fuzzy match on test-framework + workflow: "{project-root}/_bmad/bmm/workflows/testarch/framework/workflow.md" + description: "[TF] Test Framework: Initialize production-ready test framework architecture" + + - trigger: AT or fuzzy match on atdd + workflow: "{project-root}/_bmad/bmm/workflows/testarch/atdd/workflow.md" + description: "[AT] Automated Test: Generate API and/or E2E tests first, before starting implementation on a story" + + - trigger: TA or fuzzy match on test-automate + workflow: "{project-root}/_bmad/bmm/workflows/testarch/automate/workflow.md" + description: "[TA] Test Automation: Generate comprehensive test automation framework for your whole project" + + - trigger: TD or fuzzy match on test-design + workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-design/workflow.md" + description: "[TD] Test Design: Create comprehensive test scenarios ahead of development." + + - trigger: TR or fuzzy match on test-trace + workflow: "{project-root}/_bmad/bmm/workflows/testarch/trace/workflow.md" + description: "[TR] Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2)" + + - trigger: NR or fuzzy match on nfr-assess + workflow: "{project-root}/_bmad/bmm/workflows/testarch/nfr-assess/workflow.md" + description: "[NR] Non-Functional Requirements: Validate against the project implementation" + + - trigger: CI or fuzzy match on continuous-integration + workflow: "{project-root}/_bmad/bmm/workflows/testarch/ci/workflow.md" + description: "[CI] Continuous Integration: Recommend and Scaffold CI/CD quality pipeline" + + - trigger: RV or fuzzy match on test-review + workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-review/workflow.md" + description: "[RV] Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices" diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv index 635bb8a81..9ba42ca0f 100644 --- a/src/bmm/module-help.csv +++ b/src/bmm/module-help.csv @@ -1,31 +1,32 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs, -bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.yaml,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, -bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context", -bmm,anytime,Quick Spec,QS,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec", -bmm,anytime,Quick Dev,QD,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, -bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", -bmm,anytime,Write Document,WD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document", -bmm,anytime,Update Standards,US,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards", -bmm,anytime,Mermaid Generate,MG,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.",planning_artifacts,"mermaid diagram", -bmm,anytime,Validate Document,VD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.",planning_artifacts,"validation report", -bmm,anytime,Explain Concept,EC,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create clear technical explanations with examples and diagrams for complex concepts. Breaks down into digestible sections using task-oriented approach.",project_knowledge,"explanation", +bmm,anytime,Document Project,DP,10,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, +bmm,anytime,Quick Spec,TS,20,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps utilities without extensive planning",planning_artifacts,"tech spec", +bmm,anytime,Quick Dev,QD,30,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, +bmm,anytime,Correct Course,CC,40,_bmad/bmm/workflows/4-implementation/correct-course/workflow.md,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", bmm,1-analysis,Brainstorm Project,BP,10,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session", -bmm,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow-market-research.md,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents", -bmm,1-analysis,Domain Research,DR,21,_bmad/bmm/workflows/1-analysis/research/workflow-domain-research.md,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents", -bmm,1-analysis,Technical Research,TR,22,_bmad/bmm/workflows/1-analysis/research/workflow-technical-research.md,bmad-bmm-technical-research,false,analyst,Create Mode,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project_knowledge","research documents", -bmm,1-analysis,Create Brief,CB,30,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", -bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md,bmad-bmm-create-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, -bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md,bmad-bmm-validate-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", -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,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=market,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents" +bmm,1-analysis,Domain Research,DR,21,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=domain,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project-knowledge","research documents" +bmm,1-analysis,Technical Research,TR,22,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=technical,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project-knowledge","research documents" +bmm,1-analysis,Create Brief,CB,30,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-create-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", +bmm,1-analysis,Validate Brief,VB,40,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-validate-brief,false,analyst,Validate Mode,"Validates product brief completeness",planning_artifacts,"brief validation report", +bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow.md,bmad-bmm-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, +bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow.md,bmad-bmm-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", bmm,2-planning,Create UX,CU,30,_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md,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,2-planning,Validate UX,VU,40,_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md,bmad-bmm-create-ux-design,false,ux-designer,Validate Mode,"Validates UX design deliverables",planning_artifacts,"ux validation report", +,anytime,Create Dataflow,CDF,50,_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.md,bmad-bmm-create-excalidraw-dataflow,false,ux-designer,Create Mode,"Create data flow diagrams (DFD) in Excalidraw format - can be called standalone or during any workflow to add visual documentation",planning_artifacts,"dataflow diagram", +,anytime,Create Diagram,CED,51,_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.md,bmad-bmm-create-excalidraw-diagram,false,ux-designer,Create Mode,"Create system architecture diagrams ERDs UML diagrams or general technical diagrams in Excalidraw format - use anytime or call from architecture workflow to add visual documentation",planning_artifacts,"diagram", +,anytime,Create Flowchart,CFC,52,_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.md,bmad-bmm-create-excalidraw-flowchart,false,ux-designer,Create Mode,"Create a flowchart visualization in Excalidraw format for processes pipelines or logic flows - use anytime or during architecture to add process documentation",planning_artifacts,"flowchart", +,anytime,Create Wireframe,CEW,53,_bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.md,bmad-bmm-create-excalidraw-wireframe,false,ux-designer,Create Mode,"Create website or app wireframes in Excalidraw format - use anytime standalone or call from UX workflow to add UI mockups",planning_artifacts,"wireframe", bmm,3-solutioning,Create Architecture,CA,10,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture, +bmm,3-solutioning,Validate Architecture,VA,20,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,false,architect,Validate Mode,"Validates architecture completeness",planning_artifacts,"architecture validation report", 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,Validate Epics and Stories,VE,40,_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md,bmad-bmm-create-epics-and-stories,false,pm,Validate Mode,"Validates epics and stories completeness",planning_artifacts,"epics validation report", +bmm,3-solutioning,Test Design,TD,50,_bmad/bmm/workflows/testarch/test-design/workflow.md,bmad-bmm-testarch-test-design,false,tea,Create Mode,"Create comprehensive test scenarios ahead of development, recommended if string test compliance or assurance is needed. Very critical for distributed applications with separate front ends and backends outside of a monorepo.",planning_artifacts,"test design", bmm,3-solutioning,Check Implementation Readiness,IR,70,_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md,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.yaml,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.yaml,bmad-bmm-sprint-status,false,sm,Create Mode,"Anytime: Summarize sprint status and route to next workflow",,, -bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report", -bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, -bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,, -bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,, -bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa/automate/workflow.yaml,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite", -bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective, +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",,, +bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, +bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report", +bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.md,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,, +bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.md,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,, +bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.md,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective, diff --git a/src/core/resources/excalidraw/README.md b/src/core/resources/excalidraw/README.md new file mode 100644 index 000000000..a99f7a505 --- /dev/null +++ b/src/core/resources/excalidraw/README.md @@ -0,0 +1,160 @@ +# Core Excalidraw Resources + +Universal knowledge for creating Excalidraw diagrams. All agents that create Excalidraw files should reference these resources. + +## Purpose + +Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (domain-specific application). + +**Core = "How to create Excalidraw elements"** + +- How to group shapes with text labels +- How to calculate text width +- How to create arrows with proper bindings +- How to validate JSON syntax +- Base structure and primitives + +**Agents = "What diagrams to create"** + +- Frame Expert (BMM): Technical flowcharts, architecture diagrams, wireframes +- Presentation Master (CIS): Pitch decks, creative visuals, Rube Goldberg machines +- Tech Writer (BMM): Documentation diagrams, concept explanations + +## Files in This Directory + +### excalidraw-helpers.md + +**Universal element creation patterns** + +- Text width calculation +- Element grouping rules (shapes + labels) +- Grid alignment +- Arrow creation (straight, elbow) +- Theme application +- Validation checklist +- Optimization rules + +**Agents reference this to:** + +- Create properly grouped shapes +- Calculate text dimensions +- Connect elements with arrows +- Ensure valid structure + +### validate-json-instructions.md + +**Universal JSON validation process** + +- How to validate Excalidraw JSON +- Common errors and fixes +- Workflow integration +- Error recovery + +**Agents reference this to:** + +- Validate files after creation +- Fix syntax errors +- Ensure files can be opened in Excalidraw + +### library-loader.md (Future) + +**How to load external .excalidrawlib files** + +- Programmatic library loading +- Community library integration +- Custom library management + +**Status:** To be developed when implementing external library support. + +## How Agents Use These Resources + +### Example: Frame Expert (Technical Diagrams) + +```yaml +# workflows/excalidraw-diagrams/create-flowchart/workflow.md +helpers: '{project-root}/_bmad/core/resources/excalidraw/excalidraw-helpers.md' +json_validation: '{project-root}/_bmad/core/resources/excalidraw/validate-json-instructions.md' +``` + +**Domain-specific additions:** + +```yaml +# workflows/excalidraw-diagrams/_shared/flowchart-templates.yaml +flowchart: + start_node: + type: ellipse + width: 120 + height: 60 + process_box: + type: rectangle + width: 160 + height: 80 + decision_diamond: + type: diamond + width: 140 + height: 100 +``` + +### Example: Presentation Master (Creative Visuals) + +```yaml +# workflows/create-visual-metaphor/workflow.md +helpers: '{project-root}/_bmad/core/resources/excalidraw/excalidraw-helpers.md' +json_validation: '{project-root}/_bmad/core/resources/excalidraw/validate-json-instructions.md' +``` + +**Domain-specific additions:** + +```yaml +# workflows/_shared/creative-templates.yaml +rube_goldberg: + whimsical_connector: + type: arrow + strokeStyle: dashed + roughness: 2 + playful_box: + type: rectangle + roundness: 12 +``` + +## What Doesn't Belong in Core + +**Domain-Specific Elements:** + +- Flowchart-specific templates (belongs in Frame Expert) +- Pitch deck layouts (belongs in Presentation Master) +- Documentation-specific styles (belongs in Tech Writer) + +**Agent Workflows:** + +- How to create a flowchart (Frame Expert workflow) +- How to create a pitch deck (Presentation Master workflow) +- Step-by-step diagram creation (agent-specific) + +**Theming:** + +- Currently in agent workflows +- **Future:** Will be refactored to core as user-configurable themes + +## Architecture Principle + +**Single Source of Truth:** + +- Core holds universal knowledge +- Agents reference core, don't duplicate +- Updates to core benefit all agents +- Agents specialize with domain knowledge + +**DRY (Don't Repeat Yourself):** + +- Element creation logic: ONCE in core +- Text width calculation: ONCE in core +- Validation process: ONCE in core +- Arrow binding patterns: ONCE in core + +## Future Enhancements + +1. **External Library Loader** - Load .excalidrawlib files from libraries.excalidraw.com +2. **Theme Management** - User-configurable color themes saved in core +3. **Component Library** - Shared reusable components across agents +4. **Layout Algorithms** - Auto-layout helpers for positioning elements diff --git a/src/core/resources/excalidraw/library-loader.md b/src/core/resources/excalidraw/library-loader.md new file mode 100644 index 000000000..f2fd038de --- /dev/null +++ b/src/core/resources/excalidraw/library-loader.md @@ -0,0 +1,50 @@ +# External Library Loader + +**Status:** Placeholder for future implementation + +## Purpose + +Load external .excalidrawlib files from or custom sources. + +## Planned Capabilities + +- Load libraries by URL +- Load libraries from local files +- Merge multiple libraries +- Filter library components +- Cache loaded libraries + +## API Reference + +Will document how to use: + +- `importLibrary(url)` - Load library from URL +- `loadSceneOrLibraryFromBlob()` - Load from file +- `mergeLibraryItems()` - Combine libraries + +## Usage Example + +```yaml +# Future workflow.md structure +libraries: + - url: 'https://libraries.excalidraw.com/libraries/...' + filter: ['aws', 'cloud'] + - path: '{project-root}/_data/custom-library.excalidrawlib' +``` + +## Implementation Notes + +This will be developed when agents need to leverage the extensive library ecosystem available at . + +Hundreds of pre-built component libraries exist for: + +- AWS/Cloud icons +- UI/UX components +- Business diagrams +- Mind map shapes +- Floor plans +- And much more... + +## User Configuration + +Future: Users will be able to configure favorite libraries in their BMAD config for automatic loading. diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 7310ebe5a..6efee44e8 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -234,6 +234,101 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 7: Validate Workflow XML Reference Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 7: Validate Workflow Reference Guard${colors.reset}\n`); + + try { + const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs')]; + const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); + const forbiddenRef = 'validate-workflow.xml'; + const excludedFile = path.join(projectRoot, 'src', 'core', 'tasks', 'validate-workflow.xml'); + const offenders = []; + + const walk = async (dir) => { + const entries = await fs.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + await walk(fullPath); + continue; + } + if (!allowedExtensions.has(path.extname(entry.name))) { + continue; + } + if (fullPath === excludedFile) { + continue; + } + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); + } + } + }; + + for (const root of searchRoots) { + await walk(root); + } + + assert( + offenders.length === 0, + 'No validate-workflow.xml references outside XML source', + offenders.length > 0 ? offenders.join(', ') : '', + ); + } catch (error) { + assert(false, 'Validate workflow reference guard runs', error.message); + } + + console.log(''); + + // ============================================================ + // Test 8: Workflow XML Reference Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 8: Workflow Reference Guard${colors.reset}\n`); + + try { + const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs'), path.join(projectRoot, 'tools')]; + const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); + const forbiddenRef = 'workflow.xml'; + const excludedFiles = new Set([ + path.join(projectRoot, 'src', 'core', 'tasks', 'workflow.xml'), + path.join(projectRoot, 'src', 'core', 'workflows', 'advanced-elicitation', 'workflow.xml'), + ]); + const offenders = []; + + const walk = async (dir) => { + const entries = await fs.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + await walk(fullPath); + continue; + } + if (!allowedExtensions.has(path.extname(entry.name))) { + continue; + } + if (excludedFiles.has(fullPath)) { + continue; + } + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); + } + } + }; + + for (const root of searchRoots) { + await walk(root); + } + + assert(offenders.length === 0, 'No workflow.xml references outside XML source', offenders.length > 0 ? offenders.join(', ') : ''); + } catch (error) { + assert(false, 'Workflow reference guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index caea790eb..c0b5c655a 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -148,7 +148,7 @@ class ManifestGenerator { return workflows; } - // Recursively find workflow.yaml files + // Recursively find workflow files const findWorkflows = async (dir, relativePath = '') => { const entries = await fs.readdir(dir, { withFileTypes: true }); diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index dce8aee9f..fd3d5f7d3 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -304,7 +304,7 @@ class BaseIdeSetup { if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') { const moduleWorkflowsPath = path.join(bmadDir, entry.name, 'workflows'); if (await fs.pathExists(moduleWorkflowsPath)) { - const moduleWorkflows = await this.findWorkflowYamlFiles(moduleWorkflowsPath); + const moduleWorkflows = await this.findWorkflowFiles(moduleWorkflowsPath); workflows.push( ...moduleWorkflows.map((w) => ({ ...w, @@ -324,11 +324,11 @@ class BaseIdeSetup { } /** - * Recursively find workflow.yaml files + * Recursively find workflow files (workflow.yaml or workflow.md) * @param {string} dir - Directory to search * @returns {Array} List of workflow file info objects */ - async findWorkflowYamlFiles(dir) { + async findWorkflowFiles(dir) { const workflows = []; if (!(await fs.pathExists(dir))) { @@ -342,14 +342,24 @@ class BaseIdeSetup { if (entry.isDirectory()) { // Recursively search subdirectories - const subWorkflows = await this.findWorkflowYamlFiles(fullPath); + const subWorkflows = await this.findWorkflowFiles(fullPath); workflows.push(...subWorkflows); - } else if (entry.isFile() && entry.name === 'workflow.yaml') { - // Read workflow.yaml to get name and standalone property + } else if (entry.isFile() && (entry.name === 'workflow.yaml' || entry.name === 'workflow.md')) { + // Read workflow file to get name and standalone property try { const yaml = require('yaml'); const content = await fs.readFile(fullPath, 'utf8'); - const workflowData = yaml.parse(content); + let workflowData = null; + + if (entry.name === 'workflow.yaml') { + workflowData = yaml.parse(content); + } else { + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) { + continue; + } + workflowData = yaml.parse(frontmatterMatch[1]); + } if (workflowData && workflowData.name) { // Workflows are standalone by default unless explicitly false diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index 5a23fda2f..c01429397 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -2,13 +2,13 @@ const path = require('node:path'); const fs = require('fs-extra'); const csv = require('csv-parse/sync'); const chalk = require('chalk'); -const { toColonPath, toDashPath, customAgentColonName, customAgentDashName, BMAD_FOLDER_NAME } = require('./path-utils'); +const { toColonPath, toDashPath, customAgentColonName, customAgentDashName } = require('./path-utils'); /** * Generates command files for each workflow in the manifest */ class WorkflowCommandGenerator { - constructor(bmadFolderName = BMAD_FOLDER_NAME) { + constructor(bmadFolderName = 'bmad') { this.templatePath = path.join(__dirname, '../templates/workflow-command-template.md'); this.bmadFolderName = bmadFolderName; } @@ -67,10 +67,8 @@ class WorkflowCommandGenerator { for (const workflow of allWorkflows) { const commandContent = await this.generateCommandContent(workflow, bmadDir); - // Calculate the relative workflow path (e.g., bmm/workflows/4-implementation/sprint-planning/workflow.yaml) - let workflowRelPath = workflow.path || ''; - // Normalize path separators for cross-platform compatibility - workflowRelPath = workflowRelPath.replaceAll('\\', '/'); + // Calculate the relative workflow path (e.g., bmm/workflows/4-implementation/sprint-planning/workflow.md) + let workflowRelPath = workflow.path; // Remove _bmad/ prefix if present to get relative path from project root // Handle both absolute paths (/path/to/_bmad/...) and relative paths (_bmad/...) if (workflowRelPath.includes('_bmad/')) { @@ -78,15 +76,9 @@ class WorkflowCommandGenerator { if (parts.length > 1) { workflowRelPath = parts.slice(1).join('/'); } - } else if (workflowRelPath.includes('/src/')) { - // Normalize source paths (e.g. .../src/bmm/...) to relative module path (e.g. bmm/...) - const match = workflowRelPath.match(/\/src\/([^/]+)\/(.+)/); - if (match) { - workflowRelPath = `${match[1]}/${match[2]}`; - } } - // Determine if this is a YAML workflow (use normalized path which is guaranteed to be a string) - const isYamlWorkflow = workflowRelPath.endsWith('.yaml') || workflowRelPath.endsWith('.yml'); + // Determine if this is a YAML workflow + const isYamlWorkflow = workflow.path.endsWith('.yaml') || workflow.path.endsWith('.yml'); artifacts.push({ type: 'workflow-command', isYamlWorkflow: isYamlWorkflow, // For template selection @@ -133,8 +125,8 @@ class WorkflowCommandGenerator { const template = await fs.readFile(templatePath, 'utf8'); // Convert source path to installed path - // From: /Users/.../src/bmm/workflows/.../workflow.yaml - // To: {project-root}/_bmad/bmm/workflows/.../workflow.yaml + // From: /Users/.../src/bmm/workflows/.../workflow.md + // To: {project-root}/_bmad/bmm/workflows/.../workflow.md let workflowPath = workflow.path; // Extract the relative path from source @@ -218,9 +210,9 @@ class WorkflowCommandGenerator { ## Execution When running any workflow: -1. LOAD {project-root}/${this.bmadFolderName}/core/tasks/workflow.xml +1. LOAD {project-root}/${this.bmadFolderName}/core/tasks/workflow.md 2. Pass the workflow path as 'workflow-config' parameter -3. Follow workflow.xml instructions EXACTLY +3. Follow workflow.md instructions EXACTLY 4. Save outputs after EACH section ## Modes @@ -292,7 +284,7 @@ When running any workflow: * Write workflow command artifacts using dash format (NEW STANDARD) * Creates flat files like: bmad-bmm-correct-course.md * - * Note: Workflows do NOT have bmad-agent- prefix - only agents do. + * Note: Workflows do NOT have .agent.md suffix - only agents do. * * @param {string} baseCommandsDir - Base commands directory for the IDE * @param {Array} artifacts - Workflow artifacts diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index c55dae838..8ee63047f 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -740,10 +740,10 @@ class ModuleManager { } } - // Check if this is a workflow.yaml file - if (file.endsWith('workflow.yaml')) { + // Check if this is a workflow file (YAML or MD) + if (file.endsWith('workflow.yaml') || file.endsWith('workflow.md')) { await fs.ensureDir(path.dirname(targetFile)); - await this.copyWorkflowYamlStripped(sourceFile, targetFile); + await this.copyWorkflowFileStripped(sourceFile, targetFile); } else { // Copy the file with placeholder replacement await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile); @@ -757,12 +757,23 @@ class ModuleManager { } /** - * Copy workflow.yaml file with web_bundle section stripped + * Copy workflow file with web_bundle section stripped (YAML or MD) * Preserves comments, formatting, and line breaks - * @param {string} sourceFile - Source workflow.yaml file path - * @param {string} targetFile - Target workflow.yaml file path + * @param {string} sourceFile - Source workflow file path + * @param {string} targetFile - Target workflow file path */ - async copyWorkflowYamlStripped(sourceFile, targetFile) { + async copyWorkflowFileStripped(sourceFile, targetFile) { + if (sourceFile.endsWith('.md')) { + let mdContent = await fs.readFile(sourceFile, 'utf8'); + + mdContent = mdContent.replaceAll('_bmad', '_bmad'); + mdContent = mdContent.replaceAll('_bmad', this.bmadFolderName); + mdContent = this.stripWebBundleFromFrontmatter(mdContent); + + await fs.writeFile(targetFile, mdContent, 'utf8'); + return; + } + // Read the source YAML file let yamlContent = await fs.readFile(sourceFile, 'utf8'); @@ -843,6 +854,20 @@ class ModuleManager { } } + stripWebBundleFromFrontmatter(content) { + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) { + return content; + } + + const frontmatter = frontmatterMatch[1] + .split('\n') + .filter((line) => !line.trim().startsWith('web_bundle:')) + .join('\n'); + + return content.replace(frontmatterMatch[0], `---\n${frontmatter}\n---`); + } + /** * Compile .agent.yaml files to .md format in modules * @param {string} sourcePath - Source module path @@ -1151,8 +1176,8 @@ class ModuleManager { // Parse SOURCE workflow path // Handle both _bmad placeholder and hardcoded 'bmad' - // Example: {project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml - // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml + // Example: {project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.md + // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.md const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/); if (!sourceMatch) { console.warn(chalk.yellow(` Could not parse workflow path: ${sourceWorkflowPath}`)); @@ -1163,7 +1188,7 @@ class ModuleManager { // Parse INSTALL workflow path // Handle_bmad - // Example: {project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml + // Example: {project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.md const installMatch = installWorkflowPath.match(/\{project-root\}\/(_bmad)\/([^/]+)\/workflows\/(.+)/); if (!installMatch) { console.warn(chalk.yellow(` Could not parse workflow-install path: ${installWorkflowPath}`)); @@ -1173,9 +1198,13 @@ class ModuleManager { const installWorkflowSubPath = installMatch[2]; const sourceModulePath = getModulePath(sourceModule); - const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')); + const actualSourceWorkflowPath = path.join( + sourceModulePath, + 'workflows', + sourceWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, ''), + ); - const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')); + const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')); // Check if source workflow exists if (!(await fs.pathExists(actualSourceWorkflowPath))) { @@ -1186,7 +1215,7 @@ class ModuleManager { // Copy the entire workflow folder console.log( chalk.dim( - ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')}`, + ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')}`, ), ); @@ -1194,9 +1223,13 @@ class ModuleManager { // Copy the workflow directory recursively with placeholder replacement await this.copyDirectoryWithPlaceholderReplacement(actualSourceWorkflowPath, actualDestWorkflowPath); - // Update the workflow.yaml config_source reference + // Update workflow config_source references + const workflowMdPath = path.join(actualDestWorkflowPath, 'workflow.md'); const workflowYamlPath = path.join(actualDestWorkflowPath, 'workflow.yaml'); - if (await fs.pathExists(workflowYamlPath)) { + + if (await fs.pathExists(workflowMdPath)) { + await this.updateWorkflowConfigSource(workflowMdPath, moduleName); + } else if (await fs.pathExists(workflowYamlPath)) { await this.updateWorkflowConfigSource(workflowYamlPath, moduleName); } } @@ -1208,24 +1241,24 @@ class ModuleManager { } /** - * Update workflow.yaml config_source to point to new module - * @param {string} workflowYamlPath - Path to workflow.yaml file + * Update workflow config_source/main_config to point to new module + * @param {string} workflowPath - Path to workflow file * @param {string} newModuleName - New module name to reference */ - async updateWorkflowConfigSource(workflowYamlPath, newModuleName) { - let yamlContent = await fs.readFile(workflowYamlPath, 'utf8'); + async updateWorkflowConfigSource(workflowPath, newModuleName) { + let fileContent = await fs.readFile(workflowPath, 'utf8'); // Replace config_source: "{project-root}/_bmad/OLD_MODULE/config.yaml" // with config_source: "{project-root}/_bmad/NEW_MODULE/config.yaml" // Note: At this point _bmad has already been replaced with actual folder name - const configSourcePattern = /config_source:\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g; - const newConfigSource = `config_source: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`; + const configSourcePattern = /(config_source|main_config):\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g; + const newConfigSource = `$1: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`; - const updatedYaml = yamlContent.replaceAll(configSourcePattern, newConfigSource); + const updatedContent = fileContent.replaceAll(configSourcePattern, newConfigSource); - if (updatedYaml !== yamlContent) { - await fs.writeFile(workflowYamlPath, updatedYaml, 'utf8'); - console.log(chalk.dim(` Updated config_source to: ${this.bmadFolderName}/${newModuleName}/config.yaml`)); + if (updatedContent !== fileContent) { + await fs.writeFile(workflowPath, updatedContent, 'utf8'); + console.log(chalk.dim(` Updated workflow config to: ${this.bmadFolderName}/${newModuleName}/config.yaml`)); } } From de638745202516113b8b14515e9c8b7530eb3a22 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 16:27:54 +0000 Subject: [PATCH 06/22] Remove workflow.xml runner and update CLI wording --- test/test-installation-components.js | 14 -------------- .../cli/installers/lib/core/manifest-generator.js | 2 +- tools/cli/installers/lib/ide/_base-ide.js | 2 +- 3 files changed, 2 insertions(+), 16 deletions(-) diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 6efee44e8..2ce332df4 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -195,7 +195,6 @@ async function runTests() { const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs')]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); const forbiddenRef = 'advanced-elicitation/workflow.xml'; - const excludedFile = path.join(projectRoot, 'src', 'core', 'workflows', 'advanced-elicitation', 'workflow.xml'); const offenders = []; const walk = async (dir) => { @@ -209,9 +208,6 @@ async function runTests() { if (!allowedExtensions.has(path.extname(entry.name))) { continue; } - if (fullPath === excludedFile) { - continue; - } const content = await fs.readFile(fullPath, 'utf8'); if (content.includes(forbiddenRef)) { offenders.push(path.relative(projectRoot, fullPath)); @@ -257,9 +253,6 @@ async function runTests() { if (!allowedExtensions.has(path.extname(entry.name))) { continue; } - if (fullPath === excludedFile) { - continue; - } const content = await fs.readFile(fullPath, 'utf8'); if (content.includes(forbiddenRef)) { offenders.push(path.relative(projectRoot, fullPath)); @@ -291,10 +284,6 @@ async function runTests() { const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs'), path.join(projectRoot, 'tools')]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); const forbiddenRef = 'workflow.xml'; - const excludedFiles = new Set([ - path.join(projectRoot, 'src', 'core', 'tasks', 'workflow.xml'), - path.join(projectRoot, 'src', 'core', 'workflows', 'advanced-elicitation', 'workflow.xml'), - ]); const offenders = []; const walk = async (dir) => { @@ -308,9 +297,6 @@ async function runTests() { if (!allowedExtensions.has(path.extname(entry.name))) { continue; } - if (excludedFiles.has(fullPath)) { - continue; - } const content = await fs.readFile(fullPath, 'utf8'); if (content.includes(forbiddenRef)) { offenders.push(path.relative(projectRoot, fullPath)); diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index c0b5c655a..eefc12b69 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -130,7 +130,7 @@ class ManifestGenerator { } /** - * Recursively find and parse workflow.yaml and workflow.md files + * Recursively find and parse workflow definition files */ async getWorkflowsFromPath(basePath, moduleName) { const workflows = []; diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index fd3d5f7d3..b82f3b6cf 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -324,7 +324,7 @@ class BaseIdeSetup { } /** - * Recursively find workflow files (workflow.yaml or workflow.md) + * Recursively find workflow definition files * @param {string} dir - Directory to search * @returns {Array} List of workflow file info objects */ From 2224edaa84bb72d0383ebfb262414a7a3f739b7b Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 16:46:38 +0000 Subject: [PATCH 07/22] Drop YAML workflow support from CLI tooling --- .../installers/lib/core/manifest-generator.js | 294 ++++++++---------- tools/cli/installers/lib/ide/_base-ide.js | 14 +- .../cli/installers/lib/ide/_config-driven.js | 160 ++-------- .../ide/shared/workflow-command-generator.js | 9 +- tools/cli/installers/lib/modules/manager.js | 121 +------ 5 files changed, 183 insertions(+), 415 deletions(-) diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index eefc12b69..9883eac4c 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -2,7 +2,6 @@ const path = require('node:path'); const fs = require('fs-extra'); const yaml = require('yaml'); const crypto = require('node:crypto'); -const csv = require('csv-parse/sync'); const { getSourcePath, getModulePath } = require('../../../lib/project-root'); // Load package.json for version info @@ -22,19 +21,6 @@ class ManifestGenerator { this.selectedIdes = []; } - /** - * Clean text for CSV output by normalizing whitespace and escaping quotes - * @param {string} text - Text to clean - * @returns {string} Cleaned text safe for CSV - */ - cleanForCSV(text) { - if (!text) return ''; - return text - .trim() - .replaceAll(/\s+/g, ' ') // Normalize all whitespace (including newlines) to single space - .replaceAll('"', '""'); // Escape quotes for CSV - } - /** * Generate all manifests for the installation * @param {string} bmadDir - _bmad @@ -159,12 +145,8 @@ class ManifestGenerator { // Recurse into subdirectories const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; await findWorkflows(fullPath, newRelativePath); - } else if ( - entry.name === 'workflow.yaml' || - entry.name === 'workflow.md' || - (entry.name.startsWith('workflow-') && entry.name.endsWith('.md')) - ) { - // Parse workflow file (both YAML and MD formats) + } else if (entry.name === 'workflow.md') { + // Parse workflow file (MD with YAML frontmatter) if (debug) { console.log(`[DEBUG] Found workflow file: ${fullPath}`); } @@ -173,21 +155,15 @@ class ManifestGenerator { const rawContent = await fs.readFile(fullPath, 'utf8'); const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); - let workflow; - if (entry.name === 'workflow.yaml') { - // Parse YAML workflow - workflow = yaml.parse(content); - } else { - // Parse MD workflow with YAML frontmatter - const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); - if (!frontmatterMatch) { - if (debug) { - console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`); - } - continue; // Skip MD files without frontmatter + // Parse MD workflow with YAML frontmatter + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) { + if (debug) { + console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`); } - workflow = yaml.parse(frontmatterMatch[1]); + continue; // Skip MD files without frontmatter } + const workflow = yaml.parse(frontmatterMatch[1]); if (debug) { console.log(`[DEBUG] Parsed: name="${workflow.name}", description=${workflow.description ? 'OK' : 'MISSING'}`); @@ -219,7 +195,7 @@ class ManifestGenerator { // Workflows with standalone: false are filtered out above workflows.push({ name: workflow.name, - description: this.cleanForCSV(workflow.description), + description: workflow.description.replaceAll('"', '""'), // Escape quotes for CSV module: moduleName, path: installPath, }); @@ -337,15 +313,24 @@ class ManifestGenerator { const agentName = entry.name.replace('.md', ''); + // Helper function to clean and escape CSV content + const cleanForCSV = (text) => { + if (!text) return ''; + return text + .trim() + .replaceAll(/\s+/g, ' ') // Normalize whitespace + .replaceAll('"', '""'); // Escape quotes for CSV + }; + agents.push({ name: agentName, displayName: nameMatch ? nameMatch[1] : agentName, title: titleMatch ? titleMatch[1] : '', icon: iconMatch ? iconMatch[1] : '', - role: roleMatch ? this.cleanForCSV(roleMatch[1]) : '', - identity: identityMatch ? this.cleanForCSV(identityMatch[1]) : '', - communicationStyle: styleMatch ? this.cleanForCSV(styleMatch[1]) : '', - principles: principlesMatch ? this.cleanForCSV(principlesMatch[1]) : '', + role: roleMatch ? cleanForCSV(roleMatch[1]) : '', + identity: identityMatch ? cleanForCSV(identityMatch[1]) : '', + communicationStyle: styleMatch ? cleanForCSV(styleMatch[1]) : '', + principles: principlesMatch ? cleanForCSV(principlesMatch[1]) : '', module: moduleName, path: installPath, }); @@ -394,11 +379,6 @@ class ManifestGenerator { const filePath = path.join(dirPath, file); const content = await fs.readFile(filePath, 'utf8'); - // Skip internal/engine files (not user-facing tasks) - if (content.includes('internal="true"')) { - continue; - } - let name = file.replace(/\.(xml|md)$/, ''); let displayName = name; let description = ''; @@ -406,21 +386,17 @@ class ManifestGenerator { if (file.endsWith('.md')) { // Parse YAML frontmatter for .md tasks - const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); if (frontmatterMatch) { try { const frontmatter = yaml.parse(frontmatterMatch[1]); name = frontmatter.name || name; displayName = frontmatter.displayName || frontmatter.name || name; - description = this.cleanForCSV(frontmatter.description || ''); - // Tasks are standalone by default unless explicitly false (internal=true is already filtered above) - standalone = frontmatter.standalone !== false && frontmatter.standalone !== 'false'; + description = frontmatter.description || ''; + standalone = frontmatter.standalone === true || frontmatter.standalone === 'true'; } catch { // If YAML parsing fails, use defaults - standalone = true; // Default to standalone } - } else { - standalone = true; // No frontmatter means standalone } } else { // For .xml tasks, extract from tag attributes @@ -429,10 +405,10 @@ class ManifestGenerator { const descMatch = content.match(/description="([^"]+)"/); const objMatch = content.match(/([^<]+)<\/objective>/); - description = this.cleanForCSV(descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''); + description = descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''; - const standaloneFalseMatch = content.match(/]+standalone="false"/); - standalone = !standaloneFalseMatch; + const standaloneMatch = content.match(/]+standalone="true"/); + standalone = !!standaloneMatch; } // Build relative path for installation @@ -442,7 +418,7 @@ class ManifestGenerator { tasks.push({ name: name, displayName: displayName, - description: description, + description: description.replaceAll('"', '""'), module: moduleName, path: installPath, standalone: standalone, @@ -492,11 +468,6 @@ class ManifestGenerator { const filePath = path.join(dirPath, file); const content = await fs.readFile(filePath, 'utf8'); - // Skip internal tools (same as tasks) - if (content.includes('internal="true"')) { - continue; - } - let name = file.replace(/\.(xml|md)$/, ''); let displayName = name; let description = ''; @@ -504,21 +475,17 @@ class ManifestGenerator { if (file.endsWith('.md')) { // Parse YAML frontmatter for .md tools - const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); if (frontmatterMatch) { try { const frontmatter = yaml.parse(frontmatterMatch[1]); name = frontmatter.name || name; displayName = frontmatter.displayName || frontmatter.name || name; - description = this.cleanForCSV(frontmatter.description || ''); - // Tools are standalone by default unless explicitly false (internal=true is already filtered above) - standalone = frontmatter.standalone !== false && frontmatter.standalone !== 'false'; + description = frontmatter.description || ''; + standalone = frontmatter.standalone === true || frontmatter.standalone === 'true'; } catch { // If YAML parsing fails, use defaults - standalone = true; // Default to standalone } - } else { - standalone = true; // No frontmatter means standalone } } else { // For .xml tools, extract from tag attributes @@ -527,10 +494,10 @@ class ManifestGenerator { const descMatch = content.match(/description="([^"]+)"/); const objMatch = content.match(/([^<]+)<\/objective>/); - description = this.cleanForCSV(descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''); + description = descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''; - const standaloneFalseMatch = content.match(/]+standalone="false"/); - standalone = !standaloneFalseMatch; + const standaloneMatch = content.match(/]+standalone="true"/); + standalone = !!standaloneMatch; } // Build relative path for installation @@ -540,7 +507,7 @@ class ManifestGenerator { tools.push({ name: name, displayName: displayName, - description: description, + description: description.replaceAll('"', '""'), module: moduleName, path: installPath, standalone: standalone, @@ -733,15 +700,47 @@ class ManifestGenerator { async writeWorkflowManifest(cfgDir) { const csvPath = path.join(cfgDir, 'workflow-manifest.csv'); const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; + const parseCsvLine = (line) => { + const columns = line.match(/(".*?"|[^",\s]+)(?=\s*,|\s*$)/g) || []; + return columns.map((c) => c.replaceAll(/^"|"$/g, '')); + }; + + // Read existing manifest to preserve entries + const existingEntries = new Map(); + if (await fs.pathExists(csvPath)) { + const content = await fs.readFile(csvPath, 'utf8'); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + const parts = parseCsvLine(line); + if (parts.length >= 4) { + const [name, description, module, workflowPath] = parts; + existingEntries.set(`${module}:${name}`, { + name, + description, + module, + path: workflowPath, + }); + } + } + } + } // Create CSV header - standalone column removed, everything is canonicalized to 4 columns let csv = 'name,description,module,path\n'; - // Build workflows map from discovered workflows only - // Old entries are NOT preserved - the manifest reflects what actually exists on disk + // Combine existing and new workflows const allWorkflows = new Map(); - // Only add workflows that were actually discovered in this scan + // Add existing entries + for (const [key, value] of existingEntries) { + allWorkflows.set(key, value); + } + + // Add/update new workflows for (const workflow of this.workflows) { const key = `${workflow.module}:${workflow.name}`; allWorkflows.set(key, { @@ -768,23 +767,30 @@ class ManifestGenerator { */ async writeAgentManifest(cfgDir) { const csvPath = path.join(cfgDir, 'agent-manifest.csv'); - const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; // Read existing manifest to preserve entries const existingEntries = new Map(); if (await fs.pathExists(csvPath)) { const content = await fs.readFile(csvPath, 'utf8'); - const records = csv.parse(content, { - columns: true, - skip_empty_lines: true, - }); - for (const record of records) { - existingEntries.set(`${record.module}:${record.name}`, record); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 11) { + const name = parts[0].replace(/^"/, ''); + const module = parts[8]; + existingEntries.set(`${module}:${name}`, line); + } + } } } // Create CSV header with persona fields - let csvContent = 'name,displayName,title,icon,role,identity,communicationStyle,principles,module,path\n'; + let csv = 'name,displayName,title,icon,role,identity,communicationStyle,principles,module,path\n'; // Combine existing and new agents, preferring new data for duplicates const allAgents = new Map(); @@ -797,38 +803,18 @@ class ManifestGenerator { // Add/update new agents for (const agent of this.agents) { const key = `${agent.module}:${agent.name}`; - allAgents.set(key, { - name: agent.name, - displayName: agent.displayName, - title: agent.title, - icon: agent.icon, - role: agent.role, - identity: agent.identity, - communicationStyle: agent.communicationStyle, - principles: agent.principles, - module: agent.module, - path: agent.path, - }); + allAgents.set( + key, + `"${agent.name}","${agent.displayName}","${agent.title}","${agent.icon}","${agent.role}","${agent.identity}","${agent.communicationStyle}","${agent.principles}","${agent.module}","${agent.path}"`, + ); } // Write all agents - for (const [, record] of allAgents) { - const row = [ - escapeCsv(record.name), - escapeCsv(record.displayName), - escapeCsv(record.title), - escapeCsv(record.icon), - escapeCsv(record.role), - escapeCsv(record.identity), - escapeCsv(record.communicationStyle), - escapeCsv(record.principles), - escapeCsv(record.module), - escapeCsv(record.path), - ].join(','); - csvContent += row + '\n'; + for (const [, value] of allAgents) { + csv += value + '\n'; } - await fs.writeFile(csvPath, csvContent); + await fs.writeFile(csvPath, csv); return csvPath; } @@ -838,23 +824,30 @@ class ManifestGenerator { */ async writeTaskManifest(cfgDir) { const csvPath = path.join(cfgDir, 'task-manifest.csv'); - const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; // Read existing manifest to preserve entries const existingEntries = new Map(); if (await fs.pathExists(csvPath)) { const content = await fs.readFile(csvPath, 'utf8'); - const records = csv.parse(content, { - columns: true, - skip_empty_lines: true, - }); - for (const record of records) { - existingEntries.set(`${record.module}:${record.name}`, record); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 6) { + const name = parts[0].replace(/^"/, ''); + const module = parts[3]; + existingEntries.set(`${module}:${name}`, line); + } + } } } // Create CSV header with standalone column - let csvContent = 'name,displayName,description,module,path,standalone\n'; + let csv = 'name,displayName,description,module,path,standalone\n'; // Combine existing and new tasks const allTasks = new Map(); @@ -867,30 +860,15 @@ class ManifestGenerator { // Add/update new tasks for (const task of this.tasks) { const key = `${task.module}:${task.name}`; - allTasks.set(key, { - name: task.name, - displayName: task.displayName, - description: task.description, - module: task.module, - path: task.path, - standalone: task.standalone, - }); + allTasks.set(key, `"${task.name}","${task.displayName}","${task.description}","${task.module}","${task.path}","${task.standalone}"`); } // Write all tasks - for (const [, record] of allTasks) { - const row = [ - escapeCsv(record.name), - escapeCsv(record.displayName), - escapeCsv(record.description), - escapeCsv(record.module), - escapeCsv(record.path), - escapeCsv(record.standalone), - ].join(','); - csvContent += row + '\n'; + for (const [, value] of allTasks) { + csv += value + '\n'; } - await fs.writeFile(csvPath, csvContent); + await fs.writeFile(csvPath, csv); return csvPath; } @@ -900,23 +878,30 @@ class ManifestGenerator { */ async writeToolManifest(cfgDir) { const csvPath = path.join(cfgDir, 'tool-manifest.csv'); - const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; // Read existing manifest to preserve entries const existingEntries = new Map(); if (await fs.pathExists(csvPath)) { const content = await fs.readFile(csvPath, 'utf8'); - const records = csv.parse(content, { - columns: true, - skip_empty_lines: true, - }); - for (const record of records) { - existingEntries.set(`${record.module}:${record.name}`, record); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 6) { + const name = parts[0].replace(/^"/, ''); + const module = parts[3]; + existingEntries.set(`${module}:${name}`, line); + } + } } } // Create CSV header with standalone column - let csvContent = 'name,displayName,description,module,path,standalone\n'; + let csv = 'name,displayName,description,module,path,standalone\n'; // Combine existing and new tools const allTools = new Map(); @@ -929,30 +914,15 @@ class ManifestGenerator { // Add/update new tools for (const tool of this.tools) { const key = `${tool.module}:${tool.name}`; - allTools.set(key, { - name: tool.name, - displayName: tool.displayName, - description: tool.description, - module: tool.module, - path: tool.path, - standalone: tool.standalone, - }); + allTools.set(key, `"${tool.name}","${tool.displayName}","${tool.description}","${tool.module}","${tool.path}","${tool.standalone}"`); } // Write all tools - for (const [, record] of allTools) { - const row = [ - escapeCsv(record.name), - escapeCsv(record.displayName), - escapeCsv(record.description), - escapeCsv(record.module), - escapeCsv(record.path), - escapeCsv(record.standalone), - ].join(','); - csvContent += row + '\n'; + for (const [, value] of allTools) { + csv += value + '\n'; } - await fs.writeFile(csvPath, csvContent); + await fs.writeFile(csvPath, csv); return csvPath; } diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index b82f3b6cf..3c25befee 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -344,22 +344,18 @@ class BaseIdeSetup { // Recursively search subdirectories const subWorkflows = await this.findWorkflowFiles(fullPath); workflows.push(...subWorkflows); - } else if (entry.isFile() && (entry.name === 'workflow.yaml' || entry.name === 'workflow.md')) { + } else if (entry.isFile() && entry.name === 'workflow.md') { // Read workflow file to get name and standalone property try { const yaml = require('yaml'); const content = await fs.readFile(fullPath, 'utf8'); let workflowData = null; - if (entry.name === 'workflow.yaml') { - workflowData = yaml.parse(content); - } else { - const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); - if (!frontmatterMatch) { - continue; - } - workflowData = yaml.parse(frontmatterMatch[1]); + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) { + continue; } + workflowData = yaml.parse(frontmatterMatch[1]); if (workflowData && workflowData.name) { // Workflows are standalone by default unless explicitly false diff --git a/tools/cli/installers/lib/ide/_config-driven.js b/tools/cli/installers/lib/ide/_config-driven.js index 486889267..0ceff98a8 100644 --- a/tools/cli/installers/lib/ide/_config-driven.js +++ b/tools/cli/installers/lib/ide/_config-driven.js @@ -66,13 +66,6 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { */ async installToTarget(projectDir, bmadDir, config, options) { const { target_dir, template_type, artifact_types } = config; - - // Skip targets with explicitly empty artifact_types array - // This prevents creating empty directories when no artifacts will be written - if (Array.isArray(artifact_types) && artifact_types.length === 0) { - return { success: true, results: { agents: 0, workflows: 0, tasks: 0, tools: 0 } }; - } - const targetPath = path.join(projectDir, target_dir); await this.ensureDir(targetPath); @@ -93,11 +86,10 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { results.workflows = await this.writeWorkflowArtifacts(targetPath, artifacts, template_type, config); } - // Install tasks and tools using template system (supports TOML for Gemini, MD for others) + // Install tasks and tools if (!artifact_types || artifact_types.includes('tasks') || artifact_types.includes('tools')) { - const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); - const { artifacts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); - const taskToolResult = await this.writeTaskToolArtifacts(targetPath, artifacts, template_type, config); + const taskToolGen = new TaskToolCommandGenerator(); + const taskToolResult = await taskToolGen.generateDashTaskToolCommands(projectDir, bmadDir, targetPath); results.tasks = taskToolResult.tasks || 0; results.tools = taskToolResult.tools || 0; } @@ -140,12 +132,12 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { */ async writeAgentArtifacts(targetPath, artifacts, templateType, config = {}) { // Try to load platform-specific template, fall back to default-agent - const { content: template, extension } = await this.loadTemplate(templateType, 'agent', config, 'default-agent'); + const template = await this.loadTemplate(templateType, 'agent', config, 'default-agent'); let count = 0; for (const artifact of artifacts) { const content = this.renderTemplate(template, artifact); - const filename = this.generateFilename(artifact, 'agent', extension); + const filename = this.generateFilename(artifact, 'agent'); const filePath = path.join(targetPath, filename); await this.writeFile(filePath, content); count++; @@ -167,18 +159,14 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { for (const artifact of artifacts) { if (artifact.type === 'workflow-command') { - // Use different template based on workflow type (YAML vs MD) // Default to 'default' template type, but allow override via config - const workflowTemplateType = artifact.isYamlWorkflow - ? config.yaml_workflow_template || `${templateType}-workflow-yaml` - : config.md_workflow_template || `${templateType}-workflow`; + const workflowTemplateType = config.md_workflow_template || `${templateType}-workflow`; - // Fall back to default templates if specific ones don't exist - const finalTemplateType = artifact.isYamlWorkflow ? 'default-workflow-yaml' : 'default-workflow'; - // workflowTemplateType already contains full name (e.g., 'gemini-workflow-yaml'), so pass empty artifactType - const { content: template, extension } = await this.loadTemplate(workflowTemplateType, '', config, finalTemplateType); + // Fall back to default template if the requested one doesn't exist + const finalTemplateType = 'default-workflow'; + const template = await this.loadTemplate(workflowTemplateType, 'workflow', config, finalTemplateType); const content = this.renderTemplate(template, artifact); - const filename = this.generateFilename(artifact, 'workflow', extension); + const filename = this.generateFilename(artifact, 'workflow'); const filePath = path.join(targetPath, filename); await this.writeFile(filePath, content); count++; @@ -188,100 +176,40 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { return count; } - /** - * Write task/tool artifacts to target directory using templates - * @param {string} targetPath - Target directory path - * @param {Array} artifacts - Task/tool artifacts - * @param {string} templateType - Template type to use - * @param {Object} config - Installation configuration - * @returns {Promise} Counts of tasks and tools written - */ - async writeTaskToolArtifacts(targetPath, artifacts, templateType, config = {}) { - let taskCount = 0; - let toolCount = 0; - - // Pre-load templates to avoid repeated file I/O in the loop - const taskTemplate = await this.loadTemplate(templateType, 'task', config, 'default-task'); - const toolTemplate = await this.loadTemplate(templateType, 'tool', config, 'default-tool'); - - const { artifact_types } = config; - - for (const artifact of artifacts) { - if (artifact.type !== 'task' && artifact.type !== 'tool') { - continue; - } - - // Skip if the specific artifact type is not requested in config - if (artifact_types) { - if (artifact.type === 'task' && !artifact_types.includes('tasks')) continue; - if (artifact.type === 'tool' && !artifact_types.includes('tools')) continue; - } - - // Use pre-loaded template based on artifact type - const { content: template, extension } = artifact.type === 'task' ? taskTemplate : toolTemplate; - - const content = this.renderTemplate(template, artifact); - const filename = this.generateFilename(artifact, artifact.type, extension); - const filePath = path.join(targetPath, filename); - await this.writeFile(filePath, content); - - if (artifact.type === 'task') { - taskCount++; - } else { - toolCount++; - } - } - - return { tasks: taskCount, tools: toolCount }; - } - /** * Load template based on type and configuration * @param {string} templateType - Template type (claude, windsurf, etc.) * @param {string} artifactType - Artifact type (agent, workflow, task, tool) * @param {Object} config - Installation configuration * @param {string} fallbackTemplateType - Fallback template type if requested template not found - * @returns {Promise<{content: string, extension: string}>} Template content and extension + * @returns {Promise} Template content */ async loadTemplate(templateType, artifactType, config = {}, fallbackTemplateType = null) { const { header_template, body_template } = config; // Check for separate header/body templates if (header_template || body_template) { - const content = await this.loadSplitTemplates(templateType, artifactType, header_template, body_template); - // Allow config to override extension, default to .md - const ext = config.extension || '.md'; - const normalizedExt = ext.startsWith('.') ? ext : `.${ext}`; - return { content, extension: normalizedExt }; + return await this.loadSplitTemplates(templateType, artifactType, header_template, body_template); } - // Load combined template - try multiple extensions - // If artifactType is empty, templateType already contains full name (e.g., 'gemini-workflow-yaml') - const templateBaseName = artifactType ? `${templateType}-${artifactType}` : templateType; - const templateDir = path.join(__dirname, 'templates', 'combined'); - const extensions = ['.md', '.toml', '.yaml', '.yml']; + // Load combined template + const templateName = `${templateType}-${artifactType}.md`; + const templatePath = path.join(__dirname, 'templates', 'combined', templateName); - for (const ext of extensions) { - const templatePath = path.join(templateDir, templateBaseName + ext); - if (await fs.pathExists(templatePath)) { - const content = await fs.readFile(templatePath, 'utf8'); - return { content, extension: ext }; - } + if (await fs.pathExists(templatePath)) { + return await fs.readFile(templatePath, 'utf8'); } // Fall back to default template (if provided) if (fallbackTemplateType) { - for (const ext of extensions) { - const fallbackPath = path.join(templateDir, `${fallbackTemplateType}${ext}`); - if (await fs.pathExists(fallbackPath)) { - const content = await fs.readFile(fallbackPath, 'utf8'); - return { content, extension: ext }; - } + const fallbackPath = path.join(__dirname, 'templates', 'combined', `${fallbackTemplateType}.md`); + if (await fs.pathExists(fallbackPath)) { + return await fs.readFile(fallbackPath, 'utf8'); } } // Ultimate fallback - minimal template - return { content: this.getDefaultTemplate(artifactType), extension: '.md' }; + return this.getDefaultTemplate(artifactType); } /** @@ -338,7 +266,6 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { return `--- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- You must fully embody this agent's persona and follow all activation instructions exactly as specified. @@ -353,7 +280,6 @@ You must fully embody this agent's persona and follow all activation instruction return `--- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- # {{name}} @@ -371,24 +297,10 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} renderTemplate(template, artifact) { // Use the appropriate path property based on artifact type let pathToUse = artifact.relativePath || ''; - switch (artifact.type) { - case 'agent-launcher': { - pathToUse = artifact.agentPath || artifact.relativePath || ''; - - break; - } - case 'workflow-command': { - pathToUse = artifact.workflowPath || artifact.relativePath || ''; - - break; - } - case 'task': - case 'tool': { - pathToUse = artifact.path || artifact.relativePath || ''; - - break; - } - // No default + if (artifact.type === 'agent-launcher') { + pathToUse = artifact.agentPath || artifact.relativePath || ''; + } else if (artifact.type === 'workflow-command') { + pathToUse = artifact.workflowPath || artifact.relativePath || ''; } let rendered = template @@ -411,27 +323,13 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} * Generate filename for artifact * @param {Object} artifact - Artifact data * @param {string} artifactType - Artifact type (agent, workflow, task, tool) - * @param {string} extension - File extension to use (e.g., '.md', '.toml') * @returns {string} Generated filename */ - generateFilename(artifact, artifactType, extension = '.md') { + generateFilename(artifact, artifactType) { const { toDashPath } = require('./shared/path-utils'); - - // Reuse central logic to ensure consistent naming conventions - const standardName = toDashPath(artifact.relativePath); - - // Clean up potential double extensions from source files (e.g. .yaml.md, .xml.md -> .md) - // This handles any extensions that might slip through toDashPath() - const baseName = standardName.replace(/\.(md|yaml|yml|json|xml|toml)\.md$/i, '.md'); - - // If using default markdown, preserve the bmad-agent- prefix for agents - if (extension === '.md') { - return baseName; - } - - // For other extensions (e.g., .toml), replace .md extension - // Note: agent prefix is preserved even with non-markdown extensions - return baseName.replace(/\.md$/, extension); + // toDashPath already handles the .agent.md suffix for agents correctly + // No need to add it again here + return toDashPath(artifact.relativePath); } /** diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index c01429397..d5055f491 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -9,7 +9,7 @@ const { toColonPath, toDashPath, customAgentColonName, customAgentDashName } = r */ class WorkflowCommandGenerator { constructor(bmadFolderName = 'bmad') { - this.templatePath = path.join(__dirname, '../templates/workflow-command-template.md'); + this.templatePath = path.join(__dirname, '../templates/workflow-commander.md'); this.bmadFolderName = bmadFolderName; } @@ -77,11 +77,8 @@ class WorkflowCommandGenerator { workflowRelPath = parts.slice(1).join('/'); } } - // Determine if this is a YAML workflow - const isYamlWorkflow = workflow.path.endsWith('.yaml') || workflow.path.endsWith('.yml'); artifacts.push({ type: 'workflow-command', - isYamlWorkflow: isYamlWorkflow, // For template selection name: workflow.name, description: workflow.description || `${workflow.name} workflow`, module: workflow.module, @@ -117,9 +114,7 @@ class WorkflowCommandGenerator { */ async generateCommandContent(workflow, bmadDir) { // Determine template based on workflow file type - const isMarkdownWorkflow = workflow.path.endsWith('workflow.md'); - const templateName = isMarkdownWorkflow ? 'workflow-commander.md' : 'workflow-command-template.md'; - const templatePath = path.join(path.dirname(this.templatePath), templateName); + const templatePath = path.join(path.dirname(this.templatePath), 'workflow-commander.md'); // Load the appropriate template const template = await fs.readFile(templatePath, 'utf8'); diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index 8ee63047f..b91f59158 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -7,7 +7,6 @@ const { XmlHandler } = require('../../../lib/xml-handler'); const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/project-root'); const { filterCustomizationData } = require('../../../lib/agent/compiler'); const { ExternalModuleManager } = require('./external-manager'); -const { BMAD_FOLDER_NAME } = require('../ide/shared/path-utils'); /** * Manages the installation, updating, and removal of BMAD modules. @@ -28,7 +27,7 @@ const { BMAD_FOLDER_NAME } = require('../ide/shared/path-utils'); class ModuleManager { constructor(options = {}) { this.xmlHandler = new XmlHandler(); - this.bmadFolderName = BMAD_FOLDER_NAME; // Default, can be overridden + this.bmadFolderName = 'bmad'; // Default, can be overridden this.customModulePaths = new Map(); // Initialize custom module paths this.externalModuleManager = new ExternalModuleManager(); // For external official modules } @@ -417,7 +416,7 @@ class ModuleManager { if (needsDependencyInstall || wasNewClone || nodeModulesMissing) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { + execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout @@ -442,7 +441,7 @@ class ModuleManager { if (packageJsonNewer) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { + execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout @@ -740,8 +739,8 @@ class ModuleManager { } } - // Check if this is a workflow file (YAML or MD) - if (file.endsWith('workflow.yaml') || file.endsWith('workflow.md')) { + // Check if this is a workflow file (MD) + if (file.endsWith('workflow.md')) { await fs.ensureDir(path.dirname(targetFile)); await this.copyWorkflowFileStripped(sourceFile, targetFile); } else { @@ -757,101 +756,19 @@ class ModuleManager { } /** - * Copy workflow file with web_bundle section stripped (YAML or MD) + * Copy workflow file with web_bundle section stripped (MD) * Preserves comments, formatting, and line breaks * @param {string} sourceFile - Source workflow file path * @param {string} targetFile - Target workflow file path */ async copyWorkflowFileStripped(sourceFile, targetFile) { - if (sourceFile.endsWith('.md')) { - let mdContent = await fs.readFile(sourceFile, 'utf8'); + let mdContent = await fs.readFile(sourceFile, 'utf8'); - mdContent = mdContent.replaceAll('_bmad', '_bmad'); - mdContent = mdContent.replaceAll('_bmad', this.bmadFolderName); - mdContent = this.stripWebBundleFromFrontmatter(mdContent); + mdContent = mdContent.replaceAll('_bmad', '_bmad'); + mdContent = mdContent.replaceAll('_bmad', this.bmadFolderName); + mdContent = this.stripWebBundleFromFrontmatter(mdContent); - await fs.writeFile(targetFile, mdContent, 'utf8'); - return; - } - - // Read the source YAML file - let yamlContent = await fs.readFile(sourceFile, 'utf8'); - - // IMPORTANT: Replace escape sequence and placeholder BEFORE parsing YAML - // Otherwise parsing will fail on the placeholder - yamlContent = yamlContent.replaceAll('_bmad', '_bmad'); - yamlContent = yamlContent.replaceAll('_bmad', this.bmadFolderName); - - try { - // First check if web_bundle exists by parsing - const workflowConfig = yaml.parse(yamlContent); - - if (workflowConfig.web_bundle === undefined) { - // No web_bundle section, just write (placeholders already replaced above) - await fs.writeFile(targetFile, yamlContent, 'utf8'); - return; - } - - // Find the line that starts web_bundle - const lines = yamlContent.split('\n'); - let startIdx = -1; - let endIdx = -1; - let baseIndent = 0; - - // Find the start of web_bundle section - for (const [i, line] of lines.entries()) { - const match = line.match(/^(\s*)web_bundle:/); - if (match) { - startIdx = i; - baseIndent = match[1].length; - break; - } - } - - if (startIdx === -1) { - // web_bundle not found in text (shouldn't happen), copy as-is - await fs.writeFile(targetFile, yamlContent, 'utf8'); - return; - } - - // Find the end of web_bundle section - // It ends when we find a line with same or less indentation that's not empty/comment - endIdx = startIdx; - for (let i = startIdx + 1; i < lines.length; i++) { - const line = lines[i]; - - // Skip empty lines and comments - if (line.trim() === '' || line.trim().startsWith('#')) { - continue; - } - - // Check indentation - const indent = line.match(/^(\s*)/)[1].length; - if (indent <= baseIndent) { - // Found next section at same or lower indentation - endIdx = i - 1; - break; - } - } - - // If we didn't find an end, it goes to end of file - if (endIdx === startIdx) { - endIdx = lines.length - 1; - } - - // Remove the web_bundle section (including the line before if it's just a blank line) - const newLines = [...lines.slice(0, startIdx), ...lines.slice(endIdx + 1)]; - - // Clean up any double blank lines that might result - const strippedYaml = newLines.join('\n').replaceAll(/\n\n\n+/g, '\n\n'); - - // Placeholders already replaced at the beginning of this function - await fs.writeFile(targetFile, strippedYaml, 'utf8'); - } catch { - // If anything fails, just copy the file as-is - console.warn(chalk.yellow(` Warning: Could not process ${path.basename(sourceFile)}, copying as-is`)); - await fs.copy(sourceFile, targetFile, { overwrite: true }); - } + await fs.writeFile(targetFile, mdContent, 'utf8'); } stripWebBundleFromFrontmatter(content) { @@ -892,7 +809,7 @@ class ModuleManager { for (const agentFile of agentFiles) { if (!agentFile.endsWith('.agent.yaml')) continue; - const relativePath = path.relative(sourceAgentsPath, agentFile).split(path.sep).join('/'); + const relativePath = path.relative(sourceAgentsPath, agentFile); const targetDir = path.join(targetAgentsPath, path.dirname(relativePath)); await fs.ensureDir(targetDir); @@ -1198,13 +1115,9 @@ class ModuleManager { const installWorkflowSubPath = installMatch[2]; const sourceModulePath = getModulePath(sourceModule); - const actualSourceWorkflowPath = path.join( - sourceModulePath, - 'workflows', - sourceWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, ''), - ); + const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')); - const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')); + const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.md$/, '')); // Check if source workflow exists if (!(await fs.pathExists(actualSourceWorkflowPath))) { @@ -1215,7 +1128,7 @@ class ModuleManager { // Copy the entire workflow folder console.log( chalk.dim( - ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.(yaml|md)$/, '')}`, + ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.md$/, '')}`, ), ); @@ -1225,12 +1138,8 @@ class ModuleManager { // Update workflow config_source references const workflowMdPath = path.join(actualDestWorkflowPath, 'workflow.md'); - const workflowYamlPath = path.join(actualDestWorkflowPath, 'workflow.yaml'); - if (await fs.pathExists(workflowMdPath)) { await this.updateWorkflowConfigSource(workflowMdPath, moduleName); - } else if (await fs.pathExists(workflowYamlPath)) { - await this.updateWorkflowConfigSource(workflowYamlPath, moduleName); } } } From b9bc4c3fadecdfcd6e32aadef3b5ec7c4f6c1530 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Fri, 6 Feb 2026 14:33:23 +0000 Subject: [PATCH 08/22] Fix remaining workflow.yaml/xml references --- src/bmm/agents/qa.agent.yaml | 2 +- src/bmm/agents/tea.agent.yaml | 1 - .../generate-project-context/steps/step-02-generate.md | 2 +- tools/cli/installers/lib/ide/shared/path-utils.js | 2 +- 4 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/bmm/agents/qa.agent.yaml b/src/bmm/agents/qa.agent.yaml index 07ca4022f..165b19b68 100644 --- a/src/bmm/agents/qa.agent.yaml +++ b/src/bmm/agents/qa.agent.yaml @@ -28,7 +28,7 @@ agent: menu: - trigger: QA or fuzzy match on qa-automate - workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.md" description: "[QA] Automate - Generate tests for existing features (simplified)" prompts: diff --git a/src/bmm/agents/tea.agent.yaml b/src/bmm/agents/tea.agent.yaml index 5bc6cb1b1..576e67997 100644 --- a/src/bmm/agents/tea.agent.yaml +++ b/src/bmm/agents/tea.agent.yaml @@ -1,7 +1,6 @@ # Test Architect + Quality Advisor Agent Definition agent: - webskip: true metadata: id: "_bmad/bmm/agents/tea.md" name: Murat diff --git a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md index c2b428c57..e0af3d68e 100644 --- a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md +++ b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md @@ -29,7 +29,7 @@ This step will generate content and present choices for each rule category: ## PROTOCOL INTEGRATION: -- When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding diff --git a/tools/cli/installers/lib/ide/shared/path-utils.js b/tools/cli/installers/lib/ide/shared/path-utils.js index 519669233..6864ec7d4 100644 --- a/tools/cli/installers/lib/ide/shared/path-utils.js +++ b/tools/cli/installers/lib/ide/shared/path-utils.js @@ -63,7 +63,7 @@ function toDashPath(relativePath) { } // Strip common file extensions to avoid double extensions in generated filenames - // e.g., 'create-story.xml' → 'create-story', 'workflow.yaml' → 'workflow' + // e.g., 'create-story.xml' → 'create-story', 'workflow.md' → 'workflow' const withoutExt = relativePath.replace(/\.(md|yaml|yml|json|xml|toml)$/i, ''); const parts = withoutExt.split(/[/\\]/); From cdddf77f55bc2bbef82bf3da2894959d71ed917f Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Fri, 6 Feb 2026 14:41:58 +0000 Subject: [PATCH 09/22] Remove reintroduced TEA/excalidraw artifacts --- src/bmm/agents/tea.agent.yaml | 62 ------- src/core/resources/excalidraw/README.md | 160 ------------------ .../resources/excalidraw/library-loader.md | 50 ------ 3 files changed, 272 deletions(-) delete mode 100644 src/bmm/agents/tea.agent.yaml delete mode 100644 src/core/resources/excalidraw/README.md delete mode 100644 src/core/resources/excalidraw/library-loader.md diff --git a/src/bmm/agents/tea.agent.yaml b/src/bmm/agents/tea.agent.yaml deleted file mode 100644 index 576e67997..000000000 --- a/src/bmm/agents/tea.agent.yaml +++ /dev/null @@ -1,62 +0,0 @@ -# Test Architect + Quality Advisor Agent Definition - -agent: - metadata: - id: "_bmad/bmm/agents/tea.md" - name: Murat - title: Master Test Architect - icon: 🧪 - module: bmm - hasSidecar: false - - persona: - role: Master Test Architect - identity: Test architect specializing in API testing, backend services, UI automation, CI/CD pipelines, and scalable quality gates. Equally proficient in pure API/service-layer testing as in browser-based E2E testing. - communication_style: "Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments." - principles: | - - Risk-based testing - depth scales with impact - - Quality gates backed by data - - Tests mirror usage patterns (API, UI, or both) - - Flakiness is critical technical debt - - Tests first AI implements suite validates - - Calculate risk vs value for every testing decision - - Prefer lower test levels (unit > integration > E2E) when possible - - API tests are first-class citizens, not just UI support - - critical_actions: - - "Consult {project-root}/_bmad/bmm/testarch/tea-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task" - - "Load the referenced fragment(s) from {project-root}/_bmad/bmm/testarch/knowledge/ before giving recommendations" - - "Cross-check recommendations with the current official Playwright, Cypress, Pact, and CI platform documentation" - - menu: - - trigger: TF or fuzzy match on test-framework - workflow: "{project-root}/_bmad/bmm/workflows/testarch/framework/workflow.md" - description: "[TF] Test Framework: Initialize production-ready test framework architecture" - - - trigger: AT or fuzzy match on atdd - workflow: "{project-root}/_bmad/bmm/workflows/testarch/atdd/workflow.md" - description: "[AT] Automated Test: Generate API and/or E2E tests first, before starting implementation on a story" - - - trigger: TA or fuzzy match on test-automate - workflow: "{project-root}/_bmad/bmm/workflows/testarch/automate/workflow.md" - description: "[TA] Test Automation: Generate comprehensive test automation framework for your whole project" - - - trigger: TD or fuzzy match on test-design - workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-design/workflow.md" - description: "[TD] Test Design: Create comprehensive test scenarios ahead of development." - - - trigger: TR or fuzzy match on test-trace - workflow: "{project-root}/_bmad/bmm/workflows/testarch/trace/workflow.md" - description: "[TR] Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2)" - - - trigger: NR or fuzzy match on nfr-assess - workflow: "{project-root}/_bmad/bmm/workflows/testarch/nfr-assess/workflow.md" - description: "[NR] Non-Functional Requirements: Validate against the project implementation" - - - trigger: CI or fuzzy match on continuous-integration - workflow: "{project-root}/_bmad/bmm/workflows/testarch/ci/workflow.md" - description: "[CI] Continuous Integration: Recommend and Scaffold CI/CD quality pipeline" - - - trigger: RV or fuzzy match on test-review - workflow: "{project-root}/_bmad/bmm/workflows/testarch/test-review/workflow.md" - description: "[RV] Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices" diff --git a/src/core/resources/excalidraw/README.md b/src/core/resources/excalidraw/README.md deleted file mode 100644 index a99f7a505..000000000 --- a/src/core/resources/excalidraw/README.md +++ /dev/null @@ -1,160 +0,0 @@ -# Core Excalidraw Resources - -Universal knowledge for creating Excalidraw diagrams. All agents that create Excalidraw files should reference these resources. - -## Purpose - -Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (domain-specific application). - -**Core = "How to create Excalidraw elements"** - -- How to group shapes with text labels -- How to calculate text width -- How to create arrows with proper bindings -- How to validate JSON syntax -- Base structure and primitives - -**Agents = "What diagrams to create"** - -- Frame Expert (BMM): Technical flowcharts, architecture diagrams, wireframes -- Presentation Master (CIS): Pitch decks, creative visuals, Rube Goldberg machines -- Tech Writer (BMM): Documentation diagrams, concept explanations - -## Files in This Directory - -### excalidraw-helpers.md - -**Universal element creation patterns** - -- Text width calculation -- Element grouping rules (shapes + labels) -- Grid alignment -- Arrow creation (straight, elbow) -- Theme application -- Validation checklist -- Optimization rules - -**Agents reference this to:** - -- Create properly grouped shapes -- Calculate text dimensions -- Connect elements with arrows -- Ensure valid structure - -### validate-json-instructions.md - -**Universal JSON validation process** - -- How to validate Excalidraw JSON -- Common errors and fixes -- Workflow integration -- Error recovery - -**Agents reference this to:** - -- Validate files after creation -- Fix syntax errors -- Ensure files can be opened in Excalidraw - -### library-loader.md (Future) - -**How to load external .excalidrawlib files** - -- Programmatic library loading -- Community library integration -- Custom library management - -**Status:** To be developed when implementing external library support. - -## How Agents Use These Resources - -### Example: Frame Expert (Technical Diagrams) - -```yaml -# workflows/excalidraw-diagrams/create-flowchart/workflow.md -helpers: '{project-root}/_bmad/core/resources/excalidraw/excalidraw-helpers.md' -json_validation: '{project-root}/_bmad/core/resources/excalidraw/validate-json-instructions.md' -``` - -**Domain-specific additions:** - -```yaml -# workflows/excalidraw-diagrams/_shared/flowchart-templates.yaml -flowchart: - start_node: - type: ellipse - width: 120 - height: 60 - process_box: - type: rectangle - width: 160 - height: 80 - decision_diamond: - type: diamond - width: 140 - height: 100 -``` - -### Example: Presentation Master (Creative Visuals) - -```yaml -# workflows/create-visual-metaphor/workflow.md -helpers: '{project-root}/_bmad/core/resources/excalidraw/excalidraw-helpers.md' -json_validation: '{project-root}/_bmad/core/resources/excalidraw/validate-json-instructions.md' -``` - -**Domain-specific additions:** - -```yaml -# workflows/_shared/creative-templates.yaml -rube_goldberg: - whimsical_connector: - type: arrow - strokeStyle: dashed - roughness: 2 - playful_box: - type: rectangle - roundness: 12 -``` - -## What Doesn't Belong in Core - -**Domain-Specific Elements:** - -- Flowchart-specific templates (belongs in Frame Expert) -- Pitch deck layouts (belongs in Presentation Master) -- Documentation-specific styles (belongs in Tech Writer) - -**Agent Workflows:** - -- How to create a flowchart (Frame Expert workflow) -- How to create a pitch deck (Presentation Master workflow) -- Step-by-step diagram creation (agent-specific) - -**Theming:** - -- Currently in agent workflows -- **Future:** Will be refactored to core as user-configurable themes - -## Architecture Principle - -**Single Source of Truth:** - -- Core holds universal knowledge -- Agents reference core, don't duplicate -- Updates to core benefit all agents -- Agents specialize with domain knowledge - -**DRY (Don't Repeat Yourself):** - -- Element creation logic: ONCE in core -- Text width calculation: ONCE in core -- Validation process: ONCE in core -- Arrow binding patterns: ONCE in core - -## Future Enhancements - -1. **External Library Loader** - Load .excalidrawlib files from libraries.excalidraw.com -2. **Theme Management** - User-configurable color themes saved in core -3. **Component Library** - Shared reusable components across agents -4. **Layout Algorithms** - Auto-layout helpers for positioning elements diff --git a/src/core/resources/excalidraw/library-loader.md b/src/core/resources/excalidraw/library-loader.md deleted file mode 100644 index f2fd038de..000000000 --- a/src/core/resources/excalidraw/library-loader.md +++ /dev/null @@ -1,50 +0,0 @@ -# External Library Loader - -**Status:** Placeholder for future implementation - -## Purpose - -Load external .excalidrawlib files from or custom sources. - -## Planned Capabilities - -- Load libraries by URL -- Load libraries from local files -- Merge multiple libraries -- Filter library components -- Cache loaded libraries - -## API Reference - -Will document how to use: - -- `importLibrary(url)` - Load library from URL -- `loadSceneOrLibraryFromBlob()` - Load from file -- `mergeLibraryItems()` - Combine libraries - -## Usage Example - -```yaml -# Future workflow.md structure -libraries: - - url: 'https://libraries.excalidraw.com/libraries/...' - filter: ['aws', 'cloud'] - - path: '{project-root}/_data/custom-library.excalidrawlib' -``` - -## Implementation Notes - -This will be developed when agents need to leverage the extensive library ecosystem available at . - -Hundreds of pre-built component libraries exist for: - -- AWS/Cloud icons -- UI/UX components -- Business diagrams -- Mind map shapes -- Floor plans -- And much more... - -## User Configuration - -Future: Users will be able to configure favorite libraries in their BMAD config for automatic loading. From 1a30dd7ddb7c0abab654d99b95c73d3baa3b7fe9 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Fri, 6 Feb 2026 14:42:27 +0000 Subject: [PATCH 10/22] Update validate-workflow references --- src/bmm/workflows/4-implementation/create-story/workflow.md | 2 +- .../excalidraw-diagrams/create-diagram/instructions.md | 2 +- .../excalidraw-diagrams/create-flowchart/instructions.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.md b/src/bmm/workflows/4-implementation/create-story/workflow.md index a7aa49f8c..702a60bfc 100644 --- a/src/bmm/workflows/4-implementation/create-story/workflow.md +++ b/src/bmm/workflows/4-implementation/create-story/workflow.md @@ -325,7 +325,7 @@ web_bundle: false - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md Save story document unconditionally diff --git a/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md index 7d64ccb1c..1da0488f5 100644 --- a/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md +++ b/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md @@ -132,7 +132,7 @@ - Validate against {{validation}} using {_bmad}/core/tasks/validate-workflow.xml + Validate against {{validation}} using {_bmad}/core/tasks/validate-workflow.md diff --git a/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md index 925f2706c..0a7b4ea1f 100644 --- a/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md +++ b/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md @@ -232,7 +232,7 @@ - Validate against checklist at {{validation}} using {_bmad}/core/tasks/validate-workflow.xml + Validate against checklist at {{validation}} using {_bmad}/core/tasks/validate-workflow.md From 68c78ef87d9bbb46df40b1f65b3de16592136025 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Fri, 6 Feb 2026 15:53:24 +0000 Subject: [PATCH 11/22] Migrate QA automate workflow to workflow.md --- src/bmm/workflows/qa/automate/workflow.md | 32 ++++++++++++++ src/bmm/workflows/qa/automate/workflow.yaml | 47 --------------------- 2 files changed, 32 insertions(+), 47 deletions(-) create mode 100644 src/bmm/workflows/qa/automate/workflow.md delete mode 100644 src/bmm/workflows/qa/automate/workflow.yaml diff --git a/src/bmm/workflows/qa/automate/workflow.md b/src/bmm/workflows/qa/automate/workflow.md new file mode 100644 index 000000000..c62057523 --- /dev/null +++ b/src/bmm/workflows/qa/automate/workflow.md @@ -0,0 +1,32 @@ +--- +name: qa-automate +description: "Generate tests quickly for existing features using standard test patterns" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `output_folder` + - `implementation_artifacts` + - `installed_path` + - `config_source` + - `test_dir` + - `source_dir` + +# QA Automate Workflow + +Communicate all responses in {communication_language} + + + + + Read and follow instructions at: {installed_path}/instructions.md + Validate against checklist at: {installed_path}/checklist.md + + + diff --git a/src/bmm/workflows/qa/automate/workflow.yaml b/src/bmm/workflows/qa/automate/workflow.yaml deleted file mode 100644 index 847365d7b..000000000 --- a/src/bmm/workflows/qa/automate/workflow.yaml +++ /dev/null @@ -1,47 +0,0 @@ -# Quinn QA workflow: Automate -name: qa-automate -description: "Generate tests quickly for existing features using standard test patterns" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -implementation_artifacts: "{config_source}:implementation_artifacts" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/qa/automate" -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" -template: false - -# Variables and inputs -variables: - # Directory paths - test_dir: "{project-root}/tests" # Root test directory - source_dir: "{project-root}" # Source code directory - -# Output configuration -default_output_file: "{implementation_artifacts}/tests/test-summary.md" - -# Required tools -required_tools: - - read_file # Read source code and existing tests - - write_file # Create test files - - create_directory # Create test directories - - list_files # Discover features - - search_repo # Find patterns - - glob # Find files - -tags: - - qa - - automation - - testing - -execution_hints: - interactive: false - autonomous: true - iterative: false From 5744beaba3ec805092f3f0996c8b45d322afacb4 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sat, 7 Feb 2026 13:34:26 +0000 Subject: [PATCH 12/22] Migrate remaining workflows to workflow.md and fix CLI/test regressions --- docs/how-to/customize-bmad.md | 2 +- src/bmm/agents/analyst.agent.yaml | 2 +- src/bmm/agents/dev.agent.yaml | 4 +- src/bmm/agents/pm.agent.yaml | 2 +- src/bmm/agents/quick-flow-solo-dev.agent.yaml | 2 +- src/bmm/agents/sm.agent.yaml | 8 +- .../agents/tech-writer/tech-writer.agent.yaml | 2 +- src/bmm/module-help.csv | 39 +- .../steps/step-02-vision.md | 2 +- .../steps/step-03-users.md | 2 +- .../steps/step-04-metrics.md | 2 +- .../steps/step-05-scope.md | 2 +- .../create-prd/steps-c/step-02-discovery.md | 2 +- .../create-prd/steps-c/step-03-success.md | 2 +- .../create-prd/steps-c/step-04-journeys.md | 2 +- .../create-prd/steps-c/step-05-domain.md | 2 +- .../create-prd/steps-c/step-06-innovation.md | 2 +- .../steps-c/step-07-project-type.md | 2 +- .../create-prd/steps-c/step-08-scoping.md | 2 +- .../create-prd/steps-c/step-09-functional.md | 2 +- .../steps-c/step-10-nonfunctional.md | 2 +- .../create-prd/steps-c/step-11-polish.md | 2 +- .../create-prd/steps-e/step-e-01-discovery.md | 2 +- .../create-prd/steps-e/step-e-02-review.md | 2 +- .../create-prd/steps-v/step-v-01-discovery.md | 4 +- .../steps-v/step-v-10-smart-validation.md | 2 +- .../step-v-11-holistic-quality-validation.md | 2 +- .../steps/step-02-discovery.md | 2 +- .../steps/step-03-core-experience.md | 4 +- .../steps/step-04-emotional-response.md | 4 +- .../steps/step-05-inspiration.md | 4 +- .../steps/step-06-design-system.md | 4 +- .../steps/step-07-defining-experience.md | 4 +- .../steps/step-08-visual-foundation.md | 4 +- .../steps/step-09-design-directions.md | 4 +- .../steps/step-10-user-journeys.md | 4 +- .../steps/step-11-component-strategy.md | 4 +- .../steps/step-12-ux-patterns.md | 4 +- .../steps/step-13-responsive-accessibility.md | 4 +- .../steps/step-02-context.md | 4 +- .../steps/step-03-starter.md | 4 +- .../steps/step-04-decisions.md | 4 +- .../steps/step-05-patterns.md | 4 +- .../steps/step-06-structure.md | 4 +- .../steps/step-07-validation.md | 4 +- .../steps/step-01-validate-prerequisites.md | 2 +- .../steps/step-02-design-epics.md | 2 +- .../steps/step-03-create-stories.md | 2 +- .../steps/step-04-final-validation.md | 2 +- .../code-review/instructions.xml | 4 +- .../4-implementation/code-review/workflow.md | 33 + .../code-review/workflow.yaml | 48 - .../correct-course/checklist.md | 2 +- .../correct-course/instructions.md | 4 +- .../correct-course/workflow.md | 33 + .../correct-course/workflow.yaml | 56 - .../create-story/checklist.md | 14 +- .../create-story/instructions.xml | 6 +- .../4-implementation/create-story/workflow.md | 56 - .../create-story/workflow.yaml | 57 - .../dev-story/instructions.xml | 4 +- .../4-implementation/dev-story/workflow.md | 33 + .../4-implementation/dev-story/workflow.yaml | 23 - .../retrospective/instructions.md | 4 +- .../retrospective/workflow.md | 29 + .../retrospective/workflow.yaml | 55 - .../sprint-planning/instructions.md | 4 +- .../sprint-planning/workflow.md | 31 + .../sprint-planning/workflow.yaml | 51 - .../sprint-status/instructions.md | 4 +- .../sprint-status/workflow.md | 26 + .../sprint-status/workflow.yaml | 30 - .../bmad-quick-flow/quick-dev/workflow.md | 2 +- .../bmad-quick-flow/quick-spec/workflow.md | 2 +- .../document-project/instructions.md | 4 +- .../workflows/document-project/workflow.md | 30 + .../workflows/document-project/workflow.yaml | 22 - .../document-project/workflows/deep-dive.yaml | 4 +- .../document-project/workflows/full-scan.yaml | 4 +- .../create-dataflow/instructions.md | 128 -- .../create-diagram/instructions.md | 139 --- .../create-flowchart/instructions.md | 239 ---- .../create-wireframe/instructions.md | 131 --- src/bmm/workflows/qa/automate/workflow.md | 5 +- src/bmm/workflows/testarch/trace/checklist.md | 642 ---------- .../workflows/testarch/trace/instructions.md | 1030 ----------------- .../advanced-elicitation/workflow.md | 124 ++ .../advanced-elicitation/workflow.xml | 117 -- .../steps/step-03-technique-execution.md | 2 +- src/core/workflows/brainstorming/workflow.md | 2 +- .../agent-components/handler-multi.txt | 2 +- .../handler-validate-workflow.txt | 8 +- .../agent-components/handler-workflow.txt | 12 +- test/test-installation-components.js | 133 ++- .../installers/lib/core/manifest-generator.js | 2 +- tools/cli/installers/lib/ide/_base-ide.js | 13 +- .../combined/claude-workflow-yaml.md | 1 - .../combined/default-workflow-yaml.md | 15 - .../templates/workflow-command-template.md | 14 - tools/cli/installers/lib/modules/manager.js | 3 +- 100 files changed, 551 insertions(+), 3065 deletions(-) create mode 100644 src/bmm/workflows/4-implementation/code-review/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/code-review/workflow.yaml create mode 100644 src/bmm/workflows/4-implementation/correct-course/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/correct-course/workflow.yaml delete mode 100644 src/bmm/workflows/4-implementation/create-story/workflow.yaml create mode 100644 src/bmm/workflows/4-implementation/dev-story/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/dev-story/workflow.yaml create mode 100644 src/bmm/workflows/4-implementation/retrospective/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/retrospective/workflow.yaml create mode 100644 src/bmm/workflows/4-implementation/sprint-planning/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml create mode 100644 src/bmm/workflows/4-implementation/sprint-status/workflow.md delete mode 100644 src/bmm/workflows/4-implementation/sprint-status/workflow.yaml create mode 100644 src/bmm/workflows/document-project/workflow.md delete mode 100644 src/bmm/workflows/document-project/workflow.yaml delete mode 100644 src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md delete mode 100644 src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md delete mode 100644 src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md delete mode 100644 src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md delete mode 100644 src/bmm/workflows/testarch/trace/checklist.md delete mode 100644 src/bmm/workflows/testarch/trace/instructions.md create mode 100644 src/core/workflows/advanced-elicitation/workflow.md delete mode 100644 src/core/workflows/advanced-elicitation/workflow.xml delete mode 120000 tools/cli/installers/lib/ide/templates/combined/claude-workflow-yaml.md delete mode 100644 tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md delete mode 100644 tools/cli/installers/lib/ide/templates/workflow-command-template.md diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index f23a101c6..8c42b2f62 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -100,7 +100,7 @@ Any custom items you add here will be included in the agents display menu. ```yaml menu: - trigger: my-workflow - workflow: '{project-root}/my-custom/workflows/my-workflow.yaml' + workflow: '{project-root}/my-custom/workflows/my-workflow.md' description: My custom workflow - trigger: deploy action: '#deploy-prompt' diff --git a/src/bmm/agents/analyst.agent.yaml b/src/bmm/agents/analyst.agent.yaml index c340f69c1..0e6aab780 100644 --- a/src/bmm/agents/analyst.agent.yaml +++ b/src/bmm/agents/analyst.agent.yaml @@ -38,5 +38,5 @@ agent: description: "[CB] Create Brief: A guided experience to nail down your product idea into an executive brief" - trigger: DP or fuzzy match on document-project - workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" description: "[DP] Document Project: Analyze an existing project to produce useful documentation for both human and LLM" diff --git a/src/bmm/agents/dev.agent.yaml b/src/bmm/agents/dev.agent.yaml index d88166eda..807fea8ff 100644 --- a/src/bmm/agents/dev.agent.yaml +++ b/src/bmm/agents/dev.agent.yaml @@ -29,9 +29,9 @@ agent: menu: - trigger: DS or fuzzy match on dev-story - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.md" description: "[DS] Dev Story: Write the next or specified stories tests and code." - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md" description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available" diff --git a/src/bmm/agents/pm.agent.yaml b/src/bmm/agents/pm.agent.yaml index 9ce0bf32f..c990759c3 100644 --- a/src/bmm/agents/pm.agent.yaml +++ b/src/bmm/agents/pm.agent.yaml @@ -39,5 +39,5 @@ agent: description: "[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned" - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md" description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation" diff --git a/src/bmm/agents/quick-flow-solo-dev.agent.yaml b/src/bmm/agents/quick-flow-solo-dev.agent.yaml index 6d207a399..a20c8a206 100644 --- a/src/bmm/agents/quick-flow-solo-dev.agent.yaml +++ b/src/bmm/agents/quick-flow-solo-dev.agent.yaml @@ -27,5 +27,5 @@ agent: description: "[QD] Quick-flow Develop: Implement a story tech spec end-to-end (Core of Quick Flow)" - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md" description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available" diff --git a/src/bmm/agents/sm.agent.yaml b/src/bmm/agents/sm.agent.yaml index 9e51f4259..e244c280f 100644 --- a/src/bmm/agents/sm.agent.yaml +++ b/src/bmm/agents/sm.agent.yaml @@ -19,18 +19,18 @@ agent: menu: - trigger: SP or fuzzy match on sprint-planning - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md" description: "[SP] Sprint Planning: Generate or update the record that will sequence the tasks to complete the full project that the dev agent will follow" - trigger: CS or fuzzy match on create-story - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.md" description: "[CS] Context Story: Prepare a story with all required context for implementation for the developer agent" - trigger: ER or fuzzy match on epic-retrospective - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.md" data: "{project-root}/_bmad/_config/agent-manifest.csv" description: "[ER] Epic Retrospective: Party Mode review of all work completed across an epic." - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md" description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation" diff --git a/src/bmm/agents/tech-writer/tech-writer.agent.yaml b/src/bmm/agents/tech-writer/tech-writer.agent.yaml index a742a6c9f..4a99f52d7 100644 --- a/src/bmm/agents/tech-writer/tech-writer.agent.yaml +++ b/src/bmm/agents/tech-writer/tech-writer.agent.yaml @@ -21,7 +21,7 @@ agent: menu: - trigger: DP or fuzzy match on document-project - workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" + workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" description: "[DP] Document Project: Generate comprehensive project documentation (brownfield analysis, architecture scanning)" - trigger: WD or fuzzy match on write-document diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv index 9ba42ca0f..0c8096831 100644 --- a/src/bmm/module-help.csv +++ b/src/bmm/module-help.csv @@ -1,32 +1,31 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs, -bmm,anytime,Document Project,DP,10,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, -bmm,anytime,Quick Spec,TS,20,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps utilities without extensive planning",planning_artifacts,"tech spec", -bmm,anytime,Quick Dev,QD,30,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, -bmm,anytime,Correct Course,CC,40,_bmad/bmm/workflows/4-implementation/correct-course/workflow.md,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", +bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, +bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context", +bmm,anytime,Quick Spec,QS,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec", +bmm,anytime,Quick Dev,QD,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, +bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.md,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", +bmm,anytime,Write Document,WD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document", +bmm,anytime,Update Standards,US,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards", +bmm,anytime,Mermaid Generate,MG,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.",planning_artifacts,"mermaid diagram", +bmm,anytime,Validate Document,VD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.",planning_artifacts,"validation report", +bmm,anytime,Explain Concept,EC,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create clear technical explanations with examples and diagrams for complex concepts. Breaks down into digestible sections using task-oriented approach.",project_knowledge,"explanation", bmm,1-analysis,Brainstorm Project,BP,10,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session", -bmm,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=market,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents" -bmm,1-analysis,Domain Research,DR,21,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=domain,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project-knowledge","research documents" -bmm,1-analysis,Technical Research,TR,22,_bmad/bmm/workflows/1-analysis/research/workflow.md,bmad-bmm-research,false,analyst,Create Mode research_type=technical,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project-knowledge","research documents" -bmm,1-analysis,Create Brief,CB,30,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-create-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", -bmm,1-analysis,Validate Brief,VB,40,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-validate-brief,false,analyst,Validate Mode,"Validates product brief completeness",planning_artifacts,"brief validation report", -bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow.md,bmad-bmm-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, -bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow.md,bmad-bmm-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", +bmm,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow-market-research.md,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents", +bmm,1-analysis,Domain Research,DR,21,_bmad/bmm/workflows/1-analysis/research/workflow-domain-research.md,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents", +bmm,1-analysis,Technical Research,TR,22,_bmad/bmm/workflows/1-analysis/research/workflow-technical-research.md,bmad-bmm-technical-research,false,analyst,Create Mode,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project_knowledge","research documents", +bmm,1-analysis,Create Brief,CB,30,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", +bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md,bmad-bmm-create-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, +bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md,bmad-bmm-validate-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", +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,_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md,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,2-planning,Validate UX,VU,40,_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md,bmad-bmm-create-ux-design,false,ux-designer,Validate Mode,"Validates UX design deliverables",planning_artifacts,"ux validation report", -,anytime,Create Dataflow,CDF,50,_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.md,bmad-bmm-create-excalidraw-dataflow,false,ux-designer,Create Mode,"Create data flow diagrams (DFD) in Excalidraw format - can be called standalone or during any workflow to add visual documentation",planning_artifacts,"dataflow diagram", -,anytime,Create Diagram,CED,51,_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.md,bmad-bmm-create-excalidraw-diagram,false,ux-designer,Create Mode,"Create system architecture diagrams ERDs UML diagrams or general technical diagrams in Excalidraw format - use anytime or call from architecture workflow to add visual documentation",planning_artifacts,"diagram", -,anytime,Create Flowchart,CFC,52,_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.md,bmad-bmm-create-excalidraw-flowchart,false,ux-designer,Create Mode,"Create a flowchart visualization in Excalidraw format for processes pipelines or logic flows - use anytime or during architecture to add process documentation",planning_artifacts,"flowchart", -,anytime,Create Wireframe,CEW,53,_bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.md,bmad-bmm-create-excalidraw-wireframe,false,ux-designer,Create Mode,"Create website or app wireframes in Excalidraw format - use anytime standalone or call from UX workflow to add UI mockups",planning_artifacts,"wireframe", bmm,3-solutioning,Create Architecture,CA,10,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture, -bmm,3-solutioning,Validate Architecture,VA,20,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,false,architect,Validate Mode,"Validates architecture completeness",planning_artifacts,"architecture validation report", 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,Validate Epics and Stories,VE,40,_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md,bmad-bmm-create-epics-and-stories,false,pm,Validate Mode,"Validates epics and stories completeness",planning_artifacts,"epics validation report", -bmm,3-solutioning,Test Design,TD,50,_bmad/bmm/workflows/testarch/test-design/workflow.md,bmad-bmm-testarch-test-design,false,tea,Create Mode,"Create comprehensive test scenarios ahead of development, recommended if string test compliance or assurance is needed. Very critical for distributed applications with separate front ends and backends outside of a monorepo.",planning_artifacts,"test design", bmm,3-solutioning,Check Implementation Readiness,IR,70,_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md,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",,, -bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report", +bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.md,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.md,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,, bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.md,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,, +bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa/automate/workflow.md,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite", bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.md,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective, diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md index f00e18faa..5ae6e3347 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md +++ b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md @@ -7,7 +7,7 @@ nextStepFile: './step-03-users.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md index cba266411..b2881ed78 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md +++ b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md @@ -7,7 +7,7 @@ nextStepFile: './step-04-metrics.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md index e6b297c3d..0bfc5519b 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md +++ b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md @@ -7,7 +7,7 @@ nextStepFile: './step-05-scope.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md index 0914b835d..d3f6b7ccc 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md +++ b/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md @@ -7,7 +7,7 @@ nextStepFile: './step-06-complete.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md index 4829a4d36..1201b286f 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md @@ -11,7 +11,7 @@ projectTypesCSV: '../data/project-types.csv' domainComplexityCSV: '../data/domain-complexity.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md index 9a3c5e341..49cb1339e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md @@ -7,7 +7,7 @@ nextStepFile: './step-04-journeys.md' outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md index 314dab564..5c7570890 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md @@ -7,7 +7,7 @@ nextStepFile: './step-05-domain.md' outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md index 9539527dc..60b30cb15 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md @@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md' domainComplexityCSV: '../data/domain-complexity.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md index 440ccf2d2..8d2f03dd4 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md @@ -10,7 +10,7 @@ outputFile: '{planning_artifacts}/prd.md' projectTypesCSV: '../data/project-types.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md index c078d6db1..9dd55e1c0 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md @@ -10,7 +10,7 @@ outputFile: '{planning_artifacts}/prd.md' projectTypesCSV: '../data/project-types.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md index da9230adc..36c4e5293 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md @@ -7,7 +7,7 @@ nextStepFile: './step-09-functional.md' outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md index d689ebf37..210fd60c1 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md @@ -7,7 +7,7 @@ nextStepFile: './step-10-nonfunctional.md' outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md index 40919635d..121ea53ce 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md @@ -7,7 +7,7 @@ nextStepFile: './step-11-polish.md' outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md index 70bf198c3..04ad786e8 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md @@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md' purposeFile: '../data/prd-purpose.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md index 09f84b5f5..cfe2a0335 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md @@ -4,7 +4,7 @@ description: 'Discovery & Understanding - Understand what user wants to edit and # File references (ONLY variables used in this step) altStepFile: './step-e-01b-legacy-conversion.md' -prdPurpose: '{project-root}/src/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md index 64e0acbb3..1f7f9215e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md @@ -6,7 +6,7 @@ description: 'Deep Review & Analysis - Thoroughly review existing PRD and prepar nextStepFile: './step-e-03-edit.md' prdFile: '{prd_file_path}' validationReport: '{validation_report_path}' # If provided -prdPurpose: '{project-root}/src/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md index b79e12fe0..ae3f954dd 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md @@ -4,9 +4,9 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio # File references (ONLY variables used in this step) nextStepFile: './step-v-02-format-detection.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' -prdPurpose: '../data/prd-purpose.md' +prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' --- # Step 1: Document Discovery & Confirmation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md index e937c7526..1a135dcf0 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md @@ -6,7 +6,7 @@ description: 'SMART Requirements Validation - Validate Functional Requirements m nextStepFile: './step-v-11-holistic-quality-validation.md' prdFile: '{prd_file_path}' validationReportPath: '{validation_report_path}' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' --- # Step 10: SMART Requirements Validation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md index 698b6f654..581bf15f5 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md @@ -6,7 +6,7 @@ description: 'Holistic Quality Assessment - Assess PRD as cohesive, compelling d nextStepFile: './step-v-12-completeness-validation.md' prdFile: '{prd_file_path}' validationReportPath: '{validation_report_path}' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' --- # Step 11: Holistic Quality Assessment diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md index 7ab275a88..c45b1d461 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md index c64c84230..3ab99f9b1 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -161,7 +161,7 @@ Show the generated core experience content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current core experience content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current core experience content - Process the enhanced experience insights that come back - Ask user: "Accept these improvements to the core experience definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md index 247a61e21..6b74fc0fb 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -164,7 +164,7 @@ Show the generated emotional response content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current emotional response content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current emotional response content - Process the enhanced emotional insights that come back - Ask user: "Accept these improvements to the emotional response definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md index 87fe56031..f85d5f4b1 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -179,7 +179,7 @@ Show the generated inspiration analysis content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current inspiration analysis content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current inspiration analysis content - Process the enhanced pattern insights that come back - Ask user: "Accept these improvements to the inspiration analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md index 70d566ada..0ff7156b6 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -197,7 +197,7 @@ Show the generated design system content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design system content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current design system content - Process the enhanced design system insights that come back - Ask user: "Accept these improvements to the design system decision? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md index 7e904b948..53ad68f38 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -199,7 +199,7 @@ Show the generated defining experience content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current defining experience content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current defining experience content - Process the enhanced experience insights that come back - Ask user: "Accept these improvements to the defining experience? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md index bd764a60e..2f2491592 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -169,7 +169,7 @@ Show the generated visual foundation content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current visual foundation content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current visual foundation content - Process the enhanced visual insights that come back - Ask user: "Accept these improvements to the visual foundation? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md index a50ed503e..ac8f00439 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -169,7 +169,7 @@ Show the generated design direction content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design direction content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current design direction content - Process the enhanced design insights that come back - Ask user: "Accept these improvements to the design direction? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md index 985577f00..4a52e235e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -187,7 +187,7 @@ Show the generated user journey content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current user journey content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current user journey content - Process the enhanced journey insights that come back - Ask user: "Accept these improvements to the user journeys? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md index deef19b73..258f64d56 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -193,7 +193,7 @@ Show the generated component strategy content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current component strategy content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current component strategy content - Process the enhanced component insights that come back - Ask user: "Accept these improvements to the component strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md index 4708b52aa..761244e63 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -182,7 +182,7 @@ Show the generated UX patterns content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current UX patterns content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current UX patterns content - Process the enhanced pattern insights that come back - Ask user: "Accept these improvements to the UX patterns? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md index 80b81d4c8..890a9506f 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -209,7 +209,7 @@ Show the generated responsive and accessibility content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current responsive/accessibility content +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current responsive/accessibility content - Process the enhanced insights that come back - Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md index 1e9c6b9a3..14fa1264d 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md @@ -31,7 +31,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -170,7 +170,7 @@ Show the generated content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current context analysis +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with the current context analysis - Process the enhanced architectural insights that come back - Ask user: "Accept these enhancements to the project context analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md index bccea19df..c97aa9b6f 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md @@ -31,7 +31,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -277,7 +277,7 @@ Show the generated content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current starter analysis +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current starter analysis - Process enhanced insights about starter options or custom approaches - Ask user: "Accept these changes to the starter template evaluation? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md index c9f5cdedd..43b4efd9c 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md @@ -32,7 +32,7 @@ This step will generate content and present choices for each decision category: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -264,7 +264,7 @@ Show the generated decisions content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with specific decision categories +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with specific decision categories - Process enhanced insights about particular decisions - Ask user: "Accept these enhancements to the architectural decisions? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md index cbfd99d1d..a150f8909 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md @@ -32,7 +32,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -305,7 +305,7 @@ Show the generated patterns content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current patterns +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current patterns - Process enhanced consistency rules that come back - Ask user: "Accept these additional pattern refinements? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md index 3df89e6ce..39be9bbc7 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md @@ -32,7 +32,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -325,7 +325,7 @@ Show the generated project structure content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current project structure +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with current project structure - Process enhanced organizational insights that come back - Ask user: "Accept these changes to the project structure? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md index b2dc2c462..de43a25e6 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md @@ -32,7 +32,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -305,7 +305,7 @@ Show the validation results and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with validation issues +- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md with validation issues - Process enhanced solutions for complex concerns - Ask user: "Accept these architectural improvements? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md index c8d6b1330..5d2b0add9 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md @@ -13,7 +13,7 @@ outputFile: '{planning_artifacts}/epics.md' epicsTemplate: '{workflow_path}/templates/epics-template.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' # Template References diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md index 1b497c2ad..46ca5e47a 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md @@ -12,7 +12,7 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' # Template References diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md index 2e13f9b2c..07e666e03 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md @@ -12,7 +12,7 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' # Template References 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 05e8d5d4e..1cf5d5050 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 @@ -11,7 +11,7 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' # Template References diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml index e5649559d..ad17fa6ed 100644 --- a/src/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/bmm/workflows/4-implementation/code-review/instructions.xml @@ -1,6 +1,6 @@ - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml + The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md + You MUST have already loaded and processed: {installed_path}/workflow.md Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.md b/src/bmm/workflows/4-implementation/code-review/workflow.md new file mode 100644 index 000000000..d252b0957 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/workflow.md @@ -0,0 +1,33 @@ +--- +name: code-review +description: "Perform an adversarial senior developer code review with concrete findings across quality, tests, architecture, security, and performance" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `user_skill_level` + - `planning_artifacts` + - `implementation_artifacts` + - `story_dir` = `{implementation_artifacts}` + - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` + - `project_context` = `**/project-context.md` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.xml + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/bmm/workflows/4-implementation/code-review/workflow.yaml deleted file mode 100644 index 5b5f6b2fc..000000000 --- a/src/bmm/workflows/4-implementation/code-review/workflow.yaml +++ /dev/null @@ -1,48 +0,0 @@ -# Review Story Workflow -name: code-review -description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -output_folder: "{implementation_artifacts}" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" -template: false - -variables: - # Project context - project_context: "**/project-context.md" - story_dir: "{implementation_artifacts}" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review -input_file_patterns: - architecture: - description: "System architecture for review context" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - ux_design: - description: "UX design specification (if UI review)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "FULL_LOAD" - epics: - description: "Epic containing story being reviewed" - whole: "{planning_artifacts}/*epic*.md" - sharded_index: "{planning_artifacts}/*epic*/index.md" - sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" - load_strategy: "SELECTIVE_LOAD" diff --git a/src/bmm/workflows/4-implementation/correct-course/checklist.md b/src/bmm/workflows/4-implementation/correct-course/checklist.md index f13ab9be0..1e630ccbb 100644 --- a/src/bmm/workflows/4-implementation/correct-course/checklist.md +++ b/src/bmm/workflows/4-implementation/correct-course/checklist.md @@ -1,6 +1,6 @@ # Change Navigation Checklist -This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml +This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md Work through each section systematically with the user, recording findings and impacts diff --git a/src/bmm/workflows/4-implementation/correct-course/instructions.md b/src/bmm/workflows/4-implementation/correct-course/instructions.md index 430239a68..e37116f06 100644 --- a/src/bmm/workflows/4-implementation/correct-course/instructions.md +++ b/src/bmm/workflows/4-implementation/correct-course/instructions.md @@ -1,7 +1,7 @@ # Correct Course - Sprint Change Management 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/bmm/workflows/4-implementation/correct-course/workflow.yaml +The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md +You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} diff --git a/src/bmm/workflows/4-implementation/correct-course/workflow.md b/src/bmm/workflows/4-implementation/correct-course/workflow.md new file mode 100644 index 000000000..f6cfff26a --- /dev/null +++ b/src/bmm/workflows/4-implementation/correct-course/workflow.md @@ -0,0 +1,33 @@ +--- +name: correct-course +description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `user_skill_level` + - `planning_artifacts` + - `implementation_artifacts` + - `project_knowledge` + - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course` + - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.md + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + diff --git a/src/bmm/workflows/4-implementation/correct-course/workflow.yaml b/src/bmm/workflows/4-implementation/correct-course/workflow.yaml deleted file mode 100644 index 318b5a7dc..000000000 --- a/src/bmm/workflows/4-implementation/correct-course/workflow.yaml +++ /dev/null @@ -1,56 +0,0 @@ -# Correct Course - Sprint Change Management Workflow -name: "correct-course" -description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation" -author: "BMad Method" - -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" -project_knowledge: "{config_source}:project_knowledge" -output_folder: "{implementation_artifacts}" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: Load project context for impact analysis -input_file_patterns: - prd: - description: "Product requirements for impact analysis" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "FULL_LOAD" - epics: - description: "All epics to analyze change impact" - whole: "{planning_artifacts}/*epic*.md" - sharded: "{planning_artifacts}/*epic*/*.md" - load_strategy: "FULL_LOAD" - architecture: - description: "System architecture and decisions" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - ux_design: - description: "UX design specification (if UI impacts)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "FULL_LOAD" - tech_spec: - description: "Technical specification" - whole: "{planning_artifacts}/*tech-spec*.md" - load_strategy: "FULL_LOAD" - document_project: - description: "Brownfield project documentation (optional)" - sharded: "{project_knowledge}/index.md" - load_strategy: "INDEX_GUIDED" - -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course" -template: false -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" -checklist: "{installed_path}/checklist.md" -default_output_file: "{planning_artifacts}/sprint-change-proposal-{date}.md" diff --git a/src/bmm/workflows/4-implementation/create-story/checklist.md b/src/bmm/workflows/4-implementation/create-story/checklist.md index 55e6c397e..dea2f95b7 100644 --- a/src/bmm/workflows/4-implementation/create-story/checklist.md +++ b/src/bmm/workflows/4-implementation/create-story/checklist.md @@ -33,25 +33,25 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de ### **When Running from Create-Story Workflow:** -- The `{project-root}/_bmad/core/tasks/validate-workflow.xml` framework will automatically: +- The `{project-root}/_bmad/core/tasks/validate-workflow.md` framework will automatically: - Load this checklist file - Load the newly created story file (`{story_file_path}`) - - Load workflow variables from `{installed_path}/workflow.yaml` + - Load workflow variables from `{installed_path}/workflow.md` - Execute the validation process ### **When Running in Fresh Context:** - User should provide the story file path being reviewed - Load the story file directly -- Load the corresponding workflow.yaml for variable context +- Load the corresponding workflow.md for variable context - Proceed with systematic analysis ### **Required Inputs:** - **Story file**: The story file to review and improve -- **Workflow variables**: From workflow.yaml (story_dir, output_folder, epics_file, etc.) +- **Workflow variables**: From workflow.md (story_dir, output_folder, epics_file, etc.) - **Source documents**: Epics, architecture, etc. (discovered or provided) -- **Validation framework**: `validate-workflow.xml` (handles checklist execution) +- **Validation framework**: `validate-workflow.md` (handles checklist execution) --- @@ -61,9 +61,9 @@ You will systematically re-do the entire story creation process, but with a crit ### **Step 1: Load and Understand the Target** -1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion +1. **Load the workflow configuration**: `{installed_path}/workflow.md` for variable inclusion 2. **Load the story file**: `{story_file_path}` (provided by user or discovered) -3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.xml` +3. **Load validation framework**: `{project-root}/_bmad/core/tasks/validate-workflow.md` 4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file 5. **Resolve all workflow variables**: story_dir, output_folder, epics_file, architecture_file, etc. 6. **Understand current status**: What story implementation guidance is currently provided? diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index 81eb82269..2a8d6ce5f 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -1,6 +1,6 @@ - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml + The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md + You MUST have already loaded and processed: {installed_path}/workflow.md Communicate all responses in {communication_language} and generate all documents in {document_output_language} 🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or @@ -310,7 +310,7 @@ - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md Save story document unconditionally diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.md b/src/bmm/workflows/4-implementation/create-story/workflow.md index 702a60bfc..5a393e489 100644 --- a/src/bmm/workflows/4-implementation/create-story/workflow.md +++ b/src/bmm/workflows/4-implementation/create-story/workflow.md @@ -131,62 +131,6 @@ web_bundle: false GOTO step 2a - Load the FULL file: {{sprint_status}} - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - - Find the FIRST story (by reading in order from top to bottom) where: - - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - - Status value equals "backlog" - - - - 📋 No backlog stories found in sprint-status.yaml - - All stories are either already created, in progress, or done. - - **Options:** - 1. Run sprint-planning to refresh story tracking - 2. Load PM agent and run correct-course to add more stories - 3. Check if current sprint is complete and run retrospective - - HALT - - - Extract from found story key (e.g., "1-2-user-authentication"): - - epic_num: first number before dash (e.g., "1") - - story_num: second number after first dash (e.g., "2") - - story_title: remainder after second dash (e.g., "user-authentication") - - Set {{story_id}} = "{{epic_num}}.{{story_num}}" - Store story_key for later use (e.g., "1-2-user-authentication") - - - Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern - - Load {{sprint_status}} and check epic-{{epic_num}} status - If epic status is "backlog" → update to "in-progress" - If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) - If epic status is "in-progress" → no change needed - - 🚫 ERROR: Cannot create story in completed epic - Epic {{epic_num}} is marked as 'done'. All stories are complete. - If you need to add more work, either: - 1. Manually change epic status back to 'in-progress' in sprint-status.yaml - 2. Create a new epic for additional work - HALT - Cannot proceed - - - 🚫 ERROR: Invalid epic status '{{epic_status}}' - Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done - Please fix sprint-status.yaml manually or run sprint-planning to regenerate - HALT - Cannot proceed - - 📊 Epic {{epic_num}} status updated to in-progress - - - GOTO step 2a diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/bmm/workflows/4-implementation/create-story/workflow.yaml deleted file mode 100644 index 1f3ac9784..000000000 --- a/src/bmm/workflows/4-implementation/create-story/workflow.yaml +++ /dev/null @@ -1,57 +0,0 @@ -name: create-story -description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -output_folder: "{implementation_artifacts}" -story_dir: "{implementation_artifacts}" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story" -template: "{installed_path}/template.md" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" - -# Variables and inputs -variables: - sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking - epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints - prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file) - architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file) - ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file) - story_title: "" # Will be elicited if not derivable - -# Project context -project_context: "**/project-context.md" - -default_output_file: "{story_dir}/{{story_key}}.md" - -# Smart input file references - Simplified for enhanced approach -# The epics+stories file should contain everything needed with source hints -input_file_patterns: - prd: - description: "PRD (fallback - epics file should have most content)" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - architecture: - description: "Architecture (fallback - epics file should have relevant sections)" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - ux: - description: "UX design (fallback - epics file should have relevant sections)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - epics: - description: "Enhanced epics+stories file with BDD and source hints" - whole: "{planning_artifacts}/*epic*.md" - sharded: "{planning_artifacts}/*epic*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load needed epic diff --git a/src/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/bmm/workflows/4-implementation/dev-story/instructions.xml index 6150944f1..fda61b589 100644 --- a/src/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -1,6 +1,6 @@ - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml + The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md + You MUST have already loaded and processed: {installed_path}/workflow.md Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.md b/src/bmm/workflows/4-implementation/dev-story/workflow.md new file mode 100644 index 000000000..06443a43f --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/workflow.md @@ -0,0 +1,33 @@ +--- +name: dev-story +description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `user_skill_level` + - `implementation_artifacts` + - `story_dir` = `{implementation_artifacts}` + - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` + - `story_file` (if provided) + - `project_context` = `**/project-context.md` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.xml + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/bmm/workflows/4-implementation/dev-story/workflow.yaml deleted file mode 100644 index daf152b71..000000000 --- a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml +++ /dev/null @@ -1,23 +0,0 @@ -name: dev-story -description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -story_dir: "{config_source}:implementation_artifacts" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" - -story_file: "" # Explicit story path; auto-discovered if empty -implementation_artifacts: "{config_source}:implementation_artifacts" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" -project_context: "**/project-context.md" diff --git a/src/bmm/workflows/4-implementation/retrospective/instructions.md b/src/bmm/workflows/4-implementation/retrospective/instructions.md index 017503129..bb3407d42 100644 --- a/src/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/bmm/workflows/4-implementation/retrospective/instructions.md @@ -1,7 +1,7 @@ # Retrospective - Epic Completion Review 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/bmm/workflows/4-implementation/retrospective/workflow.yaml +The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md +You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.md Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} ⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever. diff --git a/src/bmm/workflows/4-implementation/retrospective/workflow.md b/src/bmm/workflows/4-implementation/retrospective/workflow.md new file mode 100644 index 000000000..4c66c8c38 --- /dev/null +++ b/src/bmm/workflows/4-implementation/retrospective/workflow.md @@ -0,0 +1,29 @@ +--- +name: retrospective +description: "Run after epic completion to review overall success, extract lessons learned, and surface impact on upcoming work" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `user_skill_level` + - `planning_artifacts` + - `implementation_artifacts` + - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` + - `story_directory` = `{implementation_artifacts}` + - `retrospectives_folder` = `{implementation_artifacts}` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/retrospective` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.md + + diff --git a/src/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/bmm/workflows/4-implementation/retrospective/workflow.yaml deleted file mode 100644 index b92ecaf1b..000000000 --- a/src/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ /dev/null @@ -1,55 +0,0 @@ -# Retrospective - Epic Completion Review Workflow -name: "retrospective" -description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic" -author: "BMad" - -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:implementation_artifacts}" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" - -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective" -template: false -instructions: "{installed_path}/instructions.md" - -required_inputs: - - agent_manifest: "{project-root}/_bmad/_config/agent-manifest.csv" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives -input_file_patterns: - epics: - description: "The completed epic for retrospective" - whole: "{planning_artifacts}/*epic*.md" - sharded_index: "{planning_artifacts}/*epic*/index.md" - sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" - load_strategy: "SELECTIVE_LOAD" - previous_retrospective: - description: "Previous epic's retrospective (optional)" - pattern: "{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md" - load_strategy: "SELECTIVE_LOAD" - architecture: - description: "System architecture for context" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - prd: - description: "Product requirements for context" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "FULL_LOAD" - document_project: - description: "Brownfield project documentation (optional)" - sharded: "{planning_artifacts}/*.md" - load_strategy: "INDEX_GUIDED" - -# Required files -sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" -story_directory: "{implementation_artifacts}" -retrospectives_folder: "{implementation_artifacts}" diff --git a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/bmm/workflows/4-implementation/sprint-planning/instructions.md index c4f4bd420..88f3eafe0 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -1,7 +1,7 @@ # Sprint Planning - Sprint Status Generator -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md +You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md ## 📚 Document Discovery - Full Epic Loading diff --git a/src/bmm/workflows/4-implementation/sprint-planning/workflow.md b/src/bmm/workflows/4-implementation/sprint-planning/workflow.md new file mode 100644 index 000000000..ee0b86b3e --- /dev/null +++ b/src/bmm/workflows/4-implementation/sprint-planning/workflow.md @@ -0,0 +1,31 @@ +--- +name: sprint-planning +description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `implementation_artifacts` + - `planning_artifacts` + - `project_name` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning` + - `status_file` = `{implementation_artifacts}/sprint-status.yaml` + - `default_output_file` = `{status_file}` + + + Communicate all responses in {communication_language} + + + Read and follow instructions at: {installed_path}/instructions.md + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + diff --git a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml deleted file mode 100644 index 7b157633c..000000000 --- a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ /dev/null @@ -1,51 +0,0 @@ -name: sprint-planning -description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -date: system-generated -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" -output_folder: "{implementation_artifacts}" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning" -instructions: "{installed_path}/instructions.md" -template: "{installed_path}/sprint-status-template.yaml" -validation: "{installed_path}/checklist.md" - -# Variables and inputs -variables: - # Project context - project_context: "**/project-context.md" - # Project identification - project_name: "{config_source}:project_name" - - # Tracking system configuration - tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello - project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key - story_location: "{config_source}:implementation_artifacts" # Relative path for file-system, Future will support URL for Jira/Linear/Trello - story_location_absolute: "{config_source}:implementation_artifacts" # Absolute path for file operations - - # Source files (file-system only) - epics_location: "{planning_artifacts}" # Directory containing epic*.md files - epics_pattern: "epic*.md" # Pattern to find epic files - - # Output configuration - status_file: "{implementation_artifacts}/sprint-status.yaml" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status -input_file_patterns: - epics: - description: "All epics with user stories" - whole: "{output_folder}/*epic*.md" - sharded: "{output_folder}/*epic*/*.md" - load_strategy: "FULL_LOAD" - -# Output configuration -default_output_file: "{status_file}" diff --git a/src/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/bmm/workflows/4-implementation/sprint-status/instructions.md index c058644a4..f1cee82bb 100644 --- a/src/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/src/bmm/workflows/4-implementation/sprint-status/instructions.md @@ -1,7 +1,7 @@ # Sprint Status - Multi-Mode Service -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml +The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md +You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-status/workflow.md Modes: interactive (default), validate, data ⚠️ ABSOLUTELY NO TIME ESTIMATES. Do NOT mention hours, days, weeks, or timelines. diff --git a/src/bmm/workflows/4-implementation/sprint-status/workflow.md b/src/bmm/workflows/4-implementation/sprint-status/workflow.md new file mode 100644 index 000000000..5baa8d646 --- /dev/null +++ b/src/bmm/workflows/4-implementation/sprint-status/workflow.md @@ -0,0 +1,26 @@ +--- +name: sprint-status +description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `implementation_artifacts` + - `planning_artifacts` + - `date` (system-generated) + - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.md + + diff --git a/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml b/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml deleted file mode 100644 index 8946f0291..000000000 --- a/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# Sprint Status - Implementation Tracker -name: sprint-status -description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -date: system-generated -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status" -instructions: "{installed_path}/instructions.md" - -# Inputs -variables: - sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" - tracking_system: "file-system" - -# Smart input file references -input_file_patterns: - sprint_status: - description: "Sprint status file generated by sprint-planning" - whole: "{implementation_artifacts}/sprint-status.yaml" - load_strategy: "FULL_LOAD" diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md b/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md index 3fbeb13b1..151426e2b 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md +++ b/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md @@ -41,7 +41,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: - `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md` - `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md` -- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` +- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md` --- diff --git a/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md b/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md index 7c41b948d..3d92da893 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md +++ b/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md @@ -4,7 +4,7 @@ description: Conversational spec engineering - ask questions, investigate code, main_config: '{project-root}/_bmad/bmm/config.yaml' # Checkpoint handler paths -advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md' --- diff --git a/src/bmm/workflows/document-project/instructions.md b/src/bmm/workflows/document-project/instructions.md index 2f567fa38..781fde439 100644 --- a/src/bmm/workflows/document-project/instructions.md +++ b/src/bmm/workflows/document-project/instructions.md @@ -1,7 +1,7 @@ # Document Project Workflow Router -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/document-project/workflow.yaml +The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md +You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/document-project/workflow.md Communicate all responses in {communication_language} diff --git a/src/bmm/workflows/document-project/workflow.md b/src/bmm/workflows/document-project/workflow.md new file mode 100644 index 000000000..b64275023 --- /dev/null +++ b/src/bmm/workflows/document-project/workflow.md @@ -0,0 +1,30 @@ +--- +name: document-project +description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development" +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve variables: + - `user_name` + - `communication_language` + - `document_output_language` + - `user_skill_level` + - `project_knowledge` + - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/document-project` + - `documentation_requirements_csv` = `{installed_path}/documentation-requirements.csv` + + + Communicate all responses in {communication_language} and generate all documents in {document_output_language} + + + Read and follow instructions at: {installed_path}/instructions.md + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + diff --git a/src/bmm/workflows/document-project/workflow.yaml b/src/bmm/workflows/document-project/workflow.yaml deleted file mode 100644 index 4667d7c0b..000000000 --- a/src/bmm/workflows/document-project/workflow.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# Document Project Workflow Configuration -name: "document-project" -version: "1.2.0" -description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development" -author: "BMad" - -# Critical variables -config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:project_knowledge" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -user_skill_level: "{config_source}:user_skill_level" -date: system-generated - -# Module path and component files -installed_path: "{project-root}/_bmad/bmm/workflows/document-project" -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" - -# Required data files - CRITICAL for project type detection and documentation requirements -documentation_requirements_csv: "{installed_path}/documentation-requirements.csv" diff --git a/src/bmm/workflows/document-project/workflows/deep-dive.yaml b/src/bmm/workflows/document-project/workflows/deep-dive.yaml index a333cc4bf..d91105112 100644 --- a/src/bmm/workflows/document-project/workflows/deep-dive.yaml +++ b/src/bmm/workflows/document-project/workflows/deep-dive.yaml @@ -3,8 +3,8 @@ name: "document-project-deep-dive" description: "Exhaustive deep-dive documentation of specific project areas" author: "BMad" -# This is a sub-workflow called by document-project/workflow.yaml -parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" +# This is a sub-workflow called by document-project/workflow.md +parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" # Critical variables inherited from parent config_source: "{project-root}/_bmad/bmb/config.yaml" diff --git a/src/bmm/workflows/document-project/workflows/full-scan.yaml b/src/bmm/workflows/document-project/workflows/full-scan.yaml index f62aba9b2..c131bb00d 100644 --- a/src/bmm/workflows/document-project/workflows/full-scan.yaml +++ b/src/bmm/workflows/document-project/workflows/full-scan.yaml @@ -3,8 +3,8 @@ name: "document-project-full-scan" description: "Complete project documentation workflow (initial scan or full rescan)" author: "BMad" -# This is a sub-workflow called by document-project/workflow.yaml -parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" +# This is a sub-workflow called by document-project/workflow.md +parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" # Critical variables inherited from parent config_source: "{project-root}/_bmad/bmb/config.yaml" diff --git a/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md deleted file mode 100644 index bf4d988c0..000000000 --- a/src/bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md +++ /dev/null @@ -1,128 +0,0 @@ -# Create Data Flow Diagram - Workflow Instructions - -```xml -This workflow creates data flow diagrams (DFD) in Excalidraw format. - - - - - Review user's request and extract: DFD level, processes, data stores, external entities - Skip to Step 4 - - - - Ask: "What level of DFD do you need?" - Present options: - 1. Context Diagram (Level 0) - Single process showing system boundaries - 2. Level 1 DFD - Major processes and data flows - 3. Level 2 DFD - Detailed sub-processes - 4. Custom - Specify your requirements - - WAIT for selection - - - - Ask: "Describe the processes, data stores, and external entities in your system" - WAIT for user description - Summarize what will be included and confirm with user - - - - Check for existing theme.json, ask to use if exists - - Ask: "Choose a DFD color scheme:" - Present numbered options: - 1. Standard DFD - - Process: #e3f2fd (light blue) - - Data Store: #e8f5e9 (light green) - - External Entity: #f3e5f5 (light purple) - - Border: #1976d2 (blue) - - 2. Colorful DFD - - Process: #fff9c4 (light yellow) - - Data Store: #c5e1a5 (light lime) - - External Entity: #ffccbc (light coral) - - Border: #f57c00 (orange) - - 3. Minimal DFD - - Process: #f5f5f5 (light gray) - - Data Store: #eeeeee (gray) - - External Entity: #e0e0e0 (medium gray) - - Border: #616161 (dark gray) - - 4. Custom - Define your own colors - - WAIT for selection - Create theme.json based on selection - - - - - List all processes with numbers (1.0, 2.0, etc.) - List all data stores (D1, D2, etc.) - List all external entities - Map all data flows with labels - Show planned structure, confirm with user - - - - Load {{templates}} and extract `dataflow` section - Load {{library}} - Load theme.json - Load {{helpers}} - - - - Follow standard DFD notation from {{helpers}} - - Build Order: - 1. External entities (rectangles, bold border) - 2. Processes (circles/ellipses with numbers) - 3. Data stores (parallel lines or rectangles) - 4. Data flows (labeled arrows) - - - DFD Rules: - - Processes: Numbered (1.0, 2.0), verb phrases - - Data stores: Named (D1, D2), noun phrases - - External entities: Named, noun phrases - - Data flows: Labeled with data names, arrows show direction - - No direct flow between external entities - - No direct flow between data stores - - - Layout: - - External entities at edges - - Processes in center - - Data stores between processes - - Minimize crossing flows - - Left-to-right or top-to-bottom flow - - - - - Verify DFD rules compliance - Strip unused elements and elements with isDeleted: true - Save to {{default_output_file}} - - - - NEVER delete the file if validation fails - always fix syntax errors - Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" - - Read the error message carefully - it shows the syntax error and position - Open the file and navigate to the error location - Fix the syntax error (add missing comma, bracket, or quote as indicated) - Save the file - Re-run validation with the same command - Repeat until validation passes - - Once validation passes, confirm with user - - - - Validate against {{validation}} - - - -``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md deleted file mode 100644 index 1da0488f5..000000000 --- a/src/bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md +++ /dev/null @@ -1,139 +0,0 @@ -# Create Diagram - Workflow Instructions - -```xml -This workflow creates system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format. - - - - - Review user's request and extract: diagram type, components/entities, relationships, notation preferences - Skip to Step 5 - Only ask about missing info in Steps 1-2 - - - - Ask: "What type of technical diagram do you need?" - Present options: - 1. System Architecture - 2. Entity-Relationship Diagram (ERD) - 3. UML Class Diagram - 4. UML Sequence Diagram - 5. UML Use Case Diagram - 6. Network Diagram - 7. Other - - WAIT for selection - - - - Ask: "Describe the components/entities and their relationships" - Ask: "What notation standard? (Standard/Simplified/Strict UML-ERD)" - WAIT for user input - Summarize what will be included and confirm with user - - - - Check if theme.json exists at output location - Ask to use it, load if yes, else proceed to Step 4 - Proceed to Step 4 - - - - Ask: "Choose a color scheme for your diagram:" - Present numbered options: - 1. Professional - - Component: #e3f2fd (light blue) - - Database: #e8f5e9 (light green) - - Service: #fff3e0 (light orange) - - Border: #1976d2 (blue) - - 2. Colorful - - Component: #e1bee7 (light purple) - - Database: #c5e1a5 (light lime) - - Service: #ffccbc (light coral) - - Border: #7b1fa2 (purple) - - 3. Minimal - - Component: #f5f5f5 (light gray) - - Database: #eeeeee (gray) - - Service: #e0e0e0 (medium gray) - - Border: #616161 (dark gray) - - 4. Custom - Define your own colors - - WAIT for selection - Create theme.json based on selection - Show preview and confirm - - - - List all components/entities - Map all relationships - Show planned layout - Ask: "Structure looks correct? (yes/no)" - Adjust and repeat - - - - Load {{templates}} and extract `diagram` section - Load {{library}} - Load theme.json and merge with template - Load {{helpers}} for guidelines - - - - Follow {{helpers}} for proper element creation - - For Each Component: - - Generate unique IDs (component-id, text-id, group-id) - - Create shape with groupIds - - Calculate text width - - Create text with containerId and matching groupIds - - Add boundElements - - - For Each Connection: - - Determine arrow type (straight/elbow) - - Create with startBinding and endBinding - - Update boundElements on both components - - - Build Order by Type: - - Architecture: Services → Databases → Connections → Labels - - ERD: Entities → Attributes → Relationships → Cardinality - - UML Class: Classes → Attributes → Methods → Relationships - - UML Sequence: Actors → Lifelines → Messages → Returns - - UML Use Case: Actors → Use Cases → Relationships - - - Alignment: - - Snap to 20px grid - - Space: 40px between components, 60px between sections - - - - - Strip unused elements and elements with isDeleted: true - Save to {{default_output_file}} - - - - NEVER delete the file if validation fails - always fix syntax errors - Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" - - Read the error message carefully - it shows the syntax error and position - Open the file and navigate to the error location - Fix the syntax error (add missing comma, bracket, or quote as indicated) - Save the file - Re-run validation with the same command - Repeat until validation passes - - Once validation passes, confirm: "Diagram created at {{default_output_file}}. Open to view?" - - - - Validate against {{validation}} using {_bmad}/core/tasks/validate-workflow.md - - - -``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md deleted file mode 100644 index 0a7b4ea1f..000000000 --- a/src/bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md +++ /dev/null @@ -1,239 +0,0 @@ -# Create Flowchart - Workflow Instructions - -```xml -This workflow creates a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows. - - - - - Before asking any questions, analyze what the user has already told you - - Review the user's initial request and conversation history - Extract any mentioned: flowchart type, complexity, decision points, save location - - - Summarize your understanding - Skip directly to Step 4 (Plan Flowchart Layout) - - - - Note what you already know - Only ask about missing information in Step 1 - - - - Proceed with full elicitation in Step 1 - - - - - Ask Question 1: "What type of process flow do you need to visualize?" - Present numbered options: - 1. Business Process Flow - Document business workflows, approval processes, or operational procedures - 2. Algorithm/Logic Flow - Visualize code logic, decision trees, or computational processes - 3. User Journey Flow - Map user interactions, navigation paths, or experience flows - 4. Data Processing Pipeline - Show data transformation, ETL processes, or processing stages - 5. Other - Describe your specific flowchart needs - - WAIT for user selection (1-5) - - Ask Question 2: "How many main steps are in this flow?" - Present numbered options: - 1. Simple (3-5 steps) - Quick process with few decision points - 2. Medium (6-10 steps) - Standard workflow with some branching - 3. Complex (11-20 steps) - Detailed process with multiple decision points - 4. Very Complex (20+ steps) - Comprehensive workflow requiring careful layout - - WAIT for user selection (1-4) - Store selection in {{complexity}} - - Ask Question 3: "Does your flow include decision points (yes/no branches)?" - Present numbered options: - 1. No decisions - Linear flow from start to end - 2. Few decisions (1-2) - Simple branching with yes/no paths - 3. Multiple decisions (3-5) - Several conditional branches - 4. Complex decisions (6+) - Extensive branching logic - - WAIT for user selection (1-4) - Store selection in {{decision_points}} - - Ask Question 4: "Where should the flowchart be saved?" - Present numbered options: - 1. Default location - docs/flowcharts/[auto-generated-name].excalidraw - 2. Custom path - Specify your own file path - 3. Project root - Save in main project directory - 4. Specific folder - Choose from existing folders - - WAIT for user selection (1-4) - - Ask for specific path - WAIT for user input - - Store final path in {{default_output_file}} - - - - Check if theme.json exists at output location - - Ask: "Found existing theme. Use it? (yes/no)" - WAIT for user response - - Load and use existing theme - Skip to Step 4 - - - Proceed to Step 3 - - - - Proceed to Step 3 - - - - - Ask: "Let's create a theme for your flowchart. Choose a color scheme:" - Present numbered options: - 1. Professional Blue - - Primary Fill: #e3f2fd (light blue) - - Accent/Border: #1976d2 (blue) - - Decision: #fff3e0 (light orange) - - Text: #1e1e1e (dark gray) - - 2. Success Green - - Primary Fill: #e8f5e9 (light green) - - Accent/Border: #388e3c (green) - - Decision: #fff9c4 (light yellow) - - Text: #1e1e1e (dark gray) - - 3. Neutral Gray - - Primary Fill: #f5f5f5 (light gray) - - Accent/Border: #616161 (gray) - - Decision: #e0e0e0 (medium gray) - - Text: #1e1e1e (dark gray) - - 4. Warm Orange - - Primary Fill: #fff3e0 (light orange) - - Accent/Border: #f57c00 (orange) - - Decision: #ffe0b2 (peach) - - Text: #1e1e1e (dark gray) - - 5. Custom Colors - Define your own color palette - - WAIT for user selection (1-5) - Store selection in {{theme_choice}} - - - Ask: "Primary fill color (hex code)?" - WAIT for user input - Store in {{custom_colors.primary_fill}} - Ask: "Accent/border color (hex code)?" - WAIT for user input - Store in {{custom_colors.accent}} - Ask: "Decision color (hex code)?" - WAIT for user input - Store in {{custom_colors.decision}} - - - Create theme.json with selected colors - Show theme preview with all colors - Ask: "Theme looks good?" - Present numbered options: - 1. Yes, use this theme - Proceed with theme - 2. No, adjust colors - Modify color selections - 3. Start over - Choose different preset - - WAIT for selection (1-3) - - Repeat Step 3 - - - - - List all steps and decision points based on gathered requirements - Show user the planned structure - Ask: "Structure looks correct? (yes/no)" - WAIT for user response - - Adjust structure based on feedback - Repeat this step - - - - - Load {{templates}} file - Extract `flowchart` section from YAML - Load {{library}} file - Load theme.json and merge colors with template - Load {{helpers}} for element creation guidelines - - - - Follow guidelines from {{helpers}} for proper element creation - - Build ONE section at a time following these rules: - - For Each Shape with Label: - 1. Generate unique IDs (shape-id, text-id, group-id) - 2. Create shape with groupIds: [group-id] - 3. Calculate text width: (text.length × fontSize × 0.6) + 20, round to nearest 10 - 4. Create text element with: - - containerId: shape-id - - groupIds: [group-id] (SAME as shape) - - textAlign: "center" - - verticalAlign: "middle" - - width: calculated width - 5. Add boundElements to shape referencing text - - - For Each Arrow: - 1. Determine arrow type needed: - - Straight: For forward flow (left-to-right, top-to-bottom) - - Elbow: For upward flow, backward flow, or complex routing - 2. Create arrow with startBinding and endBinding - 3. Set startBinding.elementId to source shape ID - 4. Set endBinding.elementId to target shape ID - 5. Set gap: 10 for both bindings - 6. If elbow arrow, add intermediate points for direction changes - 7. Update boundElements on both connected shapes - - - Alignment: - - Snap all x, y to 20px grid - - Align shapes vertically (same x for vertical flow) - - Space elements: 60px between shapes - - - Build Order: - 1. Start point (circle) with label - 2. Each process step (rectangle) with label - 3. Each decision point (diamond) with label - 4. End point (circle) with label - 5. Connect all with bound arrows - - - - - Strip unused elements and elements with isDeleted: true - Save to {{default_output_file}} - - - - NEVER delete the file if validation fails - always fix syntax errors - Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" - - Read the error message carefully - it shows the syntax error and position - Open the file and navigate to the error location - Fix the syntax error (add missing comma, bracket, or quote as indicated) - Save the file - Re-run validation with the same command - Repeat until validation passes - - Once validation passes, confirm with user: "Flowchart created at {{default_output_file}}. Open to view?" - - - - Validate against checklist at {{validation}} using {_bmad}/core/tasks/validate-workflow.md - - - -``` diff --git a/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md b/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md deleted file mode 100644 index 566b85578..000000000 --- a/src/bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md +++ /dev/null @@ -1,131 +0,0 @@ -# Create Wireframe - Workflow Instructions - -```xml -This workflow creates website or app wireframes in Excalidraw format. - - - - - Review user's request and extract: wireframe type, fidelity level, screen count, device type, save location - Skip to Step 5 - - - - Ask: "What type of wireframe do you need?" - Present options: - 1. Website (Desktop) - 2. Mobile App (iOS/Android) - 3. Web App (Responsive) - 4. Tablet App - 5. Multi-platform - - WAIT for selection - - - - Ask fidelity level (Low/Medium/High) - Ask screen count (Single/Few 2-3/Multiple 4-6/Many 7+) - Ask device dimensions or use standard - Ask save location - - - - Check for existing theme.json, ask to use if exists - - - - Ask: "Choose a wireframe style:" - Present numbered options: - 1. Classic Wireframe - - Background: #ffffff (white) - - Container: #f5f5f5 (light gray) - - Border: #9e9e9e (gray) - - Text: #424242 (dark gray) - - 2. High Contrast - - Background: #ffffff (white) - - Container: #eeeeee (light gray) - - Border: #212121 (black) - - Text: #000000 (black) - - 3. Blueprint Style - - Background: #1a237e (dark blue) - - Container: #3949ab (blue) - - Border: #7986cb (light blue) - - Text: #ffffff (white) - - 4. Custom - Define your own colors - - WAIT for selection - Create theme.json based on selection - Confirm with user - - - - List all screens and their purposes - Map navigation flow between screens - Identify key UI elements for each screen - Show planned structure, confirm with user - - - - Load {{templates}} and extract `wireframe` section - Load {{library}} - Load theme.json - Load {{helpers}} - - - - Follow {{helpers}} for proper element creation - - For Each Screen: - - Create container/frame - - Add header section - - Add content areas - - Add navigation elements - - Add interactive elements (buttons, inputs) - - Add labels and annotations - - - Build Order: - 1. Screen containers - 2. Layout sections (header, content, footer) - 3. Navigation elements - 4. Content blocks - 5. Interactive elements - 6. Labels and annotations - 7. Flow indicators (if multi-screen) - - - Fidelity Guidelines: - - Low: Basic shapes, minimal detail, placeholder text - - Medium: More defined elements, some styling, representative content - - High: Detailed elements, realistic sizing, actual content examples - - - - - Strip unused elements and elements with isDeleted: true - Save to {{default_output_file}} - - - - NEVER delete the file if validation fails - always fix syntax errors - Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('✓ Valid JSON')" - - Read the error message carefully - it shows the syntax error and position - Open the file and navigate to the error location - Fix the syntax error (add missing comma, bracket, or quote as indicated) - Save the file - Re-run validation with the same command - Repeat until validation passes - - Once validation passes, confirm with user - - - - Validate against {{validation}} - - - -``` diff --git a/src/bmm/workflows/qa/automate/workflow.md b/src/bmm/workflows/qa/automate/workflow.md index c62057523..cb52e0e49 100644 --- a/src/bmm/workflows/qa/automate/workflow.md +++ b/src/bmm/workflows/qa/automate/workflow.md @@ -26,7 +26,10 @@ web_bundle: false Read and follow instructions at: {installed_path}/instructions.md - Validate against checklist at: {installed_path}/checklist.md + + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md diff --git a/src/bmm/workflows/testarch/trace/checklist.md b/src/bmm/workflows/testarch/trace/checklist.md deleted file mode 100644 index 7b1267177..000000000 --- a/src/bmm/workflows/testarch/trace/checklist.md +++ /dev/null @@ -1,642 +0,0 @@ -# Requirements Traceability & Gate Decision - Validation Checklist - -**Workflow:** `testarch-trace` -**Purpose:** Ensure complete traceability matrix with actionable gap analysis AND make deployment readiness decision (PASS/CONCERNS/FAIL/WAIVED) - -This checklist covers **two sequential phases**: - -- **PHASE 1**: Requirements Traceability (always executed) -- **PHASE 2**: Quality Gate Decision (executed if `enable_gate_decision: true`) - ---- - -# PHASE 1: REQUIREMENTS TRACEABILITY - -## Prerequisites Validation - -- [ ] Acceptance criteria are available (from story file OR inline) -- [ ] Test suite exists (or gaps are acknowledged and documented) -- [ ] If tests are missing, recommend `*atdd` (trace does not run it automatically) -- [ ] Test directory path is correct (`test_dir` variable) -- [ ] Story file is accessible (if using BMad mode) -- [ ] Knowledge base is loaded (test-priorities, traceability, risk-governance) - ---- - -## Context Loading - -- [ ] Story file read successfully (if applicable) -- [ ] Acceptance criteria extracted correctly -- [ ] Story ID identified (e.g., 1.3) -- [ ] `test-design.md` loaded (if available) -- [ ] `tech-spec.md` loaded (if available) -- [ ] `PRD.md` loaded (if available) -- [ ] Relevant knowledge fragments loaded from `tea-index.csv` - ---- - -## Test Discovery and Cataloging - -- [ ] Tests auto-discovered using multiple strategies (test IDs, describe blocks, file paths) -- [ ] Tests categorized by level (E2E, API, Component, Unit) -- [ ] Test metadata extracted: - - [ ] Test IDs (e.g., 1.3-E2E-001) - - [ ] Describe/context blocks - - [ ] It blocks (individual test cases) - - [ ] Given-When-Then structure (if BDD) - - [ ] Priority markers (P0/P1/P2/P3) -- [ ] All relevant test files found (no tests missed due to naming conventions) - ---- - -## Criteria-to-Test Mapping - -- [ ] Each acceptance criterion mapped to tests (or marked as NONE) -- [ ] Explicit references found (test IDs, describe blocks mentioning criterion) -- [ ] Test level documented (E2E, API, Component, Unit) -- [ ] Given-When-Then narrative verified for alignment -- [ ] Traceability matrix table generated: - - [ ] Criterion ID - - [ ] Description - - [ ] Test ID - - [ ] Test File - - [ ] Test Level - - [ ] Coverage Status - ---- - -## Coverage Classification - -- [ ] Coverage status classified for each criterion: - - [ ] **FULL** - All scenarios validated at appropriate level(s) - - [ ] **PARTIAL** - Some coverage but missing edge cases or levels - - [ ] **NONE** - No test coverage at any level - - [ ] **UNIT-ONLY** - Only unit tests (missing integration/E2E validation) - - [ ] **INTEGRATION-ONLY** - Only API/Component tests (missing unit confidence) -- [ ] Classification justifications provided -- [ ] Edge cases considered in FULL vs PARTIAL determination - ---- - -## Duplicate Coverage Detection - -- [ ] Duplicate coverage checked across test levels -- [ ] Acceptable overlap identified (defense in depth for critical paths) -- [ ] Unacceptable duplication flagged (same validation at multiple levels) -- [ ] Recommendations provided for consolidation -- [ ] Selective testing principles applied - ---- - -## Gap Analysis - -- [ ] Coverage gaps identified: - - [ ] Criteria with NONE status - - [ ] Criteria with PARTIAL status - - [ ] Criteria with UNIT-ONLY status - - [ ] Criteria with INTEGRATION-ONLY status -- [ ] Gaps prioritized by risk level using test-priorities framework: - - [ ] **CRITICAL** - P0 criteria without FULL coverage (BLOCKER) - - [ ] **HIGH** - P1 criteria without FULL coverage (PR blocker) - - [ ] **MEDIUM** - P2 criteria without FULL coverage (nightly gap) - - [ ] **LOW** - P3 criteria without FULL coverage (acceptable) -- [ ] Specific test recommendations provided for each gap: - - [ ] Suggested test level (E2E, API, Component, Unit) - - [ ] Test description (Given-When-Then) - - [ ] Recommended test ID (e.g., 1.3-E2E-004) - - [ ] Explanation of why test is needed - ---- - -## Coverage Metrics - -- [ ] Overall coverage percentage calculated (FULL coverage / total criteria) -- [ ] P0 coverage percentage calculated -- [ ] P1 coverage percentage calculated -- [ ] P2 coverage percentage calculated (if applicable) -- [ ] Coverage by level calculated: - - [ ] E2E coverage % - - [ ] API coverage % - - [ ] Component coverage % - - [ ] Unit coverage % - ---- - -## Test Quality Verification - -For each mapped test, verify: - -- [ ] Explicit assertions are present (not hidden in helpers) -- [ ] Test follows Given-When-Then structure -- [ ] No hard waits or sleeps (deterministic waiting only) -- [ ] Self-cleaning (test cleans up its data) -- [ ] File size < 300 lines -- [ ] Test duration < 90 seconds - -Quality issues flagged: - -- [ ] **BLOCKER** issues identified (missing assertions, hard waits, flaky patterns) -- [ ] **WARNING** issues identified (large files, slow tests, unclear structure) -- [ ] **INFO** issues identified (style inconsistencies, missing documentation) - -Knowledge fragments referenced: - -- [ ] `test-quality.md` for Definition of Done -- [ ] `fixture-architecture.md` for self-cleaning patterns -- [ ] `network-first.md` for Playwright best practices -- [ ] `data-factories.md` for test data patterns - ---- - -## Phase 1 Deliverables Generated - -### Traceability Matrix Markdown - -- [ ] File created at `{output_folder}/traceability-matrix.md` -- [ ] Template from `trace-template.md` used -- [ ] Full mapping table included -- [ ] Coverage status section included -- [ ] Gap analysis section included -- [ ] Quality assessment section included -- [ ] Recommendations section included - -### Coverage Badge/Metric (if enabled) - -- [ ] Badge markdown generated -- [ ] Metrics exported to JSON for CI/CD integration - -### Updated Story File (if enabled) - -- [ ] "Traceability" section added to story markdown -- [ ] Link to traceability matrix included -- [ ] Coverage summary included - ---- - -## Phase 1 Quality Assurance - -### Accuracy Checks - -- [ ] All acceptance criteria accounted for (none skipped) -- [ ] Test IDs correctly formatted (e.g., 1.3-E2E-001) -- [ ] File paths are correct and accessible -- [ ] Coverage percentages calculated correctly -- [ ] No false positives (tests incorrectly mapped to criteria) -- [ ] No false negatives (existing tests missed in mapping) - -### Completeness Checks - -- [ ] All test levels considered (E2E, API, Component, Unit) -- [ ] All priorities considered (P0, P1, P2, P3) -- [ ] All coverage statuses used appropriately (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) -- [ ] All gaps have recommendations -- [ ] All quality issues have severity and remediation guidance - -### Actionability Checks - -- [ ] Recommendations are specific (not generic) -- [ ] Test IDs suggested for new tests -- [ ] Given-When-Then provided for recommended tests -- [ ] Impact explained for each gap -- [ ] Priorities clear (CRITICAL, HIGH, MEDIUM, LOW) - ---- - -## Phase 1 Documentation - -- [ ] Traceability matrix is readable and well-formatted -- [ ] Tables render correctly in markdown -- [ ] Code blocks have proper syntax highlighting -- [ ] Links are valid and accessible -- [ ] Recommendations are clear and prioritized - ---- - -# PHASE 2: QUALITY GATE DECISION - -**Note**: Phase 2 executes only if `enable_gate_decision: true` in workflow.md - ---- - -## Prerequisites - -### Evidence Gathering - -- [ ] Test execution results obtained (CI/CD pipeline, test framework reports) -- [ ] Story/epic/release file identified and read -- [ ] Test design document discovered or explicitly provided (if available) -- [ ] Traceability matrix discovered or explicitly provided (available from Phase 1) -- [ ] NFR assessment discovered or explicitly provided (if available) -- [ ] Code coverage report discovered or explicitly provided (if available) -- [ ] Burn-in results discovered or explicitly provided (if available) - -### Evidence Validation - -- [ ] Evidence freshness validated (warn if >7 days old, recommend re-running workflows) -- [ ] All required assessments available or user acknowledged gaps -- [ ] Test results are complete (not partial or interrupted runs) -- [ ] Test results match current codebase (not from outdated branch) - -### Knowledge Base Loading - -- [ ] `risk-governance.md` loaded successfully -- [ ] `probability-impact.md` loaded successfully -- [ ] `test-quality.md` loaded successfully -- [ ] `test-priorities.md` loaded successfully -- [ ] `ci-burn-in.md` loaded (if burn-in results available) - ---- - -## Process Steps - -### Step 1: Context Loading - -- [ ] Gate type identified (story/epic/release/hotfix) -- [ ] Target ID extracted (story_id, epic_num, or release_version) -- [ ] Decision thresholds loaded from workflow variables -- [ ] Risk tolerance configuration loaded -- [ ] Waiver policy loaded - -### Step 2: Evidence Parsing - -**Test Results:** - -- [ ] Total test count extracted -- [ ] Passed test count extracted -- [ ] Failed test count extracted -- [ ] Skipped test count extracted -- [ ] Test duration extracted -- [ ] P0 test pass rate calculated -- [ ] P1 test pass rate calculated -- [ ] Overall test pass rate calculated - -**Quality Assessments:** - -- [ ] P0/P1/P2/P3 scenarios extracted from test-design.md (if available) -- [ ] Risk scores extracted from test-design.md (if available) -- [ ] Coverage percentages extracted from traceability-matrix.md (available from Phase 1) -- [ ] Coverage gaps extracted from traceability-matrix.md (available from Phase 1) -- [ ] NFR status extracted from nfr-assessment.md (if available) -- [ ] Security issues count extracted from nfr-assessment.md (if available) - -**Code Coverage:** - -- [ ] Line coverage percentage extracted (if available) -- [ ] Branch coverage percentage extracted (if available) -- [ ] Function coverage percentage extracted (if available) -- [ ] Critical path coverage validated (if available) - -**Burn-in Results:** - -- [ ] Burn-in iterations count extracted (if available) -- [ ] Flaky tests count extracted (if available) -- [ ] Stability score calculated (if available) - -### Step 3: Decision Rules Application - -**P0 Criteria Evaluation:** - -- [ ] P0 test pass rate evaluated (must be 100%) -- [ ] P0 acceptance criteria coverage evaluated (must be 100%) -- [ ] Security issues count evaluated (must be 0) -- [ ] Critical NFR failures evaluated (must be 0) -- [ ] Flaky tests evaluated (must be 0 if burn-in enabled) -- [ ] P0 decision recorded: PASS or FAIL - -**P1 Criteria Evaluation:** - -- [ ] P1 test pass rate evaluated (threshold: min_p1_pass_rate) -- [ ] P1 acceptance criteria coverage evaluated (threshold: 95%) -- [ ] Overall test pass rate evaluated (threshold: min_overall_pass_rate) -- [ ] Code coverage evaluated (threshold: min_coverage) -- [ ] P1 decision recorded: PASS or CONCERNS - -**P2/P3 Criteria Evaluation:** - -- [ ] P2 failures tracked (informational, don't block if allow_p2_failures: true) -- [ ] P3 failures tracked (informational, don't block if allow_p3_failures: true) -- [ ] Residual risks documented - -**Final Decision:** - -- [ ] Decision determined: PASS / CONCERNS / FAIL / WAIVED -- [ ] Decision rationale documented -- [ ] Decision is deterministic (follows rules, not arbitrary) - -### Step 4: Documentation - -**Gate Decision Document Created:** - -- [ ] Story/epic/release info section complete (ID, title, description, links) -- [ ] Decision clearly stated (PASS / CONCERNS / FAIL / WAIVED) -- [ ] Decision date recorded -- [ ] Evaluator recorded (user or agent name) - -**Evidence Summary Documented:** - -- [ ] Test results summary complete (total, passed, failed, pass rates) -- [ ] Coverage summary complete (P0/P1 criteria, code coverage) -- [ ] NFR validation summary complete (security, performance, reliability, maintainability) -- [ ] Flakiness summary complete (burn-in iterations, flaky test count) - -**Rationale Documented:** - -- [ ] Decision rationale clearly explained -- [ ] Key evidence highlighted -- [ ] Assumptions and caveats noted (if any) - -**Residual Risks Documented (if CONCERNS or WAIVED):** - -- [ ] Unresolved P1/P2 issues listed -- [ ] Probability × impact estimated for each risk -- [ ] Mitigations or workarounds described - -**Waivers Documented (if WAIVED):** - -- [ ] Waiver reason documented (business justification) -- [ ] Waiver approver documented (name, role) -- [ ] Waiver expiry date documented -- [ ] Remediation plan documented (fix in next release, due date) -- [ ] Monitoring plan documented - -**Critical Issues Documented (if FAIL or CONCERNS):** - -- [ ] Top 5-10 critical issues listed -- [ ] Priority assigned to each issue (P0/P1/P2) -- [ ] Owner assigned to each issue -- [ ] Due date assigned to each issue - -**Recommendations Documented:** - -- [ ] Next steps clearly stated for decision type -- [ ] Deployment recommendation provided -- [ ] Monitoring recommendations provided (if applicable) -- [ ] Remediation recommendations provided (if applicable) - -### Step 5: Status Updates and Notifications - -**Gate YAML Created:** - -- [ ] Gate YAML snippet generated with decision and criteria -- [ ] Evidence references included in YAML -- [ ] Next steps included in YAML -- [ ] YAML file saved to output folder - -**Stakeholder Notification Generated:** - -- [ ] Notification subject line created -- [ ] Notification body created with summary -- [ ] Recipients identified (PM, SM, DEV lead, stakeholders) -- [ ] Notification ready for delivery (if notify_stakeholders: true) - -**Outputs Saved:** - -- [ ] Gate decision document saved to `{output_file}` -- [ ] Gate YAML saved to `{output_folder}/gate-decision-{target}.yaml` -- [ ] All outputs are valid and readable - ---- - -## Phase 2 Output Validation - -### Gate Decision Document - -**Completeness:** - -- [ ] All required sections present (info, decision, evidence, rationale, next steps) -- [ ] No placeholder text or TODOs left in document -- [ ] All evidence references are accurate and complete -- [ ] All links to artifacts are valid - -**Accuracy:** - -- [ ] Decision matches applied criteria rules -- [ ] Test results match CI/CD pipeline output -- [ ] Coverage percentages match reports -- [ ] NFR status matches assessment document -- [ ] No contradictions or inconsistencies - -**Clarity:** - -- [ ] Decision rationale is clear and unambiguous -- [ ] Technical jargon is explained or avoided -- [ ] Stakeholders can understand next steps -- [ ] Recommendations are actionable - -### Gate YAML - -**Format:** - -- [ ] YAML is valid (no syntax errors) -- [ ] All required fields present (target, decision, date, evaluator, criteria, evidence) -- [ ] Field values are correct data types (numbers, strings, dates) - -**Content:** - -- [ ] Criteria values match decision document -- [ ] Evidence references are accurate -- [ ] Next steps align with decision type - ---- - -## Phase 2 Quality Checks - -### Decision Integrity - -- [ ] Decision is deterministic (follows rules, not arbitrary) -- [ ] P0 failures result in FAIL decision (unless waived) -- [ ] Security issues result in FAIL decision (unless waived - but should never be waived) -- [ ] Waivers have business justification and approver (if WAIVED) -- [ ] Residual risks are documented (if CONCERNS or WAIVED) - -### Evidence-Based - -- [ ] Decision is based on actual test results (not guesses) -- [ ] All claims are supported by evidence -- [ ] No assumptions without documentation -- [ ] Evidence sources are cited (CI run IDs, report URLs) - -### Transparency - -- [ ] Decision rationale is transparent and auditable -- [ ] Criteria evaluation is documented step-by-step -- [ ] Any deviations from standard process are explained -- [ ] Waiver justifications are clear (if applicable) - -### Consistency - -- [ ] Decision aligns with risk-governance knowledge fragment -- [ ] Priority framework (P0/P1/P2/P3) applied consistently -- [ ] Terminology consistent with test-quality knowledge fragment -- [ ] Decision matrix followed correctly - ---- - -## Phase 2 Integration Points - -### CI/CD Pipeline - -- [ ] Gate YAML is CI/CD-compatible -- [ ] YAML can be parsed by pipeline automation -- [ ] Decision can be used to block/allow deployments -- [ ] Evidence references are accessible to pipeline - -### Stakeholders - -- [ ] Notification message is clear and actionable -- [ ] Decision is explained in non-technical terms -- [ ] Next steps are specific and time-bound -- [ ] Recipients are appropriate for decision type - ---- - -## Phase 2 Compliance and Audit - -### Audit Trail - -- [ ] Decision date and time recorded -- [ ] Evaluator identified (user or agent) -- [ ] All evidence sources cited -- [ ] Decision criteria documented -- [ ] Rationale clearly explained - -### Traceability - -- [ ] Gate decision traceable to story/epic/release -- [ ] Evidence traceable to specific test runs -- [ ] Assessments traceable to workflows that created them -- [ ] Waiver traceable to approver (if applicable) - -### Compliance - -- [ ] Security requirements validated (no unresolved vulnerabilities) -- [ ] Quality standards met or waived with justification -- [ ] Regulatory requirements addressed (if applicable) -- [ ] Documentation sufficient for external audit - ---- - -## Phase 2 Edge Cases and Exceptions - -### Missing Evidence - -- [ ] If test-design.md missing, decision still possible with test results + trace -- [ ] If traceability-matrix.md missing, decision still possible with test results (but Phase 1 should provide it) -- [ ] If nfr-assessment.md missing, NFR validation marked as NOT ASSESSED -- [ ] If code coverage missing, coverage criterion marked as NOT ASSESSED -- [ ] User acknowledged gaps in evidence or provided alternative proof - -### Stale Evidence - -- [ ] Evidence freshness checked (if validate_evidence_freshness: true) -- [ ] Warnings issued for assessments >7 days old -- [ ] User acknowledged stale evidence or re-ran workflows -- [ ] Decision document notes any stale evidence used - -### Conflicting Evidence - -- [ ] Conflicts between test results and assessments resolved -- [ ] Most recent/authoritative source identified -- [ ] Conflict resolution documented in decision rationale -- [ ] User consulted if conflict cannot be resolved - -### Waiver Scenarios - -- [ ] Waiver only used for FAIL decision (not PASS or CONCERNS) -- [ ] Waiver has business justification (not technical convenience) -- [ ] Waiver has named approver with authority (VP/CTO/PO) -- [ ] Waiver has expiry date (does NOT apply to future releases) -- [ ] Waiver has remediation plan with concrete due date -- [ ] Security vulnerabilities are NOT waived (enforced) - ---- - -# FINAL VALIDATION (Both Phases) - -## Non-Prescriptive Validation - -- [ ] Traceability format adapted to team needs (not rigid template) -- [ ] Examples are minimal and focused on patterns -- [ ] Teams can extend with custom classifications -- [ ] Integration with external systems supported (JIRA, Azure DevOps) -- [ ] Compliance requirements considered (if applicable) - ---- - -## Documentation and Communication - -- [ ] All documents are readable and well-formatted -- [ ] Tables render correctly in markdown -- [ ] Code blocks have proper syntax highlighting -- [ ] Links are valid and accessible -- [ ] Recommendations are clear and prioritized -- [ ] Gate decision is prominent and unambiguous (Phase 2) - ---- - -## Final Validation - -**Phase 1 (Traceability):** - -- [ ] All prerequisites met -- [ ] All acceptance criteria mapped or gaps documented -- [ ] P0 coverage is 100% OR documented as BLOCKER -- [ ] Gap analysis is complete and prioritized -- [ ] Test quality issues identified and flagged -- [ ] Deliverables generated and saved - -**Phase 2 (Gate Decision):** - -- [ ] All quality evidence gathered -- [ ] Decision criteria applied correctly -- [ ] Decision rationale documented -- [ ] Gate YAML ready for CI/CD integration -- [ ] Status file updated (if enabled) -- [ ] Stakeholders notified (if enabled) - -**Workflow Complete:** - -- [ ] Phase 1 completed successfully -- [ ] Phase 2 completed successfully (if enabled) -- [ ] All outputs validated and saved -- [ ] Ready to proceed based on gate decision - ---- - -## Sign-Off - -**Phase 1 - Traceability Status:** - -- [ ] ✅ PASS - All quality gates met, no critical gaps -- [ ] ⚠️ WARN - P1 gaps exist, address before PR merge -- [ ] ❌ FAIL - P0 gaps exist, BLOCKER for release - -**Phase 2 - Gate Decision Status (if enabled):** - -- [ ] ✅ PASS - Deploy to production -- [ ] ⚠️ CONCERNS - Deploy with monitoring -- [ ] ❌ FAIL - Block deployment, fix issues -- [ ] 🔓 WAIVED - Deploy with business approval and remediation plan - -**Next Actions:** - -- If PASS (both phases): Proceed to deployment -- If WARN/CONCERNS: Address gaps/issues, proceed with monitoring -- If FAIL (either phase): Run `*atdd` for missing tests, fix issues, re-run `*trace` -- If WAIVED: Deploy with approved waiver, schedule remediation - ---- - -## Notes - -Record any issues, deviations, or important observations during workflow execution: - -- **Phase 1 Issues**: [Note any traceability mapping challenges, missing tests, quality concerns] -- **Phase 2 Issues**: [Note any missing, stale, or conflicting evidence] -- **Decision Rationale**: [Document any nuanced reasoning or edge cases] -- **Waiver Details**: [Document waiver negotiations or approvals] -- **Follow-up Actions**: [List any actions required after gate decision] - ---- - - diff --git a/src/bmm/workflows/testarch/trace/instructions.md b/src/bmm/workflows/testarch/trace/instructions.md deleted file mode 100644 index 3cf4bd5be..000000000 --- a/src/bmm/workflows/testarch/trace/instructions.md +++ /dev/null @@ -1,1030 +0,0 @@ -# Test Architect Workflow: Requirements Traceability & Quality Gate Decision - -**Workflow:** `testarch-trace` -**Purpose:** Generate requirements-to-tests traceability matrix, analyze coverage gaps, and make quality gate decisions (PASS/CONCERNS/FAIL/WAIVED) -**Agent:** Test Architect (TEA) -**Format:** Pure Markdown v4.0 (no XML blocks) - ---- - -## Overview - -This workflow operates in two sequential phases to validate test coverage and deployment readiness: - -**PHASE 1 - REQUIREMENTS TRACEABILITY:** Create comprehensive traceability matrix mapping acceptance criteria to implemented tests, identify coverage gaps, and provide actionable recommendations. - -**PHASE 2 - QUALITY GATE DECISION:** Use traceability results combined with test execution evidence to make gate decisions (PASS/CONCERNS/FAIL/WAIVED) that determine deployment readiness. - -**Key Capabilities:** - -- Map acceptance criteria to specific test cases across all levels (E2E, API, Component, Unit) -- Classify coverage status (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) -- Prioritize gaps by risk level (P0/P1/P2/P3) using test-priorities framework -- Apply deterministic decision rules based on coverage and test execution results -- Generate gate decisions with evidence and rationale -- Support waivers for business-approved exceptions -- Update workflow status and notify stakeholders - ---- - -## Prerequisites - -**Required (Phase 1):** - -- Acceptance criteria (from story file OR provided inline) -- Implemented test suite (or acknowledge gaps to be addressed) - -**Required (Phase 2 - if `enable_gate_decision: true`):** - -- Test execution results (CI/CD test reports, pass/fail rates) -- Test design with risk priorities (P0/P1/P2/P3) - -**Recommended:** - -- `test-design.md` (for risk assessment and priority context) -- `nfr-assessment.md` (for release-level gates) -- `tech-spec.md` (for technical implementation context) -- Test framework configuration (playwright.config.ts, jest.config.js, etc.) - -**Halt Conditions:** - -- If story lacks any implemented tests AND no gaps are acknowledged, recommend running `*atdd` workflow first -- If acceptance criteria are completely missing, halt and request them -- If Phase 2 enabled but test execution results missing, warn and skip gate decision - -Note: `*trace` never runs `*atdd` automatically; it only recommends running it when tests are missing. - ---- - -## PHASE 1: REQUIREMENTS TRACEABILITY - -This phase focuses on mapping requirements to tests, analyzing coverage, and identifying gaps. - ---- - -### Step 1: Load Context and Knowledge Base - -**Actions:** - -1. Load relevant knowledge fragments from `{project-root}/_bmad/bmm/testarch/tea-index.csv`: - - `test-priorities-matrix.md` - P0/P1/P2/P3 risk framework with automated priority calculation, risk-based mapping, tagging strategy (389 lines, 2 examples) - - `risk-governance.md` - Risk-based testing approach: 6 categories (TECH, SEC, PERF, DATA, BUS, OPS), automated scoring, gate decision engine, coverage traceability (625 lines, 4 examples) - - `probability-impact.md` - Risk scoring methodology: probability × impact matrix, automated classification, dynamic re-assessment, gate integration (604 lines, 4 examples) - - `test-quality.md` - Definition of Done for tests: deterministic, isolated with cleanup, explicit assertions, length/time limits (658 lines, 5 examples) - - `selective-testing.md` - Duplicate coverage patterns: tag-based, spec filters, diff-based selection, promotion rules (727 lines, 4 examples) - -2. Read story file (if provided): - - Extract acceptance criteria - - Identify story ID (e.g., 1.3) - - Note any existing test design or priority information - -3. Read related BMad artifacts (if available): - - `test-design.md` - Risk assessment and test priorities - - `tech-spec.md` - Technical implementation details - - `PRD.md` - Product requirements context - -**Output:** Complete understanding of requirements, priorities, and existing context - ---- - -### Step 2: Discover and Catalog Tests - -**Actions:** - -1. Auto-discover test files related to the story: - - Search for test IDs (e.g., `1.3-E2E-001`, `1.3-UNIT-005`) - - Search for describe blocks mentioning feature name - - Search for file paths matching feature directory - - Use `glob` to find test files in `{test_dir}` - -2. Categorize tests by level: - - **E2E Tests**: Full user journeys through UI - - **API Tests**: HTTP contract and integration tests - - **Component Tests**: UI component behavior in isolation - - **Unit Tests**: Business logic and pure functions - -3. Extract test metadata: - - Test ID (if present) - - Describe/context blocks - - It blocks (individual test cases) - - Given-When-Then structure (if BDD) - - Assertions used - - Priority markers (P0/P1/P2/P3) - -**Output:** Complete catalog of all tests for this feature - ---- - -### Step 3: Map Criteria to Tests - -**Actions:** - -1. For each acceptance criterion: - - Search for explicit references (test IDs, describe blocks mentioning criterion) - - Map to specific test files and it blocks - - Use Given-When-Then narrative to verify alignment - - Document test level (E2E, API, Component, Unit) - -2. Build traceability matrix: - - ``` - | Criterion ID | Description | Test ID | Test File | Test Level | Coverage Status | - | ------------ | ----------- | ----------- | ---------------- | ---------- | --------------- | - | AC-1 | User can... | 1.3-E2E-001 | e2e/auth.spec.ts | E2E | FULL | - ``` - -3. Classify coverage status for each criterion: - - **FULL**: All scenarios validated at appropriate level(s) - - **PARTIAL**: Some coverage but missing edge cases or levels - - **NONE**: No test coverage at any level - - **UNIT-ONLY**: Only unit tests (missing integration/E2E validation) - - **INTEGRATION-ONLY**: Only API/Component tests (missing unit confidence) - -4. Check for duplicate coverage: - - Same behavior tested at multiple levels unnecessarily - - Flag violations of selective testing principles - - Recommend consolidation where appropriate - -**Output:** Complete traceability matrix with coverage classifications - ---- - -### Step 4: Analyze Gaps and Prioritize - -**Actions:** - -1. Identify coverage gaps: - - List criteria with NONE, PARTIAL, UNIT-ONLY, or INTEGRATION-ONLY status - - Assign severity based on test-priorities framework: - - **CRITICAL**: P0 criteria without FULL coverage (blocks release) - - **HIGH**: P1 criteria without FULL coverage (PR blocker) - - **MEDIUM**: P2 criteria without FULL coverage (nightly test gap) - - **LOW**: P3 criteria without FULL coverage (acceptable gap) - -2. Recommend specific tests to add: - - Suggest test level (E2E, API, Component, Unit) - - Provide test description (Given-When-Then) - - Recommend test ID (e.g., `1.3-E2E-004`) - - Explain why this test is needed - -3. Calculate coverage metrics: - - Overall coverage percentage (criteria with FULL coverage / total criteria) - - P0 coverage percentage (critical paths) - - P1 coverage percentage (high priority) - - Coverage by level (E2E%, API%, Component%, Unit%) - -4. Check against quality gates: - - P0 coverage >= 100% (required) - - P1 coverage >= 90% (recommended) - - Overall coverage >= 80% (recommended) - -**Output:** Prioritized gap analysis with actionable recommendations and coverage metrics - ---- - -### Step 5: Verify Test Quality - -**Actions:** - -1. For each mapped test, verify: - - Explicit assertions are present (not hidden in helpers) - - Test follows Given-When-Then structure - - No hard waits or sleeps - - Self-cleaning (test cleans up its data) - - File size < 300 lines - - Test duration < 90 seconds - -2. Flag quality issues: - - **BLOCKER**: Missing assertions, hard waits, flaky patterns - - **WARNING**: Large files, slow tests, unclear structure - - **INFO**: Style inconsistencies, missing documentation - -3. Reference knowledge fragments: - - `test-quality.md` for Definition of Done - - `fixture-architecture.md` for self-cleaning patterns - - `network-first.md` for Playwright best practices - - `data-factories.md` for test data patterns - -**Output:** Quality assessment for each test with improvement recommendations - ---- - -### Step 6: Generate Deliverables (Phase 1) - -**Actions:** - -1. Create traceability matrix markdown file: - - Use template from `trace-template.md` - - Include full mapping table - - Add coverage status section - - Add gap analysis section - - Add quality assessment section - - Add recommendations section - - Save to `{output_folder}/traceability-matrix.md` - -2. Generate gate YAML snippet (if enabled): - - ```yaml - traceability: - story_id: '1.3' - coverage: - overall: 85% - p0: 100% - p1: 90% - p2: 75% - gaps: - critical: 0 - high: 1 - medium: 2 - status: 'PASS' # or "FAIL" if P0 < 100% - ``` - -3. Create coverage badge/metric (if enabled): - - Generate badge markdown: `![Coverage](https://img.shields.io/badge/coverage-85%25-green)` - - Export metrics to JSON for CI/CD integration - -4. Update story file (if enabled): - - Add "Traceability" section to story markdown - - Link to traceability matrix - - Include coverage summary - - Add gate status - -**Output:** Complete Phase 1 traceability deliverables - -**Next:** If `enable_gate_decision: true`, proceed to Phase 2. Otherwise, workflow complete. - ---- - -## PHASE 2: QUALITY GATE DECISION - -This phase uses traceability results to make a quality gate decision (PASS/CONCERNS/FAIL/WAIVED) based on evidence and decision rules. - -**When Phase 2 Runs:** Automatically after Phase 1 if `enable_gate_decision: true` (default: true) - -**Skip Conditions:** If test execution results (`test_results`) not provided, warn and skip Phase 2. - ---- - -### Step 7: Gather Quality Evidence - -**Actions:** - -1. **Load Phase 1 traceability results** (inherited context): - - Coverage metrics (P0/P1/overall percentages) - - Gap analysis (missing/partial tests) - - Quality concerns (test quality flags) - - Traceability matrix - -2. **Load test execution results** (if `test_results` provided): - - Read CI/CD test reports (JUnit XML, TAP, JSON) - - Extract pass/fail counts by priority - - Calculate pass rates: - - **P0 pass rate**: `(P0 passed / P0 total) * 100` - - **P1 pass rate**: `(P1 passed / P1 total) * 100` - - **Overall pass rate**: `(All passed / All total) * 100` - - Identify failing tests and map to criteria - -3. **Load NFR assessment** (if `nfr_file` provided): - - Read `nfr-assessment.md` or similar - - Check critical NFR status (performance, security, scalability) - - Flag any critical NFR failures - -4. **Load supporting artifacts**: - - `test-design.md` → Risk priorities, DoD checklist - - `story-*.md` or `Epics.md` → Requirements context - -5. **Validate evidence freshness** (if `validate_evidence_freshness: true`): - - Check timestamps of test-design, traceability, NFR assessments - - Warn if artifacts are >7 days old - -6. **Check prerequisite workflows** (if `check_all_workflows_complete: true`): - - Verify test-design workflow complete - - Verify trace workflow complete (Phase 1) - - Verify nfr-assess workflow complete (if release-level gate) - -**Output:** Consolidated evidence bundle with all quality signals - ---- - -### Step 8: Apply Decision Rules - -**If `decision_mode: "deterministic"`** (rule-based - default): - -**Decision rules** (based on `workflow.md` thresholds): - -1. **PASS** if ALL of the following are true: - - P0 coverage ≥ `min_p0_coverage` (default: 100%) - - P1 coverage ≥ `min_p1_coverage` (default: 90%) - - Overall coverage ≥ `min_overall_coverage` (default: 80%) - - P0 test pass rate = `min_p0_pass_rate` (default: 100%) - - P1 test pass rate ≥ `min_p1_pass_rate` (default: 95%) - - Overall test pass rate ≥ `min_overall_pass_rate` (default: 90%) - - Critical NFRs passed (if `nfr_file` provided) - - No unresolved security issues ≤ `max_security_issues` (default: 0) - - No test quality red flags (hard waits, no assertions) - -2. **CONCERNS** if ANY of the following are true: - - P1 coverage 80-89% (below threshold but not critical) - - P1 test pass rate 90-94% (below threshold but not critical) - - Overall pass rate 85-89% - - P2 coverage <50% (informational) - - Some non-critical NFRs failing - - Minor test quality concerns (large test files, inferred mappings) - - **Note**: CONCERNS does NOT block deployment but requires acknowledgment - -3. **FAIL** if ANY of the following are true: - - P0 coverage <100% (missing critical tests) - - P0 test pass rate <100% (failing critical tests) - - P1 coverage <80% (significant gap) - - P1 test pass rate <90% (significant failures) - - Overall coverage <80% - - Overall pass rate <85% - - Critical NFRs failing (`max_critical_nfrs_fail` exceeded) - - Unresolved security issues (`max_security_issues` exceeded) - - Major test quality issues (tests with no assertions, pervasive hard waits) - -4. **WAIVED** (only if `allow_waivers: true`): - - Decision would be FAIL based on rules above - - Business stakeholder has approved waiver - - Waiver documented with: - - Justification (time constraint, known limitation, acceptable risk) - - Approver name and date - - Mitigation plan (follow-up stories, manual testing) - - Waiver evidence linked (email, Slack thread, ticket) - -**Risk tolerance adjustments:** - -- If `allow_p2_failures: true` → P2 test failures do NOT affect gate decision -- If `allow_p3_failures: true` → P3 test failures do NOT affect gate decision -- If `escalate_p1_failures: true` → P1 failures require explicit manager/lead approval - -**If `decision_mode: "manual"`:** - -- Present evidence summary to team -- Recommend decision based on rules above -- Team makes final call in meeting/chat -- Document decision with approver names - -**Output:** Gate decision (PASS/CONCERNS/FAIL/WAIVED) with rule-based rationale - ---- - -### Step 9: Document Decision and Evidence - -**Actions:** - -1. **Create gate decision document**: - - Save to `gate_output_file` (default: `{output_folder}/gate-decision-{gate_type}-{story_id}.md`) - - Use structure below - -2. **Document structure**: - -```markdown -# Quality Gate Decision: {gate_type} {story_id/epic_num/release_version} - -**Decision**: [PASS / CONCERNS / FAIL / WAIVED] -**Date**: {date} -**Decider**: {decision_mode} (deterministic | manual) -**Evidence Date**: {test_results_date} - ---- - -## Summary - -[1-2 sentence summary of decision and key factors] - ---- - -## Decision Criteria - -| Criterion | Threshold | Actual | Status | -| ----------------- | --------- | -------- | ------ | -| P0 Coverage | ≥100% | 100% | ✅ PASS | -| P1 Coverage | ≥90% | 88% | ⚠️ FAIL | -| Overall Coverage | ≥80% | 92% | ✅ PASS | -| P0 Pass Rate | 100% | 100% | ✅ PASS | -| P1 Pass Rate | ≥95% | 98% | ✅ PASS | -| Overall Pass Rate | ≥90% | 96% | ✅ PASS | -| Critical NFRs | All Pass | All Pass | ✅ PASS | -| Security Issues | 0 | 0 | ✅ PASS | - -**Overall Status**: 7/8 criteria met → Decision: **CONCERNS** - ---- - -## Evidence Summary - -### Test Coverage (from Phase 1 Traceability) - -- **P0 Coverage**: 100% (5/5 criteria fully covered) -- **P1 Coverage**: 88% (7/8 criteria fully covered) -- **Overall Coverage**: 92% (12/13 criteria covered) -- **Gap**: AC-5 (P1) missing E2E test - -### Test Execution Results - -- **P0 Pass Rate**: 100% (12/12 tests passed) -- **P1 Pass Rate**: 98% (45/46 tests passed) -- **Overall Pass Rate**: 96% (67/70 tests passed) -- **Failures**: 3 P2 tests (non-blocking) - -### Non-Functional Requirements - -- Performance: ✅ PASS (response time <500ms) -- Security: ✅ PASS (no vulnerabilities) -- Scalability: ✅ PASS (handles 10K users) - -### Test Quality - -- All tests have explicit assertions ✅ -- No hard waits detected ✅ -- Test files <300 lines ✅ -- Test IDs follow convention ✅ - ---- - -## Decision Rationale - -**Why CONCERNS (not PASS)**: - -- P1 coverage at 88% is below 90% threshold -- AC-5 (P1 priority) missing E2E test for error handling scenario -- This is a known gap from test-design phase - -**Why CONCERNS (not FAIL)**: - -- P0 coverage is 100% (critical paths validated) -- Overall coverage is 92% (above 80% threshold) -- Test pass rate is excellent (96% overall) -- Gap is isolated to one P1 criterion (not systemic) - -**Recommendation**: - -- Acknowledge gap and proceed with deployment -- Add missing AC-5 E2E test in next sprint -- Create follow-up story: "Add E2E test for AC-5 error handling" - ---- - -## Next Steps - -- [ ] Create follow-up story for AC-5 E2E test -- [ ] Deploy to staging environment -- [ ] Monitor production for edge cases related to AC-5 -- [ ] Update traceability matrix after follow-up test added - ---- - -## References - -- Traceability Matrix: `_bmad/output/traceability-matrix.md` -- Test Design: `_bmad/output/test-design-epic-2.md` -- Test Results: `ci-artifacts/test-report-2025-01-15.xml` -- NFR Assessment: `_bmad/output/nfr-assessment-release-1.2.md` -``` - -3. **Include evidence links** (if `require_evidence: true`): - - Link to traceability matrix - - Link to test execution reports (CI artifacts) - - Link to NFR assessment - - Link to test-design document - - Link to relevant PRs, commits, deployments - -4. **Waiver documentation** (if decision is WAIVED): - - Approver name and role (e.g., "Jane Doe, Engineering Manager") - - Approval date and method (e.g., "2025-01-15, Slack thread") - - Justification (e.g., "Time-boxed MVP, missing tests will be added in v1.1") - - Mitigation plan (e.g., "Manual testing by QA, follow-up stories created") - - Evidence link (e.g., "Slack: #engineering 2025-01-15 3:42pm") - -**Output:** Complete gate decision document with evidence and rationale - ---- - -### Step 10: Update Status Tracking and Notify - -**Actions:** - -1. **Generate stakeholder notification** (if `notify_stakeholders: true`): - - Create concise summary message for team communication - - Include: Decision, key metrics, action items - - Format for Slack/email/chat: - - ``` - 🚦 Quality Gate Decision: Story 1.3 - User Login - - Decision: ⚠️ CONCERNS - - P0 Coverage: ✅ 100% - - P1 Coverage: ⚠️ 88% (below 90%) - - Test Pass Rate: ✅ 96% - - Action Required: - - Create follow-up story for AC-5 E2E test - - Deploy to staging for validation - - Full Report: _bmad/output/gate-decision-story-1.3.md - ``` - -2. **Request sign-off** (if `require_sign_off: true`): - - Prompt for named approver (tech lead, QA lead, PM) - - Document approver name and timestamp in gate decision - - Block until sign-off received (interactive prompt) - -**Output:** Status tracking updated, stakeholders notified, sign-off obtained (if required) - -**Workflow Complete**: Both Phase 1 (traceability) and Phase 2 (gate decision) deliverables generated. - ---- - -## Decision Matrix (Quick Reference) - -| Scenario | P0 Cov | P1 Cov | Overall Cov | P0 Pass | P1 Pass | Overall Pass | NFRs | Decision | -| --------------- | ----------------- | ------ | ----------- | ------- | ------- | ------------ | ---- | ------------ | -| All green | 100% | ≥90% | ≥80% | 100% | ≥95% | ≥90% | Pass | **PASS** | -| Minor gap | 100% | 80-89% | ≥80% | 100% | 90-94% | 85-89% | Pass | **CONCERNS** | -| Missing P0 | <100% | - | - | - | - | - | - | **FAIL** | -| P0 test fail | 100% | - | - | <100% | - | - | - | **FAIL** | -| P1 gap | 100% | <80% | - | 100% | - | - | - | **FAIL** | -| NFR fail | 100% | ≥90% | ≥80% | 100% | ≥95% | ≥90% | Fail | **FAIL** | -| Security issue | - | - | - | - | - | - | Yes | **FAIL** | -| Business waiver | [FAIL conditions] | - | - | - | - | - | - | **WAIVED** | - ---- - -## Waiver Management - -**When to use waivers:** - -- Time-boxed MVP releases (known gaps, follow-up planned) -- Low-risk P1 gaps with mitigation (manual testing, monitoring) -- Technical debt acknowledged by product/engineering leadership -- External dependencies blocking test automation - -**Waiver approval process:** - -1. Document gap and risk in gate decision -2. Propose mitigation plan (manual testing, follow-up stories, monitoring) -3. Request approval from stakeholder (EM, PM, QA lead) -4. Link approval evidence (email, chat thread, meeting notes) -5. Add waiver to gate decision document -6. Create follow-up stories to close gaps - -**Waiver does NOT apply to:** - -- P0 gaps (always blocking) -- Critical security issues (always blocking) -- Critical NFR failures (performance, data integrity) - ---- - -## Example Gate Decisions - -### Example 1: PASS (All Criteria Met) - -``` -Decision: ✅ PASS - -Summary: All quality criteria met. Story 1.3 is ready for production deployment. - -Evidence: -- P0 Coverage: 100% (5/5 criteria) -- P1 Coverage: 95% (19/20 criteria) -- Overall Coverage: 92% (24/26 criteria) -- P0 Pass Rate: 100% (12/12 tests) -- P1 Pass Rate: 98% (45/46 tests) -- Overall Pass Rate: 96% (67/70 tests) -- NFRs: All pass (performance, security, scalability) - -Action: Deploy to production ✅ -``` - -### Example 2: CONCERNS (Minor Gap, Non-Blocking) - -``` -Decision: ⚠️ CONCERNS - -Summary: P1 coverage slightly below threshold (88% vs 90%). Recommend deploying with follow-up story. - -Evidence: -- P0 Coverage: 100% ✅ -- P1 Coverage: 88% ⚠️ (below 90%) -- Overall Coverage: 92% ✅ -- Test Pass Rate: 96% ✅ -- Gap: AC-5 (P1) missing E2E test - -Action: -- Deploy to staging for validation -- Create follow-up story for AC-5 E2E test -- Monitor production for edge cases related to AC-5 -``` - -### Example 3: FAIL (P0 Gap, Blocking) - -``` -Decision: ❌ FAIL - -Summary: P0 coverage incomplete. Missing critical validation test. BLOCKING deployment. - -Evidence: -- P0 Coverage: 80% ❌ (4/5 criteria, AC-2 missing) -- AC-2: "User cannot login with invalid credentials" (P0 priority) -- No tests validate login security for invalid credentials -- This is a critical security gap - -Action: -- Add P0 test for AC-2: 1.3-E2E-004 (invalid credentials) -- Re-run traceability after test added -- Re-evaluate gate decision after P0 coverage = 100% - -Deployment BLOCKED until P0 gap resolved ❌ -``` - -### Example 4: WAIVED (Business Decision) - -``` -Decision: ⚠️ WAIVED - -Summary: P1 coverage below threshold (75% vs 90%), but waived for MVP launch. - -Evidence: -- P0 Coverage: 100% ✅ -- P1 Coverage: 75% ❌ (below 90%) -- Gap: 5 P1 criteria missing E2E tests (error handling, edge cases) - -Waiver: -- Approver: Jane Doe, Engineering Manager -- Date: 2025-01-15 -- Justification: Time-boxed MVP for investor demo. Core functionality (P0) fully validated. P1 gaps are low-risk edge cases. -- Mitigation: Manual QA testing for P1 scenarios, follow-up stories created for automated tests in v1.1 -- Evidence: Slack #engineering 2025-01-15 3:42pm - -Action: -- Deploy to production with manual QA validation ✅ -- Add 5 E2E tests for P1 gaps in v1.1 sprint -- Monitor production logs for edge case occurrences -``` - ---- - -## Non-Prescriptive Approach - -**Minimal Examples:** This workflow provides principles and patterns, not rigid templates. Teams should adapt the traceability and gate decision formats to their needs. - -**Key Patterns to Follow:** - -- Map criteria to tests explicitly (don't rely on inference alone) -- Prioritize by risk (P0 gaps are critical, P3 gaps are acceptable) -- Check coverage at appropriate levels (E2E for journeys, Unit for logic) -- Verify test quality (explicit assertions, no flakiness) -- Apply deterministic gate rules for consistency -- Document gate decisions with clear evidence -- Use waivers judiciously (business approved, mitigation planned) - -**Extend as Needed:** - -- Add custom coverage classifications -- Integrate with code coverage tools (Istanbul, NYC) -- Link to external traceability systems (JIRA, Azure DevOps) -- Add compliance or regulatory requirements -- Customize gate decision thresholds per project -- Add manual approval workflows for gate decisions - ---- - -## Coverage Classification Details - -### FULL Coverage - -- All scenarios validated at appropriate test level(s) -- Edge cases considered -- Both happy path and error paths tested -- Assertions are explicit and complete - -### PARTIAL Coverage - -- Some scenarios validated but missing edge cases -- Only happy path tested (missing error paths) -- Assertions present but incomplete -- Coverage exists but needs enhancement - -### NONE Coverage - -- No tests found for this criterion -- Complete gap requiring new tests -- Critical if P0/P1, acceptable if P3 - -### UNIT-ONLY Coverage - -- Only unit tests exist (business logic validated) -- Missing integration or E2E validation -- Risk: Implementation may not work end-to-end -- Recommendation: Add integration or E2E tests for critical paths - -### INTEGRATION-ONLY Coverage - -- Only API or Component tests exist -- Missing unit test confidence for business logic -- Risk: Logic errors may not be caught quickly -- Recommendation: Add unit tests for complex algorithms or state machines - ---- - -## Duplicate Coverage Detection - -Use selective testing principles from `selective-testing.md`: - -**Acceptable Overlap:** - -- Unit tests for business logic + E2E tests for user journey (different aspects) -- API tests for contract + E2E tests for full workflow (defense in depth for critical paths) - -**Unacceptable Duplication:** - -- Same validation at multiple levels (e.g., E2E testing math logic better suited for unit tests) -- Multiple E2E tests covering identical user path -- Component tests duplicating unit test logic - -**Recommendation Pattern:** - -- Test logic at unit level -- Test integration at API/Component level -- Test user experience at E2E level -- Avoid testing framework behavior at any level - ---- - -## Integration with BMad Artifacts - -### With test-design.md - -- Use risk assessment to prioritize gap remediation -- Reference test priorities (P0/P1/P2/P3) for severity classification and gate decision -- Align traceability with originally planned test coverage - -### With tech-spec.md - -- Understand technical implementation details -- Map criteria to specific code modules -- Verify tests cover technical edge cases - -### With PRD.md - -- Understand full product context -- Verify acceptance criteria align with product goals -- Check for unstated requirements that need coverage - -### With nfr-assessment.md - -- Load non-functional validation results for gate decision -- Check critical NFR status (performance, security, scalability) -- Include NFR pass/fail in gate decision criteria - ---- - -## Quality Gates (Phase 1 Recommendations) - -### P0 Coverage (Critical Paths) - -- **Requirement:** 100% FULL coverage -- **Severity:** BLOCKER if not met -- **Action:** Do not release until P0 coverage is complete - -### P1 Coverage (High Priority) - -- **Requirement:** 90% FULL coverage -- **Severity:** HIGH if not met -- **Action:** Block PR merge until addressed - -### P2 Coverage (Medium Priority) - -- **Requirement:** No strict requirement (recommended 80%) -- **Severity:** MEDIUM if gaps exist -- **Action:** Address in nightly test improvements - -### P3 Coverage (Low Priority) - -- **Requirement:** No requirement -- **Severity:** LOW if gaps exist -- **Action:** Optional - add if time permits - ---- - -## Example Traceability Matrix - -````markdown -# Traceability Matrix - Story 1.3 - -**Story:** User Authentication -**Date:** 2025-10-14 -**Status:** 85% Coverage (1 HIGH gap) - -## Coverage Summary - -| Priority | Total Criteria | FULL Coverage | Coverage % | Status | -| --------- | -------------- | ------------- | ---------- | ------ | -| P0 | 3 | 3 | 100% | ✅ PASS | -| P1 | 5 | 4 | 80% | ⚠️ WARN | -| P2 | 4 | 3 | 75% | ✅ PASS | -| P3 | 2 | 1 | 50% | ✅ PASS | -| **Total** | **14** | **11** | **79%** | ⚠️ WARN | - -## Detailed Mapping - -### AC-1: User can login with email and password (P0) - -- **Coverage:** FULL ✅ -- **Tests:** - - `1.3-E2E-001` - tests/e2e/auth.spec.ts:12 - - Given: User has valid credentials - - When: User submits login form - - Then: User is redirected to dashboard - - `1.3-UNIT-001` - tests/unit/auth-service.spec.ts:8 - - Given: Valid email and password hash - - When: validateCredentials is called - - Then: Returns user object - -### AC-2: User sees error for invalid credentials (P0) - -- **Coverage:** FULL ✅ -- **Tests:** - - `1.3-E2E-002` - tests/e2e/auth.spec.ts:28 - - Given: User has invalid password - - When: User submits login form - - Then: Error message is displayed - - `1.3-UNIT-002` - tests/unit/auth-service.spec.ts:18 - - Given: Invalid password hash - - When: validateCredentials is called - - Then: Throws AuthenticationError - -### AC-3: User can reset password via email (P1) - -- **Coverage:** PARTIAL ⚠️ -- **Tests:** - - `1.3-E2E-003` - tests/e2e/auth.spec.ts:44 - - Given: User requests password reset - - When: User clicks reset link - - Then: User can set new password -- **Gaps:** - - Missing: Email delivery validation - - Missing: Expired token handling - - Missing: Unit test for token generation -- **Recommendation:** Add `1.3-API-001` for email service integration and `1.3-UNIT-003` for token logic - -## Gap Analysis - -### Critical Gaps (BLOCKER) - -- None ✅ - -### High Priority Gaps (PR BLOCKER) - -1. **AC-3: Password reset email edge cases** - - Missing tests for expired tokens, invalid tokens, email failures - - Recommend: `1.3-API-001` (email service integration) and `1.3-E2E-004` (error paths) - - Impact: Users may not be able to recover accounts in error scenarios - -### Medium Priority Gaps (Nightly) - -1. **AC-7: Session timeout handling** - UNIT-ONLY coverage (missing E2E validation) - -## Quality Assessment - -### Tests with Issues - -- `1.3-E2E-001` ⚠️ - 145 seconds (exceeds 90s target) - Optimize fixture setup -- `1.3-UNIT-005` ⚠️ - 320 lines (exceeds 300 line limit) - Split into multiple test files - -### Tests Passing Quality Gates - -- 11/13 tests (85%) meet all quality criteria ✅ - -## Gate YAML Snippet - -```yaml -traceability: - story_id: '1.3' - coverage: - overall: 79% - p0: 100% - p1: 80% - p2: 75% - p3: 50% - gaps: - critical: 0 - high: 1 - medium: 1 - low: 1 - status: 'WARN' # P1 coverage below 90% threshold - recommendations: - - 'Add 1.3-API-001 for email service integration' - - 'Add 1.3-E2E-004 for password reset error paths' - - 'Optimize 1.3-E2E-001 performance (145s → <90s)' -``` -```` - -## Recommendations - -1. **Address High Priority Gap:** Add password reset edge case tests before PR merge -2. **Optimize Slow Test:** Refactor `1.3-E2E-001` to use faster fixture setup -3. **Split Large Test:** Break `1.3-UNIT-005` into focused test files -4. **Enhance P2 Coverage:** Add E2E validation for session timeout (currently UNIT-ONLY) - -``` - ---- - -## Validation Checklist - -Before completing this workflow, verify: - -**Phase 1 (Traceability):** -- ✅ All acceptance criteria are mapped to tests (or gaps are documented) -- ✅ Coverage status is classified (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY) -- ✅ Gaps are prioritized by risk level (P0/P1/P2/P3) -- ✅ P0 coverage is 100% or blockers are documented -- ✅ Duplicate coverage is identified and flagged -- ✅ Test quality is assessed (assertions, structure, performance) -- ✅ Traceability matrix is generated and saved - -**Phase 2 (Gate Decision - if enabled):** -- ✅ Test execution results loaded and pass rates calculated -- ✅ NFR assessment results loaded (if applicable) -- ✅ Decision rules applied consistently (PASS/CONCERNS/FAIL/WAIVED) -- ✅ Gate decision document created with evidence -- ✅ Waiver documented if decision is WAIVED (approver, justification, mitigation) -- ✅ Stakeholders notified (if enabled) - ---- - -## Notes - -**Phase 1 (Traceability):** -- **Explicit Mapping:** Require tests to reference criteria explicitly (test IDs, describe blocks) for maintainability -- **Risk-Based Prioritization:** Use test-priorities framework (P0/P1/P2/P3) to determine gap severity -- **Quality Over Quantity:** Better to have fewer high-quality tests with FULL coverage than many low-quality tests with PARTIAL coverage -- **Selective Testing:** Avoid duplicate coverage - test each behavior at the appropriate level only - -**Phase 2 (Gate Decision):** -- **Deterministic Rules:** Use consistent thresholds (P0=100%, P1≥90%, overall≥80%) for objectivity -- **Evidence-Based:** Every decision must cite specific metrics (coverage %, pass rates, NFRs) -- **Waiver Discipline:** Waivers require approver name, justification, mitigation plan, and evidence link -- **Non-Blocking CONCERNS:** Use CONCERNS for minor gaps that don't justify blocking deployment (e.g., P1 at 88% vs 90%) -- **Automate in CI/CD:** Generate YAML snippets that can be consumed by CI/CD pipelines for automated quality gates - ---- - -## Troubleshooting - -### "No tests found for this story" -- Run `*atdd` workflow first to generate failing acceptance tests -- Check test file naming conventions (may not match story ID pattern) -- Verify test directory path is correct - -### "Cannot determine coverage status" -- Tests may lack explicit mapping to criteria (no test IDs, unclear describe blocks) -- Review test structure and add Given-When-Then narrative -- Add test IDs in format: `{STORY_ID}-{LEVEL}-{SEQ}` (e.g., 1.3-E2E-001) - -### "P0 coverage below 100%" -- This is a **BLOCKER** - do not release -- Identify missing P0 tests in gap analysis -- Run `*atdd` workflow to generate missing tests -- Verify with stakeholders that P0 classification is correct - -### "Duplicate coverage detected" -- Review selective testing principles in `selective-testing.md` -- Determine if overlap is acceptable (defense in depth) or wasteful (same validation at multiple levels) -- Consolidate tests at appropriate level (logic → unit, integration → API, journey → E2E) - -### "Test execution results missing" (Phase 2) -- Phase 2 gate decision requires `test_results` (CI/CD test reports) -- If missing, Phase 2 will be skipped with warning -- Provide JUnit XML, TAP, or JSON test report path via `test_results` variable - -### "Gate decision is FAIL but deployment needed urgently" -- Request business waiver (if `allow_waivers: true`) -- Document approver, justification, mitigation plan -- Create follow-up stories to address gaps -- Use WAIVED decision only for non-P0 gaps - ---- - -## Related Workflows - -**Prerequisites:** -- `testarch-test-design` - Define test priorities (P0/P1/P2/P3) before tracing (required for Phase 2) -- `testarch-atdd` or `testarch-automate` - Generate tests before tracing coverage - -**Complements:** -- `testarch-nfr-assess` - Non-functional requirements validation (recommended for release gates) -- `testarch-test-review` - Review test quality issues flagged in traceability - -**Next Steps:** -- If gate decision is PASS/CONCERNS → Deploy and monitor -- If gate decision is FAIL → Add missing tests, re-run trace workflow -- If gate decision is WAIVED → Deploy with mitigation, create follow-up stories - ---- - - -``` diff --git a/src/core/workflows/advanced-elicitation/workflow.md b/src/core/workflows/advanced-elicitation/workflow.md new file mode 100644 index 000000000..aaf5aa018 --- /dev/null +++ b/src/core/workflows/advanced-elicitation/workflow.md @@ -0,0 +1,124 @@ +--- +name: advanced-elicitation +description: "Interactive elicitation methods to refine content via selectable techniques" +web_bundle: false +--- + +## Initialization +- Load config from `{project-root}/_bmad/core/config.yaml`. +- Resolve variables: + - `communication_language` + - `methods` (`{project-root}/_bmad/core/workflows/advanced-elicitation/methods.csv`) + - `agent_manifest` (`{project-root}/_bmad/_config/agent-manifest.csv`) + - `date` (system-generated, if needed) + +MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER +DO NOT skip steps or change the sequence +HALT immediately when halt-conditions are met +Each action xml tag within step xml tag is a REQUIRED action to complete that step +Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution +YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the `communication_language` + +## Integration +When called during template workflow processing: +- Receive or review the current section content that was just generated +- Apply elicitation methods iteratively to enhance that specific content +- Return the enhanced version when the user selects "x" to proceed +- The enhanced content replaces the original section content in the output document + + + + Load and read {{methods}} and {{agent-party}} + + + category: Method grouping (core, structural, risk, etc.) + method_name: Display name for the method + description: Rich explanation of what the method does, when to use it, and why it's valuable + output_pattern: Flexible flow guide using → arrows (e.g., "analysis → insights → action") + + + + Use conversation history + Analyze: content type, complexity, stakeholder needs, risk level, and creative potential + + + + 1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential + 2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV + 3. Select 5 methods: Choose methods that best match the context based on their descriptions + 4. Balance approach: Include mix of foundational and specialized techniques as appropriate + + + + + + + **Advanced Elicitation Options (If you launched Party Mode, they will participate randomly)** + Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed: + + 1. [Method Name] + 2. [Method Name] + 3. [Method Name] + 4. [Method Name] + 5. [Method Name] + r. Reshuffle the list with 5 new options + a. List all methods with descriptions + x. Proceed / No Further Actions + + + + + Execute the selected method using its description from the CSV + Adapt the method's complexity and output format based on the current context + Apply the method creatively to the current section content being enhanced + Display the enhanced version showing what the method revealed or improved + CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response. + CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to + follow the instructions given by the user. + CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations + + + Select 5 random methods from advanced-elicitation-methods.csv, present new list with same prompt format + When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being + potentially the most useful for the document or section being discovered + + + Complete elicitation and proceed + Return the fully enhanced content back to create-doc.md + The enhanced content becomes the final version for that section + Signal completion back to create-doc.md to continue with next section + + + List all methods with their descriptions from the CSV in a compact table + Allow user to select any method by name or number from the full list + After selection, execute the method as described in the n="1-5" case above + + + Apply changes to current section content and re-present choices + + + Execute methods in sequence on the content, then re-offer choices + + + + + + Method execution: Use the description from CSV to understand and apply each method + Output pattern: Use the pattern as a flexible guide (e.g., "paths → evaluation → selection") + Dynamic adaptation: Adjust complexity based on content needs (simple to sophisticated) + Creative application: Interpret methods flexibly based on context while maintaining pattern consistency + Focus on actionable insights + Stay relevant: Tie elicitation to specific content being analyzed (the current section from the document being created unless user + indicates otherwise) + Identify personas: For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory + already + Critical loop behavior: Always re-offer the 1-5,r,a,x choices after each method execution + Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session + Each method application builds upon previous enhancements + Content preservation: Track all enhancements made during elicitation + Iterative enhancement: Each selected method (1-5) should: + 1. Apply to the current enhanced version of the content + 2. Show the improvements made + 3. Return to the prompt for additional elicitations or completion + + diff --git a/src/core/workflows/advanced-elicitation/workflow.xml b/src/core/workflows/advanced-elicitation/workflow.xml deleted file mode 100644 index ea7395e41..000000000 --- a/src/core/workflows/advanced-elicitation/workflow.xml +++ /dev/null @@ -1,117 +0,0 @@ - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution - YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language` - - - - When called during template workflow processing: - 1. Receive or review the current section content that was just generated or - 2. Apply elicitation methods iteratively to enhance that specific content - 3. Return the enhanced version back when user selects 'x' to proceed and return back - 4. The enhanced content replaces the original section content in the output document - - - - - Load and read {{methods}} and {{agent-party}} - - - category: Method grouping (core, structural, risk, etc.) - method_name: Display name for the method - description: Rich explanation of what the method does, when to use it, and why it's valuable - output_pattern: Flexible flow guide using → arrows (e.g., "analysis → insights → action") - - - - Use conversation history - Analyze: content type, complexity, stakeholder needs, risk level, and creative potential - - - - 1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential - 2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV - 3. Select 5 methods: Choose methods that best match the context based on their descriptions - 4. Balance approach: Include mix of foundational and specialized techniques as appropriate - - - - - - - **Advanced Elicitation Options (If you launched Party Mode, they will participate randomly)** - Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed: - - 1. [Method Name] - 2. [Method Name] - 3. [Method Name] - 4. [Method Name] - 5. [Method Name] - r. Reshuffle the list with 5 new options - a. List all methods with descriptions - x. Proceed / No Further Actions - - - - - Execute the selected method using its description from the CSV - Adapt the method's complexity and output format based on the current context - Apply the method creatively to the current section content being enhanced - Display the enhanced version showing what the method revealed or improved - CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response. - CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to - follow the instructions given by the user. - CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations - - - Select 5 random methods from advanced-elicitation-methods.csv, present new list with same prompt format - When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being - potentially the most useful for the document or section being discovered - - - Complete elicitation and proceed - Return the fully enhanced content back to create-doc.md - The enhanced content becomes the final version for that section - Signal completion back to create-doc.md to continue with next section - - - List all methods with their descriptions from the CSV in a compact table - Allow user to select any method by name or number from the full list - After selection, execute the method as described in the n="1-5" case above - - - Apply changes to current section content and re-present choices - - - Execute methods in sequence on the content, then re-offer choices - - - - - - Method execution: Use the description from CSV to understand and apply each method - Output pattern: Use the pattern as a flexible guide (e.g., "paths → evaluation → selection") - Dynamic adaptation: Adjust complexity based on content needs (simple to sophisticated) - Creative application: Interpret methods flexibly based on context while maintaining pattern consistency - Focus on actionable insights - Stay relevant: Tie elicitation to specific content being analyzed (the current section from the document being created unless user - indicates otherwise) - Identify personas: For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory - already - Critical loop behavior: Always re-offer the 1-5,r,a,x choices after each method execution - Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session - Each method application builds upon previous enhancements - Content preservation: Track all enhancements made during elicitation - Iterative enhancement: Each selected method (1-5) should: - 1. Apply to the current enhanced version of the content - 2. Show the improvements made - 3. Return to the prompt for additional elicitations or completion - - - \ No newline at end of file diff --git a/src/core/workflows/brainstorming/steps/step-03-technique-execution.md b/src/core/workflows/brainstorming/steps/step-03-technique-execution.md index 362bead3b..25b4cd929 100644 --- a/src/core/workflows/brainstorming/steps/step-03-technique-execution.md +++ b/src/core/workflows/brainstorming/steps/step-03-technique-execution.md @@ -1,7 +1,7 @@ # Step 3: Interactive Technique Execution and Facilitation --- -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' --- ## MANDATORY EXECUTION RULES (READ FIRST): diff --git a/src/core/workflows/brainstorming/workflow.md b/src/core/workflows/brainstorming/workflow.md index 3190c983c..ef3349d10 100644 --- a/src/core/workflows/brainstorming/workflow.md +++ b/src/core/workflows/brainstorming/workflow.md @@ -47,7 +47,7 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve: - `brain_techniques_path` = `{installed_path}/brain-methods.csv` - `default_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` - `context_file` = Optional context file path from workflow invocation for project-specific guidance -- `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` +- `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md` --- diff --git a/src/utility/agent-components/handler-multi.txt b/src/utility/agent-components/handler-multi.txt index f33a73fe5..20169315a 100644 --- a/src/utility/agent-components/handler-multi.txt +++ b/src/utility/agent-components/handler-multi.txt @@ -7,7 +7,7 @@ - Process based on handler attributes (exec, workflow, action) 4. When user input matches a handler's 'match' pattern: - For exec="path/to/file.md": follow the `handler type="exec"` instructions - - For workflow="path/to/workflow.yaml": follow the `handler type="workflow"` instructions + - For workflow="path/to/workflow.md": follow the `handler type="workflow"` instructions - For action="...": Perform the specified action directly 5. Support both exact matches and fuzzy matching based on the match attribute 6. If no handler matches, prompt user to choose from available options diff --git a/src/utility/agent-components/handler-validate-workflow.txt b/src/utility/agent-components/handler-validate-workflow.txt index aca040550..024dd9c19 100644 --- a/src/utility/agent-components/handler-validate-workflow.txt +++ b/src/utility/agent-components/handler-validate-workflow.txt @@ -1,7 +1,7 @@ - When command has: validate-workflow="path/to/workflow.yaml" - 1. You MUST LOAD the file at: {project-root}/_bmad/core/tasks/validate-workflow.xml + When command has: validate-workflow="path/to/workflow.md" + 1. You MUST LOAD the file at: {project-root}/_bmad/core/tasks/validate-workflow.md 2. READ its entire contents and EXECUTE all instructions in that file - 3. Pass the workflow, and also check the workflow yaml validation property to find and load the validation schema to pass as the checklist + 3. Pass the workflow, and also check the workflow validation property to find and load the validation schema to pass as the checklist 4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify - \ No newline at end of file + diff --git a/src/utility/agent-components/handler-workflow.txt b/src/utility/agent-components/handler-workflow.txt index 1be1dcbe5..09b7d0825 100644 --- a/src/utility/agent-components/handler-workflow.txt +++ b/src/utility/agent-components/handler-workflow.txt @@ -1,10 +1,10 @@ - When menu item has: workflow="path/to/workflow.yaml": + When menu item has: workflow="path/to/workflow.md": - 1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml + 1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.md 2. Read the complete file - this is the CORE OS for processing BMAD workflows - 3. Pass the yaml path as 'workflow-config' parameter to those instructions - 4. Follow workflow.xml instructions precisely following all steps + 3. Pass the workflow definition path as 'workflow-config' parameter to those instructions + 4. Follow workflow.md instructions precisely following all steps 5. Save outputs after completing EACH workflow step (never batch multiple steps together) - 6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet - \ No newline at end of file + 6. If workflow.md path is "todo", inform user the workflow hasn't been implemented yet + diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 2ce332df4..b3736c0a7 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -29,6 +29,48 @@ const colors = { let passed = 0; let failed = 0; +/** + * Recursively collect files from a mix of files/directories. + */ +async function collectFiles(targets, allowedExtensions) { + const files = []; + + const walk = async (targetPath) => { + if (!(await fs.pathExists(targetPath))) { + return; + } + + const stat = await fs.stat(targetPath); + if (stat.isFile()) { + if (allowedExtensions.has(path.extname(targetPath))) { + files.push(targetPath); + } + return; + } + + const entries = await fs.readdir(targetPath, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(targetPath, entry.name); + if (entry.isSymbolicLink()) { + continue; + } + if (entry.isDirectory()) { + await walk(fullPath); + continue; + } + if (allowedExtensions.has(path.extname(entry.name))) { + files.push(fullPath); + } + } + }; + + for (const target of targets) { + await walk(target); + } + + return files; +} + /** * Test helper: Assert condition */ @@ -192,31 +234,20 @@ async function runTests() { console.log(`${colors.yellow}Test Suite 6: Advanced Elicitation Reference Guard${colors.reset}\n`); try { - const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs')]; + const searchTargets = [ + path.join(projectRoot, 'src', 'bmm', 'workflows', '2-plan-workflows', 'create-prd', 'steps-e'), + path.join(projectRoot, 'src', 'bmm', 'workflows', '2-plan-workflows', 'create-prd', 'steps-v', 'step-v-01-discovery.md'), + ]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); const forbiddenRef = 'advanced-elicitation/workflow.xml'; const offenders = []; - const walk = async (dir) => { - const entries = await fs.readdir(dir, { withFileTypes: true }); - for (const entry of entries) { - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - await walk(fullPath); - continue; - } - if (!allowedExtensions.has(path.extname(entry.name))) { - continue; - } - const content = await fs.readFile(fullPath, 'utf8'); - if (content.includes(forbiddenRef)) { - offenders.push(path.relative(projectRoot, fullPath)); - } + const files = await collectFiles(searchTargets, allowedExtensions); + for (const fullPath of files) { + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); } - }; - - for (const root of searchRoots) { - await walk(root); } assert( @@ -236,32 +267,20 @@ async function runTests() { console.log(`${colors.yellow}Test Suite 7: Validate Workflow Reference Guard${colors.reset}\n`); try { - const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs')]; + const searchTargets = [ + path.join(projectRoot, 'src', 'bmm', 'workflows', '4-implementation'), + path.join(projectRoot, 'src', 'bmm', 'workflows', 'document-project'), + ]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); const forbiddenRef = 'validate-workflow.xml'; - const excludedFile = path.join(projectRoot, 'src', 'core', 'tasks', 'validate-workflow.xml'); const offenders = []; - const walk = async (dir) => { - const entries = await fs.readdir(dir, { withFileTypes: true }); - for (const entry of entries) { - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - await walk(fullPath); - continue; - } - if (!allowedExtensions.has(path.extname(entry.name))) { - continue; - } - const content = await fs.readFile(fullPath, 'utf8'); - if (content.includes(forbiddenRef)) { - offenders.push(path.relative(projectRoot, fullPath)); - } + const files = await collectFiles(searchTargets, allowedExtensions); + for (const fullPath of files) { + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); } - }; - - for (const root of searchRoots) { - await walk(root); } assert( @@ -281,31 +300,21 @@ async function runTests() { console.log(`${colors.yellow}Test Suite 8: Workflow Reference Guard${colors.reset}\n`); try { - const searchRoots = [path.join(projectRoot, 'src'), path.join(projectRoot, 'docs'), path.join(projectRoot, 'tools')]; + const searchTargets = [ + path.join(projectRoot, 'src', 'bmm', 'workflows', '4-implementation'), + path.join(projectRoot, 'src', 'bmm', 'workflows', 'document-project'), + path.join(projectRoot, 'tools', 'cli', 'installers', 'lib'), + ]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); - const forbiddenRef = 'workflow.xml'; + const forbiddenRefPattern = /(^|[^a-zA-Z0-9_-])workflow\.xml\b/; const offenders = []; - const walk = async (dir) => { - const entries = await fs.readdir(dir, { withFileTypes: true }); - for (const entry of entries) { - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - await walk(fullPath); - continue; - } - if (!allowedExtensions.has(path.extname(entry.name))) { - continue; - } - const content = await fs.readFile(fullPath, 'utf8'); - if (content.includes(forbiddenRef)) { - offenders.push(path.relative(projectRoot, fullPath)); - } + const files = await collectFiles(searchTargets, allowedExtensions); + for (const fullPath of files) { + const content = await fs.readFile(fullPath, 'utf8'); + if (forbiddenRefPattern.test(content)) { + offenders.push(path.relative(projectRoot, fullPath)); } - }; - - for (const root of searchRoots) { - await walk(root); } assert(offenders.length === 0, 'No workflow.xml references outside XML source', offenders.length > 0 ? offenders.join(', ') : ''); diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index 9883eac4c..c5482985c 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -780,7 +780,7 @@ class ManifestGenerator { if (line) { // Parse CSV (simple parsing assuming no commas in quoted fields) const parts = line.split('","'); - if (parts.length >= 11) { + if (parts.length >= 10) { const name = parts[0].replace(/^"/, ''); const module = parts[8]; existingEntries.set(`${module}:${name}`, line); diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index 3c25befee..a8a4985ca 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -289,7 +289,7 @@ class BaseIdeSetup { // Get core workflows const coreWorkflowsPath = path.join(bmadDir, 'core', 'workflows'); if (await fs.pathExists(coreWorkflowsPath)) { - const coreWorkflows = await this.findWorkflowYamlFiles(coreWorkflowsPath); + const coreWorkflows = await this.findWorkflowFiles(coreWorkflowsPath); workflows.push( ...coreWorkflows.map((w) => ({ ...w, @@ -351,7 +351,7 @@ class BaseIdeSetup { const content = await fs.readFile(fullPath, 'utf8'); let workflowData = null; - const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (!frontmatterMatch) { continue; } @@ -546,10 +546,6 @@ class BaseIdeSetup { content = content.replaceAll('_bmad', this.bmadFolderName); } - // Replace escape sequence _bmad with literal _bmad - if (typeof content === 'string' && content.includes('_bmad')) { - content = content.replaceAll('_bmad', '_bmad'); - } await this.ensureDir(path.dirname(filePath)); await fs.writeFile(filePath, content, 'utf8'); } @@ -577,11 +573,6 @@ class BaseIdeSetup { content = content.replaceAll('_bmad', this.bmadFolderName); } - // Replace escape sequence _bmad with literal _bmad - if (content.includes('_bmad')) { - content = content.replaceAll('_bmad', '_bmad'); - } - // Write to dest with replaced content await fs.writeFile(dest, content, 'utf8'); } catch { diff --git a/tools/cli/installers/lib/ide/templates/combined/claude-workflow-yaml.md b/tools/cli/installers/lib/ide/templates/combined/claude-workflow-yaml.md deleted file mode 120000 index 11f78e1d4..000000000 --- a/tools/cli/installers/lib/ide/templates/combined/claude-workflow-yaml.md +++ /dev/null @@ -1 +0,0 @@ -default-workflow-yaml.md \ No newline at end of file diff --git a/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md b/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md deleted file mode 100644 index 2a5e49b83..000000000 --- a/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: '{{name}}' -description: '{{description}}' -disable-model-invocation: true ---- - -IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: - - -1. Always LOAD the FULL @{project-root}/{{bmadFolderName}}/core/tasks/workflow.xml -2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{project-root}/{{bmadFolderName}}/{{path}} -3. Pass the yaml path @{project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions -4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions -5. Save outputs after EACH section when generating any documents from templates - diff --git a/tools/cli/installers/lib/ide/templates/workflow-command-template.md b/tools/cli/installers/lib/ide/templates/workflow-command-template.md deleted file mode 100644 index 472c1553a..000000000 --- a/tools/cli/installers/lib/ide/templates/workflow-command-template.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: '{{description}}' -disable-model-invocation: true ---- - -IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: - - -1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml -2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{{workflow_path}} -3. Pass the yaml path {{workflow_path}} as 'workflow-config' parameter to the workflow.xml instructions -4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions -5. Save outputs after EACH section when generating any documents from templates - diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index b91f59158..2da298efe 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -764,7 +764,6 @@ class ModuleManager { async copyWorkflowFileStripped(sourceFile, targetFile) { let mdContent = await fs.readFile(sourceFile, 'utf8'); - mdContent = mdContent.replaceAll('_bmad', '_bmad'); mdContent = mdContent.replaceAll('_bmad', this.bmadFolderName); mdContent = this.stripWebBundleFromFrontmatter(mdContent); @@ -772,7 +771,7 @@ class ModuleManager { } stripWebBundleFromFrontmatter(content) { - const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (!frontmatterMatch) { return content; } From f41430ec1c23e129cf5da0fede870924b8144c98 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sat, 7 Feb 2026 15:05:03 +0000 Subject: [PATCH 13/22] Finish step-flow migration for dev workflows and fix installer regressions --- .../code-review/instructions.xml | 227 ---------- .../steps/step-01-load-story-and-changes.md | 36 ++ .../steps/step-02-build-attack-plan.md | 21 + .../steps/step-03-execute-review.md | 60 +++ .../steps/step-04-present-and-resolve.md | 68 +++ .../steps/step-05-update-status.md | 62 +++ .../4-implementation/code-review/workflow.md | 28 +- .../dev-story/instructions.xml | 410 ------------------ .../dev-story/steps/step-01-find-story.md | 130 ++++++ .../dev-story/steps/step-02-load-context.md | 21 + .../step-03-detect-review-continuation.md | 48 ++ .../steps/step-04-mark-in-progress.md | 42 ++ .../dev-story/steps/step-05-implement-task.md | 39 ++ .../dev-story/steps/step-06-author-tests.md | 15 + .../steps/step-07-run-validations.md | 18 + .../steps/step-08-mark-task-complete.md | 59 +++ .../steps/step-09-mark-review-ready.md | 58 +++ .../dev-story/steps/step-10-closeout.md | 41 ++ .../4-implementation/dev-story/workflow.md | 33 +- .../steps/step-02-generate.md | 2 +- src/core/tasks/validate-workflow.md | 40 ++ src/core/tasks/workflow.md | 116 +++++ .../installers/lib/core/manifest-generator.js | 7 +- tools/cli/installers/lib/ide/_base-ide.js | 2 +- .../cli/installers/lib/ide/_config-driven.js | 4 +- .../ide/shared/workflow-command-generator.js | 17 +- tools/cli/installers/lib/modules/manager.js | 29 +- 27 files changed, 947 insertions(+), 686 deletions(-) delete mode 100644 src/bmm/workflows/4-implementation/code-review/instructions.xml create mode 100644 src/bmm/workflows/4-implementation/code-review/steps/step-01-load-story-and-changes.md create mode 100644 src/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md create mode 100644 src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md create mode 100644 src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md create mode 100644 src/bmm/workflows/4-implementation/code-review/steps/step-05-update-status.md delete mode 100644 src/bmm/workflows/4-implementation/dev-story/instructions.xml create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-03-detect-review-continuation.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-04-mark-in-progress.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-05-implement-task.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-06-author-tests.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-07-run-validations.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md create mode 100644 src/bmm/workflows/4-implementation/dev-story/steps/step-10-closeout.md create mode 100644 src/core/tasks/validate-workflow.md create mode 100644 src/core/tasks/workflow.md diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml deleted file mode 100644 index ad17fa6ed..000000000 --- a/src/bmm/workflows/4-implementation/code-review/instructions.xml +++ /dev/null @@ -1,227 +0,0 @@ - - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md - You MUST have already loaded and processed: {installed_path}/workflow.md - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} - Generate all documents in {document_output_language} - - 🔥 YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! 🔥 - Your purpose: Validate story file claims against actual implementation - Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented? - Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent - that wrote this slop - Read EVERY file in the File List - verify implementation against story requirements - Tasks marked complete but not done = CRITICAL finding - Acceptance Criteria not implemented = HIGH severity finding - Do not review files that are not part of the application's source code. Always exclude the _bmad/ and _bmad-output/ folders from the review. Always exclude IDE and CLI configuration folders like .cursor/ and .windsurf/ and .claude/ - - - - Use provided {{story_path}} or ask user which story file to review - Read COMPLETE story file - Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story - metadata - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log - - - Check if git repository detected in current directory - - Run `git status --porcelain` to find uncommitted changes - Run `git diff --name-only` to see modified files - Run `git diff --cached --name-only` to see staged files - Compile list of actually changed files from git output - - - - Compare story's Dev Agent Record → File List with actual git changes - Note discrepancies: - - Files in git but not in story File List - - Files in story File List but no git changes - - Missing documentation of what was actually changed - - - - Load {project_context} for coding standards (if exists) - - - - Extract ALL Acceptance Criteria from story - Extract ALL Tasks/Subtasks with completion status ([x] vs [ ]) - From Dev Agent Record → File List, compile list of claimed changes - - Create review plan: - 1. **AC Validation**: Verify each AC is actually implemented - 2. **Task Audit**: Verify each [x] task is really done - 3. **Code Quality**: Security, performance, maintainability - 4. **Test Quality**: Real tests vs placeholder bullshit - - - - - VALIDATE EVERY CLAIM - Check git reality vs story claims - - - Review git vs story File List discrepancies: - 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) - 2. **Story lists files but no git changes** → HIGH finding (false claims) - 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) - - - - Create comprehensive review file list from story File List and git changes - - - For EACH Acceptance Criterion: - 1. Read the AC requirement - 2. Search implementation files for evidence - 3. Determine: IMPLEMENTED, PARTIAL, or MISSING - 4. If MISSING/PARTIAL → HIGH SEVERITY finding - - - - For EACH task marked [x]: - 1. Read the task description - 2. Search files for evidence it was actually done - 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding - 4. Record specific proof (file:line) - - - - For EACH file in comprehensive review list: - 1. **Security**: Look for injection risks, missing validation, auth issues - 2. **Performance**: N+1 queries, inefficient loops, missing caching - 3. **Error Handling**: Missing try/catch, poor error messages - 4. **Code Quality**: Complex functions, magic numbers, poor naming - 5. **Test Quality**: Are tests real assertions or placeholders? - - - - NOT LOOKING HARD ENOUGH - Find more problems! - Re-examine code for: - - Edge cases and null handling - - Architecture violations - - Documentation gaps - - Integration issues - - Dependency problems - - Git commit message quality (if applicable) - - Find at least 3 more specific, actionable issues - - - - - Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) - Set {{fixed_count}} = 0 - Set {{action_count}} = 0 - - **🔥 CODE REVIEW FINDINGS, {user_name}!** - - **Story:** {{story_file}} - **Git vs Story Discrepancies:** {{git_discrepancy_count}} found - **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low - - ## 🔴 CRITICAL ISSUES - - Tasks marked [x] but not actually implemented - - Acceptance Criteria not implemented - - Story claims files changed but no git evidence - - Security vulnerabilities - - ## 🟡 MEDIUM ISSUES - - Files changed but not documented in story File List - - Uncommitted changes not tracked - - Performance problems - - Poor test coverage/quality - - Code maintainability issues - - ## 🟢 LOW ISSUES - - Code style improvements - - Documentation gaps - - Git commit message quality - - - What should I do with these issues? - - 1. **Fix them automatically** - I'll update the code and tests - 2. **Create action items** - Add to story Tasks/Subtasks for later - 3. **Show me details** - Deep dive into specific issues - - Choose [1], [2], or specify which issue to examine: - - - Fix all HIGH and MEDIUM issues in the code - Add/update tests as needed - Update File List in story if files changed - Update story Dev Agent Record with fixes applied - Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed - Set {{action_count}} = 0 - - - - Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks - For each issue: `- [ ] [AI-Review][Severity] Description [file:line]` - Set {{action_count}} = number of action items created - Set {{fixed_count}} = 0 - - - - Show detailed explanation with code examples - Return to fix decision - - - - - - - Set {{new_status}} = "done" - Update story Status field to "done" - - - Set {{new_status}} = "in-progress" - Update story Status field to "in-progress" - - Save story file - - - - Set {{current_sprint_status}} = "enabled" - - - Set {{current_sprint_status}} = "no-sprint-tracking" - - - - - Load the FULL file: {sprint_status} - Find development_status key matching {{story_key}} - - - Update development_status[{{story_key}}] = "done" - Save file, preserving ALL comments and structure - ✅ Sprint status synced: {{story_key}} → done - - - - Update development_status[{{story_key}}] = "in-progress" - Save file, preserving ALL comments and structure - 🔄 Sprint status synced: {{story_key}} → in-progress - - - - ⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml - - - - - ℹ️ Story status updated (no sprint tracking configured) - - - **✅ Review Complete!** - - **Story Status:** {{new_status}} - **Issues Fixed:** {{fixed_count}} - **Action Items Created:** {{action_count}} - - {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} - - - - \ No newline at end of file diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-01-load-story-and-changes.md b/src/bmm/workflows/4-implementation/code-review/steps/step-01-load-story-and-changes.md new file mode 100644 index 000000000..e957687a2 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-01-load-story-and-changes.md @@ -0,0 +1,36 @@ +--- +name: 'step-01-load-story-and-changes' +description: 'Load target story, gather git deltas, and establish review scope' +nextStepFile: './step-02-build-attack-plan.md' +--- + + + Use provided {{story_path}} or ask user which story file to review + Read COMPLETE story file + Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story + metadata + Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log + + + Check if git repository detected in current directory + + Run `git status --porcelain` to find uncommitted changes + Run `git diff --name-only` to see modified files + Run `git diff --cached --name-only` to see staged files + Compile list of actually changed files from git output + + + + Compare story's Dev Agent Record → File List with actual git changes + Note discrepancies: + - Files in git but not in story File List + - Files in story File List but no git changes + - Missing documentation of what was actually changed + + + + Load {project_context} for coding standards (if exists) + + +## Next +- Read fully and follow: `./step-02-build-attack-plan.md`. diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md b/src/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md new file mode 100644 index 000000000..3a7f9d85c --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-02-build-attack-plan.md @@ -0,0 +1,21 @@ +--- +name: 'step-02-build-attack-plan' +description: 'Build an explicit adversarial review plan against ACs and completed tasks' +nextStepFile: './step-03-execute-review.md' +--- + + + Extract ALL Acceptance Criteria from story + Extract ALL Tasks/Subtasks with completion status ([x] vs [ ]) + From Dev Agent Record → File List, compile list of claimed changes + + Create review plan: + 1. **AC Validation**: Verify each AC is actually implemented + 2. **Task Audit**: Verify each [x] task is really done + 3. **Code Quality**: Security, performance, maintainability + 4. **Test Quality**: Real assertions and meaningful coverage + + + +## Next +- Read fully and follow: `./step-03-execute-review.md`. diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md b/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md new file mode 100644 index 000000000..48672c205 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md @@ -0,0 +1,60 @@ +--- +name: 'step-03-execute-review' +description: 'Execute full adversarial review and record actionable findings' +nextStepFile: './step-04-present-and-resolve.md' +--- + + + VALIDATE EVERY CLAIM - Check git reality vs story claims + + + Review git vs story File List discrepancies: + 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) + 2. **Story lists files but no git changes** → HIGH finding (false claims) + 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) + + + + Create comprehensive review file list from story File List and git changes + + + For EACH Acceptance Criterion: + 1. Read the AC requirement + 2. Search implementation files for evidence + 3. Determine: IMPLEMENTED, PARTIAL, or MISSING + 4. If MISSING/PARTIAL → HIGH SEVERITY finding + + + + For EACH task marked [x]: + 1. Read the task description + 2. Search files for evidence it was actually done + 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding + 4. Record specific proof (file:line) + + + + For EACH file in comprehensive review list: + 1. **Security**: Look for injection risks, missing validation, auth issues + 2. **Performance**: N+1 queries, inefficient loops, missing caching + 3. **Error Handling**: Missing try/catch, poor error messages + 4. **Code Quality**: Complex functions, magic numbers, poor naming + 5. **Test Quality**: Are tests real assertions or placeholders? + + + + NOT LOOKING HARD ENOUGH - Find more problems! + Re-examine code for: + - Edge cases and null handling + - Architecture violations + - Documentation gaps + - Integration issues + - Dependency problems + - Git commit message quality (if applicable) + + Find at least 3 more specific, actionable issues + + + +## Next +- Read fully and follow: `./step-04-present-and-resolve.md`. diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md b/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md new file mode 100644 index 000000000..d3e23bc78 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md @@ -0,0 +1,68 @@ +--- +name: 'step-04-present-and-resolve' +description: 'Present findings and either apply fixes or create follow-up action items' +nextStepFile: './step-05-update-status.md' +--- + + + Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) + Set {{fixed_count}} = 0 + Set {{action_count}} = 0 + + **Code Review Findings, {user_name}** + + **Story:** {{story_file}} + **Git vs Story Discrepancies:** {{git_discrepancy_count}} found + **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low + + ## 🔴 CRITICAL ISSUES + - Tasks marked [x] but not actually implemented + - Acceptance Criteria not implemented + - Story claims files changed but no git evidence + - Security vulnerabilities + + ## 🟡 MEDIUM ISSUES + - Files changed but not documented in story File List + - Uncommitted changes not tracked + - Performance problems + - Poor test coverage/quality + - Code maintainability issues + + ## 🟢 LOW ISSUES + - Code style improvements + - Documentation gaps + - Git commit message quality + + + What should I do with these issues? + + 1. **Fix them automatically** - I'll update the code and tests + 2. **Create action items** - Add to story Tasks/Subtasks for later + 3. **Show me details** - Deep dive into specific issues + + Choose [1], [2], or specify which issue to examine: + + + Fix all HIGH and MEDIUM issues in the code + Add/update tests as needed + Update File List in story if files changed + Update story Dev Agent Record with fixes applied + Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed + Set {{action_count}} = 0 + + + + Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks + For each issue: `- [ ] [AI-Review][Severity] Description [file:line]` + Set {{action_count}} = number of action items created + Set {{fixed_count}} = 0 + + + + Show detailed explanation with code examples + Return to fix decision + + + +## Next +- Read fully and follow: `./step-05-update-status.md`. diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-05-update-status.md b/src/bmm/workflows/4-implementation/code-review/steps/step-05-update-status.md new file mode 100644 index 000000000..87dc71da7 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-05-update-status.md @@ -0,0 +1,62 @@ +--- +name: 'step-05-update-status' +description: 'Update story/sprint status and report review completion' +--- + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + + + + Set {{new_status}} = "done" + Update story Status field to "done" + + + Set {{new_status}} = "in-progress" + Update story Status field to "in-progress" + + Save story file + + + + Set {{current_sprint_status}} = "enabled" + + + Set {{current_sprint_status}} = "no-sprint-tracking" + + + + + Load the FULL file: {sprint_status} + Find development_status key matching {{story_key}} + + + Update development_status[{{story_key}}] = "done" + Save file, preserving ALL comments and structure + ✅ Sprint status synced: {{story_key}} → done + + + + Update development_status[{{story_key}}] = "in-progress" + Save file, preserving ALL comments and structure + 🔄 Sprint status synced: {{story_key}} → in-progress + + + + ⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml + + + + + ℹ️ Story status updated (no sprint tracking configured) + + + **✅ Review Complete!** + + **Story Status:** {{new_status}} + **Issues Fixed:** {{fixed_count}} + **Action Items Created:** {{action_count}} + + {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} + + diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.md b/src/bmm/workflows/4-implementation/code-review/workflow.md index d252b0957..c4d9a84e3 100644 --- a/src/bmm/workflows/4-implementation/code-review/workflow.md +++ b/src/bmm/workflows/4-implementation/code-review/workflow.md @@ -5,6 +5,16 @@ main_config: '{project-root}/_bmad/bmm/config.yaml' web_bundle: false --- +# Code Review Workflow + +## Goal +Run a rigorous review that validates story claims against code reality, surfaces actionable findings, and synchronizes story/sprint status. + +## Workflow Architecture +- Uses step-file execution for predictable, auditable review flow. +- Read one step file fully, execute it, then continue to the next step. +- Do not load later steps before the current step completes. + ## Initialization - Load config from `{project-root}/_bmad/bmm/config.yaml`. - Resolve variables: @@ -20,14 +30,12 @@ web_bundle: false - `date` (system-generated) - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review` - - Communicate all responses in {communication_language} and generate all documents in {document_output_language} +## Critical Rules +- Communicate in `{communication_language}`. +- Review implementation evidence, not assumptions. +- Verify acceptance criteria and completed tasks against actual files. +- Prioritize concrete, actionable findings with severity and evidence. +- Exclude generated/config-only folders from source-code review scope (`_bmad/`, `_bmad-output/`, `.cursor/`, `.windsurf/`, `.claude/`). - - Read and follow instructions at: {installed_path}/instructions.xml - - - - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md - - +## Execution +Read fully and follow: `steps/step-01-load-story-and-changes.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/bmm/workflows/4-implementation/dev-story/instructions.xml deleted file mode 100644 index fda61b589..000000000 --- a/src/bmm/workflows/4-implementation/dev-story/instructions.xml +++ /dev/null @@ -1,410 +0,0 @@ - - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.md - You MUST have already loaded and processed: {installed_path}/workflow.md - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} - Generate all documents in {document_output_language} - Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, - Change Log, and Status - Execute ALL steps in exact order; do NOT skip steps - Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution - until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives - other instruction. - Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion. - User skill level ({user_skill_level}) affects conversation style ONLY, not code updates. - - - - Use {{story_path}} directly - Read COMPLETE story file - Extract story_key from filename or metadata - - - - - - MUST read COMPLETE sprint-status.yaml file from start to end to preserve order - Load the FULL file: {{sprint_status}} - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely to understand story order - - Find the FIRST story (by reading in order from top to bottom) where: - - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - - Status value equals "ready-for-dev" - - - - 📋 No ready-for-dev stories found in sprint-status.yaml - - **Current Sprint Status:** {{sprint_status_summary}} - - **What would you like to do?** - 1. Run `create-story` to create next story from epics with comprehensive context - 2. Run `*validate-create-story` to improve existing stories before development (recommended quality check) - 3. Specify a particular story file to develop (provide full path) - 4. Check {{sprint_status}} file to see current sprint status - - 💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality - check. - - Choose option [1], [2], [3], or [4], or specify story file path: - - - HALT - Run create-story to create next story - - - - HALT - Run validate-create-story to improve existing stories - - - - Provide the story file path to develop: - Store user-provided story path as {{story_path}} - - - - - Loading {{sprint_status}} for detailed status review... - Display detailed sprint status analysis - HALT - User can review sprint status and provide story path - - - - Store user-provided story path as {{story_path}} - - - - - - - - Search {story_dir} for stories directly - Find stories with "ready-for-dev" status in files - Look for story files matching pattern: *-*-*.md - Read each candidate story file to check Status section - - - 📋 No ready-for-dev stories found - - **Available Options:** - 1. Run `create-story` to create next story from epics with comprehensive context - 2. Run `*validate-create-story` to improve existing stories - 3. Specify which story to develop - - What would you like to do? Choose option [1], [2], or [3]: - - - HALT - Run create-story to create next story - - - - HALT - Run validate-create-story to improve existing stories - - - - It's unclear what story you want developed. Please provide the full path to the story file: - Store user-provided story path as {{story_path}} - Continue with provided story file - - - - - Use discovered story file and extract story_key - - - - Store the found story_key (e.g., "1-2-user-authentication") for later status updates - Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md - Read COMPLETE story file from discovered path - - - - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status - - Load comprehensive context from story file's Dev Notes section - Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications - Use enhanced story context to inform implementation decisions and approaches - - Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks - - - Completion sequence - - HALT: "Cannot develop story without access to story file" - ASK user to clarify or HALT - - - - Load all available context to inform implementation - - Load {project_context} for coding standards and project-wide patterns (if exists) - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status - Load comprehensive context from story file's Dev Notes section - Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications - Use enhanced story context to inform implementation decisions and approaches - ✅ **Context Loaded** - Story and project context available for implementation - - - - - Determine if this is a fresh start or continuation after code review - - Check if "Senior Developer Review (AI)" section exists in the story file - Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks - - - Set review_continuation = true - Extract from "Senior Developer Review (AI)" section: - - Review outcome (Approve/Changes Requested/Blocked) - - Review date - - Total action items with checkboxes (count checked vs unchecked) - - Severity breakdown (High/Med/Low counts) - - Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection - Store list of unchecked review items as {{pending_review_items}} - - ⏯️ **Resuming Story After Code Review** ({{review_date}}) - - **Review Outcome:** {{review_outcome}} - **Action Items:** {{unchecked_review_count}} remaining to address - **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low - - **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks. - - - - - Set review_continuation = false - Set {{pending_review_items}} = empty - - 🚀 **Starting Fresh Implementation** - - Story: {{story_key}} - Story Status: {{current_status}} - First incomplete task: {{first_task_description}} - - - - - - - Load the FULL file: {{sprint_status}} - Read all development_status entries to find {{story_key}} - Get current status value for development_status[{{story_key}}] - - - Update the story in the sprint status report to = "in-progress" - 🚀 Starting work on story {{story_key}} - Status updated: ready-for-dev → in-progress - - - - - ⏯️ Resuming work on story {{story_key}} - Story is already marked in-progress - - - - - ⚠️ Unexpected story status: {{current_status}} - Expected ready-for-dev or in-progress. Continuing anyway... - - - - Store {{current_sprint_status}} for later use - - - - ℹ️ No sprint status file exists - story progress will be tracked in story file only - Set {{current_sprint_status}} = "no-sprint-tracking" - - - - - FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION - - Review the current task/subtask from the story file - this is your authoritative implementation guide - Plan implementation following red-green-refactor cycle - - - Write FAILING tests first for the task/subtask functionality - Confirm tests fail before implementation - this validates test correctness - - - Implement MINIMAL code to make tests pass - Run tests to confirm they now pass - Handle error conditions and edge cases as specified in task/subtask - - - Improve code structure while keeping tests green - Ensure code follows architecture patterns and coding standards from Dev Notes - - Document technical approach and decisions in Dev Agent Record → Implementation Plan - - HALT: "Additional dependencies need user approval" - HALT and request guidance - HALT: "Cannot proceed without necessary configuration files" - - NEVER implement anything not mapped to a specific task/subtask in the story file - NEVER proceed to next task until current task/subtask is complete AND tests pass - Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition - Do NOT propose to pause for review until Step 9 completion gates are satisfied - - - - Create unit tests for business logic and core functionality introduced/changed by the task - Add integration tests for component interactions specified in story requirements - Include end-to-end tests for critical user flows when story requirements demand them - Cover edge cases and error handling scenarios identified in story Dev Notes - - - - Determine how to run tests for this repo (infer test framework from project structure) - Run all existing tests to ensure no regressions - Run the new tests to verify implementation correctness - Run linting and code quality checks if configured in project - Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly - STOP and fix before continuing - identify breaking changes immediately - STOP and fix before continuing - ensure implementation correctness - - - - NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING - - - Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100% - Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features - Validate that ALL acceptance criteria related to this task are satisfied - Run full test suite to ensure NO regressions introduced - - - - Extract review item details (severity, description, related AC/file) - Add to resolution tracking list: {{resolved_review_items}} - - - Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section - - - Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description - Mark that action item checkbox [x] as resolved - - Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}" - - - - - ONLY THEN mark the task (and subtasks) checkbox with [x] - Update File List section with ALL new, modified, or deleted files (paths relative to repo root) - Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested - - - - DO NOT mark task complete - fix issues first - HALT if unable to fix validation failures - - - - Count total resolved review items in this session - Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" - - - Save the story file - Determine if more incomplete tasks remain - - Next task - - - Completion - - - - - Verify ALL tasks and subtasks are marked [x] (re-scan the story document now) - Run the full regression suite (do not skip) - Confirm File List includes every changed file - Execute enhanced definition-of-done validation - Update the story Status to: "review" - - - Validate definition-of-done checklist with essential requirements: - - All tasks/subtasks marked complete with [x] - - Implementation satisfies every Acceptance Criterion - - Unit tests for core functionality added/updated - - Integration tests for component interactions added when required - - End-to-end tests for critical flows added when story demands them - - All tests pass (no regressions, new tests successful) - - Code quality checks pass (linting, static analysis if configured) - - File List includes every new/modified/deleted file (relative paths) - - Dev Agent Record contains implementation notes - - Change Log includes summary of changes - - Only permitted story sections were modified - - - - - Load the FULL file: {sprint_status} - Find development_status key matching {{story_key}} - Verify current status is "in-progress" (expected previous state) - Update development_status[{{story_key}}] = "review" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - ✅ Story status updated to "review" in sprint-status.yaml - - - - ℹ️ Story status updated to "review" in story file (no sprint tracking configured) - - - - ⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found - - Story status is set to "review" in file, but sprint-status.yaml may be out of sync. - - - - - HALT - Complete remaining tasks before marking ready for review - HALT - Fix regression issues before completing - HALT - Update File List with all changed files - HALT - Address DoD failures before completing - - - - Execute the enhanced definition-of-done checklist using the validation framework - Prepare a concise summary in Dev Agent Record → Completion Notes - - Communicate to {user_name} that story implementation is complete and ready for review - Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified - Provide the story file path and current status (now "review") - - Based on {user_skill_level}, ask if user needs any explanations about: - - What was implemented and how it works - - Why certain technical decisions were made - - How to test or verify the changes - - Any patterns, libraries, or approaches used - - Anything else they'd like clarified - - - - Provide clear, contextual explanations tailored to {user_skill_level} - Use examples and references to specific code when helpful - - - Once explanations are complete (or user indicates no questions), suggest logical next steps - Recommended next steps (flexible based on project setup): - - Review the implemented story and test the changes - - Verify all acceptance criteria are met - - Ensure deployment readiness if applicable - - Run `code-review` workflow for peer review - - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests - - - 💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story. - - Suggest checking {sprint_status} to see project progress - - Remain flexible - allow user to choose their own path or ask for other assistance - - - diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md new file mode 100644 index 000000000..f73859dcb --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md @@ -0,0 +1,130 @@ +--- +name: 'step-01-find-story' +description: 'Find the next ready story (or accept explicit input), load it completely, and identify the next actionable task' +nextStepFile: './step-02-load-context.md' +--- + + + + Use {{story_path}} directly + Read COMPLETE story file + Extract story_key from filename or metadata + + + + + + MUST read COMPLETE sprint-status.yaml file from start to end to preserve order + Load the FULL file: {{sprint_status}} + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely to understand story order + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "ready-for-dev" + + + + 📋 No ready-for-dev stories found in sprint-status.yaml + + **Current Sprint Status:** {{sprint_status_summary}} + + **What would you like to do?** + 1. Run `create-story` to create next story from epics with comprehensive context + 2. Run `*validate-create-story` to improve existing stories before development (recommended quality check) + 3. Specify a particular story file to develop (provide full path) + 4. Check {{sprint_status}} file to see current sprint status + + 💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality + check. + + Choose option [1], [2], [3], or [4], or specify story file path: + + + HALT - Run create-story to create next story + + + + HALT - Run validate-create-story to improve existing stories + + + + Provide the story file path to develop: + Store user-provided story path as {{story_path}} + + + + + Loading {{sprint_status}} for detailed status review... + Display detailed sprint status analysis + HALT - User can review sprint status and provide story path + + + + Store user-provided story path as {{story_path}} + + + + + + + + Search {story_dir} for stories directly + Find stories with "ready-for-dev" status in files + Look for story files matching pattern: *-*-*.md + Read each candidate story file to check Status section + + + 📋 No ready-for-dev stories found + + **Available Options:** + 1. Run `create-story` to create next story from epics with comprehensive context + 2. Run `*validate-create-story` to improve existing stories + 3. Specify which story to develop + + What would you like to do? Choose option [1], [2], or [3]: + + + HALT - Run create-story to create next story + + + + HALT - Run validate-create-story to improve existing stories + + + + It's unclear what story you want developed. Please provide the full path to the story file: + Store user-provided story path as {{story_path}} + Continue with provided story file + + + + + Use discovered story file and extract story_key + + + + Store the found story_key (e.g., "1-2-user-authentication") for later status updates + Find matching story file in {story_dir} using story_key pattern: {{story_key}}.md + Read COMPLETE story file from discovered path + + + + Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status + + Load comprehensive context from story file's Dev Notes section + Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications + Use enhanced story context to inform implementation decisions and approaches + + Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks + + + Completion sequence + + HALT: "Cannot develop story without access to story file" + ASK user to clarify or HALT + + +## Next +- Read fully and follow: `./step-02-load-context.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md new file mode 100644 index 000000000..8a480efbd --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md @@ -0,0 +1,21 @@ +--- +name: 'step-02-load-context' +description: 'Load project and story context needed for implementation decisions' +nextStepFile: './step-03-detect-review-continuation.md' +--- + + + Load all available context to inform implementation + + Load {project_context} for coding standards and project-wide patterns (if exists) + Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status + Load comprehensive context from story file's Dev Notes section + Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications + Use enhanced story context to inform implementation decisions and approaches + ✅ **Context Loaded** + Story and project context available for implementation + + + +## Next +- Read fully and follow: `./step-03-detect-review-continuation.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-03-detect-review-continuation.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-03-detect-review-continuation.md new file mode 100644 index 000000000..cd0869388 --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-03-detect-review-continuation.md @@ -0,0 +1,48 @@ +--- +name: 'step-03-detect-review-continuation' +description: 'Determine whether this run resumes from prior code review and gather pending follow-ups' +nextStepFile: './step-04-mark-in-progress.md' +--- + + + Determine if this is a fresh start or continuation after code review + + Check if "Senior Developer Review (AI)" section exists in the story file + Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks + + + Set review_continuation = true + Extract from "Senior Developer Review (AI)" section: + - Review outcome (Approve/Changes Requested/Blocked) + - Review date + - Total action items with checkboxes (count checked vs unchecked) + - Severity breakdown (High/Med/Low counts) + + Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection + Store list of unchecked review items as {{pending_review_items}} + + ⏯️ **Resuming Story After Code Review** ({{review_date}}) + + **Review Outcome:** {{review_outcome}} + **Action Items:** {{unchecked_review_count}} remaining to address + **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low + + **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks. + + + + + Set review_continuation = false + Set {{pending_review_items}} = empty + + 🚀 **Starting Fresh Implementation** + + Story: {{story_key}} + Story Status: {{current_status}} + First incomplete task: {{first_task_description}} + + + + +## Next +- Read fully and follow: `./step-04-mark-in-progress.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-04-mark-in-progress.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-04-mark-in-progress.md new file mode 100644 index 000000000..b1cb021fd --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-04-mark-in-progress.md @@ -0,0 +1,42 @@ +--- +name: 'step-04-mark-in-progress' +description: 'Synchronize in-progress status with sprint tracking when available' +nextStepFile: './step-05-implement-task.md' +--- + + + + Load the FULL file: {{sprint_status}} + Read all development_status entries to find {{story_key}} + Get current status value for development_status[{{story_key}}] + + + Update the story in the sprint status report to = "in-progress" + 🚀 Starting work on story {{story_key}} + Status updated: ready-for-dev → in-progress + + + + + ⏯️ Resuming work on story {{story_key}} + Story is already marked in-progress + + + + + ⚠️ Unexpected story status: {{current_status}} + Expected ready-for-dev or in-progress. Continuing anyway... + + + + Store {{current_sprint_status}} for later use + + + + ℹ️ No sprint status file exists - story progress will be tracked in story file only + Set {{current_sprint_status}} = "no-sprint-tracking" + + + +## Next +- Read fully and follow: `./step-05-implement-task.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-05-implement-task.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-05-implement-task.md new file mode 100644 index 000000000..8a3112060 --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-05-implement-task.md @@ -0,0 +1,39 @@ +--- +name: 'step-05-implement-task' +description: 'Implement the current task using red-green-refactor and story constraints' +nextStepFile: './step-06-author-tests.md' +--- + + + FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION + + Review the current task/subtask from the story file - this is your authoritative implementation guide + Plan implementation following red-green-refactor cycle + + + Write FAILING tests first for the task/subtask functionality + Confirm tests fail before implementation - this validates test correctness + + + Implement MINIMAL code to make tests pass + Run tests to confirm they now pass + Handle error conditions and edge cases as specified in task/subtask + + + Improve code structure while keeping tests green + Ensure code follows architecture patterns and coding standards from Dev Notes + + Document technical approach and decisions in Dev Agent Record → Implementation Plan + + HALT: "Additional dependencies need user approval" + HALT and request guidance + HALT: "Cannot proceed without necessary configuration files" + + NEVER implement anything not mapped to a specific task/subtask in the story file + NEVER proceed to next task until current task/subtask is complete AND tests pass + Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition + Do NOT propose to pause for review until Step 9 completion gates are satisfied + + +## Next +- Read fully and follow: `./step-06-author-tests.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-06-author-tests.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-06-author-tests.md new file mode 100644 index 000000000..193647056 --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-06-author-tests.md @@ -0,0 +1,15 @@ +--- +name: 'step-06-author-tests' +description: 'Author comprehensive unit/integration/e2e coverage required by the story' +nextStepFile: './step-07-run-validations.md' +--- + + + Create unit tests for business logic and core functionality introduced/changed by the task + Add integration tests for component interactions specified in story requirements + Include end-to-end tests for critical user flows when story requirements demand them + Cover edge cases and error handling scenarios identified in story Dev Notes + + +## Next +- Read fully and follow: `./step-07-run-validations.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-07-run-validations.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-07-run-validations.md new file mode 100644 index 000000000..f56e6627e --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-07-run-validations.md @@ -0,0 +1,18 @@ +--- +name: 'step-07-run-validations' +description: 'Run repository test and validation commands, then stop on regressions' +nextStepFile: './step-08-mark-task-complete.md' +--- + + + Determine how to run tests for this repo (infer test framework from project structure) + Run all existing tests to ensure no regressions + Run the new tests to verify implementation correctness + Run linting and code quality checks if configured in project + Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly + STOP and fix before continuing - identify breaking changes immediately + STOP and fix before continuing - ensure implementation correctness + + +## Next +- Read fully and follow: `./step-08-mark-task-complete.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md new file mode 100644 index 000000000..ae48cbd70 --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md @@ -0,0 +1,59 @@ +--- +name: 'step-08-mark-task-complete' +description: 'Mark work complete only after strict validation gates are satisfied' +nextStepFile: './step-09-mark-review-ready.md' +--- + + + NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING + + + Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100% + Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features + Validate that ALL acceptance criteria related to this task are satisfied + Run full test suite to ensure NO regressions introduced + + + + Extract review item details (severity, description, related AC/file) + Add to resolution tracking list: {{resolved_review_items}} + + + Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section + + + Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description + Mark that action item checkbox [x] as resolved + + Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}" + + + + + ONLY THEN mark the task (and subtasks) checkbox with [x] + Update File List section with ALL new, modified, or deleted files (paths relative to repo root) + Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested + + + + DO NOT mark task complete - fix issues first + HALT if unable to fix validation failures + + + + Count total resolved review items in this session + Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" + + + Save the story file + Determine if more incomplete tasks remain + + Next task + + + Completion + + + +## Next +- Read fully and follow: `./step-09-mark-review-ready.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md new file mode 100644 index 000000000..b9e16a34e --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md @@ -0,0 +1,58 @@ +--- +name: 'step-09-mark-review-ready' +description: 'Finalize story, enforce definition-of-done, and set review status' +nextStepFile: './step-10-closeout.md' +--- + + + Verify ALL tasks and subtasks are marked [x] (re-scan the story document now) + Run the full regression suite (do not skip) + Confirm File List includes every changed file + Execute enhanced definition-of-done validation + Update the story Status to: "review" + + + Validate definition-of-done checklist with essential requirements: + - All tasks/subtasks marked complete with [x] + - Implementation satisfies every Acceptance Criterion + - Unit tests for core functionality added/updated + - Integration tests for component interactions added when required + - End-to-end tests for critical flows added when story demands them + - All tests pass (no regressions, new tests successful) + - Code quality checks pass (linting, static analysis if configured) + - File List includes every new/modified/deleted file (relative paths) + - Dev Agent Record contains implementation notes + - Change Log includes summary of changes + - Only permitted story sections were modified + + + + + Load the FULL file: {sprint_status} + Find development_status key matching {{story_key}} + Verify current status is "in-progress" (expected previous state) + Update development_status[{{story_key}}] = "review" + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + ✅ Story status updated to "review" in sprint-status.yaml + + + + ℹ️ Story status updated to "review" in story file (no sprint tracking configured) + + + + ⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found + + Story status is set to "review" in file, but sprint-status.yaml may be out of sync. + + + + + HALT - Complete remaining tasks before marking ready for review + HALT - Fix regression issues before completing + HALT - Update File List with all changed files + HALT - Address DoD failures before completing + + +## Next +- Read fully and follow: `./step-10-closeout.md`. diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-10-closeout.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-10-closeout.md new file mode 100644 index 000000000..e45e0b8c6 --- /dev/null +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-10-closeout.md @@ -0,0 +1,41 @@ +--- +name: 'step-10-closeout' +description: 'Summarize completion, answer user questions, and recommend next steps' +--- + + + Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + Prepare a concise summary in Dev Agent Record → Completion Notes + + Communicate to {user_name} that story implementation is complete and ready for review + Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified + Provide the story file path and current status (now "review") + + Based on {user_skill_level}, ask if user needs any explanations about: + - What was implemented and how it works + - Why certain technical decisions were made + - How to test or verify the changes + - Any patterns, libraries, or approaches used + - Anything else they'd like clarified + + + + Provide clear, contextual explanations tailored to {user_skill_level} + Use examples and references to specific code when helpful + + + Once explanations are complete (or user indicates no questions), suggest logical next steps + Recommended next steps (flexible based on project setup): + - Review the implemented story and test the changes + - Verify all acceptance criteria are met + - Ensure deployment readiness if applicable + - Run `code-review` workflow for peer review + - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests + + + 💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story. + + Suggest checking {sprint_status} to see project progress + + Remain flexible - allow user to choose their own path or ask for other assistance + diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.md b/src/bmm/workflows/4-implementation/dev-story/workflow.md index 06443a43f..0458eee64 100644 --- a/src/bmm/workflows/4-implementation/dev-story/workflow.md +++ b/src/bmm/workflows/4-implementation/dev-story/workflow.md @@ -5,6 +5,16 @@ main_config: '{project-root}/_bmad/bmm/config.yaml' web_bundle: false --- +# Dev Story Workflow + +## Goal +Implement a ready story end-to-end with strict validation gates, accurate progress tracking, and high-quality test coverage. + +## Workflow Architecture +- Uses step-file execution to keep context focused and deterministic. +- Read one step file fully, execute it, then move to the next step file. +- Do not pre-load future step files. + ## Initialization - Load config from `{project-root}/_bmad/bmm/config.yaml`. - Resolve variables: @@ -20,14 +30,17 @@ web_bundle: false - `date` (system-generated) - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story` - - Communicate all responses in {communication_language} and generate all documents in {document_output_language} +## Critical Rules +- Communicate in `{communication_language}` and tailor explanations to `{user_skill_level}`. +- Generate any documents in `{document_output_language}`. +- Only update allowed story sections: + - Tasks/Subtasks checkboxes + - Dev Agent Record (Debug Log, Completion Notes) + - File List + - Change Log + - Status +- Execute steps in order and do not skip validation gates. +- Continue until the story is complete unless a defined HALT condition triggers. - - Read and follow instructions at: {installed_path}/instructions.xml - - - - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md - - +## Execution +Read fully and follow: `steps/step-01-find-story.md`. diff --git a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md index e0af3d68e..b8deb658f 100644 --- a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md +++ b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md @@ -267,7 +267,7 @@ After each category, show the generated rules and present choices: #### If 'A' (Advanced Elicitation): -- Execute advanced-elicitation.xml with current category rules +- Execute advanced-elicitation workflow (`{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md`) with current category rules - Process enhanced rules that come back - Ask user: "Accept these enhanced rules for {{category}}? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/core/tasks/validate-workflow.md b/src/core/tasks/validate-workflow.md new file mode 100644 index 000000000..fa34424ad --- /dev/null +++ b/src/core/tasks/validate-workflow.md @@ -0,0 +1,40 @@ +--- +name: validate-workflow +description: Validate a target file against a checklist +standalone: true +--- + +# Task: Validate Workflow + +## Initialization +- Load config from `{project-root}/_bmad/core/config.yaml`. +- Resolve variables (if available): + - `communication_language`, `user_name`, `document_output_language` + +## Purpose +Execute a validation checklist against a target file and report findings clearly and consistently. + +## Steps +1. **Load checklist** + - Use the checklist path provided by the calling workflow (e.g., its `validation` property). + - If not provided, ask the user for the checklist path. + +2. **Load target file** + - Infer the target file from the checklist context or workflow inputs. + - If unclear, ask the user for the exact file path to validate. + +3. **Run the checklist** + - Read the checklist fully. + - Apply each item systematically to the target file. + - Record pass/fail and capture specific evidence for any issues. + +4. **Report findings** + - Summarize issues with clear labels (e.g., CRITICAL/HIGH/MEDIUM/LOW when applicable). + - Provide actionable fixes for each issue. + +5. **Edits (if applicable)** + - If the checklist instructs updates or auto-fixes, ask for confirmation before editing. + - Only apply changes after user approval. + +6. **Finalize** + - Confirm completion and provide the final validation summary. diff --git a/src/core/tasks/workflow.md b/src/core/tasks/workflow.md new file mode 100644 index 000000000..3c66a5c67 --- /dev/null +++ b/src/core/tasks/workflow.md @@ -0,0 +1,116 @@ +--- +name: workflow +description: Execute a workflow definition by loading configuration, following instructions, and producing outputs +standalone: false +--- + +# Task: Execute Workflow + +## Non-Negotiable Mandates +- Always read complete files. Do not use partial reads for workflow/task files. +- Instructions are mandatory whether embedded or referenced. +- Execute steps in order. Do not skip steps. +- Resolve variables before executing dependent actions. +- Save output checkpoints immediately when a `` tag is reached. + +## Input Contract +- Required input: `workflow-config` path (usually `workflow.md` or `workflow-*.md`). +- This runner supports markdown workflow definitions with frontmatter and XML-style instruction tags. + +## Execution Rules +1. Process steps in numeric order unless a `goto`/conditional explicitly redirects flow. +2. Optional steps require user confirmation unless `#yolo` mode is active. +3. On ``, write output, show the section, and wait for user confirmation unless `#yolo` mode is active. +4. If a required value is unknown, ask the user before continuing. + +## Execution Flow + +### 1. Load and initialize workflow + +#### 1a. Load config and resolve variables +- Load workflow definition from `workflow-config`. +- If frontmatter contains `main_config` or `config_source`, load that file. +- Resolve config references and placeholders. +- Resolve system variables: + - `date` (system-generated) + - `{project-root}` + - `{installed_path}` +- Ask the user for unresolved variables. + +#### 1b. Load required components +- Load instruction content if referenced by path. +- If a template path exists, load the full template. +- If a validation/checklist path exists, store it for validation steps. +- Data files (`csv`, `json`, etc.) may be loaded lazily when first referenced. + +#### 1c. Initialize output (template workflows) +- Resolve `default_output_file`. +- Create output directory if needed. +- Write template skeleton on first write. + +### 2. Execute instruction steps + +#### 2a. Handle step attributes +- `optional="true"`: include only with user consent unless `#yolo`. +- `if="condition"`: execute only when condition is true. +- `for-each="collection"`: repeat for each item. +- `repeat="n"`: repeat exactly `n` times. + +#### 2b. Execute step content +- Execute markdown instructions and XML-style tags. +- Replace `{{variables}}`; ask user when unresolved. + +Supported execution tags: +- ``: perform action. +- ``: conditional single action. +- `...`: conditional block. +- ``: prompt and wait. +- ``: jump to step. +- ``: run another workflow. +- ``: run another task. +- ``: run reusable protocol. + +#### 2c. Handle `` +- Generate content for that section. +- Write/update output file. +- Display section content. +- Offer next action: + - `[a]` Advanced Elicitation: `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md` + - `[p]` Party Mode: `{project-root}/_bmad/core/workflows/party-mode/workflow.md` + - `[c]` Continue + - `[y]` Enable `#yolo` for remaining sections in this run + +#### 2d. Step completion prompt +- If no special tag and not `#yolo`, ask whether to continue. + +### 3. Completion +- Confirm output is saved (for template workflows). +- Confirm required actions completed (for action workflows). +- Report workflow completion. + +## Execution Modes +- `normal`: full confirmations and interaction. +- `#yolo`: skip optional confirmations and proceed with minimal prompts. + +## Protocols + +### `discover_inputs` +Objective: load relevant project inputs from `input_file_patterns`. + +1. Parse `input_file_patterns` from the active workflow frontmatter. +2. For each pattern group, try sources in this order: +- Sharded pattern (if provided) +- Whole-document pattern fallback +3. Apply configured load strategy: +- `FULL_LOAD`: load every matching shard and combine (index first, then alphabetical). +- `SELECTIVE_LOAD`: resolve template variables and load targeted shard(s). +- `INDEX_GUIDED`: load index, infer relevant files from workflow objective, then load likely relevant files. +4. If nothing matches: +- Set corresponding content variable to empty string. +- Note absence as non-fatal. +5. Report loaded variables and source files. + +## Final Directives +- Follow this runner first, then the target workflow instructions. +- If behavior is ambiguous, re-read this file and the target workflow definition. +- Keep execution deterministic, explicit, and auditable. diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index c5482985c..4fdc5d03b 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -145,7 +145,7 @@ class ManifestGenerator { // Recurse into subdirectories const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; await findWorkflows(fullPath, newRelativePath); - } else if (entry.name === 'workflow.md') { + } else if (entry.isFile() && /^workflow(?:-[^/]+)?\.md$/.test(entry.name)) { // Parse workflow file (MD with YAML frontmatter) if (debug) { console.log(`[DEBUG] Found workflow file: ${fullPath}`); @@ -187,10 +187,11 @@ class ManifestGenerator { if (workflow.name && workflow.description) { // Build relative path for installation + const relativeWorkflowPath = relativePath ? `${relativePath}/${entry.name}` : entry.name; const installPath = moduleName === 'core' - ? `${this.bmadFolderName}/core/workflows/${relativePath}/${entry.name}` - : `${this.bmadFolderName}/${moduleName}/workflows/${relativePath}/${entry.name}`; + ? `${this.bmadFolderName}/core/workflows/${relativeWorkflowPath}` + : `${this.bmadFolderName}/${moduleName}/workflows/${relativeWorkflowPath}`; // Workflows with standalone: false are filtered out above workflows.push({ diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index a8a4985ca..1c4bdeb6a 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -344,7 +344,7 @@ class BaseIdeSetup { // Recursively search subdirectories const subWorkflows = await this.findWorkflowFiles(fullPath); workflows.push(...subWorkflows); - } else if (entry.isFile() && entry.name === 'workflow.md') { + } else if (entry.isFile() && /^workflow(?:-[^/]+)?\.md$/.test(entry.name)) { // Read workflow file to get name and standalone property try { const yaml = require('yaml'); diff --git a/tools/cli/installers/lib/ide/_config-driven.js b/tools/cli/installers/lib/ide/_config-driven.js index 0ceff98a8..0961c4d94 100644 --- a/tools/cli/installers/lib/ide/_config-driven.js +++ b/tools/cli/installers/lib/ide/_config-driven.js @@ -159,8 +159,8 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { for (const artifact of artifacts) { if (artifact.type === 'workflow-command') { - // Default to 'default' template type, but allow override via config - const workflowTemplateType = config.md_workflow_template || `${templateType}-workflow`; + // Allow explicit override, but normalize to template type prefix (without "-workflow" suffix) + const workflowTemplateType = (config.md_workflow_template || templateType).replace(/-workflow$/, ''); // Fall back to default template if the requested one doesn't exist const finalTemplateType = 'default-workflow'; diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index d5055f491..91231434a 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -144,8 +144,7 @@ class WorkflowCommandGenerator { .replaceAll('{{module}}', workflow.module) .replaceAll('{{description}}', workflow.description) .replaceAll('{{workflow_path}}', workflowPath) - .replaceAll('_bmad', this.bmadFolderName) - .replaceAll('_bmad', '_bmad'); + .replaceAll('_bmad', this.bmadFolderName); } /** @@ -225,15 +224,15 @@ When running any workflow: const match = workflowPath.match(/\/src\/bmm\/(.+)/); if (match) { transformed = `{project-root}/${this.bmadFolderName}/bmm/${match[1]}`; - } else if (workflowPath.includes('/src/core/')) { - const match = workflowPath.match(/\/src\/core\/(.+)/); - if (match) { - transformed = `{project-root}/${this.bmadFolderName}/core/${match[1]}`; - } } - - return transformed; + } else if (workflowPath.includes('/src/core/')) { + const match = workflowPath.match(/\/src\/core\/(.+)/); + if (match) { + transformed = `{project-root}/${this.bmadFolderName}/core/${match[1]}`; + } } + + return transformed; } async loadWorkflowManifest(bmadDir) { diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index 2da298efe..a2ac00312 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -739,8 +739,8 @@ class ModuleManager { } } - // Check if this is a workflow file (MD) - if (file.endsWith('workflow.md')) { + // Check if this is a workflow definition file (workflow.md or workflow-*.md) + if (/(^|\/)workflow(?:-[^/]+)?\.md$/.test(file)) { await fs.ensureDir(path.dirname(targetFile)); await this.copyWorkflowFileStripped(sourceFile, targetFile); } else { @@ -1094,7 +1094,7 @@ class ModuleManager { // Handle both _bmad placeholder and hardcoded 'bmad' // Example: {project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.md // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.md - const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/); + const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:_?bmad)\/([^/]+)\/workflows\/(.+)/); if (!sourceMatch) { console.warn(chalk.yellow(` Could not parse workflow path: ${sourceWorkflowPath}`)); continue; @@ -1103,20 +1103,22 @@ class ModuleManager { const [, sourceModule, sourceWorkflowSubPath] = sourceMatch; // Parse INSTALL workflow path - // Handle_bmad + // Handle both _bmad placeholder and hardcoded 'bmad' // Example: {project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.md - const installMatch = installWorkflowPath.match(/\{project-root\}\/(_bmad)\/([^/]+)\/workflows\/(.+)/); + // Or: {project-root}/bmad/bmgd/workflows/4-production/create-story/workflow.md + const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:_?bmad)\/([^/]+)\/workflows\/(.+)/); if (!installMatch) { console.warn(chalk.yellow(` Could not parse workflow-install path: ${installWorkflowPath}`)); continue; } - const installWorkflowSubPath = installMatch[2]; + const [, installModule, installWorkflowSubPath] = installMatch; const sourceModulePath = getModulePath(sourceModule); - const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')); + const workflowSuffixPattern = /\/workflow(?:-[^/]+)?\.md$/; + const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(workflowSuffixPattern, '')); - const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.md$/, '')); + const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(workflowSuffixPattern, '')); // Check if source workflow exists if (!(await fs.pathExists(actualSourceWorkflowPath))) { @@ -1127,7 +1129,7 @@ class ModuleManager { // Copy the entire workflow folder console.log( chalk.dim( - ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.md$/, '')}`, + ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(workflowSuffixPattern, '')} → ${installModule}/workflows/${installWorkflowSubPath.replace(workflowSuffixPattern, '')}`, ), ); @@ -1135,10 +1137,11 @@ class ModuleManager { // Copy the workflow directory recursively with placeholder replacement await this.copyDirectoryWithPlaceholderReplacement(actualSourceWorkflowPath, actualDestWorkflowPath); - // Update workflow config_source references - const workflowMdPath = path.join(actualDestWorkflowPath, 'workflow.md'); - if (await fs.pathExists(workflowMdPath)) { - await this.updateWorkflowConfigSource(workflowMdPath, moduleName); + // Update workflow config_source references in vendored workflow definition + const destinationFiles = await fs.readdir(actualDestWorkflowPath); + const workflowDefinitionFile = destinationFiles.find((name) => /^workflow(?:-[^/]+)?\.md$/.test(name)); + if (workflowDefinitionFile) { + await this.updateWorkflowConfigSource(path.join(actualDestWorkflowPath, workflowDefinitionFile), moduleName); } } } From 0b3023cdf5751bef57010d8d7031b74fb1412c0e Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sat, 7 Feb 2026 17:37:51 +0000 Subject: [PATCH 14/22] fix: harden install XML guard and remove no-op placeholder replacement --- test/test-installation-components.js | 13 +++++++++++-- .../lib/ide/shared/agent-command-generator.js | 3 +-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/test/test-installation-components.js b/test/test-installation-components.js index b3736c0a7..b0bded006 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -32,8 +32,9 @@ let failed = 0; /** * Recursively collect files from a mix of files/directories. */ -async function collectFiles(targets, allowedExtensions) { +async function collectFiles(targets, allowedExtensions, excludedFiles = new Set()) { const files = []; + const normalizedExcludes = new Set([...excludedFiles].map((p) => path.resolve(p))); const walk = async (targetPath) => { if (!(await fs.pathExists(targetPath))) { @@ -42,6 +43,10 @@ async function collectFiles(targets, allowedExtensions) { const stat = await fs.stat(targetPath); if (stat.isFile()) { + const normalizedTargetPath = path.resolve(targetPath); + if (normalizedExcludes.has(normalizedTargetPath)) { + return; + } if (allowedExtensions.has(path.extname(targetPath))) { files.push(targetPath); } @@ -58,6 +63,9 @@ async function collectFiles(targets, allowedExtensions) { await walk(fullPath); continue; } + if (normalizedExcludes.has(path.resolve(fullPath))) { + continue; + } if (allowedExtensions.has(path.extname(entry.name))) { files.push(fullPath); } @@ -273,9 +281,10 @@ async function runTests() { ]; const allowedExtensions = new Set(['.md', '.yaml', '.yml', '.xml']); const forbiddenRef = 'validate-workflow.xml'; + const excludedFile = path.join(projectRoot, 'src', 'core', 'tasks', 'validate-workflow.xml'); const offenders = []; - const files = await collectFiles(searchTargets, allowedExtensions); + const files = await collectFiles(searchTargets, allowedExtensions, new Set([excludedFile])); for (const fullPath of files) { const content = await fs.readFile(fullPath, 'utf8'); if (content.includes(forbiddenRef)) { diff --git a/tools/cli/installers/lib/ide/shared/agent-command-generator.js b/tools/cli/installers/lib/ide/shared/agent-command-generator.js index caf60614f..42b81d7c8 100644 --- a/tools/cli/installers/lib/ide/shared/agent-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/agent-command-generator.js @@ -80,8 +80,7 @@ class AgentCommandGenerator { .replaceAll('{{module}}', agent.module) .replaceAll('{{path}}', agentPathInModule) .replaceAll('{{description}}', agent.description || `${agent.name} agent`) - .replaceAll('_bmad', this.bmadFolderName) - .replaceAll('_bmad', '_bmad'); + .replaceAll('_bmad', this.bmadFolderName); } /** From 9b98cc127262c600827f4870f70d3cfc2633c08b Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sat, 7 Feb 2026 20:02:33 +0000 Subject: [PATCH 15/22] fix: correct workflow command defaults and bmm document config paths --- .../document-project/workflows/deep-dive.yaml | 2 +- .../document-project/workflows/full-scan.yaml | 2 +- test/test-installation-components.js | 50 +++++++++++++++++++ .../ide/shared/workflow-command-generator.js | 4 +- 4 files changed, 54 insertions(+), 4 deletions(-) diff --git a/src/bmm/workflows/document-project/workflows/deep-dive.yaml b/src/bmm/workflows/document-project/workflows/deep-dive.yaml index d91105112..4a7867c20 100644 --- a/src/bmm/workflows/document-project/workflows/deep-dive.yaml +++ b/src/bmm/workflows/document-project/workflows/deep-dive.yaml @@ -7,7 +7,7 @@ author: "BMad" parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" # Critical variables inherited from parent -config_source: "{project-root}/_bmad/bmb/config.yaml" +config_source: "{project-root}/_bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" date: system-generated diff --git a/src/bmm/workflows/document-project/workflows/full-scan.yaml b/src/bmm/workflows/document-project/workflows/full-scan.yaml index c131bb00d..e2e73824e 100644 --- a/src/bmm/workflows/document-project/workflows/full-scan.yaml +++ b/src/bmm/workflows/document-project/workflows/full-scan.yaml @@ -7,7 +7,7 @@ author: "BMad" parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" # Critical variables inherited from parent -config_source: "{project-root}/_bmad/bmb/config.yaml" +config_source: "{project-root}/_bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" user_name: "{config_source}:user_name" date: system-generated diff --git a/test/test-installation-components.js b/test/test-installation-components.js index b0bded006..47410e9b4 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -15,6 +15,8 @@ const path = require('node:path'); const fs = require('fs-extra'); const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder'); const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator'); +const { WorkflowCommandGenerator } = require('../tools/cli/installers/lib/ide/shared/workflow-command-generator'); +const { BMAD_FOLDER_NAME } = require('../tools/cli/installers/lib/ide/shared/path-utils'); // ANSI colors const colors = { @@ -207,6 +209,24 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 4: Workflow Command Generator Defaults + // ============================================================ + console.log(`${colors.yellow}Test Suite 4: Workflow Generator Defaults${colors.reset}\n`); + + try { + const workflowGenerator = new WorkflowCommandGenerator(); + assert( + workflowGenerator.bmadFolderName === BMAD_FOLDER_NAME, + 'Workflow generator default BMAD folder matches shared constant', + `Expected "${BMAD_FOLDER_NAME}", got "${workflowGenerator.bmadFolderName}"`, + ); + } catch (error) { + assert(false, 'Workflow generator default path is valid', error.message); + } + + console.log(''); + // ============================================================ // Test 5: QA Agent Compilation // ============================================================ @@ -236,6 +256,36 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 9: Guard against incorrect module config references + // ============================================================ + console.log(`${colors.yellow}Test Suite 9: BMM Config Reference Guard${colors.reset}\n`); + + try { + const searchTargets = [path.join(projectRoot, 'src', 'bmm', 'workflows', 'document-project', 'workflows')]; + const allowedExtensions = new Set(['.yaml', '.yml']); + const forbiddenRef = '{project-root}/_bmad/bmb/config.yaml'; + const offenders = []; + + const files = await collectFiles(searchTargets, allowedExtensions); + for (const fullPath of files) { + const content = await fs.readFile(fullPath, 'utf8'); + if (content.includes(forbiddenRef)) { + offenders.push(path.relative(projectRoot, fullPath)); + } + } + + assert( + offenders.length === 0, + 'No bmm workflow configs should reference _bmad/bmb/config.yaml', + offenders.length > 0 ? offenders.join(', ') : '', + ); + } catch (error) { + assert(false, 'BMM config reference guard runs', error.message); + } + + console.log(''); + // ============================================================ // Test 6: Guard against advanced-elicitation XML references // ============================================================ diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index 91231434a..d368ac7f5 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -2,13 +2,13 @@ const path = require('node:path'); const fs = require('fs-extra'); const csv = require('csv-parse/sync'); const chalk = require('chalk'); -const { toColonPath, toDashPath, customAgentColonName, customAgentDashName } = require('./path-utils'); +const { toColonPath, toDashPath, customAgentColonName, customAgentDashName, BMAD_FOLDER_NAME } = require('./path-utils'); /** * Generates command files for each workflow in the manifest */ class WorkflowCommandGenerator { - constructor(bmadFolderName = 'bmad') { + constructor(bmadFolderName = BMAD_FOLDER_NAME) { this.templatePath = path.join(__dirname, '../templates/workflow-commander.md'); this.bmadFolderName = bmadFolderName; } From d8e9caac1ed055a8070b9750534cd39238e93429 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sat, 7 Feb 2026 22:51:38 +0000 Subject: [PATCH 16/22] fix: add workflow loader fallback guidance and guards --- .../agent-components/handler-workflow.txt | 21 ++++++++---- test/test-installation-components.js | 33 +++++++++++++++++++ .../ide/shared/workflow-command-generator.js | 14 +++++--- 3 files changed, 58 insertions(+), 10 deletions(-) diff --git a/src/utility/agent-components/handler-workflow.txt b/src/utility/agent-components/handler-workflow.txt index 09b7d0825..82ce16f94 100644 --- a/src/utility/agent-components/handler-workflow.txt +++ b/src/utility/agent-components/handler-workflow.txt @@ -1,10 +1,19 @@ When menu item has: workflow="path/to/workflow.md": - 1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.md - 2. Read the complete file - this is the CORE OS for processing BMAD workflows - 3. Pass the workflow definition path as 'workflow-config' parameter to those instructions - 4. Follow workflow.md instructions precisely following all steps - 5. Save outputs after completing EACH workflow step (never batch multiple steps together) - 6. If workflow.md path is "todo", inform user the workflow hasn't been implemented yet + 1. Resolve loader paths safely: + - Primary: {project-root}/_bmad/core/tasks/workflow.md + - Fallback: {project-root}/src/core/tasks/workflow.md + 2. Verify the primary loader exists and is readable before loading it + 3. If primary is missing/unreadable: + - Log a warning with the primary path and underlying error + - Attempt the fallback loader path + 4. If fallback is also missing/unreadable: + - Log an error including both attempted paths and underlying errors + - Fail fast with a descriptive message and HALT + 5. LOAD the resolved workflow loader file and read it completely + 6. Pass the workflow definition path as 'workflow-config' parameter to those instructions + 7. Follow workflow.md instructions precisely following all steps + 8. Save outputs after completing EACH workflow step (never batch multiple steps together) + 9. If workflow.md path is "todo", inform user the workflow hasn't been implemented yet diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 47410e9b4..6503807cf 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -221,6 +221,18 @@ async function runTests() { 'Workflow generator default BMAD folder matches shared constant', `Expected "${BMAD_FOLDER_NAME}", got "${workflowGenerator.bmadFolderName}"`, ); + + const launcherContent = workflowGenerator.buildLauncherContent('bmm', [ + { + name: 'create-story', + displayPath: '{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.md', + description: 'Create and validate the next story', + }, + ]); + assert( + launcherContent.includes('{project-root}/src/core/tasks/workflow.md'), + 'Workflow launcher includes fallback loader path for workflow task', + ); } catch (error) { assert(false, 'Workflow generator default path is valid', error.message); } @@ -383,6 +395,27 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 10: Workflow Handler Fallback Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 10: Workflow Handler Fallback Guard${colors.reset}\n`); + + try { + const workflowHandlerPath = path.join(projectRoot, 'src', 'utility', 'agent-components', 'handler-workflow.txt'); + const content = await fs.readFile(workflowHandlerPath, 'utf8'); + + assert(content.includes('{project-root}/src/core/tasks/workflow.md'), 'Workflow handler documents fallback loader path'); + assert(content.includes('Log an error including both attempted paths'), 'Workflow handler requires explicit dual-path error logging'); + assert( + content.includes('Fail fast with a descriptive message and HALT'), + 'Workflow handler mandates fail-fast behavior when loader is unavailable', + ); + } catch (error) { + assert(false, 'Workflow handler fallback guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index d368ac7f5..3f0d2a437 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -204,10 +204,16 @@ class WorkflowCommandGenerator { ## Execution When running any workflow: -1. LOAD {project-root}/${this.bmadFolderName}/core/tasks/workflow.md -2. Pass the workflow path as 'workflow-config' parameter -3. Follow workflow.md instructions EXACTLY -4. Save outputs after EACH section +1. Resolve loader paths: + - Primary: {project-root}/${this.bmadFolderName}/core/tasks/workflow.md + - Fallback: {project-root}/src/core/tasks/workflow.md +2. Check the primary path exists and is readable before loading +3. If primary is missing/unreadable, log a warning with the path and error, then try fallback +4. If fallback is also missing/unreadable, log an error with both attempted paths and stop +5. LOAD the resolved workflow loader file +6. Pass the workflow path as 'workflow-config' parameter +7. Follow workflow.md instructions EXACTLY +8. Save outputs after EACH section ## Modes - Normal: Full interaction From cc141b93aca190f3d6f66b097adc48cd83ecbd9e Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 00:37:42 +0000 Subject: [PATCH 17/22] fix: resolve workflow guardrails and installer regressions --- README.md | 9 + .../create-prd/steps-v/step-v-01-discovery.md | 2 +- .../steps/step-04-emotional-response.md | 2 +- .../steps/step-03-execute-review.md | 61 +++++- .../steps/step-04-present-and-resolve.md | 6 + .../correct-course/workflow.md | 4 +- .../create-story/instructions.xml | 2 +- .../dev-story/steps/step-02-load-context.md | 21 +- .../steps/step-08-mark-task-complete.md | 27 ++- .../steps/step-09-mark-review-ready.md | 4 + .../4-implementation/dev-story/workflow.md | 26 ++- src/core/tasks/validate-workflow.md | 32 ++- .../handler-validate-workflow.txt | 16 +- test/test-installation-components.js | 142 ++++++++++++++ .../installers/lib/core/manifest-generator.js | 184 ++---------------- .../cli/installers/lib/ide/_config-driven.js | 117 +++++++++-- .../ide/shared/task-tool-command-generator.js | 51 +++-- tools/cli/installers/lib/modules/manager.js | 26 ++- 18 files changed, 495 insertions(+), 237 deletions(-) diff --git a/README.md b/README.md index 6e1f3a9b0..8a461b602 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,15 @@ Products, platforms, complex features — structured planning then build: Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/). +### Workflow Path Resolution + +BMad workflow/task files often reference placeholders such as `{project-root}` and installed paths like `{project-root}/_bmad/...`. + +- In installed projects, `{project-root}` resolves to the consuming repository root where BMAD is installed. +- `_bmad/...` paths point to the installed BMAD runtime content in that repository. +- In this source repository, equivalent source files typically live under `src/...`. +- When a workflow must run directly from source (without install), use explicit `src/...` paths in that workflow step. + ## Modules BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time. After the V6 beta period these will also be available as Plugins and Granular Skills. diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md index ae3f954dd..29b70b1f3 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md @@ -6,7 +6,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio nextStepFile: './step-v-02-format-detection.md' advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' -prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' +prdPurpose: '../data/prd-purpose.md' --- # Step 1: Document Discovery & Confirmation diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md index 6b74fc0fb..1dfb52dd1 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md +- When 'A' selected: Read fully and follow: src/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md b/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md index 48672c205..6ca2f3896 100644 --- a/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-03-execute-review.md @@ -2,16 +2,29 @@ name: 'step-03-execute-review' description: 'Execute full adversarial review and record actionable findings' nextStepFile: './step-04-present-and-resolve.md' +reviewFindingsFile: '{story_dir}/review-findings.json' --- VALIDATE EVERY CLAIM - Check git reality vs story claims + Every issue MUST be captured using the structured findings contract below + + Initialize findings artifacts: + - Set {{review_findings}} = [] (in-memory array) + - Set {{review_findings_file}} = {reviewFindingsFile} + - Each finding record MUST contain: + id, severity, type, summary, detail, file_line, proof, suggested_fix, reviewer, timestamp + - `file_line` format MUST be `path/to/file:line` + - `reviewer` value MUST be `senior-dev-review` + - `timestamp` MUST use system ISO datetime + Review git vs story File List discrepancies: 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) 2. **Story lists files but no git changes** → HIGH finding (false claims) 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) + For every discrepancy, append a finding object to {{review_findings}}. @@ -21,8 +34,29 @@ nextStepFile: './step-04-present-and-resolve.md' For EACH Acceptance Criterion: 1. Read the AC requirement 2. Search implementation files for evidence - 3. Determine: IMPLEMENTED, PARTIAL, or MISSING - 4. If MISSING/PARTIAL → HIGH SEVERITY finding + 3. Determine: IMPLEMENTED, PARTIAL, or MISSING using this algorithm: + - IMPLEMENTED: + - Direct code evidence exists for ALL AC clauses, and + - At least one corroborating test OR deterministic runtime verification exists, and + - Any docs/comments are supported by code/test evidence. + - PARTIAL: + - Some AC clauses have direct implementation evidence but one or more clauses are missing OR only indirectly covered, or + - Evidence is helper/utility code not clearly wired to the story path, or + - Evidence is docs/comments only without strong corroboration. + - MISSING: + - No credible code/test/docs evidence addresses the AC clauses. + 4. Evidence-strength rules: + - Code + tests = strong evidence + - Code only = medium evidence + - Docs/comments/README only = weak evidence (cannot justify IMPLEMENTED alone) + 5. Indirect evidence rules: + - Generic helpers/utilities count as PARTIAL unless explicitly wired by call sites OR integration tests. + 6. Severity mapping for AC gaps: + - MISSING critical-path AC → HIGH + - MISSING non-critical AC → MEDIUM + - PARTIAL critical-path AC → HIGH + - PARTIAL non-critical AC → MEDIUM + 7. If AC is PARTIAL or MISSING, append a finding object to {{review_findings}}. @@ -31,6 +65,7 @@ nextStepFile: './step-04-present-and-resolve.md' 2. Search files for evidence it was actually done 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding 4. Record specific proof (file:line) + 5. Append finding object to {{review_findings}} when mismatch is found @@ -40,6 +75,7 @@ nextStepFile: './step-04-present-and-resolve.md' 3. **Error Handling**: Missing try/catch, poor error messages 4. **Code Quality**: Complex functions, magic numbers, poor naming 5. **Test Quality**: Are tests real assertions or placeholders? + 6. For each issue, append finding object to {{review_findings}} @@ -54,6 +90,27 @@ nextStepFile: './step-04-present-and-resolve.md' Find at least 3 more specific, actionable issues + + Persist findings contract for downstream step: + - Save {{review_findings}} as JSON array to {{review_findings_file}} + - Ensure JSON is valid and each finding includes all required fields + - Set {{findings_contract}} = "JSON array at {{review_findings_file}}" + + + Example finding record (must match real records): + { + "id": "AC-003-MISSING-001", + "severity": "HIGH", + "type": "acceptance-criteria", + "summary": "AC-3 missing null-check in API handler", + "detail": "Endpoint accepts null payload despite AC requiring rejection with 400.", + "file_line": "src/api/handler.ts:87", + "proof": "No guard before dereference; test suite lacks AC-3 rejection test.", + "suggested_fix": "Add null guard + 400 response and add regression test in test/api/handler.test.ts.", + "reviewer": "senior-dev-review", + "timestamp": "2026-02-08T00:00:00.000Z" + } + ## Next diff --git a/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md b/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md index d3e23bc78..87df0d1ab 100644 --- a/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md +++ b/src/bmm/workflows/4-implementation/code-review/steps/step-04-present-and-resolve.md @@ -2,9 +2,15 @@ name: 'step-04-present-and-resolve' description: 'Present findings and either apply fixes or create follow-up action items' nextStepFile: './step-05-update-status.md' +reviewFindingsFile: '{story_dir}/review-findings.json' --- + Load structured findings from {reviewFindingsFile} + Validate findings schema for each entry: + id, severity, type, summary, detail, file_line, proof, suggested_fix, reviewer, timestamp + + If findings file missing or malformed: HALT with explicit error and return to step 3 generation Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) Set {{fixed_count}} = 0 Set {{action_count}} = 0 diff --git a/src/bmm/workflows/4-implementation/correct-course/workflow.md b/src/bmm/workflows/4-implementation/correct-course/workflow.md index f6cfff26a..9b0149e75 100644 --- a/src/bmm/workflows/4-implementation/correct-course/workflow.md +++ b/src/bmm/workflows/4-implementation/correct-course/workflow.md @@ -17,7 +17,7 @@ web_bundle: false - `project_knowledge` - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` - `date` (system-generated) - - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course` + - `installed_path` = `src/bmm/workflows/4-implementation/correct-course` - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md` @@ -28,6 +28,6 @@ web_bundle: false - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using src/core/tasks/validate-workflow.md diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index 2a8d6ce5f..e10d70cf1 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -310,7 +310,7 @@ - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using src/core/tasks/validate-workflow.md Save story document unconditionally diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md index 8a480efbd..30ef4f6a6 100644 --- a/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-02-load-context.md @@ -8,8 +8,25 @@ nextStepFile: './step-03-detect-review-continuation.md' Load all available context to inform implementation Load {project_context} for coding standards and project-wide patterns (if exists) - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status - Load comprehensive context from story file's Dev Notes section + Validate story source before parsing: + - Verify story file exists and is readable + - If missing/unreadable: emit explicit error and HALT + + Parse and validate required sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Status + - If section missing, empty, or malformed: emit explicit error with section name and HALT + - Dev Notes is CRITICAL and MUST be present with non-empty actionable content + + Parse and validate optional section: Change Log + - If missing/empty: create warning and continue with safe default ("No prior change log entries") + + Validate structure before extraction: + - Story: identifiable title + narrative structure + - Acceptance Criteria: parseable list/numbered clauses + - Tasks/Subtasks: checkbox task format with stable task boundaries + - Dev Agent Record/File List/Status: parseable heading + body content + - If malformed structure prevents reliable parsing: emit explicit error and HALT + + Load comprehensive context from story file's Dev Notes section ONLY after validation passes Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications Use enhanced story context to inform implementation decisions and approaches ✅ **Context Loaded** diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md index ae48cbd70..03d1d68f9 100644 --- a/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-08-mark-task-complete.md @@ -7,6 +7,13 @@ nextStepFile: './step-09-mark-review-ready.md' NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING + Initialize review-tracking variables before checks: + - If {{resolved_review_items}} is undefined: set {{resolved_review_items}} = [] + - If {{unresolved_review_items}} is undefined: set {{unresolved_review_items}} = [] + - Set {{review_continuation}} by checking current task title/original task list for prefix "[AI-Review]" + - Set {{date}} from system-generated timestamp in project date format + + Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100% Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features @@ -16,14 +23,26 @@ nextStepFile: './step-09-mark-review-ready.md' Extract review item details (severity, description, related AC/file) - Add to resolution tracking list: {{resolved_review_items}} + Add current review task to resolution tracking list: append structured entry to {{resolved_review_items}} Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section - Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description - Mark that action item checkbox [x] as resolved + Find matching action item in "Senior Developer Review (AI) → Action Items" using fuzzy matching: + 1. Normalize strings (lowercase, trim, remove "[AI-Review]" prefix/punctuation) + 2. Try exact and substring matches first + 3. If none, compute token-overlap/Jaccard score per candidate + 4. Select highest-scoring candidate when score >= 0.60 + 5. If tie at best score, prefer the candidate with more shared tokens; log ambiguity + + + Mark that action item checkbox [x] as resolved + + + Log warning and append task to {{unresolved_review_items}} + Add resolution note in Dev Agent Record that no corresponding action item was found + Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}" @@ -41,7 +60,7 @@ nextStepFile: './step-09-mark-review-ready.md' - Count total resolved review items in this session + Set {{resolved_count}} = length({{resolved_review_items}}) Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})" diff --git a/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md b/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md index b9e16a34e..1ddae1928 100644 --- a/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md +++ b/src/bmm/workflows/4-implementation/dev-story/steps/step-09-mark-review-ready.md @@ -10,6 +10,10 @@ nextStepFile: './step-10-closeout.md' Confirm File List includes every changed file Execute enhanced definition-of-done validation Update the story Status to: "review" + Initialize sprint tracking state: + - If {sprint_status} exists and is readable, load file and set {{current_sprint_status}} from tracking mode/content + - If file does not exist, unreadable, or indicates no sprint tracking, set {{current_sprint_status}} = "no-sprint-tracking" + Validate definition-of-done checklist with essential requirements: diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.md b/src/bmm/workflows/4-implementation/dev-story/workflow.md index 0458eee64..ac00070ad 100644 --- a/src/bmm/workflows/4-implementation/dev-story/workflow.md +++ b/src/bmm/workflows/4-implementation/dev-story/workflow.md @@ -1,7 +1,8 @@ --- name: dev-story description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria" -main_config: '{project-root}/_bmad/bmm/config.yaml' +projectRoot: '{project-root}' +main_config: '{projectRoot}/_bmad/bmm/config.yaml' web_bundle: false --- @@ -16,7 +17,11 @@ Implement a ready story end-to-end with strict validation gates, accurate progre - Do not pre-load future step files. ## Initialization -- Load config from `{project-root}/_bmad/bmm/config.yaml`. +- Resolve `projectRoot`: + - Prefer `{project-root}` when provided by runtime. + - If unavailable, resolve repo root from current working directory (locate-repo-root helper / process cwd) and set `projectRoot`. + - Validate that `{projectRoot}/_bmad/bmm/config.yaml` exists and is readable before continuing. +- Load config from `{projectRoot}/_bmad/bmm/config.yaml`. - Resolve variables: - `user_name` - `communication_language` @@ -28,7 +33,7 @@ Implement a ready story end-to-end with strict validation gates, accurate progre - `story_file` (if provided) - `project_context` = `**/project-context.md` - `date` (system-generated) - - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/dev-story` + - `installed_path` = `{projectRoot}/_bmad/bmm/workflows/4-implementation/dev-story` ## Critical Rules - Communicate in `{communication_language}` and tailor explanations to `{user_skill_level}`. @@ -42,5 +47,20 @@ Implement a ready story end-to-end with strict validation gates, accurate progre - Execute steps in order and do not skip validation gates. - Continue until the story is complete unless a defined HALT condition triggers. +## HALT Definition +- HALT triggers: + - Required inputs/files are missing or unreadable. + - Validation gates fail and cannot be remediated in current step. + - Test/regression failures persist after fix attempts. + - Story state becomes inconsistent (e.g., malformed task structure preventing safe updates). +- HALT behavior: + - Stop executing further steps immediately. + - Persist current story-file edits and workflow state safely. + - Emit explicit user-facing error message describing trigger and remediation needed. + - Do not apply partial completion marks after HALT. +- Resume semantics: + - Manual resume only after user confirms the blocking issue is resolved. + - Resume from the last incomplete step checkpoint, re-running validations before progressing. + ## Execution Read fully and follow: `steps/step-01-find-story.md`. diff --git a/src/core/tasks/validate-workflow.md b/src/core/tasks/validate-workflow.md index fa34424ad..7b3ff72b6 100644 --- a/src/core/tasks/validate-workflow.md +++ b/src/core/tasks/validate-workflow.md @@ -8,8 +8,14 @@ standalone: true ## Initialization - Load config from `{project-root}/_bmad/core/config.yaml`. -- Resolve variables (if available): - - `communication_language`, `user_name`, `document_output_language` +- Validate config load before continuing: + - Verify file exists and is readable. + - Parse YAML and fail fast with explicit error if parsing fails. + - Require `user_name`; if missing, abort initialization with descriptive error. + - Apply explicit defaults when optional keys are absent: + - `communication_language = "en"` + - `document_output_language = "en"` + - Log resolved values and config source path. ## Purpose Execute a validation checklist against a target file and report findings clearly and consistently. @@ -20,8 +26,16 @@ Execute a validation checklist against a target file and report findings clearly - If not provided, ask the user for the checklist path. 2. **Load target file** - - Infer the target file from the checklist context or workflow inputs. - - If unclear, ask the user for the exact file path to validate. + - Infer candidate target path in this order: + - Explicit keys in workflow/checklist inputs: `file`, `path`, `target`, `filePath` + - Path-like tokens in checklist items + - First matching path from glob patterns supplied by checklist/input + - Normalize all candidate paths relative to repo root and resolve `.`/`..`. + - Validate candidate existence and expected file type (`.yaml`, `.yml`, `.json`, or checklist-defined extension). + - If multiple valid candidates remain, prefer explicit key fields over inferred tokens. + - If no valid candidate is found, prompt user with schema example: + - `Please provide the exact file path (relative to repo root), e.g. ./workflows/ci.yml` + - Validate user-supplied path before proceeding. 3. **Run the checklist** - Read the checklist fully. @@ -33,8 +47,14 @@ Execute a validation checklist against a target file and report findings clearly - Provide actionable fixes for each issue. 5. **Edits (if applicable)** - - If the checklist instructs updates or auto-fixes, ask for confirmation before editing. - - Only apply changes after user approval. + - If checklist requires edits/auto-fixes, follow safe-edit protocol: + - Ask for confirmation before editing. + - Create backup snapshot of target file before changes. + - Generate reversible diff preview and show it to user. + - Apply edits only after user approval. + - Run syntax/validation checks against edited file. + - If validation fails or user cancels, rollback from backup and report rollback status. + - Record backup/diff locations in task output. 6. **Finalize** - Confirm completion and provide the final validation summary. diff --git a/src/utility/agent-components/handler-validate-workflow.txt b/src/utility/agent-components/handler-validate-workflow.txt index 024dd9c19..4284ef69a 100644 --- a/src/utility/agent-components/handler-validate-workflow.txt +++ b/src/utility/agent-components/handler-validate-workflow.txt @@ -1,7 +1,15 @@ When command has: validate-workflow="path/to/workflow.md" - 1. You MUST LOAD the file at: {project-root}/_bmad/core/tasks/validate-workflow.md - 2. READ its entire contents and EXECUTE all instructions in that file - 3. Pass the workflow, and also check the workflow validation property to find and load the validation schema to pass as the checklist - 4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify + 1. Resolve loader paths safely: + - Primary: {project-root}/_bmad/core/tasks/validate-workflow.md + - Fallback: {project-root}/src/core/tasks/validate-workflow.md + 2. Verify primary path exists and is readable before loading + 3. Wrap read/parse in try/catch and log path + underlying error on failure + 4. If primary fails, attempt fallback and log warning that fallback mode is active + 5. If fallback also fails: + - Log clear error with both attempted paths and caught errors + - Fail fast with deterministic exception (do not continue with partial state) + 6. READ entire resolved task file and EXECUTE all instructions + 7. Pass the workflow and inspect workflow validation property to find/load checklist schema + 8. If target file cannot be inferred from checklist context, prompt user for exact path diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 6503807cf..f955aa2d9 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -12,10 +12,15 @@ */ const path = require('node:path'); +const os = require('node:os'); const fs = require('fs-extra'); +const yaml = require('yaml'); const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder'); const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator'); const { WorkflowCommandGenerator } = require('../tools/cli/installers/lib/ide/shared/workflow-command-generator'); +const { TaskToolCommandGenerator } = require('../tools/cli/installers/lib/ide/shared/task-tool-command-generator'); +const { IdeManager } = require('../tools/cli/installers/lib/ide/manager'); +const { ModuleManager } = require('../tools/cli/installers/lib/modules/manager'); const { BMAD_FOLDER_NAME } = require('../tools/cli/installers/lib/ide/shared/path-utils'); // ANSI colors @@ -416,6 +421,143 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 11: Gemini Template Extension Regression Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 11: Gemini Template Extension Guard${colors.reset}\n`); + + try { + const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-gemini-install-')); + const projectDir = path.join(tmpRoot, 'project'); + const bmadDir = path.join(tmpRoot, BMAD_FOLDER_NAME); + await fs.ensureDir(projectDir); + await fs.copy(path.join(projectRoot, 'src', 'core'), path.join(bmadDir, 'core')); + await fs.copy(path.join(projectRoot, 'src', 'bmm'), path.join(bmadDir, 'bmm')); + + const manifestGenerator = new ManifestGenerator(); + await manifestGenerator.generateManifests(bmadDir, ['bmm'], [], { ides: ['gemini'] }); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + await ideManager.setup('gemini', projectDir, bmadDir, { selectedModules: ['bmm'] }); + + const commandsDir = path.join(projectDir, '.gemini', 'commands'); + const generated = await fs.readdir(commandsDir); + + assert( + generated.some((file) => file.endsWith('.toml')), + 'Gemini installer emits template-native TOML command files', + generated.join(', '), + ); + + assert(!generated.some((file) => file.endsWith('.md')), 'Gemini installer does not emit markdown command files', generated.join(', ')); + + await fs.remove(tmpRoot); + } catch (error) { + assert(false, 'Gemini template extension guard runs', error.message); + } + + console.log(''); + + // ============================================================ + // Test 12: Manifest Stale Entry Cleanup Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 12: Manifest Stale Entry Cleanup Guard${colors.reset}\n`); + + try { + const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-manifest-clean-')); + const bmadDir = path.join(tmpRoot, BMAD_FOLDER_NAME); + await fs.copy(path.join(projectRoot, 'src', 'core'), path.join(bmadDir, 'core')); + await fs.copy(path.join(projectRoot, 'src', 'bmm'), path.join(bmadDir, 'bmm')); + + const cfgDir = path.join(bmadDir, '_config'); + await fs.ensureDir(cfgDir); + const staleManifestPath = path.join(cfgDir, 'workflow-manifest.csv'); + await fs.writeFile( + staleManifestPath, + 'name,description,module,path\n"old","old workflow","core","_bmad/core/workflows/old/workflow.md"\n', + ); + + const manifestGenerator = new ManifestGenerator(); + await manifestGenerator.generateManifests(bmadDir, ['bmm'], [], { ides: ['claude-code'] }); + const regenerated = await fs.readFile(staleManifestPath, 'utf8'); + + assert( + !regenerated.includes('"old","old workflow","core","_bmad/core/workflows/old/workflow.md"'), + 'Workflow manifest regeneration removes stale/deleted rows', + ); + + await fs.remove(tmpRoot); + } catch (error) { + assert(false, 'Manifest stale entry cleanup guard runs', error.message); + } + + console.log(''); + + // ============================================================ + // Test 13: Internal Task Command Exposure Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 13: Internal Task Exposure Guard${colors.reset}\n`); + + try { + const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-task-filter-')); + const projectDir = path.join(tmpRoot, 'project'); + const bmadDir = path.join(tmpRoot, BMAD_FOLDER_NAME); + const commandsDir = path.join(tmpRoot, 'commands'); + await fs.ensureDir(projectDir); + await fs.copy(path.join(projectRoot, 'src', 'core'), path.join(bmadDir, 'core')); + await fs.copy(path.join(projectRoot, 'src', 'bmm'), path.join(bmadDir, 'bmm')); + + const manifestGenerator = new ManifestGenerator(); + await manifestGenerator.generateManifests(bmadDir, ['bmm'], [], { ides: ['claude-code'] }); + + const taskToolGenerator = new TaskToolCommandGenerator(); + await taskToolGenerator.generateDashTaskToolCommands(projectDir, bmadDir, commandsDir); + const generated = await fs.readdir(commandsDir); + + assert( + !generated.some((file) => /^bmad-workflow\./.test(file)), + 'Task/tool command generation excludes internal workflow runner task command', + generated.join(', '), + ); + + await fs.remove(tmpRoot); + } catch (error) { + assert(false, 'Internal task exposure guard runs', error.message); + } + + console.log(''); + + // ============================================================ + // Test 14: Workflow Frontmatter web_bundle Strip Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 14: web_bundle Frontmatter Strip Guard${colors.reset}\n`); + + try { + const manager = new ModuleManager(); + const content = `--- +name: demo-workflow +description: Demo +web_bundle: + enabled: true + bundle: + mode: strict +--- + +# Demo +`; + const stripped = manager.stripWebBundleFromFrontmatter(content); + const frontmatterMatch = stripped.match(/^---\n([\s\S]*?)\n---/); + const parsed = frontmatterMatch ? yaml.parse(frontmatterMatch[1]) : {}; + + assert(!stripped.includes('web_bundle:'), 'web_bundle strip removes nested web_bundle block from frontmatter'); + assert(parsed.name === 'demo-workflow' && parsed.description === 'Demo', 'web_bundle strip preserves other frontmatter keys'); + } catch (error) { + assert(false, 'web_bundle strip guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index 4fdc5d03b..f64f72109 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -701,60 +701,16 @@ class ManifestGenerator { async writeWorkflowManifest(cfgDir) { const csvPath = path.join(cfgDir, 'workflow-manifest.csv'); const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; - const parseCsvLine = (line) => { - const columns = line.match(/(".*?"|[^",\s]+)(?=\s*,|\s*$)/g) || []; - return columns.map((c) => c.replaceAll(/^"|"$/g, '')); - }; - - // Read existing manifest to preserve entries - const existingEntries = new Map(); - if (await fs.pathExists(csvPath)) { - const content = await fs.readFile(csvPath, 'utf8'); - const lines = content.split('\n').filter((line) => line.trim()); - - // Skip header - for (let i = 1; i < lines.length; i++) { - const line = lines[i]; - if (line) { - const parts = parseCsvLine(line); - if (parts.length >= 4) { - const [name, description, module, workflowPath] = parts; - existingEntries.set(`${module}:${name}`, { - name, - description, - module, - path: workflowPath, - }); - } - } - } - } // Create CSV header - standalone column removed, everything is canonicalized to 4 columns let csv = 'name,description,module,path\n'; - // Combine existing and new workflows - const allWorkflows = new Map(); - - // Add existing entries - for (const [key, value] of existingEntries) { - allWorkflows.set(key, value); - } - - // Add/update new workflows - for (const workflow of this.workflows) { - const key = `${workflow.module}:${workflow.name}`; - allWorkflows.set(key, { - name: workflow.name, - description: workflow.description, - module: workflow.module, - path: workflow.path, - }); - } - - // Write all workflows - for (const [, value] of allWorkflows) { - const row = [escapeCsv(value.name), escapeCsv(value.description), escapeCsv(value.module), escapeCsv(value.path)].join(','); + // Regenerate from current install scan to avoid preserving stale/deleted entries + const sortedWorkflows = [...this.workflows].sort((a, b) => `${a.module}:${a.name}`.localeCompare(`${b.module}:${b.name}`)); + for (const workflow of sortedWorkflows) { + const row = [escapeCsv(workflow.name), escapeCsv(workflow.description), escapeCsv(workflow.module), escapeCsv(workflow.path)].join( + ',', + ); csv += row + '\n'; } @@ -769,50 +725,12 @@ class ManifestGenerator { async writeAgentManifest(cfgDir) { const csvPath = path.join(cfgDir, 'agent-manifest.csv'); - // Read existing manifest to preserve entries - const existingEntries = new Map(); - if (await fs.pathExists(csvPath)) { - const content = await fs.readFile(csvPath, 'utf8'); - const lines = content.split('\n').filter((line) => line.trim()); - - // Skip header - for (let i = 1; i < lines.length; i++) { - const line = lines[i]; - if (line) { - // Parse CSV (simple parsing assuming no commas in quoted fields) - const parts = line.split('","'); - if (parts.length >= 10) { - const name = parts[0].replace(/^"/, ''); - const module = parts[8]; - existingEntries.set(`${module}:${name}`, line); - } - } - } - } - // Create CSV header with persona fields let csv = 'name,displayName,title,icon,role,identity,communicationStyle,principles,module,path\n'; + const sortedAgents = [...this.agents].sort((a, b) => `${a.module}:${a.name}`.localeCompare(`${b.module}:${b.name}`)); - // Combine existing and new agents, preferring new data for duplicates - const allAgents = new Map(); - - // Add existing entries - for (const [key, value] of existingEntries) { - allAgents.set(key, value); - } - - // Add/update new agents - for (const agent of this.agents) { - const key = `${agent.module}:${agent.name}`; - allAgents.set( - key, - `"${agent.name}","${agent.displayName}","${agent.title}","${agent.icon}","${agent.role}","${agent.identity}","${agent.communicationStyle}","${agent.principles}","${agent.module}","${agent.path}"`, - ); - } - - // Write all agents - for (const [, value] of allAgents) { - csv += value + '\n'; + for (const agent of sortedAgents) { + csv += `"${agent.name}","${agent.displayName}","${agent.title}","${agent.icon}","${agent.role}","${agent.identity}","${agent.communicationStyle}","${agent.principles}","${agent.module}","${agent.path}"\n`; } await fs.writeFile(csvPath, csv); @@ -826,47 +744,11 @@ class ManifestGenerator { async writeTaskManifest(cfgDir) { const csvPath = path.join(cfgDir, 'task-manifest.csv'); - // Read existing manifest to preserve entries - const existingEntries = new Map(); - if (await fs.pathExists(csvPath)) { - const content = await fs.readFile(csvPath, 'utf8'); - const lines = content.split('\n').filter((line) => line.trim()); - - // Skip header - for (let i = 1; i < lines.length; i++) { - const line = lines[i]; - if (line) { - // Parse CSV (simple parsing assuming no commas in quoted fields) - const parts = line.split('","'); - if (parts.length >= 6) { - const name = parts[0].replace(/^"/, ''); - const module = parts[3]; - existingEntries.set(`${module}:${name}`, line); - } - } - } - } - // Create CSV header with standalone column let csv = 'name,displayName,description,module,path,standalone\n'; - - // Combine existing and new tasks - const allTasks = new Map(); - - // Add existing entries - for (const [key, value] of existingEntries) { - allTasks.set(key, value); - } - - // Add/update new tasks - for (const task of this.tasks) { - const key = `${task.module}:${task.name}`; - allTasks.set(key, `"${task.name}","${task.displayName}","${task.description}","${task.module}","${task.path}","${task.standalone}"`); - } - - // Write all tasks - for (const [, value] of allTasks) { - csv += value + '\n'; + const sortedTasks = [...this.tasks].sort((a, b) => `${a.module}:${a.name}`.localeCompare(`${b.module}:${b.name}`)); + for (const task of sortedTasks) { + csv += `"${task.name}","${task.displayName}","${task.description}","${task.module}","${task.path}","${task.standalone}"\n`; } await fs.writeFile(csvPath, csv); @@ -880,47 +762,11 @@ class ManifestGenerator { async writeToolManifest(cfgDir) { const csvPath = path.join(cfgDir, 'tool-manifest.csv'); - // Read existing manifest to preserve entries - const existingEntries = new Map(); - if (await fs.pathExists(csvPath)) { - const content = await fs.readFile(csvPath, 'utf8'); - const lines = content.split('\n').filter((line) => line.trim()); - - // Skip header - for (let i = 1; i < lines.length; i++) { - const line = lines[i]; - if (line) { - // Parse CSV (simple parsing assuming no commas in quoted fields) - const parts = line.split('","'); - if (parts.length >= 6) { - const name = parts[0].replace(/^"/, ''); - const module = parts[3]; - existingEntries.set(`${module}:${name}`, line); - } - } - } - } - // Create CSV header with standalone column let csv = 'name,displayName,description,module,path,standalone\n'; - - // Combine existing and new tools - const allTools = new Map(); - - // Add existing entries - for (const [key, value] of existingEntries) { - allTools.set(key, value); - } - - // Add/update new tools - for (const tool of this.tools) { - const key = `${tool.module}:${tool.name}`; - allTools.set(key, `"${tool.name}","${tool.displayName}","${tool.description}","${tool.module}","${tool.path}","${tool.standalone}"`); - } - - // Write all tools - for (const [, value] of allTools) { - csv += value + '\n'; + const sortedTools = [...this.tools].sort((a, b) => `${a.module}:${a.name}`.localeCompare(`${b.module}:${b.name}`)); + for (const tool of sortedTools) { + csv += `"${tool.name}","${tool.displayName}","${tool.description}","${tool.module}","${tool.path}","${tool.standalone}"\n`; } await fs.writeFile(csvPath, csv); diff --git a/tools/cli/installers/lib/ide/_config-driven.js b/tools/cli/installers/lib/ide/_config-driven.js index 0961c4d94..7a0f9ede5 100644 --- a/tools/cli/installers/lib/ide/_config-driven.js +++ b/tools/cli/installers/lib/ide/_config-driven.js @@ -89,9 +89,10 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { // Install tasks and tools if (!artifact_types || artifact_types.includes('tasks') || artifact_types.includes('tools')) { const taskToolGen = new TaskToolCommandGenerator(); - const taskToolResult = await taskToolGen.generateDashTaskToolCommands(projectDir, bmadDir, targetPath); - results.tasks = taskToolResult.tasks || 0; - results.tools = taskToolResult.tools || 0; + const { artifacts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); + const taskToolResult = await this.writeTaskToolArtifacts(targetPath, artifacts, template_type, config, artifact_types); + results.tasks = taskToolResult.tasks; + results.tools = taskToolResult.tools; } this.printSummary(results, target_dir); @@ -132,12 +133,12 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { */ async writeAgentArtifacts(targetPath, artifacts, templateType, config = {}) { // Try to load platform-specific template, fall back to default-agent - const template = await this.loadTemplate(templateType, 'agent', config, 'default-agent'); + const { template, extension } = await this.loadTemplateWithMetadata(templateType, 'agent', config, 'default-agent'); let count = 0; for (const artifact of artifacts) { const content = this.renderTemplate(template, artifact); - const filename = this.generateFilename(artifact, 'agent'); + const filename = this.generateFilename(artifact, 'agent', extension); const filePath = path.join(targetPath, filename); await this.writeFile(filePath, content); count++; @@ -164,9 +165,9 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { // Fall back to default template if the requested one doesn't exist const finalTemplateType = 'default-workflow'; - const template = await this.loadTemplate(workflowTemplateType, 'workflow', config, finalTemplateType); + const { template, extension } = await this.loadTemplateWithMetadata(workflowTemplateType, 'workflow', config, finalTemplateType); const content = this.renderTemplate(template, artifact); - const filename = this.generateFilename(artifact, 'workflow'); + const filename = this.generateFilename(artifact, 'workflow', extension); const filePath = path.join(targetPath, filename); await this.writeFile(filePath, content); count++; @@ -176,6 +177,51 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { return count; } + /** + * Write task/tool artifacts to target directory + * @param {string} targetPath - Target directory path + * @param {Array} artifacts - Task/tool artifacts + * @param {string} templateType - Template type to use + * @param {Object} config - Installation configuration + * @param {Array} artifactTypes - Optional include filter from installer config + * @returns {Promise<{tasks:number,tools:number}>} Count of artifacts written + */ + async writeTaskToolArtifacts(targetPath, artifacts, templateType, config = {}, artifactTypes = null) { + let tasks = 0; + let tools = 0; + const templateCache = new Map(); + + for (const artifact of artifacts) { + if (artifact.type !== 'task' && artifact.type !== 'tool') { + continue; + } + + if (artifactTypes && !artifactTypes.includes(`${artifact.type}s`)) { + continue; + } + + const cacheKey = `${templateType}:${artifact.type}`; + if (!templateCache.has(cacheKey)) { + const loaded = await this.loadTemplateWithMetadata(templateType, artifact.type, config, `default-${artifact.type}`); + templateCache.set(cacheKey, loaded); + } + + const { template, extension } = templateCache.get(cacheKey); + const content = this.renderTemplate(template, artifact); + const filename = this.generateFilename(artifact, artifact.type, extension); + const filePath = path.join(targetPath, filename); + await this.writeFile(filePath, content); + + if (artifact.type === 'task') { + tasks++; + } else { + tools++; + } + } + + return { tasks, tools }; + } + /** * Load template based on type and configuration * @param {string} templateType - Template type (claude, windsurf, etc.) @@ -185,31 +231,58 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { * @returns {Promise} Template content */ async loadTemplate(templateType, artifactType, config = {}, fallbackTemplateType = null) { + const { template } = await this.loadTemplateWithMetadata(templateType, artifactType, config, fallbackTemplateType); + return template; + } + + /** + * Load template with file extension metadata for extension-aware command generation + * @param {string} templateType - Template type (claude, windsurf, etc.) + * @param {string} artifactType - Artifact type (agent, workflow, task, tool) + * @param {Object} config - Installation configuration + * @param {string} fallbackTemplateType - Fallback template type if requested template not found + * @returns {Promise<{template:string, extension:string}>} Template content and extension + */ + async loadTemplateWithMetadata(templateType, artifactType, config = {}, fallbackTemplateType = null) { const { header_template, body_template } = config; + const supportedExtensions = ['.md', '.toml', '.yaml', '.yml', '.json', '.txt']; // Check for separate header/body templates if (header_template || body_template) { - return await this.loadSplitTemplates(templateType, artifactType, header_template, body_template); + const template = await this.loadSplitTemplates(templateType, artifactType, header_template, body_template); + return { template, extension: '.md' }; } - // Load combined template - const templateName = `${templateType}-${artifactType}.md`; - const templatePath = path.join(__dirname, 'templates', 'combined', templateName); - - if (await fs.pathExists(templatePath)) { - return await fs.readFile(templatePath, 'utf8'); + // Load combined template with extension detection + for (const extension of supportedExtensions) { + const templateName = `${templateType}-${artifactType}${extension}`; + const templatePath = path.join(__dirname, 'templates', 'combined', templateName); + if (await fs.pathExists(templatePath)) { + return { + template: await fs.readFile(templatePath, 'utf8'), + extension, + }; + } } // Fall back to default template (if provided) if (fallbackTemplateType) { - const fallbackPath = path.join(__dirname, 'templates', 'combined', `${fallbackTemplateType}.md`); - if (await fs.pathExists(fallbackPath)) { - return await fs.readFile(fallbackPath, 'utf8'); + for (const extension of supportedExtensions) { + const fallbackPath = path.join(__dirname, 'templates', 'combined', `${fallbackTemplateType}${extension}`); + if (await fs.pathExists(fallbackPath)) { + return { + template: await fs.readFile(fallbackPath, 'utf8'), + extension, + }; + } } } // Ultimate fallback - minimal template - return this.getDefaultTemplate(artifactType); + return { + template: this.getDefaultTemplate(artifactType), + extension: '.md', + }; } /** @@ -325,11 +398,15 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} * @param {string} artifactType - Artifact type (agent, workflow, task, tool) * @returns {string} Generated filename */ - generateFilename(artifact, artifactType) { + generateFilename(artifact, artifactType, extension = '.md') { const { toDashPath } = require('./shared/path-utils'); // toDashPath already handles the .agent.md suffix for agents correctly // No need to add it again here - return toDashPath(artifact.relativePath); + const dashName = toDashPath(artifact.relativePath); + if (extension === '.md') { + return dashName; + } + return dashName.replace(/\.md$/i, extension); } /** diff --git a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js index b293fc0e0..6690d5c9c 100644 --- a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js @@ -19,6 +19,15 @@ class TaskToolCommandGenerator { this.bmadFolderName = bmadFolderName; } + /** + * Determine if manifest entry is standalone/user-facing. + * @param {Object} item - Manifest row + * @returns {boolean} True when item should be exposed as a command + */ + isStandalone(item) { + return item?.standalone === 'true' || item?.standalone === true; + } + /** * Collect task and tool artifacts for IDE installation * @param {string} bmadDir - BMAD installation directory @@ -28,12 +37,14 @@ class TaskToolCommandGenerator { const tasks = await this.loadTaskManifest(bmadDir); const tools = await this.loadToolManifest(bmadDir); - // All tasks/tools in manifest are standalone (internal=true items are filtered during manifest generation) + const standaloneTasks = (tasks || []).filter((task) => this.isStandalone(task)); + const standaloneTools = (tools || []).filter((tool) => this.isStandalone(tool)); + const artifacts = []; const bmadPrefix = `${BMAD_FOLDER_NAME}/`; // Collect task artifacts - for (const task of tasks || []) { + for (const task of standaloneTasks) { let taskPath = (task.path || '').replaceAll('\\', '/'); // Convert absolute paths to relative paths if (path.isAbsolute(taskPath)) { @@ -58,7 +69,7 @@ class TaskToolCommandGenerator { } // Collect tool artifacts - for (const tool of tools || []) { + for (const tool of standaloneTools) { let toolPath = (tool.path || '').replaceAll('\\', '/'); // Convert absolute paths to relative paths if (path.isAbsolute(toolPath)) { @@ -85,8 +96,8 @@ class TaskToolCommandGenerator { return { artifacts, counts: { - tasks: (tasks || []).length, - tools: (tools || []).length, + tasks: standaloneTasks.length, + tools: standaloneTools.length, }, }; } @@ -100,6 +111,8 @@ class TaskToolCommandGenerator { async generateTaskToolCommands(projectDir, bmadDir, baseCommandsDir = null) { const tasks = await this.loadTaskManifest(bmadDir); const tools = await this.loadToolManifest(bmadDir); + const standaloneTasks = (tasks || []).filter((task) => this.isStandalone(task)); + const standaloneTools = (tools || []).filter((tool) => this.isStandalone(tool)); // Base commands directory - use provided or default to Claude Code structure const commandsDir = baseCommandsDir || path.join(projectDir, '.claude', 'commands', 'bmad'); @@ -107,7 +120,7 @@ class TaskToolCommandGenerator { let generatedCount = 0; // Generate command files for tasks - for (const task of tasks || []) { + for (const task of standaloneTasks) { const moduleTasksDir = path.join(commandsDir, task.module, 'tasks'); await fs.ensureDir(moduleTasksDir); @@ -119,7 +132,7 @@ class TaskToolCommandGenerator { } // Generate command files for tools - for (const tool of tools || []) { + for (const tool of standaloneTools) { const moduleToolsDir = path.join(commandsDir, tool.module, 'tools'); await fs.ensureDir(moduleToolsDir); @@ -132,8 +145,8 @@ class TaskToolCommandGenerator { return { generated: generatedCount, - tasks: (tasks || []).length, - tools: (tools || []).length, + tasks: standaloneTasks.length, + tools: standaloneTools.length, }; } @@ -234,11 +247,13 @@ Follow all instructions in the ${type} file exactly as written. async generateColonTaskToolCommands(projectDir, bmadDir, baseCommandsDir) { const tasks = await this.loadTaskManifest(bmadDir); const tools = await this.loadToolManifest(bmadDir); + const standaloneTasks = (tasks || []).filter((task) => this.isStandalone(task)); + const standaloneTools = (tools || []).filter((tool) => this.isStandalone(tool)); let generatedCount = 0; // Generate command files for tasks - for (const task of tasks || []) { + for (const task of standaloneTasks) { const commandContent = this.generateCommandContent(task, 'task'); // Use underscore format: bmad_bmm_name.md const flatName = toColonName(task.module, 'tasks', task.name); @@ -249,7 +264,7 @@ Follow all instructions in the ${type} file exactly as written. } // Generate command files for tools - for (const tool of tools || []) { + for (const tool of standaloneTools) { const commandContent = this.generateCommandContent(tool, 'tool'); // Use underscore format: bmad_bmm_name.md const flatName = toColonName(tool.module, 'tools', tool.name); @@ -261,8 +276,8 @@ Follow all instructions in the ${type} file exactly as written. return { generated: generatedCount, - tasks: (tasks || []).length, - tools: (tools || []).length, + tasks: standaloneTasks.length, + tools: standaloneTools.length, }; } @@ -278,11 +293,13 @@ Follow all instructions in the ${type} file exactly as written. async generateDashTaskToolCommands(projectDir, bmadDir, baseCommandsDir) { const tasks = await this.loadTaskManifest(bmadDir); const tools = await this.loadToolManifest(bmadDir); + const standaloneTasks = (tasks || []).filter((task) => this.isStandalone(task)); + const standaloneTools = (tools || []).filter((tool) => this.isStandalone(tool)); let generatedCount = 0; // Generate command files for tasks - for (const task of tasks || []) { + for (const task of standaloneTasks) { const commandContent = this.generateCommandContent(task, 'task'); // Use dash format: bmad-bmm-name.md const flatName = toDashPath(`${task.module}/tasks/${task.name}.md`); @@ -293,7 +310,7 @@ Follow all instructions in the ${type} file exactly as written. } // Generate command files for tools - for (const tool of tools || []) { + for (const tool of standaloneTools) { const commandContent = this.generateCommandContent(tool, 'tool'); // Use dash format: bmad-bmm-name.md const flatName = toDashPath(`${tool.module}/tools/${tool.name}.md`); @@ -305,8 +322,8 @@ Follow all instructions in the ${type} file exactly as written. return { generated: generatedCount, - tasks: (tasks || []).length, - tools: (tools || []).length, + tasks: standaloneTasks.length, + tools: standaloneTools.length, }; } diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index a2ac00312..f872582b9 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -776,12 +776,28 @@ class ModuleManager { return content; } - const frontmatter = frontmatterMatch[1] - .split('\n') - .filter((line) => !line.trim().startsWith('web_bundle:')) - .join('\n'); + try { + const yaml = require('yaml'); + const parsed = yaml.parse(frontmatterMatch[1]); - return content.replace(frontmatterMatch[0], `---\n${frontmatter}\n---`); + if (!parsed || typeof parsed !== 'object' || !Object.prototype.hasOwnProperty.call(parsed, 'web_bundle')) { + return content; + } + + delete parsed.web_bundle; + const serialized = yaml + .stringify(parsed, { + indent: 2, + lineWidth: 0, + sortMapEntries: false, + }) + .trimEnd(); + + return content.replace(frontmatterMatch[0], `---\n${serialized}\n---`); + } catch (error) { + console.warn(`Warning: Failed to parse workflow frontmatter for web_bundle removal: ${error.message}`); + return content; + } } /** From bd20d75998ab6de044424dafc2a92fbfdb0e4dac Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 01:13:23 +0000 Subject: [PATCH 18/22] fix: restore runtime workflow paths and standalone parsing --- .../steps/step-01-validate-prerequisites.md | 3 - .../correct-course/workflow.md | 4 +- test/test-installation-components.js | 120 ++++++++++++++++++ .../installers/lib/core/manifest-generator.js | 54 ++++++-- .../ide/shared/task-tool-command-generator.js | 9 +- 5 files changed, 172 insertions(+), 18 deletions(-) diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md index 5d2b0add9..d6eaef376 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md @@ -15,9 +15,6 @@ epicsTemplate: '{workflow_path}/templates/epics-template.md' # Task References advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md' partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' - -# Template References -epicsTemplate: '{workflow_path}/templates/epics-template.md' --- # Step 1: Validate Prerequisites and Extract Requirements diff --git a/src/bmm/workflows/4-implementation/correct-course/workflow.md b/src/bmm/workflows/4-implementation/correct-course/workflow.md index 9b0149e75..1fe79da87 100644 --- a/src/bmm/workflows/4-implementation/correct-course/workflow.md +++ b/src/bmm/workflows/4-implementation/correct-course/workflow.md @@ -17,7 +17,7 @@ web_bundle: false - `project_knowledge` - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` - `date` (system-generated) - - `installed_path` = `src/bmm/workflows/4-implementation/correct-course` + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course` - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md` @@ -28,6 +28,6 @@ web_bundle: false - Validate against checklist at {installed_path}/checklist.md using src/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md diff --git a/test/test-installation-components.js b/test/test-installation-components.js index f955aa2d9..15fe1a087 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -558,6 +558,126 @@ web_bundle: console.log(''); + // ============================================================ + // Test 15: Correct-Course Installed Path Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 15: Correct-Course Installed Path Guard${colors.reset}\n`); + + try { + const workflowPath = path.join(projectRoot, 'src', 'bmm', 'workflows', '4-implementation', 'correct-course', 'workflow.md'); + const content = await fs.readFile(workflowPath, 'utf8'); + + assert( + content.includes('`installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course`'), + 'Correct-course workflow uses installed runtime path', + ); + assert( + content.includes('{project-root}/_bmad/core/tasks/validate-workflow.md'), + 'Correct-course workflow uses installed validate-workflow task path', + ); + } catch (error) { + assert(false, 'Correct-course installed path guard runs', error.message); + } + + console.log(''); + + // ============================================================ + // Test 16: Task/Tool Standalone and CRLF Parsing Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 16: Task/Tool Standalone + CRLF Guard${colors.reset}\n`); + + try { + const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-standalone-crlf-')); + const coreTasksDir = path.join(tmpRoot, '_bmad', 'core', 'tasks'); + const coreToolsDir = path.join(tmpRoot, '_bmad', 'core', 'tools'); + await fs.ensureDir(coreTasksDir); + await fs.ensureDir(coreToolsDir); + + await fs.writeFile( + path.join(coreTasksDir, 'default-task.md'), + `--- +name: default-task +displayName: Default Task +description: Defaults to standalone +--- +`, + ); + + await fs.writeFile( + path.join(coreTasksDir, 'internal-task.md'), + `--- +name: internal-task +displayName: Internal Task +description: Hidden task +internal: true +--- +`, + ); + + await fs.writeFile( + path.join(coreTasksDir, 'crlf-task.md'), + '---\r\nname: crlf-task\r\ndisplayName: CRLF Task\r\ndescription: Parsed from CRLF\r\nstandalone: true\r\n---\r\n', + ); + + await fs.writeFile( + path.join(coreToolsDir, 'default-tool.md'), + `--- +name: default-tool +displayName: Default Tool +description: Defaults to standalone +--- +`, + ); + + await fs.writeFile( + path.join(coreToolsDir, 'internal-tool.md'), + `--- +name: internal-tool +displayName: Internal Tool +description: Hidden tool +internal: true +--- +`, + ); + + await fs.writeFile( + path.join(coreToolsDir, 'crlf-tool.md'), + '---\r\nname: crlf-tool\r\ndisplayName: CRLF Tool\r\ndescription: Parsed from CRLF\r\nstandalone: true\r\n---\r\n', + ); + + const manifestGenerator = new ManifestGenerator(); + const tasks = await manifestGenerator.getTasksFromDir(coreTasksDir, 'core'); + const tools = await manifestGenerator.getToolsFromDir(coreToolsDir, 'core'); + + const defaultTask = tasks.find((task) => task.name === 'default-task'); + const internalTask = tasks.find((task) => task.name === 'internal-task'); + const crlfTask = tasks.find((task) => task.name === 'crlf-task'); + const defaultTool = tools.find((tool) => tool.name === 'default-tool'); + const internalTool = tools.find((tool) => tool.name === 'internal-tool'); + const crlfTool = tools.find((tool) => tool.name === 'crlf-tool'); + + assert(defaultTask?.standalone === true, 'Tasks default to standalone when standalone key is omitted'); + assert(internalTask?.standalone === false, 'Tasks marked internal are excluded from standalone commands'); + assert(crlfTask?.description === 'Parsed from CRLF', 'CRLF task frontmatter is parsed correctly'); + + assert(defaultTool?.standalone === true, 'Tools default to standalone when standalone key is omitted'); + assert(internalTool?.standalone === false, 'Tools marked internal are excluded from standalone commands'); + assert(crlfTool?.description === 'Parsed from CRLF', 'CRLF tool frontmatter is parsed correctly'); + + const taskToolGenerator = new TaskToolCommandGenerator(); + assert(taskToolGenerator.isStandalone({}) === true, 'Task/tool command filter defaults missing standalone metadata to visible'); + assert( + taskToolGenerator.isStandalone({ standalone: 'false' }) === false, + 'Task/tool command filter hides entries explicitly marked standalone=false', + ); + + await fs.remove(tmpRoot); + } catch (error) { + assert(false, 'Task/tool standalone and CRLF guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index f64f72109..22bc21f10 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -383,18 +383,25 @@ class ManifestGenerator { let name = file.replace(/\.(xml|md)$/, ''); let displayName = name; let description = ''; - let standalone = false; + let standalone = true; if (file.endsWith('.md')) { // Parse YAML frontmatter for .md tasks - const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (frontmatterMatch) { try { - const frontmatter = yaml.parse(frontmatterMatch[1]); + const frontmatter = yaml.parse(frontmatterMatch[1]) || {}; name = frontmatter.name || name; displayName = frontmatter.displayName || frontmatter.name || name; description = frontmatter.description || ''; - standalone = frontmatter.standalone === true || frontmatter.standalone === 'true'; + const isInternal = frontmatter.internal === true || frontmatter.internal === 'true'; + if (frontmatter.standalone === true || frontmatter.standalone === 'true') { + standalone = true; + } else if (frontmatter.standalone === false || frontmatter.standalone === 'false') { + standalone = false; + } else { + standalone = !isInternal; + } } catch { // If YAML parsing fails, use defaults } @@ -408,8 +415,16 @@ class ManifestGenerator { const objMatch = content.match(/([^<]+)<\/objective>/); description = descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''; - const standaloneMatch = content.match(/]+standalone="true"/); - standalone = !!standaloneMatch; + const standaloneTrueMatch = content.match(/]+standalone="true"/i); + const standaloneFalseMatch = content.match(/]+standalone="false"/i); + const internalMatch = content.match(/]+internal="true"/i); + if (standaloneFalseMatch) { + standalone = false; + } else if (standaloneTrueMatch) { + standalone = true; + } else { + standalone = !internalMatch; + } } // Build relative path for installation @@ -472,18 +487,25 @@ class ManifestGenerator { let name = file.replace(/\.(xml|md)$/, ''); let displayName = name; let description = ''; - let standalone = false; + let standalone = true; if (file.endsWith('.md')) { // Parse YAML frontmatter for .md tools - const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (frontmatterMatch) { try { - const frontmatter = yaml.parse(frontmatterMatch[1]); + const frontmatter = yaml.parse(frontmatterMatch[1]) || {}; name = frontmatter.name || name; displayName = frontmatter.displayName || frontmatter.name || name; description = frontmatter.description || ''; - standalone = frontmatter.standalone === true || frontmatter.standalone === 'true'; + const isInternal = frontmatter.internal === true || frontmatter.internal === 'true'; + if (frontmatter.standalone === true || frontmatter.standalone === 'true') { + standalone = true; + } else if (frontmatter.standalone === false || frontmatter.standalone === 'false') { + standalone = false; + } else { + standalone = !isInternal; + } } catch { // If YAML parsing fails, use defaults } @@ -497,8 +519,16 @@ class ManifestGenerator { const objMatch = content.match(/([^<]+)<\/objective>/); description = descMatch ? descMatch[1] : objMatch ? objMatch[1].trim() : ''; - const standaloneMatch = content.match(/]+standalone="true"/); - standalone = !!standaloneMatch; + const standaloneTrueMatch = content.match(/]+standalone="true"/i); + const standaloneFalseMatch = content.match(/]+standalone="false"/i); + const internalMatch = content.match(/]+internal="true"/i); + if (standaloneFalseMatch) { + standalone = false; + } else if (standaloneTrueMatch) { + standalone = true; + } else { + standalone = !internalMatch; + } } // Build relative path for installation diff --git a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js index 6690d5c9c..3cfa572f3 100644 --- a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js @@ -25,7 +25,14 @@ class TaskToolCommandGenerator { * @returns {boolean} True when item should be exposed as a command */ isStandalone(item) { - return item?.standalone === 'true' || item?.standalone === true; + if (item?.standalone === false || item?.standalone === 'false') { + return false; + } + if (item?.internal === true || item?.internal === 'true') { + return false; + } + // Backward-compatible default: entries are user-facing unless explicitly hidden. + return true; } /** From d7a55394c5f6dd96ab3100227437721c2de62a72 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 01:18:31 +0000 Subject: [PATCH 19/22] fix: define installed workflow paths in qa and create-story --- src/bmm/workflows/4-implementation/create-story/workflow.md | 3 ++- src/bmm/workflows/qa/automate/workflow.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.md b/src/bmm/workflows/4-implementation/create-story/workflow.md index 5a393e489..7a33d9b1c 100644 --- a/src/bmm/workflows/4-implementation/create-story/workflow.md +++ b/src/bmm/workflows/4-implementation/create-story/workflow.md @@ -14,6 +14,7 @@ web_bundle: false - `sprint_status`, `epics_file`, `prd_file`, `architecture_file`, `ux_file` - `project_context` - `date` (system-generated) + - `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/create-story` Communicate all responses in {communication_language} and generate all documents in {document_output_language} @@ -269,7 +270,7 @@ web_bundle: false - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md Save story document unconditionally diff --git a/src/bmm/workflows/qa/automate/workflow.md b/src/bmm/workflows/qa/automate/workflow.md index cb52e0e49..314a0ec3c 100644 --- a/src/bmm/workflows/qa/automate/workflow.md +++ b/src/bmm/workflows/qa/automate/workflow.md @@ -13,7 +13,7 @@ web_bundle: false - `document_output_language` - `output_folder` - `implementation_artifacts` - - `installed_path` + - `installed_path` = `{project-root}/_bmad/bmm/workflows/qa/automate` - `config_source` - `test_dir` - `source_dir` @@ -29,7 +29,7 @@ web_bundle: false - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md From 00a23349697123c59daed00167040d65bb7dd83a Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 13:07:55 +0000 Subject: [PATCH 20/22] fix: align workflow path guidance with installed runtime --- .augment/code_review_guidelines.yaml | 9 ++++----- .../create-ux-design/steps/step-04-emotional-response.md | 2 +- .../4-implementation/create-story/instructions.xml | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/.augment/code_review_guidelines.yaml b/.augment/code_review_guidelines.yaml index 02e4f2b95..08677c8c0 100644 --- a/.augment/code_review_guidelines.yaml +++ b/.augment/code_review_guidelines.yaml @@ -56,7 +56,7 @@ areas: - "src/**/workflows/**" rules: - id: "workflow_entry_point_required" - description: "Every workflow folder must have workflow.yaml, workflow.md, or workflow.xml as entry point" + description: "Every workflow folder must have workflow.md (or workflow-*.md variant) as entry point" severity: "high" - id: "sharded_workflow_steps_folder" @@ -64,7 +64,7 @@ areas: severity: "high" - id: "standard_workflow_instructions" - description: "Standard workflows using workflow.yaml must include instructions.md for execution guidance" + description: "Standard workflows using workflow.md should include instructions.md for execution guidance" severity: "medium" - id: "workflow_step_limit" @@ -75,11 +75,10 @@ areas: # WORKFLOW ENTRY FILE RULES # ============================================ workflow_definitions: - description: "Workflow entry files (workflow.yaml, workflow.md, workflow.xml)" + description: "Workflow entry files (workflow.md variants)" globs: - - "src/**/workflows/**/workflow.yaml" - "src/**/workflows/**/workflow.md" - - "src/**/workflows/**/workflow.xml" + - "src/**/workflows/**/workflow-*.md" rules: - id: "workflow_name_required" description: "Workflow entry files must define 'name' field in frontmatter or root element" diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md index 1dfb52dd1..6b74fc0fb 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md @@ -30,7 +30,7 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: src/core/workflows/advanced-elicitation/workflow.md +- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md - When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml index e10d70cf1..37dbfee88 100644 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/create-story/instructions.xml @@ -310,7 +310,7 @@ - Validate against checklist at {installed_path}/checklist.md using src/core/tasks/validate-workflow.md + Validate against checklist at {installed_path}/checklist.md using {project-root}/_bmad/core/tasks/validate-workflow.md Save story document unconditionally From 40787c50352cdbc1733b8a2ede48192570d7d4f0 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 13:27:10 +0000 Subject: [PATCH 21/22] fix: restore help routing and external module install tolerance --- src/core/tasks/help.md | 15 ++++++++++- test/test-installation-components.js | 29 +++++++++++++++++++++ tools/cli/installers/lib/modules/manager.js | 4 +-- 3 files changed, 45 insertions(+), 3 deletions(-) diff --git a/src/core/tasks/help.md b/src/core/tasks/help.md index e797d4fdc..a2b414400 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/help.md @@ -49,10 +49,23 @@ Determine what was just completed: **Required items next** — List the next required workflow For each item show: - Workflow **name** - - **Command** (use the catalog command name; present it in your platform's command format, e.g., `bmad-example-build-prototype`) + - **Command** when `command` is present + - **Agent load instruction + code** when `command` is empty - **Agent** title and display name from the CSV (e.g., "🎨 Alex (Designer)") - Brief **description** + ### Display branching rules + - When `command` has a value: + - Present the command in your platform's command format (for example: `bmad-example-build-prototype`) + - When `command` is empty: + - Do not invent a slash command + - Show how to load the agent from `agent` and then invoke using the workflow/code description + - Example: + - `Explain Concept (EC)` + - `Load: /tech-writer, then ask to "EC about [topic]"` + - `Agent: Tech Writer` + - `Description: Create clear technical explanations with examples` + ### Additional response output guidance to convey: - Run each workflow in a **fresh context window** - Load the agent using the platform's command format for `agent-command`, or run the workflow command directly diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 15fe1a087..eefa1ed4a 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -14,6 +14,7 @@ const path = require('node:path'); const os = require('node:os'); const fs = require('fs-extra'); +const csv = require('csv-parse/sync'); const yaml = require('yaml'); const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder'); const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator'); @@ -678,6 +679,34 @@ internal: true console.log(''); + // ============================================================ + // Test 17: Help Task Agent-Only Guidance Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 17: Help Task Agent-Only Guidance Guard${colors.reset}\n`); + + try { + const helpTaskPath = path.join(projectRoot, 'src', 'core', 'tasks', 'help.md'); + const moduleHelpPath = path.join(projectRoot, 'src', 'bmm', 'module-help.csv'); + + const helpTaskContent = await fs.readFile(helpTaskPath, 'utf8'); + const moduleHelpRows = csv.parse(await fs.readFile(moduleHelpPath, 'utf8'), { + columns: true, + skip_empty_lines: true, + }); + + const hasAgentOnlyRows = moduleHelpRows.some((row) => !row.command && row.agent); + assert(hasAgentOnlyRows, 'Help catalog includes agent-only rows with empty command values'); + + assert( + helpTaskContent.includes('When `command` is empty') && helpTaskContent.includes('Do not invent a slash command'), + 'Help task includes explicit guidance for agent-only rows without commands', + ); + } catch (error) { + assert(false, 'Help task agent-only guidance guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index f872582b9..26f08037b 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -416,7 +416,7 @@ class ModuleManager { if (needsDependencyInstall || wasNewClone || nodeModulesMissing) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress', { + execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout @@ -441,7 +441,7 @@ class ModuleManager { if (packageJsonNewer) { const installSpinner = ora(`Installing dependencies for ${moduleInfo.name}...`).start(); try { - execSync('npm install --production --no-audit --no-fund --prefer-offline --no-progress', { + execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', { cwd: moduleCacheDir, stdio: 'pipe', timeout: 120_000, // 2 minute timeout From 129f2d4ac9e897c25a5a6da1bf9331c9fc9d98b2 Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Sun, 8 Feb 2026 14:05:42 +0000 Subject: [PATCH 22/22] fix: hide internal workflow task from codex exports --- test/test-installation-components.js | 35 +++++++++++++++++++ .../lib/ide/shared/bmad-artifacts.js | 30 ++++++++++++++-- 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/test/test-installation-components.js b/test/test-installation-components.js index eefa1ed4a..7c456f570 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -21,6 +21,7 @@ const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest const { WorkflowCommandGenerator } = require('../tools/cli/installers/lib/ide/shared/workflow-command-generator'); const { TaskToolCommandGenerator } = require('../tools/cli/installers/lib/ide/shared/task-tool-command-generator'); const { IdeManager } = require('../tools/cli/installers/lib/ide/manager'); +const { CodexSetup } = require('../tools/cli/installers/lib/ide/codex'); const { ModuleManager } = require('../tools/cli/installers/lib/modules/manager'); const { BMAD_FOLDER_NAME } = require('../tools/cli/installers/lib/ide/shared/path-utils'); @@ -707,6 +708,40 @@ internal: true console.log(''); + // ============================================================ + // Test 18: Codex Task Visibility Guard + // ============================================================ + console.log(`${colors.yellow}Test Suite 18: Codex Task Visibility Guard${colors.reset}\n`); + + try { + const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-codex-visibility-')); + const projectDir = path.join(tmpRoot, 'project'); + const bmadDir = path.join(tmpRoot, BMAD_FOLDER_NAME); + await fs.ensureDir(projectDir); + await fs.copy(path.join(projectRoot, 'src', 'core'), path.join(bmadDir, 'core')); + await fs.copy(path.join(projectRoot, 'src', 'bmm'), path.join(bmadDir, 'bmm')); + + const manifestGenerator = new ManifestGenerator(); + await manifestGenerator.generateManifests(bmadDir, ['bmm'], [], { ides: ['codex'] }); + + const codexSetup = new CodexSetup(); + await codexSetup.setup(projectDir, bmadDir, { + selectedModules: ['bmm'], + preCollectedConfig: { installLocation: 'project' }, + }); + + const promptsDir = path.join(projectDir, '.codex', 'prompts'); + const generated = await fs.readdir(promptsDir); + + assert(!generated.includes('bmad-workflow.md'), 'Codex export excludes internal workflow runner task prompt', generated.join(', ')); + + await fs.remove(tmpRoot); + } catch (error) { + assert(false, 'Codex task visibility guard runs', error.message); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js index 7bcfd6a79..a506d4f0e 100644 --- a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js +++ b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js @@ -1,5 +1,6 @@ const path = require('node:path'); const fs = require('fs-extra'); +const yaml = require('yaml'); /** * Helpers for gathering BMAD agents/tasks from the installed tree. @@ -149,8 +150,33 @@ async function getTasksFromDir(dirPath, moduleName) { const filePath = path.join(dirPath, file); const content = await fs.readFile(filePath, 'utf8'); - // Skip internal/engine files (not user-facing tasks) - if (content.includes('internal="true"')) { + let isInternal = false; + let isStandalone = true; + + if (file.endsWith('.md')) { + // Parse markdown frontmatter for standalone/internal flags. + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + if (frontmatterMatch) { + try { + const frontmatter = yaml.parse(frontmatterMatch[1]) || {}; + isInternal = frontmatter.internal === true || frontmatter.internal === 'true'; + if (frontmatter.standalone === false || frontmatter.standalone === 'false') { + isStandalone = false; + } + } catch { + // Keep defaults when frontmatter parsing fails. + } + } + } else { + // XML tasks rely on attributes for standalone/internal visibility. + isInternal = /internal\s*=\s*["']true["']/i.test(content); + if (/standalone\s*=\s*["']false["']/i.test(content)) { + isStandalone = false; + } + } + + // Skip internal/engine or explicitly non-standalone tasks. + if (isInternal || !isStandalone) { continue; }