ma-agents 3.4.9 → 3.5.0

package/lib/bmad-extension/skills/bmad-sprint-status/workflow.md

@@ -0,0 +1,434 @@
+# Sprint Status Health Workflow
+
+**Goal:** Produce an analysis-focused sprint health summary with risk flags and next-action recommendations by reading the unified `sprint-status.yaml`.
+
+**Your Role:** You are a Scrum Master providing clear, actionable sprint visibility. Focus on health metrics, risk flags, and next steps — not display tables (use `/sprint-status-view` for that).
+
+**READ-ONLY:** This skill NEVER writes to `sprint-status.yaml` or any other file.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
+- `done_folder` = `{implementation_artifacts}/done/`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| Sprint status | `{sprint_status_file}` | FULL_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="0" goal="Determine execution mode">
+  <action>Set mode = {{mode}} if provided by caller; otherwise mode = "interactive"</action>
+
+  <check if="mode == data">
+    <action>Jump to Step 20</action>
+  </check>
+
+  <check if="mode == validate">
+    <action>Jump to Step 30</action>
+  </check>
+
+  <check if="mode == interactive">
+    <action>Continue to Step 1</action>
+  </check>
+</step>
+
+<step n="1" goal="Locate and load sprint-status.yaml">
+  <action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
+  <action>Try to read {sprint_status_file}</action>
+  <check if="file not found">
+    <output>No sprint-status.yaml found. Run `/bmad-sprint-planning` to initialize.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Parse YAML — extract metadata fields: generated, last_updated, project, project_key, tracking_system, story_location</action>
+  <action>Parse three data sections: epics (map), backlog (array), sprints (map)</action>
+  <action>Continue to Step 2</action>
+</step>
+
+<step n="2" goal="Analyze active sprint health">
+  <action>Scan sprints map for the sprint entry with status: active</action>
+  <check if="no active sprint found">
+    <action>Set active_sprint = null</action>
+    <action>Continue to Step 2b (backlog health)</action>
+  </check>
+  <check if="active sprint found">
+    <action>Store as active_sprint with all its fields (name, capacity, start, end, items)</action>
+    <action>Compute items_by_status: count items in active_sprint.items grouped by status field (in-progress, review, ready-for-dev, backlog, on-hold, cancelled, done)</action>
+    <action>capacity_used = length of active_sprint.items array</action>
+    <action>capacity_total = active_sprint.capacity</action>
+    <action>capacity_pct = if capacity_total > 0 then round((capacity_used / capacity_total) * 100) else 0 (treat capacity=0 as "no limit set")</action>
+    <action>If active_sprint.start is populated: compute sprint_age_days = number of days between active_sprint.start date and today</action>
+    <action>For each item in active_sprint.items with status: in-progress: compute item_age_days = sprint_age_days (proxy — item assumed in-progress since sprint start)</action>
+  </check>
+</step>
+
+<step n="2b" goal="Analyze backlog health">
+  <action>backlog_total = length of backlog array</action>
+  <action>backlog_bugs = count of backlog items where type == "bug"</action>
+  <action>backlog_stories = backlog_total - backlog_bugs</action>
+  <action>backlog_critical_bugs = count of backlog bugs where severity == "critical" or severity == "high"</action>
+  <action>Continue to Step 2c</action>
+</step>
+
+<step n="2c" goal="Compute epic progress">
+  <action>For each epic key in the epics map:
+    - epic_number = numeric portion of key (e.g., key "epic-17" → epic_number = 17)
+    - active_count = count of items across backlog array AND all sprints[*].items arrays where item.epic == epic_number
+    - done_count = count of files in {done_folder} whose filename starts with "{epic_number}-" (e.g., "17-*.md")
+    - total_count = done_count + active_count
+    - Store as: {epic_key, status, retrospective, done_count, active_count, total_count}
+  </action>
+  <action>Continue to Step 2d</action>
+</step>
+
+<step n="2d" goal="Compute sprint history">
+  <action>closed_sprints = all sprint entries where status == "closed"</action>
+  <action>closed_count = length of closed_sprints</action>
+  <action>For each closed sprint: capture name, item count (length of items array), start, end dates</action>
+  <action>Continue to Step 3</action>
+</step>
+
+<step n="3" goal="Detect risk flags">
+  <action>Initialize risks = [] (empty list)</action>
+
+  <!-- Risk: No active sprint -->
+  <check if="active_sprint == null">
+    <action>Append to risks: "No active sprint — consider running `/add-sprint` to create one or activating a planning sprint"</action>
+  </check>
+
+  <!-- Risk: Stale items (in-progress for more than 14 days based on sprint start) -->
+  <check if="active_sprint is not null AND sprint_age_days > 14">
+    <action>For each item in active_sprint.items where status == "in-progress":
+      Append to risks: "Item {{item.id}} has been in-progress for {{sprint_age_days}} days (sprint started {{active_sprint.start}})"
+    </action>
+  </check>
+
+  <!-- Risk: Items not started -->
+  <check if="active_sprint is not null">
+    <action>not_started_count = count of items in active_sprint.items where status == "ready-for-dev" or status == "backlog"</action>
+    <check if="not_started_count > 0">
+      <action>Append to risks: "{{not_started_count}} of {{capacity_used}} items still in ready-for-dev status — not yet started"</action>
+    </check>
+  </check>
+
+  <!-- Risk: Over-capacity -->
+  <check if="active_sprint is not null AND capacity_total > 0 AND capacity_used > capacity_total">
+    <action>overage = capacity_used - capacity_total</action>
+    <action>Append to risks: "Sprint over capacity: {{capacity_used}}/{{capacity_total}} items ({{overage}} over limit)"</action>
+  </check>
+
+  <!-- Risk: At capacity with unstarted items -->
+  <check if="active_sprint is not null AND capacity_total > 0 AND capacity_used >= capacity_total AND not_started_count > 0">
+    <action>Append to risks: "Sprint at {{capacity_pct}}% capacity ({{capacity_used}}/{{capacity_total}}) with {{not_started_count}} items still in ready-for-dev"</action>
+  </check>
+
+  <!-- Risk: No progress toward completion -->
+  <check if="active_sprint is not null AND sprint_age_days >= 3">
+    <action>review_or_done_count = count of items in active_sprint.items where status == "review" or status == "done"</action>
+    <check if="review_or_done_count == 0">
+      <action>Append to risks: "No items in review or done — sprint may be at risk (sprint is {{sprint_age_days}} days old)"</action>
+    </check>
+  </check>
+
+  <!-- Risk: On-hold or cancelled items in active sprint -->
+  <check if="active_sprint is not null">
+    <action>For each item in active_sprint.items where status == "on-hold" or status == "cancelled":
+      Append to risks: "1 item {{item.status}}: {{item.id}}"
+    </action>
+  </check>
+
+  <!-- Risk: Stale sprint-status.yaml file -->
+  <action>staleness_date = last_updated if present, else generated</action>
+  <action>file_age_days = number of days between staleness_date and today</action>
+  <check if="file_age_days > 7">
+    <action>Append to risks: "`last_updated` is {{file_age_days}} days old — sprint-status.yaml may be stale"</action>
+  </check>
+
+  <!-- Risk: Orphaned stories (item references epic not in epics section) -->
+  <action>For each item in backlog array AND each item in all sprints[*].items arrays:
+    If item.epic is not null AND "epic-{{item.epic}}" key does not exist in epics map:
+      Append to risks: "Orphaned story detected: item {{item.id}} references epic-{{item.epic}} which is not in the epics section"
+  </action>
+
+  <!-- Risk: In-progress epic with no stories -->
+  <action>For each epic in epics map where epic.status == "in-progress":
+    active_count from Step 2c for this epic
+    If active_count == 0 AND done_count (from Step 2c) == 0:
+      Append to risks: "In-progress epic {{epic_key}} has no associated stories"
+  </action>
+
+  <!-- Risk: Critical bugs in backlog -->
+  <action>For each item in backlog array where type == "bug" AND (severity == "critical" or severity == "high"):
+    Append to risks: "Critical/high severity bug in backlog: {{item.id}} ({{item.severity}})"
+  </action>
+
+  <action>Continue to Step 4</action>
+</step>
+
+<step n="4" goal="Select next action recommendation">
+  <note>When selecting "first" item: prefer active sprint items over backlog items; within each group, sort by epic number then story number</note>
+  <action>Scan for next recommended workflow using priority order:</action>
+  1. If any item in active_sprint.items has status == "in-progress" → set next_workflow_id = "dev-story", next_story_id = first such item's id
+  2. Else if any item in active_sprint.items has status == "review" → set next_workflow_id = "code-review", next_story_id = first such item's id
+  3. Else if any item in active_sprint.items OR backlog has status == "ready-for-dev" → set next_workflow_id = "dev-story", next_story_id = first such item's id
+  4. Else if any item in backlog has status == "backlog" → set next_workflow_id = "create-story", next_story_id = first such item's id
+  5. Else if any epic has retrospective == "optional" AND status == "done" → set next_workflow_id = "retrospective", next_story_id = that epic's key
+  6. Else → set next_workflow_id = null, next_story_id = null (all work complete)
+  <action>Store next_workflow_id, next_story_id</action>
+  <action>Continue to Step 5</action>
+</step>
+
+<step n="5" goal="Display interactive health summary">
+  <output>
+## Sprint Health Summary
+
+- Project: {{project}} ({{project_key}})
+- Tracking: {{tracking_system}}
+- Last updated: {{last_updated}}
+
+{{#if active_sprint}}
+### Active Sprint: {{active_sprint.name}}
+**Capacity:** {{capacity_used}} / {{capacity_total}} ({{capacity_pct}}%)
+**Dates:** {{active_sprint.start}} to {{active_sprint.end}}
+**Items by status:** in-progress {{items_by_status.in-progress}}, review {{items_by_status.review}}, ready-for-dev {{items_by_status.ready-for-dev}}, backlog {{items_by_status.backlog}}, on-hold {{items_by_status.on-hold}}
+{{else}}
+### Active Sprint
+No active sprint found.
+{{/if}}
+
+### Risk Flags
+{{#if risks}}
+{{#each risks}}
+- {{this}}
+{{/each}}
+{{else}}
+No risks detected.
+{{/if}}
+
+### Backlog Health
+- Total unassigned: {{backlog_total}} ({{backlog_stories}} stories, {{backlog_bugs}} bugs)
+- Critical/high bugs in backlog: {{backlog_critical_bugs}}
+
+### Epic Progress
+{{#each epic_progress}}
+- {{epic_key}} ({{status}}): {{done_count}}/{{total_count}} done
+{{/each}}
+
+### Sprint History
+- {{closed_count}} closed sprint(s)
+{{#each closed_sprints}}
+- {{name}}: {{item_count}} items, {{start}} to {{end}}
+{{/each}}
+
+### Next Recommendation
+{{#if next_workflow_id}}
+/{{next_workflow_id}} ({{next_story_id}})
+{{else}}
+All work complete — great job!
+{{/if}}
+  </output>
+</step>
+
+<step n="6" goal="Offer interactive actions">
+  <ask>Pick an option:
+1) Run recommended workflow now
+2) Show all items grouped by status (active sprint + backlog)
+3) Show detailed sprint view (runs `/sprint-status-view`)
+4) Show raw sprint-status.yaml
+5) Exit
+Choice:</ask>
+
+  <check if="choice == 1">
+    <check if="next_workflow_id is null">
+      <output>No workflow to run — all work is complete.</output>
+    </check>
+    <check if="next_workflow_id is not null">
+      <output>Run `/{{next_workflow_id}}`.
+If the command targets a story, set `story_key={{next_story_id}}` when prompted.</output>
+    </check>
+  </check>
+
+  <check if="choice == 2">
+    <output>
+### Items by Status
+
+**In Progress:**
+{{#each active_sprint.items where status == "in-progress"}}
+- {{id}}: {{title}}
+{{/each}}
+
+**Review:**
+{{#each active_sprint.items where status == "review"}}
+- {{id}}: {{title}}
+{{/each}}
+
+**Ready for Dev (sprint):**
+{{#each active_sprint.items where status == "ready-for-dev"}}
+- {{id}}: {{title}}
+{{/each}}
+
+**Ready for Dev (backlog):**
+{{#each backlog where status == "ready-for-dev"}}
+- {{id}}: {{title}}
+{{/each}}
+
+**Backlog (unassigned):**
+{{#each backlog where status == "backlog"}}
+- {{id}}: {{title}}
+{{/each}}
+    </output>
+  </check>
+
+  <check if="choice == 3">
+    <output>For a full formatted table view with all items, run `/sprint-status-view`.</output>
+  </check>
+
+  <check if="choice == 4">
+    <action>Display the full contents of {sprint_status_file}</action>
+  </check>
+
+  <check if="choice == 5">
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<!-- ========================= -->
+<!-- Data mode for other flows -->
+<!-- ========================= -->
+
+<step n="20" goal="Data mode output">
+  <action>Load and parse {sprint_status_file} same as Steps 1–2d</action>
+  <action>Detect risks same as Step 3</action>
+  <action>Compute recommendation same as Step 4</action>
+  <template-output>active_sprint_id = {{active_sprint_id}}</template-output>
+  <template-output>active_sprint_name = {{active_sprint_name}}</template-output>
+  <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
+  <template-output>next_story_id = {{next_story_id}}</template-output>
+  <template-output>count_backlog = {{count_backlog}}</template-output>
+  <template-output>count_ready = {{count_ready}}</template-output>
+  <template-output>count_in_progress = {{count_in_progress}}</template-output>
+  <template-output>count_review = {{count_review}}</template-output>
+  <template-output>count_done = {{count_done}}</template-output>
+  <template-output>count_on_hold = {{count_on_hold}}</template-output>
+  <template-output>capacity_used = {{capacity_used}}</template-output>
+  <template-output>capacity_total = {{capacity_total}}</template-output>
+  <template-output>capacity_pct = {{capacity_pct}}</template-output>
+  <template-output>backlog_total = {{backlog_total}}</template-output>
+  <template-output>backlog_bugs = {{backlog_bugs}}</template-output>
+  <template-output>backlog_critical_bugs = {{backlog_critical_bugs}}</template-output>
+  <template-output>epic_summary = {{epic_summary}}</template-output>
+  <template-output>risks = {{risks}}</template-output>
+  <action>Return to caller</action>
+</step>
+
+<!-- Notes on count_* field semantics in data mode:
+  count_backlog   = items with status "backlog" across active sprint items + backlog array
+  count_ready     = items with status "ready-for-dev" across active sprint items + backlog array
+  count_in_progress = items with status "in-progress" in active sprint
+  count_review    = items with status "review" in active sprint
+  count_done      = items with status "done" in active sprint (not counting done/ folder archived items)
+  count_on_hold   = items with status "on-hold" or "cancelled" in active sprint
+  Backward compatibility: count_backlog, count_ready, count_in_progress, count_review, count_done,
+    next_workflow_id, next_story_id, and risks keys are preserved from the original built-in data mode output.
+-->
+
+<!-- ========================= -->
+<!-- Validate mode -->
+<!-- ========================= -->
+
+<step n="30" goal="Validate sprint-status.yaml against unified schema">
+  <action>Check that {sprint_status_file} exists</action>
+  <check if="missing">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "sprint-status.yaml missing"</template-output>
+    <template-output>suggestion = "Run /bmad-sprint-planning to create it"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Read and parse {sprint_status_file}</action>
+
+  <action>Validate required metadata fields exist: generated, last_updated, project, project_key, tracking_system, story_location</action>
+  <check if="any required field missing">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Missing required metadata field(s): {{missing_fields}}"</template-output>
+    <template-output>suggestion = "Re-run /bmad-sprint-planning or add missing fields manually"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Verify three data sections exist: epics (map or empty map {}), backlog (array or empty array []), sprints (map or empty map {})</action>
+  <check if="any data section missing">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Missing data section(s): {{missing_sections}}. Expected: epics, backlog, sprints"</template-output>
+    <template-output>suggestion = "Re-run /bmad-sprint-planning or repair the file manually to add missing sections"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Validate all epic status values: must be one of backlog, in-progress, done, on-hold, cancelled</action>
+  <check if="invalid epic status found">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Invalid epic status value(s): {{invalid_epic_entries}}"</template-output>
+    <template-output>suggestion = "Valid epic statuses: backlog, in-progress, done, on-hold, cancelled"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Validate all item status values (across backlog array and all sprints[*].items arrays): must be one of backlog, ready-for-dev, in-progress, review, done, on-hold, cancelled</action>
+  <check if="invalid item status found">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Invalid item status value(s): {{invalid_item_entries}}"</template-output>
+    <template-output>suggestion = "Valid item statuses: backlog, ready-for-dev, in-progress, review, done, on-hold, cancelled"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Validate all sprint status values: must be one of planning, active, closed</action>
+  <check if="invalid sprint status found">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Invalid sprint status value(s): {{invalid_sprint_entries}}"</template-output>
+    <template-output>suggestion = "Valid sprint statuses: planning, active, closed"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Check single-active-sprint constraint: count sprints with status == "active"</action>
+  <check if="active_sprint_count > 1">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Multiple active sprints detected ({{active_sprint_count}}). At most one sprint may have status: active."</template-output>
+    <template-output>suggestion = "Close or set other active sprints to planning status"</template-output>
+    <action>Return</action>
+  </check>
+
+  <action>Spot check single-location invariant: sample up to 5 item IDs from across all locations and verify each ID appears in exactly one location (either backlog array OR one sprint's items array, never both)</action>
+  <check if="any item found in multiple locations">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "Single-location invariant violated: item(s) {{duplicate_ids}} appear in multiple locations"</template-output>
+    <template-output>suggestion = "Remove duplicate item entries — each item ID must appear in exactly one location"</template-output>
+    <action>Return</action>
+  </check>
+
+  <template-output>is_valid = true</template-output>
+  <template-output>message = "sprint-status.yaml valid: unified schema structure verified"</template-output>
+</step>
+
+</workflow>

package/lib/bmad-extension/skills/cleanup-done/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: cleanup-done
+description: Archive done and cancelled items — remove from sprint-status.yaml and move story/bug files to done/ subfolder
+type: skill
+triggers:
+  - "cleanup done"
+  - "archive done items"
+  - "clean up done"
+---
+
+# Cleanup Done
+
+Archive done and cancelled items from `sprint-status.yaml` — remove them from the active file and move their story/bug `.md` files to the `done/` subfolder.
+
+## Purpose
+
+Keeps the active sprint view lean by archiving completed and cancelled work. Preserves story artifacts in `done/` for historical reference. Updates epic statuses when all stories for an epic have been archived.
+
+**BMAD context:** Path resolution uses `story_location` from `sprint-status.yaml` metadata (or `_bmad-output/implementation-artifacts` as the default). The Scrum Master agent (`bmm-sm`) is the primary invoker of this skill.
+
+---
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Set default `story_location` = `_bmad-output/implementation-artifacts`. Check whether `{story_location}/sprint-status.yaml` exists at the default path.</action>
+  <check if="file does not exist">
+    <output>Error: No sprint-status.yaml found at `{story_location}/sprint-status.yaml`. Run `/bmad-sprint-planning` first to initialize the file.</output>
+    <action>Exit — no changes made.</action>
+  </check>
+  <action>Read `{story_location}/sprint-status.yaml` and parse all sections: metadata, `epics`, `backlog`, `sprints`.</action>
+  <action>If the parsed metadata contains a `story_location` field, update `story_location` to that value (allows the skill to resolve file paths correctly for non-default locations).</action>
+  <action>Store parsed data as {{sprint_data}} with sub-objects: {{sprint_data.metadata}}, {{sprint_data.epics}}, {{sprint_data.backlog}}, {{sprint_data.sprints}}.</action>
+</step>
+
+<step n="1" goal="Scan all sections for archivable items">
+  <action>Initialize {{archivable_items}} = [] (empty list).</action>
+
+  <action>Scan the `backlog` array: for each item where `status` is `done` or `cancelled`, add to {{archivable_items}} with source = "backlog".</action>
+
+  <action>Scan ALL sprints in the `sprints` map — including sprints with `status: closed` (schema section 6.7 explicitly permits cleanup-done to archive items from closed sprints):
+    For each sprint key (e.g., `sprint-1`, `sprint-2`):
+      For each item in sprint's `items` array:
+        If item's `status` is `done` or `cancelled`:
+          Add to {{archivable_items}} with source = "{sprint_key} ({sprint_name})"
+  </action>
+
+  <check if="archivable_items is empty">
+    <output>No done or cancelled items found. Nothing to clean up.</output>
+    <action>Exit — no changes made.</action>
+  </check>
+</step>
+
+<step n="2" goal="Display archivable items and confirm">
+  <action>Count done vs cancelled: {{done_count}} = items where status = "done", {{cancelled_count}} = items where status = "cancelled".</action>
+  <output>
+## Items to Archive
+
+| # | ID | Title | Type | Status | Source |
+|---|----|----|------|--------|--------|
+{{#each archivable_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status}} | {{source}} |
+{{/each}}
+
+**Found {{archivable_items.length}} items to archive ({{done_count}} done, {{cancelled_count}} cancelled).**
+  </output>
+
+  <ask>Options:
+- [c] Confirm and archive all listed items
+- [s] Select specific items (enter numbers, e.g. 1,3,5)
+- [x] Cancel without changes
+
+Choice:</ask>
+
+  <check if="user selects 'x'">
+    <output>Cancelled — no changes made.</output>
+    <action>Exit.</action>
+  </check>
+
+  <check if="user selects 's'">
+    <ask>Enter item numbers to archive (comma-separated):</ask>
+    <action>Filter {{archivable_items}} to only the items matching the user's selection. Store as {{confirmed_items}}.</action>
+  </check>
+
+  <check if="user selects 'c'">
+    <action>Set {{confirmed_items}} = {{archivable_items}} (all items).</action>
+  </check>
+</step>
+
+<step n="3" goal="Archive story/bug files">
+  <action>Ensure `{story_location}/done/` directory exists. Create it if it does not exist.</action>
+  <action>Initialize {{files_moved}} = [], {{files_skipped_missing}} = [], {{files_skipped_exists}} = [].</action>
+
+  <action>For each item in {{confirmed_items}}:
+    1. Resolve source path: `{story_location}/{item.id}.md`
+       - For bug items, also try `{story_location}/bug-{slug}.md` and `{story_location}/BUG-{slug}.md` as fallbacks if the primary path does not exist (where {slug} is derived from the id by removing any leading BUG- or bug- prefix, lowercased).
+    2. Resolve destination path: `{story_location}/done/{item.id}.md`
+
+    3. If no source file exists at any resolved path:
+       - Log warning: "File not found: {resolved_path} — skipping file move."
+       - Add to {{files_skipped_missing}}.
+       - Continue to next item (YAML removal proceeds regardless).
+
+    4. If destination file already exists:
+       - Log warning: "File already exists at destination: {destination_path} — skipping file move."
+       - Add to {{files_skipped_exists}}.
+       - Continue to next item (YAML removal proceeds regardless).
+
+    5. Move (rename) the source file to the destination path.
+       Use a move/rename operation (not copy+delete) to preserve git history.
+       Add {from: source_path, to: destination_path} to {{files_moved}}.
+  </action>
+</step>
+
+<step n="4" goal="Remove archived items from sprint-status.yaml">
+  <action>For each item in {{confirmed_items}}:
+    - If item's source is "backlog": remove the item object from {{sprint_data.backlog}} array.
+    - If item's source is a sprint (e.g., "sprint-1 (Sprint Name)"): extract the sprint key from the source string (the part before the space and parenthesis, e.g., "sprint-1"), then remove the item object from that sprint's `items` array in {{sprint_data.sprints}}.
+  </action>
+
+  <action>Track whether any backlog items were removed. If yes: renumber remaining backlog items' `priority` values sequentially starting at 1 to match their new array positions (priority[0] = 1, priority[1] = 2, ..., priority[N-1] = N). Store the count of remaining backlog items as {{backlog_items_renumbered}} (0 if no backlog items were removed). This keeps the `priority` field in sync with array position per schema section 3.3.</action>
+</step>
+
+<step n="5" goal="Update epic statuses">
+  <action>For each epic in {{sprint_data.epics}} where epic's current `status` is `in-progress`:
+    1. Determine the epic number N from the key (e.g., `epic-5` → N = 5).
+    2. Check if ANY items with `epic: N` remain in:
+       a. {{sprint_data.backlog}} (after removal in Step 4)
+       b. Any sprint's `items` array in {{sprint_data.sprints}} (after removal in Step 4)
+    3. Also verify that at least one item for this epic was archived now or previously exists in `{story_location}/done/` (to guard against marking an epic done that never had stories — epics with zero items anywhere should NOT be auto-marked done unless there are archived stories for them).
+    4. If no remaining items for this epic exist in backlog or any sprint, AND at least one archived item exists for this epic: update the epic's `status` to `done`.
+    5. Record which epics were transitioned to `done` in {{epics_marked_done}}.
+  </action>
+</step>
+
+<step n="6" goal="Detect empty active sprints">
+  <action>After item removal (Step 4), check each sprint that had items removed from its `items` array:
+    - If the sprint's `items` array is now empty AND the sprint's `status` is `active`:
+      - Add to {{empty_active_sprints}} list with sprint name.
+  </action>
+</step>
+
+<step n="7" goal="Atomic write to sprint-status.yaml">
+  <action>Update {{sprint_data.metadata.last_updated}} to the current ISO-8601 date (YYYY-MM-DD). Preserve {{sprint_data.metadata.generated}} unchanged.</action>
+  <action>Write the complete updated `sprint-status.yaml` in a single write operation, incorporating:
+    - All item removals from sprint `items` arrays (Step 4)
+    - All item removals from `backlog` array (Step 4)
+    - Backlog priority renumbering (Step 4)
+    - Epic status updates (Step 5)
+    - Updated `last_updated` metadata (this step)
+    - All sections NOT modified pass through unchanged.
+  </action>
+</step>
+
+<step n="8" goal="Display summary output">
+  <output>
+## Cleanup Complete
+
+### Items Archived ({{confirmed_items.length}})
+
+| ID | Title | Type | Status | Source |
+|----|-------|------|--------|--------|
+{{#each confirmed_items}}
+| {{id}} | {{title}} | {{type}} | {{status}} | {{source}} |
+{{/each}}
+
+### Files Moved ({{files_moved.length}})
+
+{{#each files_moved}}
+- `{{from}}` → `{{to}}`
+{{/each}}
+
+{{#if files_skipped_missing.length > 0}}
+### Warnings — Files Not Found (skipped, YAML still cleaned up)
+
+{{#each files_skipped_missing}}
+- File not found: `{{this}}` — skipping file move.
+{{/each}}
+{{/if}}
+
+{{#if files_skipped_exists.length > 0}}
+### Warnings — Destination Already Exists (skipped, YAML still cleaned up)
+
+{{#each files_skipped_exists}}
+- File already exists at destination: `{{this}}` — skipping file move.
+{{/each}}
+{{/if}}
+
+{{#if backlog_items_renumbered > 0}}
+### Backlog Renumbered
+
+{{backlog_items_renumbered}} remaining backlog items renumbered (priorities 1..{{backlog_items_renumbered}}).
+{{/if}}
+
+{{#if epics_marked_done.length > 0}}
+### Epics Marked Done
+
+{{#each epics_marked_done}}
+- **{{this}}** — all stories archived; epic status updated to `done`.
+{{/each}}
+{{/if}}
+
+{{#if empty_active_sprints.length > 0}}
+### Suggestion
+
+{{#each empty_active_sprints}}
+Sprint **{{this}}** has no remaining items. Consider running `/close-sprint` to close it.
+{{/each}}
+{{/if}}
+
+**Next steps:** `/sprint-status-view` to review the updated sprint | `/close-sprint` if a sprint is empty | `/generate-backlog` to refresh the backlog
+  </output>
+</step>
+
+</workflow>