ma-agents 3.8.0 → 3.9.0

package/README.md

@@ -2,12 +2,11 @@
 
 A universal NPX tool to install AI coding agent skills. Write skills once, install them across Claude Code, Gemini, Copilot, Cline, Cursor, Kilocode, and Roo Code.
 
-## What's New in v3.8.0
+## What's New in v3.9.0
 
-- **BMAD-METHOD v6.5.0** — upgraded from 6.3.0; 42-platform baseline, TOML customization coexistence confirmed
-- **`--agent` flag fixed** — `--agent claude-code` now correctly scopes the entire install (skills, BMAD update, instruction-block stamping) to that tool only; previously it was ignored in non-interactive mode
-- **Stale Copilot skills dir cleanup** — upgrading from an older version that used `.github/copilot/skills/` now automatically removes the old directory when `.github/skills/` is populated
-- **Plugin resolver verified** — bundle resolves via BMAD's Strategy 1 (module.yaml); no package.json needed; 134 skills install cleanly in all CI matrix configurations
+- **Jira sprint backend** — the install wizard now offers Jira as a 4th sprint management option. Select Jira to provide your Jira URL and project key; credentials are stored in `_bmad/bmm/config.yaml`. All 13 sprint management skills automatically route operations to Jira or file-system based on `tracking_system` in `sprint-status.yaml`.
+- **Skill-level Jira routing** — every sprint skill reads `tracking_system` and routes to the Jira backend via whatever Jira-capable tool is available in your agent context (MCP server, plugin, or native integration). Failure prompts offer retry or permanent switch to file management.
+- **Routing alignment (3.8.1)** — copilot, roo-code, and kilocode persona skills now land in `.agents/skills/` to match `bmad-method 6.5.0`'s unified target directory.
 
 See [CHANGELOG.md](CHANGELOG.md) for full release notes.
 

package/bin/cli.js

@@ -380,6 +380,46 @@ async function collectRemotePath(concern) {
   }
 }
 
+async function collectJiraConfig() {
+  // Collect Jira server URL
+  let jiraUrl;
+  while (true) {
+    const { url } = await prompts({
+      type: 'text',
+      name: 'url',
+      message: 'Jira server URL (e.g. https://mycompany.atlassian.net):'
+    });
+    if (!url || !url.trim()) {
+      console.log(chalk.red('  Jira server URL cannot be empty. Please try again.'));
+      continue;
+    }
+    jiraUrl = url.trim();
+    break;
+  }
+
+  // Collect Jira project key
+  let jiraProjectKey;
+  while (true) {
+    const { key } = await prompts({
+      type: 'text',
+      name: 'key',
+      message: 'Jira project key (e.g. MYPROJ):'
+    });
+    if (!key || !key.trim()) {
+      console.log(chalk.red('  Jira project key cannot be empty. Please try again.'));
+      continue;
+    }
+    if (!/^[A-Z][A-Z0-9]+$/.test(key.trim())) {
+      console.log(chalk.red('  Jira project key must be uppercase alphanumeric (e.g. MYPROJ). Please try again.'));
+      continue;
+    }
+    jiraProjectKey = key.trim();
+    break;
+  }
+
+  return { mode: 'jira', jiraUrl, jiraProjectKey };
+}
+
 function normalizePath(p) {
   return p.replace(/\\/g, '/');
 }
