@aholbreich/agent-skills 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+Added:
+
+- `jira-browser-fetch --backlog URL|BOARD_ID` to fetch all issues from a Jira Software board backlog through the authenticated browser session.
+- Backlog manifests at `raw/jira-board-<board-id>-backlog.json` and a `backlogs` section in `raw/jira-browser-fetch-run.json`.
+- Documentation examples for natural-language user requests that should invoke the skills.
+
 ## 0.1.0 - 2026-05-06
 
 Initial public package structure.

package/README.md

@@ -8,7 +8,7 @@ This repository is a pure skills package. It currently contains browser-authenti
 
 | Skill | Purpose |
 |---|---|
-| [`jira-browser-fetch`](skills/jira-browser-fetch/) | Fetch Jira issue JSON, rendered HTML/XML, linked/referenced issues, JQL result sets, and attachments through an authenticated Chrome session. |
+| [`jira-browser-fetch`](skills/jira-browser-fetch/) | Fetch Jira issue JSON, rendered HTML/XML, linked/referenced issues, Jira Software board backlogs, JQL result sets, and attachments through an authenticated Chrome session. |
 | [`confluence-browser-fetch`](skills/confluence-browser-fetch/) | Fetch Confluence page JSON, storage/view HTML, browser HTML, descendants, CQL result sets, and attachments through an authenticated Chrome session. |
 
 ## Compatibility
@@ -170,6 +170,23 @@ jira-browser-fetch \
   --jql 'assignee = currentUser() ORDER BY updated DESC'
 ```
 
+Fetch a Jira Software board backlog:
+
+```bash
+jira-browser-fetch \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --backlog 'https://example.atlassian.net/jira/software/c/projects/ABC/boards/42/backlog?epics=visible'
+```
+
+Example user requests that should invoke this skill:
+
+- "Fetch all Jira issues from this backlog URL into `raw/`."
+- "Archive board 42's Jira backlog for my LLM wiki."
+- "Fetch `PROJ-123` through my browser session and include linked issues."
+- "Pull my assigned Jira issues without asking me for an API token."
+- "Use this JQL and store the raw Jira evidence under the wiki raw folder."
+
 ## Confluence examples
 
 Fetch one page by URL:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",

package/skills/jira-browser-fetch/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: jira-browser-fetch
-description: Fetch Jira issue raw data through an authenticated Chrome browser session when jira-cli/API tokens do not work, especially with Microsoft/SSO. Use to archive Jira issues, linked tickets, rendered HTML/XML, remote links, and attachments into a raw wiki folder.
+description: Fetch Jira issue raw data through an authenticated Chrome browser session when jira-cli/API tokens do not work, especially with Microsoft/SSO. Use to archive Jira issues, Jira Software board backlogs, JQL result sets, linked tickets, rendered HTML/XML, remote links, and attachments into a raw wiki folder.
 license: MIT
 compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and Google Chrome/Chromium with remote debugging. No npm dependencies.
 ---
 
 # Jira Browser Fetch
 
-Use this skill when Jira API-token authentication fails or the organization uses Microsoft/SSO and the user wants Jira issues archived into a local raw/wiki folder.
+Use this skill when Jira API-token authentication fails or the organization uses Microsoft/SSO and the user wants Jira issues, Jira Software board backlogs, or JQL result sets archived into a local raw/wiki folder.
 
 The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, and fetches Jira REST/HTML/XML/attachments into a raw directory.
 
@@ -33,12 +33,23 @@ Important options:
 --depth N          recursion depth for connected tickets
 --scan-text        find issue keys in JSON/XML/HTML text, not only formal Jira links
 --jql JQL          search Jira with JQL and fetch all matching issues
+--backlog URL|ID   fetch all issues from a Jira Software board backlog URL or board id
 --assignee-me      fetch all issues assigned to current Jira user
 --max-attachment-size S  skip attachment files larger than S (default 5mb; use unlimited to disable)
 --prefix A,B,C     only follow keys with these project prefixes
 --wait SEC         SSO/session wait timeout per issue
 ```
 
+## Example User Requests
+
+Use this skill for user requests like:
+
+- "Fetch Jira issue `PROJ-123` into `raw/` through my browser session."
+- "Archive this Jira backlog for my LLM wiki: `https://example.atlassian.net/jira/software/c/projects/ABC/boards/42/backlog?epics=visible`."
+- "Fetch all Jira issues matching this JQL into the wiki raw folder."
+- "Pull my assigned Jira issues without asking me for an API token."
+- "Fetch this ticket and all linked tickets, including attachments under the default size limit."
+
 ## Typical Workflow
 
 1. Identify raw directory.
