ma-agents 3.4.8 → 3.5.0

package/_bmad-output/implementation-artifacts/17-24-rework-prioritize-backlog.md

@@ -0,0 +1,344 @@
+# Story 17.24: Rework prioritize-backlog Skill (Light Rework -- Create from Scratch)
+
+Status: review
+
+## Story
+
+As a **Scrum Master**,
+I want the `prioritize-backlog` skill to reorder items in the `backlog` section of the unified `sprint-status.yaml` using multiple prioritization criteria (severity, business value, dependencies, type, age),
+So that backlog reprioritization works against the single source of truth, is available across all IDE agents and BMAD workflows, and supports interactive, automated, and suggestion-only modes.
+
+## Acceptance Criteria
+
+1. **Given** the `prioritize-backlog` skill is invoked from ANY IDE agent (Claude Code, Cursor, Cline, Roo Code, Gemini, Copilot, Kilocode, etc.) OR from a BMAD workflow,
+   **When** the unified `sprint-status.yaml` exists,
+   **Then** it reads items from the `backlog` section only (items assigned to a sprint are NOT shown and NOT reprioritized),
+   **And** the display shows items in current priority order with columns: Priority, ID, Title, Type, Epic, Severity, Status.
+
+2. **Given** the `backlog` section contains items,
+   **When** the Scrum Master selects **Full** mode (interactive reprioritization),
+   **Then** the skill presents the current backlog order alongside a suggested new order based on multi-criteria analysis,
+   **And** the Scrum Master can accept, modify, or reject the suggested order,
+   **And** upon acceptance the skill renumbers `priority` values 1..N to match the new array positions,
+   **And** writes the reordered `backlog` section back to `sprint-status.yaml` in a single atomic write,
+   **And** updates the `last_updated` metadata timestamp,
+   **And** all other sections (`epics`, `sprints`) are preserved unchanged.
+
+3. **Given** the `backlog` section contains items,
+   **When** the Scrum Master selects **Quick** mode (automated reprioritization),
+   **Then** the skill applies the default prioritization rules automatically without interactive approval,
+   **And** renumbers `priority` values 1..N,
+   **And** writes the reordered backlog in a single atomic write,
+   **And** displays a summary of what changed (items that moved up, down, or stayed in place).
+
+4. **Given** the `backlog` section contains items,
+   **When** the Scrum Master selects **Auto-suggest** mode,
+   **Then** the skill generates a suggested new ordering with per-item rationale,
+   **And** displays the suggestions without modifying `sprint-status.yaml`,
+   **And** no file write occurs.
+
+5. **Given** the prioritization criteria are applied,
+   **When** the skill scores and ranks backlog items,
+   **Then** the following criteria are evaluated in weighted order (FR67):
+   - **Severity** -- critical and high bugs float to the top
+   - **Business value** -- high-value items rank higher
+   - **Dependencies** -- items blocking other items receive a priority boost
+   - **Type weighting** -- bugs receive a slight priority boost over stories (at equal value)
+   - **Age** -- older items (lower epic number or earlier creation) receive a slight boost to prevent starvation
+
+6. **Given** `sprint-status.yaml` does not exist,
+   **When** the skill is invoked,
+   **Then** it reports: "No sprint-status.yaml found. Run sprint planning first to initialize the file.",
+   **And** exits without creating any file.
+
+7. **Given** the `backlog` section is empty (all items assigned to sprints or no items exist),
+   **When** the skill is invoked,
+   **Then** it reports: "Backlog is empty. Nothing to prioritize.",
+   **And** exits without modifying the file.
+
+8. **Given** the old `backlog.yaml` file exists alongside `sprint-status.yaml`,
+   **When** the skill is invoked,
+   **Then** it operates on `sprint-status.yaml` only (the old file is ignored; see Story 17.23 for migration),
+   **And** logs a note: "Legacy backlog.yaml detected. Run migration to consolidate."
+
+9. **Given** the skill source files exist in BOTH deployment pipelines (IDE skill at `skills/prioritize-backlog/` and BMAD extension at `lib/bmad-extension/skills/prioritize-backlog/`),
+   **When** the ma-agents installer is run,
+   **Then** the IDE skill is deployed to all agent directories via `lib/installer.js` (`performInstall`),
+   **And** the BMAD extension skill is deployed via `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`,
+   **And** the installed copies are byte-identical to their source (minus frontmatter injection by the installer for the IDE path).
+
+10. **Given** the skill is invoked from ANY IDE agent OR from a BMAD workflow,
+    **When** it executes,
+    **Then** it works identically in both invocation modes (NFR19).
+
+## Tasks / Subtasks
+
+### Task 1: Create the IDE skill source files (AC: 9, 10) -- NEW
+
+The IDE skill does NOT exist. The previous (rolled-back) Phase 1 implementation only modified an installed copy at `.claude/skills/prioritize-backlog/SKILL.md`, which was wiped on rollback. This task creates the skill from scratch in the correct source location.
+
+- [x] 1.1 Create `skills/prioritize-backlog/skill.json` with metadata:
+  ```json
+  {
+    "name": "prioritize-backlog",
+    "version": "1.0.0",
+    "description": "Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age",
+    "category": "workflow",
+    "tags": ["backlog", "prioritization", "sprint-management"]
+  }
+  ```
+  Note: `always_load` is intentionally omitted (defaults to false) -- this skill is invoked on demand, not loaded for every task.
+
+- [x] 1.2 Create `skills/prioritize-backlog/SKILL.md` with the complete skill workflow (see Task 3 for content specification). This is the canonical skill content that the installer deploys to all IDE agents.
+
+### Task 2: Create the BMAD extension skill source files (AC: 9, 10) -- NEW
+
+The BMAD extension skill does NOT exist. The previous Phase 1 implementation never created files in this pipeline. This task creates the skill from scratch.
+
+- [x] 2.1 Create `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` -- this is a SEPARATE file from the IDE skill SKILL.md. The BMAD extension version is authored for the BMAD Scrum Master agent (`bmm-sm`) context and may have BMAD-specific phrasing (e.g., referencing `_bmad/bmm/config.yaml` for path resolution). The core workflow logic MUST be functionally identical to the IDE version.
+
+- [x] 2.2 Create `lib/bmad-extension/skills/prioritize-backlog/bmad-skill-manifest.yaml`:
+  ```yaml
+  type: skill
+  name: prioritize-backlog
+  module: ma-skills
+  ```
+
+- [x] 2.3 Register the skill in `lib/bmad-extension/module-help.csv` by adding a row:
+  ```csv
+  ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age.",_bmad-output/implementation-artifacts,"backlog",
+  ```
+  The `agent` column is `bmm-sm` (Scrum Master) because backlog prioritization is a Scrum Master responsibility.
+
+### Task 3: Implement the skill workflow content (AC: 1, 2, 3, 4, 5, 6, 7, 8)
+
+The SKILL.md content (for both the IDE and BMAD extension versions) must implement the following workflow. Both versions MUST be functionally identical in their workflow logic.
+
+- [x] 3.1 **Step 0 -- Load configuration and validate file existence:**
+  - Read `sprint-status.yaml` at `_bmad-output/implementation-artifacts/sprint-status.yaml` (or resolve path from config).
+  - If the file does not exist, report error: "No sprint-status.yaml found. Run sprint planning first to initialize the file." Exit (AC 6).
+  - Parse the full file: `epics`, `backlog`, and `sprints` sections.
+  - If a legacy `backlog.yaml` file exists in the same directory, log a note: "Legacy backlog.yaml detected. Run migration to consolidate." Do NOT read or operate on the legacy file (AC 8).
+  - If the `backlog` array is empty, report: "Backlog is empty. Nothing to prioritize." Exit (AC 7).
+
+- [x] 3.2 **Step 1 -- Display current backlog order:**
+  - Read the `backlog` array from the parsed `sprint-status.yaml`.
+  - Display items in current priority order in a table with columns: Priority (#), ID, Title, Type, Epic, Severity, Status.
+  - Show total count of backlog items.
+  - Do NOT display items from any sprint's `items` array -- only `backlog` section items are shown (AC 1).
+
+- [x] 3.3 **Step 2 -- Choose prioritization mode:**
+  - Prompt the Scrum Master to select a mode:
+    - **[f] Full** -- interactive: generates a suggested order, presents current vs proposed side-by-side, user approves or adjusts before write.
+    - **[q] Quick** -- automated: applies default rules and reorders immediately, then shows summary of changes.
+    - **[a] Auto-suggest** -- read-only: generates suggestions with per-item rationale, no file modification.
+  - Store selected mode for the workflow branch.
+
+- [x] 3.4 **Step 3 -- Multi-criteria prioritization analysis (all modes):**
+  - For each item in the `backlog` array, compute a composite priority score using weighted criteria (AC 5, FR67):
+    1. **Severity weight (highest impact):** Items with `severity: critical` get the highest score boost. `high` > `medium` > `low`. Items with `severity: null` (stories) get no severity adjustment.
+    2. **Business value weight:** Inferred from item context -- items in earlier epics or with explicit priority indicators rank higher. If the item's current `priority` value is low (was previously prioritized high), preserve that signal.
+    3. **Dependency weight:** Read `epics.md` to identify explicit dependencies between stories. Items that BLOCK other items (other items depend on them) get a priority boost. Items that ARE BLOCKED get a slight deprioritization (they cannot proceed anyway). Within the same epic, assume stories are sequential (lower story number first).
+    4. **Type weight:** Bugs (`type: bug`) receive a slight priority boost over stories (`type: story`) at otherwise equal scoring, reflecting the principle that defects should be addressed before new features.
+    5. **Age weight (starvation prevention):** Items from lower-numbered epics or with lower item numbers within their epic get a slight boost to prevent indefinite deferral. This is the weakest signal -- it is a tiebreaker, not a dominant factor.
+  - Produce a ranked list sorted by composite score (highest score = priority 1).
+
+- [x] 3.5 **Step 3a -- Full mode workflow (AC: 2):**
+  - Display a comparison table: current order (left) vs suggested order (right), highlighting items that would move.
+  - For each item that changes position, show a brief rationale (e.g., "critical bug", "blocks 3 items", "age > 2 epics").
+  - Prompt: "[a] Accept suggested order / [m] Manually adjust (enter new order) / [c] Cancel"
+  - On `a`: proceed to Step 4 with the suggested order.
+  - On `m`: prompt the user to enter item numbers in their desired order. Validate that all items are accounted for (no duplicates, no missing). Proceed to Step 4 with the manual order.
+  - On `c`: exit without changes.
+
+- [x] 3.6 **Step 3b -- Quick mode workflow (AC: 3):**
+  - Apply the computed ranked order directly without prompting.
+  - Proceed immediately to Step 4 with the computed order.
+
+- [x] 3.7 **Step 3c -- Auto-suggest mode workflow (AC: 4):**
+  - Display the suggested new order with per-item rationale in a detailed table: New Priority, ID, Title, Rationale, Change (e.g., "+3 up", "-2 down", "unchanged").
+  - Display a summary: N items would move up, M items would move down, K items unchanged.
+  - Do NOT proceed to Step 4. Exit with: "Suggestions displayed. No changes written. Run again in Full or Quick mode to apply."
+
+- [x] 3.8 **Step 4 -- Apply reordering and persist (AC: 2, 3):**
+  - Take the confirmed ordering (from Full or Quick mode).
+  - Reorder the `backlog` array to match the new order.
+  - Renumber the `priority` field on each item sequentially: position 0 gets `priority: 1`, position 1 gets `priority: 2`, etc. (schema section 3.3: `priority` is a denormalized index that MUST be kept in sync with array position).
+  - Update the `last_updated` metadata field to the current ISO-8601 timestamp.
+  - Preserve the `generated` metadata field unchanged.
+  - Preserve the `epics` section unchanged.
+  - Preserve the `sprints` section unchanged.
+  - Write the complete `sprint-status.yaml` in a single atomic write (read-modify-write pattern).
+
+- [x] 3.9 **Step 5 -- Summary output:**
+  - Display the reprioritization summary:
+    - Mode used (Full / Quick).
+    - Items reordered: total count.
+    - Items that moved up (with old and new priority).
+    - Items that moved down (with old and new priority).
+    - Items unchanged.
+  - Suggest next steps: `/add-to-sprint` to assign top-priority items to a sprint, `/sprint-status-view` to view overall progress.
+
+### Task 4: Verify no legacy file references (AC: 8)
+
+- [x] 4.1 Confirm neither SKILL.md file contains any instruction to read from or write to `backlog.yaml` as a data source or write target.
+- [x] 4.2 Confirm neither SKILL.md file contains any instruction to write a standalone `backlog.yaml` file.
+- [x] 4.3 Confirm the only data file read/written is `sprint-status.yaml`.
+- [x] 4.4 Confirm neither SKILL.md file references the old `development_status` map or `sprint-plan-*.yaml` files.
+
+### Task 5: Deployment verification (AC: 9)
+
+- [x] 5.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer.
+- [x] 5.2 Verify the IDE skill appears in the installed MANIFEST.yaml for at least one agent (e.g., check `.claude/skills/MANIFEST.yaml` includes `prioritize-backlog`).
+- [x] 5.3 Diff the installed IDE copy (e.g., `.claude/skills/prioritize-backlog/SKILL.md`) against the source (`skills/prioritize-backlog/SKILL.md`) -- the content should match after accounting for frontmatter injection by the installer.
+- [x] 5.4 Verify the BMAD extension copy exists at `_bmad/extensions/ma-agents-skills/skills/prioritize-backlog/SKILL.md` after a BMAD install.
+- [x] 5.5 Verify the BMAD extension copy matches the source at `lib/bmad-extension/skills/prioritize-backlog/SKILL.md`.
+- [x] 5.6 Verify `prioritize-backlog` appears in the BMAD module help output.
+
+## Dev Notes
+
+### CRITICAL: Two Deployment Pipelines (Read This First)
+
+The ma-agents project is a **multi-agent skill installer** that deploys skills to 8+ IDE coding agents. There are TWO independent deployment pipelines, and this story creates source files for BOTH.
+
+**Why this matters:** The previous version of this story was fundamentally wrong -- it directed edits to `.claude/skills/prioritize-backlog/SKILL.md`, which is an INSTALLED COPY (a read-only deployed artifact). That path is where the installer OUTPUTS files, not where source files live. Furthermore, the Phase 1 implementation was rolled back entirely, so `prioritize-backlog` does NOT currently exist in either pipeline. This story creates it from scratch in both locations.
+
+#### Pipeline 1: IDE Skills (all IDE agents) -- NEW
+
+- **Source location:** `skills/prioritize-backlog/skill.json` + `skills/prioritize-backlog/SKILL.md`
+- **Status:** Does NOT exist. Task 1 creates these files from scratch.
+- **Deployed by:** `lib/installer.js` -> `performInstall()` which:
+  1. Reads `skill.json` for metadata
+  2. Falls back through: `templates/<agent>.md` -> `templates/generic.md` -> `SKILL.md`
+  3. Strips existing frontmatter, injects fresh frontmatter from `skill.json`
+  4. Copies to each agent's install directory (e.g., `.claude/skills/`, `.cursor/skills/`, etc.)
+- **Never hardcode agent paths.** The installer handles deployment to all agents automatically.
+- **Reference skill:** See `skills/story-status-lookup/` for a working example of `skill.json` + `SKILL.md`.
+
+#### Pipeline 2: BMAD Extension Skills (BMAD agents only) -- NEW
+
+- **Source location:** `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` + `bmad-skill-manifest.yaml`
+- **Status:** Does NOT exist. Task 2 creates these files from scratch.
+- **Deployed by:** `lib/bmad.js` which copies `lib/bmad-extension/` to `_bmad/extensions/ma-agents-skills/`
+- **Registered in:** `lib/bmad-extension/module-help.csv` (new row mapping to `bmm-sm` agent)
+- **Reference skill:** See `lib/bmad-extension/skills/add-to-sprint/` for a working example of `SKILL.md` + `bmad-skill-manifest.yaml`.
+
+#### Install Locations (NEVER edit these directly)
+
+- `.claude/skills/`, `.cursor/skills/`, `.cline/skills/`, `.roo/skills/`, `.gemini/skills/`, `.github/copilot/skills/`, `.kilocode/skills/` -- all managed by installer
+- `_bmad/extensions/ma-agents-skills/skills/` -- managed by BMAD deployer
+
+### What This Story Changes vs Current Behavior
+
+**Current state (post-rollback):** The `prioritize-backlog` skill does NOT exist in either pipeline. The Phase 1 implementation created an installed copy at `.claude/skills/prioritize-backlog/SKILL.md` that read/wrote a standalone `backlog.yaml` file. That implementation was rolled back in commit `85fad06`. No source files for this skill exist anywhere in the repository.
+
+**New behavior:** The skill is created from scratch in BOTH deployment pipelines. It reads the `backlog` array from `sprint-status.yaml`, applies multi-criteria prioritization scoring, and writes the reordered backlog back to the same file. Three modes are supported: Full (interactive), Quick (automated), and Auto-suggest (read-only). The `sprints` and `epics` sections are preserved unchanged on every write.
+
+### Key Design Decisions
+
+- **Output target:** `sprint-status.yaml` `backlog` section only. No standalone `backlog.yaml` is read or written.
+- **Scope boundary:** Only items in the `backlog` array are subject to reprioritization. Items in `sprints[].items` are completely excluded from the view and from scoring. This respects the single-location invariant (schema section 6.1).
+- **Three modes:** Full (interactive approval), Quick (automated apply), Auto-suggest (display-only). This provides flexibility from full control to quick automation.
+- **Priority renumbering:** After reordering, `priority` values are renumbered 1..N to keep the denormalized index in sync with array positions (schema section 3.3).
+- **Atomic write:** Single read-modify-write to `sprint-status.yaml`. The `backlog` section is replaced with the reordered version; `epics` and `sprints` sections are passed through unchanged.
+- **Weighted criteria (FR67):** Severity > Business Value > Dependencies > Type > Age. Severity is the strongest signal (critical bugs must float to top); age is the weakest (tiebreaker to prevent starvation).
+- **Dependency inference:** Reads `epics.md` for explicit inter-story dependencies. Within the same epic, assumes sequential ordering (lower story number = earlier dependency). Items that block other items get a priority boost.
+- **Legacy file handling:** If `backlog.yaml` exists alongside `sprint-status.yaml`, it is ignored with a logged note suggesting migration (Story 17.23).
+
+### Unified Schema Sections Touched
+
+- **`backlog`** -- read (display items, compute scores) + write (reordered array with renumbered priorities)
+- **`epics`** -- preserved unchanged (pass-through on write)
+- **`sprints`** -- preserved unchanged (pass-through on write); NOT read for item discovery (only `backlog` is in scope)
+- **Metadata** -- `last_updated` is updated on every write; `generated` is preserved unchanged
+
+### Rework Level: Light (but Create from Scratch)
+
+The epics document classifies this as a "Light rework" because the core prioritization logic (multi-criteria scoring, three modes, dependency analysis) is conceptually simple and well-defined. However, because the Phase 1 implementation was fully rolled back, the dev agent must create all files from scratch rather than modifying existing files. The tasks reflect this reality -- there are no files to read or modify, only files to create.
+
+### Prioritization Criteria Details (FR67)
+
+The following criteria are used to compute a composite priority score for each backlog item:
+
+| Criteria | Weight | Signal Source | Effect |
+|----------|--------|---------------|--------|
+| Severity | Highest | `severity` field on item | `critical` = top, `high` = elevated, `medium`/`low` = moderate/slight boost, `null` = no effect |
+| Business Value | High | Existing `priority` value, epic importance | Preserves existing prioritization signals; items from higher-priority epics rank higher |
+| Dependencies | Medium | `epics.md` inter-story dependencies | Blocking items boosted; blocked items slightly deprioritized |
+| Type | Low | `type` field on item | `bug` gets slight boost over `story` at equal composite score |
+| Age | Lowest | Epic number, item position | Lower epic number = older = slight boost; tiebreaker only |
+
+### Reference Files
+
+- **Schema:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (canonical schema, especially section 3 for backlog items, section 3.3 for priority renumbering)
+- **Sprint status:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- **Epics source:** `_bmad-output/planning-artifacts/epics.md` (for dependency inference in prioritization scoring)
+- **IDE skill reference:** `skills/story-status-lookup/skill.json` + `skills/story-status-lookup/SKILL.md` (example of `skill.json` + `SKILL.md` structure)
+- **BMAD skill reference:** `lib/bmad-extension/skills/add-to-sprint/` (example of `SKILL.md` + `bmad-skill-manifest.yaml`)
+- **Module help CSV:** `lib/bmad-extension/module-help.csv`
+- **PRD:** `_bmad-output/planning-artifacts/prd.md` (FR67, FR133, FR134)
+
+### Cross-References
+
+- **Story 17.9** (prerequisite): Defines the unified `sprint-status.yaml` schema and the `backlog` array item structure with `priority` field (section 3)
+- **Story 17.15** (prerequisite): `bmad-sprint-planning` bootstraps the file; `prioritize-backlog` requires it to exist
+- **Story 17.10** (prerequisite): `generate-backlog` populates the `backlog` section that this skill reorders
+- **Story 17.11** (downstream): `add-to-sprint` moves top-priority items from the backlog this skill orders into sprints
+- **Story 17.12** (peer): `remove-from-sprint` may return items to backlog, which may then need reprioritization
+- **Story 17.23** (migration): Migrates old `backlog.yaml` to the unified file; this skill ignores the legacy file if present
+
+### PRD Traceability
+
+- **FR67:** Story/bug prioritization supports multiple criteria beyond epic precedence -- criteria include severity, business value, dependencies, type, and age. This is the primary FR for this story; the multi-criteria scoring engine implements it directly.
+- **FR133:** `sprint-status.yaml` includes top-level metadata (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`) -- `last_updated` must be refreshed on write.
+- **FR134:** Each item in the backlog carries a consistent structure (`id`, `type`, `epic`, `title`, `priority`, `status`, `severity`). Prioritization respects section boundaries -- items in `backlog` are reordered; items in `sprints` are untouched.
+- **FR65:** All sprint, backlog, and epic status data is managed in a single `sprint-status.yaml` file. This skill reads from and writes to that single file.
+- **NFR19:** Skills work identically across invocation modes (slash command, menu, workflow).
+
+### Architecture Reference
+
+- Architecture Decision P2-5 in `_bmad-output/planning-artifacts/architecture.md` -- Pre-built Extension Workflows (FR61, FR68-FR70)
+- Architecture Decision P2-11 in `_bmad-output/planning-artifacts/architecture.md` -- Unified sprint-status.yaml model
+- Schema: `_bmad-output/planning-artifacts/sprint-status-schema.md` -- canonical schema, especially section 3 (backlog), section 3.3 (priority renumbering invariant), section 6.1 (single-location invariant)
+
+---
+
+## Dev Agent Record
+
+### Implementation Notes
+
+- Created skill from scratch in both deployment pipelines (IDE + BMAD extension).
+- IDE skill (`skills/prioritize-backlog/`) uses `skill.json` + `SKILL.md` pattern — no `always_load` (on-demand skill).
+- BMAD extension (`lib/bmad-extension/skills/prioritize-backlog/`) adds frontmatter triggers and BMAD config path resolution.
+- The BMAD version checks `_bmad/bmm/config.yaml` for a `sprint_status_path` override before defaulting to the standard path.
+- Both versions implement identical multi-criteria scoring (severity, business value, dependencies, type, age) and all three modes (Full, Quick, Auto-suggest).
+- Registered in `lib/bmad-extension/module-help.csv` with `bmm-sm` agent assignment.
+
+### Code Review Findings (2026-04-06)
+
+- AC 1-10: All acceptance criteria implemented.
+- No `backlog.yaml` read/write instructions — only detection + warning (AC 8). PASS.
+- No `development_status` map or `sprint-plan-*.yaml` references. PASS.
+- Priority renumbering 1..N in Step 4. PASS.
+- Epics/sprints/generated preserved unchanged on every write. PASS.
+- Three modes (Full/Quick/Auto-suggest) all implemented. PASS.
+- Cross-repo-validation test failure is pre-existing (unrelated to this story — checked on main branch). PASS.
+
+### File List
+
+**Created:**
+- `skills/prioritize-backlog/skill.json` — IDE skill metadata
+- `skills/prioritize-backlog/SKILL.md` — IDE skill workflow (canonical source)
+- `lib/bmad-extension/skills/prioritize-backlog/SKILL.md` — BMAD extension skill workflow
+- `lib/bmad-extension/skills/prioritize-backlog/bmad-skill-manifest.yaml` — BMAD skill manifest
+
+**Modified:**
+- `lib/bmad-extension/module-help.csv` — Added `prioritize-backlog` row for `bmm-sm` agent
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Status updated to `review`
+- `_bmad-output/implementation-artifacts/17-24-rework-prioritize-backlog.md` — Story status + tasks updated
+
+### Change Log
+
+| Date | Change | Author |
+|------|--------|--------|
+| 2026-04-06 | Created skill from scratch in both deployment pipelines; implemented multi-criteria prioritization with Full/Quick/Auto-suggest modes | Dev Agent |

package/_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md

@@ -0,0 +1,279 @@
+# Story 17.9: Unified sprint-status.yaml Schema
+
+Status: done
+
+## Story
+
+As a **Scrum Master**,
+I want all sprint management data consolidated into a single `sprint-status.yaml` file with three structured sections (epics, backlog, sprints),
+So that there is one source of truth for all sprint/backlog state — eliminating data duplication and cross-file consistency bugs.
+
+## Acceptance Criteria
+
+1. **Given** the unified schema is defined,
+   **When** `sprint-status.yaml` is created or updated by any skill,
+   **Then** it contains exactly three data sections (`epics`, `backlog`, `sprints`) plus top-level metadata fields (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`).
+
+2. **Given** the `epics` section exists,
+   **When** any skill reads it,
+   **Then** it is a YAML **map** keyed by epic ID (e.g., `epic-5:`) with fields `status` (`backlog` | `in-progress` | `done`) and `retrospective` (`optional` | `done` | null).
+
+3. **Given** the `backlog` section exists,
+   **When** any skill reads it,
+   **Then** it is a YAML **array** of item objects. Each item has: `id` (string), `type` (`story` | `bug`), `epic` (integer | null), `title` (string), `priority` (integer), `status` (string), and optional `severity` (null | `critical` | `high` | `medium` | `low`).
+
+4. **Given** the `sprints` section exists,
+   **When** any skill reads it,
+   **Then** it is a YAML **map** keyed by sprint ID (e.g., `sprint-3:`) with fields: `name` (string), `status` (`planning` | `active` | `closed`), `capacity` (integer), `start` (ISO date string or empty), `end` (ISO date string or empty), and `items` (array of item objects — same schema as backlog items but WITHOUT the `priority` field).
+
+5. **Given** a story or bug exists in the file,
+   **When** any skill searches for it,
+   **Then** the item exists in exactly **one** location — either the `backlog` array OR a single sprint's `items` array. Never both.
+
+6. **Given** an item's status changes (e.g., `ready-for-dev` to `in-progress`),
+   **When** the status is updated by any skill,
+   **Then** the `status` field is updated **in-place** on the item in whichever section it resides.
+
+7. **Given** an item reaches `done` status,
+   **When** cleanup runs (Story 17.14),
+   **Then** the item is REMOVED from `sprint-status.yaml` entirely and archived to `done/`.
+
+8. **Given** a sprint transitions from `planning` to `active`,
+   **When** the activation occurs,
+   **Then** only one sprint can have `status: active` at a time. The previous active sprint must be closed first.
+
+9. **Given** the `tracking_system` field is set to `file-system` (default),
+   **When** any sprint skill runs,
+   **Then** it reads/writes the local YAML file. When set to `jira`, skills route to the Jira adapter (Story 17.22).
+
+## Tasks / Subtasks
+
+- [x] Task 1: Define canonical YAML schema (AC: 1-4)
+  - [x] 1.1 Write the canonical schema as a reference specification — this is the contract ALL 13 skills will code against
+  - [x] 1.2 Document the top-level metadata fields and their semantics
+  - [x] 1.3 Document the `epics` map schema with status transitions
+  - [x] 1.4 Document the `backlog` array item schema with all fields
+  - [x] 1.5 Document the `sprints` map schema with sprint entity and items sub-schema
+  - [x] 1.6 Document the item schema difference between backlog (has `priority`) and sprint items (no `priority`)
+- [x] Task 2: Define invariants and constraints (AC: 5-8)
+  - [x] 2.1 Document the single-location invariant — an item ID must appear in exactly one section
+  - [x] 2.2 Document the in-place status update rule
+  - [x] 2.3 Document the done-removal rule
+  - [x] 2.4 Document the single-active-sprint constraint
+  - [x] 2.5 Document valid sprint status transitions: `planning` → `active` → `closed` (no backward)
+  - [x] 2.6 Document valid story status transitions: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+- [x] Task 3: Define the tracking_system adapter contract (AC: 9)
+  - [x] 3.1 Document the `tracking_system` field semantics (`file-system` vs `jira`)
+  - [x] 3.2 Document that the schema is the canonical data contract for both backends
+- [x] Task 4: Create a reference example file (AC: 1-9)
+  - [x] 4.1 Write a fully populated example `sprint-status.yaml` showing all sections with realistic data from the agents project
+  - [x] 4.2 Include edge cases: a bug in backlog, a closed sprint with empty items, a planning sprint with no items
+
+### Review Findings
+
+- [x] [Review][Decision] #1 `on-hold` and `cancelled` statuses added to schema — Added to epic statuses (Section 2.3) and item statuses (Section 6.6) with transition rules. `on-hold` is bidirectional pause; `cancelled` is terminal from any non-done state. **Resolved.**
+- [x] [Review][Decision] #2 `canceled` status — Resolved by #1. Added `cancelled` as terminal status for both epics and items.
+- [x] [Review][Decision] #3 Priority dual-authority resolved — Array position is now authoritative; `priority` field is denormalized index kept in sync (Section 3.3). Validation rule 12 added.
+- [x] [Review][Decision] #4 `remove-from-sprint` status reset — Status resets to `ready-for-dev` (not `backlog`, because story file already exists). Only `ready-for-dev` items may be added to sprints. Documented in Section 4.5 and Section 6.6. **Resolved.**
+- [x] [Review][Decision] #5 Closed sprint immutability exception — Section 6.7 now has explicit exception for done/cancelled item archival by `cleanup-done`. Section 6.8 added for sprint item disposition on close. **Resolved.**
+- [x] [Review][Decision] #6 Capacity is advisory — Section 4.2 updated: skills SHOULD warn but MUST NOT block when items exceed capacity. **Resolved.**
+- [x] [Review][Patch] #7 P2-11 sprint item `priority` removed — architecture.md line 956 fixed. **Applied.**
+- [x] [Review][Patch] #8 P2-11 backlog status constraint aligned — architecture.md line 969 updated to match schema Section 3.3. **Applied.**
+- [x] [Review][Patch] #9 Story Dev Notes reference fixed — "17.2-17.16" → "17.10-17.24". **Applied.**
+- [x] [Review][Patch] #10 Empty section validity notes added — `backlog: []` and `epics: {}` documented as valid (Sections 2.4 and 3.3). **Applied.**
+- [x] [Review][Patch] #11 Epic-to-item mapping rule added — `epic: N` maps to `epic-N` key; `epic: null` excluded from derivation (Section 3.3). **Applied.**
+- [x] [Review][Patch] #12 Done item movement restriction added — `done` items cannot be moved to backlog; only archived (Section 4.5). **Applied.**
+- [x] [Review][Patch] #13 Priority reassignment rule defined — `max(existing) + 1`; empty backlog gets `priority: 1` (Section 4.5). **Applied.**
+- [x] [Review][Patch] #14 Closed sprint disposition note added — New Section 6.8 documents item disposition before close. **Applied.**
+- [x] [Review][Defer] #15 sprint-status.yaml still uses old flat `development_status` format — deferred, pre-existing (migration is Story 17.23)
+- [x] [Review][Defer] #16 `generated` field in sprint-status.yaml is bare date, not ISO-8601 datetime — deferred, pre-existing (will be reformatted by Story 17.15 bootstrap)
+- [x] [Review][Defer] #17 No `schema_version` metadata field — deferred, out of scope for 17.9 (can be added in a future story if schema evolution is needed)
+- [x] [Review][Defer] #18 Concurrent modification has no locking guidance — deferred, skills run serially in current architecture
+- [x] [Review][Defer] #19 `correct-course` referenced in Section 4.6 but not in skill map — deferred, informational reference only
+
+## Dev Notes
+
+### What This Story IS
+
+This is a **schema definition** story, not a skill implementation story. The deliverable is a canonical YAML schema specification that serves as the contract for all 13 skills that will be reworked in subsequent stories (17.10-17.24). Think of it as the "protobuf definition" — the interface contract that everything else implements against.
+
+### What This Story Is NOT
+
+This story does NOT:
+- Modify any existing skills
+- Write any JavaScript/TypeScript code
+- Change how any skill reads or writes sprint-status.yaml
+- Migrate existing data
+
+Those are all subsequent stories (17.10-17.24).
+
+### Current State (What's Being Replaced)
+
+The current `sprint-status.yaml` uses a **flat `development_status` map**:
+
+```yaml
+generated: 2026-03-15
+project: agents
+tracking_system: file-system
+story_location: _bmad-output/implementation-artifacts
+
+development_status:
+  epic-1: done
+  1-1-ci-cd-yes-flag: done
+  epic-1-retrospective: optional
+  epic-5: in-progress
+  5-5-explicit-parameter-passing: review
+```
+
+**Problems with this format:**
+- Epics, stories, and retrospectives share a flat namespace
+- No sprint entity — just a status list
+- No backlog concept — items are either in the list or not
+- No movement semantics — status is a string, not a lifecycle
+- Separate `backlog.yaml` and `sprints/sprint-N.yaml` files exist but drift out of sync
+
+### New Schema (The Deliverable)
+
+```yaml
+generated: "2026-04-03T12:00:00Z"
+last_updated: "2026-04-03T12:00:00Z"
+project: agents
+project_key: NOKEY
+tracking_system: file-system
+story_location: _bmad-output/implementation-artifacts
+
+epics:
+  epic-5:
+    status: in-progress
+    retrospective: optional
+  epic-17:
+    status: in-progress
+    retrospective: optional
+
+backlog:
+  - id: "17-10-rework-generate-backlog"
+    type: story
+    epic: 17
+    title: "Rework generate-backlog Skill"
+    priority: 1
+    status: backlog
+    severity: null
+  - id: "BUG-path-spaces"
+    type: bug
+    epic: null
+    title: "Fix space-in-path bug"
+    priority: 2
+    status: backlog
+    severity: high
+
+sprints:
+  sprint-3:
+    name: "Sprint 3"
+    status: active
+    capacity: 6
+    start: "2026-04-03"
+    end: "2026-04-14"
+    items:
+      - id: "5-5-explicit-parameter-passing"
+        type: story
+        epic: 5
+        title: "Explicit Parameter Passing"
+        status: in-progress
+        severity: null
+      - id: "5-6-fix-space-in-path-bug"
+        type: story
+        epic: 5
+        title: "Fix Space-in-Path Bug"
+        status: review
+        severity: null
+  sprint-2:
+    name: "Sprint 2"
+    status: closed
+    capacity: 8
+    start: "2026-03-15"
+    end: "2026-03-28"
+    items: []
+```
+
+### Key Schema Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| `epics` is a **map**, not array | Keyed lookup by `epic-N` — matches how skills search for epic status |
+| `backlog` is an **array** | Ordered by priority — position in array = priority rank |
+| `sprints` is a **map** keyed by sprint ID | Fast lookup by `sprint-N` key; matches existing sprint ID convention |
+| Items in backlog have `priority` field | Explicit numeric priority for sorting |
+| Items in sprint do NOT have `priority` | Once in a sprint, priority is implicit (order within the sprint) |
+| `severity` is null for stories | Only bugs have severity; null distinguishes stories from bugs alongside `type` |
+| Sprint `items` uses same schema minus `priority` | Consistency — same item object, just drops one field on move |
+
+### Skills That Will Consume This Schema (13 total)
+
+All of these will be reworked in subsequent stories to read/write the new schema:
+
+| Skill | Story | Operation | Current Schema Assumption |
+|-------|-------|-----------|--------------------------|
+| `bmad-sprint-planning` | 17.15 | Bootstraps entire file | Writes flat `development_status` map |
+| `generate-backlog` | 17.10 | Writes `backlog` section | Writes separate `backlog.yaml` |
+| `add-sprint` | 17.16 | Writes `sprints` section | Creates separate `sprints/sprint-N.yaml` |
+| `add-to-sprint` | 17.11 | Moves items backlog→sprint | Dual-writes `backlog.yaml` + `sprint-N.yaml` |
+| `remove-from-sprint` | 17.12 | Moves items sprint→backlog | Dual-writes reverse |
+| `sprint-status-view` | 17.13 | Reads all sections | Cross-references 3 files |
+| `cleanup-done` | 17.14 | Removes done items | Scans 3 files |
+| `modify-sprint` | 17.17 | Updates sprint entry | Reads/writes `sprint-N.yaml` |
+| `bmad-dev-story` | 17.18 | Updates item status | Writes flat `development_status[key]` |
+| `story-status-lookup` | 17.19 | Searches for item | Reads flat `development_status[key]` |
+| `bmad-sprint-status` | 17.20 | Summarizes sprint health | Parses flat key map |
+| `prioritize-backlog` | 17.24 | Reorders backlog items | Reads/writes `backlog.yaml` |
+| `close-sprint` | 17.21 | Closes sprint lifecycle | NEW — does not exist yet |
+
+### Architecture Reference
+
+- [Architecture P2-11: Unified Sprint-Status File Architecture](../_bmad-output/planning-artifacts/architecture.md) — full schema, design principles, skill integration map, adapter pattern
+- [PRD FR133-FR140](../_bmad-output/planning-artifacts/prd.md) — functional requirements for unified sprint-status
+- [Epics: Epic 17](../_bmad-output/planning-artifacts/epics.md) — all 16 stories with acceptance criteria
+
+### Project Structure Notes
+
+- Schema file location: `{sprint_management_path}/_bmad-output/implementation-artifacts/sprint-status.yaml` (resolved via `config.yaml`, defaults to `_bmad-output/implementation-artifacts/sprint-status.yaml`)
+- `done/` archive folder: `{implementation_artifacts}/done/`
+- Config path: `_bmad/bmm/config.yaml` → `sprint_management_path`, `implementation_artifacts`
+
+### Deliverable Location
+
+The schema specification should be written as a reference document. Suggested location: `_bmad-output/planning-artifacts/sprint-status-schema.md` — a standalone schema reference that dev agents can load when implementing skills 17.10-17.24.
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4.6 (1M context)
+
+### Debug Log References
+
+- Validated reference YAML example programmatically using Python `yaml.safe_load()` + structural assertions
+- All invariants verified: single-location, single-active-sprint, field completeness, sprint items lack `priority`
+
+### Completion Notes List
+
+- Created canonical schema specification at `_bmad-output/planning-artifacts/sprint-status-schema.md` (10 sections)
+- Section 1: Top-level structure — 6 metadata fields + 3 data sections
+- Section 2: Epics map schema — keyed by `epic-N`, status transitions `backlog → in-progress → done`
+- Section 3: Backlog array schema — 7 required fields per item including `priority`
+- Section 4: Sprints map schema — sprint entity + items sub-schema (6 fields, NO `priority`)
+- Section 5: Tracking system adapter contract — `file-system` vs `jira` backend behavior
+- Section 6: Invariants and constraints — 7 rules (single-location, in-place update, done-removal, single-active-sprint, sprint transitions, item transitions, closed sprint immutability)
+- Section 7: Skill integration map — all 13 consuming skills with rework level
+- Section 8: File location resolution — single-repo and multi-repo modes
+- Section 9: Reference example — fully populated YAML with 3 epics, 4 backlog items, 3 sprints (active/planning/closed)
+- Section 10: Schema validation checklist — 10-point validation rules for writing skills
+
+### Change Log
+
+- 2026-04-03: Created sprint-status-schema.md — canonical YAML schema specification (Story 17.9)
+
+### File List
+
+- `_bmad-output/planning-artifacts/sprint-status-schema.md` (NEW) — canonical schema reference document
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (MODIFIED) — status updated for story 17-9
+- `_bmad-output/implementation-artifacts/17-9-unified-sprint-status-schema.md` (MODIFIED) — story file updates