ma-agents 2.20.3 → 2.22.0

package/lib/bmad-extension/agents/bmm-sre.customize.yaml

@@ -0,0 +1,30 @@
+# sre.customize.yaml
+agent:
+  metadata:
+    name: "Alex"
+
+persona:
+  role: "Site Reliability Engineer"
+  identity: "Expert in system availability, reliability, and Kubernetes operations (incident response, SLO/SLA management)."
+  communication_style: "Calm, data-driven, and systematic. Focuses on stability."
+  principles:
+    - "Automation over manual effort."
+    - "Monitor everything that matters."
+    - "Blame-free post-mortems."
+
+menu:
+  - trigger: bmad-sre-health-check
+    workflow: "bmm/workflows/sre/health-check.md"
+    description: "Run Cluster Health Check"
+  - trigger: bmad-sre-fix-deployments
+    workflow: "bmm/workflows/sre/fix-deployments.md"
+    description: "Troubleshoot & Fix Deployments"
+  - trigger: bmad-sre-performance-opt
+    workflow: "bmm/workflows/sre/performance-opt.md"
+    description: "Performance Optimization Analysis"
+
+critical_actions:
+  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/sre/MANIFEST.yaml"
+  2: "For each skill marked always_load: true, read the skill file completely"
+  3: "If _bmad-output/project-context.md exists, read it completely"
+  4: "Follow all skill directives and project-context rules during this session"

package/lib/bmad-extension/agents/bmm-tech-writer.customize.yaml

@@ -0,0 +1,5 @@
+critical_actions:
+  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml"
+  2: "For each skill marked always_load: true, read the skill file completely"
+  3: "If _bmad-output/project-context.md exists, read it completely"
+  4: "Follow all skill directives and project-context rules during this session"

package/lib/bmad-extension/agents/bmm-ux-designer.customize.yaml

@@ -0,0 +1,5 @@
+critical_actions:
+  1: "Read the skills MANIFEST at {project-root}/_bmad/skills/MANIFEST.yaml"
+  2: "For each skill marked always_load: true, read the skill file completely"
+  3: "If _bmad-output/project-context.md exists, read it completely"
+  4: "Follow all skill directives and project-context rules during this session"

package/lib/bmad-extension/module-help.csv

@@ -0,0 +1,7 @@
+module,phase,name,code,agent,file,command,yolo,tag,group,description,output_folder,output_type,notes
+ma-agents-skills,4-implementation,add-sprint,add-sprint,bmm-sm,lib/bmad-extension/workflows/add-sprint/workflow.md,/add-sprint,false,sprint,sprint-management,Create a new sprint with capacity limits and optional start/end context,_bmad-output/implementation-artifacts,yaml,Creates sprint-plan-{number}.yaml artifact
+ma-agents-skills,4-implementation,add-to-sprint,add-to-sprint,bmm-sm,lib/bmad-extension/workflows/add-to-sprint/workflow.md,/add-to-sprint,false,sprint,sprint-management,Assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization,_bmad-output/implementation-artifacts,yaml,Updates sprint-plan-{number}.yaml assigned_items
+ma-agents-skills,4-implementation,modify-sprint,modify-sprint,bmm-sm,lib/bmad-extension/workflows/modify-sprint/workflow.md,/modify-sprint,false,sprint,sprint-management,Modify existing sprint — add/remove items, change capacity, update metadata with concurrency guard,_bmad-output/implementation-artifacts,yaml,Updates sprint-plan-{number}.yaml in place
+ma-agents-skills,4-implementation,sprint-status-view,sprint-status-view,bmm-sm,lib/bmad-extension/workflows/sprint-status-view/workflow.md,/sprint-status-view,false,sprint,sprint-management,View sprint progress with all assigned items (stories + bugs) and remaining capacity,_bmad-output/implementation-artifacts,display,Reads sprint-plan-*.yaml and sprint-status.yaml
+ma-agents-skills,4-implementation,create-bug-story,create-bug-story,bmm-dev,lib/bmad-extension/workflows/create-bug-story/workflow.md,/create-bug-story,false,bug,bug-management,Create a structured bug story from a detected defect and add to backlog as standalone item,_bmad-output/implementation-artifacts,markdown,Creates bug-{slug}.md artifact with YAML frontmatter (type/severity/title)
+ma-agents-skills,4-implementation,project-context-expansion,project-context-expansion,bmm-sm,lib/bmad-extension/workflows/project-context-expansion/workflow.md,/project-context-expansion,false,context,project-context,Post-retrospective companion: propose and confirm additions to Project-Specific Rules in project-context.md,_bmad-output,markdown,Appends approved rules to ## Project-Specific Rules section only — never overwrites other sections; run after /bmad-retrospective

