ma-agents 3.6.2 → 3.9.0

package/lib/bmad-extension-plugin/skills/prioritize-backlog/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: prioritize-backlog
+description: Reprioritize backlog items in sprint-status.yaml using multiple criteria -- severity, business value, dependencies, type, age
+type: skill
+triggers:
+  - "prioritize backlog"
+  - "reprioritize backlog"
+  - "sort backlog"
+---
+
+# Prioritize Backlog
+
+Reprioritize backlog items in `sprint-status.yaml` using multiple criteria: severity, business value, dependencies, type, and age.
+
+## 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`:
+   a. Perform the Jira operation: Query all backlog issues (not assigned to any sprint) for project `{jira_project_key}` at `{jira_url}`. Apply the prioritization criteria specified by the user. Reorder the issues in the board backlog by updating the issue rank/priority order (use whatever ranking capability is available on the board — NextGen board issue ranking or classic board priority field). Map canonical priority back to Jira fields.
+      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.
+
+---
+
+<workflow>
+
+<step n="0" goal="Load configuration and validate file existence">
+  <action>Determine the path to `sprint-status.yaml`:
+  1. Check `_bmad/bmm/config.yaml` for an `artifacts_path` or `sprint_status_path` override.
+  2. If not set, default to `_bmad-output/implementation-artifacts/sprint-status.yaml`.
+  </action>
+  <action>Read the resolved `sprint-status.yaml` path.</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 — do not create any file.</action>
+  </check>
+  <action>Parse the full file: read `epics`, `backlog`, and `sprints` sections plus all metadata fields (`generated`, `last_updated`, `project`, `project_key`, `tracking_system`, `story_location`). Store the entire parsed structure as {{file_data}} for later atomic write.</action>
+  <check if="legacy backlog.yaml exists in the same directory as sprint-status.yaml">
+    <output>Note: Legacy backlog.yaml detected. Run migration to consolidate.</output>
+    <action>Continue — do NOT read from or write to the legacy file. Operate on sprint-status.yaml only.</action>
+  </check>
+  <check if="{{file_data.backlog}} is empty or null">
+    <output>Backlog is empty. Nothing to prioritize.</output>
+    <action>Exit workflow — do not modify the file.</action>
+  </check>
+  <action>Store {{backlog_items}} = {{file_data.backlog}} (the array of items to work with).</action>
+  <action>Store {{original_order}} = copy of {{backlog_items}} with their current priority values, for use in the change summary later.</action>
+</step>
+
+<step n="1" goal="Display current backlog order">
+  <action>Read {{backlog_items}} in their current array order (position 0 = highest priority).</action>
+  <output>
+## Current Backlog ({{backlog_items.length}} items)
+
+| Priority | ID | Title | Type | Epic | Severity | Status |
+|---|---|---|---|---|---|---|
+{{#each backlog_items}}
+| {{priority}} | {{id}} | {{title}} | {{type}} | {{#if epic}}epic-{{epic}}{{else}}—{{/if}} | {{severity or "—"}} | {{status}} |
+{{/each}}
+
+*Note: Items assigned to sprints are not shown — only unassigned backlog items are listed here.*
+  </output>
+</step>
+
+<step n="2" goal="Choose prioritization mode">
+  <ask>Select a prioritization mode:
+
+**[f] Full** — Interactive: generates a suggested order, presents current vs proposed side-by-side. You review and approve (or adjust) before any write occurs.
+**[q] Quick** — Automated: applies default multi-criteria rules immediately, then shows a summary of what moved.
+**[a] Auto-suggest** — Read-only: shows the suggested order with per-item rationale. No file is modified.
+**[x] Cancel** — Exit without changes.
+
+Choice:</ask>
+  <check if="user selects 'x'">
+    <output>Cancelled — no changes made.</output>
+    <action>Exit workflow.</action>
+  </check>
+  <action>Store {{selected_mode}} = user choice.</action>
+</step>
+
+<step n="3" goal="Multi-criteria prioritization analysis">
+  <action>For each item in {{backlog_items}}, compute a composite priority score using the following weighted criteria (highest weight listed first):</action>
+
+  <action>**1. Severity weight (highest impact):**
+  - `severity: critical` → +40 points
+  - `severity: high`     → +30 points
+  - `severity: medium`   → +10 points
+  - `severity: low`      → +5 points
+  - `severity: null`     → +0 points (no adjustment for stories)
+  </action>
+
+  <action>**2. Business value weight:**
+  - Use the item's existing `priority` value as a signal for current business value ranking. Items with lower `priority` values (higher priority) receive a proportional boost: score += max(0, ({{backlog_items.length}} - current_priority + 1) * 2). This preserves existing prioritization signals while allowing other criteria to override.
+  - Items from lower-numbered epics (or `epic: null`) receive a slight additional boost: score += max(0, (20 - epic_number)) * 1, treating null as epic 0.
+  </action>
+
+  <action>**3. Dependency weight:**
+  - Read `_bmad-output/planning-artifacts/epics.md` if it exists to identify explicit inter-story dependencies.
+  - Within the same epic, items with lower story numbers are assumed to be prerequisites for higher-numbered stories. Items that block others get a +15 point boost.
+  - Items that are explicitly blocked by other UNASSIGNED backlog items get a -10 point adjustment (they cannot proceed anyway).
+  - If epics.md cannot be read or does not define explicit dependencies, use only the intra-epic ordering heuristic.
+  </action>
+
+  <action>**4. Type weight (tiebreaker):**
+  - `type: bug` → +3 points (bugs receive a slight boost over stories at equal composite score)
+  - `type: story` → +0 points
+  </action>
+
+  <action>**5. Age weight (starvation prevention — weakest signal):**
+  - Items from epics with lower epic numbers receive +1 point per 5 epic numbers below the maximum epic in the backlog (e.g., if max epic is 17, epic-12 gets +1, epic-7 gets +2).
+  - Items with `epic: null` are treated as oldest (receive the maximum age boost among all items).
+  - This is a tiebreaker only — it prevents starvation but does not override higher-priority signals.
+  </action>
+
+  <action>Compute {{composite_score}} for each item = severity_score + business_value_score + dependency_score + type_score + age_score.</action>
+  <action>Sort items by {{composite_score}} descending (highest score = priority 1). Break ties by current `priority` value (lower = higher priority stays higher).</action>
+  <action>Store {{suggested_order}} = sorted list of items. Store {{rationale_map}} = per-item map of score breakdown and reason summary.</action>
+</step>
+
+<step n="3a" goal="Full mode: present comparison and get approval" condition="{{selected_mode}} == 'f'">
+  <output>
+## Prioritization Analysis: Current vs Suggested
+
+| Current Priority | ID | Suggested Priority | Change | Key Rationale |
+|---|---|---|---|---|
+{{#each original_order}}
+| {{priority}} | {{id}} | {{suggested_position}} | {{change_indicator}} | {{rationale}} |
+{{/each}}
+
+*Items highlighted with ↑ move up, ↓ move down, = stay in place.*
+  </output>
+  <ask>Options:
+- **[a]** Accept the suggested order as-is
+- **[m]** Manually adjust — enter item IDs in your preferred order (comma-separated)
+- **[c]** Cancel — exit without changes
+
+Choice:</ask>
+  <check if="user selects 'c'">
+    <output>Cancelled — no changes made.</output>
+    <action>Exit workflow.</action>
+  </check>
+  <check if="user selects 'a'">
+    <action>Set {{final_order}} = {{suggested_order}}.</action>
+  </check>
+  <check if="user selects 'm'">
+    <ask>Enter item IDs in your preferred priority order (highest priority first), comma-separated. You MUST include all {{backlog_items.length}} items — no duplicates or omissions allowed:
+Example: 17-10-rework-generate-backlog, 17-11-rework-add-to-sprint, ...</ask>
+    <action>Parse the user-provided list into {{manual_order_ids}}.</action>
+    <action>Validate:
+    - Count must equal {{backlog_items.length}} (no missing items)
+    - All IDs must exist in {{backlog_items}} (no unknown IDs)
+    - No duplicate IDs
+    </action>
+    <check if="validation fails">
+      <output>Invalid input: {{validation_error}}. Please re-enter the complete list of all {{backlog_items.length}} item IDs in your preferred order.</output>
+      <action>Repeat the manual-entry prompt until valid input is received or user cancels.</action>
+    </check>
+    <action>Reorder {{backlog_items}} to match {{manual_order_ids}} sequence. Set {{final_order}} = reordered list.</action>
+  </check>
+  <action>Proceed to Step 4 with {{final_order}}.</action>
+</step>
+
+<step n="3b" goal="Quick mode: apply suggested order automatically" condition="{{selected_mode}} == 'q'">
+  <action>Set {{final_order}} = {{suggested_order}}.</action>
+  <action>Proceed to Step 4 with {{final_order}}.</action>
+</step>
+
+<step n="3c" goal="Auto-suggest mode: display suggestions without writing" condition="{{selected_mode}} == 'a'">
+  <output>
+## Suggested Backlog Order (Read-Only — No Changes Written)
+
+| New Priority | ID | Title | Old Priority | Change | Rationale |
+|---|---|---|---|---|---|
+{{#each suggested_order}}
+| {{new_priority}} | {{id}} | {{title}} | {{old_priority}} | {{change_indicator}} | {{rationale}} |
+{{/each}}
+
+**Summary:**
+- Items that would move up: {{move_up_count}}
+- Items that would move down: {{move_down_count}}
+- Items unchanged: {{unchanged_count}}
+
+Suggestions displayed. No changes written. Run again in Full or Quick mode to apply.
+  </output>
+  <action>Exit workflow — do NOT proceed to Step 4.</action>
+</step>
+
+<step n="4" goal="Apply reordering and persist">
+  <action>Take {{final_order}} (from Full or Quick mode).</action>
+  <action>Renumber `priority` field on each item sequentially: position 0 in the array gets `priority: 1`, position 1 gets `priority: 2`, and so on through position N-1 gets `priority: N`. This keeps the denormalized index in sync with array position (schema section 3.3).</action>
+  <action>Get the current ISO-8601 timestamp (format: YYYY-MM-DDTHH:MM:SS). Update {{file_data.last_updated}} to this timestamp.</action>
+  <action>Preserve {{file_data.generated}} unchanged.</action>
+  <action>Preserve {{file_data.epics}} section unchanged — do NOT modify any epic entries.</action>
+  <action>Preserve {{file_data.sprints}} section unchanged — do NOT modify any sprint entries or items within sprints.</action>
+  <action>Set {{file_data.backlog}} = {{final_order}} (the reordered array with renumbered priorities).</action>
+  <action>Write the complete updated {{file_data}} back to the resolved sprint-status.yaml path in a single atomic write (read-modify-write pattern). This single write replaces the file entirely — no partial updates.</action>
+</step>
+
+<step n="5" goal="Display summary output">
+  <action>Compute change summary by comparing {{original_order}} (old positions) against {{final_order}} (new positions).</action>
+  <output>
+## Reprioritization Complete
+
+**Mode:** {{mode_label}} ({{current_datetime}})
+**Items reordered:** {{backlog_items.length}} total
+
+### Changes Made
+
+| ID | Title | Old Priority | New Priority | Direction |
+|---|---|---|---|---|
+{{#each changed_items}}
+| {{id}} | {{title}} | {{old_priority}} | {{new_priority}} | {{direction}} |
+{{/each}}
+
+{{#if unchanged_items.length > 0}}
+**Unchanged ({{unchanged_items.length}} items):** {{unchanged_ids_list}}
+{{/if}}
+
+**sprint-status.yaml updated successfully.**
+
+**Next steps:**
+- `/add-to-sprint` — Assign the top-priority backlog items to the current sprint
+- `/sprint-status-view` — View overall sprint progress and capacity
+  </output>
+</step>
+
+</workflow>

package/lib/bmad-extension-plugin/skills/prioritize-backlog/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: prioritize-backlog
+module: ma-skills

package/lib/bmad-extension-plugin/skills/project-context-expansion/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: project-context-expansion
+description: Post-retrospective workflow to update project-context.md with discovered patterns and conventions
+type: skill
+triggers:
+  - "project context expansion"
+  - "expand project context"
+---
+
+# Project Context Expansion Workflow
+
+Post-retrospective companion workflow to update `_bmad-output/project-context.md` with
+patterns and conventions discovered during the sprint.
+
+Run this workflow at the end of `/bmad-retrospective` to close the living document lifecycle loop.
+The agent proposes additions; the human decides what gets written.
+
+<workflow>
+
+<step n="1" goal="Check whether project-context.md exists">
+
+  <action>Check if `_bmad-output/project-context.md` exists in the project root</action>
+
+  <check if="file does NOT exist">
+    <output>
+ℹ️ **No project-context.md found.**
+
+`_bmad-output/project-context.md` does not exist in this project yet.
+
+To create it, either:
+- Run `npx ma-agents install` at the project level (auto-generates on first install)
+- Run `/bmad-generate-project-context` to create it manually
+
+Skipping project-context expansion — nothing to update.
+    </output>
+    <action>Exit workflow</action>
+  </check>
+
+  <check if="file exists">
+    <output>
+✅ Found `_bmad-output/project-context.md` — proceeding with expansion review.
+    </output>
+  </check>
+
+</step>
+
+<step n="2" goal="Read and present the current Project-Specific Rules section">
+
+  <action>Read the complete contents of `_bmad-output/project-context.md`</action>
+
+  <action>Extract the `## Project-Specific Rules` section:
+    - Find the line starting with `## Project-Specific Rules`
+    - Read all content until the next `##` section header (or end of file)
+    - Store as {{current_rules_content}}
+  </action>
+
+  <check if="{{current_rules_content}} contains only the TODO comment or is effectively empty">
+    <action>Set {{rules_are_empty}} = true</action>
+  </check>
+
+  <check if="{{current_rules_content}} contains substantive rules">
+    <action>Set {{rules_are_empty}} = false</action>
+  </check>
+
+  <output>
+## Current Project-Specific Rules
+
+{{current_rules_content}}
+
+---
+
+I will now review the retrospective discussion to propose additions to this section.
+  </output>
+
+</step>
+
+<step n="3" goal="Gather sprint patterns — from retrospective context or user input">
+
+  <action>Check whether there is active retrospective context in this session (i.e., this workflow
+  was invoked immediately after running /bmad-retrospective and discussion content is available).
+  </action>
+
+  <check if="retrospective context IS present in this session">
+    <action>Use the retrospective discussion to identify patterns, conventions, and lessons.
+    Skip the user prompt below — proceed directly to the proposal step.
+    </action>
+  </check>
+
+  <check if="retrospective context is NOT present (workflow invoked cold or standalone)">
+    <output>
+ℹ️ **No retrospective session detected in this context.**
+
+This workflow is designed to run after `/bmad-retrospective`, but it can also be used
+standalone to capture any conventions or patterns you've observed.
+    </output>
+    <ask>
+Briefly describe the patterns or conventions you want to add to Project-Specific Rules.
+For example: "agents kept omitting error handling in async functions" or
+"we decided all PRs need a test-plan section in the description".
+
+You can also just say "run retrospective first" to cancel.
+    </ask>
+    <check if="user says 'run retrospective first' or equivalent cancel">
+      <output>
+ℹ️ To get the most value, run `/bmad-retrospective` first, then invoke `/project-context-expansion`
+at the end of that session. No changes made.
+      </output>
+      <action>Exit workflow</action>
+    </check>
+    <action>Store the user-described patterns as {{sprint_patterns}} and use them as the source
+    material for the proposal in the next action below.
+    </action>
+  </check>
+
+  <action>Based on the retrospective discussion OR user-described patterns, identify items that
+  should become standing rules for AI agents — specifically:
+    - Coding conventions agents got wrong or needed correction on during the sprint
+    - Patterns agents should consistently apply in this project
+    - Architectural decisions that agents must respect (and that are not obvious from the code)
+    - Testing or review conventions specific to this project
+    - Gotchas or anti-patterns agents kept producing that should be explicitly prohibited
+    - Workflow or communication rules specific to this team's practices
+  </action>
+
+  <action>Filter OUT anything that belongs in other sections:
+    - Technology Stack updates → belongs in `## Technology Stack` (use `/bmad-generate-project-context`)
+    - Mandatory pre-task rules → belongs in `## AI Agent Mandatory Rules` (set at install time)
+    - Do NOT propose changes to any section other than `## Project-Specific Rules`
+  </action>
+
+  <check if="no relevant patterns found from retrospective">
+    <output>
+ℹ️ **No new rules to propose.**
+
+Based on the retrospective discussion, no patterns were identified that would add value
+as standing rules in `## Project-Specific Rules`. The section is already up to date.
+
+If you noticed patterns the agents got wrong, you can manually edit
+`_bmad-output/project-context.md` to add your own rules at any time.
+    </output>
+    <action>Exit workflow</action>
+  </check>
+
+  <action>Draft proposed additions as clear, imperative rules:
+    - Each rule is a single actionable statement (e.g., "Always use X when Y")
+    - Rules are specific enough to change agent behavior, not vague principles
+    - Each rule is distinct — no overlap with existing rules
+    - Store as {{proposed_additions}}
+  </action>
+
+  <output>
+## Proposed Additions to Project-Specific Rules
+
+Based on patterns from this sprint's retrospective, here are the additions I recommend:
+
+{{proposed_additions}}
+
+---
+
+**Review these carefully.** These additions will be appended to `## Project-Specific Rules`
+in `_bmad-output/project-context.md` and will govern all future AI agent sessions.
+  </output>
+
+</step>
+
+<step n="4" goal="Human review and confirmation gate">
+
+  <ask>
+Review the proposed additions above.
+
+Options:
+- **[y] Accept all** — append all proposed additions as shown
+- **[n] Reject all** — skip without any changes
+- **[e] Edit** — describe which rules to add, remove, or reword before writing
+  </ask>
+
+  <check if="user selects 'n'">
+    <output>
+❌ **Expansion skipped.** No changes were made to `_bmad-output/project-context.md`.
+    </output>
+    <action>Exit workflow</action>
+  </check>
+
+  <check if="user selects 'e'">
+    <ask>Describe your edits — which rules to keep, drop, or reword:</ask>
+    <action>Apply user edits to {{proposed_additions}}</action>
+    <action>Re-display the revised proposal</action>
+    <ask>Proceed with this revised version? [y] Yes / [n] Cancel:</ask>
+    <check if="user selects 'n'">
+      <output>
+❌ **Expansion cancelled.** No changes were made to `_bmad-output/project-context.md`.
+      </output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+</step>
+
+<step n="5" goal="Write approved additions to Project-Specific Rules only">
+
+  <action>Read the current full contents of `_bmad-output/project-context.md` again (to ensure freshness)</action>
+
+  <action>Locate the `## Project-Specific Rules` section:
+    - Find the line starting with `## Project-Specific Rules`
+    - Identify the end of the section (next `##` header or end of file)
+    - Preserve all existing content in the section — do NOT remove or reorder existing rules
+  </action>
+
+  <action>Append the approved additions at the END of the `## Project-Specific Rules` section,
+  before the next `##` header. Insert a blank line separator if the section is not empty.
+  </action>
+
+  <action>CRITICAL CONSTRAINTS — do NOT touch any other section:
+    - Do NOT modify `## AI Agent Mandatory Rules`
+    - Do NOT modify `## Technology Stack`
+    - Do NOT modify any other section
+    - Do NOT reformat or reorganize the file
+    - Only append to `## Project-Specific Rules`
+  </action>
+
+  <action>Save the updated `_bmad-output/project-context.md`</action>
+
+  <output>
+✅ **Project-Specific Rules updated successfully!**
+
+- **File:** `_bmad-output/project-context.md`
+- **Rules added:** {{count_of_added_rules}}
+
+The new rules will be active in all AI agent sessions that load `project-context.md`
+via `critical_actions` (all BMAD agents load it automatically on activation).
+
+**Next:** Commit `_bmad-output/project-context.md` to version control so the rules
+are shared across the team and persist across sessions.
+  </output>
+
+</step>
+
+</workflow>

package/lib/bmad-extension-plugin/skills/project-context-expansion/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: project-context-expansion
+module: ma-skills