ma-agents 3.6.2 → 3.9.0

package/skills/bmad-sprint-planning/SKILL.md

@@ -27,6 +27,47 @@ Attempt to read project name from `_bmad/bmm/config.yaml` (field `project_name`)
 
 ---
 
+## 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>

package/skills/bmad-sprint-status/SKILL.md

@@ -8,6 +8,45 @@ Analyze sprint health, surface risk flags, and recommend next actions from the u
 
 ---
 
+## 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 the active sprint for project `{jira_project_key}` at `{jira_url}` and retrieve all sprint issues with their statuses. Query backlog issue count. Query epic progress (completed stories per epic). Map Jira sprint states and issue statuses to canonical vocabulary per the status mapping below. Use this data for health analysis — no writes. Status mapping: Backlog/Open → backlog, To Do/Selected for Development → ready-for-dev, In Progress → in-progress, In Review/Code Review → review, Done/Resolved → done, On Hold/Blocked → on-hold, Won't Do/Cancelled → 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 steps below.
+
+---
+
 ## Invocation Modes
 
 This skill supports three execution modes. Set `mode` before invoking:

package/skills/cleanup-done/SKILL.md

@@ -8,6 +8,45 @@ Keeps the active sprint view lean by archiving completed and cancelled work. Pre
 
 ---
 
+## 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 issues in project `{jira_project_key}` at `{jira_url}` with status Done/Resolved/Closed. For each such issue that maps to a local story file at `{story_location}/{id}.md`: transition the issue to the resolved/done Jira workflow state if not already there (using the issue transition API). Then move the local story file to `{story_location}/done/{id}.md` — this local file operation always executes regardless of backend. Note: Jira issues are NOT deleted; they remain in Jira as resolved.
+      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">

package/skills/close-sprint/SKILL.md

@@ -4,6 +4,45 @@ Close an active sprint — archive done/cancelled items, disposition incomplete
 
 **Schema Reference:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (Story 17.9)
 
+## 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 issues in the active sprint for project `{jira_project_key}` at `{jira_url}`. For done/cancelled items: transition each to resolved/done Jira state using the issue transition API; then move each corresponding local story file from `{story_location}/{id}.md` to `{story_location}/done/{id}.md` (local file operation — always executes). For incomplete items (not done/cancelled): remove each issue from the sprint using the "remove issue from sprint" operation (returns them to board backlog). Then close the sprint using the sprint close API.
+      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">

package/skills/generate-backlog/SKILL.md

@@ -11,6 +11,47 @@ This skill reads `epics.md` and `bug-*.md` files and writes the `backlog` and `e
 
 ---
 
+## 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 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 Jira epics (issues of type Epic) in project `{jira_project_key}` at `{jira_url}` to build the epics map. Query all backlog issues (Story and Bug type, not assigned to any active sprint) in project `{jira_project_key}`. For any backlog items not already present in Jira, create new Jira issues (one API call per item). For existing items whose fields have changed, update them. Use the Jira field mapping: item.title → issue summary, item.type → issue type (story → Story, bug → Bug), item.status → Jira workflow status (see status mapping below), item.priority → issue priority. 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.
+
+---
+
 <workflow>
 
 <step n="1" goal="Load existing sprint-status.yaml state">

package/skills/modify-sprint/SKILL.md

@@ -5,6 +5,45 @@ Guided workflow to modify an existing sprint's metadata (name, capacity, dates,
 > **Scope:** This skill modifies sprint **metadata only** — name, capacity, start date, end date, and status.
 > To assign items to a sprint, use `/add-to-sprint`. To remove items, use `/remove-from-sprint`.
 
+## 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: Find the sprint by name or ID in the board for project `{jira_project_key}` at `{jira_url}`. Update the sprint's name, dates, or goal using the sprint update API. If the status is being changed to `active`: start the sprint using the sprint start API (transitions the sprint from future/planning to active state — enforces the single-active-sprint constraint).
+      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">

package/skills/prioritize-backlog/SKILL.md

@@ -2,6 +2,45 @@
 
 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">

package/skills/remove-from-sprint/SKILL.md

@@ -2,6 +2,45 @@
 
 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`).
 
+## 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: Find the Jira issue matching the item ID in project `{jira_project_key}` at `{jira_url}` (search by issue key or summary). Remove the issue from its current sprint using the "remove issue from sprint" operation, returning it to the board backlog.
+      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">

package/skills/sprint-status-view/SKILL.md

@@ -6,6 +6,45 @@ Display a formatted, read-only dashboard of all sprint, backlog, and epic data f
 
 ---
 
