ma-agents 3.4.8 → 3.5.0

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

@@ -1,158 +1,214 @@
 ---
 name: cleanup-done
-description: Archive done stories and bugs — move files to done/ subfolder and remove from sprint/backlog
+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 Workflow
+# Cleanup Done
 
-Archive done stories and bugs — move files to the `done/` subfolder and remove from sprint/backlog tracking.
+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="1" goal="Identify all done items across data sources">
-  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml` — collect all story keys where status is `done`</action>
-  <action>Read `_bmad-output/implementation-artifacts/backlog.yaml` — collect all items where status is `done`</action>
-  <action>Glob `_bmad-output/implementation-artifacts/bug-*.md` — for each bug file, parse YAML frontmatter and collect those with `status: done`</action>
-  <action>Deduplicate across all three sources — build {{done_items}} as a unified list with: id, title, type (story/bug), source_file</action>
-  <check if="no done items found">
-    <output>No items with status `done` found across sprint-status.yaml, backlog.yaml, or bug files. Nothing to archive.</output>
-    <action>Exit workflow</action>
+<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="2" goal="Display done items and confirm archival scope">
+<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>
-## Done Items Ready for Archival
+## Items to Archive
 
-| # | ID | Title | Type | Source |
-|---|---|---|---|---|
-{{#each done_items}}
-| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{source}} |
+| # | ID | Title | Type | Status | Source |
+|---|----|----|------|--------|--------|
+{{#each archivable_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{status}} | {{source}} |
 {{/each}}
 
-*Total: {{done_items.length}} items*
+**Found {{archivable_items.length}} items to archive ({{done_count}} done, {{cancelled_count}} cancelled).**
   </output>
+
   <ask>Options:
-- [a] Archive all
-- [s] Select specific items (enter item numbers)
-- [q] Cancel
+- [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 'q'">
-    <output>Cancelled. No changes made.</output>
-    <action>Exit workflow</action>
-  </check>
-  <check if="user selects 'a'">
-    <action>Set {{items_to_archive}} = all {{done_items}}</action>
+
+  <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>Resolve entered numbers against the table above</action>
-    <action>Set {{items_to_archive}} = selected items</action>
+    <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="Ensure done/ directory exists">
-  <action>Check if `_bmad-output/implementation-artifacts/done/` directory exists</action>
-  <action>If not, create it</action>
+<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="Move files to done/ directory">
-  <action>For each item in {{items_to_archive}}:
-
-    **Stories** (type == story):
-    - Source: `_bmad-output/implementation-artifacts/{id}.md`
-    - Destination: `_bmad-output/implementation-artifacts/done/{id}.md`
-    - Use rename/move operation
-    - Skip if source file does not exist (log warning)
-    - Skip if destination file already exists (log warning — do not overwrite)
-
-    **Bugs** (type == bug):
-    - Source: `_bmad-output/implementation-artifacts/bug-{slug}.md`
-    - Destination: `_bmad-output/implementation-artifacts/done/bug-{slug}.md`
-    - Use rename/move operation
-    - Skip if source file does not exist (log warning)
-    - Skip if destination file already exists (log warning — do not overwrite)
+<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 results: {{moved}}, {{skipped_missing}}, {{skipped_exists}}</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="Remove done IDs from sprint files">
-  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to find all sprint files</action>
-  <action>For each sprint file:
-    - Read the sprint's `items` array
-    - Check if any item IDs in the array match {{items_to_archive}}
-    - If NO matches found: skip this sprint file entirely (no modification needed)
-    - If matches found:
-      - Remove the matching item IDs from the array
-      - If items array becomes empty AND sprint status is `active`: auto-close the sprint by setting status to `closed`
-      - Update `last_modified` to current ISO timestamp
-      - Write the updated sprint file
+<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="Remove done items from backlog.yaml">
-  <action>Read `_bmad-output/implementation-artifacts/backlog.yaml`</action>
-  <action>Remove all entries whose ID is in {{items_to_archive}}</action>
-  <action>Re-number remaining item priorities sequentially: 1, 2, 3, ..., N</action>
-  <action>Write updated `_bmad-output/implementation-artifacts/backlog.yaml`</action>
+<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="Remove done entries from sprint-status.yaml">
-  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
-  <action>In the `development_status` section:
-    - Remove done story keys that are in {{items_to_archive}}
-    - Remove done bug keys that are in {{items_to_archive}}
-    - Do NOT remove epic keys (keys matching `epic-*`)
-    - Do NOT remove retrospective keys (keys ending with `-retrospective`)
-    - If all stories belonging to an epic have been removed: set that epic's status to `done`
-    - Preserve YAML comments where possible
+<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>
-  <action>Write updated `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
 </step>
 
-<step n="8" goal="Report summary">
+<step n="8" goal="Display summary output">
   <output>
-## Archival Complete
+## Cleanup Complete
+
+### Items Archived ({{confirmed_items.length}})
+
+| ID | Title | Type | Status | Source |
+|----|-------|------|--------|--------|
+{{#each confirmed_items}}
+| {{id}} | {{title}} | {{type}} | {{status}} | {{source}} |
+{{/each}}
 
-**Files moved to `done/`:** {{moved_count}}
-{{#each moved_items}}
-- {{id}} ({{type}}) -> done/
+### Files Moved ({{files_moved.length}})
+
+{{#each files_moved}}
+- `{{from}}` → `{{to}}`
 {{/each}}
 
-{{#if skipped_missing.length}}
-**Skipped (source missing):** {{skipped_missing.length}}
-{{#each skipped_missing}}
-- {{id}} — source file not found
+{{#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 skipped_exists.length}}
-**Skipped (already in done/):** {{skipped_exists.length}}
-{{#each skipped_exists}}
-- {{id}} — destination already exists
+{{#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}}
 
-**Sprint updates:**
-{{#each updated_sprints}}
-- {{sprint_id}}: removed {{removed_count}} item(s){{#if auto_closed}} — auto-closed (no remaining items){{/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}}
 
-**Backlog:** {{backlog_removed_count}} items removed, priorities renumbered 1..{{backlog_remaining_count}}
+{{#if empty_active_sprints.length > 0}}
+### Suggestion
 
-**Sprint-status.yaml:** {{status_removed_count}} entries removed
-{{#if epics_marked_done.length}}
-- Epics marked done: {{#each epics_marked_done}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{#each empty_active_sprints}}
+Sprint **{{this}}** has no remaining items. Consider running `/close-sprint` to close it.
+{{/each}}
 {{/if}}
 
-**Next Steps:**
-- Use `/sprint-status-view` to verify updated sprint state
-- Use `/prioritize-backlog` to reorder remaining backlog items
+**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>