@@ -64,6 +75,12 @@ scripts/jira-browser-fetch.js \
   --server https://example.atlassian.net \
   --raw-dir ./raw \
   --assignee-me
+
+# Fetch every issue currently visible in a Jira Software board backlog:
+scripts/jira-browser-fetch.js \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --backlog 'https://example.atlassian.net/jira/software/c/projects/ABC/boards/42/backlog?epics=visible'
 ```
 
 ## Output Layout
@@ -88,6 +105,12 @@ A run manifest is written to:
 raw/jira-browser-fetch-run.json
 ```
 
+Backlog fetches also write:
+
+```text
+raw/jira-board-<board-id>-backlog.json
+```
+
 ## Installation / PATH
 
 The skill can be used directly by path. Optionally install a convenience symlink:

package/skills/jira-browser-fetch/references/usage.md

@@ -80,6 +80,26 @@ scripts/jira-browser-fetch.js \
   --jql "assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC"
 ```
 
+Fetch every issue currently visible in a Jira Software board backlog:
+
+```bash
+scripts/jira-browser-fetch.js \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --backlog 'https://example.atlassian.net/jira/software/c/projects/ABC/boards/42/backlog?epics=visible'
+```
+
+If you already know the board id, this is equivalent:
+
+```bash
+scripts/jira-browser-fetch.js \
+  --server https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --backlog 42
+```
+
+A backlog fetch writes `raw/jira-board-<board-id>-backlog.json` with the ordered backlog issue keys and adds a `backlogs` section to `raw/jira-browser-fetch-run.json`.
+
 Use a shorter wait when the browser session is already logged in:
 
 ```bash
@@ -102,11 +122,21 @@ Default max attachment download size is `5mb`. Use `--max-attachment-size unlimi
 | `JIRA_RAW_DIR` | Default output raw directory |
 | `JIRA_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9223` |
 | `JIRA_FETCH_WAIT_SEC` | Wait timeout per issue, default `900` |
-| `JIRA_MAX_SEARCH_RESULTS` | Max issues added per JQL search, default `1000` |
+| `JIRA_MAX_SEARCH_RESULTS` | Max issues added per JQL or backlog search, default `1000` |
 | `JIRA_MAX_ATTACHMENT_SIZE` / `JIRA_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |
 | `JIRA_CHROME_PROFILE` | Dedicated Chrome profile dir |
 | `CHROME` | Chrome executable path |
 
+## Example user requests
+
+Agents should invoke this skill for requests such as:
+
+- "Fetch all Jira issues from this backlog URL into `/raw`."
+- "Archive board 42's Jira backlog for my LLM wiki."
+- "Fetch my assigned Jira issues through the browser because API tokens do not work."
+- "Fetch `PROJ-123` and all connected tickets with attachments."
+- "Use this JQL and store the raw Jira evidence under the wiki raw folder."
+
 ## Troubleshooting
 
 ### `no Jira cookies yet`

package/skills/jira-browser-fetch/scripts/jira-browser-fetch.js

@@ -6,7 +6,15 @@ const fsp = require('fs/promises');
 const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
-const { parseSize, formatBytes, safeName, issueKeysFromText } = require('./lib');
+const {
+  parseSize,
+  formatBytes,
+  safeName,
+  issueKeysFromText,
+  parseBacklogInput,
+  backlogApiUrl,
+  issueKeysFromAgilePage,
+} = require('./lib');
 
 function usage() {
   console.log(`Usage: jira-browser-fetch [ISSUE-KEY ...] [options]
@@ -21,8 +29,9 @@ Options:
   --depth N                Connected fetch depth (default: 1 with --connected, otherwise 0)
   --scan-text              Include issue keys found anywhere in issue JSON/XML/HTML text
   --jql JQL                Search Jira with JQL and fetch all matching issues
+  --backlog URL|BOARD_ID   Fetch all issues from a Jira Software board backlog URL or board id
   --assignee-me            Fetch all issues assigned to current Jira user
-  --max-search-results N   Max issues to add per JQL search (default: 1000)
+  --max-search-results N   Max issues to add per JQL/backlog search (default: 1000)
   --max-attachment-size S  Skip attachment downloads larger than S (default: 5mb; use unlimited to disable)
   --prefix A,B,C           Only fetch referenced keys with these project prefixes
   --wait SEC               Wait time for SSO/session per issue (default: 900)
@@ -37,7 +46,8 @@ Examples:
   jira-browser-fetch SWING-4770 --raw-dir /path/wiki/raw
   jira-browser-fetch SWING-4770 --connected --prefix SWING,SSD,EC --raw-dir ./raw
   jira-browser-fetch --assignee-me --raw-dir ./raw
-  JIRA_SERVER=https://example.atlassian.net jira-browser-fetch PROJ-123 --connected
+  jira-browser-fetch --backlog 'https://example.atlassian.net/jira/software/c/projects/ABC/boards/42/backlog?epics=visible' --raw-dir ./raw
+  JIRA_SERVER=https://example.atlassian.net jira-browser-fetch --backlog 42 --connected
 `);
 }
 
