ma-agents 3.4.7 → 3.4.9

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

@@ -29,26 +29,9 @@ ma-skills,4-implementation,Vault Secrets,cyber-vault-secrets,,skill:cyber-vault-
 ma-skills,4-implementation,Verify Docker Users,cyber-verify-docker-users,,skill:cyber-verify-docker-users,bmad-cyber-verify-docker-users,false,bmm-cyber,,"Verify Docker image user configurations and hardening compliance.",output_folder,"verification report",
 ma-skills,4-implementation,Verify Image Signature,cyber-verify-image-signature,,skill:cyber-verify-image-signature,bmad-cyber-verify-image-signature,false,bmm-cyber,,"Verify Docker image signatures for supply chain integrity.",output_folder,"verification report",
 ma-skills,4-implementation,Vulnerability Scan,cyber-vulnerability-scan,,skill:cyber-vulnerability-scan,bmad-cyber-vulnerability-scan,false,bmm-cyber,,"Orchestrate vulnerability scanning across project components.",output_folder,"scan report",
-ma-skills,4-implementation,Create Bug Story,create-bug-story,,skill:create-bug-story,create-bug-story,false,bmm-dev,,"Create a structured bug story with severity and type classification, add to backlog.yaml.",_bmad-output/implementation-artifacts,"bug story",
-ma-skills,4-implementation,Add Sprint,add-sprint,,skill:add-sprint,add-sprint,false,bmm-sm,,"Create a new sprint entity with capacity limits and optional ISO dates (YAML schema).",_bmad-output/implementation-artifacts/sprints,"sprint entity",
+ma-skills,4-implementation,Create Bug Story,create-bug-story,,skill:create-bug-story,create-bug-story,false,bmm-dev,,"Create a structured bug story from a detected defect and add to backlog.",_bmad-output/implementation-artifacts,"bug story",
+ma-skills,4-implementation,Add Sprint,add-sprint,,skill:add-sprint,add-sprint,false,bmm-sm,,"Create a new sprint with capacity limits and optional start/end context.",_bmad-output/implementation-artifacts,"sprint plan",
 ma-skills,4-implementation,Modify Sprint,modify-sprint,,skill:modify-sprint,modify-sprint,false,bmm-sm,,"Modify existing sprint — add/remove items, change capacity, update metadata.",_bmad-output/implementation-artifacts,"sprint plan",
-ma-skills,4-implementation,Add to Sprint,add-to-sprint,,skill:add-to-sprint,add-to-sprint,false,bmm-sm,,"Assign backlog items to a sprint from flat prioritized backlog.",_bmad-output/implementation-artifacts,"sprint plan",
+ma-skills,4-implementation,Add to Sprint,add-to-sprint,,skill:add-to-sprint,add-to-sprint,false,bmm-sm,,"Assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.",_bmad-output/implementation-artifacts,"sprint plan",
 ma-skills,4-implementation,Project Context Expansion,project-context-expansion,,skill:project-context-expansion,project-context-expansion,false,bmm-sm,,"Post-retrospective companion to update project-context.md with new rules.",_bmad-output,"project context",
