ma-agents 3.1.0 → 3.3.0

package/lib/bmad-extension/skills/sprint-status-view/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sprint-status-view
-description: Display sprint progress with assigned items, type distinction, and remaining capacity
+description: Display sprint progress with capacity, items, and backlog. Regenerates sprint-status.yaml.
 type: skill
 triggers:
   - "sprint status view"
@@ -9,194 +9,255 @@ triggers:
 
 # Sprint Status View Workflow
 
-Extension workflow that displays sprint progress with assigned items (stories + bugs), type distinction, and remaining capacity.
-
-> **Architecture mandate:** This workflow is a NEW extension at `lib/bmad-extension/workflows/sprint-status-view/`. It does NOT modify any files under `_bmad/bmm/workflows/`.
+Display sprint status with capacity, items, and backlog summary. Regenerates `sprint-status.yaml` from authoritative sources.
 
 <workflow>
 
-<step n="1" goal="Discover all sprint artifact files">
-  <action>Glob `_bmad-output/implementation-artifacts/sprint-plan-*.yaml` to discover all sprint artifact files</action>
-  <check if="no sprint files found">
+<step n="1" goal="Suggest running /cleanup-done first">
+  <output>
+**Tip:** Consider running `/cleanup-done` before viewing sprint status to archive completed items and free capacity.
+  </output>
+  <action>Continue to next step (advisory only -- do not auto-invoke /cleanup-done)</action>
+</step>
+
+<step n="2" goal="Load data sources">
+  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to discover all sprint entity files</action>
+  <action>Store discovered sprint files as {{sprint_files}} list</action>
+
+  <action>Read `_bmad-output/implementation-artifacts/backlog.yaml` if it exists</action>
+  <action>Store the backlog items list as {{backlog_items}} (or empty list if file not found)</action>
+
+  <action>Glob `_bmad-output/implementation-artifacts/bug-*.md` to discover all bug story files (fallback for bug metadata)</action>
+  <action>For each bug file found, parse YAML frontmatter to extract: title, severity, status</action>
+  <action>Store as {{bug_metadata_map}} keyed by file basename (e.g., `bug-login-crash`)</action>
+
+  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml` if it exists (fallback for story status when backlog.yaml is missing or incomplete)</action>
+  <action>Parse development_status section into {{status_fallback_map}} -- key: story key, value: status</action>
+  <action>Exclude epic-* keys and *-retrospective keys from the fallback map</action>
+
+  <check if="no sprint files found AND no backlog.yaml exists">
     <output>
-ℹ️ **No Sprints Found**
+**No Sprint Data Found**
 
-No sprint plan files exist yet (`sprint-plan-*.yaml`).
+No sprint files exist (`sprints/sprint-*.yaml`) and no `backlog.yaml` was found.
 
 **To get started:**
-- Run `/add-sprint` to create your first sprint
-- Run `/add-to-sprint` to assign backlog items to it
+1. Run `/generate-backlog` to create a backlog from your epics
+2. Run `/add-sprint` to create your first sprint
+3. Run `/add-to-sprint` to assign backlog items to it
     </output>
     <action>Exit workflow</action>
   </check>
-  <action>For each sprint file found, read the full YAML content and store as {{sprint_plans}} list</action>
-  <action>Sort {{sprint_plans}} by sprint_number ascending</action>
 </step>
 
-<step n="2" goal="Load sprint-status.yaml for user story execution statuses">
-  <action>Read `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
-  <check if="file not found">
-    <output>⚠️ `sprint-status.yaml` not found. User story execution statuses will not be available. Run `/sprint-planning` to initialize.</output>
-    <action>Set {{story_status_map}} = {} (empty — will show data integrity warnings per missing item)</action>
-  </check>
-  <check if="file found">
-    <action>Parse development_status section into {{story_status_map}} — key: story key, value: status</action>
-    <action>Exclude epic-* keys and *-retrospective keys from the map</action>
-  </check>
-</step>
-
-<step n="3" goal="Discover bug stories for type/severity data">
-  <action>Glob `_bmad-output/implementation-artifacts/bug-*.md` to discover all bug story files</action>
-  <check if="no bug files found">
-    <action>Set {{bug_metadata_map}} = {} (empty)</action>
-  </check>
-  <check if="bug files found">
-    <action>For each bug file, parse YAML frontmatter to extract: type, severity, title</action>
-    <action>Build {{bug_metadata_map}} — key: file basename (e.g., `bug-login-crash`), value: {severity, title}</action>
-  </check>
-</step>
-
-<step n="4" goal="Display sprint status for each sprint">
-  <action>For each sprint in {{sprint_plans}} (in order):</action>
-  <action>Calculate: {{assigned_count}} = length(sprint.assigned_items)</action>
-  <action>Calculate: {{remaining_capacity}} = sprint.capacity - {{assigned_count}}</action>
-
-  <action>For each item identifier in sprint.assigned_items, resolve item details:
-
-    **If item is a story (key matches regex `^\d+-\d+-.+`):**
-    - Look up status in {{story_status_map}}[item_key]
-    - If NOT found in {{story_status_map}}:
-      → Record as DATA INTEGRITY WARNING: "Item {item_key} has no status entry in sprint-status.yaml — run /sprint-planning to initialize status tracking for this item."
-      → Display item with marker: ⚠️ [status unknown]
-    - If found: display with current status label
-
-    **If item is a bug (key matches regex `^bug-.+`):**
-    - Look up in {{bug_metadata_map}}[item_key]
-    - If NOT found: display with title as item_key, severity as "unknown"
-    - If found: display with title and severity from frontmatter
-    - Bug execution status: use `status` from bug file frontmatter if present; otherwise "not-started"
-
-    **If item matches neither pattern:** display as type "Unknown" with raw identifier as title
+<step n="3" goal="Display each sprint">
+  <action>For each sprint in {{sprint_files}}, read the full YAML content</action>
+  <action>Sort sprints for display: active first, then planning, then closed</action>
+  <action>Initialize {{total_done_in_sprints}} = 0 for step 4</action>
+
+  <action>For each sprint (in sorted order):
+
+    **If sprint.status is "closed":**
+    - Count total items in sprint.items
+    - Display collapsed summary line only
+
+    **If sprint.status is NOT "closed" (active or planning):**
+    - Calculate {{item_count}} = length(sprint.items)
+    - For each item identifier in sprint.items, resolve details:
+      - Look up item in {{backlog_items}} by matching `id` field
+      - If found in backlog: use `type`, `title`, `status`, `severity` from backlog entry
+      - If NOT found in backlog and item matches `^bug-`: look up in {{bug_metadata_map}} for title/severity, use status from bug frontmatter or default to "backlog"
+      - If NOT found in backlog and item matches a story pattern: look up in {{status_fallback_map}} for status, infer title from key, set type to "story"
+      - If item cannot be resolved from any source: display with raw identifier, type "unknown", status "unknown"
+    - If resolved item status is "done", increment {{total_done_in_sprints}}
+    - Build capacity bar: `[===---]` style where `=` represents filled slots and `-` represents remaining capacity
   </action>
 