@@ -428,24 +468,43 @@ function writeRepoLayoutConfig(layout) {
   const configPath = path.join(process.cwd(), '_bmad', 'bmm', 'config.yaml');
   try {
     if (!fs.existsSync(configPath)) {
-      console.log(chalk.yellow('  _bmad/bmm/config.yaml not found — skipping config write'));
-      return;
+      // Create an empty file so writeConfigField can append to it
+      fs.mkdirSync(path.join(process.cwd(), '_bmad', 'bmm'), { recursive: true });
+      fs.writeFileSync(configPath, '', 'utf-8');
     }
     let content = fs.readFileSync(configPath, 'utf-8');
     const projectRoot = process.cwd();
     const kbPortable = toPortablePath(layout.knowledgebase.path, projectRoot);
-    const spPortable = toPortablePath(layout.sprintManagement.path, projectRoot);
     const kbPath = kbPortable.portable;
-    const spPath = spPortable.portable;
     content = writeConfigField(content, 'knowledgebase_path', kbPath);
-    content = writeConfigField(content, 'sprint_management_path', spPath);
-    // Derive workflow-consumable artifact paths from layout paths (relative when base is relative)
-    const planningArtifacts = kbPath === '.' ? '_bmad-output/planning-artifacts' : `${kbPath}/_bmad-output/planning-artifacts`;
-    const implArtifacts = spPath === '.' ? '_bmad-output/implementation-artifacts' : `${spPath}/_bmad-output/implementation-artifacts`;
-    content = writeConfigField(content, 'planning_artifacts', planningArtifacts);
-    content = writeConfigField(content, 'implementation_artifacts', implArtifacts);
-    fs.writeFileSync(configPath, content, 'utf-8');
-    console.log(chalk.gray(`  Config: knowledgebase_path="${kbPath}", sprint_management_path="${spPath}"`));
+
+    const spMode = layout.sprintManagement.mode;
+    if (spMode === 'jira') {
+      // Jira backend: write sprint_backend + Jira config; no sprint_management_path
+      content = writeConfigField(content, 'sprint_backend', 'jira');
+      content = writeConfigField(content, 'jira_url', layout.sprintManagement.jiraUrl);
+      content = writeConfigField(content, 'jira_project_key', layout.sprintManagement.jiraProjectKey);
+      // Derive artifact paths from kb only
+      const planningArtifacts = kbPath === '.' ? '_bmad-output/planning-artifacts' : `${kbPath}/_bmad-output/planning-artifacts`;
+      const implArtifacts = '_bmad-output/implementation-artifacts';
+      content = writeConfigField(content, 'planning_artifacts', planningArtifacts);
+      content = writeConfigField(content, 'implementation_artifacts', implArtifacts);
+      fs.writeFileSync(configPath, content, 'utf-8');
+      console.log(chalk.gray(`  Config: knowledgebase_path="${kbPath}", sprint_backend=jira, jira_url="${layout.sprintManagement.jiraUrl}", jira_project_key="${layout.sprintManagement.jiraProjectKey}"`));
+    } else {
+      // File-system backend
+      const spPortable = toPortablePath(layout.sprintManagement.path, projectRoot);
+      const spPath = spPortable.portable;
+      content = writeConfigField(content, 'sprint_backend', 'file-system');
+      content = writeConfigField(content, 'sprint_management_path', spPath);
+      // Derive workflow-consumable artifact paths from layout paths (relative when base is relative)
+      const planningArtifacts = kbPath === '.' ? '_bmad-output/planning-artifacts' : `${kbPath}/_bmad-output/planning-artifacts`;
+      const implArtifacts = spPath === '.' ? '_bmad-output/implementation-artifacts' : `${spPath}/_bmad-output/implementation-artifacts`;
+      content = writeConfigField(content, 'planning_artifacts', planningArtifacts);
+      content = writeConfigField(content, 'implementation_artifacts', implArtifacts);
+      fs.writeFileSync(configPath, content, 'utf-8');
+      console.log(chalk.gray(`  Config: knowledgebase_path="${kbPath}", sprint_backend=file-system, sprint_management_path="${spPath}"`));
+    }
   } catch (e) {
     console.log(chalk.red(`  Cannot write config.yaml: ${e.message}`));
   }
@@ -453,6 +512,7 @@ function writeRepoLayoutConfig(layout) {
 
 function writeProjectLayoutYaml(layout) {
   const layoutPath = path.join(process.cwd(), '_bmad-output', 'project-layout.yaml');
+  // Only skip writing when BOTH concerns are truly same-repo (jira requires config recording)
   const bothSame = layout.knowledgebase.mode === 'same' && layout.sprintManagement.mode === 'same';
 
   if (bothSame) {
@@ -464,7 +524,7 @@ function writeProjectLayoutYaml(layout) {
     return;
   }
 
-  // Multi-repo: generate project-layout.yaml
+  // Multi-repo or Jira mode: generate project-layout.yaml
   fs.mkdirSync(path.join(process.cwd(), '_bmad-output'), { recursive: true });
 
   const date = new Date().toISOString().slice(0, 10);
@@ -487,15 +547,20 @@ function writeProjectLayoutYaml(layout) {
   }
 
   // Sprint management section
-  const spPortable = toPortablePath(layout.sprintManagement.path, projectRoot);
   content += `sprint_management:\n`;
   content += `  mode: ${layout.sprintManagement.mode}\n`;
-  content += `  path: ${yamlEscapeValue(spPortable.portable)}\n`;
-  if (spPortable.isAbsolute) {
-    content += `  # PORTABILITY: absolute path — other developers may need to reconfigure\n`;
-  }
-  if (layout.sprintManagement.mode === 'remote' && layout.sprintManagement.gitUrl) {
-    content += `  gitUrl: ${yamlEscapeValue(layout.sprintManagement.gitUrl)}\n`;
+  if (layout.sprintManagement.mode === 'jira') {
+    content += `  jira_url: ${yamlEscapeValue(layout.sprintManagement.jiraUrl)}\n`;
+    content += `  jira_project_key: ${yamlEscapeValue(layout.sprintManagement.jiraProjectKey)}\n`;
+  } else {
+    const spPortable = toPortablePath(layout.sprintManagement.path, projectRoot);
+    content += `  path: ${yamlEscapeValue(spPortable.portable)}\n`;
+    if (spPortable.isAbsolute) {
+      content += `  # PORTABILITY: absolute path — other developers may need to reconfigure\n`;
+    }
+    if (layout.sprintManagement.mode === 'remote' && layout.sprintManagement.gitUrl) {
+      content += `  gitUrl: ${yamlEscapeValue(layout.sprintManagement.gitUrl)}\n`;
+    }
   }
 
   fs.writeFileSync(layoutPath, content, 'utf-8');
@@ -529,14 +594,23 @@ function readExistingLayout() {
         const modeMatch = afterSection.match(/^\s+mode:\s*(\S+)/m);
         const pathMatch = afterSection.match(/^\s+path:\s*"?([^"\n]+)"?/m);
         const gitUrlMatch = afterSection.match(/^\s+gitUrl:\s*"?([^"\n]+)"?/m);
-
-        if (modeMatch && pathMatch) {
-          const resolvedPath = resolveStoredPath(pathMatch[1], projectRoot);
-          const entry = { mode: modeMatch[1], path: resolvedPath };
-          if (modeMatch[1] === 'remote' && gitUrlMatch) {
-            entry.gitUrl = gitUrlMatch[1];
+        const jiraUrlMatch = afterSection.match(/^\s+jira_url:\s*"?([^"\n]+)"?/m);
+        const jiraProjectKeyMatch = afterSection.match(/^\s+jira_project_key:\s*"?([^"\n]+)"?/m);
+
+        if (modeMatch) {
+          const mode = modeMatch[1];
+          if (mode === 'jira') {
+            const jiraUrl = jiraUrlMatch ? jiraUrlMatch[1].replace(/^"(.*)"$/, '$1') : '';
+            const jiraProjectKey = jiraProjectKeyMatch ? jiraProjectKeyMatch[1].replace(/^"(.*)"$/, '$1') : '';
+            layout[key] = { mode: 'jira', jiraUrl, jiraProjectKey };
+          } else if (pathMatch) {
+            const resolvedPath = resolveStoredPath(pathMatch[1], projectRoot);
+            const entry = { mode, path: resolvedPath };
+            if (mode === 'remote' && gitUrlMatch) {
+              entry.gitUrl = gitUrlMatch[1];
+            }
+            layout[key] = entry;
           }
-          layout[key] = entry;
         }
       }
 
@@ -666,6 +740,7 @@ async function collectRepoLayout(flags, existingLayout = null) {
       { title: 'Current repository (default)', value: 'same' },
       { title: 'Local path', value: 'local' },
       { title: 'Remote git repository', value: 'remote' },
+      ...(concern === 'sprintManagement' ? [{ title: 'Jira', value: 'jira' }] : []),
     ];
     // Pre-select existing mode if available
     const initialIndex = existingMode ? modeChoices.findIndex(c => c.value === existingMode) : 0;
@@ -686,6 +761,8 @@ async function collectRepoLayout(flags, existingLayout = null) {
       layout[concern] = await collectLocalPath(labels[concern]);
     } else if (mode === 'remote') {
       layout[concern] = await collectRemotePath(labels[concern]);
+    } else if (mode === 'jira') {
+      layout[concern] = await collectJiraConfig();
     }
   }
 

package/lib/agents.js

@@ -74,22 +74,14 @@ const agents = [
     version: '1.0.0',
     category: 'ide',
     description: 'GitHub Copilot Agent Mode',
-    // F2b — routing fix. bmad-method 6.3.0's PluginResolver writes the
-    // `github-copilot` platform's skills into `.github/skills/` (per its
-    // bundled `tools/installer/ide/platform-codes.yaml`). The previous
-    // ma-agents path of `.github/copilot/skills/` produced TWO competing
-    // skill directories: BMAD wrote 99 plugin skills (including the five
-    // `ma-agent-*` personas) to `.github/skills/` while the ma-agents
-    // installer loop dumped 44 legacy ma-agents-only skills into
-    // `.github/copilot/skills/`. The smoke verifier (and end users) only
-    // saw the latter, so personas appeared "missing" for copilot. Aligning
-    // the ma-agents target_dir with BMAD's puts both writers in the same
-    // tree, identical to the four working tools (Claude Code, Cline,
-    // Roo Code, Kilocode). The instruction file path is intentionally
-    // unchanged — `.github/copilot/copilot.md` is still where Copilot
-    // reads its custom-instructions; only the skills target is moving.
-    skillsDir: '.github/skills',
-    getProjectPath: () => path.join(process.cwd(), '.github', 'skills'),
+    // bmad-method 6.5.0 moved `github-copilot`, `roo`, and `kilo` platforms
+    // from their tool-specific directories to the shared `.agents/skills/`
+    // tree (see platform-codes.yaml). Aligning here keeps the smoke verifier
+    // and all downstream consumers in sync with BMAD's actual write target.
+    // The instruction file path is unchanged — `.github/copilot/copilot.md`
+    // is still where Copilot reads custom-instructions.
+    skillsDir: '.agents/skills',
+    getProjectPath: () => path.join(process.cwd(), '.agents', 'skills'),
     getGlobalPath: () => {
       const platform = os.platform();
       if (platform === 'win32') {
@@ -112,8 +104,8 @@ const agents = [
     version: '1.0.0',
     category: 'ide',
     description: 'Kilocode AI Assistant',
-    skillsDir: '.kilocode/skills',
-    getProjectPath: () => path.join(process.cwd(), '.kilocode', 'skills'),
+    skillsDir: '.agents/skills',
+    getProjectPath: () => path.join(process.cwd(), '.agents', 'skills'),
     getGlobalPath: () => {
       const platform = os.platform();
       if (platform === 'win32') {
@@ -164,8 +156,8 @@ const agents = [
     version: '1.0.0',
     category: 'ide',
     description: 'Roo Code AI Assistant (Enhanced Cline fork)',
-    skillsDir: '.roo/skills',
-    getProjectPath: () => path.join(process.cwd(), '.roo', 'skills'),
+    skillsDir: '.agents/skills',
+    getProjectPath: () => path.join(process.cwd(), '.agents', 'skills'),
     getGlobalPath: () => {
       const platform = os.platform();
       if (platform === 'win32') {

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

@@ -11,6 +11,45 @@ triggers:
 
 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.
 
+## 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: Create a new sprint in the board for project `{jira_project_key}` at `{jira_url}` using the sprint create API. Set the sprint name, goal (if provided), start date, and end date from the provided sprint data. The new sprint starts in "future/planning" state.
+      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/lib/bmad-extension/skills/add-to-sprint/SKILL.md

@@ -13,6 +13,45 @@ Guided workflow to move backlog items to a sprint in the unified `sprint-status.
 
 **Movement semantics:** Each item exists in exactly one location — either the `backlog` array OR a sprint's `items` array, never both. This skill atomically removes items from `backlog` and appends them to the target sprint's `items` array in a single file write.
 
+## 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). Find the active sprint on the board for project `{jira_project_key}`. Move the issue to the active sprint using the "add issue to sprint" operation.
+      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/lib/bmad-extension/skills/bmad-dev-story/workflow.md

@@ -36,6 +36,45 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## Backend Routing
+
+Before executing any status-update 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). Transition the issue to the new status using the Jira issue transition API. Map canonical status to Jira workflow status: 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/lib/bmad-extension/skills/bmad-sprint-planning/workflow.md

@@ -42,6 +42,47 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## 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/lib/bmad-extension/skills/bmad-sprint-status/workflow.md

@@ -37,6 +37,45 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## 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.
+
+---
+
 ## EXECUTION
 
 <workflow>

package/lib/bmad-extension/skills/cleanup-done/SKILL.md

@@ -20,6 +20,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/lib/bmad-extension/skills/close-sprint/SKILL.md

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