ma-agents 3.4.8 → 3.5.0

package/lib/bmad-extension/workflows/remove-from-sprint/workflow.md

@@ -0,0 +1,164 @@
+# Remove-from-Sprint Workflow
+
+Guided workflow to move sprint items back to the backlog in the unified `sprint-status.yaml` using reverse movement semantics (inverse of `add-to-sprint`).
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Resolve the sprint-status.yaml path: check `_bmad/bmm/config.yaml` for `sprint_management_path`; if not set, default to `_bmad-output/implementation-artifacts/sprint-status.yaml`</action>
+  <action>Read the resolved `sprint-status.yaml` — the unified single source of truth for sprint and backlog state</action>
+  <check if="file does not exist">
+    <output>No sprint-status.yaml found. Run sprint planning first to initialize the file (`/bmad-sprint-planning`).</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Parse the full file: metadata fields (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`), `epics` section, `backlog` array, and `sprints` map</action>
+  <action>Store parsed data as {{sprint_file}}</action>
+</step>
+
+<step n="1" goal="Identify sprints with removable items">
+  <action>Scan the `sprints` map in {{sprint_file}}. For each sprint entry, check if its `items` array has at least one element.</action>
+  <action>Build {{sprints_with_items}} = list of sprints where `items` is non-empty, ordered by sprint key (sprint-1, sprint-2, …)</action>
+  <check if="{{sprints_with_items}} is empty">
+    <output>No sprints with assigned items found. Nothing to remove.</output>
+    <action>Exit workflow</action>
+  </check>
+  <check if="exactly one sprint has items">
+    <action>Auto-select that sprint. Store as {{selected_sprint_id}} and {{selected_sprint}}</action>
+    <output>Auto-selected the only sprint with items: **{{selected_sprint.name}}** ({{selected_sprint.status}})</output>
+  </check>
+  <check if="multiple sprints have items">
+    <output>
+## Sprints with Assigned Items
+
+| # | Sprint ID | Name | Status | Capacity | Items |
+|---|-----------|------|--------|----------|-------|
+{{#each sprints_with_items}}
+| {{@index+1}} | {{id}} | {{name}} | {{status}} | {{capacity}} | {{items.length}} |
+{{/each}}
+    </output>
+    <ask>Select sprint to remove items from (enter number):</ask>
+    <action>Store selected sprint as {{selected_sprint_id}} and {{selected_sprint}}</action>
+  </check>
+  <check if="selected_sprint.status == 'closed'">
+    <output>Cannot remove items from a closed sprint. Closed sprints are immutable (schema section 6.7). Use `/close-sprint` or `/cleanup-done` to disposition items in closed sprints.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="2" goal="Display sprint items and identify eligible items for removal">
+  <action>Read {{selected_sprint.items}} array</action>
+  <action>Partition items into two groups:
+    - {{ineligible_items}} = items where `status` is `done` or `cancelled`
+    - {{eligible_items}} = all other items (status: ready-for-dev, in-progress, review, on-hold, backlog)
+  </action>
+  <check if="{{ineligible_items}} is non-empty">
+    <output>
+> **Note:** {{ineligible_items.length}} done/cancelled item(s) cannot be removed. Use `/cleanup-done` or `/close-sprint` to archive them.
+>
+> Ineligible items: {{#each ineligible_items}}{{id}} ({{status}}){{#unless @last}}, {{/unless}}{{/each}}
+    </output>
+  </check>
+  <check if="{{eligible_items}} is empty">
+    <output>All items in **{{selected_sprint.name}}** are done or cancelled. Use `/cleanup-done` or `/close-sprint` to archive them.</output>
+    <action>Exit workflow</action>
+  </check>
+  <output>
+## Items in {{selected_sprint.name}} — Eligible for Removal
+
+| # | ID | Title | Type | Epic | Status | Severity |
+|---|----|-------|------|------|--------|----------|
+{{#each eligible_items}}
+| {{@index+1}} | {{id}} | {{title}} | {{type}} | {{epic ?? "—"}} | {{status}} | {{severity ?? "—"}} |
+{{/each}}
+
+*Sprint capacity: {{selected_sprint.items.length}}/{{selected_sprint.capacity}}*
+  </output>
+</step>
+
+<step n="3" goal="Select items to remove">
+  <ask>Which items do you want to remove from the sprint? Enter item numbers (comma-separated) or "all" to remove all eligible items:</ask>
+  <check if="user enters 'all'">
+    <action>Set {{items_to_remove}} = all items in {{eligible_items}}</action>
+  </check>
+  <check if="user enters item numbers">
+    <action>Resolve entered numbers against the eligible_items table. Validate all numbers are in range.</action>
+    <check if="any number is out of range">
+      <output>Invalid selection: number(s) out of range. Please enter valid item numbers from the table above.</output>
+      <goto step="3" />
+    </check>
+    <action>Set {{items_to_remove}} = items at the specified positions in {{eligible_items}}</action>
+  </check>
+</step>
+
+<step n="4" goal="Confirmation — warn about status resets">
+  <output>
+## Confirm Removal from {{selected_sprint.name}}
+
+The following items will be moved back to the backlog:
+
+| ID | Title | Current Status | Backlog Status After |
+|----|-------|---------------|----------------------|
+{{#each items_to_remove}}
+| {{id}} | {{title}} | {{status}} | ready-for-dev{{#if (ne status "ready-for-dev")}} ⚠️ status will be reset{{/if}} |
+{{/each}}
+
+**Effect on sprint capacity:** {{selected_sprint.items.length}} → {{selected_sprint.items.length - items_to_remove.length}} / {{selected_sprint.capacity}} items
+
+**Note:** Each removed item will be appended to the end of the backlog with `status: ready-for-dev`. Run `/prioritize-backlog` after this operation to reorder the backlog.
+  </output>
+  <check if="any item_to_remove has status != 'ready-for-dev'">
+    <output>
+> **Warning:** {{#each items_to_remove}}{{#if (ne status "ready-for-dev")}}**{{id}}** is currently `{{status}}` — its status will be reset to `ready-for-dev`. Any in-progress work tracking will be lost.{{/if}}{{/each}}
+    </output>
+  </check>
+  <ask>Options: [c] Confirm removal / [x] Cancel:</ask>
+  <check if="user selects 'x'">
+    <output>Removal cancelled — no changes made.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="5" goal="Execute reverse movement — atomic write">
+  <action>Load current {{sprint_file}} state (re-read if needed to get latest data)</action>
+  <action>Determine {{current_max_priority}}:
+    - If {{sprint_file.backlog}} is empty, set {{current_max_priority}} = 0
+    - Otherwise, set {{current_max_priority}} = max(item.priority for item in sprint_file.backlog)
+  </action>
+  <action>For each item in {{items_to_remove}} (in the order they appear in the sprint's items array):
+    1. REMOVE the item object from {{selected_sprint_id}}.items in the sprints map
+    2. INCREMENT {{current_max_priority}} by 1
+    3. SET item.status = "ready-for-dev"
+    4. ADD item.priority = {{current_max_priority}}
+    5. APPEND the item (with fields: id, type, epic, title, priority, status, severity) to the backlog array
+  </action>
+  <action>After all items are moved: renumber ALL backlog items' priority values sequentially (1..N) to match their array positions. First item in array gets priority 1, second gets priority 2, etc. Track each removed item's final renumbered priority in {{items_to_remove[n].final_priority}} for use in the summary.</action>
+  <action>Set {{sprint_file.last_updated}} = current ISO-8601 timestamp (e.g., "2026-04-06T12:00:00Z")</action>
+  <action>Write the complete updated sprint-status.yaml in a SINGLE atomic operation. The write MUST include all three sections (epics, backlog, sprints) and all metadata fields. Preserve the `generated` timestamp unchanged.</action>
+</step>
+
+<step n="6" goal="Display removal summary">
+  <output>
+## Removal Complete
+
+**Sprint:** {{selected_sprint.name}}
+**Items removed this session:** {{items_to_remove.length}}
+**Updated sprint capacity:** {{selected_sprint.items.length - items_to_remove.length}}/{{selected_sprint.capacity}} items
+
+### Removed Items — Now in Backlog
+
+| ID | Title | Backlog Priority | Status |
+|----|-------|-----------------|--------|
+{{#each items_to_remove}}
+| {{id}} | {{title}} | {{final_priority}} | ready-for-dev |
+{{/each}}
+
+**Updated backlog count:** {{sprint_file.backlog.length}} items
+
+**Next Steps:**
+- Run `/prioritize-backlog` to reorder the backlog after removals
+- Run `/add-to-sprint` to reassign items to a sprint
+- Run `/sprint-status-view` to view the updated sprint status
+  </output>
+</step>
+
+</workflow>

package/lib/bmad-extension/workflows/sprint-status-view/workflow.md

@@ -1,4 +1,166 @@
-<!-- This workflow has been superseded by lib/bmad-extension/skills/sprint-status-view/SKILL.md -->
-<!-- Resolved via skill:sprint-status-view in module-help.csv -->
+# Sprint Status View
 
-See `lib/bmad-extension/skills/sprint-status-view/SKILL.md` for the current workflow.
+Display a formatted, read-only dashboard of all sprint, backlog, and epic data from the unified `sprint-status.yaml` file.
+
+> **READ-ONLY SKILL:** This skill NEVER writes to `sprint-status.yaml` or any other file. It is purely a display/reporting skill.
+
+---
+
+## Step 1 — Load sprint-status.yaml
+
+Resolve the path to `sprint-status.yaml` using the BMAD config:
+- Check `_bmad/bmm/config.yaml` for `sprint_management_path` (if configured for multi-repo mode)
+- Default path: `_bmad-output/implementation-artifacts/sprint-status.yaml`
+
+Read the file. If it does not exist:
+- Output: "No sprint-status.yaml found. Run `/bmad-sprint-planning` to initialize."
+- Exit without error.
+
+Parse all sections from the file:
+- **Metadata:** `project`, `last_updated` (plus `generated`, `project_key`, `tracking_system`, `story_location` if present)
+- **`epics`** — map of epic entries (keys: `epic-N`)
+- **`backlog`** — array of unassigned item objects
+- **`sprints`** — map of sprint entries (keys: `sprint-N`)
+
+If the file exists but uses the old flat `development_status` schema (no `epics`/`backlog`/`sprints` sections), output:
+"sprint-status.yaml uses the pre-Epic-17 schema. Run `/bmad-sprint-planning` to migrate to the unified schema."
+Then exit.
+
+---
+
+## Step 2 — Classify Sprints
+
+Partition the `sprints` map into three groups:
+- **active** — entries where `status: active`
+- **planning** — entries where `status: planning`
+- **closed** — entries where `status: closed`
+
+Sort each group by sprint key (`sprint-N`) ascending by numeric value of N.
+
+---
+
+## Step 3 — Render Header
+
+Output:
+
+```
+# Sprint Status — {project}
+*Last updated: {last_updated}*
+
+---
+```
+
+---
+
+## Step 4 — Render Active Sprints
+
+If there are active sprints, output a `## Active Sprints` section header.
+
+For each active sprint (sorted by key ascending):
+
+1. Sprint header:
+   ```
+   ### {sprint.name}
+   **Status:** active | **Capacity:** {items.length} / {capacity} | **Start:** {start or "—"} | **End:** {end or "—"}
+   ```
+   If `items.length > capacity`, append inline: `⚠️ over capacity by {items.length - capacity} item(s)`
+
+2. Items table (if items array is non-empty):
+   ```
+   | Item | Title | Type | Status | Severity |
+   |------|-------|------|--------|----------|
+   | {id} | {title} | Story | {status} | — |
+   | {id} | {title} | Bug   | {status} | {severity} |
+   ```
+   - Type column: use "Story" for `type: story`, "Bug" for `type: bug`
+   - Severity column: show severity value for bugs, "—" for stories
+
+3. If items array is empty, output: `*(No items assigned to this sprint)*`
+
+---
+
+## Step 5 — Render Planning Sprints
+
+If there are planning sprints, output a `## Planning Sprints` section header.
+
+For each planning sprint (sorted by key ascending), use the same format as Step 4 with `status: planning`.
+
+---
+
+## Step 6 — Render Closed Sprint Summaries
+
+If there are closed sprints, output a `## Closed Sprints` section header followed by a summary table:
+
+```
+| Sprint | Items | Start | End |
+|--------|-------|-------|-----|
+| {sprint.name} | {items.length} items (archived) | {start or "—"} | {end or "—"} |
+```
+
+Do NOT list individual items within closed sprints (collapsed view by default).
+
+---
+
+## Step 7 — Render Backlog
+
+Count total backlog items: `{backlog.length}`.
+
+Output a `## Backlog — {backlog.length} items` section header.
+
+If backlog is empty, output: `*(No items in backlog)*`
+
+Otherwise, output a table in array order (position = priority):
+
+```
+| # | Item | Title | Type | Status | Severity |
+|---|------|-------|------|--------|----------|
+| 1 | {id} | {title} | Story | {status} | — |
+| 2 | {id} | {title} | Bug   | {status} | {severity} |
+```
+
+- `#` column: 1-based position in the array (= priority rank)
+- Severity column: show severity for bugs, "—" for stories
+
+---
+
+## Step 8 — Render Epics Overview
+
+Output a `## Epics` section header.
+
+If the `epics` map is empty, output: `*(No epics defined)*`
+
+Otherwise, for each epic in the map (sorted by key ascending by numeric value of N):
+
+1. Count items referencing this epic across all sections:
+   - Scan `backlog` items where `epic == N` (N = epic number, e.g., `17` for `epic-17`)
+   - Scan all `sprints[*].items` where `epic == N`
+   - Tally counts by status
+
+2. Output a table row:
+   ```
+   | Epic | Status | Retrospective | Items (active) |
+   |------|--------|---------------|----------------|
+   | epic-4 | on-hold | optional | {count} total ({status breakdown}) |
+   ```
+   - Status breakdown: list non-zero status counts, e.g., "2 in-progress, 1 ready-for-dev"
+   - If no items reference the epic, show "0 total"
+   - `retrospective` field: show value or "—" if null
+
+---
+
+## Step 9 — Render Alerts (Conditional)
+
+Scan for alert conditions:
+
+1. **Over-capacity sprints:** Any sprint where `items.length > capacity`
+   - Alert: `Over capacity: {sprint.name} is over capacity by {items.length - capacity} item(s) ({items.length} / {capacity})`
+
+2. **Stale in-progress items:** Items with `status: in-progress` in **active** sprints where the sprint's `start` date is more than 14 days before today
+   - Alert: `Stale in-progress: {item.id} has been in-progress for {N} days ({sprint.name} started {start})`
+
+3. **Empty active sprints:** Active sprints with zero items
+   - Alert: `Empty active sprint: {sprint.name} is active but has no items assigned`
+
+If NO alert conditions exist, omit this section entirely (do not output "No alerts" or any placeholder).
+
+If alerts exist, output a `## Alerts` section header followed by a bulleted list.

package/mil498/README.md

@@ -0,0 +1,4 @@
+MIL-STD-498 DIDs converted to HTML.
+
+For more information (what is it, why do you need it), see the article at [http://kkovacs.eu/free-project-management-template-mil-std-498]!
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.4.8",
+  "version": "3.5.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {

package/skills/add-sprint/SKILL.md

@@ -0,0 +1,165 @@
+# Add Sprint
+
+Guided workflow to create a new sprint entry in the `sprints` section of `sprint-status.yaml` with capacity limits, optional ISO dates, and auto-incremented sprint ID.
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Locate `sprint-status.yaml` at `_bmad-output/implementation-artifacts/sprint-status.yaml` relative to the project root</action>
+  <check if="sprint-status.yaml does not exist">
+    <output>No sprint-status.yaml found. Run sprint planning first to initialize the file.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Read and parse the full file: `epics`, `backlog`, and `sprints` sections plus all metadata fields</action>
+  <action>Store parsed content as {{file_content}}</action>
+</step>
+
+<step n="1" goal="Auto-increment sprint ID and derive default name">
+  <action>Extract all keys from the `sprints` map in {{file_content}}</action>
+  <action>Parse numeric suffix from each key matching pattern `sprint-N` (e.g., `sprint-1` → 1, `sprint-3` → 3)</action>
+  <check if="no sprint keys exist in sprints map">
+    <action>Set {{new_number}} = 1</action>
+    <action>Set {{default_name}} = "Sprint 1"</action>
+  </check>
+  <check if="sprint keys exist">
+    <action>Find the highest numeric suffix among all sprint keys; store as {{max_number}}</action>
+    <action>Set {{new_number}} = {{max_number}} + 1</action>
+    <action>Look up the sprint entry whose key has suffix {{max_number}}; read its `name` field</action>
+    <action>If the name matches pattern "Sprint N" or "Sprint N — description" or "Sprint N - description", set {{default_name}} = "Sprint {{new_number}}"; otherwise set {{default_name}} = "Sprint {{new_number}}" as safe fallback</action>
+  </check>
+  <action>Set {{sprint_id}} = "sprint-{{new_number}}"</action>
+  <action>Set {{sprint_name}} = {{default_name}}</action>
+  <output>
+Auto-generated Sprint ID: **{{sprint_id}}**
+Default Sprint Name: **{{sprint_name}}**
+  </output>
+  <ask>Sprint ID: {{sprint_id}} — press Enter to accept or type a different number:</ask>
+  <check if="user provides a different number">
+    <action>Set {{sprint_id}} = "sprint-{user_number}"</action>
+    <action>Check if {{sprint_id}} already exists as a key in the `sprints` map</action>
+    <check if="sprint_id already exists">
+      <output>Sprint ID {{sprint_id}} already exists in sprint-status.yaml. Please choose a different number.</output>
+      <goto step="1" sub="re-prompt for number only" />
+    </check>
+    <action>Update {{sprint_name}} default to "Sprint {user_number}"</action>
+  </check>
+  <ask>Sprint name: '{{sprint_name}}' — press Enter to accept or type a different name:</ask>
+  <check if="user provides a different name">
+    <action>Set {{sprint_name}} = user input</action>
+  </check>
+</step>
+
+<step n="2" goal="Gather capacity (required)">
+  <action>Explain: capacity is the maximum number of items (stories + bugs) that can be assigned to this sprint. This is advisory — skills will warn but not block when exceeded.</action>
+  <ask>What is the sprint capacity? (Enter a positive integer)</ask>
+  <action>Store input as {{capacity_input}}</action>
+  <action>Validate {{capacity_input}} is a positive integer (greater than zero, no decimals, no non-numeric characters)</action>
+  <check if="{{capacity_input}} is NOT a positive integer">
+    <output>Invalid capacity: "{{capacity_input}}". Capacity must be a positive integer (e.g., 5, 10, 20). Zero and negative values are not allowed.</output>
+    <goto step="2" />
+  </check>
+  <action>Store as {{capacity}} (integer)</action>
+</step>
+
+<step n="3" goal="Gather optional start and end dates">
+  <ask>Optional — Sprint start date (ISO format YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store as {{start_input}}</action>
+  <check if="start_input is not empty">
+    <action>Validate {{start_input}} matches ISO date pattern YYYY-MM-DD (4-digit year, 2-digit month 01-12, 2-digit day 01-31)</action>
+    <check if="start_input does not match ISO date pattern">
+      <output>Invalid date format: "{{start_input}}". Please use YYYY-MM-DD (e.g., 2026-04-15).</output>
+      <goto step="3" sub="re-prompt for start date only" />
+    </check>
+    <action>Store as {{start}} = {{start_input}}</action>
+  </check>
+  <check if="start_input is empty">
+    <action>Store as {{start}} = "" (empty string)</action>
+  </check>
+  <ask>Optional — Sprint end date (ISO format YYYY-MM-DD, press Enter to skip):</ask>
+  <action>Store as {{end_input}}</action>
+  <check if="end_input is not empty">
+    <action>Validate {{end_input}} matches ISO date pattern YYYY-MM-DD</action>
+    <check if="end_input does not match ISO date pattern">
+      <output>Invalid date format: "{{end_input}}". Please use YYYY-MM-DD (e.g., 2026-04-28).</output>
+      <goto step="3" sub="re-prompt for end date only" />
+    </check>
+    <check if="end_input is before start and start is not empty">
+      <output>Warning: end date {{end_input}} is before start date {{start}}. Continuing as requested.</output>
+    </check>
+    <action>Store as {{end}} = {{end_input}}</action>
+  </check>
+  <check if="end_input is empty">
+    <action>Store as {{end}} = "" (empty string)</action>
+  </check>
+</step>
+
+<step n="4" goal="Confirmation">
+  <output>
+## New Sprint Summary — Please Confirm
+
+- Sprint ID: {{sprint_id}}
+- Sprint Name: {{sprint_name}}
+- Capacity: {{capacity}} items
+- Start Date: {{start}} *(empty if skipped)*
+- End Date: {{end}} *(empty if skipped)*
+- Status: planning
+- Items: [] *(empty — use /add-to-sprint to assign items)*
+- Target: sprint-status.yaml sprints section
+  </output>
+  <ask>Confirm creation? [y] Yes / [n] Cancel / [e] Edit a field</ask>
+  <check if="user selects 'e'">
+    <ask>Which field to edit? (id / name / capacity / start / end)</ask>
+    <check if="field == 'id'"><goto step="1" /></check>
+    <check if="field == 'name'">
+      <ask>Sprint name (or press Enter to use "{{sprint_name}}"):</ask>
+      <check if="input is not empty"><action>Set {{sprint_name}} = user input</action></check>
+      <goto step="4" />
+    </check>
+    <check if="field == 'capacity'"><goto step="2" /></check>
+    <check if="field == 'start'"><goto step="3" sub="start date only" /></check>
+    <check if="field == 'end'"><goto step="3" sub="end date only" /></check>
+  </check>
+  <check if="user selects 'n'">
+    <output>Sprint creation cancelled.</output>
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<step n="5" goal="Write sprint entry to sprint-status.yaml">
+  <action>Re-read the current content of `_bmad-output/implementation-artifacts/sprint-status.yaml` to get the latest state</action>
+  <action>Get the current ISO-8601 timestamp for `last_updated`</action>
+  <action>Append a new entry to the `sprints` map with this structure:
+```yaml
+  {{sprint_id}}:
+    name: "{{sprint_name}}"
+    status: planning
+    capacity: {{capacity}}
+    start: "{{start}}"
+    end: "{{end}}"
+    items: []
+```
+  </action>
+  <action>Preserve the `epics` section unchanged</action>
+  <action>Preserve the `backlog` section unchanged</action>
+  <action>Preserve all existing entries in the `sprints` section unchanged</action>
+  <action>Update the `last_updated` metadata field to the current ISO-8601 timestamp</action>
+  <action>Preserve the `generated` field unchanged (never modify)</action>
+  <action>Write the complete updated file to `_bmad-output/implementation-artifacts/sprint-status.yaml` in a single atomic write (read-modify-write pattern)</action>
+</step>
+
+<step n="6" goal="Summary output">
+  <output>
+Sprint created successfully!
+
+- Sprint: {{sprint_name}} ({{sprint_id}})
+- Capacity: {{capacity}} items
+- Status: planning
+
+Next Steps:
+- Use /add-to-sprint to assign backlog items to this sprint
+- Use /modify-sprint to update sprint details later
+- Use /sprint-status-view to view sprint progress
+  </output>
+</step>
+
+</workflow>

package/skills/add-sprint/skill.json

@@ -0,0 +1,7 @@
+{
+  "name": "add-sprint",
+  "version": "1.0.0",
+  "description": "Guided workflow to create a new sprint entry in the sprints section of sprint-status.yaml with capacity limits, optional ISO dates, and auto-incremented ID",
+  "category": "workflow",
+  "tags": ["sprint-management", "add-sprint", "capacity"]
+}