ma-agents 3.4.8 → 3.5.0

package/skills/close-sprint/SKILL.md

@@ -0,0 +1,370 @@
+# Close Sprint Workflow
+
+Close an active sprint — archive done/cancelled items, disposition incomplete items (move to next sprint or return to backlog), and set sprint status to `closed`.
+
+**Schema Reference:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (Story 17.9)
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Set {{status_file}} = `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+  <action>Set {{story_location}} = resolve from {{status_file}} metadata field `story_location` (default: `_bmad-output/implementation-artifacts`)</action>
+
+  <check if="{{status_file}} does NOT exist">
+    <output>**Error:** No sprint-status.yaml found. Run sprint planning first to initialize the file.</output>
+    <action>Exit workflow</action>
+  </check>
+
+  <action>Read the FULL {{status_file}}</action>
+  <action>Parse into {{data}} with sections: metadata, `epics`, `backlog`, and `sprints`</action>
+  <action>Store {{story_location}} from {{data}}.metadata.story_location</action>
+</step>
+
+<step n="1" goal="Identify the active sprint">
+  <action>Scan {{data}}.sprints for a sprint with `status: active`</action>
+  <check if="no active sprint found">
+    <output>No active sprint found. Nothing to close.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Store the active sprint as {{active_sprint}} (id + full sprint data)</action>
+  <action>Store {{active_sprint_id}} = the sprint's map key (e.g., `sprint-1`)</action>
+</step>
+
+<step n="2" goal="Display sprint summary and confirm closure">
+  <action>Read {{active_sprint}}.items array</action>
+  <action>Store {{all_items}} = {{active_sprint}}.items</action>
+  <action>Store {{total_count}} = length of {{all_items}}</action>
+
+  <!-- Initialize counters and collections (always, to prevent undefined in summary output) -->
+  <action>Set {{done_count}} = 0</action>
+  <action>Set {{cancelled_count}} = 0</action>
+  <action>Set {{moved_to_sprint_count}} = 0</action>
+  <action>Set {{moved_to_sprint_name}} = ""</action>
+  <action>Set {{returned_to_backlog_count}} = 0</action>
+  <action>Set {{archived_done_files}} = []</action>
+  <action>Set {{archived_cancelled_files}} = []</action>
+  <action>Set {{skipped_done}} = []</action>
+  <action>Set {{skipped_cancelled}} = []</action>
+
+  <check if="{{total_count}} == 0">
+    <action>Set {{empty_sprint_fast_path}} = true</action>
+    <action>Jump to step 7 (empty sprint fast path)</action>
+  </check>
+
+  <action>Set {{empty_sprint_fast_path}} = false</action>
+  <action>Categorize items:
+    - {{done_items}} = items where status == `done`
+    - {{cancelled_items}} = items where status == `cancelled`
+    - {{incomplete_items}} = items where status is `ready-for-dev`, `in-progress`, `review`, or `on-hold`
+  </action>
+
+  <output>
+## Sprint Closure Summary: {{active_sprint.name}} ({{active_sprint_id}})
+
+**Total items:** {{total_count}}
+- Done: {{done_items.length}} (will be archived)
+- Cancelled: {{cancelled_items.length}} (will be archived)
+- Incomplete: {{incomplete_items.length}} (requires disposition)
+
+| # | ID | Title | Type | Status | Disposition |
+|---|----|----|----|----|---|
+{{#each done_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | done | archive to done/ |
+{{/each}}
+{{#each cancelled_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | cancelled | archive to done/ |
+{{/each}}
+{{#each incomplete_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status}} | pending decision |
+{{/each}}
+  </output>
+
+  <ask>Proceed with sprint closure? [c] Confirm and proceed / [x] Cancel:</ask>
+  <check if="user selects 'x'">
+    <output>Sprint closure cancelled. No changes made.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="3" goal="Archive done items (AC: 2)">
+  <check if="{{done_items}} is empty">
+    <action>Skip to step 4 (done_count stays 0, archived_done_files stays [])</action>
+  </check>
+
+  <action>Ensure `{{story_location}}/done/` directory exists. If it does not exist, create it.</action>
+
+  <action>For each item in {{done_items}}:
+    1. Resolve source path: `{{story_location}}/{{item.id}}.md`
+       - For bug items (type == bug): also try `{{story_location}}/bug-{{item.id_slug}}.md` as fallback (handle case variations)
+    2. Resolve destination path: `{{story_location}}/done/{{item.id}}.md`
+    3. If source file does NOT exist:
+       - Log warning: "File not found: {{source_path}} — skipping file move."
+       - Add item to {{skipped_done}} with reason "source missing"
+       - Continue to next item
+    4. If destination file ALREADY EXISTS in done/:
+       - Log warning: "File already exists at destination: {{destination_path}} — skipping file move."
+       - Add item to {{skipped_done}} with reason "destination exists"
+       - Continue to next item
+    5. Move (rename) the file: source → destination
+    6. Add item to {{archived_done_files}}
+  </action>
+
+  <action>Remove ALL done items from {{active_sprint}}.items in {{data}}</action>
+  <action>Store {{done_count}} = length of {{done_items}}</action>
+</step>
+
+<step n="4" goal="Archive cancelled items (AC: 3)">
+  <check if="{{cancelled_items}} is empty">
+    <action>Skip to step 5 (cancelled_count stays 0, archived_cancelled_files stays [])</action>
+  </check>
+
+  <action>Ensure `{{story_location}}/done/` directory exists (may already exist from step 3)</action>
+
+  <action>For each item in {{cancelled_items}}:
+    1. Resolve source path: `{{story_location}}/{{item.id}}.md`
+       - For bug items (type == bug): also try `{{story_location}}/bug-{{item.id_slug}}.md` as fallback (handle case variations)
+    2. Resolve destination path: `{{story_location}}/done/{{item.id}}.md`
+    3. If source file does NOT exist:
+       - Log warning: "File not found: {{source_path}} — skipping file move."
+       - Add item to {{skipped_cancelled}} with reason "source missing"
+       - Continue to next item
+    4. If destination file ALREADY EXISTS in done/:
+       - Log warning: "File already exists at destination: {{destination_path}} — skipping file move."
+       - Add item to {{skipped_cancelled}} with reason "destination exists"
+       - Continue to next item
+    5. Move (rename) the file: source → destination
+    6. Add item to {{archived_cancelled_files}}
+  </action>
+
+  <action>Remove ALL cancelled items from {{active_sprint}}.items in {{data}}</action>
+  <action>Store {{cancelled_count}} = length of {{cancelled_items}}</action>
+</step>
+
+<step n="5" goal="Disposition incomplete items (AC: 4, 11)">
+  <check if="{{incomplete_items}} is empty">
+    <action>Skip to step 6</action>
+  </check>
+
+  <output>
+## Incomplete Items Requiring Disposition
+
+| # | ID | Title | Type | Status |
+|---|----|----|----|----|
+{{#each incomplete_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status}} |
+{{/each}}
+
+**Options:**
+**(a)** Move all to the next sprint
+**(b)** Return all to backlog
+**(c)** Decide per item
+  </output>
+
+  <ask>Choose disposition option [a/b/c]:</ask>
+
+  <!-- OPTION A: Move all to next sprint -->
+  <check if="user selects 'a'">
+    <action>Scan {{data}}.sprints for sprints with `status: planning`</action>
+    <action>Store {{planning_sprints}} = list of planning sprints</action>
+
+    <check if="{{planning_sprints}} is empty">
+      <output>**No planning sprint found.** Run `/add-sprint` to create one, or choose option (b) to return items to backlog.</output>
+      <ask>Choose disposition option [b] Return all to backlog / [c] Decide per item:</ask>
+      <check if="user selects 'b'"><goto option_b /></check>
+      <check if="user selects 'c'"><goto option_c /></check>
+    </check>
+
+    <check if="{{planning_sprints}}.length > 1">
+      <output>
+## Planning Sprints Available
+
+| # | Sprint | Capacity | Items | Remaining |
+|---|---|---|---|---|
+{{#each planning_sprints}}
+| {{@index+1}} | {{name}} ({{id}}) | {{capacity}} | {{items_count}} | {{remaining}} |
+{{/each}}
+      </output>
+      <ask>Select target sprint (enter number):</ask>
+      <action>Store {{target_sprint}} = selected planning sprint</action>
+    </check>
+
+    <check if="{{planning_sprints}}.length == 1">
+      <action>Store {{target_sprint}} = {{planning_sprints}}[0]</action>
+    </check>
+
+    <action>Calculate {{new_count}} = {{target_sprint}}.items.length + {{incomplete_items}}.length</action>
+    <check if="{{new_count}} > {{target_sprint}}.capacity">
+      <output>**Capacity Warning:** Adding {{incomplete_items.length}} items would bring {{target_sprint.name}} to {{new_count}}/{{target_sprint.capacity}} capacity (exceeds limit). Proceeding anyway (capacity is advisory).</output>
+    </check>
+
+    <action>For each item in {{incomplete_items}}:
+      1. REMOVE the item from {{active_sprint}}.items in {{data}}
+      2. ADD the item to {{target_sprint}}.items in {{data}}
+      3. PRESERVE the item's current `status` unchanged (no reset)
+    </action>
+    <action>Store {{moved_to_sprint_count}} = length of {{incomplete_items}}</action>
+    <action>Store {{moved_to_sprint_name}} = {{target_sprint}}.name</action>
+    <action>Store {{returned_to_backlog_count}} = 0</action>
+  </check>
+
+  <!-- OPTION B: Return all to backlog -->
+  <check if="user selects 'b'" id="option_b">
+    <action>Calculate {{max_priority}} = max `priority` value among all items currently in {{data}}.backlog (0 if backlog is empty)</action>
+
+    <action>For each item in {{incomplete_items}} (processing in order):
+      1. REMOVE the item from {{active_sprint}}.items in {{data}}
+      2. SET item.status = `ready-for-dev` (schema section 4.5 — status reset on backlog return)
+      3. SET item.priority = {{max_priority}} + 1 (then increment {{max_priority}} for the next item)
+      4. APPEND the item to the END of {{data}}.backlog
+      5. PRESERVE all other fields: `id`, `type`, `epic`, `title`, `severity`
+    </action>
+
+    <action>Re-number ALL {{data}}.backlog items' `priority` fields sequentially 1..N (array position 0 = priority 1) to maintain the denormalized index invariant</action>
+    <action>Store {{returned_to_backlog_count}} = length of {{incomplete_items}}</action>
+    <action>Store {{moved_to_sprint_count}} = 0</action>
+    <action>Store {{moved_to_sprint_name}} = ""</action>
+  </check>
+
+  <!-- OPTION C: Per-item decision -->
+  <check if="user selects 'c'" id="option_c">
+    <action>Initialize {{per_item_sprint_targets}} = {} and {{per_item_backlog}} = []</action>
+    <action>Initialize {{moved_to_sprint_count}} = 0 and {{returned_to_backlog_count}} = 0</action>
+
+    <action>For each item in {{incomplete_items}} (iterate one by one):
+      Display: "**Item:** {{item.id}} — {{item.title}} (status: {{item.status}})"
+    </action>
+    <ask>**[s]** Move to next sprint / **[b]** Return to backlog:</ask>
+
+    <check if="user selects 's'">
+      <action>Scan {{data}}.sprints for sprints with `status: planning`</action>
+      <check if="no planning sprint exists">
+        <output>No planning sprint found. Returning this item to the backlog instead.</output>
+        <action>Add item to {{per_item_backlog}}</action>
+      </check>
+      <check if="planning sprint(s) exist">
+        <check if="multiple planning sprints">
+          <output>Select target sprint:</output>
+          <ask>Planning sprint number:</ask>
+          <action>Store selected sprint as {{item_target_sprint}}</action>
+        </check>
+        <check if="single planning sprint">
+          <action>Store as {{item_target_sprint}}</action>
+        </check>
+        <action>Check capacity warning (same advisory logic as option a)</action>
+        <action>REMOVE item from {{active_sprint}}.items in {{data}}</action>
+        <action>ADD item to {{item_target_sprint}}.items in {{data}} preserving current status</action>
+        <action>Increment {{moved_to_sprint_count}}</action>
+      </check>
+    </check>
+
+    <check if="user selects 'b'">
+      <action>Add item to {{per_item_backlog}}</action>
+    </check>
+
+    <action>After all per-item decisions, process {{per_item_backlog}}:
+      1. Calculate {{max_priority}} = max `priority` value among all items in {{data}}.backlog (0 if empty)
+      2. For each item in {{per_item_backlog}}:
+         - REMOVE item from {{active_sprint}}.items in {{data}}
+         - SET item.status = `ready-for-dev`
+         - SET item.priority = {{max_priority}} + 1 (then increment for next)
+         - APPEND to END of {{data}}.backlog
+      3. Re-number ALL {{data}}.backlog items' `priority` fields sequentially 1..N
+      4. Set {{returned_to_backlog_count}} = length of {{per_item_backlog}}
+    </action>
+    <action>Store {{moved_to_sprint_name}} = name of the planning sprint used (if any items moved to sprint)</action>
+  </check>
+</step>
+
+<step n="6" goal="Validate single-location invariant before write">
+  <action>Build a flat list of all item IDs across {{data}}.backlog and all sprints in {{data}}.sprints</action>
+  <action>Check for any ID that appears more than once across all locations</action>
+  <check if="any duplicate ID found">
+    <output>**Error:** Data integrity violation — item {{duplicate_id}} appears in more than one location. Aborting write to prevent data corruption. Please report this as a bug in the skill.</output>
+    <action>Exit workflow without writing</action>
+  </check>
+</step>
+
+<step n="7" goal="Finalize sprint closure (AC: 5, 8)">
+  <action>Set {{data}}.sprints.{{active_sprint_id}}.status = `closed`</action>
+  <action>Verify {{data}}.sprints.{{active_sprint_id}}.items is now empty (`[]`)</action>
+  <check if="items array is NOT empty">
+    <output>**Warning:** Sprint items array is not empty after disposition. This may indicate a processing error. Proceeding with closure anyway — remaining items are listed below for manual review.</output>
+  </check>
+  <action>Update {{data}}.metadata.last_updated = current ISO-8601 timestamp</action>
+  <action>Preserve {{data}}.metadata.generated unchanged</action>
+  <action>Preserve {{data}}.epics unchanged</action>
+  <action>Preserve all other sprints in {{data}}.sprints unchanged</action>
+
+  <critical>Write the complete updated {{data}} to {{status_file}} as a SINGLE atomic write. This one write includes: item removals from the active sprint, backlog additions, next-sprint additions, sprint status change to closed, and metadata update.</critical>
+</step>
+
+<step n="8" goal="Display summary output">
+  <!-- Handle empty sprint fast path from step 2 -->
+  <check if="{{empty_sprint_fast_path}} == true">
+    <output>
+## Sprint Closed Successfully
+
+**Sprint:** {{active_sprint.name}} ({{active_sprint_id}})
+**Status:** closed
+
+Sprint {{active_sprint.name}} closed. No items to disposition.
+
+**Next Steps:**
+- Use `/add-sprint` to create the next sprint
+- Use `/sprint-status-view` to review the updated status
+    </output>
+    <action>Exit workflow</action>
+  </check>
+
+  <output>
+## Sprint Closed Successfully
+
+**Sprint:** {{active_sprint.name}} ({{active_sprint_id}})
+**Status:** closed
+
+**Disposition:**
+- Done items archived: {{done_count}}
+- Cancelled items archived: {{cancelled_count}}
+{{#if moved_to_sprint_count}}
+- Items moved to {{moved_to_sprint_name}}: {{moved_to_sprint_count}}
+{{/if}}
+{{#if returned_to_backlog_count}}
+- Items returned to backlog: {{returned_to_backlog_count}}
+{{/if}}
+
+{{#if archived_done_files.length}}
+**Files moved to done/:**
+{{#each archived_done_files}}
+- {{id}} → done/
+{{/each}}
+{{/if}}
+
+{{#if archived_cancelled_files.length}}
+**Cancelled files moved to done/:**
+{{#each archived_cancelled_files}}
+- {{id}} → done/
+{{/each}}
+{{/if}}
+
+{{#if skipped_done.length}}
+**Skipped (warnings):**
+{{#each skipped_done}}
+- {{id}} — {{reason}}
+{{/each}}
+{{/if}}
+
+{{#if skipped_cancelled.length}}
+**Skipped (warnings):**
+{{#each skipped_cancelled}}
+- {{id}} — {{reason}}
+{{/each}}
+{{/if}}
+
+**Next Steps:**
+- Use `/add-sprint` to create the next sprint
+- Use `/prioritize-backlog` to reorder the backlog after returns
+- Use `/sprint-status-view` to review the updated status
+  </output>
+</step>
+
+</workflow>

package/skills/close-sprint/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "close-sprint",
+  "version": "1.0.0",
+  "description": "Close an active sprint — archive done/cancelled items, disposition incomplete items (move to next sprint or return to backlog), set sprint status to closed",
+  "category": "workflow",
+  "tags": ["sprint-management", "close-sprint", "archival", "movement-semantics"]
+}

package/skills/generate-backlog/SKILL.md

@@ -0,0 +1,178 @@
+# Generate Backlog
+
+Generate or refresh the `backlog` section of `sprint-status.yaml` from epics and bug story files, while preserving existing sprint assignments and priorities.
+
+## Purpose
+
+This skill reads `epics.md` and `bug-*.md` files and writes the `backlog` and `epics` sections of `sprint-status.yaml`. The `sprints` section is preserved unchanged. This implements the single-source-of-truth model: all unassigned stories and bugs live in the `backlog` section of the unified file rather than a separate `backlog.yaml`.
+
+**Output target:** `_bmad-output/implementation-artifacts/sprint-status.yaml` (`backlog` and `epics` sections only)
+**Never writes:** A standalone `backlog.yaml` file.
+
+---
+
+<workflow>
+
+<step n="1" goal="Load existing sprint-status.yaml state">
+  <action>Check whether `_bmad-output/implementation-artifacts/sprint-status.yaml` exists</action>
+  <check if="file does not exist">
+    <output>ERROR: `sprint-status.yaml` not found. Run `/bmad-sprint-planning` first to bootstrap the file before using `generate-backlog`.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+  <action>Parse the `sprints` section (map keyed by sprint-N). For each sprint, collect all item IDs from the sprint's `items` array. Build {{sprint_item_ids}} = flat set of all item IDs across ALL sprints (across all sprint statuses: planning, active, closed).</action>
+  <action>Parse the `backlog` section (array). Build {{existing_backlog_map}} = map from item ID to the full item object (to preserve priority and status during merge).</action>
+  <action>Preserve the top-level metadata fields: {{generated}}, {{project}}, {{project_key}}, {{tracking_system}}, {{story_location}}</action>
+  <action>Preserve the full {{sprints}} section verbatim (will be passed through unchanged on write)</action>
+  <action>Preserve the existing {{epics}} section for status/retrospective merge later</action>
+</step>
+
+<step n="2" goal="Build done-items exclusion set from done/ archive">
+  <action>Glob `_bmad-output/implementation-artifacts/done/*.md` to discover archived story files</action>
+  <action>For each file found, derive the item ID from the filename (strip `.md` extension, use basename)</action>
+  <action>Build {{done_item_ids}} = set of all archived item IDs</action>
+  <check if="no done/ files found">
+    <action>Set {{done_item_ids}} = empty set</action>
+  </check>
+</step>
+
+<step n="3" goal="Extract stories from epics.md">
+  <action>Read `_bmad-output/planning-artifacts/epics.md`</action>
+  <check if="file does not exist">
+    <output>WARNING: `epics.md` not found at `_bmad-output/planning-artifacts/epics.md`. No stories will be extracted from epics. Continuing with bug-only backlog.</output>
+    <action>Set {{epic_stories}} = [] and {{parsed_epics}} = []</action>
+  </check>
+  <action>Parse epics.md to extract:
+    - Each epic: epic number (N from "Epic N" header), epic title, epic status (if present in the file)
+    - Each story under each epic: story number (M from "Story N.M" format), story title
+  </action>
+  <action>For each story, generate the kebab-case item ID: `{epic_number}-{story_number}-{title-slug}` where title-slug is the title lowercased, spaces replaced with hyphens, non-alphanumeric characters (except hyphens) removed, consecutive hyphens collapsed</action>
+  <action>Exclude stories whose derived ID is in {{sprint_item_ids}} (already assigned to a sprint)</action>
+  <action>Exclude stories whose derived ID is in {{done_item_ids}} (archived)</action>
+  <action>Store remaining stories as {{epic_stories}} — list of objects with: id, epic (integer), title, type="story", severity=null</action>
+  <action>Store parsed epics as {{parsed_epics}} — list of objects with: epic_id (e.g., "epic-5"), epic_number (integer), title</action>
+</step>
+
+<step n="4" goal="Extract bugs from bug-*.md files">
+  <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}} = []</action>
+  </check>
+  <action>For each bug file found:
+    - Parse YAML frontmatter to extract: `id` (or derive from filename: `BUG-{basename-without-bug-prefix-and-extension}`), `title`, `severity` (critical/high/medium/low), `status`
+    - If `id` is not in frontmatter, derive from filename: strip `bug-` prefix and `.md` extension, prefix with `BUG-`
+    - If `status` is not in frontmatter, default to `backlog`
+    - Exclude bugs whose ID is in {{sprint_item_ids}} or {{done_item_ids}}
+    - Create bug item: {id, type="bug", epic=null, title, severity, status}
+  </action>
+  <action>Store as {{bug_stories}}</action>
+</step>
+
+<step n="5" goal="Merge with existing backlog — preserve priorities, detect orphans">
+  <action>Build {{all_source_ids}} = set of all IDs from {{epic_stories}} + {{bug_stories}}</action>
+
+  <action>**Orphan detection:** For each item in {{existing_backlog_map}} whose ID is NOT in {{all_source_ids}} AND NOT in {{sprint_item_ids}} AND NOT in {{done_item_ids}}:
+    - Flag the item as orphaned
+    - Collect orphaned items in {{orphaned_items}} list
+    - Keep the orphaned item in the backlog (do NOT auto-remove — human review required)
+  </action>
+
+  <action>**New item detection:** For each item in {{epic_stories}} and {{bug_stories}} whose ID is NOT in {{existing_backlog_map}}:
+    - Assign status = "backlog"
+    - Mark as new in {{new_items}} list
+  </action>
+
+  <action>**Existing item preservation:** For each item in {{epic_stories}} and {{bug_stories}} whose ID IS in {{existing_backlog_map}}:
+    - Preserve the existing item's `priority` and `status` values from {{existing_backlog_map}}
+    - Update title from the source file (in case it was renamed)
+  </action>
+
+  <action>Assemble {{merged_items}} = all items from {{epic_stories}} (with preserved or new priority/status) + all items from {{bug_stories}} (with preserved or new priority/status) + all items from {{orphaned_items}} (with existing priority/status preserved)</action>
+
+  <action>**Backlog-sprint conflict detection:** Set {{backlog_sprint_conflicts}} = list of items that were in {{existing_backlog_map}} AND in {{sprint_item_ids}} (items found in both the backlog and a sprint — data integrity violation corrected by removing them from the backlog; sprint assignment takes precedence)</action>
+</step>
+
+<step n="6" goal="Sort and renumber backlog items by priority">
+  <action>Sort {{merged_items}} by the following criteria (most important first):
+    1. **Critical bugs first:** Items with type="bug" AND severity="critical" rank highest
+       - Among critical bugs: existing items ordered by their current priority (ascending); new critical bugs ordered by their position in the discovered bug file list (alphabetical by filename)
+    2. **Explicit priority (preserved from existing backlog):** Items that existed in the previous backlog are ranked by their preserved priority value (lower number = higher rank)
+    3. **New items by epic order:** New items (not in existing backlog) are ranked by their epic number (ascending), then by story number within the epic (ascending)
+    4. **Bugs without explicit priority:** New bugs (not in existing backlog) are appended after all stories, sorted by severity (high → medium → low → null)
+    5. **Orphaned items:** Orphaned items are appended last, maintaining their relative order
+  </action>
+  <action>Re-number priorities sequentially: assign priority = 1 to the first item, priority = 2 to the second, etc. (position 0 in array = priority 1)</action>
+  <action>Store as {{sorted_backlog}}</action>
+</step>
+
+<step n="7" goal="Build refreshed epics section">
+  <action>For each epic in {{parsed_epics}}:
+    - Look up the epic in the existing {{epics}} section by key (e.g., "epic-5")
+    - If the epic already exists: preserve its `status` and `retrospective` values. Do NOT downgrade status (e.g., if existing status is "in-progress" and the source implies "backlog", keep "in-progress").
+    - If the epic is new (not in existing epics): set status = "backlog", retrospective = "optional"
+  </action>
+  <action>Build {{refreshed_epics}} = map of all epics from the existing file PLUS any newly discovered epics. Existing epics not present in parsed_epics are preserved unchanged (do not remove epics that are no longer in the source, as they may be in-progress or done).</action>
+</step>
+
+<step n="8" goal="Write sprint-status.yaml atomically">
+  <action>Assemble the complete file content:
+    1. Preserve top-level metadata: `generated`, `project`, `project_key`, `tracking_system`, `story_location` (unchanged)
+    2. Set `last_updated` = current ISO-8601 datetime string (e.g., "2026-04-06T10:00:00Z")
+    3. Write `epics` section from {{refreshed_epics}}
+    4. Write `backlog` section from {{sorted_backlog}} (array, ordered by priority)
+    5. Write `sprints` section from the preserved {{sprints}} section (verbatim, NO changes)
+  </action>
+  <action>Validate before writing:
+    - Every backlog item has all 7 required fields: id, type, epic, title, priority, status, severity
+    - priority values are sequential starting from 1 and match array position
+    - No item ID appears in both backlog and any sprint's items array
+    - Every epic has both status and retrospective fields
+  </action>
+  <action>Write the assembled content to `_bmad-output/implementation-artifacts/sprint-status.yaml` as a single atomic write (read-modify-write pattern)</action>
+</step>
+
+<step n="9" goal="Report summary">
+  <output>
+## Generate Backlog — Complete
+
+**Backlog section refreshed in `sprint-status.yaml`**
+
+| Metric | Count |
+|--------|-------|
+| Total stories from epics.md | {{epic_story_count}} |
+| Total bugs from bug-*.md | {{bug_count}} |
+| New items added to backlog | {{new_items_count}} |
+| Existing items preserved | {{preserved_count}} |
+| Items excluded (sprint-assigned) | {{sprint_excluded_count}} |
+| Items excluded (archived in done/) | {{done_excluded_count}} |
+| Items corrected (removed from backlog — already in sprint) | {{backlog_sprint_conflicts.length}} |
+| Total backlog items | {{total_backlog_count}} |
+
+{{#if backlog_sprint_conflicts}}
+⚠️ **Data integrity corrections:**
+The following items were found in both the backlog and a sprint. They have been removed from the backlog (sprint assignment takes precedence):
+{{#each backlog_sprint_conflicts}}
+- {{id}} — {{title}}
+{{/each}}
+
+{{/if}}
+{{#if orphaned_items}}
+### Orphaned Items (WARNING — Human Review Required)
+
+The following items exist in the backlog but were NOT found in `epics.md` or any `bug-*.md` file. They have been kept in the backlog but should be reviewed:
+
+{{#each orphaned_items}}
+- `{{id}}` — {{title}} (priority: {{priority}}, status: {{status}})
+{{/each}}
+
+These items may represent: renamed stories, deleted epics, or manually added items. Remove them manually if they are no longer needed.
+{{/if}}
+
+**Next steps:**
+- Use `/prioritize-backlog` to reorder items
+- Use `/add-to-sprint` to assign items to a sprint
+- Use `/bmad-sprint-planning` to plan a full sprint
+  </output>
+</step>
+
+</workflow>

package/skills/generate-backlog/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "generate-backlog",
+  "version": "1.0.0",
+  "description": "Generate or refresh the backlog section of sprint-status.yaml from epics and bug stories, preserving existing priorities and sprint assignments",
+  "category": "workflow",
+  "tags": ["backlog", "sprint-management", "epics", "bugs"]
+}