ma-agents 3.1.0 → 3.2.0

package/README.md

@@ -60,7 +60,11 @@ The `_bmad-output/` folder is **intentionally tracked in version control** as pr
 `_bmad-output/` holds all AI-generated planning artifacts produced by BMAD agents:
 
 - **`planning-artifacts/`** — PRDs, architecture documents, UX designs
-- **`implementation-artifacts/`** — Epics, user stories, sprint status
+- **`implementation-artifacts/`** — Epics, user stories, sprint status, backlog
+  - **`sprints/`** — Sprint entity YAML files (`sprint-{id}.yaml`)
+  - **`done/`** — Archived completed stories and bugs
+  - **`backlog.yaml`** — Flat prioritized backlog (generated)
+  - **`sprint-status.yaml`** — Sprint status (derived, auto-regenerated)
 - **`methodology/`** — BMAD-METHOD training materials and onboarding presentation
 
 ### Why it is version-controlled
@@ -117,7 +121,7 @@ The file is version-controlled as part of `_bmad-output/` project knowledge. Com
 | Joseph (MIL-STD-498) | `_bmad/skills/` | `generic` | `_bmad/bmm/agents/mil498.md` |
 | Antigravity | `_bmad/skills/` | `generic` | `_bmad/bmm/agents/antigravity.md` |
 
-## Available Skills (28)
+## Available Skills (34)
 
 | Skill ID | Domain | Description |
 | :--- | :--- | :--- |
@@ -154,6 +158,13 @@ The file is version-controlled as part of `_bmad-output/` project knowledge. Com
 | `self-signed-cert` | Security | Automated Root CA and self-signed certificate generation |
 | `docker-image-signing` | Security | Automated cryptographic signing for Docker images |
 | `docker-hardening-verification` | Security | Audits images for least-privilege and OpenShift compatibility |
+| **Sprint Management** | | |
+| `add-sprint` | Agile | Create sprint entities with capacity, ISO dates, and structured YAML schema |
+| `generate-backlog` | Agile | Generate or refresh a flat prioritized backlog from epics and bug stories |
+| `add-to-sprint` | Agile | Assign backlog items to a sprint with capacity enforcement |
+| `remove-from-sprint` | Agile | Remove items from a sprint and return to unassigned backlog |
+| `cleanup-done` | Agile | Archive done items to `done/` and remove from sprint/backlog tracking |
+| `prioritize-backlog` | Agile | Reprioritize backlog using severity, value, dependencies, and type |
 
 ## Automated Skill Discovery
 
@@ -242,6 +253,36 @@ The integration includes a suite of specialized playbooks:
 - **Security & Trust**: Vault secrets, certificate generation, and vulnerability scanning.
 - **Diagnostics**: Advanced health checks across K8s, Docker, and Podman.
 
