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 9cfefd46c..5c3511d66 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 0febf9763..6b9480f79 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/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index 0d0b3addc..2eef1a83d 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -773,8 +773,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 { @@ -1125,7 +1125,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) { await prompts.log.warn(` Could not parse workflow path: ${sourceWorkflowPath}`); continue; @@ -1134,20 +1134,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) { await prompts.log.warn(` 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))) { @@ -1157,17 +1159,18 @@ class ModuleManager { // Copy the entire workflow folder await prompts.log.message( - ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.md$/, '')}`, + ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(workflowSuffixPattern, '')} → ${installModule}/workflows/${installWorkflowSubPath.replace(workflowSuffixPattern, '')}`, ); await fs.ensureDir(path.dirname(actualDestWorkflowPath)); // 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); } } }