-ma-skills,4-implementation,Sprint Status View,sprint-status-view,,skill:sprint-status-view,sprint-status-view,false,bmm-sm,,"View sprint status with capacity, items, and backlog. Regenerates sprint-status.yaml.",_bmad-output/implementation-artifacts,"status display",
-ma-skills,4-implementation,Generate Backlog,generate-backlog,,skill:generate-backlog,generate-backlog,false,bmm-sm,,"Generate or refresh flat backlog from epics and bug stories.",_bmad-output/implementation-artifacts,"backlog",
-ma-skills,4-implementation,Remove from Sprint,remove-from-sprint,,skill:remove-from-sprint,remove-from-sprint,false,bmm-sm,,"Remove items from a sprint and return to unassigned backlog.",_bmad-output/implementation-artifacts,"sprint plan",
-ma-skills,4-implementation,Cleanup Done,cleanup-done,,skill:cleanup-done,cleanup-done,false,bmm-sm,,"Archive done items — move files to done/ and remove from sprint/backlog.",_bmad-output/implementation-artifacts,"archived items",
-ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog using multiple criteria — severity, value, dependencies.",_bmad-output/implementation-artifacts,"backlog",
-ma-skills,anytime,ML Agent (Demerzel),bmad-ma-agent-ml,,skill:bmad-ma-agent-ml,bmad-ma-agent-ml,false,bmm-demerzel,,"Machine Learning Scientist specializing in falsifiable hypothesis validation and failure-cost analysis.",output_folder,"agent customization",
-ma-skills,1-research,ML Ideation & PRD,ml-ideation,,skill:ml-ideation,ml-ideation,false,bmm-demerzel,,"Frame ML research problem, define requirements, and produce Research Thesis and PRD.",_bmad-output/planning-artifacts,"ML documents",
-ma-skills,1-research,ML EDA & Research,ml-eda,,skill:ml-eda,ml-eda,false,bmm-demerzel,,"Perform exploratory data analysis, establish baselines, and produce EDA report.",_bmad-output/planning-artifacts,"EDA report",
-ma-skills,1-research,ML Architecture Design,ml-architecture,,skill:ml-architecture,ml-architecture,false,bmm-demerzel,,"Design model architecture, stack, and experiment tracking strategy.",_bmad-output/planning-artifacts,"arch design",
-ma-skills,4-implementation,ML Detailed Design,ml-detailed-design,,skill:ml-detailed-design,ml-detailed-design,false,bmm-demerzel,,"Break down infrastructure and experiment tasks from architecture.",_bmad-output/planning-artifacts,"task breakdown",
-ma-skills,4-implementation,ML TechSpec (Contract),ml-techspec,,skill:ml-techspec,ml-techspec,false,bmm-demerzel,,"Lock experiment parameters and performance tiers before training.",_bmad-output/planning-artifacts,"techspec contract",
-ma-skills,4-implementation,ML Infra & Sync,ml-infra,,skill:ml-infra,ml-infra,false,bmm-demerzel,,"Build ML infrastructure, manage dependencies, and run smoke tests.",_bmad-output/implementation-artifacts,"infra status",
-ma-skills,4-implementation,ML Experiment,ml-experiment,,skill:ml-experiment,ml-experiment,false,bmm-demerzel,,"Execute training experiments against locked TechSpec and log metrics.",_bmad-output/implementation-artifacts,"experiments log",
-ma-skills,4-implementation,ML Results Analysis,ml-analysis,,skill:ml-analysis,ml-analysis,false,bmm-demerzel,,"Evaluate experiment outcomes against TechSpec success tiers.",_bmad-output/implementation-artifacts,"analysis report",
-ma-skills,4-implementation,ML HPO (Tuning),ml-hparam,,skill:ml-hparam,ml-hparam,false,bmm-demerzel,,"Perform automated hyperparameter optimization (conditional).",_bmad-output/implementation-artifacts,"tuning results",
-ma-skills,4-implementation,ML Iterative Revision,ml-revision,,skill:ml-revision,ml-revision,false,bmm-demerzel,,"Amend hypothesis and requirements based on experiment findings.",_bmad-output/planning-artifacts,"amended docs",
-ma-skills,anytime,ML Advise & Search,ml-advise,,skill:ml-advise,ml-advise,false,bmm-demerzel,,"Search past experiments and surface findings or failure warnings.",_bmad-output,"findings report",
-ma-skills,anytime,ML Retrospective,ml-retrospective,,skill:ml-retrospective,ml-retrospective,false,bmm-demerzel,,"Capture session learnings and update project context.",_bmad-output,"session learnings",
+ma-skills,4-implementation,Sprint Status View,sprint-status-view,,skill:sprint-status-view,sprint-status-view,false,bmm-sm,,"View sprint progress with assigned items and remaining capacity.",_bmad-output/implementation-artifacts,"status display",

package/lib/bmad-extension/skills/add-sprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-sprint
-description: Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema for sprint planning
+description: Guided workflow to create a new sprint with capacity limits for realistic sprint planning
 type: skill
 triggers:
   - "add sprint"
@@ -9,35 +9,17 @@ triggers:
 
 # Add Sprint Workflow
 
-Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema.
+Guided workflow to create a new sprint with capacity limits for realistic sprint planning.
 
 <workflow>
 
