@aholbreich/agent-skills 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -1,6 +1,49 @@
 # Changelog
 
-## Unreleased
+## 1.1.0 - 2026-05-11
+
+Added:
+
+- `jira-browser-fetch --skip-existing` skips issues that already have a valid `raw/<KEY>/issue.json`, reading the saved `connected-keys.json` so `--connected --scan-text` traversal still resumes correctly.
+- `jira-browser-fetch` prints aggregate progress (`[N/total] pct%`) and a trailing ETA line during multi-issue runs.
+- `confluence-update` and `confluence-browser-fetch` emit a clearer error when Confluence probes return 404. After all wikiBase probes 404, the verifier does one sanity probe against the Jira API at the same site root; if that succeeds, the error specifically says "cookies are valid for ${site} but Confluence at ${wikiBase} returned 404", pointing to either a wrong `--site` or a tenant without Confluence enabled.
+- README gains a "Project status" section flagging the opinionated browser-only auth approach, Linux-Fedora-only end-to-end testing, and a feedback request.
+- Every SKILL.md's "Shared Atlassian SSO Session" section now teaches calling agents three things: (i) the script-Chrome is a separate window from the user's regular browser, cookies from the user's Chrome are not read; (ii) reuse signal — `Reusing Chrome DevTools on port 9223` / `Found existing tab for <host>` means do not re-prompt SSO; (iii) `CHROME=/path/to/launcher` env var for Flatpak/Snap/non-PATH installs. The Typical Workflow's SSO step is clarified to be first-run-or-expired-only.
+
+Changed:
+
+- The "Reuse one Atlassian browser login" section in README now reflects the unified-defaults behavior — no env vars required for the default sharing.
+- **Unified Chrome profile and DevTools port across all five Atlassian skills.** Defaults are now `~/.local/share/atlassian-browser-chrome` and port `9223` for `jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, and `bitbucket-browser-fetch`. One SSO login persists across all skills — no env vars required. Skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars still override for isolation. Each SKILL.md gains a "Shared Atlassian SSO Session" section near the top.
+- `confluence-update` and `confluence-browser-fetch` now strip a trailing `/wiki` from `--site` (or `CONFLUENCE_SITE`) with a stderr note, instead of building the unreachable `…/wiki/wiki` URL.
+- Replaced the 19-step `npm run check` chain with a `bin/check.js` script that auto-discovers `bin/`, `lib/`, and every `skills/*/scripts/` JS file. Aggregates failures (no longer stops at the first error) and prints a summary line. New skills/scripts are picked up automatically with no `package.json` edit.
+
+Migration:
+
+- Users who previously logged in via the old per-skill profiles (`~/.local/share/jira-browser-fetch-chrome`, `confluence-browser-fetch-chrome`, `bitbucket-browser-fetch-chrome`) will hit a fresh login on first run after upgrade. To preserve the existing session, move whichever profile you used: `mv ~/.local/share/jira-browser-fetch-chrome ~/.local/share/atlassian-browser-chrome` (only one — pick the one with your live cookies). Or just re-SSO once; the new shared profile then serves all five skills.
+
+## 1.0.1 - 2026-05-09
+
+Added:
+
+- `jira-update <command> --help` and `confluence-update <command> --help` now print command-specific options instead of falling back to top-level usage.
+- `jira-update transition --help` documents the `--field key=value` heuristics (`priority`/`resolution`/`status` wrap as `{name: VALUE}`; `labels`/`components`/`fixVersions` split on commas; everything else passes through as a string).
+- `jira-update` validates issue keys client-side (`PROJ-123` form). `comment`, `transition`, `update-fields`, `link <FROM>`, and `link --to <TO>` fail fast with exit 2 instead of round-tripping a bad key through SSO and the Jira REST API.
+
+Changed:
+
+- `jira-update` validation errors (missing manifest fields, unresolved transitions/link types, bad representation) now exit 2 with a clean `error: ...` message instead of dumping a Node stack trace and exiting 1. Implemented via a new `UsageError` class in `skills/jira-update/scripts/lib.js`.
+
+## 1.0.0 - 2026-05-08
+
+Added:
+
+- New `jira-update` skill for dry-run-first Jira Cloud writes through an authenticated browser session: `create`, `comment`, `transition`, `update-fields`, and `link` commands. Markdown-to-ADF conversion by default; ADF passthrough as escape hatch.
+
+Changed:
+
+- Extracted browser/CDP/cookie helpers from all four existing skills into a single source-of-truth `lib/atlassian-browser.js`. Vendored at pack time into each `skills/*/scripts/atlassian-browser.js` so each skill folder remains self-contained on disk. Eliminates ~870 lines of duplicated code across the bundle.
+
+## 0.9.0 - 2026-05-07
 
 Added:
 

package/README.md

@@ -1,14 +1,31 @@
 # Agent Skills
 
-Handcrafted [Agent Skills](https://agentskills.io/) for developer and LLM-wiki workflows. The package is intentionally a pure skills package with broad compatibility across Pi, Claude Code, Codex, OpenClaw/generic `.agents` setups, and other Agent Skills-compatible harnesses.
+**Browser-authenticated Atlassian write surface for SSO-locked organizations.** Five [Agent Skills](https://agentskills.io/) covering Jira read+write, Confluence read+write, and Bitbucket read — designed for orgs where Microsoft/SSO blocks API-token use.
 
-This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetch/update tools that work well when Jira/Confluence/Bitbucket API-token authentication is unavailable because an organization uses Microsoft/SSO.
+The package is a pure Agent Skills bundle, compatible with Pi, Claude Code, Codex, OpenClaw / generic `.agents` setups, and other Agent Skills-compatible harnesses.
+
+## Why this exists
+
+Most Atlassian automation tools assume API tokens. In SSO-locked enterprises, API tokens are often disabled or restricted in ways that make scripted writes painful. These skills route through an authenticated **browser session** instead — you log in to Jira/Confluence/Bitbucket once in Chrome, and the skills replay your cookies via DevTools to make REST calls. No API token required.
+
+Beyond the SSO bypass, the skills are built around three differentiators:
+
+- **Dry-run-first writes.** Every write command (`jira-update create`, `confluence-update replace-block`, etc.) emits a full audit folder under `raw/` first. You only get a real write when you re-run with `--apply`. Each audit folder contains the proposed payload, the before-state, and a diff summary — review exactly what would happen before it does.
+- **Markdown → ADF conversion.** `jira-update` converts Markdown to Atlassian Document Format (Jira Cloud's structured rich-text representation), so agents write descriptions, comments, and transitions in a familiar format without hand-rolling ADF JSON.
+- **Shared browser session.** All Atlassian skills can reuse a single Chrome profile + DevTools port, so you log in once and every fetch/update skill rides the same SSO session.
+
+## Project status
+
+Opinionated bundle: SSO browser-session auth only, no API tokens or app passwords. The whole stack is built around extracting Chrome cookies via the DevTools Protocol — if API tokens already work for your org, you do not need this. All five Atlassian skills share one Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`) by default; log in once and the others reuse the session.
+
+**Tested on Linux (Fedora) at the moment.** macOS browser paths exist in the auto-detection logic but are not end-to-end verified; Windows is unsupported. Reports of what works on other distros or OSes are very welcome — open an issue or PR at [github.com/aholbreich/agent-skills/issues](https://github.com/aholbreich/agent-skills/issues). Feedback on SSO flavors, browser detection, profile/port collisions, and unusual Atlassian tenant shapes is especially useful.
 
 ## Skills
 
 | Skill | Purpose |
 |---|---|
 | [`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. |
+| [`jira-update`](skills/jira-update/) | Dry-run-first Jira Cloud writes through an authenticated browser session: create issues, add comments, transition workflows, update fields, and link issues. Markdown-to-ADF conversion by default; ADF passthrough as escape hatch. |
 | [`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. |
 | [`confluence-update`](skills/confluence-update/) | Dry-run-first Confluence page updates, agent-owned block replacement, Markdown-to-storage conversion, and page creation through an authenticated browser session. |
 | [`bitbucket-browser-fetch`](skills/bitbucket-browser-fetch/) | Fetch Bitbucket Cloud project repository inventories and clone URL lists through an authenticated browser session. |
@@ -101,18 +118,22 @@ npx @aholbreich/agent-skills
 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 project
+npx @aholbreich/agent-skills install --target agents          # ~/.agents/skills (default)
+npx @aholbreich/agent-skills install --target claude          # ~/.claude/skills
+npx @aholbreich/agent-skills install --target codex           # ~/.codex/skills
+npx @aholbreich/agent-skills install --target pi              # ~/.pi/agent/skills
+npx @aholbreich/agent-skills install --target project-agents  # ./.agents/skills
+npx @aholbreich/agent-skills install --target project-pi      # ./.pi/skills
 ```
 
+The bare `--target project` is a deprecated alias for `--target project-pi`; use the explicit form. Run `npx @aholbreich/agent-skills paths` to see every target's full path.
+
 Install only selected skills:
 
 ```bash
 npx @aholbreich/agent-skills install --skill jira-browser-fetch
 npx @aholbreich/agent-skills install --skill confluence-browser-fetch
-npx @aholbreich/agent-skills install --skill jira-browser-fetch --target project
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --target project-agents
 ```
 
 Or use the dependency-free interactive picker:
@@ -176,6 +197,7 @@ If installed globally via npm, the package exposes:
 ```bash
 agent-skills
 jira-browser-fetch
+jira-update
 confluence-browser-fetch
 confluence-update
 bitbucket-browser-fetch
@@ -183,14 +205,16 @@ bitbucket-browser-fetch
 
 ## Reuse one Atlassian browser login
 
-To avoid separate Jira and Confluence SSO prompts, use one shared automation profile and DevTools port for both fetchers:
+All five skills share one Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`) by default. Log in once via any skill and the others ride the same SSO session — no env vars required.
+
+To relocate the shared profile or run on a different port:
 
 ```bash
-export ATLASSIAN_CHROME_PROFILE="$HOME/.local/share/atlassian-browser-fetch-chrome"
-export ATLASSIAN_CHROME_DEBUG_PORT=9223
+export ATLASSIAN_CHROME_PROFILE="$HOME/some/other/path"
+export ATLASSIAN_CHROME_DEBUG_PORT=9333
 ```
 
-Skill-specific variables such as `JIRA_CHROME_PROFILE`, `CONFLUENCE_CHROME_PROFILE`, or `BITBUCKET_CHROME_PROFILE` still override the shared profile when needed.
+Skill-specific variables (`JIRA_CHROME_PROFILE`, `CONFLUENCE_CHROME_PROFILE`, `BITBUCKET_CHROME_PROFILE`, and the matching `*_CHROME_DEBUG_PORT`) override the shared values when you intentionally want skill isolation.
 
 ## Bitbucket examples
 
@@ -281,6 +305,54 @@ Example user requests that should invoke this skill:
 - "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."
 
+## Jira update examples
+
+Dry-run an issue creation from a manifest:
+
+```bash
+jira-update create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json
+```
+
+Apply after review:
+
+```bash
+jira-update create \
+  --server https://example.atlassian.net \
+  --file ./new-bug.json \
+  --apply
+```
+
+Add a comment from Markdown:
+
+```bash
+jira-update comment PROJ-123 \
+  --server https://example.atlassian.net \
+  --file ./reply.md \
+  --apply
+```
+
+Transition with a comment:
+
+```bash
+jira-update transition PROJ-123 \
+  --server https://example.atlassian.net \
+  --to "In Progress" \
+  --comment-file ./status.md \
+  --apply
+```
+
+Link two issues:
+
+```bash
+jira-update link PROJ-123 \
+  --server https://example.atlassian.net \
+  --to PROJ-456 \
+  --type blocks \
+  --apply
+```
+
 ## Confluence examples
 
 Fetch one page by URL:
@@ -325,9 +397,9 @@ Disable the limit:
 --max-attachment-size unlimited
 ```
 
-## Output and LLM wiki use
+## Example workflow: populating an LLM wiki
 
-The tools are designed to populate a wiki `raw/` folder. They do not synthesize pages themselves. A typical LLM wiki workflow is:
+One common use case for the fetch skills is feeding an LLM-curated knowledge base. The tools populate a `raw/` evidence folder; they do not synthesize pages themselves. A typical pipeline:
 
 1. fetch Jira/Confluence sources into `raw/`,
 2. treat `raw/` as immutable evidence,

package/bin/agent-skills.js

@@ -40,7 +40,10 @@ Commands:
   help                    Show this help
 
 Options for install:
-  --target NAME           pi | agents | claude | codex | openclaw | project | project-agents | project-claude | project-codex (default: agents)
+  --target NAME           Install destination (default: agents). Run "agent-skills paths" for full paths.
+                          User-scoped:    pi | agents | claude | codex | openclaw
+                          Project-scoped: project-pi | project-agents | project-claude | project-codex
+                          Deprecated:     project (alias for project-pi)
   --dir PATH              Custom skills directory, overrides --target
   --skill NAME            Install only selected skill(s); repeatable, comma-separated, or '*' for all
   --pick                  Interactively choose which bundled skills to install
@@ -54,10 +57,10 @@ Examples:
   npx @aholbreich/agent-skills install --pick
   npx @aholbreich/agent-skills install --target agents --force
   npx @aholbreich/agent-skills install --target pi --force
-  npx @aholbreich/agent-skills install --target project
+  npx @aholbreich/agent-skills install --target project-agents
+  npx @aholbreich/agent-skills install --target project-pi
   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 --dir ~/.pi/agent/skills
   npx @aholbreich/agent-skills list
 
@@ -160,6 +163,9 @@ async function install(args) {
   if (!customDir && !TARGETS[target]) {
     throw new Error(`Unknown target '${target}'. Valid targets: ${Object.keys(TARGETS).join(', ')}`);
   }
+  if (target === 'project' && !customDir) {
+    console.warn('warning: --target project is deprecated; it maps to ./.pi/skills. Use --target project-pi for the same path or --target project-agents for ./.agents/skills.');
+  }
   if (pick && skillFilters.length) {
     throw new Error('Use either --pick or --skill, not both');
   }
@@ -193,9 +199,9 @@ async function install(args) {
   }
 
   console.log(`Done. Installed: ${installed}. Skipped: ${skipped}.`);
-  if (target.startsWith('project') && !customDir) {
+  if ((target === 'project' || target.startsWith('project-')) && !customDir) {
     console.log('Project-local skills are available when running an Agent Skills-compatible tool inside this project.');
-  } else if (target === 'pi' && !customDir) {
+  } else if ((target === 'pi' || target === 'project-pi') && !customDir) {
     console.log('Restart Pi or start a new session to discover newly installed skills.');
   }
 }

package/bin/check.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..');
+
+async function listJsFiles(dir) {
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...await listJsFiles(full));
+    else if (entry.isFile() && entry.name.endsWith('.js')) out.push(full);
+  }
+  return out;
+}
+
+async function collectTargets() {
+  const files = [];
+  for (const d of ['bin', 'lib']) files.push(...await listJsFiles(path.join(repoRoot, d)));
+  const skillsDir = path.join(repoRoot, 'skills');
+  for (const entry of await fsp.readdir(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    files.push(...await listJsFiles(path.join(skillsDir, entry.name, 'scripts')));
+  }
+  return files.sort();
+}
+
+async function main() {
+  const verbose = process.argv.includes('--verbose');
+  const skipVendor = process.argv.includes('--no-vendor');
+
+  if (!skipVendor) {
+    const vendor = spawnSync(process.execPath, [path.join(repoRoot, 'bin/vendor.js')], { stdio: 'inherit' });
+    if (vendor.status !== 0) process.exit(vendor.status || 1);
+  }
+
+  const targets = await collectTargets();
+  const failures = [];
+  const start = Date.now();
+  for (const file of targets) {
+    const rel = path.relative(repoRoot, file);
+    const result = spawnSync(process.execPath, ['--check', file], { encoding: 'utf8' });
+    if (result.status === 0) {
+      if (verbose) console.log(`ok  ${rel}`);
+    } else {
+      console.error(`FAIL ${rel}`);
+      failures.push({ rel, stderr: result.stderr });
+    }
+  }
+  const ms = Date.now() - start;
+
+  if (failures.length) {
+    console.error(`\n${failures.length} file(s) failed syntax check:`);
+    for (const f of failures) {
+      console.error(`\n--- ${f.rel} ---`);
+      console.error(f.stderr.trim());
+    }
+    process.exit(1);
+  }
+  console.log(`Syntax-checked ${targets.length} file(s) in ${ms}ms.`);
+}
+
+module.exports = { collectTargets, listJsFiles };
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}

package/bin/vendor.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..');
+const source = path.join(repoRoot, 'lib/atlassian-browser.js');
+const skillsDir = path.join(repoRoot, 'skills');
+
+if (!fs.existsSync(source)) {
+  console.error(`vendor: source not found at ${source}`);
+  process.exit(1);
+}
+
+const content = fs.readFileSync(source);
+const skills = fs.readdirSync(skillsDir, { withFileTypes: true }).filter(d => d.isDirectory());
+for (const skill of skills) {
+  const scriptsDir = path.join(skillsDir, skill.name, 'scripts');
+  if (!fs.existsSync(scriptsDir)) continue;
+  const dest = path.join(scriptsDir, 'atlassian-browser.js');
+  fs.writeFileSync(dest, content);
+  console.log(`vendored -> ${path.relative(repoRoot, dest)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -39,10 +39,13 @@
     "jira-browser-fetch": "skills/jira-browser-fetch/scripts/jira-browser-fetch.js",
     "confluence-browser-fetch": "skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js",
     "confluence-update": "skills/confluence-update/scripts/confluence-update.js",
-    "bitbucket-browser-fetch": "skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js"
+    "bitbucket-browser-fetch": "skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js",
+    "jira-update": "skills/jira-update/scripts/jira-update.js"
   },
   "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 && node --check skills/confluence-update/scripts/confluence-update.js && node --check skills/confluence-update/scripts/lib.js && node --check skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js && node --check skills/bitbucket-browser-fetch/scripts/lib.js",
+    "vendor": "node bin/vendor.js",
+    "check": "node bin/check.js",
+    "pretest": "npm run vendor",
     "test": "node --test",
     "ci": "npm run check && npm test && npm pack --dry-run",
     "pack:dry": "npm pack --dry-run",

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

@@ -36,6 +36,20 @@ Important options:
 --profile-dir DIR  Chrome profile dir
 ```
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+Bitbucket sits on `bitbucket.org` rather than `*.atlassian.net`, so its cookies are scoped separately, but sharing one Chrome profile/port still avoids spawning extra browser windows.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-login — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Example
 
 ```bash