@@ -51,6 +61,7 @@ const opts = {
   depth: undefined,
   scanText: false,
   jqls: [],
+  backlogs: [],
   assigneeMe: false,
   maxSearchResults: Number(process.env.JIRA_MAX_SEARCH_RESULTS || 1000),
   maxAttachmentBytes: parseSize(process.env.JIRA_MAX_ATTACHMENT_SIZE || process.env.JIRA_MAX_ATTACHMENT_BYTES || '5mb'),
@@ -70,6 +81,7 @@ for (let i = 2; i < process.argv.length; i++) {
   else if (a === '--depth') opts.depth = Number(process.argv[++i]);
   else if (a === '--scan-text') opts.scanText = true;
   else if (a === '--jql') opts.jqls.push(process.argv[++i]);
+  else if (a === '--backlog') opts.backlogs.push(process.argv[++i]);
   else if (a === '--assignee-me') opts.assigneeMe = true;
   else if (a === '--max-search-results') opts.maxSearchResults = Number(process.argv[++i]);
   else if (a === '--max-attachment-size') opts.maxAttachmentBytes = parseSize(process.argv[++i]);
@@ -84,7 +96,7 @@ for (let i = 2; i < process.argv.length; i++) {
   else { console.error(`Unknown argument: ${a}`); process.exit(2); }
 }
 
-if (!issues.length && !opts.jqls.length && !opts.assigneeMe) { usage(); process.exit(2); }
+if (!issues.length && !opts.jqls.length && !opts.backlogs.length && !opts.assigneeMe) { usage(); process.exit(2); }
 if (opts.assigneeMe) opts.jqls.push('assignee = currentUser() ORDER BY updated DESC');
 if (opts.depth === undefined) opts.depth = opts.connected ? 1 : 0;
 if (opts.depth > 0) opts.connected = true;
@@ -259,6 +271,65 @@ async function searchJql(jql) {
   return [...new Set(found)];
 }
 
+async function fetchBacklogPageWithWait(url) {
+  const deadline = Date.now() + opts.waitSec * 1000;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const cookie = await getCookieHeader();
+      if (!cookie) {
+        last = 'no Jira cookies yet';
+      } else {
+        const result = await fetchJson(url, cookie, 'application/json');
+        if (result.status === 200 && result.json && Array.isArray(result.json.issues)) return result.json;
+        last = `HTTP ${result.status} ${(result.text || '').slice(0, 180).replace(/\s+/g, ' ')}`;
+      }
+    } catch (e) { last = e.message; }
+    process.stdout.write(`\r${new Date().toLocaleTimeString()} waiting for authenticated Jira backlog session: ${last.padEnd(120).slice(0, 120)}`);
+    await sleep(3000);
+  }
+  process.stdout.write('\n');
+  throw new Error(`Could not fetch Jira backlog. Last result: ${last}`);
+}
+
+async function searchBacklog(input) {
+  const backlog = parseBacklogInput(input, opts.server);
+  await ensureBrowser(backlog.browseUrl);
+  console.log(`If prompted in Chrome, complete SSO for: ${backlog.browseUrl}`);
+  console.log(`Waiting up to ${opts.waitSec}s for Jira backlog access...`);
+
+  const found = [];
+  let startAt = 0;
+  const pageSize = Math.min(100, Math.max(1, opts.maxSearchResults || 1000));
+
+  while (found.length < opts.maxSearchResults) {
+    const limit = Math.min(pageSize, opts.maxSearchResults - found.length);
+    const url = backlogApiUrl(opts.server, backlog.boardId, startAt, limit);
+    const page = await fetchBacklogPageWithWait(url);
+    const keys = issueKeysFromAgilePage(page);
+    for (const key of keys) found.push(key);
+    console.log(`Fetched backlog page board=${backlog.boardId} startAt=${startAt}, issues=${keys.length}${typeof page.total === 'number' ? `, total=${page.total}` : ''}`);
+    if (page.isLast === true) break;
+    if (typeof page.total === 'number' && startAt + keys.length >= page.total) break;
+    if (!keys.length) break;
+    startAt += keys.length;
+  }
+
+  const keys = [...new Set(found)];
+  const manifest = {
+    fetchedAt: new Date().toISOString(),
+    server: opts.server,
+    boardId: backlog.boardId,
+    source: backlog.source,
+    browseUrl: backlog.browseUrl,
+    endpoint: `/rest/agile/1.0/board/${backlog.boardId}/backlog`,
+    issueCount: keys.length,
+    issues: keys,
+  };
+  await fsp.writeFile(path.join(opts.rawDir, `jira-board-${backlog.boardId}-backlog.json`), JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
 function addKey(set, key) {
   if (!key) return;
   key = String(key).toUpperCase();
@@ -455,6 +526,22 @@ async function main() {
   const seen = new Set();
   const failed = [];
   const searches = [];
+  const backlogs = [];
+
+  for (const backlogInput of opts.backlogs) {
+    console.log(`\n===== Fetching Jira backlog: ${backlogInput} =====`);
+    try {
+      const backlog = await searchBacklog(backlogInput);
+      backlogs.push(backlog);
+      console.log(`Backlog board ${backlog.boardId} matched ${backlog.issueCount} issue(s): ${backlog.issues.join(' ') || '(none)'}`);
+      for (const key of backlog.issues) {
+        if (!queue.some(q => q.key === key)) queue.push({ key, depth: 0, from: `Backlog board ${backlog.boardId}` });
+      }
+    } catch (e) {
+      failed.push({ key: `BACKLOG: ${backlogInput}`, error: e.message });
+      console.error(`BACKLOG FAILED: ${e.message}`);
+    }
+  }
 
   for (const jql of opts.jqls) {
     console.log(`\n===== Searching JQL: ${jql} =====`);
@@ -489,7 +576,7 @@ async function main() {
     }
   }
 
-  const runMeta = { fetchedAt: new Date().toISOString(), server: opts.server, rawDir: opts.rawDir, requested: issues, searches, fetched: [...seen].filter(k => !failed.some(f => f.key === k)), failed };
+  const runMeta = { fetchedAt: new Date().toISOString(), server: opts.server, rawDir: opts.rawDir, requested: issues, searches, backlogs, fetched: [...seen].filter(k => !failed.some(f => f.key === k)), failed };
   await fsp.writeFile(path.join(opts.rawDir, 'jira-browser-fetch-run.json'), JSON.stringify(runMeta, null, 2));
 
   if (failed.length) {

package/skills/jira-browser-fetch/scripts/lib.js

@@ -40,6 +40,46 @@ function shouldSkipAttachment(size, maxAttachmentBytes) {
   return Number.isFinite(n) && n > maxAttachmentBytes;
 }
 
+function parseBacklogInput(input, server = '') {
+  if (!input) throw new Error('Missing Jira backlog URL or board id');
+  const value = String(input).trim();
+  const numeric = value.match(/^\d+$/);
+  if (numeric) {
+    return {
+      boardId: Number(value),
+      source: value,
+      browseUrl: server ? `${String(server).replace(/\/$/, '')}/jira/software/c/boards/${value}/backlog` : value,
+    };
+  }
+
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Invalid Jira backlog URL or board id: ${input}`);
+  }
+
+  const m = url.pathname.match(/\/boards\/(\d+)(?:\/backlog)?\b/);
+  if (!m) throw new Error(`Could not parse Jira board id from backlog URL: ${input}`);
+
+  return {
+    boardId: Number(m[1]),
+    source: value,
+    browseUrl: value,
+  };
+}
+
+function backlogApiUrl(server, boardId, startAt, maxResults) {
+  const base = String(server || '').replace(/\/$/, '');
+  const params = new URLSearchParams({ startAt: String(startAt), maxResults: String(maxResults) });
+  return `${base}/rest/agile/1.0/board/${boardId}/backlog?${params}`;
+}
+
+function issueKeysFromAgilePage(page) {
+  const issues = page && Array.isArray(page.issues) ? page.issues : [];
+  return issues.map(issue => issue && issue.key).filter(Boolean);
+}
+
 module.exports = {
   DEFAULT_MAX_ATTACHMENT_BYTES,
   parseSize,
@@ -47,4 +87,7 @@ module.exports = {
   safeName,
   issueKeysFromText,
   shouldSkipAttachment,
+  parseBacklogInput,
+  backlogApiUrl,
+  issueKeysFromAgilePage,
 };