-<step n="1" goal="Gather and validate sprint number and name">
-  <action>Ask the user for the sprint number</action>
-  <ask>What is the sprint number? (positive integer, e.g., 1, 2, 3)</ask>
-  <action>Store input as {{sprint_number_input}}</action>
-  <action>Validate {{sprint_number_input}} matches `^[1-9]\d*$` (positive integer, no leading zeros, no non-numeric characters)</action>
-  <action>Validate {{sprint_number_input}} is <= 9999</action>
-  <check if="{{sprint_number_input}} fails validation (zero, negative, non-numeric, leading zeros like '03', or > 9999)">
-    <output>❌ Invalid sprint number: "{{sprint_number_input}}". Must be a positive integer (1-9999), no leading zeros.</output>
-    <goto step="1" />
-  </check>
-  <action>Store as {{sprint_number}} (integer)</action>
-  <action>Construct {{sprint_id}} = "sprint-{{sprint_number}}"</action>
-
-  <!-- Smart default name: detect naming patterns from existing sprints -->
-  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to discover existing sprint files</action>
-  <action>If existing sprints found, read the `name` field from the most recent one (highest sprint number)</action>
-  <action>Infer a smart default name:
-    - If previous name follows a sequential pattern with a numeric suffix (e.g., "app04"), suggest the next increment (e.g., "app05")
-    - If previous name follows a date pattern (e.g., "2026-W14"), suggest the next date interval
-    - If previous name is "Sprint {n}", suggest "Sprint {{sprint_number}}"
-    - If no pattern detected or no existing sprints, default to "Sprint {{sprint_number}}"
-  </action>
-  <ask>Sprint name? (press Enter for "{{default_name}}", or type a custom name):</ask>
-  <action>If user presses Enter or leaves blank, set {{sprint_name}} = "{{default_name}}"</action>
-  <action>If user provides input, store as {{sprint_name}}</action>
+<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">
@@ -52,71 +34,32 @@ Guided workflow to create a new sprint entity with capacity limits, optional ISO
   <action>Store as {{capacity}} (integer)</action>
 </step>
 
-<step n="3a" goal="Gather optional start date (ISO format)">
-  <action>Explain: start and end dates are optional ISO dates (YYYY-MM-DD format). Press Enter to skip.</action>
-  <ask>Optional — Sprint start date (YYYY-MM-DD, press Enter to skip):</ask>
-  <action>Store input as {{start_input}}</action>
-  <check if="{{start_input}} is not empty">
-    <action>Validate {{start_input}} matches regex `^\d{4}-\d{2}-\d{2}$`</action>
-    <action>Verify {{start_input}} resolves to a real calendar date (reject impossible dates like 2026-02-30, 2026-13-45, etc.)</action>
-    <check if="{{start_input}} fails date validation">
-      <output>❌ Invalid date: "{{start_input}}". Must be a valid date in YYYY-MM-DD format (e.g., 2026-04-01).</output>
-      <goto step="3a" />
-    </check>
-  </check>
-  <action>Store as {{start_date}} (valid ISO date string, or empty string "" if skipped)</action>
-</step>
-
-<step n="3b" goal="Gather optional end date (ISO format)">
-  <ask>Optional — Sprint end date (YYYY-MM-DD, press Enter to skip):</ask>
-  <action>Store input as {{end_input}}</action>
-  <check if="{{end_input}} is not empty">
-    <action>Validate {{end_input}} matches regex `^\d{4}-\d{2}-\d{2}$`</action>
-    <action>Verify {{end_input}} resolves to a real calendar date</action>
-    <check if="{{end_input}} fails date validation">
-      <output>❌ Invalid date: "{{end_input}}". Must be a valid date in YYYY-MM-DD format (e.g., 2026-04-14).</output>
-      <goto step="3b" />
-    </check>
-  </check>
-  <action>Store as {{end_date}} (valid ISO date string, or empty string "" if skipped)</action>
-
-  <check if="both {{start_date}} and {{end_date}} are non-empty AND {{start_date}} > {{end_date}}">
-    <output>❌ Invalid date range: start date ({{start_date}}) is after end date ({{end_date}}). Start must be on or before end.</output>
-    <goto step="3a" />
-  </check>
+<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 ID:** {{sprint_id}}
-- **Sprint Name:** "{{sprint_name}}"
-- **Status:** planning
+- **Sprint Number:** {{sprint_number}}
+- **Sprint Name:** {{sprint_name}}
 - **Capacity (max items):** {{capacity}}
