ma-agents 3.6.2 → 3.9.0

package/lib/bmad-extension-plugin/skills/bmad-sprint-planning/sprint-status-template.yaml

@@ -0,0 +1,89 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the unified three-section schema format.
+# The actual file will be generated/refreshed from your epics and bug files.
+#
+# Schema version: 1.0 (Story 17.9)
+# Architecture: Decision P2-11
+#
+# SECTIONS:
+#   epics   — map keyed by epic-N; regenerated each planning run (with status preservation)
+#   backlog — array of items (stories + bugs); additive — new items appended, existing preserved
+#   sprints — map keyed by sprint-N; NEVER modified by this skill
+#
+# STATUS DEFINITIONS:
+# ===================
+# Epic Status:   backlog → in-progress → done  (on-hold: bidirectional; cancelled: terminal)
+# Item Status:   backlog → ready-for-dev → in-progress → review → done
+#                (on-hold: bidirectional pause; cancelled: terminal)
+# Retrospective: optional → done  (null: not applicable)
+
+generated: "2026-01-15T10:00:00Z"
+last_updated: "2026-01-15T10:00:00Z"
+project: "Example Project"
+project_key: NOKEY
+tracking_system: file-system
+story_location: "_bmad-output/implementation-artifacts"
+
+# ── Epics ──────────────────────────────────────────────────────────────────────
+# Map keyed by epic-N. Fully regenerated each run; epic statuses are never downgraded.
+epics:
+  epic-1:
+    status: in-progress
+    retrospective: optional
+  epic-2:
+    status: backlog
+    retrospective: optional
+  epic-3:
+    status: on-hold
+    retrospective: null
+
+# ── Backlog ───────────────────────────────────────────────────────────────────
+# Ordered array — position 0 = highest priority. Priority field must match position.
+# Only items NOT in a sprint and NOT archived in done/ appear here.
+backlog:
+  - id: "1-2-account-management"
+    type: story
+    epic: 1
+    title: "Account Management"
+    priority: 1
+    status: ready-for-dev
+    severity: null
+  - id: "BUG-login-crash"
+    type: bug
+    epic: null
+    title: "Fix login crash on empty password"
+    priority: 2
+    status: backlog
+    severity: critical
+  - id: "2-1-personality-system"
+    type: story
+    epic: 2
+    title: "Personality System"
+    priority: 3
+    status: backlog
+    severity: null
+  - id: "2-2-chat-interface"
+    type: story
+    epic: 2
+    title: "Chat Interface"
+    priority: 4
+    status: backlog
+    severity: null
+
+# ── Sprints ───────────────────────────────────────────────────────────────────
+# Map keyed by sprint-N. This skill NEVER modifies the sprints section.
+# Use add-sprint, add-to-sprint, modify-sprint, close-sprint to manage sprints.
+sprints:
+  sprint-1:
+    name: "Sprint 1 — Foundation"
+    status: active
+    capacity: 4
+    start: "2026-01-15"
+    end: "2026-01-28"
+    items:
+      - id: "1-1-user-authentication"
+        type: story
+        epic: 1
+        title: "User Authentication"
+        status: in-progress
+        severity: null

package/lib/bmad-extension-plugin/skills/bmad-sprint-planning/workflow.md

