diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md deleted file mode 100644 index 05bd180c..00000000 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md +++ /dev/null @@ -1,399 +0,0 @@ -# Senior Developer Review - Workflow Instructions - -````xml -The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} -Generate all documents in {document_output_language} -This workflow performs a SYSTEMATIC Senior Developer Review on a story with status "review", validates EVERY acceptance criterion and EVERY completed task, appends structured review notes with evidence, and updates the story status based on outcome. -If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, offer ad-hoc review option. -Ad-hoc review mode: User can specify any files to review and what to review for (quality, security, requirements, etc.). Creates standalone review report. -SYSTEMATIC VALIDATION REQUIREMENT: For EVERY acceptance criterion, verify implementation with evidence (file:line). For EVERY task marked complete, verify it was actually done. Tasks marked complete but not done = HIGH SEVERITY finding. -⚠ī¸ ZERO TOLERANCE FOR LAZY VALIDATION ⚠ī¸ -If you FAIL to catch even ONE task marked complete that was NOT actually implemented, or ONE acceptance criterion marked done that is NOT in the code with evidence, you have FAILED YOUR ONLY PURPOSE. This is an IMMEDIATE DISQUALIFICATION. No shortcuts. No assumptions. No "looks good enough." You WILL read every file. You WILL verify every claim. You WILL provide evidence (file:line) for EVERY validation. Failure to catch false completions = you failed humanity and the project. Your job is to be the uncompromising gatekeeper. DO YOUR JOB COMPLETELY OR YOU WILL BE REPLACED. -Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section. -Execute ALL steps in exact order; do NOT skip steps - -DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content. -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - - - - Use {{story_path}} directly - Read COMPLETE story file and parse sections - Extract story_key from filename or story metadata - Verify Status is "review" or "ready-for-review" - if not, HALT with message: "Story status must be 'review' or 'ready-for-review' to proceed" - - - - MUST read COMPLETE sprint-status.yaml file from start to end to preserve order - Load the FULL file: {{output_folder}}/sprint-status.yaml - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - - Find FIRST story (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 "review" OR "ready-for-review" - - - - 📋 No stories with status "review" or "ready-for-review" found - -**What would you like to do?** -1. Run `dev-story` to implement and mark a story ready for review -2. Check sprint-status.yaml for current story states -3. Tell me what code to review and what to review it for - - Select an option (1/2/3): - - - What code would you like me to review? - - Provide: - - File path(s) or directory to review - - What to review for: - â€ĸ General quality and standards - â€ĸ Requirements compliance - â€ĸ Security concerns - â€ĸ Performance issues - â€ĸ Architecture alignment - â€ĸ Something else (specify) - - Your input:? - - - Parse user input to extract: - - {{review_files}}: file paths or directories to review - - {{review_focus}}: what aspects to focus on - - {{review_context}}: any additional context provided - - - Set ad_hoc_review_mode = true - Skip to step 4 with custom scope - - - - HALT - - - - Use the first story found with status "review" - Resolve story file path in {{story_dir}} - Read the COMPLETE story file - - - Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata - Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log - HALT with message: "Unable to read story file" - - - - - After discovery, these content variables are available: {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} - - - - Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent. - Continue but record a WARNING in review notes: "No story context file found" - - Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}}) - Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}" - - Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. - Architecture and brownfield docs were pre-loaded in Step 1.5 as {architecture_content} and {document_project_content} - - - - Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.). - Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available). - - - - - Use {{review_files}} as the file list to review - Focus review on {{review_focus}} aspects specified by user - Use {{review_context}} for additional guidance - Skip acceptance criteria checking (no story context) - If architecture docs exist, verify alignment with architectural constraints - - - - SYSTEMATIC VALIDATION - Check EVERY AC and EVERY task marked complete - - From the story, read Acceptance Criteria section completely - parse into numbered list - From the story, read Tasks/Subtasks section completely - parse ALL tasks and subtasks with their completion state ([x] = completed, [ ] = incomplete) - From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks). - - Step 4A: SYSTEMATIC ACCEPTANCE CRITERIA VALIDATION - Create AC validation checklist with one entry per AC - For EACH acceptance criterion (AC1, AC2, AC3, etc.): - 1. Read the AC requirement completely - 2. Search changed files for evidence of implementation - 3. Determine: IMPLEMENTED, PARTIAL, or MISSING - 4. Record specific evidence (file:line references where AC is satisfied) - 5. Check for corresponding tests (unit/integration/E2E as applicable) - 6. If PARTIAL or MISSING: Flag as finding with severity based on AC criticality - 7. Document in AC validation checklist - - Generate AC Coverage Summary: "X of Y acceptance criteria fully implemented" - - Step 4B: SYSTEMATIC TASK COMPLETION VALIDATION - Create task validation checklist with one entry per task/subtask - For EACH task/subtask marked as COMPLETED ([x]): - 1. Read the task description completely - 2. Search changed files for evidence the task was actually done - 3. Determine: VERIFIED COMPLETE, QUESTIONABLE, or NOT DONE - 4. Record specific evidence (file:line references proving task completion) - 5. **CRITICAL**: If marked complete but NOT DONE → Flag as HIGH SEVERITY finding with message: "Task marked complete but implementation not found: [task description]" - 6. If QUESTIONABLE → Flag as MEDIUM SEVERITY finding: "Task completion unclear: [task description]" - 7. Document in task validation checklist - - For EACH task/subtask marked as INCOMPLETE ([ ]): - 1. Note it was not claimed to be complete - 2. Check if it was actually done anyway (sometimes devs forget to check boxes) - 3. If done but not marked: Note in review (helpful correction, not a finding) - - Generate Task Completion Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete" - - Step 4C: CROSS-CHECK EPIC TECH-SPEC REQUIREMENTS - Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files. - flag as High Severity finding. - - Step 4D: COMPILE VALIDATION FINDINGS - Compile all validation findings into structured list: - - Missing AC implementations (severity based on AC importance) - - Partial AC implementations (MEDIUM severity) - - Tasks falsely marked complete (HIGH severity - this is critical) - - Questionable task completions (MEDIUM severity) - - Missing tests for ACs (severity based on AC criticality) - - Architecture violations (HIGH severity) - - - - - - For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns. - Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests). - Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns. - Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections. - - - - Determine outcome based on validation results: - - BLOCKED: Any HIGH severity finding (AC missing, task falsely marked complete, critical architecture violation) - - CHANGES REQUESTED: Any MEDIUM severity findings or multiple LOW severity issues - - APPROVE: All ACs implemented, all completed tasks verified, no significant issues - - - Prepare a structured review report with sections: - 1. **Summary**: Brief overview of review outcome and key concerns - 2. **Outcome**: Approve | Changes Requested | Blocked (with justification) - 3. **Key Findings** (by severity): - - HIGH severity issues first (especially falsely marked complete tasks) - - MEDIUM severity issues - - LOW severity issues - 4. **Acceptance Criteria Coverage**: - - Include complete AC validation checklist from Step 4A - - Show: AC# | Description | Status (IMPLEMENTED/PARTIAL/MISSING) | Evidence (file:line) - - Summary: "X of Y acceptance criteria fully implemented" - - List any missing or partial ACs with severity - 5. **Task Completion Validation**: - - Include complete task validation checklist from Step 4B - - Show: Task | Marked As | Verified As | Evidence (file:line) - - **CRITICAL**: Highlight any tasks marked complete but not done in RED/bold - - Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete" - 6. **Test Coverage and Gaps**: - - Which ACs have tests, which don't - - Test quality issues found - 7. **Architectural Alignment**: - - Tech-spec compliance - - Architecture violations if any - 8. **Security Notes**: Security findings if any - 9. **Best-Practices and References**: With links - 10. **Action Items**: - - CRITICAL: ALL action items requiring code changes MUST have checkboxes for tracking - - Format for actionable items: `- [ ] [Severity] Description (AC #X) [file: path:line]` - - Format for informational notes: `- Note: Description (no action required)` - - Imperative phrasing for action items - - Map to related ACs or files with specific line references - - Include suggested owners if clear - - Example format: - ``` - ### Action Items - - **Code Changes Required:** - - [ ] [High] Add input validation on login endpoint (AC #1) [file: src/routes/auth.js:23-45] - - [ ] [Med] Add unit test for invalid email format [file: tests/unit/auth.test.js] - - **Advisory Notes:** - - Note: Consider adding rate limiting for production deployment - - Note: Document the JWT expiration policy in README - ``` - - - The AC validation checklist and task validation checklist MUST be included in the review - this is the evidence trail - - - - - Generate review report as a standalone document - Save to {{output_folder}}/code-review-{{date}}.md - Include sections: - - Review Type: Ad-Hoc Code Review - - Reviewer: {{user_name}} - - Date: {{date}} - - Files Reviewed: {{review_files}} - - Review Focus: {{review_focus}} - - Outcome: (Approve | Changes Requested | Blocked) - - Summary - - Key Findings - - Test Coverage and Gaps - - Architectural Alignment - - Security Notes - - Best-Practices and References (with links) - - Action Items - - Review saved to: {{output_folder}}/code-review-{{date}}.md - - - - Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)". - Insert subsections: - - Reviewer: {{user_name}} - - Date: {{date}} - - Outcome: (Approve | Changes Requested | Blocked) with justification - - Summary - - Key Findings (by severity - HIGH/MEDIUM/LOW) - - **Acceptance Criteria Coverage**: - * Include complete AC validation checklist with table format - * AC# | Description | Status | Evidence - * Summary: X of Y ACs implemented - - **Task Completion Validation**: - * Include complete task validation checklist with table format - * Task | Marked As | Verified As | Evidence - * **Highlight falsely marked complete tasks prominently** - * Summary: X of Y tasks verified, Z questionable, W false completions - - Test Coverage and Gaps - - Architectural Alignment - - Security Notes - - Best-Practices and References (with links) - - Action Items: - * CRITICAL: Format with checkboxes for tracking resolution - * Code changes required: `- [ ] [Severity] Description [file: path:line]` - * Advisory notes: `- Note: Description (no action required)` - * Group by type: "Code Changes Required" and "Advisory Notes" - - Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended". - If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged. - Save the story file. - - MUST include the complete validation checklists - this is the evidence that systematic review was performed - - - - - - Skip sprint status update (no story context) - 📋 Ad-hoc review complete - no sprint status to update - - - - Determine target status based on review outcome: - - If {{outcome}} == "Approve" → target_status = "done" - - If {{outcome}} == "Changes Requested" → target_status = "in-progress" - - If {{outcome}} == "Blocked" → target_status = "review" (stay in review) - - - Load the FULL file: {{output_folder}}/sprint-status.yaml - Read all development_status entries to find {{story_key}} - Verify current status is "review" (expected previous state) - Update development_status[{{story_key}}] = {{target_status}} - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ✅ Sprint status updated: review → {{target_status}} - - - - ⚠ī¸ Could not update sprint-status: {{story_key}} not found - -Review was saved to story file, but sprint-status.yaml may be out of sync. - - - - - - - - All action items are included in the standalone review report - Would you like me to create tracking items for these action items? (backlog/tasks) - - If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location. - Append a row per action item with Date={{date}}, Story="Ad-Hoc Review", Epic="N/A", Type, Severity, Owner (or "TBD"), Status="Open", Notes with file refs and context. - - - - - Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references. - Add {{action_item_count}} follow-up items to story Tasks/Subtasks? - - Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)". - - - If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location. - Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs. - - - If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}. - - Save modified files. - Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes). - - - - - Run validation checklist at {installed_path}/checklist.md using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml - Report workflow completion. - - - **✅ Ad-Hoc Code Review Complete, {user_name}!** - -**Review Details:** -- Files Reviewed: {{review_files}} -- Review Focus: {{review_focus}} -- Review Outcome: {{outcome}} -- Action Items: {{action_item_count}} -- Review Report: {{output_folder}}/code-review-{{date}}.md - -**Next Steps:** -1. Review the detailed findings in the review report -2. If changes requested: Address action items in the code -3. If blocked: Resolve blockers before proceeding -4. Re-run review on updated code if needed - - - - - **✅ Story Review Complete, {user_name}!** - -**Story Details:** -- Story: {{epic_num}}.{{story_num}} -- Story Key: {{story_key}} -- Review Outcome: {{outcome}} -- Sprint Status: {{target_status}} -- Action Items: {{action_item_count}} - -**Next Steps:** -1. Review the Senior Developer Review notes appended to story -2. If approved: Story is marked done, continue with next story -3. If changes requested: Address action items and re-run `dev-story` -4. If blocked: Resolve blockers before proceeding - - - - - -```` diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml index 6e896a97..12d64c41 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml @@ -3,6 +3,8 @@ You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} + ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or + updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. đŸ”Ĩ YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! đŸ”Ĩ Your purpose: Validate story file claims against actual implementation @@ -173,4 +175,4 @@ - \ No newline at end of file + diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md deleted file mode 100644 index 5988853a..00000000 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md +++ /dev/null @@ -1,257 +0,0 @@ -# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default) - -````xml -The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Generate all documents in {document_output_language} -This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context. -DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks. -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - - - Resolve variables from config_source: story_dir (sprint_artifacts), output_folder, user_name, communication_language. If story_dir missing → ASK user to provide a stories directory and update variable. - Create {{story_dir}} if it does not exist - Resolve installed component paths from workflow.yaml: template, instructions, validation - Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns. - - - - - After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content}, {document_project_content} - - - - PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development - - Find the previous completed story to extract dev agent learnings and review findings: - 1. Load {{output_folder}}/sprint-status.yaml COMPLETELY - 2. Find current {{story_key}} in development_status section - 3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order) - 4. If previous story exists: - - Extract {{previous_story_key}} - - Check previous story status (done, in-progress, review, etc.) - - If status is "done", "review", or "in-progress" (has some completion): - * Construct path: {{story_dir}}/{{previous_story_key}}.md - * Load the COMPLETE previous story file - * Parse ALL sections comprehensively: - - A) Dev Agent Record → Completion Notes List: - - New patterns/services created (to reuse, not recreate) - - Architectural deviations or decisions made - - Technical debt deferred to future stories - - Warnings or recommendations for next story - - Interfaces/methods created for reuse - - B) Dev Agent Record → Debug Log References: - - Issues encountered and solutions - - Gotchas or unexpected challenges - - Workarounds applied - - C) Dev Agent Record → File List: - - Files created (NEW) - understand new capabilities - - Files modified (MODIFIED) - track evolving components - - Files deleted (DELETED) - removed functionality - - D) Dev Notes: - - Any "future story" notes or TODOs - - Patterns established - - Constraints discovered - - E) Senior Developer Review (AI) section (if present): - - Review outcome (Approve/Changes Requested/Blocked) - - Unresolved action items (unchecked [ ] items) - - Key findings that might affect this story - - Architectural concerns raised - - F) Senior Developer Review → Action Items (if present): - - Check for unchecked [ ] items still pending - - Note any systemic issues that apply to multiple stories - - G) Review Follow-ups (AI) tasks (if present): - - Check for unchecked [ ] review tasks still pending - - Determine if they're epic-wide concerns - - H) Story Status: - - If "review" or "in-progress" - incomplete, note what's pending - - If "done" - confirmed complete - * Store ALL findings as {{previous_story_learnings}} with structure: - - new_files: [list] - - modified_files: [list] - - new_services: [list with descriptions] - - architectural_decisions: [list] - - technical_debt: [list] - - warnings_for_next: [list] - - review_findings: [list if review exists] - - pending_items: [list of unchecked action items] - - If status is "backlog" or "drafted": - * Set {{previous_story_learnings}} = "Previous story not yet implemented" - 5. If no previous story exists (first story in epic): - - Set {{previous_story_learnings}} = "First story in epic - no predecessor context" - - - If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time. - Build a prioritized document set for this epic - search and load from {input_file_patterns} list of potential locations: - 1) tech_spec_file (epic-scoped) - 2) epics_file (acceptance criteria and breakdown) the specific epic the story will be part of - 3) prd_file (business requirements and constraints) whole or sharded - 4) architecture_file (architecture constraints) whole or sharded - - READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation. - - - - MUST read COMPLETE {sprint_status} file from start to end to preserve order - 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 "backlog" - - - - 📋 No backlog stories found in sprint-status.yaml - - All stories are either already drafted or completed. - - **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 - - 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") - - Verify story is enumerated in {{epics_file}}. If not found, HALT with message: - "Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story." - - Check if story file already exists at expected path in {{story_dir}} - - ℹī¸ Story file already exists: {{story_file_path}} -Will update existing story file rather than creating new one. - - Set update_mode = true - - - - - From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story. - From architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story. - Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts. - requirements_context_summary - - - - Review {{previous_story_learnings}} and extract actionable intelligence: - - New patterns/services created → Note for reuse (DO NOT recreate) - - Architectural deviations → Understand and maintain consistency - - Technical debt items → Assess if this story should address them - - Files modified → Understand current state of evolving components - - Warnings/recommendations → Apply to this story's approach - - Review findings → Learn from issues found in previous story - - Pending action items → Determine if epic-wide concerns affect this story - - - If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts. - - Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located. - - structure_alignment_summary - - - - Assemble acceptance criteria list from tech_spec or epics. If gaps exist, derive minimal, testable criteria from PRD verbatim phrasing (NO invention). - Create tasks/subtasks directly mapped to ACs. Include explicit testing subtasks per testing-strategy and existing tests framework. Cite architecture/source documents for any technical mandates. - acceptance_criteria - tasks_subtasks - - - - Resolve output path: {default_output_file} using current {{epic_num}} and {{story_num}}. If targeting an existing story for update, use its path. - Initialize from template.md if creating a new file; otherwise load existing file for edit. - Compute a concise story_title from epic/story context; if missing, synthesize from PRD feature name and epic number. - story_header - story_body - dev_notes_with_citations - - If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"): - - Add "Learnings from Previous Story" subsection to Dev Notes - - Include relevant completion notes, new files/patterns, deviations - - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md] - - Highlight interfaces/services to REUSE (not recreate) - - Note any technical debt to address in this story - - List pending review items that affect this story (if any) - - Reference specific files created: "Use {{file_path}} for {{purpose}}" - - Format example: - ``` - ### Learnings from Previous Story - - **From Story {{previous_story_key}} (Status: {{previous_status}})** - - - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method - - **Architectural Change**: Switched from session-based to JWT authentication - - **Schema Changes**: User model now includes `passwordHash` field, migration applied - - **Technical Debt**: Email verification skipped, should be included in this or subsequent story - - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there - - **Pending Review Items**: Rate limiting mentioned in review - consider for this story - - [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record] - ``` - - - change_log - - - - Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml - Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation. - - - Update {{output_folder}}/sprint-status.yaml - 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}}] = "drafted" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ⚠ī¸ Could not update story status: {{story_key}} not found in sprint-status.yaml - -Story file was created successfully, but sprint-status.yaml was not updated. -You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`. - - - - Report created/updated story path - **✅ Story Created Successfully, {user_name}!** - -**Story Details:** - -- Story ID: {{story_id}} -- Story Key: {{story_key}} -- File: {{story_file}} -- Status: drafted (was backlog) - -**⚠ī¸ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command. - -**Next Steps:** - -1. Review the drafted story in {{story_file}} -2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step) -3. Or run `story-ready` to manually mark the story ready without generating technical context - - - - -```` diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml index 14351805..9142bae2 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml @@ -2,6 +2,8 @@ The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and generate all documents in {document_output_language} + ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or + updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. đŸ”Ĩ CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or disasters! đŸ”Ĩ @@ -321,4 +323,4 @@ - \ No newline at end of file + diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md deleted file mode 100644 index 655bfd5a..00000000 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md +++ /dev/null @@ -1,268 +0,0 @@ -# Develop Story - Workflow Instructions - -```xml -The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -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. -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - - - - Use {{story_path}} directly - Read COMPLETE story file - Extract story_key from filename or metadata - task_check - - - MUST read COMPLETE sprint-status.yaml file from start to end to preserve order - Load the FULL file: {{output_folder}}/sprint-status.yaml - 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 -**Options:** -1. Run `story-context` to generate context file and mark drafted stories as ready -2. Run `story-ready` to quickly mark drafted stories as ready without generating context -3. Run `create-story` if no incomplete stories are drafted yet -4. Check {output_folder}/sprint-status.yaml to see current sprint status - - HALT - - - 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 - - Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml - - Read COMPLETE context file - Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests - Use this context to inform implementation decisions and approaches - - - ℹī¸ No context file found for {{story_key}} - -Proceeding with story file only. For better context, consider running `story-context` workflow first. - - - - 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 - - - - - After discovery, these content variables are available: {architecture_content}, {tech_spec_content}, {ux_design_content}, {epics_content} (selective load), {document_project_content} - - - - 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}} -Context file: {{context_available}} -First incomplete task: {{first_task_description}} - - - - - - Load the FULL file: {{output_folder}}/sprint-status.yaml - 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... - - - - - - Review acceptance criteria and dev notes for the selected task - Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log - Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions - Handle error conditions and edge cases appropriately - ASK user for approval before adding - HALT and request guidance - HALT: "Cannot proceed without necessary configuration files" - Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers - Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied - - - - Create unit tests for business logic and core functionality introduced/changed by the task - Add integration tests for component interactions where desired by test plan or story notes - Include end-to-end tests for critical user flows where desired by test plan or story notes - Cover edge cases and error handling scenarios noted in the test plan or story notes - - - - Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided) - Run all existing tests to ensure no regressions - Run the new tests to verify implementation correctness - Run linting and code quality checks if configured - Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete - STOP and fix before continuing, consider how current changes made broke regression - STOP and fix before continuing - - - - If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section - - Check if completed task has [AI-Review] prefix (indicates review follow-up task) - - - 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 mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds - Update File List section with any new, modified, or deleted files (paths relative to repo root) - Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups) - - - 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 story definition-of-done checklist, if the story includes one - Update the story Status to: review - - - Load the FULL file: {{output_folder}}/sprint-status.yaml - 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 file updated, but sprint-status update failed: {{story_key}} not found - -Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync. - - - - Return to step 1 to complete remaining work (Do NOT finish with partial progress) - STOP and resolve before completing - Update it before completing - - - - Optionally run the workflow validation task against the story using {project-root}/{bmad_folder}/core/tasks/validate-workflow.xml - 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", was "in-progress") - - 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 - Common next steps to suggest (but allow user flexibility): - - Review the implemented story yourself and test the changes - - Verify all acceptance criteria are met - - Ensure deployment readiness if applicable - - Run `code-review` workflow for peer review - - Check sprint-status.yaml to see project progress - - Remain flexible - allow user to choose their own path or ask for other assistance - - - -``` diff --git a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml index 6de3bc6b..651d26b7 100644 --- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.xml @@ -3,6 +3,8 @@ You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} + ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or + updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. 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 @@ -401,4 +403,4 @@ Remain flexible - allow user to choose their own path or ask for other assistance - \ No newline at end of file + diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md deleted file mode 100644 index e5ff2cb4..00000000 --- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md +++ /dev/null @@ -1,165 +0,0 @@ - - -```xml -The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} -This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping. -If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed. -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - - Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths. - ask the user for file paths. HALT and wait for docs to proceed - - - MUST read COMPLETE {sprint-status} file to discover next epic - Read ALL development_status entries - Find all epics with status "backlog" (not yet contexted) - Identify the FIRST backlog epic as the suggested default - - - 📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}} - Use this epic? -- [y] Yes, use {{suggested_epic_id}} -- [n] No, let me specify a different epic_id - - - - Enter the epic_id you want to context - Store user-provided epic_id as {{epic_id}} - - - - Use {{suggested_epic_id}} as {{epic_id}} - - - - - ✅ All epics are already contexted! - -No epics with status "backlog" found in sprint-status.yaml. - - Do you want to re-context an existing epic? Enter epic_id or [q] to quit: - - - Store as {{epic_id}} - - - - HALT - No work needed - - - - Resolve output file path using workflow variables and initialize by writing the template. - - - - - After discovery, these content variables are available: {prd_content}, {gdd_content}, {architecture_content}, {ux_design_content}, {epics_content} (will load only epic-{{epic_id}}.md if sharded), {document_project_content} - Extract {{epic_title}} from {prd_content} or {epics_content} based on {{epic_id}}. - - - - Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1) - Get current status value if epic exists - - - ⚠ī¸ Epic {{epic_id}} not found in sprint-status.yaml - -This epic hasn't been registered in the sprint plan yet. -Run sprint-planning workflow to initialize epic tracking. - - HALT - - - - ℹī¸ Epic {{epic_id}} already marked as contexted - -Continuing to regenerate tech spec... - - - - - - Read COMPLETE found {recommended_inputs}. - - Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals - Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets - Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints) - - - - - Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate. - - Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners - Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available - Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes) - Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow) - - - - - - Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture - Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections - Replace {{nfr_reliability}} with availability, recovery, and degradation behavior - Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals - - - - - Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json). - - Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known - - - - - Extract acceptance criteria from PRD; normalize into atomic, testable statements. - - Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria - Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea - - - - - - Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step - Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases) - - - - - Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml - - - Load the FULL file: {sprint_status} - Find development_status key "epic-{{epic_id}}" - Verify current status is "backlog" (expected previous state) - Update development_status["epic-{{epic_id}}"] = "contexted" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ⚠ī¸ Could not update epic status: epic-{{epic_id}} not found - - - **✅ Tech Spec Generated Successfully, {user_name}!** - -**Epic Details:** -- Epic ID: {{epic_id}} -- Epic Title: {{epic_title}} -- Tech Spec File: {{default_output_file}} -- Epic Status: contexted (was backlog) - -**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed. - -**Next Steps:** -1. Load SM agent and run `create-story` to begin implementing the first story under this epic. - - - - -``` diff --git a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md deleted file mode 100644 index 87358b6d..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ /dev/null @@ -1,210 +0,0 @@ - - -```xml -The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} -Generate all documents in {document_output_language} -This workflow assembles a Story Context file for a single drafted story by extracting acceptance criteria, tasks, relevant docs/code, interfaces, constraints, and testing guidance. -If {story_path} is provided, use it. Otherwise, find the first story with status "drafted" in sprint-status.yaml. If none found, HALT. -Check if context file already exists. If it does, ask user if they want to replace it, verify it, or cancel. - -DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only. -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - - - Use {{story_path}} directly - Read COMPLETE story file and parse sections - Extract story_key from filename or story metadata - Verify Status is "drafted" - if not, HALT with message: "Story status must be 'drafted' to generate context" - - - - MUST read COMPLETE sprint-status.yaml file from start to end to preserve order - Load the FULL file: {{output_folder}}/sprint-status.yaml - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - - Find FIRST story (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 "drafted" - - - - 📋 No drafted stories found in sprint-status.yaml - All stories are either still in backlog or already marked ready/in-progress/done. - - **Next Steps:** - 1. Run `create-story` to draft more stories - 2. Run `sprint-planning` to refresh story tracking - - HALT - - - Use the first drafted story found - Find matching story file in {{story_path}} using story_key pattern - Read the COMPLETE story file - - - Extract {{epic_id}}, {{story_id}}, {{story_title}}, {{story_status}} from filename/content - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes - Extract user story fields (asA, iWant, soThat) - story_tasks - acceptance_criteria - - - Check if file exists at {default_output_file} - - - ⚠ī¸ Context file already exists: {default_output_file} - - **What would you like to do?** - 1. **Replace** - Generate new context file (overwrites existing) - 2. **Verify** - Validate existing context file - 3. **Cancel** - Exit without changes - - Choose action (replace/verify/cancel): - - - GOTO validation_step - - - - HALT with message: "Context generation cancelled" - - - - Continue to generate new context file - - - - Store project root path for relative path conversion: extract from {project-root} variable - Define path normalization function: convert any absolute path to project-relative by removing project root prefix - Initialize output by writing template to {default_output_file} - as_a - i_want - so_that - - - - - After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content} - - - - Review loaded content from Step 1.5 for items relevant to this story's domain (use keywords from story title, ACs, and tasks). - Extract relevant sections from: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {document_project_content} - Note: Tech-Spec ({tech_spec_content}) is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance. - For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md"). - - Add artifacts.docs entries with {path, title, section, snippet}: - - path: PROJECT-RELATIVE path only (strip {project-root} prefix) - - title: Document title - - section: Relevant section name - - snippet: Brief excerpt (2-3 sentences max, NO invention) - - - - - Search source tree for modules, files, and symbols matching story intent and AC keywords (controllers, services, components, tests). - Identify existing interfaces/APIs the story should reuse rather than recreate. - Extract development constraints from Dev Notes and architecture (patterns, layers, testing requirements). - For all discovered code artifacts: convert absolute paths to project-relative format (strip {project-root} prefix). - - Add artifacts.code entries with {path, kind, symbol, lines, reason}: - - path: PROJECT-RELATIVE path only (e.g., "src/services/api.js" not full path) - - kind: file type (controller, service, component, test, etc.) - - symbol: function/class/interface name - - lines: line range if specific (e.g., "45-67") - - reason: brief explanation of relevance to this story - - Populate interfaces with API/interface signatures: - - name: Interface or API name - - kind: REST endpoint, GraphQL, function signature, class interface - - signature: Full signature or endpoint definition - - path: PROJECT-RELATIVE path to definition - - Populate constraints with development rules: - - Extract from Dev Notes and architecture - - Include: required patterns, layer restrictions, testing requirements, coding standards - - - - - Detect dependency manifests and frameworks in the repo: - - Node: package.json (dependencies/devDependencies) - - Python: pyproject.toml/requirements.txt - - Go: go.mod - - Unity: Packages/manifest.json, Assets/, ProjectSettings/ - - Other: list notable frameworks/configs found - - Populate artifacts.dependencies with keys for detected ecosystems and their packages with version ranges where present - - - - - From Dev Notes, architecture docs, testing docs, and existing tests, extract testing standards (frameworks, patterns, locations). - - Populate tests.standards with a concise paragraph - Populate tests.locations with directories or glob patterns where tests live - Populate tests.ideas with initial test ideas mapped to acceptance criteria IDs - - - - - - Validate output context file structure and content - Validate against checklist at {installed_path}/checklist.md using {bmad_folder}/core/tasks/validate-workflow.xml - - - - Open {{story_path}} - Find the "Status:" line (usually at the top) - Update story file: Change Status to "ready-for-dev" - Under 'Dev Agent Record' → 'Context Reference' (create if missing), add or update a list item for {default_output_file}. - Save the story file. - - - Load the FULL file: {{output_folder}}/sprint-status.yaml - Find development_status key matching {{story_key}} - Verify current status is "drafted" (expected previous state) - Update development_status[{{story_key}}] = "ready-for-dev" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ⚠ī¸ Story file updated, but could not update sprint-status: {{story_key}} not found - -You may need to run sprint-planning to refresh tracking. - - - - ✅ Story context generated successfully, {user_name}! - -**Story Details:** - -- Story: {{epic_id}}.{{story_id}} - {{story_title}} -- Story Key: {{story_key}} -- Context File: {default_output_file} -- Status: drafted → ready-for-dev - -**Context Includes:** - -- Documentation artifacts and references -- Existing code and interfaces -- Dependencies and frameworks -- Testing standards and ideas -- Development constraints - -**Next Steps:** - -1. Review the context file: {default_output_file} -2. Run `dev-story` to implement the story -3. Generate context for more drafted stories if needed - - - - -``` diff --git a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md deleted file mode 100644 index 0ae5aab7..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md +++ /dev/null @@ -1,112 +0,0 @@ -# Story Approved Workflow Instructions (DEV Agent) - -The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - -This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete) -Workflow: Update story file status to Done - - - - - Use {story_path} directly - Read COMPLETE story file and parse sections - Extract story_key from filename or story metadata - Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done" - - - - MUST read COMPLETE sprint-status.yaml file from start to end to preserve order - Load the FULL file: {output_folder}/sprint-status.yaml - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - -Find FIRST story (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 "review" - - - - 📋 No stories with status "review" found - -All stories are either still in development or already done. - -**Next Steps:** - -1. Run `dev-story` to implement stories -2. Run `code-review` if stories need review first -3. Check sprint-status.yaml for current story states - - HALT - - -Use the first reviewed story found -Find matching story file in {story_dir} using story_key pattern -Read the COMPLETE story file - - -Extract story_id and story_title from the story file - -Find the "Status:" line (usually at the top) -Update story file: Change Status to "done" - -Add completion notes to Dev Agent Record section: -Find "## Dev Agent Record" section and add: - -``` -### Completion Notes -**Completed:** {date} -**Definition of Done:** All acceptance criteria met, code reviewed, tests passing -``` - - - -Save the story file - - - -Load the FULL file: {output_folder}/sprint-status.yaml -Find development_status key matching {story_key} -Verify current status is "review" (expected previous state) -Update development_status[{story_key}] = "done" -Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ⚠ī¸ Story file updated, but could not update sprint-status: {story_key} not found - -Story is marked Done in file, but sprint-status.yaml may be out of sync. - - - - - - - -**Story Approved and Marked Done, {user_name}!** - -✅ Story file updated → Status: done -✅ Sprint status updated: review → done - -**Completed Story:** - -- **ID:** {story_id} -- **Key:** {story_key} -- **Title:** {story_title} -- **Completed:** {date} - -**Next Steps:** - -1. Continue with next story in your backlog - - Run `create-story` for next backlog story - - Or run `dev-story` if ready stories exist -2. Check epic completion status - - Run `retrospective` workflow to check if epic is complete - - Epic retrospective will verify all stories are done - - - - - -``` diff --git a/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md b/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md deleted file mode 100644 index 21d5e45d..00000000 --- a/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md +++ /dev/null @@ -1,118 +0,0 @@ -# Story Ready Workflow Instructions (SM Agent) - -The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} -Generate all documents in {document_output_language} -ALWAYS reload {{sprint_status}} (docs/sprint-artifacts/sprint-status.yaml by default) from disk immediately before reading or updating statuses. Multiple workflows change this file between runs; never rely on a previously loaded copy or cached memory. - - - -This workflow is run by SM agent AFTER user reviews a drafted story and confirms it's ready for development -Simple workflow: Update story file status to Ready - - - -If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready - -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 ALL stories (reading in order from start to end) 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 "drafted" - - -Collect up to 10 drafted story keys in order (limit for display purposes) -Count total drafted stories found - - - 📋 No drafted stories found in {sprint_status} - -All stories are either still in backlog or already marked ready/in-progress/done. - -**Options:** - -1. Run `create-story` to draft more stories -2. Run `sprint-planning` to refresh story tracking - - HALT - - -Display available drafted stories: - -**Drafted Stories Available ({{drafted_count}} found):** - -{{list_of_drafted_story_keys}} - - - -Select the drafted story to mark as Ready (enter story key or number): -Auto-select first story from the list - -Resolve selected story_key from user input or auto-selection -Find matching story file in {{story_dir}} using story_key pattern - - - -Read the story file from resolved path -Extract story_id and story_title from the file - -Find the "Status:" line (usually at the top) -Update story file: Change Status to "ready-for-dev" -Save the story file - - - -Load the FULL file: {sprint_status} -Find development_status key matching {{story_key}} -Verify current status is "drafted" (expected previous state) -Update development_status[{{story_key}}] = "ready-for-dev" -Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - ⚠ī¸ Story file updated, but could not update sprint-status: {{story_key}} not found - -You may need to run sprint-planning to refresh tracking. - - - - - - - -**Story Marked Ready for Development, {user_name}!** - -✅ Story file updated: `{{story_file}}` → Status: ready-for-dev -✅ Sprint status updated: drafted → ready-for-dev - -**Story Details:** - -- **ID:** {{story_id}} -- **Key:** {{story_key}} -- **Title:** {{story_title}} -- **File:** `{{story_file}}` -- **Status:** ready-for-dev - -**Next Steps:** - -1. **Recommended:** Run `story-context` workflow to generate implementation context - - This creates a comprehensive context XML for the DEV agent - - Includes relevant architecture, dependencies, and existing code - -2. **Alternative:** Skip context generation and go directly to `dev-story` workflow - - Faster, but DEV agent will have less context - - Only recommended for simple, well-understood stories - -**To proceed:** - -- For context generation: Stay with SM agent and run `story-context` workflow -- For direct implementation: Load DEV agent and run `dev-story` workflow - - - -