package/lib/bmad-extension/module.yaml

@@ -0,0 +1,3 @@
+extends-module: bmm
+name: ma-agents-skills
+description: MA-Agents skill enforcement extension for BMM agents

package/lib/bmad-extension/workflows/add-sprint/workflow.md

@@ -0,0 +1,112 @@
+# Add Sprint Workflow
+
+Guided workflow to create a new sprint with capacity limits for realistic sprint planning.
+
+<workflow>
+
+<step n="1" goal="Gather sprint number and name">
+  <action>Ask the user for the sprint number (e.g., 1, 2, 3)</action>
+  <ask>What is the sprint number? (e.g., 1)</ask>
+  <action>Store as {{sprint_number}}</action>
+  <ask>What is the sprint name? (e.g., "Sprint 1 — Foundation") — press Enter to use "Sprint {{sprint_number}}"</ask>
+  <action>If user presses Enter or leaves blank, default to "Sprint {{sprint_number}}"</action>
+  <action>Store as {{sprint_name}}</action>
+</step>
+
+<step n="2" goal="Gather capacity as positive integer">
+  <action>Explain capacity: the maximum number of items (stories + bugs) that can be assigned to this sprint</action>
+  <ask>What is the sprint capacity? (Enter a positive integer — the maximum number of stories/bugs for this sprint)</ask>
+  <action>Store input as {{capacity_input}}</action>
+  <action>Validate {{capacity_input}} is a positive integer (greater than zero, no decimals, no non-numeric characters)</action>
+  <check if="{{capacity_input}} is NOT a positive integer">
+    <output>❌ Invalid capacity: "{{capacity_input}}". Capacity must be a positive integer (e.g., 5, 10, 20). Zero and negative values are not allowed.</output>
+    <goto step="2" />
+  </check>
+  <action>Store as {{capacity}} (integer)</action>
+</step>
+
+<step n="3" goal="Gather optional start and end context">
+  <action>Explain: start/end context can be dates (e.g., "2026-03-18") or milestone descriptions (e.g., "Q1 Planning Complete")</action>
+  <ask>Optional — Sprint start context (date or milestone, press Enter to skip):</ask>
+  <action>Store as {{start_context}} (empty string if skipped)</action>
+  <ask>Optional — Sprint end context (date or milestone, press Enter to skip):</ask>
+  <action>Store as {{end_context}} (empty string if skipped)</action>
+</step>
+
+<step n="4" goal="Confirm and validate all inputs">
+  <output>
+## Sprint Summary — Please Confirm
+
+- **Sprint Number:** {{sprint_number}}
+- **Sprint Name:** {{sprint_name}}
+- **Capacity (max items):** {{capacity}}
+- **Start Context:** {{start_context}} *(empty if skipped)*
+- **End Context:** {{end_context}} *(empty if skipped)*
+- **Output File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
+  </output>
+  <ask>Confirm creation? [y] Yes / [n] Cancel / [e] Edit a field:</ask>
+  <check if="user selects 'e'">
+    <ask>Which field to edit? (number / name / capacity / start / end)</ask>
+    <check if="field == 'number'">
+      <ask>New sprint number:</ask>
+      <action>Store as {{sprint_number}}</action>
+      <action>If sprint name was auto-defaulted to the old "Sprint {n}", update it to "Sprint {{sprint_number}}"</action>
+      <goto step="4" />
+    </check>
+    <check if="field == 'name'">
+      <ask>New sprint name (or press Enter to use "Sprint {{sprint_number}}"):</ask>
+      <action>If blank, set {{sprint_name}} = "Sprint {{sprint_number}}"; else store user input as {{sprint_name}}</action>
+      <goto step="4" />
+    </check>
+    <check if="field == 'capacity'"><goto step="2" /></check>
+    <check if="field == 'start'"><goto step="3" /></check>
+    <check if="field == 'end'"><goto step="3" /></check>
+  </check>
+  <check if="user selects 'n'">
+    <output>❌ Sprint creation cancelled.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="5" goal="Generate sprint artifact file">
+  <action>Determine output path: `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`</action>
+  <action>Check if file already exists at output path</action>
+  <check if="file already exists">
+    <output>⚠️ A sprint plan already exists at `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`.</output>
+    <ask>Overwrite existing sprint plan? [y] Yes / [n] Cancel:</ask>
+    <check if="user selects 'n'">
+      <output>❌ Sprint creation cancelled to preserve existing sprint plan.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+  <action>Get current ISO timestamp for created_date and last_modified</action>
+  <action>Write sprint artifact YAML to `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml` with this structure:
+
+```yaml
+sprint_number: {{sprint_number}}
+sprint_name: "{{sprint_name}}"
+capacity: {{capacity}}
+assigned_items: []
+status: planning
+start_context: "{{start_context}}"
+end_context: "{{end_context}}"
+created_date: "{{current_iso_timestamp}}"
+last_modified: "{{current_iso_timestamp}}"
+```
+  </action>
+  <output>
+✅ **Sprint created successfully!**
+
+- **File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
+- **Sprint:** {{sprint_name}}
+- **Capacity:** {{capacity}} items
+- **Status:** planning
+
+**Next Steps:**
+- Use `/add-to-sprint` to assign backlog items to this sprint
+- Use `/modify-sprint` to update sprint details later
+- Use `/sprint-status-view` to view sprint progress
+  </output>
+</step>
+
+</workflow>