@@ -0,0 +1,413 @@
+# Sprint Planning Workflow
+
+**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
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `planning_artifacts`
+- `date` as system-generated current ISO-8601 datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `tracking_system` = `file-system`
+- `project_key` = `NOKEY`
+- `story_location` = `{implementation_artifacts}`
+- `epics_location` = `{planning_artifacts}`
+- `epics_pattern` = `*epic*.md`
+- `status_file` = `{implementation_artifacts}/sprint-status.yaml`
+- `done_folder` = `{implementation_artifacts}/done/`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/epics/index.md` + parts (sharded) | FULL_LOAD |
+| Bugs | `{implementation_artifacts}/bug-*.md` | FULL_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## Backend Routing
+
+Before executing any file-system operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   > "This operation will create/update Jira sprints and items in bulk. If it fails mid-way, Jira may be in partial state. The Jira server URL is `{jira_url}` and project key is `{jira_project_key}` (from `_bmad/bmm/config.yaml`). Proceed?"
+
+   a. Perform the Jira operation: Query all epics, backlog issues, sprint definitions, and sprint items for project `{jira_project_key}` at `{jira_url}` (multiple sequential read calls). For the write phase: create new Jira sprints for each sprint definition not already in Jira (one API call per sprint). Create or update Jira issues for each item in the plan (one API call per item). Map item fields as follows: title → issue summary, type → issue type (story → Story, bug → Bug), status → Jira workflow status (see status mapping below), priority → issue priority/rank. Map sprint fields: name → sprint name, start_date → sprint start date, end_date → sprint end date. Status mapping: backlog → Backlog/Open, ready-for-dev → To Do/Selected for Development, in-progress → In Progress, review → In Review/Code Review, done → Done/Resolved, on-hold → On Hold/Blocked, cancelled → Won't Do/Cancelled.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+<action>Load `{project_context}` for project-wide patterns and conventions (if exists)</action>
+<action>Communicate in `{communication_language}` with `{user_name}`</action>
+
+**Epic Discovery Process:**
+
+1. Search for whole document first — look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file in `{epics_location}`
+2. If whole document not found, look for `epics/index.md` (sharded version)
+3. If sharded version found:
+   - Read `index.md` to understand structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`)
+   - Process all epics and stories from combined content
+4. If both whole and sharded versions 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: keywords like "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 key: `1-1-user-authentication`
+
+<action>Build complete inventory: `{{all_epics}}` (list of epic numbers + titles + detected statuses) and `{{all_stories}}` (list of story objects: `id`, `epic_num`, `title`)</action>
+</step>
+
+<step n="2" goal="Scan bug files">
+<action>Glob `{implementation_artifacts}/bug-*.md` to find all bug story files</action>
+<check if="no bug files found">
+  <action>Set `{{all_bugs}}` = [] (empty list)</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 from filename: strip path and `.md` extension, then prefix with `BUG-` after removing `bug-` prefix (e.g., `bug-path-spaces.md` → `BUG-path-spaces`)</action>
+  <action>Set `{{all_bugs}}` = list of bug objects: `id`, `title`, `severity` (default `medium` if missing), `status` (default `backlog` if missing)</action>
+</check>
+</step>
+
+<step n="3" goal="Mode detection — bootstrap vs refresh">
+<check if="`{status_file}` does NOT exist">
+  <action>Set `{{mode}}` = `bootstrap`</action>
+  <action>Proceed to Step 4 then Step 5</action>
+</check>
+<check if="`{status_file}` EXISTS">
+  <action>Set `{{mode}}` = `refresh`</action>
+  <action>Read existing `{status_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 `{done_folder}` for archived files. Build `{{done_item_ids}}` = set of basenames (without `.md`) from all files in the done folder (e.g., `done/1-1-user-auth.md` → `1-1-user-auth`)</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` (Story 17.14) 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` = `{date}` (current ISO-8601 datetime)
+- `last_updated` = `{date}`
+- `project` = `{project_name}`
+- `project_key` = `NOKEY`
+- `tracking_system` = `file-system`
+- `story_location` = `{story_location}`
+
+**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 a candidate list</action>
+<action>For each candidate item:
+  - Skip if item ID is in `{{done_item_ids}}`
+  - For stories: detect status by checking if `{story_location}/{story_id}.md` exists → `ready-for-dev`; else → `backlog`
+  - Assign `priority` = sequential index (1, 2, 3...) ordered by: critical bugs first, then by epic order
+</action>
+
+**Ordering rules:**
+1. Bugs with `severity: critical` — highest priority group
+2. Stories by epic order, then story number within epic
+3. Bugs with `severity: high`, `medium`, `low` — after stories
+
+<action>Build backlog array with each 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 if set)
+  - `severity`: `null` for stories, value for bugs
+</action>
+
+**`sprints` section:** empty map `{}`
+
+<action>Write complete `sprint-status.yaml` to `{status_file}` with the following structure:</action>
+
+```yaml
+generated: "{date}"
+last_updated: "{date}"
+project: "{project_name}"
+project_key: NOKEY
+tracking_system: file-system
+story_location: "{story_location}"
+
+epics:
+  epic-1:
+    status: {status}
+    retrospective: optional
+  # ... all epics
+
+backlog:
+  - id: "{id}"
+    type: {story|bug}
+    epic: {num|null}
+    title: "{title}"
+    priority: {n}
+    status: {status}
+    severity: {null|critical|high|medium|low}
+  # ... all non-done items
+
+sprints: {}
+```
+</step>
+
+<step n="6" goal="Refresh mode — additive merge">
+<check if="`{{mode}}` != `refresh`">
+  <action>Skip this step</action>
+</check>
+
+<action>Read existing `{{existing_file}}`:
+  - Extract `generated` timestamp (preserve — never change)
+  - Extract existing `epics` section
+  - Extract existing `backlog` array
+  - Extract existing `sprints` map
+</action>
+
+**Regenerate `epics` section (reference data — always overwritten with preservation):**
+<action>For each epic in `{{all_epics}}`:
+  - If epic already exists in `{{existing_file.epics}}`:
+    - Apply never-downgrade rule for `status`: keep existing if it's more advanced than detected
+    - Status advancement order: `backlog` < `in-progress` < `done` (never downgrade; `on-hold` and `cancelled` are sticky)
+    - Preserve existing `retrospective` value
+  - If epic is NEW (not in existing file):
+    - Set `status` = detected status from narrative (default `backlog`)
+    - Set `retrospective` = `optional`
+</action>
+
+**Status preservation rules (never downgrade):**
+- If existing `status` is `done` → keep `done` regardless
+- If existing `status` is `in-progress` and detected is `backlog` → keep `in-progress`
+- If existing `status` is `on-hold` → keep `on-hold` (sticky)
+- If existing `status` is `cancelled` → keep `cancelled` (terminal state)
+- Otherwise → use detected status
+
+**Build exclusion sets:**
+<action>
+  - `{{existing_backlog_ids}}` = set of all `id` values in existing `backlog` array
+  - `{{sprint_item_ids}}` = set of all `id` values in any `sprints[*].items` array
+  - `{{excluded_ids}}` = union of `{{existing_backlog_ids}}`, `{{sprint_item_ids}}`, `{{done_item_ids}}`
+</action>
+
+**Identify new items:**
+<action>For each story in `{{all_stories}}`:
+  - If story ID is NOT in `{{excluded_ids}}` → it is a NEW item to append
+</action>
+<action>For each bug in `{{all_bugs}}`:
+  - If bug ID is NOT in `{{excluded_ids}}` → it is a NEW item to append
+</action>
+
+**Append new items to backlog:**
+<action>Calculate `{{max_priority}}` = maximum `priority` value in existing backlog (0 if empty)</action>
+<action>For each new item (stories first in epic order, then bugs):
+  - Assign `priority` = `{{max_priority}}` + sequential increment (1, 2, 3...)
+  - For stories: detect status by checking if `{story_location}/{story_id}.md` exists → `ready-for-dev`; else → `backlog`
+  - For bugs: use status from frontmatter or default `backlog`
+  - Build item with same schema as bootstrap mode
+</action>
+
+**Preserve existing sections:**
+- `backlog`: keep all existing items unchanged (status, priority, all fields) + append new items at end
+- `sprints`: pass through unchanged — do NOT modify sprint data
+
+**Update metadata:**
+- `last_updated` = `{date}` (current ISO-8601 datetime)
+- `generated` = preserve original value (NEVER change)
+
+<action>Write updated `sprint-status.yaml` to `{status_file}` (atomic read-modify-write)</action>
+</step>
+
+<step n="7" goal="Validation">
+<action>Run validation checklist (see checklist.md):</action>
+
+- [ ] File is valid YAML syntax
+- [ ] Exactly 6 metadata fields present: `generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`
+- [ ] Exactly 3 data sections: `epics`, `backlog`, `sprints`
+- [ ] Every epic in `epics.md` appears in the `epics` section
+- [ ] Every story in `epics.md` appears in exactly one location: `backlog`, a sprint's `items`, or `done/` folder
+- [ ] No item ID appears in more than one active location (single-location invariant)
+- [ ] All epic `status` values are legal: `backlog`, `in-progress`, `done`, `on-hold`, `cancelled`
+- [ ] All item `status` values are legal: `backlog`, `ready-for-dev`, `in-progress`, `review`, `done`, `on-hold`, `cancelled`
+- [ ] Backlog `priority` values are sequential 1..N matching array positions
+- [ ] `sprints` section is unchanged from existing (refresh mode only)
+- [ ] `generated` timestamp is unchanged (refresh mode only)
+
+<check if="validation fails">
+  <output>
+## Validation Errors
+
+The following issues were detected:
+
+{{#each validation_errors}}
+- {{message}}
+{{/each}}
+
+Please review and correct the file before proceeding.
+  </output>
+</check>
+</step>
+
+<step n="8" goal="Report summary">
+<action>Count and display totals:</action>
+
+<output>
+## Sprint Planning Complete
+
+**Mode:** {{mode}} ({{#if bootstrap}}first run — file created{{else}}refresh — file updated{{/if}})
+**File:** `{status_file}`
+
+### 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 `{status_file}`
+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)
+```
+
+### 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.
+
+### 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
+```

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

@@ -0,0 +1,6 @@
+---
+name: bmad-sprint-status
+description: 'Summarize sprint health, surface risks, and recommend next actions from the unified sprint-status.yaml. Use when the user says "check sprint status" or "show sprint health"'
+---
+
+Follow the instructions in ./workflow.md.

package/lib/bmad-extension-plugin/skills/bmad-sprint-status/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: bmad-sprint-status
+module: ma-skills