+#### Sprint Management (v3.1+)
+
+`ma-agents` includes a complete sprint management system built on first-class YAML entities:
+
+**Data Model:**
+- **Sprint entities** at `sprints/sprint-{id}.yaml` — capacity, dates, assigned items, status lifecycle (`planning` -> `active` -> `closed`)
+- **Flat backlog** at `backlog.yaml` — prioritized list of stories and bugs, independent of epic grouping
+- **Bug lifecycle** — bugs are first-class backlog items with severity, type classification, and the same lifecycle as stories
+- **Derived sprint-status.yaml** — auto-regenerated from backlog + sprint files (no manual maintenance)
+
+**Workflows:**
+
+| Command | Description |
+|---------|-------------|
+| `/add-sprint` | Create a sprint with capacity limits and optional ISO dates |
+| `/generate-backlog` | Build or refresh the flat backlog from epics and bug files |
+| `/add-to-sprint` | Assign backlog items to a sprint (dual-write: backlog + sprint file) |
+| `/remove-from-sprint` | Return items from sprint to backlog (status preserved) |
+| `/cleanup-done` | Archive completed items to `done/`, auto-close empty sprints |
+| `/prioritize-backlog` | Reorder backlog — full, quick-adjust, or AI-suggested modes |
+| `/sprint-status-view` | View sprint capacity, items, backlog, and regenerate sprint-status.yaml |
+| `/create-bug-story` | Create a structured bug with severity, type, and automatic backlog entry |
+
+**Key Design Principles:**
+- **Dual-write consistency**: assigning/removing items updates both `backlog.yaml` and the sprint file atomically
+- **Single-active sprint**: only one sprint can be `active` at a time
+- **Done item archival**: completed work moves to `done/` subfolder, freeing sprint capacity
+- **Priority is independent of epics**: stories from different epics interleave by priority, not epic order
+- **Concurrency guards**: sprint files use `last_modified` timestamps to detect external modifications
+
 ### Install Options (Direct)
 ```bash
 # Default: installs to project-level paths (current directory)
@@ -436,6 +477,11 @@ ma-agents/
 │   ├── bmad.js                 # BMAD-METHOD integration and injection logic
 │   ├── bmad-cache/             # Pre-bundled BMAD external modules (bmb, cis, gds, tea)
 │   ├── bmad-customizations/    # BMAD persona templates (.md) and YAML configs
+│   ├── bmad-extension/         # Extension module: sprint management, bug tracking, agent skills
+│   │   ├── skills/             # SKILL.md packages (add-sprint, generate-backlog, etc.)
+│   │   ├── workflows/          # Legacy workflow copies (redirects to SKILL.md)
+│   │   ├── module.yaml         # Extension module definition
+│   │   └── module-help.csv     # Skill registry with descriptions and output paths
 │   ├── bmad-workflows/         # Specialized BMAD playbooks (SRE, Cyber, etc.)
 │   └── mil498-templates/       # MIL-STD-498 DID library (SRS, SSS, SSDD, etc.)
 ├── scripts/

package/lib/bmad-extension/module-help.csv

@@ -29,9 +29,13 @@ ma-skills,4-implementation,Vault Secrets,cyber-vault-secrets,,skill:cyber-vault-
 ma-skills,4-implementation,Verify Docker Users,cyber-verify-docker-users,,skill:cyber-verify-docker-users,bmad-cyber-verify-docker-users,false,bmm-cyber,,"Verify Docker image user configurations and hardening compliance.",output_folder,"verification report",
 ma-skills,4-implementation,Verify Image Signature,cyber-verify-image-signature,,skill:cyber-verify-image-signature,bmad-cyber-verify-image-signature,false,bmm-cyber,,"Verify Docker image signatures for supply chain integrity.",output_folder,"verification report",
 ma-skills,4-implementation,Vulnerability Scan,cyber-vulnerability-scan,,skill:cyber-vulnerability-scan,bmad-cyber-vulnerability-scan,false,bmm-cyber,,"Orchestrate vulnerability scanning across project components.",output_folder,"scan report",
-ma-skills,4-implementation,Create Bug Story,create-bug-story,,skill:create-bug-story,create-bug-story,false,bmm-dev,,"Create a structured bug story from a detected defect and add to backlog.",_bmad-output/implementation-artifacts,"bug story",
-ma-skills,4-implementation,Add Sprint,add-sprint,,skill:add-sprint,add-sprint,false,bmm-sm,,"Create a new sprint with capacity limits and optional start/end context.",_bmad-output/implementation-artifacts,"sprint plan",
+ma-skills,4-implementation,Create Bug Story,create-bug-story,,skill:create-bug-story,create-bug-story,false,bmm-dev,,"Create a structured bug story with severity and type classification, add to backlog.yaml.",_bmad-output/implementation-artifacts,"bug story",
+ma-skills,4-implementation,Add Sprint,add-sprint,,skill:add-sprint,add-sprint,false,bmm-sm,,"Create a new sprint entity with capacity limits and optional ISO dates (YAML schema).",_bmad-output/implementation-artifacts/sprints,"sprint entity",
 ma-skills,4-implementation,Modify Sprint,modify-sprint,,skill:modify-sprint,modify-sprint,false,bmm-sm,,"Modify existing sprint — add/remove items, change capacity, update metadata.",_bmad-output/implementation-artifacts,"sprint plan",
-ma-skills,4-implementation,Add to Sprint,add-to-sprint,,skill:add-to-sprint,add-to-sprint,false,bmm-sm,,"Assign backlog items (stories + bugs) to a sprint using multi-criteria prioritization.",_bmad-output/implementation-artifacts,"sprint plan",
+ma-skills,4-implementation,Add to Sprint,add-to-sprint,,skill:add-to-sprint,add-to-sprint,false,bmm-sm,,"Assign backlog items to a sprint from flat prioritized backlog.",_bmad-output/implementation-artifacts,"sprint plan",
 ma-skills,4-implementation,Project Context Expansion,project-context-expansion,,skill:project-context-expansion,project-context-expansion,false,bmm-sm,,"Post-retrospective companion to update project-context.md with new rules.",_bmad-output,"project context",
-ma-skills,4-implementation,Sprint Status View,sprint-status-view,,skill:sprint-status-view,sprint-status-view,false,bmm-sm,,"View sprint progress with assigned items and remaining capacity.",_bmad-output/implementation-artifacts,"status display",
+ma-skills,4-implementation,Sprint Status View,sprint-status-view,,skill:sprint-status-view,sprint-status-view,false,bmm-sm,,"View sprint status with capacity, items, and backlog. Regenerates sprint-status.yaml.",_bmad-output/implementation-artifacts,"status display",
+ma-skills,4-implementation,Generate Backlog,generate-backlog,,skill:generate-backlog,generate-backlog,false,bmm-sm,,"Generate or refresh flat backlog from epics and bug stories.",_bmad-output/implementation-artifacts,"backlog",
+ma-skills,4-implementation,Remove from Sprint,remove-from-sprint,,skill:remove-from-sprint,remove-from-sprint,false,bmm-sm,,"Remove items from a sprint and return to unassigned backlog.",_bmad-output/implementation-artifacts,"sprint plan",
+ma-skills,4-implementation,Cleanup Done,cleanup-done,,skill:cleanup-done,cleanup-done,false,bmm-sm,,"Archive done items — move files to done/ and remove from sprint/backlog.",_bmad-output/implementation-artifacts,"archived items",
+ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog using multiple criteria — severity, value, dependencies.",_bmad-output/implementation-artifacts,"backlog",

package/lib/bmad-extension/skills/add-sprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-sprint
-description: Guided workflow to create a new sprint with capacity limits for realistic sprint planning
+description: Guided workflow to create a new sprint entity with capacity limits, optional ISO dates, and structured YAML schema for sprint planning
 type: skill
 triggers:
   - "add sprint"
@@ -9,17 +9,35 @@ triggers:
 
 # 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">
@@ -34,32 +52,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'">
@@ -68,45 +125,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