+## 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 sprint data for project `{jira_project_key}` at `{jira_url}`: active sprint with all its issues and their statuses, backlog issues count and list, epic summary and progress. Map Jira sprint states to canonical vocabulary (future → planning, active → active, closed → closed). Map Jira issue statuses to canonical statuses per the status mapping below. Use this data for the display — no writes. Status mapping: Backlog/Open → backlog, To Do/Selected for Development → ready-for-dev, In Progress → in-progress, In Review/Code Review → review, Done/Resolved → done, On Hold/Blocked → on-hold, Won't Do/Cancelled → 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 steps below.
+
+---
+
 ## Step 1 — Load sprint-status.yaml
 
 Read `_bmad-output/implementation-artifacts/sprint-status.yaml`.

package/skills/story-status-lookup/SKILL.md

@@ -9,19 +9,42 @@ Do not flag bugs in WIP code. Do flag bugs in delivered code.
 
 ---
 
-## Backend Configuration
-
-Before performing a lookup, check the project context for the configured sprint management backend.
-
-**Where to look (in priority order):**
-1. `project-context.md` in the project root — look for a `sprint_management` field
-2. The root directives file (`CLAUDE.md`, `.cursor/rules`, or equivalent for the active agent)
-3. If neither defines a backend, **default to `file-system`**
-
-| `sprint_management` value | Backend |
-|---|---|
-| `file-system` or not set | Read `sprint-status.yaml` (see below) |
-| `jira` | *(Future — see Jira section below)* |
+## Backend Routing
+
+Before performing a lookup, 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: Search for the Jira issue matching the item ID in project `{jira_project_key}` at `{jira_url}` (search by issue key or summary match). Return the issue's current Jira status. Map to canonical vocabulary: Backlog/Open → backlog, To Do/Selected for Development → ready-for-dev, In Progress → in-progress, In Review/Code Review → review, Done/Resolved/Closed → done, On Hold/Blocked → on-hold, Won't Do/Cancelled → cancelled. If the issue is not found in Jira, report "not found" and classify as WIP.
+      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 steps below.
 
 ---
 
@@ -78,12 +101,6 @@ Never guess or assume delivered status. When in doubt, WIP.
 
 ---
 
-## Future: Jira Backend
-
-When `sprint_management: jira` is set in the project context, this extension point applies:
-
-- Jira base URL, project key, and credentials will be defined in the project context or environment config
-- Query the Jira issue status API for the relevant issue key
-- Map the Jira workflow status to delivered/WIP using a status mapping defined in the project context
+## Jira Backend
 
-**This backend is not yet implemented.** When Jira support is added, update this skill with the lookup procedure and status mapping. The file-system backend remains the default fallback if Jira is unreachable.
+When `tracking_system: jira` is configured in `sprint-status.yaml`, the Backend Routing section above handles the lookup. The Jira backend queries the issue by key or summary and maps the Jira workflow status to the canonical vocabulary. The file-system backend remains the fallback if the Jira operation fails and the user chooses to switch backends.

package/.ma-agents.json

@@ -1,10 +0,0 @@
-{
-  "manifestVersion": "1.2.0",
-  "agent": null,
-  "agents": [
-    null
-  ],
-  "scope": "project",
-  "skills": {},
-  "profile": "standard"
-}

package/AGENTS.md

