frappe-builder 1.1.0-dev.8

package/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md

@@ -0,0 +1,255 @@
+# Step 3: Generate Epics and Stories
+
+## STEP GOAL:
+
+To generate all epics with their stories based on the approved epics_list, following the template structure exactly.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process epics sequentially
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring story creation and acceptance criteria expertise
+- ✅ User brings their implementation priorities and constraints
+
+### Step-Specific Rules:
+
+- 🎯 Generate stories for each epic following the template exactly
+- 🚫 FORBIDDEN to deviate from template structure
+- 💬 Each story must have clear acceptance criteria
+- 🚪 ENSURE each story is completable by a single dev agent
+- 🔗 **CRITICAL: Stories MUST NOT depend on future stories within the same epic**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate stories collaboratively with user input
+- 💾 Append epics and stories to {planning_artifacts}/epics.md following template
+- 📖 Process epics one at a time in sequence
+- 🚫 FORBIDDEN to skip any epic or rush through stories
+
+## STORY GENERATION PROCESS:
+
+### 1. Load Approved Epic Structure
+
+Load {planning_artifacts}/epics.md and review:
+
+- Approved epics_list from Step 2
+- FR coverage map
+- All requirements (FRs, NFRs, additional, **UX Design requirements if present**)
+- Template structure at the end of the document
+
+**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic.
+
+### 2. Explain Story Creation Approach
+
+**STORY CREATION GUIDELINES:**
+
+For each epic, create stories that:
+
+- Follow the exact template structure
+- Are sized for single dev agent completion
+- Have clear user value
+- Include specific acceptance criteria
+- Reference requirements being fulfilled
+
+**🚨 DATABASE/ENTITY CREATION PRINCIPLE:**
+Create tables/entities ONLY when needed by the story:
+
+- ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
+- ✅ RIGHT: Each story creates/alters ONLY the tables it needs
+
+**🔗 STORY DEPENDENCY PRINCIPLE:**
+Stories must be independently completable in sequence:
+
+- ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
+- ✅ RIGHT: Each story can be completed based only on previous stories
+- ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
+- ✅ RIGHT: "This story works independently and enables future stories"
+
+**STORY FORMAT (from template):**
+
+```
+### Story {N}.{M}: {story_title}
+
+As a {user_type},
+I want {capability},
+So that {value_benefit}.
+
+**Acceptance Criteria:**
+
+**Given** {precondition}
+**When** {action}
+**Then** {expected_outcome}
+**And** {additional_criteria}
+```
+
+**✅ GOOD STORY EXAMPLES:**
+
+_Epic 1: User Authentication_
+
+- Story 1.1: User Registration with Email
+- Story 1.2: User Login with Password
+- Story 1.3: Password Reset via Email
+
+_Epic 2: Content Creation_
+
+- Story 2.1: Create New Blog Post
+- Story 2.2: Edit Existing Blog Post
+- Story 2.3: Publish Blog Post
+
+**❌ BAD STORY EXAMPLES:**
+
+- Story: "Set up database" (no user value)
+- Story: "Create all models" (too large, no user value)
+- Story: "Build authentication system" (too large)
+- Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
+- Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)
+
+### 3. Process Epics Sequentially
+
+For each epic in the approved epics_list:
+
+#### A. Epic Overview
+
+Display:
+
+- Epic number and title
+- Epic goal statement
+- FRs covered by this epic
+- Any NFRs or additional requirements relevant
+- Any UX Design Requirements (UX-DRs) relevant to this epic
+
+#### B. Story Breakdown
+
+Work with user to break down the epic into stories:
+
+- Identify distinct user capabilities
+- Ensure logical flow within the epic
+- Size stories appropriately
+
+#### C. Generate Each Story
+
+For each story in the epic:
+
+1. **Story Title**: Clear, action-oriented
+2. **User Story**: Complete the As a/I want/So that format
+3. **Acceptance Criteria**: Write specific, testable criteria
+
+**AC Writing Guidelines:**
+
+- Use Given/When/Then format
+- Each AC should be independently testable
+- Include edge cases and error conditions
+- Reference specific requirements when applicable
+
+#### D. Collaborative Review
+
+After writing each story:
+
+- Present the story to user
+- Ask: "Does this story capture the requirement correctly?"
+- "Is the scope appropriate for a single dev session?"
+- "Are the acceptance criteria complete and testable?"
+
+#### E. Append to Document
+
+When story is approved:
+
+- Append it to {planning_artifacts}/epics.md following template structure
+- Use correct numbering (Epic N, Story M)
+- Maintain proper markdown formatting
+
+### 4. Epic Completion
+
+After all stories for an epic are complete:
+
+- Display epic summary
+- Show count of stories created
+- Verify all FRs for the epic are covered
+- Get user confirmation to proceed to next epic
+
+### 5. Repeat for All Epics
+
+Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).
+
+### 6. Final Document Completion
+
+After all epics and stories are generated:
+
+- Verify the document follows template structure exactly
+- Ensure all placeholders are replaced
+- Confirm all FRs are covered
+- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input)
+- Check formatting consistency
+
+## TEMPLATE STRUCTURE COMPLIANCE:
+
+The final {planning_artifacts}/epics.md must follow this structure exactly:
+
+1. **Overview** section with project name
+2. **Requirements Inventory** with all three subsections populated
+3. **FR Coverage Map** showing requirement to epic mapping
+4. **Epic List** with approved epic structure
+5. **Epic sections** for each epic (N = 1, 2, 3...)
+   - Epic title and goal
+   - All stories for that epic (M = 1, 2, 3...)
+     - Story title and user story
+     - Acceptance Criteria using Given/When/Then format
+
+### 7. Present FINAL MENU OPTIONS
+
+After all epics and stories are complete:
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill
+- IF P: Invoke the `bmad-party-mode` skill
+- IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `./step-04-final-validation.md` to begin final validation phase.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed in sequence
+- Stories created for each epic
+- Template structure followed exactly
+- All FRs covered by stories
+- Stories appropriately sized
+- Acceptance criteria are specific and testable
+- Document is complete and ready for development
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from template structure
+- Missing epics or stories
+- Stories too large or unclear
+- Missing acceptance criteria
+- Not following proper formatting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md