+  <action>Display non-closed sprints:</action>
   <output>
+{{#each non_closed_sprints}}
 ---
 
-## 🏃 {{sprint.sprint_name}} (Sprint {{sprint.sprint_number}})
+## {{sprint.name}} ({{sprint.status}}) -- {{item_count}}/{{sprint.capacity}} items
 
-**Status:** {{sprint.status}} | **Capacity:** {{sprint.capacity}} items | **Assigned:** {{assigned_count}} | **Remaining:** {{remaining_capacity}}
-{{#if sprint.start_context}}**Start:** {{sprint.start_context}}{{/if}} {{#if sprint.end_context}}| **End:** {{sprint.end_context}}{{/if}}
+{{#if sprint.start}}**Start:** {{sprint.start}}{{/if}}{{#if sprint.end}} | **End:** {{sprint.end}}{{/if}}
 
-{{#if over_capacity}}
-⚠️ **Over capacity by {{overage}} item(s)**
-{{/if}}
-
-### Assigned Items
-
-| Item | Title | Type | Status / Severity |
-|---|---|---|---|
+| Item | Type | Status |
+|---|---|---|
 {{#each resolved_items}}
-{{#if is_story}}
-| {{item_key}} | {{title}} | 📋 Story | {{status}} |
-{{/if}}
-{{#if is_bug}}
-| {{item_key}} | {{title}} | 🐛 Bug | Severity: {{severity}} / {{bug_status}} |
-{{/if}}
+| {{id}} | {{#if is_story}}[story]{{/if}}{{#if is_bug}}[bug, {{severity}}]{{/if}} | {{status}} |
 {{/each}}
+{{#if items_empty}}
+*(No items assigned)*
+{{/if}}
 
-{{#if data_integrity_warnings}}
-**⚠️ Data Integrity Warnings:**
-{{#each data_integrity_warnings}}
-- {{this}}
+**Capacity:** {{capacity_bar}}
 {{/each}}
-{{/if}}
+  </output>
 
-{{#if assigned_items_empty}}
-*(No items assigned to this sprint)*
-{{/if}}
+  <action>Display closed sprints:</action>
+  <output>
+{{#each closed_sprints}}
+---
+**{{sprint.name}}** (closed) -- {{item_count}} items completed
+{{/each}}
   </output>
 </step>
 
-<step n="5" goal="Display unassigned backlog summary">
-  <action>Collect all item keys from {{story_status_map}} that are NOT in any sprint's assigned_items list — these are unassigned user stories</action>
-  <action>Collect all bug basenames from {{bug_metadata_map}} that are NOT in any sprint's assigned_items list — these are unassigned bugs</action>
-  <action>Count unassigned stories by status: {{unassigned_by_status}}</action>
-  <output>
+<step n="4" goal="Completed items summary">
+  <action>Count items with status "done" that are still present in non-closed sprint files (use {{total_done_in_sprints}} from step 3)</action>
+  <check if="total_done_in_sprints > 0">
+    <output>
 ---
 
-## 📦 Unassigned Backlog
+## Completed Items
 
-### 📋 Unassigned Stories
+{{total_done_in_sprints}} done item(s) are still in sprint files. Run `/cleanup-done` to archive them and free capacity.
+    </output>
+  </check>
+  <check if="total_done_in_sprints == 0">
+    <action>Skip this section -- no done items lingering in sprints</action>
+  </check>
+</step>
 
-| Status | Count |
-|---|---|
-| backlog | {{count_backlog}} |
-| ready-for-dev | {{count_ready}} |
-| in-progress | {{count_in_progress}} |
-| review | {{count_review}} |
-| done | {{count_done}} |
+<step n="5" goal="Unassigned backlog">
+  <action>Filter {{backlog_items}} to find items where sprint is null (unassigned)</action>
+  <action>Exclude items with status "done" from the unassigned list</action>
+  <action>Sort unassigned items by priority ascending (lowest number = highest priority)</action>
+  <action>Store as {{unassigned_items}}</action>
+  <action>Store total count as {{unassigned_total}}</action>
+  <action>Take top 15 items for display as {{unassigned_display}}</action>
 
-*Total unassigned stories: {{total_unassigned}}*
+  <check if="unassigned_total > 0">
+    <output>
+---
 
-### 🐛 Unassigned Bugs
+## Unassigned Backlog
 
-{{#if unassigned_bugs}}
-| ID / File | Title | Severity |
-|---|---|---|
-{{#each unassigned_bugs}}
-| {{id}} | {{title}} | {{severity}} |
+| # | Item | Type | Priority | Status |
+|---|---|---|---|---|
+{{#each unassigned_display}}
+| {{priority}} | {{id}} | {{type}} | {{priority}} | {{status}} |
 {{/each}}
-{{else}}
-*(No unassigned bugs)*
-{{/if}}
-
-**Tip:** Use `/add-to-sprint` to assign unassigned items to a sprint.
-  </output>
-</step>
-
-<step n="6" goal="Offer next actions">
-  <ask>Options:
-1. Show full unassigned backlog item list (IDs + titles + statuses)
-2. Add items to a sprint — run `/add-to-sprint`
-3. Modify a sprint — run `/modify-sprint`
-4. Create a new sprint — run `/add-sprint`
-5. Exit
+{{#if unassigned_total > 15}}
 
-Choice:</ask>
-  <check if="choice == 1">
-    <action>For each unassigned story key in {{story_status_map}} not assigned to any sprint, display: key, inferred title, status</action>
-    <action>For each unassigned bug in {{bug_metadata_map}} not assigned to any sprint, display: id, title, severity</action>
+... and {{unassigned_total - 15}} more
+{{/if}}
+    </output>
+  </check>
+  <check if="unassigned_total == 0">
     <output>
-### Full Unassigned Backlog
+---
 
-**Stories:**
-| Key | Title | Status |
-|---|---|---|
-{{#each unassigned_story_items}}
-| {{key}} | {{title}} | {{status}} |
-{{/each}}
+## Unassigned Backlog
 
-**Bugs:**
-| ID | Title | Severity |
-|---|---|---|
-{{#each unassigned_bugs}}
-| {{id}} | {{title}} | {{severity}} |
-{{/each}}
+*(All backlog items are assigned to sprints)*
     </output>
+  </check>
+</step>
+
+<step n="6" goal="Next actions menu">
+  <ask>
+**Next Actions:**
+[1] Full backlog
+[2] /add-to-sprint
+[3] /remove-from-sprint
+[4] /prioritize-backlog
+[5] /add-sprint
+[6] /cleanup-done
+[7] Exit
+
+Choice:
+  </ask>
+  <check if="choice == 1">
+    <action>Display all items from {{backlog_items}} in a table: id, type, priority, status, sprint, severity</action>
     <goto step="6" />
   </check>
   <check if="choice == 2">
-    <output>▶️ Run `/add-to-sprint` to assign backlog items to a sprint.</output>
+    <output>Run `/add-to-sprint` to assign backlog items to a sprint.</output>
   </check>
   <check if="choice == 3">
-    <output>▶️ Run `/modify-sprint` to add/remove items or change sprint settings.</output>
+    <output>Run `/remove-from-sprint` to remove items from a sprint.</output>
   </check>
   <check if="choice == 4">
-    <output>▶️ Run `/add-sprint` to create a new sprint.</output>
+    <output>Run `/prioritize-backlog` to reorder backlog priorities.</output>
   </check>
   <check if="choice == 5">
+    <output>Run `/add-sprint` to create a new sprint.</output>
+  </check>
+  <check if="choice == 6">
+    <output>Run `/cleanup-done` to archive completed items from sprints.</output>
+  </check>
+  <check if="choice == 7">
     <action>Exit workflow</action>
   </check>
 </step>
 
+<step n="7" goal="Regenerate sprint-status.yaml (internal)" internal="true">
+  <action>This step runs automatically after display (steps 3-6) completes, before the workflow exits.</action>
+
+  <action>Read existing `_bmad-output/implementation-artifacts/sprint-status.yaml` if it exists</action>
+  <action>Preserve the STATUS DEFINITIONS comment block at the top of the file (lines starting with `#` that define status values)</action>
+  <action>Preserve any epic-* keys and *-retrospective keys from the existing file</action>
+
+  <action>Build the new development_status section:
+    - Source 1: {{backlog_items}} from backlog.yaml -- for each item where status is NOT "done", add an entry: key = item.id, value = item.status
+    - Source 2: sprint entity files -- for each sprint, for each item in sprint.items, ensure the item has an entry. If the item was already added from backlog.yaml, the backlog value wins. If the item is NOT in backlog.yaml, look up status from {{bug_metadata_map}} or {{status_fallback_map}}.
+    - Exclude items with status "done" -- only non-done items appear in sprint-status.yaml
+  </action>
+
+  <action>Collect sprint metadata for header comments:
+    - For each sprint: id, name, status, item count, capacity
+  </action>
+
+  <action>Get current ISO timestamp as {{generated_at}}</action>
+
+  <action>Write `_bmad-output/implementation-artifacts/sprint-status.yaml` with this structure:
+
+```yaml
+# generated: {{original_generated_date or generated_at}}
+# updated: {{generated_at}} — regenerated by sprint-status-view
+# project: {{project_name from existing file or "unknown"}}
+# project_key: {{project_key from existing file or "NOKEY"}}
+# tracking_system: file-system
+# story_location: _bmad-output/implementation-artifacts
+#
+# Sprints:
+{{#each sprints}}
+#   {{sprint.id}}: {{sprint.name}} ({{sprint.status}}) — {{item_count}}/{{sprint.capacity}} items
+{{/each}}
+#
+# STATUS DEFINITIONS:
+# ==================
+# (preserve the full STATUS DEFINITIONS block from the existing file verbatim)
+# If no existing file, use these defaults:
+# backlog        — item is in the backlog, not yet started
+# ready-for-dev  — story file created, ready for development
+# in-progress    — item is actively being worked on
+# review         — item is in review
+# done           — item is complete (excluded from this file)
+
+{{#if preserved_epic_keys}}
+# Epic tracking
+{{#each preserved_epic_keys}}
+{{key}}: {{value}}
+{{/each}}
+{{/if}}
+
+development_status:
+{{#each active_items}}
+  {{id}}: {{status}}
+{{/each}}
+
+{{#if preserved_retro_keys}}
+# Retrospective tracking
+{{#each preserved_retro_keys}}
+{{key}}: {{value}}
+{{/each}}
+{{/if}}
+```
+
+  </action>
+</step>
+
 </workflow>

package/lib/bmad-extension/workflows/add-sprint/workflow.md

@@ -1,16 +1,38 @@
+<!-- IMPORTANT: This file must be kept in sync with lib/bmad-extension/skills/add-sprint/SKILL.md
+     SKILL.md is the authoritative source (resolved via skill:add-sprint in module-help.csv).
+     This workflow.md is a legacy copy. Any changes should be made to SKILL.md first, then synced here. -->
+
 # Add Sprint Workflow
 
-Guided workflow to create a new sprint with capacity limits for realistic sprint planning.
+Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema.
 
 <workflow>
 
-<step n="1" goal="Gather sprint number and name">
-  <action>Ask the user for the sprint number (e.g., 1, 2, 3)</action>
-  <ask>What is the sprint number? (e.g., 1)</ask>
-  <action>Store as {{sprint_number}}</action>
-  <ask>What is the sprint name? (e.g., "Sprint 1 — Foundation") — press Enter to use "Sprint {{sprint_number}}"</ask>
-  <action>If user presses Enter or leaves blank, default to "Sprint {{sprint_number}}"</action>
-  <action>Store as {{sprint_name}}</action>
+<step n="1" goal="Gather and validate sprint number and name">
+  <action>Ask the user for the sprint number</action>
+  <ask>What is the sprint number? (positive integer, e.g., 1, 2, 3)</ask>
+  <action>Store input as {{sprint_number_input}}</action>
+  <action>Validate {{sprint_number_input}} matches `^[1-9]\d*$` (positive integer, no leading zeros, no non-numeric characters)</action>
+  <action>Validate {{sprint_number_input}} is <= 9999</action>
+  <check if="{{sprint_number_input}} fails validation (zero, negative, non-numeric, leading zeros like '03', or > 9999)">
+    <output>❌ Invalid sprint number: "{{sprint_number_input}}". Must be a positive integer (1-9999), no leading zeros.</output>
+    <goto step="1" />
+  </check>
+  <action>Store as {{sprint_number}} (integer)</action>
+  <action>Construct {{sprint_id}} = "sprint-{{sprint_number}}"</action>
+
+  <!-- Smart default name: detect naming patterns from existing sprints -->
+  <action>Glob `_bmad-output/implementation-artifacts/sprints/sprint-*.yaml` to discover existing sprint files</action>
+  <action>If existing sprints found, read the `name` field from the most recent one (highest sprint number)</action>
+  <action>Infer a smart default name:
+    - If previous name follows a sequential pattern with a numeric suffix (e.g., "app04"), suggest the next increment (e.g., "app05")
+    - If previous name follows a date pattern (e.g., "2026-W14"), suggest the next date interval
+    - If previous name is "Sprint {n}", suggest "Sprint {{sprint_number}}"
+    - If no pattern detected or no existing sprints, default to "Sprint {{sprint_number}}"
+  </action>
+  <ask>Sprint name? (press Enter for "{{default_name}}", or type a custom name):</ask>
+  <action>If user presses Enter or leaves blank, set {{sprint_name}} = "{{default_name}}"</action>
+  <action>If user provides input, store as {{sprint_name}}</action>
 </step>
 
 <step n="2" goal="Gather capacity as positive integer">
@@ -25,32 +47,71 @@ Guided workflow to create a new sprint with capacity limits for realistic sprint
   <action>Store as {{capacity}} (integer)</action>
 </step>
 
-<step n="3" goal="Gather optional start and end context">
-  <action>Explain: start/end context can be dates (e.g., "2026-03-18") or milestone descriptions (e.g., "Q1 Planning Complete")</action>
-  <ask>Optional — Sprint start context (date or milestone, press Enter to skip):</ask>
-  <action>Store as {{start_context}} (empty string if skipped)</action>
-  <ask>Optional — Sprint end context (date or milestone, press Enter to skip):</ask>
-  <action>Store as {{end_context}} (empty string if skipped)</action>
+<step n="3a" goal="Gather optional start date (ISO format)">
+  <action>Explain: start and end dates are optional ISO dates (YYYY-MM-DD format). Press Enter to skip.</action>
+  <ask>Optional — Sprint start date (YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store input as {{start_input}}</action>
+  <check if="{{start_input}} is not empty">
+    <action>Validate {{start_input}} matches regex `^\d{4}-\d{2}-\d{2}$`</action>
+    <action>Verify {{start_input}} resolves to a real calendar date (reject impossible dates like 2026-02-30, 2026-13-45, etc.)</action>
+    <check if="{{start_input}} fails date validation">
+      <output>❌ Invalid date: "{{start_input}}". Must be a valid date in YYYY-MM-DD format (e.g., 2026-04-01).</output>
+      <goto step="3a" />
+    </check>
+  </check>
+  <action>Store as {{start_date}} (valid ISO date string, or empty string "" if skipped)</action>
+</step>
+
+<step n="3b" goal="Gather optional end date (ISO format)">
+  <ask>Optional — Sprint end date (YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store input as {{end_input}}</action>
+  <check if="{{end_input}} is not empty">
+    <action>Validate {{end_input}} matches regex `^\d{4}-\d{2}-\d{2}$`</action>
+    <action>Verify {{end_input}} resolves to a real calendar date</action>
+    <check if="{{end_input}} fails date validation">
+      <output>❌ Invalid date: "{{end_input}}". Must be a valid date in YYYY-MM-DD format (e.g., 2026-04-14).</output>
+      <goto step="3b" />
+    </check>
+  </check>
+  <action>Store as {{end_date}} (valid ISO date string, or empty string "" if skipped)</action>
+
+  <check if="both {{start_date}} and {{end_date}} are non-empty AND {{start_date}} > {{end_date}}">
+    <output>❌ Invalid date range: start date ({{start_date}}) is after end date ({{end_date}}). Start must be on or before end.</output>
+    <goto step="3a" />
+  </check>
 </step>
 
 <step n="4" goal="Confirm and validate all inputs">
   <output>
 ## Sprint Summary — Please Confirm
 
-- **Sprint Number:** {{sprint_number}}
-- **Sprint Name:** {{sprint_name}}
+- **Sprint ID:** {{sprint_id}}
+- **Sprint Name:** "{{sprint_name}}"
+- **Status:** planning
 - **Capacity (max items):** {{capacity}}
-- **Start Context:** {{start_context}} *(empty if skipped)*
-- **End Context:** {{end_context}} *(empty if skipped)*
-- **Output File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
+- **Start Date:** {{start_date}} *(empty if skipped)*
+- **End Date:** {{end_date}} *(empty if skipped)*
+- **Items:** [] *(empty — items assigned via /add-to-sprint)*
+- **Output File:** `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`
   </output>
   <ask>Confirm creation? [y] Yes / [n] Cancel / [e] Edit a field:</ask>
   <check if="user selects 'e'">
     <ask>Which field to edit? (number / name / capacity / start / end)</ask>
     <check if="field == 'number'">
-      <ask>New sprint number:</ask>
-      <action>Store as {{sprint_number}}</action>
-      <action>If sprint name was auto-defaulted to the old "Sprint {n}", update it to "Sprint {{sprint_number}}"</action>
+      <ask>New sprint number? (positive integer, 1-9999)</ask>
+      <action>Store input as {{sprint_number_input}}</action>
+      <action>Validate {{sprint_number_input}} matches `^[1-9]\d*$` and is <= 9999</action>
+      <check if="{{sprint_number_input}} fails validation">
+        <output>❌ Invalid sprint number: "{{sprint_number_input}}". Must be a positive integer (1-9999), no leading zeros.</output>
+        <goto step="4" />
+      </check>
+      <action>Store as {{sprint_number}} (integer)</action>
+      <action>Construct {{sprint_id}} = "sprint-{{sprint_number}}"</action>
+      <action>If sprint name was using previous default "Sprint {old_n}", update to "Sprint {{sprint_number}}"</action>
+      <action>Check if file exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
+      <check if="file already exists at new path">
+        <output>⚠️ A sprint entity already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`. You will be prompted to overwrite at creation.</output>
+      </check>
       <goto step="4" />
     </check>
     <check if="field == 'name'">
@@ -59,45 +120,74 @@ Guided workflow to create a new sprint with capacity limits for realistic sprint
       <goto step="4" />
     </check>
     <check if="field == 'capacity'"><goto step="2" /></check>
-    <check if="field == 'start'"><goto step="3" /></check>
-    <check if="field == 'end'"><goto step="3" /></check>
+    <check if="field == 'start'"><goto step="3a" /></check>
+    <check if="field == 'end'"><goto step="3b" /></check>
+    <check if="field is not recognized">
+      <output>❌ Unrecognized field: "{{field}}". Valid options: number, name, capacity, start, end.</output>
+      <goto step="4" />
+    </check>
   </check>
   <check if="user selects 'n'">
     <output>❌ Sprint creation cancelled.</output>
     <action>Exit workflow</action>
   </check>
+  <check if="user input is not 'y', 'n', or 'e'">
+    <output>❌ Unrecognized option: "{{user_input}}". Please enter [y] Yes, [n] Cancel, or [e] Edit a field.</output>
+    <goto step="4" />
+  </check>
 </step>
 
-<step n="5" goal="Generate sprint artifact file">
-  <action>Determine output path: `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`</action>
-  <action>Check if file already exists at output path</action>
-  <check if="file already exists">
-    <output>⚠️ A sprint plan already exists at `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`.</output>
-    <ask>Overwrite existing sprint plan? [y] Yes / [n] Cancel:</ask>
+<step n="5" goal="Generate sprint entity YAML file">
+  <action>Determine output path: `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
+  <action>Ensure directory `_bmad-output/implementation-artifacts/sprints/` exists (create if needed)</action>
+
+  <!-- Overwrite protection for new path -->
+  <action>Check if file already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`</action>
+  <check if="file already exists at new path">
+    <anchor id="overwrite_prompt" />
+    <output>⚠️ A sprint entity already exists at `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`.</output>
+    <ask>Overwrite existing sprint? [y] Yes / [n] Cancel:</ask>
     <check if="user selects 'n'">
-      <output>❌ Sprint creation cancelled to preserve existing sprint plan.</output>
+      <output>❌ Sprint creation cancelled to preserve existing sprint.</output>
       <action>Exit workflow</action>
     </check>
+    <check if="user input is not 'y' or 'n'">
+      <output>❌ Unrecognized option: "{{user_input}}". Please enter [y] Yes or [n] Cancel.</output>
+      <goto anchor="overwrite_prompt" />
+    </check>
   </check>
+
+  <!-- Advisory check for old-format file -->
+  <action>Check if file exists at old path: `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`</action>
+  <check if="old-format file exists">
+    <output>ℹ️ **Note:** An old-format sprint file exists at `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`. The new sprint will be created at the new path. The old file is NOT auto-migrated — review or remove it manually if no longer needed.</output>
+  </check>
+
   <action>Get current ISO timestamp for created_date and last_modified</action>
-  <action>Write sprint artifact YAML to `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml` with this structure:
+  <action>Write sprint entity YAML to `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml` with this structure:
 
 ```yaml
-sprint_number: {{sprint_number}}
-sprint_name: "{{sprint_name}}"
-capacity: {{capacity}}
-assigned_items: []
+id: {{sprint_id}}
+name: "{{sprint_name}}"
 status: planning
-start_context: "{{start_context}}"
-end_context: "{{end_context}}"
+capacity: {{capacity}}
+start: "{{start_date}}"
+end: "{{end_date}}"
+items: []
 created_date: "{{current_iso_timestamp}}"
 last_modified: "{{current_iso_timestamp}}"
 ```
+
+  **YAML output rules:**
+  - Always quote the `name` field to handle special characters
+  - `start` and `end` are empty string `""` if skipped
+  - `items` is always empty array `[]` at creation
+  - `status` is always `planning` at creation (never `active` or `closed`)
   </action>
   <output>
 ✅ **Sprint created successfully!**
 
-- **File:** `_bmad-output/implementation-artifacts/sprint-plan-{{sprint_number}}.yaml`
+- **File:** `_bmad-output/implementation-artifacts/sprints/{{sprint_id}}.yaml`
 - **Sprint:** {{sprint_name}}
 - **Capacity:** {{capacity}} items
 - **Status:** planning