@aholbreich/agent-skills 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+- Recommended `npx skills add aholbreich/agent-skills -g` cross-agent install path, plus collision/update guidance for Pi and project-local overrides.
+- CI/package dry-run scripts that use `npm pack --dry-run` for compatibility with older local pnpm launchers.
+
 ## 0.1.0 - 2026-05-06
 
 Initial public package structure.

package/COMPATIBILITY.md

@@ -4,96 +4,111 @@ This package is designed as a pure [Agent Skills](https://agentskills.io/) packa
 
 Each bundled skill is a directory containing `SKILL.md` plus scripts and references. The frontmatter follows the Agent Skills conventions: required `name` and `description`, directory name matching the skill name, lowercase hyphenated names, and optional `license`/`compatibility` metadata.
 
-## Compatibility matrix
-
-| Tool / Harness | Status | Install method |
-|---|---:|---|
-| Pi | Supported and tested | `pi install npm:@aholbreich/agent-skills` or `npx @aholbreich/agent-skills --target pi` |
-| Claude Code | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target claude` or copy `skills/*` into Claude's skills directory |
-| OpenAI Codex | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target codex` or copy `skills/*` into Codex's skills directory |
-| OpenClaw / generic Agent Skills harnesses | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target agents` or copy `skills/*` into `.agents/skills` / configured skills directory |
-| Any Agent Skills-compatible tool | Compatible layout | Copy each folder under `skills/` into the tool's configured skills directory |
+## Recommended installer
 
-## Install commands
-
-### Generic Agent Skills default
+For cross-agent installation, prefer the open Skills CLI:
 
 ```bash
-npx @aholbreich/agent-skills
+npx skills add aholbreich/agent-skills -g
 ```
 
-This installs to `~/.agents/skills` and is equivalent to:
+The Skills CLI discovers `skills/*/SKILL.md`, supports many agent clients, and symlinks agent-specific installs to a managed source by default. Use `--copy` only when symlinks are not supported.
+
+Useful variants:
 
 ```bash
-npx @aholbreich/agent-skills --target agents
+npx skills add aholbreich/agent-skills --list
+npx skills add aholbreich/agent-skills              # project-local/team install
+npx skills add aholbreich/agent-skills -g -y        # non-interactive global install
+npx skills update -g                                # update global skills installed by the Skills CLI
+npx skills list -g                                  # list global skills
 ```
 
-### Pi global
+## Compatibility matrix
 
-```bash
-pi install npm:@aholbreich/agent-skills
-```
+| Tool / Harness | Status | Recommended install method |
+|---|---:|---|
+| Pi | Supported and tested | `pi install npm:@aholbreich/agent-skills` for Pi-managed package updates, or `npx skills add aholbreich/agent-skills -g` for cross-agent installs |
+| Claude Code | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g --agent claude-code` |
+| OpenAI Codex | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g --agent codex` |
+| OpenClaw / generic Agent Skills harnesses | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g` or install to `.agents/skills` |
+| Any Agent Skills-compatible tool | Compatible layout | Copy or symlink each folder under `skills/` into the tool's configured skills directory |
+
+## Pi-native install commands
 
-or:
+Pi can install this repository as a Pi package directly from npm:
 
 ```bash
-npx @aholbreich/agent-skills --target pi
+pi install npm:@aholbreich/agent-skills
 ```
 
-### Pi project-local
+Project-local Pi package install:
 
 ```bash
 pi install -l npm:@aholbreich/agent-skills
 ```
 
-or:
+Temporary Pi run without installing:
 
 ```bash
-npx @aholbreich/agent-skills --target project
+pi -e npm:@aholbreich/agent-skills
 ```
 
-### Claude Code
+## Package fallback installer
+
+The npm package also ships a small dependency-free installer for environments where the Skills CLI is not available:
 
 ```bash
-npx @aholbreich/agent-skills --target claude
+npx @aholbreich/agent-skills
 ```
 
-Project-local Claude-style install:
+This installs to `~/.agents/skills` and is equivalent to:
 
 ```bash
-npx @aholbreich/agent-skills --target project-claude
+npx @aholbreich/agent-skills --target agents
 ```
 
-### Codex
+Other targets:
 
 ```bash
+npx @aholbreich/agent-skills --target pi
+npx @aholbreich/agent-skills --target claude
 npx @aholbreich/agent-skills --target codex
+npx @aholbreich/agent-skills --target project
+npx @aholbreich/agent-skills --target project-agents
+npx @aholbreich/agent-skills install --dir /path/to/skills
 ```
 
-Project-local Codex-style install:
+This fallback copies files. For symlinked, multi-agent installs, prefer `npx skills add aholbreich/agent-skills`.
 
-```bash
-npx @aholbreich/agent-skills --target project-codex
-```
+## Collision behavior
 
-### Generic `.agents/skills`
+Agent Skills are identified by their `name` frontmatter. If the same skill name exists in more than one discovered location, agents apply their own precedence rules.
 
-```bash
-npx @aholbreich/agent-skills --target agents
-```
+Common precedence pattern:
 
-Project-local generic install:
+1. Project-local skills override user/global skills.
+2. User/global skills override bundled/system skills.
+3. Duplicate names are not merged.
 
-```bash
-npx @aholbreich/agent-skills --target project-agents
+Pi example:
+
+```text
+.pi/skills/jira-browser-fetch/SKILL.md
 ```
 
-### Custom skills directory
+shadows:
 
-```bash
-npx @aholbreich/agent-skills install --dir /path/to/skills
+```text
+~/.nvm/.../@aholbreich/agent-skills/skills/jira-browser-fetch/SKILL.md
 ```
 
+That is useful for intentional repo-specific overrides, but it also means package updates may not affect the active skill in that repository. If you see a collision warning, choose one source of truth:
+
+- Keep the project-local skill if the repository intentionally customizes it.
+- Remove the project-local copy if you want the package/global install to be active.
+- Re-run the installer/update command for the install method that owns the active copy.
+
 ## Discoverability
 
 The package is tagged for discovery with npm keywords including:
@@ -106,7 +121,11 @@ The package is tagged for discovery with npm keywords including:
 - `claude-code`
 - `codex`
 
-After publishing to npm, tools and indexes that crawl npm packages for Agent Skills-compatible packages, such as skills registries, should be able to discover the package from its package metadata and conventional `skills/` directory.
+The repository is also compatible with the Skills CLI GitHub shorthand:
+
+```bash
+npx skills add aholbreich/agent-skills --list
+```
 
 If a registry requires manual submission, use:
 
@@ -114,6 +133,7 @@ If a registry requires manual submission, use:
 Package: @aholbreich/agent-skills
 Repository: https://github.com/aholbreich/agent-skills
 Skills directory: skills/
+Install command: npx skills add aholbreich/agent-skills -g
 ```
 
 ## Compliance checks in this repo
@@ -129,6 +149,6 @@ That includes:
 - JavaScript syntax checks.
 - Unit tests.
 - Skill frontmatter compliance checks.
-- `pnpm pack --dry-run` package content check.
+- `npm pack --dry-run` package content check.
 
 The compliance tests are intentionally local and dependency-free; they validate the parts of the Agent Skills structure that matter for broad tool compatibility.

package/README.md

@@ -8,25 +8,23 @@ 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
 
 This repository follows the Agent Skills directory convention: each skill lives under `skills/<skill-name>/SKILL.md` with matching frontmatter.
 
-Supported install targets:
+Recommended install paths:
 
-| Target | Command |
+| Use case | Command |
 |---|---|
-| Pi | `pi install npm:@aholbreich/agent-skills` |
-| Pi via npx | `npx @aholbreich/agent-skills --target pi` |
-| Claude Code-style global skills | `npx @aholbreich/agent-skills --target claude` |
-| Codex-style global skills | `npx @aholbreich/agent-skills --target codex` |
-| OpenClaw / generic `.agents/skills` | `npx @aholbreich/agent-skills --target agents` |
-| Project-local generic skills | `npx @aholbreich/agent-skills --target project-agents` |
+| Cross-agent wizard (recommended) | `npx skills add aholbreich/agent-skills -g` |
+| Pi package-managed install | `pi install npm:@aholbreich/agent-skills` |
+| Project-local/team skills | `npx skills add aholbreich/agent-skills` |
+| Package fallback without the aggregator | `npx @aholbreich/agent-skills` |
 
-See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details.
+See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details, including collision behavior.
 
 ## Requirements
 
@@ -37,52 +35,74 @@ See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details.
 
 No npm runtime dependencies are required.
 
-## Install with Pi
+## Recommended install with the Skills CLI
 
-From GitHub:
+For most users, use the open `skills` installer. It discovers the skills in this repository, prompts for compatible agents, and symlinks agent-specific installs to a single managed source by default.
+
+Global/user install:
 
 ```bash
-pi install git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills -g
 ```
 
 Project-local install, useful for teams:
 
 ```bash
-pi install -l git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills
 ```
 
-Try without installing:
+List available skills without installing:
 
 ```bash
-pi -e git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills --list
 ```
 
-## One-shot install with npx
+Non-interactive examples:
 
-Install bundled skills into the generic Agent Skills directory `~/.agents/skills`:
+```bash
+npx skills add aholbreich/agent-skills -g --skill '*' -y
+npx skills add aholbreich/agent-skills -g --agent claude-code --agent codex --skill jira-browser-fetch -y
+```
+
+Use `--copy` only when symlinks are not supported in your environment.
+
+## Pi-native install
+
+If you only use Pi and want Pi to manage package updates, install the npm package directly:
 
 ```bash
-npx @aholbreich/agent-skills
+pi install npm:@aholbreich/agent-skills
 ```
 
-This is equivalent to:
+Project-local Pi package install, useful for teams that already standardize on Pi packages:
 
 ```bash
-npx @aholbreich/agent-skills --target agents
+pi install -l npm:@aholbreich/agent-skills
 ```
 
-Install into a project-local `.pi/skills` directory:
+Try without installing:
 
 ```bash
-npx @aholbreich/agent-skills install --target project
+pi -e npm:@aholbreich/agent-skills
+```
+
+## Package fallback with npx
+
+If you cannot use the `skills` aggregator, this package also ships a small installer. It copies bundled skills into a selected skills directory.
+
+Install bundled skills into the generic Agent Skills directory `~/.agents/skills`:
+
+```bash
+npx @aholbreich/agent-skills
 ```
 
-Install for Claude Code, Codex, or generic Agent Skills harnesses:
+Install for a specific target:
 
 ```bash
+npx @aholbreich/agent-skills install --target agents
 npx @aholbreich/agent-skills install --target claude
 npx @aholbreich/agent-skills install --target codex
-npx @aholbreich/agent-skills install --target agents
+npx @aholbreich/agent-skills install --target project
 ```
 
 Overwrite existing installed skill directories:
@@ -97,6 +117,18 @@ List bundled skills:
 npx @aholbreich/agent-skills list
 ```
 
+## Collision and update notes
+
+Avoid installing the same skill into multiple locations for the same agent unless you intentionally want one copy to shadow another. Most agents give project-local skills priority over user/global skills.
+
+For example, in Pi a project skill at `.pi/skills/jira-browser-fetch/SKILL.md` shadows the same skill installed from `npm:@aholbreich/agent-skills`. In that case `pi update` updates the package, but the active project-local copy remains unchanged.
+
+Recommended rule of thumb:
+
+- Cross-agent users: prefer `npx skills add aholbreich/agent-skills -g`.
+- Pi-only users: prefer `pi install npm:@aholbreich/agent-skills`.
+- Team/repo-specific overrides: commit project-local skills intentionally and update them intentionally.
+
 ## Manual install
 
 ```bash
@@ -170,6 +202,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/bin/agent-skills.js

@@ -27,6 +27,11 @@ function usage() {
 
 Install this package's Agent Skills into a local skills directory.
 
+Recommended cross-agent installer:
+  npx skills add aholbreich/agent-skills -g
+
+This fallback installer copies files for environments where the Skills CLI is unavailable.
+
 Commands:
   install                 Install skills (default command)
   list                    List bundled skills
@@ -40,6 +45,7 @@ Options for install:
   --dry-run               Show what would be copied without writing
 
 Examples:
+  npx skills add aholbreich/agent-skills -g
   npx @aholbreich/agent-skills
   npx @aholbreich/agent-skills install --target agents --force
   npx @aholbreich/agent-skills install --target pi --force

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -42,10 +42,10 @@
   "scripts": {
     "check": "node --check bin/agent-skills.js && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js",
     "test": "node --test",
-    "ci": "pnpm run check && pnpm test && pnpm pack --dry-run",
-    "pack:dry": "pnpm pack --dry-run",
-    "prepack": "pnpm run check",
-    "prepublishOnly": "pnpm run check && pnpm test"
+    "ci": "npm run check && npm test && npm pack --dry-run",
+    "pack:dry": "npm pack --dry-run",
+    "prepack": "npm run check",
+    "prepublishOnly": "npm run check && npm test"
   },
   "pi": {
     "skills": [

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,
 };