@@ -0,0 +1,131 @@
+# Step 4: Final Validation
+
+## STEP GOAL:
+
+To validate complete coverage of all requirements and ensure stories are ready for development.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process validation sequentially without skipping
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring validation expertise and quality assurance
+- ✅ User brings their implementation priorities and final review
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validating complete requirements coverage
+- 🚫 FORBIDDEN to skip any validation checks
+- 💬 Validate FR coverage, story completeness, and dependencies
+- 🚪 ENSURE all stories are ready for development
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Validate every requirement has story coverage
+- 💾 Check story dependencies and flow
+- 📖 Verify architecture compliance
+- 🚫 FORBIDDEN to approve incomplete coverage
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete epic and story breakdown from previous steps
+- Focus: Final validation of requirements coverage and story readiness
+- Limits: Validation only, no new content creation
+- Dependencies: Completed story generation from Step 3
+
+## VALIDATION PROCESS:
+
+### 1. FR Coverage Validation
+
+Review the complete epic and story breakdown to ensure EVERY FR is covered:
+
+**CRITICAL CHECK:**
+
+- Go through each FR from the Requirements Inventory
+- Verify it appears in at least one story
+- Check that acceptance criteria fully address the FR
+- No FRs should be left uncovered
+
+### 2. Architecture Implementation Validation
+
+**Check for Starter Template Setup:**
+
+- Does Architecture document specify a starter template?
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- This includes cloning, installing dependencies, initial configuration
+
+**Database/Entity Creation Validation:**
+
+- Are database tables/entities created ONLY when needed by stories?
+- ❌ WRONG: Epic 1 creates all tables upfront
+- ✅ RIGHT: Tables created as part of the first story that needs them
+- Each story should create/modify ONLY what it needs
+
+### 3. Story Quality Validation
+
+**Each story must:**
+
+- Be completable by a single dev agent
+- Have clear acceptance criteria
+- Reference specific FRs it implements
+- Include necessary technical details
+- **Not have forward dependencies** (can only depend on PREVIOUS stories)
+- Be implementable without waiting for future stories
+
+### 4. Epic Structure Validation
+
+**Check that:**
+
+- Epics deliver user value, not technical milestones
+- Dependencies flow naturally
+- Foundation stories only setup what's needed
+- No big upfront technical work
+
+### 5. Dependency Validation (CRITICAL)
+
+**Epic Independence Check:**
+
+- Does each epic deliver COMPLETE functionality for its domain?
+- Can Epic 2 function without Epic 3 being implemented?
+- Can Epic 3 function standalone using Epic 1 & 2 outputs?
+- ❌ WRONG: Epic 2 requires Epic 3 features to work
+- ✅ RIGHT: Each epic is independently valuable
+
+**Within-Epic Story Dependency Check:**
+For each epic, review stories in order:
+
+- Can Story N.1 be completed without Stories N.2, N.3, etc.?
+- Can Story N.2 be completed using only Story N.1 output?
+- Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
+- ❌ WRONG: "This story depends on a future story"
+- ❌ WRONG: Story references features not yet implemented
+- ✅ RIGHT: Each story builds only on previous stories
+
+### 6. Complete and Save
+
+If all validations pass:
+
+- Update any remaining placeholders in the document
+- Ensure proper formatting
+- Save the final epics.md
+
+**Present Final Menu:**
+**All validations complete!** [C] Complete Workflow
+
+HALT — wait for user input before proceeding.
+
+When C is selected, the workflow is complete and the epics.md is ready for development.
+
+Epics and Stories complete. Invoke the `bmad-help` skill.
+
+Upon Completion of task output: offer to answer any questions about the Epics and Stories.