-- **Start Date:** {{start_date}} *(empty if skipped)*
-- **End Date:** {{end_date}} *(empty if skipped)*
-- **Items:** [] *(empty — items assigned via /add-to-sprint)*
-- **Output File:** `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`
+- **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? (positive integer, 1-9999)</ask>
-      <action>Store input as {{sprint_number_input}}</action>
-      <action>Validate {{sprint_number_input}} matches `^[1-9]\d*$` and is <= 9999</action>
-      <check if="{{sprint_number_input}} fails validation">
-        <output>❌ Invalid sprint number: "{{sprint_number_input}}". Must be a positive integer (1-9999), no leading zeros.</output>
-        <goto step="4" />
-      </check>
-      <action>Store as {{sprint_number}} (integer)</action>
-      <action>Construct {{sprint_id}} = "sprint-{{sprint_number}}"</action>
-      <action>If sprint name was using previous default "Sprint {old_n}", update to "Sprint {{sprint_number}}"</action>
-      <action>Check if file exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
-      <check if="file already exists at new path">
-        <output>⚠️ A sprint entity already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`. You will be prompted to overwrite at creation.</output>
-      </check>
+      <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'">
@@ -125,74 +68,45 @@ Guided workflow to create a new sprint entity with capacity limits, optional ISO
       <goto step="4" />
     </check>
     <check if="field == 'capacity'"><goto step="2" /></check>
-    <check if="field == 'start'"><goto step="3a" /></check>
-    <check if="field == 'end'"><goto step="3b" /></check>
-    <check if="field is not recognized">
-      <output>❌ Unrecognized field: "{{field}}". Valid options: number, name, capacity, start, end.</output>
-      <goto step="4" />
-    </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>
-  <check if="user input is not 'y', 'n', or 'e'">
-    <output>❌ Unrecognized option: "{{user_input}}". Please enter [y] Yes, [n] Cancel, or [e] Edit a field.</output>
-    <goto step="4" />
-  </check>
 </step>
 
-<step n="5" goal="Generate sprint entity YAML file">
-  <action>Determine output path: `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
-  <action>Ensure directory `_bmad-output/implementation-artifacts/sprints/` exists (create if needed)</action>
-
-  <!-- Overwrite protection for new path -->
-  <action>Check if file already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
-  <check if="file already exists at new path">
-    <anchor id="overwrite_prompt" />
-    <output>⚠️ A sprint entity already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`.</output>
-    <ask>Overwrite existing sprint? [y] Yes / [n] Cancel:</ask>
+<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.</output>
+      <output>❌ Sprint creation cancelled to preserve existing sprint plan.</output>
       <action>Exit workflow</action>
     </check>
-    <check if="user input is not 'y' or 'n'">
-      <output>❌ Unrecognized option: "{{user_input}}". Please enter [y] Yes or [n] Cancel.</output>
-      <goto anchor="overwrite_prompt" />
-    </check>
   </check>
-
-  <!-- Advisory check for old-format file -->
-  <action>Check if file exists at old path: `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`</action>
-  <check if="old-format file exists">
-    <output>ℹ️ **Note:** An old-format sprint file exists at `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`. The new sprint will be created at the new path. The old file is NOT auto-migrated — review or remove it manually if no longer needed.</output>
-  </check>
-
   <action>Get current ISO timestamp for created_date and last_modified</action>
-  <action>Write sprint entity YAML to `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml` with this structure:
+  <action>Write sprint artifact YAML to `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml` with this structure:
 
 ```yaml
-id: {{sprint_id}}
-name: "{{sprint_name}}"
-status: planning
+sprint_number: {{sprint_number}}
+sprint_name: "{{sprint_name}}"
 capacity: {{capacity}}
