ma-agents 3.4.8 → 3.5.0

package/skills/add-to-sprint/SKILL.md

@@ -0,0 +1,231 @@
+# Add-to-Sprint Skill
+
+Guided workflow to move backlog items to a sprint in the unified `sprint-status.yaml` using movement semantics.
+
+**Movement semantics:** Each item exists in exactly one location — either the `backlog` array OR a sprint's `items` array, never both. This skill atomically removes items from `backlog` and appends them to the target sprint's `items` array in a single file write.
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Locate `sprint-status.yaml` at `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+  <check if="file does not exist">
+    <output>❌ No sprint-status.yaml found. Run sprint planning first to initialize the file (e.g., `/bmad-sprint-planning`).</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Read and parse the full file: `epics`, `backlog`, and `sprints` sections plus metadata fields</action>
+  <action>Store the complete parsed document as {{sprint_status}} for atomic write-back later</action>
+</step>
+
+<step n="1" goal="Identify assignable sprints">
+  <action>Parse the `sprints` map from {{sprint_status}}</action>
+  <action>Filter to sprints with `status: planning` or `status: active` — exclude `status: closed` sprints</action>
+  <check if="no assignable sprints remain (all sprints are closed or sprints map is empty)">
+    <output>❌ No assignable sprints found. Run `/add-sprint` first to create a sprint before assigning items.</output>
+    <action>Exit workflow</action>
+  </check>
+  <check if="exactly one assignable sprint">
+    <action>Auto-select it as {{target_sprint}} (skip selection prompt)</action>
+    <output>ℹ️ Auto-selected the only assignable sprint: **{{target_sprint.name}}** ({{target_sprint.status}})</output>
+  </check>
+  <check if="multiple assignable sprints">
+    <action>Build a sprint selection table from the assignable sprints</action>
+    <output>
+## Available Sprints
+
+| # | Sprint | Status | Capacity | Assigned | Remaining |
+|---|--------|--------|----------|----------|-----------|
+{{#each assignable_sprints}}
+| {{@index+1}} | {{name}} | {{status}} | {{capacity}} | {{items.length}} | {{capacity - items.length}} |
+{{/each}}
+    </output>
+    <ask>Select target sprint (enter number):</ask>
+    <action>Resolve entered number to the corresponding sprint entry and store as {{target_sprint}} (the sprint's map key and full sprint object)</action>
+  </check>
+</step>
+
+<step n="2" goal="Display backlog items eligible for sprint assignment">
+  <action>Read the `backlog` array from {{sprint_status}}</action>
+  <action>Filter to items with `status: ready-for-dev` ONLY — schema section 4.5 movement rules require this status for sprint assignment</action>
+  <check if="no ready-for-dev items exist in the backlog">
+    <output>❌ No items eligible for sprint assignment. Items must have `status: ready-for-dev` to be added to a sprint. Items with `status: backlog` must first have a story file created (which advances them to `ready-for-dev`).</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Display eligible backlog items in priority order (array order = priority order, position 0 = highest priority)</action>
+  <output>
+## Backlog Items (eligible for sprint assignment)
+
+| # | ID | Title | Type | Epic | Severity |
+|---|-----|-------|------|------|----------|
+{{#each eligible_backlog_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{epic}} | {{severity}} |
+{{/each}}
+
+*Total eligible: {{eligible_count}} items (status: ready-for-dev)*
+  </output>
+</step>
+
+<step n="3" goal="Display sprint capacity">
+  <action>Calculate capacity usage: current assigned count = `{{target_sprint.items.length}}`</action>
+  <action>Calculate remaining = `{{target_sprint.capacity}} - {{target_sprint.items.length}}`</action>
+  <output>
+## Sprint Capacity: {{target_sprint.name}}
+
+- **Capacity:** {{target_sprint.capacity}} items
+- **Assigned:** {{target_sprint.items.length}} items
+- **Remaining:** {{remaining_capacity}} slots
+
+{{#if remaining_capacity <= 0}}
+⚠️ This sprint is **at or over capacity**. Adding items will exceed the limit.
+{{/if}}
+  </output>
+</step>
+
+<step n="4" goal="Select candidate items for this sprint">
+  <ask>Which backlog items do you want to consider for this sprint? Enter item numbers (comma-separated), or "all" to evaluate the full eligible backlog:</ask>
+  <check if="user enters 'all'">
+    <action>Set {{candidate_items}} = all items from the eligible backlog list displayed in step 2</action>
+  </check>
+  <check if="user enters item numbers">
+    <action>Resolve the entered numbers against the eligible backlog table from step 2</action>
+    <action>Validate all entered numbers correspond to displayed items — report error for any invalid numbers</action>
+    <action>Set {{candidate_items}} = those specific items</action>
+  </check>
+</step>
+
+<step n="5" goal="Multi-criteria prioritization analysis">
+  <action>For each item in {{candidate_items}}, evaluate and score across criteria:
+    - **Business value:** High (H) / Medium (M) / Low (L) — impact on users or project goals
+    - **Dependency status:** Blocked (blocked by another item) / Blocking (blocks other items) / Independent
+    - **Severity** (bugs only): Critical / High / Medium / Low — N/A for stories
+    - **Effort estimation:** Small (S ≤ 1 day) / Medium (M 2–3 days) / Large (L 4+ days)
+  </action>
+  <action>Generate a ranked ordering recommendation, factoring in:
+    1. Blocking dependencies first (items that unlock others)
+    2. High business value + low/medium effort (quick wins)
+    3. Critical/High bugs ahead of Medium/Low bugs
+    4. Avoid blocked items unless capacity allows waiting
+  </action>
+  <output>
+## Prioritization Analysis
+
+| Rank | ID | Title | Type | Business Value | Dependencies | Severity | Effort | Rationale |
+|------|----|-------|------|----------------|--------------|----------|--------|-----------|
+{{#each ranked_items}}
+| {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} | {{rationale}} |
+{{/each}}
+
+**Recommended selection** (up to {{remaining_capacity}} items to stay within capacity): {{recommended_selection}}
+  </output>
+</step>
+
+<step n="6" goal="User confirms or adjusts selection">
+  <ask>Review the ranking above. Options:
+- [c] Confirm recommended selection as-is
+- [m] Modify selection (specify item numbers to include)
+- [r] Re-rank items (provide new priority order)
+- [x] Cancel without assigning
+
+Choice:</ask>
+  <check if="user selects 'x'">
+    <output>❌ Assignment cancelled — no changes made.</output>
+    <action>Exit workflow</action>
+  </check>
+  <check if="user selects 'm'">
+    <ask>Enter item numbers to assign (comma-separated):</ask>
+    <action>Resolve entered numbers against the eligible backlog table from step 2</action>
+    <action>Set {{confirmed_items}} = those specific items</action>
+  </check>
+  <check if="user selects 'r'">
+    <ask>Enter item numbers in your preferred priority order (comma-separated). Only items you include will be assigned — items not listed will be excluded from this session and remain in the backlog:</ask>
+    <action>Set {{confirmed_items}} = items matching the user-provided numbers, in the order provided. Items from {{candidate_items}} NOT mentioned are excluded from this session (they remain in the backlog for future sprints).</action>
+  </check>
+  <check if="user selects 'c'">
+    <action>Set {{confirmed_items}} = recommended selection from step 5</action>
+  </check>
+  <action>Store confirmed ranking in {{confirmed_ranking}} for the audit record</action>
+</step>
+
+<step n="7" goal="Execute movement with capacity enforcement">
+  <action>Initialize {{current_sprint_count}} = {{target_sprint.items.length}} (current assigned count before any additions this session)</action>
+  <action>Initialize {{items_to_move}} = [] (items confirmed for movement)</action>
+  <action>For each item in {{confirmed_items}}, in confirmed ranking order:</action>
+  <check if="adding this item would exceed sprint capacity (current_sprint_count + 1 > target_sprint.capacity)">
+    <output>⚠️ **Capacity Warning:** Adding "{{item.title}}" would bring assigned items to {{current_sprint_count + 1}}/{{target_sprint.capacity}} — exceeding sprint capacity by {{current_sprint_count + 1 - target_sprint.capacity}}.</output>
+    <ask>Options:
+- [a] Add anyway (over-capacity acknowledged)
+- [s] Skip this item (leave in backlog)
+- [m] Exit to run `/modify-sprint` to increase capacity first
+
+Choice:</ask>
+    <check if="user selects 's'">
+      <action>Skip this item — do NOT add to {{items_to_move}}. Continue to next item.</action>
+    </check>
+    <check if="user selects 'm'">
+      <output>💡 Run `/modify-sprint` to increase capacity for **{{target_sprint.name}}**, then re-run `/add-to-sprint`.</output>
+      <action>Exit workflow without making any changes</action>
+    </check>
+    <check if="user selects 'a'">
+      <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</action>
+    </check>
+  </check>
+  <check if="item is within capacity">
+    <action>Add to {{items_to_move}} and increment {{current_sprint_count}}</action>
+  </check>
+</step>
+
+<step n="8" goal="Atomic write — persist all movements to sprint-status.yaml">
+  <action>If {{items_to_move}} is empty (all items were skipped or cancelled), exit without writing.</action>
+
+  <action>**Pre-write: single-location invariant check.** Build {{all_sprint_item_ids}} = flat set of all item IDs across ALL sprints in {{sprint_status}}.sprints (every sprint, every status). For each item in {{items_to_move}}: check if its ID exists in {{all_sprint_item_ids}}. If ANY match is found:
+    <output>**Error:** Data integrity violation — item {{item.id}} already exists in a sprint. Aborting to prevent duplicate. The sprint-status.yaml file may be corrupted. No changes have been written.</output>
+    <action>Exit workflow without writing</action>
+  </action>
+
+  <action>**Pre-write: backlog re-validation.** Build {{current_backlog_ids}} = set of all item IDs currently in {{sprint_status}}.backlog. For each item in {{items_to_move}}: check if its ID exists in {{current_backlog_ids}}. If ANY item is missing:
+    <output>**Error:** Item {{item.id}} was selected for sprint assignment but is no longer in the backlog. The file may have been modified externally. No changes have been written. Please re-run `/add-to-sprint` to start fresh.</output>
+    <action>Exit workflow without writing</action>
+  </action>
+
+  <action>Perform ALL of the following in a single atomic write to `sprint-status.yaml`:</action>
+  <action>1. For each item in {{items_to_move}}:
+    - Build the sprint item object: copy `id`, `type`, `epic`, `title`, `status`, `severity` from the backlog item — DROP the `priority` field (sprint items do not have priority)
+    - APPEND the sprint item object to `sprints[{{target_sprint_key}}].items`
+    - REMOVE the original item object from the `backlog` array
+  </action>
+  <action>2. Renumber remaining backlog items' `priority` values sequentially (1..N) to match their new array positions (position 0 → priority 1, position 1 → priority 2, etc.)</action>
+  <action>3. Update `last_updated` to the current ISO-8601 timestamp</action>
+  <action>4. Preserve `generated`, `epics`, and all other metadata fields unchanged</action>
+  <action>5. Write the complete updated `sprint-status.yaml` in a single write operation (all removals + additions + renumbering happen together — no partial state)</action>
+</step>
+
+<step n="9" goal="Display summary">
+  <output>
+## Assignment Complete
+
+**Sprint:** {{target_sprint.name}}
+**Items assigned this session:** {{items_to_move.length}}
+
+| # | ID | Title | Type |
+|---|----|-------|------|
+{{#each items_to_move}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} |
+{{/each}}
+
+### Confirmed Ranking (Audit Record)
+
+| Rank | ID | Title | Type | Business Value | Dependencies | Severity | Effort |
+|------|----|-------|------|----------------|--------------|----------|--------|
+{{#each confirmed_ranking}}
+| {{rank}} | {{id}} | {{title}} | {{type}} | {{business_value}} | {{dependency_status}} | {{severity}} | {{effort}} |
+{{/each}}
+
+**Updated Capacity:** {{current_sprint_count}}/{{target_sprint.capacity}} items used ({{target_sprint.capacity - current_sprint_count}} remaining)
+
+**Next Steps:**
+- Use `/remove-from-sprint` to move items back to backlog if needed
+- Use `/modify-sprint` to adjust capacity or sprint metadata
+- Use `/sprint-status-view` to view the full sprint with all assigned items
+  </output>
+</step>
+
+</workflow>

package/skills/add-to-sprint/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "add-to-sprint",
+  "version": "1.0.0",
+  "description": "Guided workflow to move backlog items to a sprint in the unified sprint-status.yaml using movement semantics",
+  "category": "workflow",
+  "tags": ["sprint-management", "backlog", "movement-semantics"]
+}

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"]
+}