package/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/templates/epics-template.md

@@ -0,0 +1,61 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# {{project_name}} - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
+
+## Requirements Inventory
+
+### Functional Requirements
+
+{{fr_list}}
+
+### NonFunctional Requirements
+
+{{nfr_list}}
+
+### Additional Requirements
+
+{{additional_requirements}}
+
+### UX Design Requirements
+
+{{ux_design_requirements}}
+
+### FR Coverage Map
+
+{{requirements_coverage_map}}
+
+## Epic List
+
+{{epics_list}}
+
+<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+<!-- for each AC on this story -->
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+**And** {{additional_criteria}}
+
+<!-- End story repeat -->

package/_bmad/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/workflow.md

@@ -0,0 +1,53 @@
+# Create Epics and Stories
+
+**Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for development teams.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {project-root}/_bmad/bmm/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `planning_artifacts`, `user_name`, `communication_language`, `document_output_language`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. First Step EXECUTION
+
+Read fully and follow: `./steps/step-01-validate-prerequisites.md` to begin the workflow.

package/_bmad/bmm/workflows/4-implementation/bmad-code-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-code-review
+description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+---
+
+Follow the instructions in ./workflow.md.

package/_bmad/bmm/workflows/4-implementation/bmad-code-review/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-01-gather-context.md

@@ -0,0 +1,61 @@
+---
+diff_output: '' # set at runtime
+spec_file: '' # set at runtime (path or empty)
+review_mode: '' # set at runtime: "full" or "no-spec"
+---
+
+# Step 1: Gather Context
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do not modify any files. This step is read-only.
+
+## INSTRUCTIONS
+
+1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode:
+   - "staged" / "staged changes" → Staged changes only
+   - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
+   - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned)
+   - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range
+   - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
+   - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff").
+   - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question).
+   - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows:
+     - **Exactly one `review` story:** Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, fall through to instruction 2.
+     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. Then use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3.
+   - **If no match and no sprint tracking:** Fall through to instruction 2.
+
+2. HALT. Ask the user: **What do you want to review?** Present these options:
+   - **Uncommitted changes** (staged + unstaged)
+   - **Staged changes only**
+   - **Branch diff** vs a base branch (ask which base branch)
+   - **Specific commit range** (ask for the range)
+   - **Provided diff or file list** (user pastes or provides a path)
+
+3. Construct `{diff_output}` from the chosen source.
+   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
+   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
+   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
+   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+
+4. Ask the user: **Is there a spec or story file that provides context for these changes?**
+   - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - If no: set `{review_mode}` = `"no-spec"`.
+
+5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+
+6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
+   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
+   - If the user declines: proceed as-is with the full diff.
+
+### CHECKPOINT
+
+Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
+
+
+## NEXT
+
+Read fully and follow `./step-02-review.md`

