ma-agents 3.4.8 → 3.5.0

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: Move backlog items to a sprint in the unified sprint-status.yaml using movement semantics
 type: skill
 triggers:
   - "add to sprint"
@@ -9,179 +9,233 @@ triggers:
 
 # Add-to-Sprint Workflow
 
-Guided workflow to assign unassigned backlog items to a sprint from the flat prioritized backlog.
+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="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>
+<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>
+  <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="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 sprints exist. Run `/add-sprint` first to create a sprint before assigning items.</output>
+<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>
-  <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>
+  <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 | Name | Status | Capacity | Assigned | Remaining |
-|---|---|---|---|---|---|---|
-{{#each sprints}}
-| {{@index+1}} | {{id}} | {{name}} | {{status}} | {{capacity}} | {{assigned_count}} | {{remaining}} |
+| # | Sprint | Status | Capacity | Assigned | Remaining |
+|---|--------|--------|----------|----------|-----------|
+{{#each assignable_sprints}}
+| {{@index+1}} | {{name}} | {{status}} | {{capacity}} | {{items.length}} | {{capacity - items.length}} |
 {{/each}}
-
-*Closed sprints are shown for reference but cannot be selected.*
-  </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>
+    </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>
-  <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="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>Display eligible backlog items in priority order (array order = priority order, position 0 = highest priority)</action>
+  <output>
+## Backlog Items (eligible for sprint assignment)
+
+| # | 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>
 </step>
 
-<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>
+<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.name}} ({{target_sprint.id}})
+## Sprint Capacity: {{target_sprint.name}}
 
-[{{capacity_bar}}] {{assigned_count}}/{{target_sprint.capacity}} items ({{remaining_capacity}} remaining)
+- **Capacity:** {{target_sprint.capacity}} items
+- **Assigned:** {{target_sprint.items.length}} 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="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 from the eligible backlog list displayed in step 2</action>
+  </check>
+  <check if="user enters item numbers">
+    <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>
 
-  <action>Take the top 20 items from {{unassigned_items}} (or all if fewer than 20)</action>
+<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
+    - **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 | 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="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)
+- [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>Resolve entered numbers against the eligible backlog table from step 2</action>
+    <action>Set {{confirmed_items}} = those specific items</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 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 from step 5</action>
+  </check>
+  <action>Store confirmed ranking in {{confirmed_ranking}} for the audit record</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="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>
+  <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
-- [q] Quit (stop assigning, keep items already assigned this session)
+- [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.</action>
+      <action>Skip this item — do NOT add to {{items_to_move}}. 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 if="user selects 'm'">
+      <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>Proceed with adding this item despite over-capacity.</action>
+      <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</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>
+  <check if="item is within capacity">
+    <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</action>
+  </check>
 </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}})
+<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>
-  <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>**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>
-  <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>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
 
-**Sprint:** {{target_sprint.name}} ({{target_sprint.id}})
-**Items assigned this session:** {{assigned_count_this_session}}
+**Sprint:** {{target_sprint.name}}
+**Items assigned this session:** {{items_to_move.length}}
+
+| # | ID | Title | Type |
+|---|----|-------|------|
+{{#each items_to_move}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} |
+{{/each}}
+
+### Confirmed Ranking (Audit Record)
 
-| # | ID | Title | Type | Priority |
-|---|---|---|---|---|
-{{#each assigned_items}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{priority}} |
+| 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:** {{current_sprint_count}}/{{target_sprint.capacity}} items used ({{target_sprint.capacity - current_sprint_count}} remaining)
 
 **Next Steps:**
-- Use `/add-to-sprint` again to assign more items
-- 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

package/{.opencode → lib/bmad-extension}/skills/bmad-dev-story/checklist.md

@@ -18,18 +18,18 @@ validation-rules:
   - 'Enhanced story context must contain sufficient technical guidance'
 ---
 
-# 🎯 Enhanced Definition of Done Checklist
+# Enhanced Definition of Done Checklist
 
 **Critical validation:** Story is truly ready for review only when ALL items below are satisfied
 
-## 📋 Context & Requirements Validation
+## Context & Requirements Validation
 
 - [ ] **Story Context Completeness:** Dev Notes contains ALL necessary technical requirements, architecture patterns, and implementation guidance
 - [ ] **Architecture Compliance:** Implementation follows all architectural requirements specified in Dev Notes
 - [ ] **Technical Specifications:** All technical specifications (libraries, frameworks, versions) from Dev Notes are implemented correctly
 - [ ] **Previous Story Learnings:** Previous story insights incorporated (if applicable) and build upon appropriately
 
-## ✅ Implementation Completion
+## Implementation Completion
 
 - [ ] **All Tasks Complete:** Every task and subtask marked complete with [x]
 - [ ] **Acceptance Criteria Satisfaction:** Implementation satisfies EVERY Acceptance Criterion in the story
@@ -37,7 +37,7 @@ validation-rules:
 - [ ] **Edge Cases Handled:** Error conditions and edge cases appropriately addressed
 - [ ] **Dependencies Within Scope:** Only uses dependencies specified in story or project-context.md
 
-## 🧪 Testing & Quality Assurance
+## Testing & Quality Assurance
 
 - [ ] **Unit Tests:** Unit tests added/updated for ALL core functionality introduced/changed by this story
 - [ ] **Integration Tests:** Integration tests added/updated for component interactions when story requirements demand them
@@ -47,7 +47,7 @@ validation-rules:
 - [ ] **Code Quality:** Linting and static checks pass when configured in project
 - [ ] **Test Framework Compliance:** Tests use project's testing frameworks and patterns from Dev Notes
 
-## 📝 Documentation & Tracking
+## Documentation & Tracking
 
 - [ ] **File List Complete:** File List includes EVERY new, modified, or deleted file (paths relative to repo root)
 - [ ] **Dev Agent Record Updated:** Contains relevant Implementation Notes and/or Debug Log for this work
@@ -55,24 +55,24 @@ validation-rules:
 - [ ] **Review Follow-ups:** All review follow-up tasks (marked [AI-Review]) completed and corresponding review items marked resolved (if applicable)
 - [ ] **Story Structure Compliance:** Only permitted sections of story file were modified
 
-## 🔚 Final Status Verification
+## Final Status Verification
 
 - [ ] **Story Status Updated:** Story Status set to "review"
-- [ ] **Sprint Status Updated:** Sprint status updated to "review" (when sprint tracking is used)
+- [ ] **Sprint Status Updated:** Sprint status updated to "review" in sprint-status.yaml (item found by id in backlog or sprint items)
 - [ ] **Quality Gates Passed:** All quality checks and validations completed successfully
 - [ ] **No HALT Conditions:** No blocking issues or incomplete work remaining
 - [ ] **User Communication Ready:** Implementation summary prepared for user review
 
-## 🎯 Final Validation Output
+## Final Validation Output
 
 ```
 Definition of Done: {{PASS/FAIL}}
 
-✅ **Story Ready for Review:** {{story_key}}
-📊 **Completion Score:** {{completed_items}}/{{total_items}} items passed
-🔍 **Quality Gates:** {{quality_gates_status}}
-📋 **Test Results:** {{test_results_summary}}
-📝 **Documentation:** {{documentation_status}}
+Story Ready for Review: {{story_key}}
+Completion Score: {{completed_items}}/{{total_items}} items passed
+Quality Gates: {{quality_gates_status}}
+Test Results: {{test_results_summary}}
+Documentation: {{documentation_status}}
 ```
 
 **If FAIL:** List specific failures and required actions before story can be marked Ready for Review