@@ -1,97 +0,0 @@
-<!-- Generated by ma-agents. Edit outside the MA-AGENTS-START/END markers to preserve your changes. -->
-# Project Agent Instructions
-
-This file is auto-discovered by OpenCode and any agent that respects `AGENTS.md`.
-It establishes universal safety rules, text-vs-file discipline, and BMAD phase
-discipline for every agent operating in this project.
-
-## Universal Rules
-
-The universal rules block below is stamped and maintained by ma-agents. Edit
-outside the HTML-comment `MA-AGENTS` start and end markers to preserve your
-own additions — content inside the markers is regenerated on every install.
-
-<!-- MA-AGENTS-START -->
-# AI Agent Skills - Planning Instruction
-
-You have access to a library of skills in your skills directory. Before starting any task:
-
-1. Read the skill manifest at .opencode/skills/MANIFEST.yaml
-2. Based on the task description, select which skills are relevant
-3. Read only the selected skill files
-4. Then proceed with the task
-
-Always load skills marked with always_load: true.
-Do not load skills that are not relevant to the current task.
-
-## Respond in TEXT vs. create FILES
-
-Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
-
-- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
-- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
-- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
-- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
-- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
-
-## BMAD phase discipline
-
-BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
-
-- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
-- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
-- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.
-<!-- MA-AGENTS-END -->
-
-## Critical Behavior Rules
-
-These rules are non-negotiable across every profile and every agent.
-
-- **Never create files in `~/.claude/` or any user home directory.** All
-  project artifacts must land inside the current working directory. Home-
-  directory writes cross-contaminate between projects and are a common source
-  of secret/config leakage.
-- **Never write outside the project root without an explicit user request
-  naming the absolute path.** "Write to disk" means the project, not the
-  operator's machine.
-- **Do not modify files you did not read first.** Read the current content
-  before proposing or performing an edit — blind writes silently destroy user
-  work.
-
-## BMAD Phase Declaration
-
-BMAD-METHOD organizes work into four phases. Respect the currently declared
-phase; do not skip ahead to the next phase without a phase transition signal
-from the user, the active skill, or the story status.
-
-- **Discovery / PM (analysis, planning).** Deliverables: product briefs,
-  PRDs, market and domain research, epics and stories lists. Do NOT produce
-  code, architecture diagrams, or implementation artifacts in this phase.
-  When asked "what do you think", respond in text.
-- **Architecture.** Deliverables: solution design, component boundaries,
-  data-flow, interface contracts. Do NOT write application code or skill
-  implementations. Narrate decisions and capture them as documents.
-- **Tech Lead / Stories.** Deliverables: individual story files with full
-  acceptance criteria, task breakdowns, and dev notes. Do NOT begin
-  implementation — stories are contracts the implementer consumes later.
-- **Implementation.** Deliverables: code, tests, and the Dev Agent Record on
-  the story file. At this phase, write files. Do NOT retroactively fabricate
-  planning documents for code that already exists — flag the gap instead.
-
-When no phase is declared (no active skill, no story in progress, no explicit
-user statement), ask before assuming.
-
-## Project BMAD Output Structure
-
-BMAD artifacts live under `_bmad-output/` (or the paths configured in
-`_bmad/bmm/config.yaml` when present). The install-time resolver logs the
-resolved paths on each run; consult that log output if in doubt.
-
-- **Planning artifacts** — PRDs, product briefs, market and domain research.
-- **Architecture artifacts** — solution design, component boundaries. May be
-  co-located with planning artifacts when no separate directory is configured.
-- **Implementation artifacts (stories)** — individual story files and their
-  Dev Agent Records.
-
-Always consult the `MANIFEST.yaml` referenced inside the universal block above
-for the full list of installed skills and their locations.

package/AiAudit.md

@@ -1,12 +0,0 @@
-# AI Audit Trail
-
-| Date | Task | Tokens (est.) |
-|------|------|---------------|
-| 2026-03-18 | Story 9.2: JSON Injection — Create opencode.json When Absent. Added MA_AGENTS_SOURCE constant, json-merge branch in updateAgentInstructions(), and 12-test fixture suite. | In: ~18K / Out: ~6K |
-| 2026-04-06 | Story 17.11: Rework add-to-sprint skill with unified sprint-status.yaml movement semantics. Created IDE skill (skills/add-to-sprint/), rewrote BMAD extension skill and workflow, updated module-help.csv. Full develop + code review + PR cycle. | In: ~35K / Out: ~12K |
-| 2026-04-06 | Story 17.12: Rework remove-from-sprint skill with unified sprint-status.yaml reverse movement semantics. Created IDE skill, BMAD extension skill, workflow wrapper, module-help.csv row. Full develop + code review cycle. PR #17. | In: ~30K / Out: ~14K |
-| 2026-04-06 | Story 17.13: Rework sprint-status-view skill for unified sprint-status.yaml three-section schema. Created IDE skill (skills/sprint-status-view/), rewrote BMAD SKILL.md and workflow.md, updated module-help.csv. Full develop + code review + fix cycle. PR #18. | In: ~40K / Out: ~16K |
-| 2026-04-06 | Story 17.14: Create cleanup-done skill from scratch (greenfield). IDE skill + BMAD extension with 9-step archival workflow for unified schema. Full develop + code review + fix cycle. PR #19. | In: ~35K / Out: ~14K |
-| 2026-04-06 | Story 17.18: Rework bmad-dev-story as BMAD extension override. Replaced flat development_status map operations with cross-section item search on unified sprint-status.yaml schema. Full develop + code review + fix cycle. PR #21. | In: ~25K / Out: ~12K |
-| 2026-04-06 | Story 17.20: Rework bmad-sprint-status skill as BMAD extension override + IDE skill for unified sprint-status.yaml schema. Analysis-focused health summary with 10 risk conditions, backlog health, epic progress, sprint history, 3 execution modes. Full develop + code review + PR cycle. PR #23. | In: ~30K / Out: ~15K |
-| 2026-04-06 | Story 17.22: Jira Adapter Pattern — design specification story. Created adapter-pattern-spec.md (8 sections: detection logic, interface contract, skill template, skill mapping, Jira requirements, pipeline integration, extensibility). Full develop + code review + fix cycle. PR #26. | In: ~20K / Out: ~10K |