package/_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-02-review.md

@@ -0,0 +1,41 @@
+---
+failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+---
+
+# Step 2: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The Blind Hunter subagent receives NO project context — diff only.
+- The Edge Case Hunter subagent receives diff and project read access.
+- The Acceptance Auditor subagent receives diff, spec, and context docs.
+
+## INSTRUCTIONS
+
+1. Launch parallel subagents. Each subagent gets NO conversation history from this session:
+
+   - **Blind Hunter** -- Invoke the `bmad-review-adversarial-general` skill in a subagent. Pass `content` = `{diff_output}` only. No spec, no project access.
+
+   - **Edge Case Hunter** -- Invoke the `bmad-review-edge-case-hunter` skill in a subagent. Pass `content` = `{diff_output}`. This subagent has read access to the project.
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) -- A subagent that receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
+     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+
+2. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+
+3. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+
+4. **Fallback** (if subagents are not available): Generate prompt files in `{implementation_artifacts}` -- one per active reviewer:
+   - `review-blind-hunter.md` (always)
+   - `review-edge-case-hunter.md` (always)
+   - `review-acceptance-auditor.md` (only if `{review_mode}` = `"full"`)
+
+   HALT. Tell the user to run each prompt in a separate session and paste back findings. When findings are pasted, resume from this point and proceed to step 3.
+
+5. Collect all findings from the completed layers.
+
+
+## NEXT
+
+Read fully and follow `./step-03-triage.md`

package/_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -0,0 +1,50 @@
+---
+---
+
+# Step 3: Triage
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Be precise. When uncertain between categories, prefer the more conservative classification.
+
+## INSTRUCTIONS
+
+1. **Normalize** findings into a common format. Expected input formats:
+   - Adversarial (Blind Hunter): markdown list of descriptions
+   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence` fields
+   - Acceptance Auditor: markdown list with title, AC/constraint reference, and evidence
+
+   If a layer's output does not match its expected format, attempt best-effort parsing. Note any parsing issues for the user.
+
+   Convert all to a unified list where each finding has:
+   - `id` -- sequential integer
+   - `source` -- `blind`, `edge`, `auditor`, or merged sources (e.g., `blind+edge`)
+   - `title` -- one-line summary
+   - `detail` -- full description
+   - `location` -- file and line reference (if available)
+
+2. **Deduplicate.** If two or more findings describe the same issue, merge them into one:
+   - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose).
+   - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
+   - Set `source` to the merged sources (e.g., `blind+edge`).
+
+3. **Classify** each finding into exactly one bucket:
+   - **intent_gap** -- The spec/intent is incomplete; cannot resolve from existing information. Only possible if `{review_mode}` = `"full"`.
+   - **bad_spec** -- The spec should have prevented this; spec is wrong or ambiguous. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is trivially fixable without human input. Just needs a code change.
+   - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
+   - **reject** -- Noise, false positive, or handled elsewhere.
+
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `intent_gap` or `bad_spec`, reclassify it as `patch` (if code-fixable) or `defer` (if not).
+
+4. **Drop** all `reject` findings. Record the reject count for the summary.
+
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping rejects AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+
+6. If zero findings remain after dropping rejects and no layers failed, note clean review.
+
+
+## NEXT
+
+Read fully and follow `./step-04-present.md`