ma-agents 3.1.0 → 3.3.0

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

@@ -1,6 +1,6 @@
 ---
 name: add-sprint
-description: Guided workflow to create a new sprint with capacity limits for realistic sprint planning
+description: Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema for sprint planning
 type: skill
 triggers:
   - "add sprint"
@@ -9,17 +9,35 @@ triggers:
 
 # Add Sprint Workflow
 
-Guided workflow to create a new sprint with capacity limits for realistic sprint planning.
+Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema.
 
 <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 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>
 
 <step n="2" goal="Gather capacity as positive integer">
@@ -34,32 +52,71 @@ Guided workflow to create a new sprint with capacity limits for realistic sprint
   <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 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>
 
 <step n="4" goal="Confirm and validate all inputs">
   <output>
 ## Sprint Summary — Please Confirm
 
-- **Sprint Number:** {{sprint_number}}
-- **Sprint Name:** {{sprint_name}}
+- **Sprint ID:** {{sprint_id}}
+- **Sprint Name:** "{{sprint_name}}"
+- **Status:** planning
 - **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`
+- **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`
   </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>
+      <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>
       <goto step="4" />
     </check>
     <check if="field == 'name'">
@@ -68,45 +125,74 @@ Guided workflow to create a new sprint with capacity limits for realistic sprint
       <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 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>
   <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 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>
+<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>
     <check if="user selects 'n'">
-      <output>❌ Sprint creation cancelled to preserve existing sprint plan.</output>
+      <output>❌ Sprint creation cancelled to preserve existing sprint.</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 artifact YAML to `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml` with this structure:
+  <action>Write sprint entity YAML to `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml` with this structure:
 
 ```yaml
-sprint_number: {{sprint_number}}
-sprint_name: "{{sprint_name}}"
-capacity: {{capacity}}
-assigned_items: []
+id: {{sprint_id}}
+name: "{{sprint_name}}"
 status: planning
-start_context: "{{start_context}}"
-end_context: "{{end_context}}"
+capacity: {{capacity}}
+start: "{{start_date}}"
+end: "{{end_date}}"
+items: []
 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/sprint-plan-{{sprint_number}}.yaml`
+- **File:** `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.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 using multi-criteria prioritization
+description: Guided workflow to assign backlog items to a sprint from the flat prioritized backlog
 type: skill
 triggers:
   - "add to sprint"
@@ -9,204 +9,178 @@ triggers:
 
 # Add-to-Sprint Workflow
 
-Guided workflow to assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.
+Guided workflow to assign unassigned backlog items to a sprint from the flat prioritized backlog.
 
 <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>
+<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>
   </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>
+<step n="2" goal="Load sprints and select target">
+  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to discover all sprint 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>
+    <output>No sprints exist. 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>
+  <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>
   <output>
-## 🏃 Available Sprints
+## Available Sprints
 
-| # | Sprint | Status | Capacity | Assigned | Remaining |
-|---|---|---|---|---|---|
+| # | ID | Name | Status | Capacity | Assigned | Remaining |
+|---|---|---|---|---|---|---|
 {{#each sprints}}
-| {{@index+1}} | {{sprint_name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
+| {{@index+1}} | {{id}} | {{name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
 {{/each}}
+
+*Closed sprints are shown for reference but cannot be selected.*
   </output>
-  <ask>Select target sprint (enter number):</ask>
-  <action>Store selected sprint data as {{target_sprint}}</action>
+  <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>
+  </check>
 </step>
 
-<step n="4" goal="Display current sprint capacity usage">
-  <action>Calculate: {{assigned_count}} = length of {{target_sprint.assigned_items}}</action>
+<step n="3" goal="Display sprint capacity and unassigned backlog items">
+  <action>Calculate: {{assigned_count}} = length of {{target_sprint.items}}</action>
   <action>Calculate: {{remaining_capacity}} = {{target_sprint.capacity}} - {{assigned_count}}</action>
   <output>
-## Sprint Capacity: {{target_sprint.sprint_name}}
+## Sprint Capacity: {{target_sprint.name}} ({{target_sprint.id}})
 
-- **Capacity:** {{target_sprint.capacity}} items
-- **Assigned:** {{assigned_count}} items
-- **Remaining:** {{remaining_capacity}} slots
+[{{capacity_bar}}] {{assigned_count}}/{{target_sprint.capacity}} items ({{remaining_capacity}} remaining)
 
 {{#if remaining_capacity <= 0}}
-⚠️ This sprint is **at or over capacity**. Adding items will exceed the limit.
+Warning: 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>
+  <action>Take the top 20 items from {{unassigned_items}} (or all if fewer than 20)</action>
   <output>
-## 🎯 Prioritization Analysis
+## Unassigned Backlog Items
 
-| 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}} |
+| # | ID | Title | Type | Priority | Severity |
+|---|---|---|---|---|---|
+{{#each displayed_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{priority}} | {{severity_or_na}} |
 {{/each}}
 
-**Recommended selection** (up to {{remaining_capacity}} items to stay within capacity): {{recommended_selection}}
+*Showing {{displayed_count}} of {{total_unassigned}} unassigned items.*
   </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>
+<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>
     <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 if="user enters 'all'">
+    <action>Set {{selected_items}} = all displayed items from step 3</action>
   </check>
-  <check if="user selects 'c'">
-    <action>Set {{confirmed_items}} = recommended selection</action>
+  <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>
-  <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>
+<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>
     <ask>Options:
 - [a] Add anyway (over-capacity acknowledged)
 - [s] Skip this item
-- [m] Modify sprint capacity first via `/modify-sprint`
+- [q] Quit (stop assigning, keep items already assigned this session)
 
 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>
+      <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>
     </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 if="user selects 'a'">
+      <action>Proceed with adding this item despite over-capacity.</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>
+  <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>
 </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
+<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
     - Update `last_modified` to current ISO timestamp
+    - Preserve all other fields unchanged
   </action>
-  <action>**Do NOT modify sprint-status.yaml** — sprint membership is exclusively tracked in sprint-plan-{n}.yaml</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>
   <output>
-## ✅ Assignment Complete
-
-**Sprint:** {{target_sprint.sprint_name}}
-**Items assigned this session:** {{assigned_this_session}}
+## Assignment Complete
 
-### Confirmed Ranking (Audit Record)
+**Sprint:** {{target_sprint.name}} ({{target_sprint.id}})
+**Items assigned this session:** {{assigned_count_this_session}}
 
-| Rank | ID | Title | Type | Business Value | Dependencies | Severity | Effort |
-|---|---|---|---|---|---|---|---|
-{{#each confirmed_ranking}}
-| {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} |
+| # | ID | Title | Type | Priority |
+|---|---|---|---|---|
+{{#each assigned_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{priority}} |
 {{/each}}
 
-**Updated Capacity:** {{new_assigned_count}}/{{target_sprint.capacity}} items used ({{new_remaining}} remaining)
+**Capacity Usage:** {{new_assigned_total}}/{{target_sprint.capacity}} items ({{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>