ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/17-20-rework-bmad-sprint-status.md

@@ -1,508 +0,0 @@
-# Story 17.20: Rework bmad-sprint-status Skill (Extension Override -- Analysis-Focused Health Summary)
-
-Status: review
-
-## Story
-
-As a **Scrum Master**,
-I want the `bmad-sprint-status` skill to produce an analysis-focused health summary with risk flags and recommendations by reading the unified `sprint-status.yaml`,
-So that sprint health, risks, and next-action recommendations are surfaced quickly from the single source of truth, available across all IDE agents and BMAD workflows.
-
-## Acceptance Criteria
-
-1. **Given** `bmad-sprint-status` is a BMAD built-in skill (originating from `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/`),
-   **When** the extension override files are created in `lib/bmad-extension/skills/bmad-sprint-status/`,
-   **Then** the extension version takes precedence over the built-in during BMAD deployment (via the `--custom-content` flag),
-   **And** the built-in at `node_modules/bmad-method/` is NOT modified.
-
-2. **Given** the `bmad-sprint-status` skill is invoked in interactive mode,
-   **When** it reads `sprint-status.yaml`,
-   **Then** it identifies the active sprint from the `sprints` section and produces a health summary containing:
-   - **Active Sprint Health:** items grouped by status count (in-progress, review, ready-for-dev, backlog, on-hold, cancelled), capacity usage (`items.length / capacity` as a ratio and percentage), sprint name, and date range
-   - **Risk Flags:** blocked/on-hold items, over-capacity warning, stale items (in-progress for more than 14 days since sprint `start` date), items not started (still in `ready-for-dev` or `backlog` status), no items progressing toward completion (no items in `review` or `done`)
-   - **Backlog Health:** total unassigned items count, count by type (story vs bug), critical/high severity bug count
-   - **Epic Progress:** stories done/total per epic (derived by scanning `backlog` and all `sprints[*].items` for matching `epic` field; done count from `done/` folder)
-   - **Sprint History:** count of closed sprints with one-line summaries (name, item count, dates)
-   - **Next Recommendation:** the single most actionable next step (same priority logic as current built-in)
-
-3. **Given** the active sprint has items with concerning statuses,
-   **When** the health summary is generated,
-   **Then** it flags specific, actionable risks such as:
-   - "3 of 6 items still in `ready-for-dev` status -- not yet started"
-   - "Sprint at 100% capacity (6/6) with 2 items still in `ready-for-dev`"
-   - "No items in `review` or `done` -- sprint may be at risk"
-   - "Item 17-15 has been in-progress for 12 days (sprint started 2026-04-03)"
-   - "1 item on-hold: 5-5-explicit-parameter-passing"
-   - "`last_updated` is 8 days old -- sprint-status.yaml may be stale"
-   - "Orphaned story detected: story 99-1 references epic-99 which is not in the `epics` section"
-
-4. **Given** no active sprint exists (all sprints are `planning` or `closed`, or no sprints section),
-   **When** the health summary is generated,
-   **Then** it reports "No active sprint" and recommends running `/add-sprint` or activating a planning sprint,
-   **And** still displays backlog health, epic progress, and sprint history sections.
-
-5. **Given** `sprint-status.yaml` does not exist,
-   **When** the skill is invoked,
-   **Then** it reports: "No sprint-status.yaml found. Run `/bmad-sprint-planning` to initialize.",
-   **And** the skill exits without error.
-
-6. **Given** the skill is invoked in data mode (`mode = data`),
-   **When** it processes `sprint-status.yaml`,
-   **Then** it returns structured key-value output consumable by other skills/workflows:
-   - `active_sprint_id`, `active_sprint_name`
-   - `count_backlog`, `count_ready`, `count_in_progress`, `count_review`, `count_done`, `count_on_hold`
-   - `capacity_used`, `capacity_total`, `capacity_pct`
-   - `epic_summary` (per-epic done/total)
-   - `backlog_total`, `backlog_bugs`, `backlog_critical_bugs`
-   - `risks` (list of risk strings)
-   - `next_workflow_id`, `next_story_id`
-   **And** the output contract is backward-compatible with the current data mode consumers (preserving `next_workflow_id`, `next_story_id`, `count_*`, `risks` keys).
-
-7. **Given** the skill is invoked in validate mode (`mode = validate`),
-   **When** it checks `sprint-status.yaml`,
-   **Then** it validates the unified schema structure: presence of `epics`, `backlog`, `sprints` sections plus 6 metadata fields, valid status values per the schema state machines, single-location invariant (spot check), and at most one active sprint,
-   **And** returns `is_valid`, `error`, `suggestion` keys.
-
-8. **Given** the skill source files exist in BOTH deployment pipelines (IDE skill at `skills/bmad-sprint-status/` and BMAD extension override at `lib/bmad-extension/skills/bmad-sprint-status/`),
-   **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 override is deployed via `lib/bmad.js` to `_bmad/extensions/ma-agents-skills/`,
-   **And** the BMAD extension override replaces the upstream built-in during BMAD agent compilation.
-
-9. **Given** the skill is invoked from ANY IDE agent (Claude Code, Cursor, Cline, Roo Code, Gemini, Copilot, Kilocode, etc.) OR from a BMAD workflow,
-   **When** it executes,
-   **Then** it works identically in both invocation modes (NFR19),
-   **And** the skill is read-only -- it NEVER writes to `sprint-status.yaml` or any other file.
-
-10. **Given** the analysis-focused summary from `bmad-sprint-status` and the display-focused view from `sprint-status-view` (Story 17.13) both exist,
-    **When** a user needs sprint information,
-    **Then** the two skills serve complementary purposes:
-    - `bmad-sprint-status` = **analysis and recommendations** (health metrics, risk flags, next-action recommendation, concise for LLM context)
-    - `sprint-status-view` = **display and navigation** (formatted tables, all items listed, interactive menu for drill-down)
-    **And** there is no functional duplication -- `bmad-sprint-status` does NOT render full item tables, and `sprint-status-view` does NOT compute risk flags or recommendations.
-
-## Tasks / Subtasks
-
-### Task 1: Create the BMAD extension override skill files (AC: 1, 8) -- CRITICAL OVERRIDE
-
-`bmad-sprint-status` is a **BMAD built-in skill** that ships with `bmad-method` at `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/`. Per project policy, we NEVER modify built-in skills directly. Instead, we create an **extension override** in `lib/bmad-extension/skills/bmad-sprint-status/` that takes precedence at deployment time.
-
-The built-in contains two files (`SKILL.md`, `workflow.md`). The extension override MUST provide replacements for BOTH files (plus a `bmad-skill-manifest.yaml`) so the override is complete and no built-in file leaks through.
-
-- [x] 1.1 Create `lib/bmad-extension/skills/bmad-sprint-status/bmad-skill-manifest.yaml`:
-  ```yaml
-  type: skill
-  name: bmad-sprint-status
-  module: ma-skills
-  ```
-
-- [x] 1.2 Create `lib/bmad-extension/skills/bmad-sprint-status/SKILL.md` -- override of the built-in SKILL.md. The BMAD extension version is authored for the BMAD Scrum Master agent (`bmm-sm`) context and references `_bmad/bmm/config.yaml` for path resolution. It MUST delegate to `./workflow.md` (same pattern as the upstream built-in):
-  ```markdown
-  ---
-  name: bmad-sprint-status
-  description: 'Summarize sprint health, surface risks, and recommend next actions from the unified sprint-status.yaml. Use when the user says "check sprint status" or "show sprint health"'
-  ---
-
-  Follow the instructions in ./workflow.md.
-  ```
-
-- [x] 1.3 Create `lib/bmad-extension/skills/bmad-sprint-status/workflow.md` -- complete replacement of the upstream built-in workflow. This is the main implementation file. See Task 4 for content specification.
-
-- [x] 1.4 Register the skill in `lib/bmad-extension/module-help.csv` by adding a row:
-  ```csv
-  ma-skills,4-implementation,Sprint Status Health,bmad-sprint-status,,skill:bmad-sprint-status,bmad-sprint-status,false,bmm-sm,,"Analyze sprint health, surface risk flags, and recommend next actions from the unified sprint-status.yaml.",_bmad-output/implementation-artifacts,"health summary",
-  ```
-  The `agent` column is `bmm-sm` (Scrum Master) because sprint health analysis is a Scrum Master responsibility.
-
-### Task 2: Create the IDE skill source files (AC: 8, 9) -- NEW
-
-The IDE skill does NOT yet exist (the current installed copy at `.claude/skills/bmad-sprint-status/` is the BMAD built-in, not an IDE skill). This task creates a proper IDE skill from scratch so all 8+ IDE coding agents can invoke sprint health analysis directly.
-
-- [x] 2.1 Create `skills/bmad-sprint-status/skill.json` with metadata:
-  ```json
-  {
-    "name": "bmad-sprint-status",
-    "version": "1.0.0",
-    "description": "Analyze sprint health, surface risk flags, and recommend next actions from the unified sprint-status.yaml",
-    "category": "workflow",
-    "tags": ["sprint-status", "sprint-management", "health", "risks", "analysis"]
-  }
-  ```
-  Note: `always_load` is intentionally omitted (defaults to false) -- this skill is invoked on demand, not loaded for every task.
-
-- [x] 2.2 Create `skills/bmad-sprint-status/SKILL.md` with the complete skill workflow (see Task 5 for content specification). This is the canonical skill content that the installer deploys to all IDE agents. The IDE version is self-contained (does not reference `./workflow.md`) and does not rely on BMAD config loading -- it resolves paths from the project structure directly.
-
-### Task 3: Read and understand the current built-in skill (AC: 1-7)
-
-Before writing the replacement files, study the built-in to understand what is being overridden.
-
-- [x] 3.1 Read `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/SKILL.md` (upstream built-in) -- note it delegates to `./workflow.md`
-- [x] 3.2 Read `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md` (upstream built-in) -- document the workflow structure:
-  - Step 0: Mode dispatch (interactive / data / validate)
-  - Step 1: Locate sprint-status.yaml
-  - Step 2: Parse flat `development_status` map, classify keys by pattern, count statuses, detect risks
-  - Step 3: Select next action recommendation
-  - Step 4: Display summary
-  - Step 5: Offer interactive actions (4 options)
-  - Step 20: Data mode output (key-value pairs)
-  - Step 30: Validate mode (schema checks)
-- [x] 3.3 Document what MUST change: `development_status` flat map parsing replaced with structured `epics`/`backlog`/`sprints` section reads, legacy status mappings removed, capacity tracking added, sprint-scoped analysis added, risk flags expanded
-- [x] 3.4 Document what MUST be preserved: three execution modes (interactive / data / validate), mode dispatch routing, next-action recommendation logic, data mode output key names (backward compatibility), interactive action menu structure
-
-### Task 4: Implement the BMAD extension workflow.md content (AC: 2, 3, 4, 5, 6, 7, 9, 10)
-
-The `workflow.md` file (for `lib/bmad-extension/skills/bmad-sprint-status/workflow.md`) must implement the following workflow.
-
-- [x] 4.1 **Initialization -- Config loading:** Preserve the existing initialization block from the built-in workflow:
-  - Load config from `{project-root}/_bmad/bmm/config.yaml`
-  - Resolve: `project_name`, `user_name`, `communication_language`, `document_output_language`, `implementation_artifacts`
-  - Set `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
-  - Set `done_folder` = `{implementation_artifacts}/done/`
-  - Load `project_context` = `**/project-context.md` (if exists)
-
-- [x] 4.2 **Step 0 -- Mode dispatch (preserved from built-in):**
-  - `mode = data` -> Jump to Step 20
-  - `mode = validate` -> Jump to Step 30
-  - `mode = interactive` (default) -> Continue to Step 1
-
-- [x] 4.3 **Step 1 -- Locate and load sprint-status.yaml:**
-  - Load `{project_context}` for project-wide patterns (if exists)
-  - Try to read `{sprint_status_file}`
-  - If file not found: output "sprint-status.yaml not found. Run `/bmad-sprint-planning` to initialize." and exit
-  - Parse YAML into three data sections: `epics`, `backlog`, `sprints`, plus metadata fields
-
-- [x] 4.4 **Step 2 -- Analyze active sprint health (AC: 2):**
-  - Scan `sprints` map for the sprint with `status: active`. If no active sprint found, set `active_sprint = null` and skip to Step 2b
-  - For the active sprint, compute:
-    - `items_by_status`: count items grouped by `status` field (in-progress, review, ready-for-dev, backlog, on-hold, cancelled, done)
-    - `capacity_used` = `items.length`, `capacity_total` = `capacity`, `capacity_pct` = `(items.length / capacity) * 100` (handle capacity=0 as "no limit")
-    - `sprint_age_days` = days between `start` date and today (if `start` is populated)
-    - Per-item staleness: for each item with `status: in-progress`, compute days since sprint `start` date
-
-- [x] 4.5 **Step 2b -- Analyze backlog health (AC: 2):**
-  - `backlog_total` = length of `backlog` array
-  - `backlog_bugs` = count of items with `type: bug`
-  - `backlog_critical_bugs` = count of bugs with `severity: critical` or `severity: high`
-  - `backlog_stories` = `backlog_total - backlog_bugs`
-
-- [x] 4.6 **Step 2c -- Compute epic progress (AC: 2):**
-  - For each epic in the `epics` section:
-    - Count items across `backlog` and all `sprints[*].items` where `epic` field matches the epic number
-    - Scan `{done_folder}` for archived story files matching the epic pattern (e.g., files starting with `N-` for `epic-N`)
-    - Compute `done_count` (from done folder) and `total_count` (done + active items)
-    - Record epic status from `epics` section
-
-- [x] 4.7 **Step 2d -- Compute sprint history (AC: 2):**
-  - Count sprints with `status: closed`
-  - For each closed sprint, capture: name, item count (length of `items` array), start/end dates
-
-- [x] 4.8 **Step 3 -- Detect risk flags (AC: 3, 4):**
-  - **Stale items:** Items with `status: in-progress` in the active sprint where `start` date is more than 14 days before today
-  - **Not started:** Count of items in active sprint with `status: ready-for-dev` or `status: backlog` -- flag if more than half the sprint items are not started
-  - **Over-capacity:** Active sprint where `items.length > capacity` (include overage count)
-  - **No progress:** No items in `review` or `done` status in the active sprint (flag only if sprint is at least 3 days old)
-  - **On-hold/blocked items:** Any items with `status: on-hold` or `status: cancelled` in the active sprint
-  - **Stale file:** `last_updated` timestamp is more than 7 days old (fall back to `generated` if `last_updated` missing)
-  - **Orphaned stories:** Any item in `backlog` or `sprints[*].items` whose `epic` field references an epic number not present in the `epics` section
-  - **In-progress epic with no stories:** Any epic with `status: in-progress` that has zero items referencing it across `backlog` and all `sprints[*].items`
-  - **Critical bugs in backlog:** Any bug with `severity: critical` sitting in the backlog (not assigned to a sprint)
-  - **No active sprint:** No sprint has `status: active` (recommend activating a planning sprint or creating one)
-
-- [x] 4.9 **Step 4 -- Select next action recommendation (AC: 2):**
-  Preserve the priority-based recommendation logic from the built-in, adapted for the unified schema:
-  1. If any item in the active sprint has `status: in-progress` -> recommend `dev-story` for that item
-  2. Else if any item has `status: review` -> recommend `code-review` for that item
-  3. Else if any item has `status: ready-for-dev` (in sprint or backlog) -> recommend `dev-story`
-  4. Else if any item has `status: backlog` -> recommend `create-story`
-  5. Else if any epic has `retrospective: optional` and `status: done` -> recommend `retrospective`
-  6. Else -> all work complete; congratulate the user
-  When selecting "first" item: prefer active sprint items over backlog items; within each, sort by epic number then story number.
-
-- [x] 4.10 **Step 5 -- Display interactive summary (AC: 2, 3):**
-  Output the health summary in this format:
-
-  ```
-  ## Sprint Health Summary
-
-  - Project: {{project}} ({{project_key}})
-  - Tracking: {{tracking_system}}
-  - Last updated: {{last_updated}}
-
-  ### Active Sprint: {{sprint_name}}
-  **Capacity:** {{capacity_used}} / {{capacity_total}} ({{capacity_pct}}%)
-  **Dates:** {{start}} to {{end}}
-  **Items by status:** in-progress {{n}}, review {{n}}, ready-for-dev {{n}}, backlog {{n}}, on-hold {{n}}
-
-  ### Risk Flags
-  {{#each risks}}
-  - {{this}}
-  {{/each}}
-  (or "No risks detected." if empty)
-
-  ### Backlog Health
-  - Total unassigned: {{backlog_total}} ({{backlog_stories}} stories, {{backlog_bugs}} bugs)
-  - Critical/high bugs in backlog: {{backlog_critical_bugs}}
-
-  ### Epic Progress
-  {{#each epics}}
-  - Epic {{id}} ({{status}}): {{done}}/{{total}} done
-  {{/each}}
-
-  ### Sprint History
-  - {{closed_count}} closed sprint(s)
-  {{#each closed_sprints}}
-  - {{name}}: {{item_count}} items, {{start}} to {{end}}
-  {{/each}}
-
-  ### Next Recommendation
-  /{{next_workflow_id}} ({{next_story_id}})
-  ```
-
-- [x] 4.11 **Step 6 -- Offer interactive actions (AC: 2):**
-  Present menu options:
-  1. Run recommended workflow now
-  2. Show all items grouped by status (active sprint items + backlog items)
-  3. Show detailed sprint view -- suggest running `/sprint-status-view` for full formatted tables
-  4. Show raw sprint-status.yaml
-  5. Exit
-
-- [x] 4.12 **Step 20 -- Data mode output (AC: 6):**
-  Parse and analyze the same as Steps 1-4, then output structured key-value pairs:
-  ```
-  active_sprint_id = {{active_sprint_id}}
-  active_sprint_name = {{active_sprint_name}}
-  next_workflow_id = {{next_workflow_id}}
-  next_story_id = {{next_story_id}}
-  count_backlog = {{count_backlog}}
-  count_ready = {{count_ready}}
-  count_in_progress = {{count_in_progress}}
-  count_review = {{count_review}}
-  count_done = {{count_done}}
-  count_on_hold = {{count_on_hold}}
-  capacity_used = {{capacity_used}}
-  capacity_total = {{capacity_total}}
-  capacity_pct = {{capacity_pct}}
-  backlog_total = {{backlog_total}}
-  backlog_bugs = {{backlog_bugs}}
-  backlog_critical_bugs = {{backlog_critical_bugs}}
-  epic_summary = {{epic_summary}}
-  risks = {{risks}}
-  ```
-  Note: `count_backlog`, `count_ready`, `count_in_progress`, `count_review`, `count_done`, `next_workflow_id`, `next_story_id`, and `risks` are backward-compatible with the existing data mode output from the built-in. The additional keys (`active_sprint_id`, `capacity_*`, `backlog_*`, `epic_summary`, `count_on_hold`) are new extensions that do not break existing consumers.
-
-- [x] 4.13 **Step 30 -- Validate mode (AC: 7):**
-  Check `sprint-status.yaml` against the unified schema:
-  - File exists
-  - Required metadata fields present: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
-  - Three data sections present: `epics` (map or empty map), `backlog` (array or empty array), `sprints` (map or empty map)
-  - All epic status values are valid: `backlog`, `in-progress`, `done`, `on-hold`, `cancelled`
-  - All item status values are valid: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`, `on-hold`, `cancelled`
-  - All sprint status values are valid: `planning`, `active`, `closed`
-  - At most one sprint has `status: active`
-  - Spot check single-location invariant: sample up to 5 item IDs and verify each appears in exactly one location
-  Return `is_valid`, `error`, `suggestion` keys. If validation passes: `is_valid = true`, `message = "sprint-status.yaml valid: unified schema structure verified"`.
-
-### Task 5: Implement the IDE skill SKILL.md content (AC: 2, 3, 4, 5, 6, 7, 9, 10)
-
-- [x] 5.1 Write `skills/bmad-sprint-status/SKILL.md` implementing the same analysis logic as the workflow (Task 4), but authored as a standalone skill instruction (not wrapped in `<workflow>` XML tags, not referencing `./workflow.md`). The content should:
-  - Load and parse `sprint-status.yaml` from `_bmad-output/implementation-artifacts/sprint-status.yaml` (direct path resolution, no BMAD config dependency)
-  - Support the same three modes: interactive (default), data, validate
-  - Compute the same health metrics, risk flags, epic progress, and recommendations
-  - Render the same summary format
-  - Include the interactive action menu
-  - Include a note that this is a READ-ONLY skill -- no writes to any file
-
-- [x] 5.2 Ensure the SKILL.md does not include any hardcoded frontmatter -- the installer will strip existing frontmatter and inject fresh frontmatter from `skill.json`.
-
-### Task 6: Remove legacy parsing and validate clean separation from sprint-status-view (AC: 9, 10)
-
-- [x] 6.1 Confirm neither the IDE SKILL.md nor the BMAD extension workflow.md contains any instruction to parse the flat `development_status` map
-- [x] 6.2 Confirm neither file reads `sprint-plan-*.yaml`, `backlog.yaml`, or scans `bug-*.md` frontmatter for status data
-- [x] 6.3 Confirm the only data source is `sprint-status.yaml` (plus `done/` folder for epic done counts)
-- [x] 6.4 Confirm neither file writes to `sprint-status.yaml` or any other file (read-only invariant)
-- [x] 6.5 Confirm legacy status mappings are removed: no "drafted" -> "ready-for-dev", no "contexted" -> "in-progress"
-- [x] 6.6 Confirm `bmad-sprint-status` does NOT render full item tables (that is `sprint-status-view`'s job) -- it shows only counts and specific risk-flagged items by ID
-- [x] 6.7 Confirm `bmad-sprint-status` DOES compute risk flags and recommendations (that is NOT `sprint-status-view`'s job -- 17.13 does alerts but not recommendations)
-
-### Task 7: Deployment verification (AC: 1, 8)
-
-- [x] 7.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer
-- [x] 7.2 Verify the IDE skill appears in the installed MANIFEST.yaml for at least one agent (e.g., check `.claude/skills/MANIFEST.yaml` includes `bmad-sprint-status` with the updated description)
-- [x] 7.3 Diff the installed IDE copy (e.g., `.claude/skills/bmad-sprint-status/SKILL.md`) against the source (`skills/bmad-sprint-status/SKILL.md`) -- the content should match after accounting for frontmatter injection by the installer
-- [x] 7.4 Verify the BMAD extension override exists at `_bmad/extensions/ma-agents-skills/skills/bmad-sprint-status/SKILL.md` after a BMAD install
-- [x] 7.5 Verify the BMAD extension override's `workflow.md` exists at `_bmad/extensions/ma-agents-skills/skills/bmad-sprint-status/workflow.md`
-- [x] 7.6 Confirm the installed BMAD copy does NOT contain the old `development_status` parsing logic (override successfully replaced the built-in)
-- [x] 7.7 Verify `bmad-sprint-status` appears in the BMAD module help output with the updated description
-
-## Dev Notes
-
-### CRITICAL: Extension Override of a Built-in Skill
-
-This story creates an **extension override** for the BMAD built-in `bmad-sprint-status` skill. The override mechanism works as follows:
-
-1. The built-in lives at `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/` (SKILL.md + workflow.md)
-2. The extension override lives at `lib/bmad-extension/skills/bmad-sprint-status/` (SKILL.md + workflow.md + bmad-skill-manifest.yaml)
-3. During BMAD deployment (`lib/bmad.js` with `--custom-content`), the extension module's skill folder takes precedence over the built-in -- the entire folder is replaced
-4. The override MUST provide ALL files that the built-in provides (SKILL.md and workflow.md) so no built-in file leaks through
-
-**Never modify the built-in at `node_modules/bmad-method/`.** That is an upstream package managed by the bmad-method maintainers.
-
-### Two Deployment Pipelines
-
-#### Pipeline 1: IDE Skills (all IDE agents)
-- **Source location:** `skills/bmad-sprint-status/skill.json` + `skills/bmad-sprint-status/SKILL.md` (NEW -- create both)
-- **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.
-
-#### Pipeline 2: BMAD Extension Override (BMAD agents only)
-- **Source location:** `lib/bmad-extension/skills/bmad-sprint-status/SKILL.md` + `workflow.md` + `bmad-skill-manifest.yaml` (NEW -- create all three)
-- **Deployed by:** `lib/bmad.js` which copies `lib/bmad-extension/` to `_bmad/extensions/ma-agents-skills/`
-- **Override behavior:** The extension skill folder with the same name as a built-in skill replaces the built-in during BMAD agent compilation
-- **Registered in:** `lib/bmad-extension/module-help.csv` (maps skill to `bmm-sm` agent)
-
-#### 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
-- `.claude/skills/bmad-sprint-status/` currently contains the BMAD built-in copy -- this will be replaced by the IDE skill on next install
-
-### Relationship to sprint-status-view (Story 17.13) -- BOTH Are Needed
-
-After agent discussion, the decision is that **both skills are needed** and serve complementary purposes:
-
-| Aspect | `bmad-sprint-status` (this story) | `sprint-status-view` (17.13) |
-|--------|-----------------------------------|------------------------------|
-| **Purpose** | Analysis and recommendations | Display and navigation |
-| **Output style** | Concise health metrics, risk flags, one recommended next action | Full formatted tables of all items, capacity bars, interactive drill-down |
-| **Item rendering** | Counts by status; individual items mentioned only when flagged as risks | Every item listed in Markdown tables with all fields |
-| **Risk analysis** | Computes 10 risk conditions with specific actionable messages | Shows 3 alert conditions (over-capacity, stale, empty sprint) |
-| **Recommendations** | Priority-based next-action recommendation (dev-story, code-review, etc.) | No recommendations -- offers navigation menu instead |
-| **Modes** | interactive / data / validate | Display only (no data or validate mode) |
-| **Epic progress** | Done/total counts including `done/` archive scan | Active item counts only (no done folder scan) |
-| **LLM optimization** | Optimized for LLM context consumption (concise, structured) | Optimized for human reading (visual formatting, tables) |
-
-**Key non-overlap guarantees:**
-- `bmad-sprint-status` does NOT render full item tables
-- `sprint-status-view` does NOT compute risk flags or action recommendations
-- `bmad-sprint-status` menu option 3 suggests running `/sprint-status-view` for detailed tables (cross-skill handoff)
-
-### What This Story Changes vs Current Behavior
-
-**Current state (built-in, pre-Epic-17):** The `bmad-sprint-status` workflow parses the flat `development_status` map:
-- Classifies keys by pattern: `epic-*` = epic, `*-retrospective` = retrospective, everything else = story
-- Counts statuses across ALL stories globally (no sprint concept)
-- Maps legacy statuses ("drafted" -> "ready-for-dev", "contexted" -> "in-progress")
-- Has no capacity tracking, no sprint-scoped analysis, no backlog/sprint distinction
-- Detects 6 risk conditions (review items, no ready-for-dev, stale file, orphaned stories, empty epics)
-- Recommends next workflow using priority logic (in-progress > review > ready-for-dev > backlog > retrospective)
-
-**New behavior (unified schema, this story):** After the extension override:
-- Reads structured `epics`, `backlog`, and `sprints` sections directly
-- Identifies the active sprint and scopes status analysis to it
-- Calculates capacity usage (`items.length / capacity`)
-- Epic progress includes `done/` folder scanning for accurate totals
-- Detects 10 risk conditions including staleness per item, over-capacity, critical bugs, no-active-sprint
-- Backlog health section (total, bugs, critical bugs) is new
-- Sprint history section (closed sprint summaries) is new
-- Legacy status mappings removed (unified schema uses canonical statuses)
-- Data mode output is backward-compatible with new extensions
-- Validate mode checks unified schema structure (not flat `development_status`)
-
-### Unified Schema Sections Read
-
-- **`epics`** -- read for epic status and progress calculation (read-only)
-- **`backlog`** -- read for backlog health metrics and item counts contributing to epic progress (read-only)
-- **`sprints`** -- read for active sprint identification, item status counts, capacity usage, sprint history (read-only)
-- **Metadata** -- `project`, `project_key`, `tracking_system`, `last_updated` used in header and staleness detection
-- **`done/` folder** -- scanned for archived files to compute epic done counts (read-only, file system)
-- This skill is **read-only** -- it never writes to `sprint-status.yaml` or any other file
-
-### Reference Files
-
-- **Schema:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (canonical schema for sprint-status.yaml)
-- **Sprint status:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
-- **Current built-in SKILL.md:** `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/SKILL.md` (to be overridden, not modified)
-- **Current built-in workflow:** `node_modules/bmad-method/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md` (to be overridden, not modified)
-- **BMAD extension manifest:** `lib/bmad-extension/skills/bmad-sprint-status/bmad-skill-manifest.yaml` (NEW)
-- **Module help CSV:** `lib/bmad-extension/module-help.csv` (new row)
-- **IDE skill reference:** `skills/story-status-lookup/skill.json` + `skills/story-status-lookup/SKILL.md`
-- **BMAD skill reference:** `lib/bmad-extension/skills/add-to-sprint/` (SKILL.md + bmad-skill-manifest.yaml)
-- **Related story (display counterpart):** `_bmad-output/implementation-artifacts/17-13-rework-sprint-status-view.md`
-- **Story 17.15 (override pattern reference):** `_bmad-output/implementation-artifacts/17-15-rework-bmad-sprint-planning.md`
-
-### Cross-References
-
-- **Story 17.9** (prerequisite): Defines the unified `sprint-status.yaml` schema this skill reads from -- three sections (epics, backlog, sprints) with consistent item structure
-- **Story 17.15** (prerequisite): `bmad-sprint-planning` bootstraps the file; this skill relies on the file existing and being well-formed. Also the reference for how to create a BMAD built-in extension override (same pattern used here).
-- **Story 17.13** (complementary): `sprint-status-view` is the display-focused counterpart; this skill is the analysis-focused variant. No functional duplication -- see comparison table above.
-- **Story 17.10** (upstream): `generate-backlog` populates the backlog section this skill analyzes
-- **Story 17.16** (upstream): `add-sprint` creates sprint entries this skill analyzes
-- **Story 17.11** (upstream): `add-to-sprint` moves items into sprints; this skill reads the result
-- **Story 17.14** (related): `cleanup-done` removes archived items from the file and moves files to `done/`; this skill scans `done/` for epic progress counts
-- **Story 17.18** (related): `bmad-dev-story` updates item statuses that this skill reads for health analysis
-- **Story 17.19** (related): `story-status-lookup` is single-item lookup; this skill is full-sprint health analysis
-- **Story 17.21** (related): `close-sprint` transitions sprints to closed; this skill reports closed sprint history
-- **Story 17.23** (related): Migration story removes the old `development_status` section; after migration, this skill's validate mode should no longer encounter the old format
-
-### PRD Traceability
-
-- **FR65:** All sprint, backlog, and epic status data is managed in a single `sprint-status.yaml` file -- this skill reads that single file exclusively for all health metrics
-- **FR71:** Sprint status displays unified `sprint-status.yaml` contents -- this skill provides the analysis layer (health metrics, risks) while sprint-status-view (17.13) provides the display layer
-- **FR130:** Done items are removed from `sprint-status.yaml` -- this skill accounts for done items via `done/` folder scanning for epic progress totals
-- **FR133:** `sprint-status.yaml` includes top-level metadata (generated, last_updated, project, etc.) -- used in the header and for staleness detection
-- **FR134:** Each item carries consistent structure (id, type, epic, title, priority, status, severity) -- used for risk flag computation and status counting
-- **FR135:** Each sprint entity carries: name, status, capacity, optional start/end dates, and items list -- used for capacity analysis and staleness computation
-- **FR66:** Sprint capacity is defined by number of items -- used for over-capacity risk detection
-- **NFR19:** Sprint extension workflows must read/write the unified `sprint-status.yaml` file -- this skill reads only that file (plus `done/` folder), no secondary sources
-
-### Architecture Reference
-
-- Architecture Decision P2-11 in `_bmad-output/planning-artifacts/architecture.md`
-- Skill Integration Map entry: `bmad-sprint-status | 17.20 | Reads structured sections for summary | All sections (read-only) | Light`
-- Architecture note on skill ownership: `bmad-sprint-status` is listed as one of 7 existing BMAD/ma-agents skills being reworked (not one of the 6 extension-only skills)
-
----
-
-## Dev Agent Record
-
-### Session Log
-
-| Date | Agent | Task | Notes |
-|------|-------|------|-------|
-| 2026-04-06 | claude-sonnet-4-6 | Full story implementation | Created all source files for BMAD extension override and IDE skill. Registered in module-help.csv. |
-
-### Implementation Notes
-
-- BMAD extension override at `lib/bmad-extension/skills/bmad-sprint-status/` provides complete replacement of the built-in (SKILL.md + workflow.md + bmad-skill-manifest.yaml).
-- IDE skill at `skills/bmad-sprint-status/` (SKILL.md + skill.json) is self-contained with direct path resolution.
-- `workflow.md` uses the same `<workflow>` XML tag structure as other BMAD extension skills (add-to-sprint, sprint-status-view, etc.).
-- Task 7 (deployment verification) requires running the ma-agents installer — deferred to integration testing.
-
----
-
-## File List
-
-### Created
-
-- `lib/bmad-extension/skills/bmad-sprint-status/bmad-skill-manifest.yaml` — BMAD manifest (type, name, module)
-- `lib/bmad-extension/skills/bmad-sprint-status/SKILL.md` — BMAD extension skill entry point (delegates to workflow.md)
-- `lib/bmad-extension/skills/bmad-sprint-status/workflow.md` — Full BMAD workflow with unified schema parsing, risk detection, and three modes
-- `skills/bmad-sprint-status/skill.json` — IDE skill metadata
-- `skills/bmad-sprint-status/SKILL.md` — IDE skill: standalone implementation (no workflow.md dependency)
-
-### Modified
-
-- `lib/bmad-extension/module-help.csv` — Added Sprint Status Health row (bmad-sprint-status, bmm-sm agent)
-- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Story 17-20 status: ready-for-dev → review; last_updated: 2026-04-06
-- `_bmad-output/implementation-artifacts/17-20-rework-bmad-sprint-status.md` — Status: review; all tasks checked; this section added
-
----
-
-## Change Log
-
-| Version | Date | Author | Change |
-|---------|------|--------|--------|
-| 1.0.0 | 2026-04-06 | claude-sonnet-4-6 | Initial implementation — BMAD extension override and IDE skill for unified sprint-status.yaml schema |