ma-agents 3.4.9 → 3.5.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 entry in the sprints section of sprint-status.yaml with capacity limits, optional ISO dates, and auto-incremented ID
 type: skill
 triggers:
   - "add sprint"
@@ -9,112 +9,166 @@ 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 entry in the `sprints` section of `sprint-status.yaml` with capacity limits, optional ISO dates, and auto-incremented sprint ID.
 
 <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="0" goal="Load configuration and validate file existence">
+  <action>Resolve the path to `sprint-status.yaml`. Check `_bmad/bmm/config.yaml` for a configured `story_location` path; if not set, default to `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+  <action>Attempt to read the file at the resolved path</action>
+  <check if="sprint-status.yaml does not exist">
+    <output>No sprint-status.yaml found. Run sprint planning first to initialize the file.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Read and parse the full file: `epics`, `backlog`, and `sprints` sections plus all metadata fields</action>
+  <action>Store parsed content as {{file_content}}</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>
+<step n="1" goal="Auto-increment sprint ID and derive default name">
+  <action>Extract all keys from the `sprints` map in {{file_content}}</action>
+  <action>Parse numeric suffix from each key matching pattern `sprint-N` (e.g., `sprint-1` → 1, `sprint-3` → 3)</action>
+  <check if="no sprint keys exist in sprints map">
+    <action>Set {{new_number}} = 1</action>
+    <action>Set {{default_name}} = "Sprint 1"</action>
+  </check>
+  <check if="sprint keys exist">
+    <action>Find the highest numeric suffix among all sprint keys; store as {{max_number}}</action>
+    <action>Set {{new_number}} = {{max_number}} + 1</action>
+    <action>Look up the sprint entry whose key has suffix {{max_number}}; read its `name` field</action>
+    <action>If the name matches pattern "Sprint N" or "Sprint N — description" or "Sprint N - description", set {{default_name}} = "Sprint {{new_number}}"; otherwise set {{default_name}} = "Sprint {{new_number}}" as safe fallback</action>
+  </check>
+  <action>Set {{sprint_id}} = "sprint-{{new_number}}"</action>
+  <action>Set {{sprint_name}} = {{default_name}}</action>
+  <output>
+Auto-generated Sprint ID: **{{sprint_id}}**
+Default Sprint Name: **{{sprint_name}}**
+  </output>
+  <ask>Sprint ID: {{sprint_id}} — press Enter to accept or type a different number:</ask>
+  <check if="user provides a different number">
+    <action>Set {{sprint_id}} = "sprint-{user_number}"</action>
+    <action>Check if {{sprint_id}} already exists as a key in the `sprints` map</action>
+    <check if="sprint_id already exists">
+      <output>Sprint ID {{sprint_id}} already exists in sprint-status.yaml. Please choose a different number.</output>
+      <goto step="1" sub="re-prompt for number only" />
+    </check>
+    <action>Update {{sprint_name}} default to "Sprint {user_number}"</action>
+  </check>
+  <ask>Sprint name: '{{sprint_name}}' — press Enter to accept or type a different name:</ask>
+  <check if="user provides a different name">
+    <action>Set {{sprint_name}} = user input</action>
+  </check>
+</step>
+
+<step n="2" goal="Gather capacity (required)">
+  <action>Explain: capacity is the maximum number of items (stories + bugs) that can be assigned to this sprint. This is advisory — skills will warn but not block when exceeded (per schema section 4.2).</action>
+  <ask>What is the sprint capacity? (Enter a positive integer)</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>
+    <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 n="3" goal="Gather optional start and end dates">
+  <ask>Optional — Sprint start date (ISO format YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store as {{start_input}}</action>
+  <check if="start_input is not empty">
+    <action>Validate {{start_input}} matches ISO date pattern YYYY-MM-DD (4-digit year, 2-digit month 01-12, 2-digit day 01-31)</action>
+    <check if="start_input does not match ISO date pattern">
+      <output>Invalid date format: "{{start_input}}". Please use YYYY-MM-DD (e.g., 2026-04-15).</output>
+      <goto step="3" sub="re-prompt for start date only" />
+    </check>
+    <action>Store as {{start}} = {{start_input}}</action>
+  </check>
+  <check if="start_input is empty">
+    <action>Store as {{start}} = "" (empty string)</action>
+  </check>
+  <ask>Optional — Sprint end date (ISO format YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store as {{end_input}}</action>
+  <check if="end_input is not empty">
+    <action>Validate {{end_input}} matches ISO date pattern YYYY-MM-DD</action>
+    <check if="end_input does not match ISO date pattern">
+      <output>Invalid date format: "{{end_input}}". Please use YYYY-MM-DD (e.g., 2026-04-28).</output>
+      <goto step="3" sub="re-prompt for end date only" />
+    </check>
+    <check if="end_input is before start and start is not empty">
+      <output>Warning: end date {{end_input}} is before start date {{start}}. Continuing as requested.</output>
+    </check>
+    <action>Store as {{end}} = {{end_input}}</action>
+  </check>
+  <check if="end_input is empty">
+    <action>Store as {{end}} = "" (empty string)</action>
+  </check>
 </step>
 
-<step n="4" goal="Confirm and validate all inputs">
+<step n="4" goal="Confirmation">
   <output>
-## Sprint Summary — Please Confirm
+## New 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`
+- Sprint ID: {{sprint_id}}
+- Sprint Name: {{sprint_name}}
+- Capacity: {{capacity}} items
+- Start Date: {{start}} *(empty if skipped)*
+- End Date: {{end}} *(empty if skipped)*
+- Status: planning
+- Items: [] *(empty — use /add-to-sprint to assign items)*
+- Target: sprint-status.yaml sprints section
   </output>