package/lib/bmad-extension/workflows/add-to-sprint/workflow.md

@@ -0,0 +1,206 @@
+# Add-to-Sprint Workflow
+
+Guided workflow to assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.
+
+<workflow>
+
+<step n="1a" goal="Discover user story backlog items from sprint-status.yaml">
+  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml` — authoritative source for user story execution status</action>
+  <action>Parse the development_status section. For each entry:
+    - Skip epic keys (keys matching `epic-*`)
+    - Skip retrospective keys (keys ending with `-retrospective`)
+    - Collect story keys and their current status (backlog, ready-for-dev, in-progress, review, done)
+  </action>
+  <action>Store as {{user_stories}} — list of objects with: key, status</action>
+  <action>Infer story title from key (e.g., `12-1-add-sprint-workflow` → "Add Sprint Workflow")</action>
+</step>
+
+<step n="1b" goal="Discover bug story backlog items">
+  <action>Glob `_bmad-output/implementation-artifacts/bug-*.md` to discover all bug story files</action>
+  <check if="no bug files found">
+    <action>Set {{bug_stories}} = [] (empty list)</action>
+  </check>
+  <check if="bug files found">
+    <action>For each bug file, parse YAML frontmatter to extract: `type`, `severity`, `title`</action>
+    <action>Store as {{bug_stories}} — list of objects with: file, type (bug), severity, title</action>
+  </check>
+</step>
+
+<step n="1c" goal="Filter out items already assigned to any sprint">
+  <action>Glob `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` to discover all existing sprint artifact files</action>
+  <action>For each sprint file found, read its assigned_items list</action>
+  <action>Build {{all_assigned_items}} = flat set of every item identifier (story keys and bug basenames) across ALL sprint plans</action>
+  <action>Filter {{user_stories}}: remove any story whose key is present in {{all_assigned_items}}</action>
+  <action>Filter {{bug_stories}}: remove any bug whose file basename is present in {{all_assigned_items}}</action>
+  <action>Items already assigned to any sprint will NOT appear in the backlog — this prevents duplicate assignment</action>
+  <check if="no sprint files found">
+    <action>Set {{all_assigned_items}} = [] — no filtering needed when no sprints exist yet</action>
+  </check>
+</step>
+
+<step n="2" goal="Present flat backlog combining stories and bugs">
+  <action>Combine {{user_stories}} and {{bug_stories}} into a flat backlog list</action>
+  <action>Stories and bugs are peers — no epic grouping (FR65)</action>
+  <output>
+## 📋 Backlog Items
+
+| # | ID / File | Title | Type | Status/Severity |
+|---|---|---|---|---|
+{{#each backlog_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status_or_severity}} |
+{{/each}}
+
+*Total: {{story_count}} stories, {{bug_count}} bugs*
+  </output>
+</step>
+
+<step n="3" goal="List available sprints and select target sprint">
+  <action>Glob `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` to discover all sprint artifact files</action>
+  <check if="no sprint files found">
+    <output>❌ No sprint plans found. Run `/add-sprint` first to create a sprint before assigning items.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>For each sprint file found, read and extract: sprint_number, sprint_name, capacity, assigned_items count, status</action>
+  <output>
+## 🏃 Available Sprints
+
+| # | Sprint | Status | Capacity | Assigned | Remaining |
+|---|---|---|---|---|---|
+{{#each sprints}}
+| {{@index+1}} | {{sprint_name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
+{{/each}}
+  </output>
+  <ask>Select target sprint (enter number):</ask>
+  <action>Store selected sprint data as {{target_sprint}}</action>
+</step>
+
+<step n="4" goal="Display current sprint capacity usage">
+  <action>Calculate: {{assigned_count}} = length of {{target_sprint.assigned_items}}</action>
+  <action>Calculate: {{remaining_capacity}} = {{target_sprint.capacity}} - {{assigned_count}}</action>
+  <output>
+## Sprint Capacity: {{target_sprint.sprint_name}}
+
+- **Capacity:** {{target_sprint.capacity}} items
+- **Assigned:** {{assigned_count}} items
+- **Remaining:** {{remaining_capacity}} slots
+
+{{#if remaining_capacity <= 0}}
+⚠️ This sprint is **at or over capacity**. Adding items will exceed the limit.
+{{/if}}
+  </output>
+</step>
+
+<step n="5" goal="Select candidate items for this sprint">
+  <ask>Which backlog items do you want to consider for this sprint? Enter item numbers (comma-separated), or "all" to evaluate the full backlog:</ask>
+  <check if="user enters 'all'">
+    <action>Set {{candidate_items}} = all items in {{backlog_items}} (the full filtered backlog list from step 2)</action>
+  </check>
+  <check if="user enters item numbers">
+    <action>Resolve the entered numbers against the backlog table from step 2 and set {{candidate_items}} = those specific items</action>
+  </check>
+</step>
+
+<step n="6" goal="Multi-criteria prioritization guidance">
+  <action>For each item in {{candidate_items}}, evaluate and score across criteria:
+    - **Business value:** High (H) / Medium (M) / Low (L) — impact on users or project goals
+    - **Dependency status:** Blocked (blocked by another item) / Blocking (blocks other items) / Independent
+    - **Severity** (bugs only): Critical / High / Medium / Low — N/A for stories
+    - **Effort estimation:** Small (S ≤ 1 day) / Medium (M 2–3 days) / Large (L 4+ days)
+  </action>
+  <action>Generate a ranked ordering recommendation, factoring in:
+    1. Blocking dependencies first (items that unlock others)
+    2. High business value + low/medium effort (quick wins)
+    3. Critical/High bugs ahead of Medium/Low bugs
+    4. Avoid blocked items unless capacity allows waiting
+  </action>
+  <output>
+## 🎯 Prioritization Analysis
+
+| Rank | ID / File | Title | Type | Business Value | Dependencies | Severity | Effort | Rationale |
+|---|---|---|---|---|---|---|---|---|
+{{#each ranked_items}}
+| {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} | {{rationale}} |
+{{/each}}
+
+**Recommended selection** (up to {{remaining_capacity}} items to stay within capacity): {{recommended_selection}}
+  </output>
+</step>
+
+<step n="7" goal="User confirms or adjusts ranking">
+  <ask>Review the ranking above. Options:
+- [c] Confirm recommended selection as-is
+- [m] Modify selection (specify item numbers to include)
+- [r] Re-rank items (provide new priority order)
+- [x] Cancel without assigning
+
+Choice:</ask>
+  <check if="user selects 'x'">
+    <output>❌ Assignment cancelled — no changes made.</output>
+    <action>Exit workflow</action>
+  </check>
+  <check if="user selects 'm'">
+    <ask>Enter item numbers to assign (comma-separated):</ask>
+    <action>Update {{confirmed_items}} with user selection</action>
+  </check>
+  <check if="user selects 'r'">
+    <ask>Enter item numbers in your preferred priority order (comma-separated). Only items you include will be assigned — items not listed will be excluded from this session and remain in the unassigned backlog:</ask>
+    <action>Set {{confirmed_items}} = only the items matching the user-provided numbers, in the order provided. Items from {{candidate_items}} NOT mentioned are excluded from assignment in this session (they remain available in the backlog for future sprints).</action>
+  </check>
+  <check if="user selects 'c'">
+    <action>Set {{confirmed_items}} = recommended selection</action>
+  </check>
+  <action>Store confirmed ranking in {{confirmed_ranking}} for auditability (included in workflow output)</action>
+</step>
+
+<step n="8" goal="Assign selected items to sprint with capacity enforcement">
+  <action>For each item in {{confirmed_items}}, in confirmed ranking order:</action>
+  <action>Re-calculate current assigned count (in case multiple items are being added)</action>
+  <check if="assigning this item would exceed capacity">
+    <output>⚠️ **Capacity Warning:** Adding "{{item.title}}" would bring assigned items to {{new_count}}/{{target_sprint.capacity}} — exceeding sprint capacity by {{overage}}.</output>
+    <ask>Options:
+- [a] Add anyway (over-capacity acknowledged)
+- [s] Skip this item
+- [m] Modify sprint capacity first via `/modify-sprint`
+
+Choice:</ask>
+    <check if="user selects 's'">
+      <action>Skip this item — do not add to sprint. Continue to next item in the {{confirmed_items}} loop.</action>
+    </check>
+    <check if="user selects 'm'">
+      <output>💡 Run `/modify-sprint` to increase capacity for {{target_sprint.sprint_name}}, then re-run `/add-to-sprint`.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+  <action>Add item identifier to {{target_sprint.assigned_items}} list in the sprint-plan-{{target_sprint.sprint_number}}.yaml artifact</action>
+  <action>Item identifier format: story key for user stories (e.g., `12-1-add-sprint-workflow`), file basename for bugs (e.g., `bug-login-crash`)</action>
+</step>
+
+<step n="9" goal="Persist changes and display confirmed ranking for auditability">
+  <action>Update `_bmad-output/implementation-artifacts/sprint-plan-{{target_sprint.sprint_number}}.yaml`:
+    - Update `assigned_items` list with all newly assigned item identifiers
+    - Update `last_modified` to current ISO timestamp
+  </action>
+  <action>**Do NOT modify sprint-status.yaml** — sprint membership is exclusively tracked in sprint-plan-{n}.yaml</action>
+  <output>
+## ✅ Assignment Complete
+
+**Sprint:** {{target_sprint.sprint_name}}
+**Items assigned this session:** {{assigned_this_session}}
+
+### Confirmed Ranking (Audit Record)
+
+| Rank | ID | Title | Type | Business Value | Dependencies | Severity | Effort |
+|---|---|---|---|---|---|---|---|
+{{#each confirmed_ranking}}
+| {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} |
+{{/each}}
+
+**Updated Capacity:** {{new_assigned_count}}/{{target_sprint.capacity}} items used ({{new_remaining}} remaining)
+
+**Next Steps:**
+- Use `/modify-sprint` to adjust capacity or remove items
+- Use `/sprint-status-view` to view the full sprint with all assigned items
+  </output>
+</step>
+
+</workflow>

package/lib/bmad-extension/workflows/create-bug-story/workflow.md

@@ -0,0 +1,186 @@
+# Create Bug Story Workflow
+
+Guided workflow to create a structured bug story from a detected defect and add it to the backlog as a standalone item.
+
+<workflow>
+
+<step n="1" goal="Gather bug title and severity">
+  <action>Explain: This workflow creates a structured bug story file that enters the backlog alongside user stories.</action>
+  <ask>What is the bug title? (short, descriptive — e.g., "Login fails with empty password field")</ask>
+  <action>Store as {{bug_title}}</action>
+  <action>Validate {{bug_title}} is not empty</action>
+  <check if="{{bug_title}} is empty">
+    <output>❌ Bug title cannot be empty.</output>
+    <goto step="1" />
+  </check>
+
+  <output>
+**Severity levels:**
+- `critical` — Data loss, security breach, or system crash in normal usage
+- `high` — Core feature broken or serious security risk; blocks users
+- `medium` — Feature partially broken or degraded; workaround exists
+- `low` — Minor issue, cosmetic defect, or edge case with minimal user impact
+  </output>
+  <ask>What is the severity? [critical / high / medium / low]</ask>
+  <action>Store as {{severity}}</action>
+  <action>Normalize to lowercase</action>
+  <check if="{{severity}} is not one of: critical, high, medium, low">
+    <output>❌ Severity must be one of: critical, high, medium, low.</output>
+    <goto step="1" />
+  </check>
+</step>
+
+<step n="2" goal="Gather affected component and reproduction steps">
+  <ask>What is the affected component? (e.g., "auth module", "login page", "installer pipeline")</ask>
+  <action>Store as {{affected_component}}</action>
+
+  <ask>What are the reproduction steps? (numbered steps to reproduce the bug — describe them one at a time or as a list)</ask>
+  <action>Store as {{reproduction_steps}}</action>
+</step>
+
+<step n="3" goal="Gather expected vs actual behavior">
+  <ask>What is the expected behavior? (what should happen when working correctly)</ask>
+  <action>Store as {{expected_behavior}}</action>
+
+  <ask>What is the actual behavior? (what actually happens — the defect)</ask>
+  <action>Store as {{actual_behavior}}</action>
+</step>
+
+<step n="4" goal="Gather root cause hypothesis and affected files">
+  <ask>What is your root cause hypothesis? (optional — press Enter to skip; e.g., "Null check missing in validateUser()")</ask>
+  <action>Store as {{root_cause}} (empty string if skipped)</action>
+
+  <ask>What files are affected? (optional — comma-separated paths relative to repo root, press Enter to skip)</ask>
+  <action>Store as {{affected_files}} (empty string if skipped)</action>
+  <action>If provided, split by comma and trim whitespace to form a list of file paths</action>
+
+  <ask>Is there a suggested fix? (optional — brief description or press Enter to skip)</ask>
+  <action>Store as {{suggested_fix}} (empty string if skipped)</action>
+</step>
+
+<step n="5" goal="Confirm all bug details before writing">
+  <action>Derive {{title_slug}} by converting {{bug_title}} to lowercase kebab-case:
+    - Convert to lowercase
+    - Replace spaces and underscores with hyphens
+    - Remove characters that are not alphanumeric or hyphens
+    - Collapse consecutive hyphens into one
+    - Trim leading/trailing hyphens
+  </action>
+  <action>Set {{output_file}} = `_bmad-output/implementation-artifacts/bug-{{title_slug}}.md`</action>
+
+  <output>
+## Bug Story Summary — Please Confirm
+
+- **Title:** {{bug_title}}
+- **Severity:** {{severity}}
+- **Affected Component:** {{affected_component}}
+- **Reproduction Steps:** {{reproduction_steps}}
+- **Expected Behavior:** {{expected_behavior}}
+- **Actual Behavior:** {{actual_behavior}}
+- **Root Cause Hypothesis:** {{root_cause}} *(empty if skipped)*
+- **Affected Files:** {{affected_files}} *(empty if skipped)*
+- **Suggested Fix:** {{suggested_fix}} *(empty if skipped)*
+- **Output File:** `{{output_file}}`
+  </output>
+  <ask>Confirm creation? [y] Yes / [n] Cancel / [e] Edit a field:</ask>
+  <check if="user selects 'e'">
+    <ask>Which field to edit? (title / severity / component / steps / expected / actual / root-cause / files / fix)</ask>
+    <check if="field == 'title' OR field == 'severity'"><goto step="1" /></check>
+    <check if="field == 'component' OR field == 'steps'"><goto step="2" /></check>
+    <check if="field == 'expected' OR field == 'actual'"><goto step="3" /></check>
+    <check if="field == 'root-cause' OR field == 'files' OR field == 'fix'"><goto step="4" /></check>
+    <check if="none of the above matched">
+      <output>❌ Unrecognized field. Valid options: title / severity / component / steps / expected / actual / root-cause / files / fix</output>
+      <goto step="5" />
+    </check>
+  </check>
+  <check if="user selects 'n'">
+    <output>❌ Bug story creation cancelled.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="6" goal="Write bug story file">
+  <action>Check if {{output_file}} already exists</action>
+  <check if="file already exists">
+    <output>⚠️ A bug story already exists at `{{output_file}}`.</output>
+    <ask>Overwrite? [y] Yes — overwrite existing / [n] Cancel / [s] Save with unique suffix (e.g. bug-{{title_slug}}-2.md):</ask>
+    <check if="user selects 's'">
+      <action>Find the next available suffix: try bug-{{title_slug}}-2.md, -3.md, etc. until a filename that does not exist is found. Set {{output_file}} to that path.</action>
+    </check>
+    <check if="user selects 'n'">
+      <output>❌ Bug story creation cancelled to preserve existing file.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <action>Write bug story to {{output_file}} using the template below.
+    CRITICAL: The YAML frontmatter block MUST be the very first content in the file — no blank lines, no title, nothing before the opening `---`.
+    Format optional fields (root_cause, affected_files, suggested_fix) as follows:
+      - If {{root_cause}} is empty, write: `_Not identified_`
+      - If {{affected_files}} is empty, write: `_Unknown_`; otherwise list each file as a `- path/to/file` bullet
+      - If {{suggested_fix}} is empty, omit the Suggested Fix section entirely
+  </action>
+
+  <action>Write file with this exact structure:
+
+```
+---
+type: bug
+severity: {{severity}}
+title: {{bug_title}}
+---
+
+# Bug: {{bug_title}}
+
+**Severity:** {{severity}}
+**Affected Component:** {{affected_component}}
+
+## Reproduction Steps
+
+{{reproduction_steps}}
+
+## Expected Behavior
+
+{{expected_behavior}}
+
+## Actual Behavior
+
+{{actual_behavior}}
+
+## Root Cause Hypothesis
+
+{{root_cause or "_Not identified_"}}
+
+## Affected Files
+
+{{affected_files list or "_Unknown_"}}
+
+## Suggested Fix
+
+{{suggested_fix — omit section if empty}}
+
+## Notes
+
+- Created via `create-bug-story` workflow
+- Discoverable by sprint workflows via glob: `_bmad-output/implementation-artifacts/bug-*.md`
+- To add to a sprint, run `/add-to-sprint`
+```
+  </action>
+
+  <output>
+✅ **Bug story created successfully!**
+
+- **File:** `{{output_file}}`
+- **Title:** {{bug_title}}
+- **Severity:** {{severity}}
+- **Component:** {{affected_component}}
+
+**Next Steps:**
+- Use `/add-to-sprint` to assign this bug to the current sprint
+- Use `/sprint-status-view` to see all sprint items including this bug
+- To detect more bugs, ensure the `auto-bug-detection` skill is loaded in your session
+  </output>
+</step>
+
+</workflow>