-start: "{{start_date}}"
-end: "{{end_date}}"
-items: []
+assigned_items: []
+status: planning
+start_context: "{{start_context}}"
+end_context: "{{end_context}}"
 created_date: "{{current_iso_timestamp}}"
 last_modified: "{{current_iso_timestamp}}"
 ```
-
-  **YAML output rules:**
-  - Always quote the `name` field to handle special characters
-  - `start` and `end` are empty string `""` if skipped
-  - `items` is always empty array `[]` at creation
-  - `status` is always `planning` at creation (never `active` or `closed`)
   </action>
   <output>
 ✅ **Sprint created successfully!**
 
-- **File:** `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`
+- **File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
 - **Sprint:** {{sprint_name}}
 - **Capacity:** {{capacity}} items
 - **Status:** planning

package/lib/bmad-extension/skills/add-to-sprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-to-sprint
-description: Guided workflow to assign backlog items to a sprint from the flat prioritized backlog
+description: Guided workflow to assign backlog items to a sprint using multi-criteria prioritization
 type: skill
 triggers:
   - "add to sprint"
@@ -9,178 +9,204 @@ triggers:
 
 # Add-to-Sprint Workflow
 
-Guided workflow to assign unassigned backlog items to a sprint from the flat prioritized backlog.
+Guided workflow to assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.
 
 <workflow>
 
-<step n="1" goal="Load backlog and identify unassigned items">
-  <action>Read `_bmad-output/implementation-artifacts/backlog.yaml`</action>
-  <action>Parse the `backlog` array. Filter items where `sprint` is `null` (unassigned).</action>
-  <action>Sort filtered items by `priority` ascending (lowest number = highest priority).</action>
-  <action>Store as {{unassigned_items}} list.</action>
-  <check if="no unassigned items remain">
-    <output>All backlog items are already assigned to sprints. Nothing to assign.</output>
-    <action>Exit workflow</action>
+<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="2" goal="Load sprints and select target">
-  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to discover all sprint files</action>
+<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">
-    <output>No sprints exist. Run `/add-sprint` first to create a sprint before assigning items.</output>
-    <action>Exit workflow</action>
+    <action>Set {{all_assigned_items}} = [] — no filtering needed when no sprints exist yet</action>
   </check>
-  <action>Read each sprint file; extract: id, name, status, capacity, items (array length = assigned count)</action>
-  <action>Sort sprints by status: `active` first, then `planning`, then `closed`</action>
-  <action>Display sprints table (closed sprints shown but marked as not selectable):</action>
+</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>
-## Available Sprints
+## 📋 Backlog Items
 
-| # | ID | Name | Status | Capacity | Assigned | Remaining |
-|---|---|---|---|---|---|---|
-{{#each sprints}}
-| {{@index+1}} | {{id}} | {{name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
+| # | ID / File | Title | Type | Status/Severity |
+|---|---|---|---|---|
+{{#each backlog_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status_or_severity}} |
 {{/each}}
 
-*Closed sprints are shown for reference but cannot be selected.*
+*Total: {{story_count}} stories, {{bug_count}} bugs*
   </output>
-  <check if="exactly one active sprint exists">
-    <output>Auto-selecting active sprint: {{active_sprint.name}} ({{active_sprint.id}})</output>
-    <ask>Proceed with this sprint? [y] Yes / [n] Choose a different sprint:</ask>
-    <check if="user selects 'y'">
-      <action>Set {{target_sprint}} = the active sprint</action>
-    </check>
-    <check if="user selects 'n'">
-      <ask>Select target sprint by number (active or planning only):</ask>
-      <action>Validate selection is not a closed sprint</action>
-      <action>Store as {{target_sprint}}</action>
-    </check>
-  </check>
-  <check if="no active sprint exists OR multiple active/planning sprints">
-    <ask>Select target sprint by number (active or planning only):</ask>
-    <action>Validate selection is not a closed sprint</action>
-    <check if="user selected a closed sprint">
-      <output>Closed sprints cannot receive new items. Select an active or planning sprint.</output>
-      <goto step="2" />
-    </check>
-    <action>Store as {{target_sprint}}</action>
+</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="3" goal="Display sprint capacity and unassigned backlog items">
-  <action>Calculate: {{assigned_count}} = length of {{target_sprint.items}}</action>
+<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.name}} ({{target_sprint.id}})
+## Sprint Capacity: {{target_sprint.sprint_name}}
 
-[{{capacity_bar}}] {{assigned_count}}/{{target_sprint.capacity}} items ({{remaining_capacity}} remaining)
+- **Capacity:** {{target_sprint.capacity}} items
+- **Assigned:** {{assigned_count}} items
+- **Remaining:** {{remaining_capacity}} slots
 
 {{#if remaining_capacity <= 0}}
-Warning: This sprint is at or over capacity. Adding items will exceed the limit.
+⚠️ 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>
 
-  <action>Take the top 20 items from {{unassigned_items}} (or all if fewer than 20)</action>
+<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>
-## Unassigned Backlog Items
+## 🎯 Prioritization Analysis
 
-| # | ID | Title | Type | Priority | Severity |
-|---|---|---|---|---|---|
-{{#each displayed_items}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{priority}} | {{severity_or_na}} |
+| 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}}
 
-*Showing {{displayed_count}} of {{total_unassigned}} unassigned items.*
+**Recommended selection** (up to {{remaining_capacity}} items to stay within capacity): {{recommended_selection}}
   </output>
 </step>
 
-<step n="4" goal="Prompt for item selection">
-  <ask>Select items to add (comma-separated numbers, 'all' for all shown, or 'q' to cancel):</ask>
-  <check if="user enters 'q'">
-    <output>Assignment cancelled -- no changes made.</output>
+<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 enters 'all'">
-    <action>Set {{selected_items}} = all displayed items from step 3</action>
+  <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 enters comma-separated numbers">
-    <action>Parse and validate each number is within the displayed list range</action>
-    <check if="any number is invalid or out of range">
-      <output>Invalid selection: {{invalid_numbers}}. Enter numbers from the list above.</output>
-      <goto step="4" />
-    </check>
-    <action>Set {{selected_items}} = the items corresponding to the entered numbers</action>
+  <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="5" goal="Capacity check and assignment">
-  <action>For each item in {{selected_items}}, in order:</action>
-  <action>Re-calculate current assigned count (accounts for items already added in this session)</action>
-  <check if="adding this item would exceed capacity">
-    <output>Capacity Warning: Adding "{{item.title}}" ({{item.id}}) would bring assigned items to {{new_count}}/{{target_sprint.capacity}} -- exceeding sprint capacity by {{overage}}.</output>
+<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
-- [q] Quit (stop assigning, keep items already assigned this session)
+- [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.</action>
-    </check>
-    <check if="user selects 'q'">
-      <action>Stop processing remaining items. Proceed to step 6 with items confirmed so far.</action>
+      <action>Skip this item — do not add to sprint. Continue to next item in the {{confirmed_items}} loop.</action>
     </check>
-    <check if="user selects 'a'">
-      <action>Proceed with adding this item despite over-capacity.</action>
+    <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>For each confirmed item:
-    - Add item ID to {{target_sprint}}.items array
-    - Set item's `sprint` field in backlog.yaml to {{target_sprint.id}}
-    - Update {{target_sprint}}.last_modified to current ISO timestamp
-  </action>
-  <action>Store all confirmed items as {{assigned_items}} for the summary.</action>
+  <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="6" goal="Persist changes and display summary">
-  <check if="no items were confirmed for assignment">
-    <output>No items were assigned. No files modified.</output>
-    <action>Exit workflow</action>
-  </check>
-  <action>**Dual-write — both files must be updated for consistency:**</action>
-  <action>Write updated `_bmad-output/implementation-artifacts/backlog.yaml`:
-    - Preserve all existing fields on all items
-    - Only the `sprint` field changes on assigned items (set to {{target_sprint.id}})
-  </action>
-  <check if="backlog.yaml write fails">
-    <output>**Error:** Failed to write backlog.yaml. No changes persisted. Sprint file NOT modified.</output>
-    <action>Exit workflow</action>
-  </check>
-  <action>Write updated `_bmad-output/implementation-artifacts/sprints/{{target_sprint.id}}.yaml`:
-    - Append confirmed item IDs to the `items` array
+<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
-    - Preserve all other fields unchanged
   </action>
-  <check if="sprint file write fails">
-    <output>**Warning: Inconsistent state!** backlog.yaml was updated but sprint file write failed. The `sprint` field in backlog.yaml now references {{target_sprint.id}} but the sprint file's `items` array is stale. Re-run `/add-to-sprint` or manually fix `sprints/{{target_sprint.id}}.yaml`.</output>
-  </check>
-  <action>**Do NOT read or write sprint-plan-*.yaml or sprint-status.yaml**</action>
+  <action>**Do NOT modify sprint-status.yaml** — sprint membership is exclusively tracked in sprint-plan-{n}.yaml</action>
   <output>
-## Assignment Complete
+## ✅ Assignment Complete
 
-**Sprint:** {{target_sprint.name}} ({{target_sprint.id}})
-**Items assigned this session:** {{assigned_count_this_session}}
+**Sprint:** {{target_sprint.sprint_name}}
+**Items assigned this session:** {{assigned_this_session}}
 
-| # | ID | Title | Type | Priority |
-|---|---|---|---|---|
-{{#each assigned_items}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{priority}} |
+### 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}}
 
-**Capacity Usage:** {{new_assigned_total}}/{{target_sprint.capacity}} items ({{new_remaining}} remaining)
+**Updated Capacity:** {{new_assigned_count}}/{{target_sprint.capacity}} items used ({{new_remaining}} remaining)
 
 **Next Steps:**
-- Use `/add-to-sprint` again to assign more items
 - Use `/modify-sprint` to adjust capacity or remove items
 - Use `/sprint-status-view` to view the full sprint with all assigned items
   </output>