-  <ask>Confirm creation? [y] Yes / [n] Cancel / [e] Edit a field:</ask>
+  <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>
+    <ask>Which field to edit? (id / name / capacity / start / end)</ask>
+    <check if="field == 'id'"><goto step="1" /></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>
+      <ask>Sprint name (or press Enter to use "{{sprint_name}}"):</ask>
+      <check if="input is not empty"><action>Set {{sprint_name}} = user input</action></check>
       <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="3" sub="start date only" /></check>
+    <check if="field == 'end'"><goto step="3" sub="end date only" /></check>
   </check>
   <check if="user selects 'n'">
-    <output>❌ Sprint creation cancelled.</output>
+    <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:
-
+<step n="5" goal="Write sprint entry to sprint-status.yaml">
+  <action>Re-read the current content of `sprint-status.yaml` (resolved path from Step 0) to get the latest state</action>
+  <action>Get the current ISO-8601 timestamp for `last_updated`</action>
+  <action>Append a new entry to the `sprints` map 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}}"
+  {{sprint_id}}:
+    name: "{{sprint_name}}"
+    status: planning
+    capacity: {{capacity}}
+    start: "{{start}}"
+    end: "{{end}}"
+    items: []
 ```
   </action>
+  <action>Preserve the `epics` section unchanged</action>
+  <action>Preserve the `backlog` section unchanged</action>
+  <action>Preserve all existing entries in the `sprints` section unchanged</action>
+  <action>Update the `last_updated` metadata field to the current ISO-8601 timestamp</action>
+  <action>Preserve the `generated` field unchanged (never modify)</action>
+  <action>Write the complete updated file in a single atomic write (read-modify-write pattern)</action>
+</step>
+
+<step n="6" goal="Summary output">
   <output>
-✅ **Sprint created successfully!**
+Sprint created successfully!
 
-- **File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
-- **Sprint:** {{sprint_name}}
-- **Capacity:** {{capacity}} items
-- **Status:** planning
+- Sprint: {{sprint_name}} ({{sprint_id}})
+- 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
+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>
 

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: Move backlog items to a sprint in the unified sprint-status.yaml using movement semantics
 type: skill
 triggers:
   - "add to sprint"
@@ -9,88 +9,81 @@ triggers:
 
 # Add-to-Sprint Workflow
 
-Guided workflow to assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.
+Guided workflow to move backlog items to a sprint in the unified `sprint-status.yaml` using movement semantics.
+
+**Movement semantics:** Each item exists in exactly one location — either the `backlog` array OR a sprint's `items` array, never both. This skill atomically removes items from `backlog` and appends them to the target sprint's `items` array in a single file write.
 
 <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)
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Resolve the path to `sprint-status.yaml`:
+    1. If `_bmad/bmm/config.yaml` exists, read `sprint_management_path` from it; the file is at `{sprint_management_path}/_bmad-output/implementation-artifacts/sprint-status.yaml`
+    2. Otherwise, use the default single-repo path: `_bmad-output/implementation-artifacts/sprint-status.yaml`
   </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 if="file does not exist at resolved path">
+    <output>❌ No sprint-status.yaml found. Run `/bmad-sprint-planning` first to initialize the file.</output>
+    <action>Exit workflow</action>
   </check>
+  <action>Read and parse the full file: `epics`, `backlog`, and `sprints` sections plus metadata fields</action>
+  <action>Store the complete parsed document as {{sprint_status}} for atomic write-back later</action>
 </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="Identify assignable sprints">
+  <action>Parse the `sprints` map from {{sprint_status}}</action>
+  <action>Filter to sprints with `status: planning` or `status: active` — exclude `status: closed` sprints</action>
+  <check if="no assignable sprints remain (all sprints are closed or sprints map is empty)">
+    <output>❌ No assignable sprints found. Run `/add-sprint` first to create a sprint before assigning items.</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
+  <check if="exactly one assignable sprint">
+    <action>Auto-select it as {{target_sprint}} (skip selection prompt)</action>
+    <output>ℹ️ Auto-selected the only assignable sprint: **{{target_sprint.name}}** ({{target_sprint.status}})</output>
+  </check>
+  <check if="multiple assignable sprints">
+    <action>Build a sprint selection table from the assignable sprints</action>
+    <output>
+## Available Sprints
 
-| # | ID / File | Title | Type | Status/Severity |
-|---|---|---|---|---|
-{{#each backlog_items}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status_or_severity}} |
+| # | Sprint | Status | Capacity | Assigned | Remaining |
+|---|--------|--------|----------|----------|-----------|
+{{#each assignable_sprints}}
+| {{@index+1}} | {{name}} | {{status}} | {{capacity}} | {{items.length}} | {{capacity - items.length}} |
 {{/each}}
-
-*Total: {{story_count}} stories, {{bug_count}} bugs*
-  </output>
+    </output>
+    <ask>Select target sprint (enter number):</ask>
+    <action>Resolve entered number to the corresponding sprint entry and store as {{target_sprint}} (the sprint's map key and full sprint object)</action>
+  </check>
 </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>
+<step n="2" goal="Display backlog items eligible for sprint assignment">
+  <action>Read the `backlog` array from {{sprint_status}}</action>
+  <action>Filter to items with `status: ready-for-dev` ONLY — schema section 4.5 movement rules require this status for sprint assignment</action>
+  <check if="no ready-for-dev items exist in the backlog">
+    <output>❌ No items eligible for sprint assignment. Items must have `status: ready-for-dev` to be added to a sprint. Items with `status: backlog` must first have a story file created (which advances them to `ready-for-dev`).</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>Display eligible backlog items in priority order (array order = priority order, position 0 = highest priority)</action>
   <output>
-## 🏃 Available Sprints
+## Backlog Items (eligible for sprint assignment)
 
-| # | Sprint | Status | Capacity | Assigned | Remaining |
-|---|---|---|---|---|---|
-{{#each sprints}}
-| {{@index+1}} | {{sprint_name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
+| # | ID | Title | Type | Epic | Severity |
+|---|-----|-------|------|------|----------|
+{{#each eligible_backlog_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{epic}} | {{severity}} |
 {{/each}}
+
+*Total eligible: {{eligible_count}} items (status: ready-for-dev)*
   </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>
+<step n="3" goal="Display sprint capacity">
+  <action>Calculate capacity usage: current assigned count = `{{target_sprint.items.length}}`</action>
+  <action>Calculate remaining = `{{target_sprint.capacity}} - {{target_sprint.items.length}}`</action>
   <output>
-## Sprint Capacity: {{target_sprint.sprint_name}}
+## Sprint Capacity: {{target_sprint.name}}
 
 - **Capacity:** {{target_sprint.capacity}} items
-- **Assigned:** {{assigned_count}} items
+- **Assigned:** {{target_sprint.items.length}} items
 - **Remaining:** {{remaining_capacity}} slots
 
 {{#if remaining_capacity <= 0}}
@@ -99,17 +92,19 @@ Guided workflow to assign backlog items (stories + bugs) to a sprint using multi
   </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>
+<step n="4" 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 eligible 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>
+    <action>Set {{candidate_items}} = all items from the eligible backlog list displayed in 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>
+    <action>Resolve the entered numbers against the eligible backlog table from step 2</action>
+    <action>Validate all entered numbers correspond to displayed items — report error for any invalid numbers</action>
+    <action>Set {{candidate_items}} = those specific items</action>
   </check>
 </step>
 
-<step n="6" goal="Multi-criteria prioritization guidance">
+<step n="5" goal="Multi-criteria prioritization analysis">
   <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
@@ -123,10 +118,10 @@ Guided workflow to assign backlog items (stories + bugs) to a sprint using multi
     4. Avoid blocked items unless capacity allows waiting
   </action>
   <output>
-## 🎯 Prioritization Analysis
+## Prioritization Analysis
 
-| Rank | ID / File | Title | Type | Business Value | Dependencies | Severity | Effort | Rationale |
-|---|---|---|---|---|---|---|---|---|
+| Rank | ID | Title | Type | Business Value | Dependencies | Severity | Effort | Rationale |
+|------|----|-------|------|----------------|--------------|----------|--------|-----------|
 {{#each ranked_items}}
 | {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} | {{rationale}} |
 {{/each}}
@@ -135,7 +130,7 @@ Guided workflow to assign backlog items (stories + bugs) to a sprint using multi
   </output>
 </step>
 
-<step n="7" goal="User confirms or adjusts ranking">
+<step n="6" goal="User confirms or adjusts selection">
   <ask>Review the ranking above. Options:
 - [c] Confirm recommended selection as-is
 - [m] Modify selection (specify item numbers to include)
@@ -149,65 +144,98 @@ Choice:</ask>
   </check>
   <check if="user selects 'm'">
     <ask>Enter item numbers to assign (comma-separated):</ask>
-    <action>Update {{confirmed_items}} with user selection</action>
+    <action>Resolve entered numbers against the eligible backlog table from step 2</action>
+    <action>Set {{confirmed_items}} = those specific items</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>
+    <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 backlog:</ask>
+    <action>Set {{confirmed_items}} = items matching the user-provided numbers, in the order provided. Items from {{candidate_items}} NOT mentioned are excluded from this session (they remain in the backlog for future sprints).</action>
   </check>
   <check if="user selects 'c'">
-    <action>Set {{confirmed_items}} = recommended selection</action>
+    <action>Set {{confirmed_items}} = recommended selection from step 5</action>
   </check>
-  <action>Store confirmed ranking in {{confirmed_ranking}} for auditability (included in workflow output)</action>
+  <action>Store confirmed ranking in {{confirmed_ranking}} for the audit record</action>
 </step>
 
-<step n="8" goal="Assign selected items to sprint with capacity enforcement">
+<step n="7" goal="Execute movement with capacity enforcement">
+  <action>Initialize {{current_sprint_count}} = {{target_sprint.items.length}} (current assigned count before any additions this session)</action>
+  <action>Initialize {{items_to_move}} = [] (items confirmed for movement)</action>
   <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>
+  <check if="adding this item would exceed sprint capacity (current_sprint_count + 1 > target_sprint.capacity)">
+    <output>⚠️ **Capacity Warning:** Adding "{{item.title}}" would bring assigned items to {{current_sprint_count + 1}}/{{target_sprint.capacity}} — exceeding sprint capacity by {{current_sprint_count + 1 - target_sprint.capacity}}.</output>
     <ask>Options:
 - [a] Add anyway (over-capacity acknowledged)
-- [s] Skip this item
-- [m] Modify sprint capacity first via `/modify-sprint`
+- [s] Skip this item (leave in backlog)
+- [m] Exit to run `/modify-sprint` to increase capacity first
 
 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 {{items_to_move}}. Continue to next item.</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>
+      <output>💡 Run `/modify-sprint` to increase capacity for **{{target_sprint.name}}**, then re-run `/add-to-sprint`.</output>
+      <action>Exit workflow without making any changes</action>
     </check>
+    <check if="user selects 'a'">
+      <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</action>
+    </check>
+  </check>
+  <check if="item is within capacity">
+    <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</action>
   </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
+<step n="8" goal="Atomic write — persist all movements to sprint-status.yaml">
+  <action>If {{items_to_move}} is empty (all items were skipped or cancelled), exit without writing.</action>
+
+  <action>**Pre-write: single-location invariant check.** Build {{all_sprint_item_ids}} = flat set of all item IDs across ALL sprints in {{sprint_status}}.sprints (every sprint, every status). For each item in {{items_to_move}}: check if its ID exists in {{all_sprint_item_ids}}. If ANY match is found:
+    <output>**Error:** Data integrity violation — item {{item.id}} already exists in a sprint. Aborting to prevent duplicate. The sprint-status.yaml file may be corrupted. No changes have been written.</output>
+    <action>Exit workflow without writing</action>
+  </action>
+
+  <action>**Pre-write: backlog re-validation.** Build {{current_backlog_ids}} = set of all item IDs currently in {{sprint_status}}.backlog. For each item in {{items_to_move}}: check if its ID exists in {{current_backlog_ids}}. If ANY item is missing:
+    <output>**Error:** Item {{item.id}} was selected for sprint assignment but is no longer in the backlog. The file may have been modified externally. No changes have been written. Please re-run `/add-to-sprint` to start fresh.</output>
+    <action>Exit workflow without writing</action>
   </action>
-  <action>**Do NOT modify sprint-status.yaml** — sprint membership is exclusively tracked in sprint-plan-{n}.yaml</action>
+
+  <action>Perform ALL of the following in a single atomic write to `sprint-status.yaml`:</action>
+  <action>1. For each item in {{items_to_move}}:
+    - Build the sprint item object: copy `id`, `type`, `epic`, `title`, `status`, `severity` from the backlog item — DROP the `priority` field (sprint items do not have priority)
+    - APPEND the sprint item object to `sprints[{{target_sprint_key}}].items`
+    - REMOVE the original item object from the `backlog` array
+  </action>
+  <action>2. Renumber remaining backlog items' `priority` values sequentially (1..N) to match their new array positions (position 0 → priority 1, position 1 → priority 2, etc.)</action>
+  <action>3. Update `last_updated` to the current ISO-8601 timestamp</action>
+  <action>4. Preserve `generated`, `epics`, and all other metadata fields unchanged</action>
+  <action>5. Write the complete updated `sprint-status.yaml` in a single write operation (all removals + additions + renumbering happen together — no partial state)</action>
+</step>
+
+<step n="9" goal="Display summary">
   <output>
-## ✅ Assignment Complete
+## Assignment Complete
+
+**Sprint:** {{target_sprint.name}}
+**Items assigned this session:** {{items_to_move.length}}
 
-**Sprint:** {{target_sprint.sprint_name}}
-**Items assigned this session:** {{assigned_this_session}}
+| # | ID | Title | Type |
+|---|----|-------|------|
+{{#each items_to_move}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} |
+{{/each}}
 
 ### 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)
+**Updated Capacity:** {{current_sprint_count}}/{{target_sprint.capacity}} items used ({{target_sprint.capacity - current_sprint_count}} remaining)
 
 **Next Steps:**
-- Use `/modify-sprint` to adjust capacity or remove items
+- Use `/remove-from-sprint` to move items back to backlog if needed
+- Use `/modify-sprint` to adjust capacity or sprint metadata
 - Use `/sprint-status-view` to view the full sprint with all assigned items
   </output>
 </step>

package/{.opencode/skills/add-to-sprint → lib/bmad-extension/skills/bmad-dev-story}/bmad-skill-manifest.yaml

@@ -1,3 +1,3 @@
 type: skill
-name: add-to-sprint
+name: bmad-dev-story
 module: ma-skills