ma-agents 3.4.9 → 3.5.0

package/skills/bmad-sprint-planning/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: bmad-sprint-planning
+description: 'Bootstrap or update the unified sprint-status.yaml from epics. Creates the file with three sections (epics, backlog, sprints) on first run; refreshes epics and adds new items on subsequent runs.'
+---
+
+# Sprint Planning Skill
+
+**Goal:** Bootstrap or refresh the unified `sprint-status.yaml` from epics, building a complete three-section file (`epics`, `backlog`, `sprints`).
+
+**Your Role:** You are a Scrum Master bootstrapping or refreshing sprint tracking. Parse epic files, scan bugs, detect story statuses, and produce or update a structured `sprint-status.yaml` with the unified schema.
+
+---
+
+## INITIALIZATION
+
+### Path Resolution
+
+Resolve project root as the directory containing `_bmad-output/`. Then set:
+
+- `implementation_artifacts` = `_bmad-output/implementation-artifacts`
+- `planning_artifacts` = `_bmad-output/planning-artifacts`
+- `status_file` = `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- `done_folder` = `_bmad-output/implementation-artifacts/done/`
+- `story_location` = `_bmad-output/implementation-artifacts`
+
+Attempt to read project name from `_bmad/bmm/config.yaml` (field `project_name`). If the file does not exist or `project_name` is absent, derive project name from the root directory name or use `"Unknown Project"`.
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+
+**Epic Discovery Process:**
+
+1. Search for whole document first — look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file in `_bmad-output/planning-artifacts/`
+2. If whole document not found, look for `_bmad-output/planning-artifacts/epics/index.md` (sharded version)
+3. If sharded version found: read `index.md` then read ALL referenced epic section files
+4. If both exist, use the whole document
+
+<action>For each epic file found, extract:</action>
+
+- Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
+- Story IDs and titles from patterns like `### Story 1.1: User Authentication`
+- Epic status cues from narrative text:
+  - "in progress", "started", "active" → `in-progress`
+  - "on hold", "paused", "blocked" → `on-hold`
+  - "cancelled", "dropped" → `cancelled`
+  - default → `backlog`
+
+**Story ID Conversion Rules:**
+
+- Original: `### Story 1.1: User Authentication`
+- Replace period with dash: `1-1`
+- Convert title to kebab-case: `user-authentication`
+- Final ID: `1-1-user-authentication`
+
+<action>Build:
+  - `{{all_epics}}` — list of epic objects: `epic_num`, `title`, `detected_status`
+  - `{{all_stories}}` — list of story objects: `id`, `epic_num`, `title`
+</action>
+</step>
+
+<step n="2" goal="Scan bug files">
+<action>Glob `_bmad-output/implementation-artifacts/bug-*.md` to find all bug story files</action>
+<check if="no bug files found">
+  <action>Set `{{all_bugs}}` = []</action>
+</check>
+<check if="bug files found">
+  <action>For each bug file, parse YAML frontmatter to extract: `title`, `severity`, `status`</action>
+  <action>Derive bug ID: strip `bug-` prefix and `.md` extension, then prefix with `BUG-` (e.g., `bug-path-spaces.md` → `BUG-path-spaces`)</action>
+  <action>Set `{{all_bugs}}` = list of bug objects: `id`, `title`, `severity` (default `medium`), `status` (default `backlog`)</action>
+</check>
+</step>
+
+<step n="3" goal="Mode detection — bootstrap vs refresh">
+<check if="`_bmad-output/implementation-artifacts/sprint-status.yaml` does NOT exist">
+  <action>Set `{{mode}}` = `bootstrap`</action>
+  <action>Proceed to Step 4 then Step 5</action>
+</check>
+<check if="`_bmad-output/implementation-artifacts/sprint-status.yaml` EXISTS">
+  <action>Set `{{mode}}` = `refresh`</action>
+  <action>Read existing file into `{{existing_file}}`</action>
+  <action>Proceed to Step 4 then Step 6</action>
+</check>
+</step>
+
+<step n="4" goal="Done exclusion scan">
+<action>Scan `_bmad-output/implementation-artifacts/done/` for archived files. Build `{{done_item_ids}}` = set of basenames (without `.md`) from all files in the done folder</action>
+<check if="`{{mode}}` == `refresh`">
+  <action>Scan `{{existing_file}}` for items with `status: done` in `backlog` or any `sprints[*].items`</action>
+  <check if="any done items found in backlog or sprints">
+    <output>
+## Warning: Done Items Detected in Active File
+
+The following items have `status: done` but are still present in the active `sprint-status.yaml`:
+
+{{#each done_items_in_file}}
+- `{{id}}` (in: {{location}})
+{{/each}}
+
+These items should be archived before adding new items. Consider running `cleanup-done` to archive them first.
+
+Continuing with planning — done items will be excluded from new additions.
+    </output>
+    <action>Add these IDs to `{{done_item_ids}}`</action>
+  </check>
+</check>
+</step>
+
+<step n="5" goal="Bootstrap mode — build complete file from scratch">
+<check if="`{{mode}}` != `bootstrap`">
+  <action>Skip this step</action>
+</check>
+
+**Build metadata:**
+- `generated` = current ISO-8601 datetime
+- `last_updated` = current ISO-8601 datetime
+- `project` = resolved project name
+- `project_key` = `NOKEY`
+- `tracking_system` = `file-system`
+- `story_location` = `_bmad-output/implementation-artifacts`
+
+**Build `epics` section:**
+<action>For each epic in `{{all_epics}}`:
+  - Key: `epic-{epic_num}`
+  - `status`: use detected status from epic narrative, default `backlog`
+  - `retrospective`: `optional`
+</action>
+
+**Build `backlog` section:**
+<action>Combine `{{all_stories}}` and `{{all_bugs}}` into candidate list, excluding any IDs in `{{done_item_ids}}`</action>
+<action>For each story candidate:
+  - Detect status: check if `_bmad-output/implementation-artifacts/{story_id}.md` exists → `ready-for-dev`; else → `backlog`
+</action>
+
+**Ordering rules for initial priority:**
+1. Bugs with `severity: critical` — first (highest priority)
+2. Stories in epic order, then story number within each epic
+3. Remaining bugs (`high`, `medium`, `low`) — after stories
+
+<action>Assign sequential `priority` values (1, 2, 3...) based on ordering</action>
+
+**Build each backlog item:**
+```
+id:       story ID (e.g., "1-1-user-auth") or bug ID (e.g., "BUG-path-spaces")
+type:     "story" or "bug"
+epic:     epic number as integer for stories, null for bugs
+title:    story/bug title
+priority: sequential integer (1 = highest)
+status:   detected status for stories; "backlog" for bugs (or from frontmatter)
+severity: null for stories; value for bugs
+```
+
+**`sprints` section:** empty map `{}`
+
+<action>Write complete `sprint-status.yaml` to `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+</step>
+
+<step n="6" goal="Refresh mode — additive merge">
+<check if="`{{mode}}` != `refresh`">
+  <action>Skip this step</action>
+</check>
+
+<action>From `{{existing_file}}` extract:
+  - `generated` timestamp (preserve — never change)
+  - existing `epics` map
+  - existing `backlog` array
+  - existing `sprints` map
+</action>
+
+**Regenerate `epics` section with status preservation:**
+<action>For each epic in `{{all_epics}}`:
+  - If epic already exists in existing file: apply never-downgrade rule for `status`; preserve existing `retrospective`
+  - If epic is NEW: use detected status (default `backlog`), `retrospective: optional`
+</action>
+
+**Never-downgrade status rules:**
+- `done` → keep `done` (no downgrade)
+- `in-progress` + detected `backlog` → keep `in-progress`
+- `on-hold` → keep `on-hold` (sticky)
+- `cancelled` → keep `cancelled` (terminal)
+- Otherwise → use detected status
+
+**Build exclusion sets:**
+- `{{existing_backlog_ids}}` = all `id` values in existing `backlog` array
+- `{{sprint_item_ids}}` = all `id` values in any `sprints[*].items` arrays
+- `{{excluded_ids}}` = union of above + `{{done_item_ids}}`
+
+**Find new items to append:**
+<action>From `{{all_stories}}` and `{{all_bugs}}`, identify items whose ID is NOT in `{{excluded_ids}}`</action>
+
+**Append new items:**
+<action>Calculate `{{max_priority}}` = max `priority` in existing backlog (0 if empty)</action>
+<action>For each new item (stories in epic order first, then bugs):
+  - `priority` = `{{max_priority}}` + sequential increment
+  - For stories: detect status from file existence
+  - For bugs: use frontmatter status or default `backlog`
+</action>
+
+**Final file:**
+- `backlog` = existing items (unchanged) + new items (appended)
+- `sprints` = existing sprints (unchanged — pass through exactly)
+- `epics` = regenerated (with preservation)
+- `last_updated` = current ISO-8601 datetime
+- `generated` = original value (NEVER change)
+
+<action>Write updated file (atomic read-modify-write)</action>
+</step>
+
+<step n="7" goal="Validation">
+<action>Validate the written file:</action>
+
+- [ ] File is valid YAML syntax
+- [ ] 6 metadata fields present: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
+- [ ] 3 data sections: `epics`, `backlog`, `sprints`
+- [ ] No `development_status` section (old flat format must not appear)
+- [ ] Every epic in source files appears in `epics` section
+- [ ] Every story appears in exactly one location (backlog, sprint, or done/)
+- [ ] No item ID in more than one active location (single-location invariant)
+- [ ] All `status` values are legal (epic: backlog/in-progress/done/on-hold/cancelled; item: backlog/ready-for-dev/in-progress/review/done/on-hold/cancelled)
+- [ ] Backlog `priority` values are sequential 1..N
+- [ ] `sprints` section unchanged (refresh mode)
+- [ ] `generated` timestamp unchanged (refresh mode)
+
+<check if="validation errors found">
+  <output>
+## Validation Errors
+
+{{#each validation_errors}}
+- {{message}}
+{{/each}}
+
+Please review `_bmad-output/implementation-artifacts/sprint-status.yaml` and correct the issues.
+  </output>
+</check>
+</step>
+
+<step n="8" goal="Report summary">
+<output>
+## Sprint Planning Complete
+
+**Mode:** {{mode}} ({{#if bootstrap}}first run — file created{{else}}refresh — file updated{{/if}})
+**File:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
+
+### Summary
+
+| Section | Count |
+|---------|-------|
+| Total epics | {{epic_count}} |
+| Total stories | {{story_count}} |
+| Total bugs | {{bug_count}} |
+{{#if refresh}}
+| New items added | {{new_items_count}} |
+| Items preserved (backlog) | {{preserved_backlog_count}} |
+| Items excluded (sprint-assigned) | {{sprint_assigned_count}} |
+| Items excluded (done-archived) | {{done_archived_count}} |
+{{/if}}
+
+### Epic Status Overview
+
+| Epic | Title | Status |
+|------|-------|--------|
+{{#each epics_summary}}
+| `{{id}}` | {{title}} | {{status}} |
+{{/each}}
+
+### Next Steps
+
+1. Review the generated `_bmad-output/implementation-artifacts/sprint-status.yaml`
+2. Run `generate-backlog` to refresh and reprioritize backlog items
+3. Run `add-sprint` to create a sprint for the next iteration
+4. Run `add-to-sprint` to assign backlog items to a sprint
+</output>
+</step>
+
+</workflow>
+
+---
+
+## Additional Documentation
+
+### Status State Machines
+
+**Epic Status Flow:**
+```
+backlog → in-progress → done
+              ↕
+           on-hold
+
+Any non-done → cancelled (terminal)
+```
+
+**Story/Bug Status Flow:**
+```
+backlog → ready-for-dev → in-progress → review → done
+               ↕              ↕           ↕
+            on-hold        on-hold      on-hold
+
+Any non-done → cancelled (terminal)
+```
+
+### Three-Section Schema Summary
+
+```yaml
+epics:        # Map keyed by epic-N — regenerated each run with preservation
+backlog:      # Array of items — additive only (new items appended, existing preserved)
+sprints:      # Map keyed by sprint-N — NEVER modified by this skill
+```
+
+### Never-Downgrade Rule
+
+Status is never downgraded on refresh. If the existing file says `in-progress`, a re-detected `backlog` from the epic file does NOT override it. This ensures human-set statuses are preserved across planning runs.
+
+### Schema Quick Reference
+
+**Backlog item fields:** `id`, `type`, `epic`, `title`, `priority`, `status`, `severity`
+**Sprint item fields:** `id`, `type`, `epic`, `title`, `status`, `severity` (no `priority`)
+**Epic fields:** `status`, `retrospective`

package/skills/bmad-sprint-planning/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "bmad-sprint-planning",
+  "version": "1.0.0",
+  "description": "Bootstrap or update the unified sprint-status.yaml from epics. Creates the file with three sections (epics, backlog, sprints) on first run; refreshes epics and adds new items on subsequent runs.",
+  "category": "workflow",
+  "tags": ["sprint-planning", "sprint-management", "epics", "bootstrap"]
+}

package/skills/bmad-sprint-status/SKILL.md

@@ -0,0 +1,273 @@
+# bmad-sprint-status
+
+Analyze sprint health, surface risk flags, and recommend next actions from the unified `sprint-status.yaml`.
+
+**READ-ONLY:** This skill NEVER writes to `sprint-status.yaml` or any other file.
+
+**Path resolution:** This skill resolves paths directly from the project structure. The sprint status file is at `_bmad-output/implementation-artifacts/sprint-status.yaml` relative to the project root. The done folder is at `_bmad-output/implementation-artifacts/done/`.
+
+---
+
+## Invocation Modes
+
+This skill supports three execution modes. Set `mode` before invoking:
+
+- `mode = interactive` (default) — full health summary with risk flags and interactive action menu
+- `mode = data` — structured key-value output for consumption by other skills/workflows
+- `mode = validate` — schema validation of sprint-status.yaml against the unified schema
+
+---
+
+## Step 0: Determine Execution Mode
+
+Set `mode` = value provided by caller; if not provided, default to `"interactive"`.
+
+- If `mode == "data"` → skip to Step 20
+- If `mode == "validate"` → skip to Step 30
+- If `mode == "interactive"` → continue to Step 1
+
+---
+
+## Step 1: Locate and Load sprint-status.yaml
+
+1. Try to read `_bmad-output/implementation-artifacts/sprint-status.yaml` from the project root.
+2. If file not found: output `"No sprint-status.yaml found. Run /bmad-sprint-planning to initialize."` and stop.
+3. Parse YAML — extract:
+   - Metadata fields: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
+   - Three data sections: `epics` (map), `backlog` (array), `sprints` (map)
+
+---
+
+## Step 2: Analyze Active Sprint Health
+
+1. Scan the `sprints` map for the entry with `status: active`.
+2. If no active sprint found: set `active_sprint = null` and skip to Step 2b.
+3. If active sprint found, store it and compute:
+   - `items_by_status`: count items in `active_sprint.items` grouped by `status` field
+   - `capacity_used` = length of `active_sprint.items` array
+   - `capacity_total` = `active_sprint.capacity`
+   - `capacity_pct` = `round((capacity_used / capacity_total) * 100)` if `capacity_total > 0`, else `0`
+   - If `active_sprint.start` is populated: `sprint_age_days` = days between `active_sprint.start` and today
+
+---
+
+## Step 2b: Analyze Backlog Health
+
+1. `backlog_total` = length of `backlog` array
+2. `backlog_bugs` = count of backlog items where `type == "bug"`
+3. `backlog_stories` = `backlog_total - backlog_bugs`
+4. `backlog_critical_bugs` = count of backlog bugs where `severity == "critical"` or `severity == "high"`
+
+---
+
+## Step 2c: Compute Epic Progress
+
+For each epic key in the `epics` map:
+
+1. `epic_number` = numeric portion of key (e.g., `"epic-17"` → `17`)
+2. `active_count` = count of items across `backlog` array AND all `sprints[*].items` arrays where `item.epic == epic_number`
+3. `done_count` = count of files in `_bmad-output/implementation-artifacts/done/` whose filename starts with `"{epic_number}-"` (e.g., `"17-*.md"`)
+4. `total_count` = `done_count + active_count`
+5. Store: `{epic_key, status, retrospective, done_count, active_count, total_count}`
+
+---
+
+## Step 2d: Compute Sprint History
+
+1. `closed_sprints` = all sprint entries where `status == "closed"`
+2. `closed_count` = length of `closed_sprints`
+3. For each closed sprint: capture `name`, item count (length of `items` array), `start`, `end`
+
+---
+
+## Step 3: Detect Risk Flags
+
+Initialize `risks = []` (empty list). Check each risk condition and append messages as applicable:
+
+**Risk: No active sprint**
+- If `active_sprint == null`: append `"No active sprint — consider running /add-sprint to create one or activating a planning sprint"`
+
+**Risk: Stale in-progress items** (sprint has been running for more than 14 days)
+- If `active_sprint` exists AND `sprint_age_days > 14`: for each item in `active_sprint.items` with `status == "in-progress"`:
+  append `"Item {item.id} has been in-progress for {sprint_age_days} days (sprint started {active_sprint.start})"`
+
+**Risk: Items not started**
+- If `active_sprint` exists: count items where `status == "ready-for-dev"` or `status == "backlog"` → `not_started_count`
+- If `not_started_count > 0`: append `"{not_started_count} of {capacity_used} items still in ready-for-dev status — not yet started"`
+
+**Risk: Over-capacity**
+- If `active_sprint` exists AND `capacity_total > 0` AND `capacity_used > capacity_total`:
+  `overage = capacity_used - capacity_total`
+  append `"Sprint over capacity: {capacity_used}/{capacity_total} items ({overage} over limit)"`
+
+**Risk: At capacity with unstarted items**
+- If `active_sprint` exists AND `capacity_total > 0` AND `capacity_used >= capacity_total` AND `not_started_count > 0`:
+  append `"Sprint at {capacity_pct}% capacity ({capacity_used}/{capacity_total}) with {not_started_count} items still in ready-for-dev"`
+
+**Risk: No progress toward completion** (only flag if sprint is at least 3 days old)
+- If `active_sprint` exists AND `sprint_age_days >= 3`:
+  `review_or_done_count` = count of items where `status == "review"` or `status == "done"`
+  If `review_or_done_count == 0`: append `"No items in review or done — sprint may be at risk (sprint is {sprint_age_days} days old)"`
+
+**Risk: On-hold or cancelled items in active sprint**
+- If `active_sprint` exists: for each item where `status == "on-hold"` or `status == "cancelled"`:
+  append `"1 item {item.status}: {item.id}"`
+
+**Risk: Stale sprint-status.yaml file**
+- `staleness_date` = `last_updated` if present, else `generated`
+- `file_age_days` = days between `staleness_date` and today
+- If `file_age_days > 7`: append `"\`last_updated\` is {file_age_days} days old — sprint-status.yaml may be stale"`
+
+**Risk: Orphaned stories** (item references epic not in epics section)
+- For each item in `backlog` array AND each item in all `sprints[*].items` arrays:
+  If `item.epic` is not null AND `"epic-{item.epic}"` does not exist in `epics` map:
+  append `"Orphaned story detected: item {item.id} references epic-{item.epic} which is not in the epics section"`
+
+**Risk: In-progress epic with no stories**
+- For each epic in `epics` map where `epic.status == "in-progress"`:
+  If `active_count == 0` AND `done_count == 0`:
+  append `"In-progress epic {epic_key} has no associated stories"`
+
+**Risk: Critical/high bugs in backlog**
+- For each item in `backlog` array where `type == "bug"` AND (`severity == "critical"` or `severity == "high"`):
+  append `"Critical/high severity bug in backlog: {item.id} ({item.severity})"`
+
+---
+
+## Step 4: Select Next Action Recommendation
+
+Priority order (highest to lowest). When selecting "first" item: prefer active sprint items over backlog items; within each group, sort by epic number then story number.
+
+1. If any item in `active_sprint.items` has `status == "in-progress"` → `next_workflow_id = "dev-story"`, `next_story_id` = first such item's id
+2. Else if any item in `active_sprint.items` has `status == "review"` → `next_workflow_id = "code-review"`, `next_story_id` = first such item's id
+3. Else if any item in `active_sprint.items` OR `backlog` has `status == "ready-for-dev"` → `next_workflow_id = "dev-story"`, `next_story_id` = first such item's id
+4. Else if any item in `backlog` has `status == "backlog"` → `next_workflow_id = "create-story"`, `next_story_id` = first such item's id
+5. Else if any epic has `retrospective == "optional"` AND `status == "done"` → `next_workflow_id = "retrospective"`, `next_story_id` = that epic's key
+6. Else → `next_workflow_id = null`, `next_story_id = null` (all work complete)
+
+---
+
+## Step 5: Display Interactive Health Summary
+
+Output this health summary (replace all `{{...}}` with computed values):
+
+```
+## Sprint Health Summary
+
+- Project: {{project}} ({{project_key}})
+- Tracking: {{tracking_system}}
+- Last updated: {{last_updated}}
+
+### Active Sprint: {{active_sprint.name}}
+(If no active sprint: "No active sprint found.")
+**Capacity:** {{capacity_used}} / {{capacity_total}} ({{capacity_pct}}%)
+**Dates:** {{active_sprint.start}} to {{active_sprint.end}}
+**Items by status:** in-progress {{n}}, review {{n}}, ready-for-dev {{n}}, backlog {{n}}, on-hold {{n}}
+
+### Risk Flags
+- {{risk_1}}
+- {{risk_2}}
+(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
+- {{epic_key}} ({{status}}): {{done_count}}/{{total_count}} done
+(one line per epic)
+
+### Sprint History
+- {{closed_count}} closed sprint(s)
+- {{sprint_name}}: {{item_count}} items, {{start}} to {{end}}
+(one line per closed sprint)
+
+### Next Recommendation
+/{{next_workflow_id}} ({{next_story_id}})
+(or "All work complete — great job!" if no recommendation)
+```
+
+---
+
+## Step 6: Offer Interactive Actions
+
+Present the following menu and handle the user's choice:
+
+```
+Pick an option:
+1) Run recommended workflow now
+2) Show all items grouped by status (active sprint + backlog)
+3) Show detailed sprint view (runs /sprint-status-view)
+4) Show raw sprint-status.yaml
+5) Exit
+Choice:
+```
+
+- **Choice 1:** If `next_workflow_id` is null, output "No workflow to run — all work is complete." Otherwise output: `"Run /{next_workflow_id}. If the command targets a story, set story_key={next_story_id} when prompted."`
+- **Choice 2:** List items grouped by status: in-progress, review, ready-for-dev (sprint), ready-for-dev (backlog), backlog (unassigned). Show `id: title` per item.
+- **Choice 3:** Output: `"For a full formatted table view with all items, run /sprint-status-view."`
+- **Choice 4:** Display the full contents of `sprint-status.yaml`.
+- **Choice 5:** Exit.
+
+---
+
+## Step 20: Data Mode Output
+
+Load and parse sprint-status.yaml (same as Steps 1–2d), detect risks (same as Step 3), compute recommendation (same as Step 4), then output these 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}}
+```
+
+**Count field semantics:**
+- `count_backlog` = items with `status "backlog"` across active sprint items + backlog array
+- `count_ready` = items with `status "ready-for-dev"` across active sprint items + backlog array
+- `count_in_progress` = items with `status "in-progress"` in active sprint
+- `count_review` = items with `status "review"` in active sprint
+- `count_done` = items with `status "done"` in active sprint (does not count `done/` archived items)
+- `count_on_hold` = items with `status "on-hold"` or `"cancelled"` in active sprint
+
+**Backward compatibility:** `count_backlog`, `count_ready`, `count_in_progress`, `count_review`, `count_done`, `next_workflow_id`, `next_story_id`, and `risks` are preserved from the original built-in data mode output. The additional keys (`active_sprint_id`, `active_sprint_name`, `capacity_*`, `backlog_*`, `epic_summary`, `count_on_hold`) are new extensions that do not break existing consumers.
+
+Return output to caller.
+
+---
+
+## Step 30: Validate Mode
+
+Validate `_bmad-output/implementation-artifacts/sprint-status.yaml` against the unified schema. Return `is_valid`, `error`, `suggestion` (or `message`) keys.
+
+1. **File exists?** If not: `is_valid = false`, `error = "sprint-status.yaml missing"`, `suggestion = "Run /bmad-sprint-planning to create it"`
+
+2. **Required metadata fields present?** Check: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`. If any missing: `is_valid = false`, `error = "Missing required metadata field(s): {missing_fields}"`, `suggestion = "Re-run /bmad-sprint-planning or add missing fields manually"`
+
+3. **Three data sections present?** Check: `epics` (map or `{}`), `backlog` (array or `[]`), `sprints` (map or `{}`). If any missing: `is_valid = false`, `error = "Missing data section(s): {missing_sections}. Expected: epics, backlog, sprints"`, `suggestion = "Re-run /bmad-sprint-planning or repair the file manually"`
+
+4. **Valid epic statuses?** Check all epic `status` values against: `backlog`, `in-progress`, `done`, `on-hold`, `cancelled`. If invalid: `is_valid = false`, `error = "Invalid epic status value(s): {invalid_entries}"`, `suggestion = "Valid epic statuses: backlog, in-progress, done, on-hold, cancelled"`
+
+5. **Valid item statuses?** Check all item `status` values (across `backlog` array AND all `sprints[*].items` arrays) against: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`, `on-hold`, `cancelled`. If invalid: `is_valid = false`, `error = "Invalid item status value(s): {invalid_entries}"`, `suggestion = "Valid item statuses: backlog, ready-for-dev, in-progress, review, done, on-hold, cancelled"`
+
+6. **Valid sprint statuses?** Check all sprint `status` values against: `planning`, `active`, `closed`. If invalid: `is_valid = false`, `error = "Invalid sprint status value(s): {invalid_entries}"`, `suggestion = "Valid sprint statuses: planning, active, closed"`
+
+7. **Single active sprint?** Count sprints with `status: active`. If count > 1: `is_valid = false`, `error = "Multiple active sprints detected ({count}). At most one sprint may have status: active."`, `suggestion = "Close or set other active sprints to planning status"`
+
+8. **Single-location invariant (spot check)?** Sample up to 5 item IDs from all locations. Verify each ID appears in exactly one location (either `backlog` array OR one sprint's `items` array, never both). If duplicate: `is_valid = false`, `error = "Single-location invariant violated: item(s) {duplicate_ids} appear in multiple locations"`, `suggestion = "Remove duplicate item entries — each item ID must appear in exactly one location"`
+
+9. **All checks passed:** `is_valid = true`, `message = "sprint-status.yaml valid: unified schema structure verified"`

package/skills/bmad-sprint-status/skill.json

@@ -0,0 +1,7 @@
+{
+  "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"]
+}