Changelog

All notable changes to the Jira Integration Skill will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

3.29.1 - 2026-08-28

Documentation

• expand=transitions.fields under-reports the resolution field: a transition that reports it absent may still accept --resolution and set it. Attempt the transition with --resolution and treat only the "cannot be set" error as a rejection (intent-verbs)

3.29.0 - 2026-08-27

Changed

• jira-qa-gather prints the description and every comment (all pages, chronological, with author and date — the same rendering as jira-issue work) in its text output, so a QA reviewer no longer needs a second jira-issue work KEY call per ticket; --no-body restores the metadata-only shape, and --json gains a description key. The shared rendering moved to lib/render.py
• jira-link create FROM TO without --type now fails with a usage error that shows the --type Relates example and points to list-types, instead of the bare Missing option '--type' / '-t'

3.28.0 - 2026-08-17

Added

• Every command that posts mention-capable wiki markup verifies [~username] mentions against Jira inside the posting call — jira-comment add/edit, jira-transition do --comment, jira-worklog add --comment, and the --description of jira-create issue/jira-issue update. An unknown username aborts with candidate suggestions in the form that actually notifies ([~name] on Server/DC, [~accountid:...] on Cloud, where a plain username mention can never notify and is always flagged); mentions inside {code}/{noformat} blocks and backslash-escaped literals are ignored; auth/transport failures surface as themselves, never as "unknown user". Skip with --no-verify-mentions (#199)
• jira-issue get/work/qa, jira-comment list, jira-worklog list and jira-board print the technical identifier next to each display name (Server/DC username, accountid:<id> on Cloud), so ticket participants can be mentioned or assigned without a separate user lookup (#199)

Fixed

• lib.client.resolve_assignee and the new lib.users.find_users (now also used by jira-user.py's fallbacks) search users with username= on Server/DC (query= only on Cloud) — the previous unconditional query= returned the library's error string on Server/DC, so email identifiers only ever resolved through the raw fallback (#199)
• resolve_assignee resolves an exact username first and accepts a search result only on an exact field match or a single unambiguous candidate; with several fuzzy candidates it falls back to the raw identifier so Jira rejects it visibly instead of silently assigning an arbitrary user (#199)

3.27.1 - 2026-08-14

Fixed

• jira-create accepts - for --description to read the description from stdin, matching jira-issue update (#196)

[3.27.0] - 2026-08-13

Documentation

• jira-communication: references/comments.md documents how to verify a comment actually renders as intended — GET .../comment/<id>?expand=renderedBody and what to grep for (<del> = strikethrough trap fired, literal backslash = escape leaked, - = correctly escaped dash). A 2xx on add/edit proves the write, not the rendering.

Documentation

• AGENTS.md: the release workflow goes through a release PR now — main requires pull requests, so the old direct-push flow only worked via owner bypass. The steps also name all four version surfaces (.claude-plugin/plugin.json, plugin.json, both SKILL.md), require the signed annotated tag on the verified merge commit (the old step 7 showed a lightweight tag), and describe the actual release artifacts (zip + tar.gz per package, checksums with Sigstore signature, SLSA provenance).

[3.26.0] - 2026-08-13

Fixed

• jira-syntax: validate-jira-syntax.sh no longer fails wholesale on the hybrid template files (#190). Files containing Markdown code fences are wrappers around a Jira-markup payload: the untagged fences are now extracted and validated as Jira markup, while language-tagged fences (bash usage examples) and wrapper prose are skipped. Draft files without fences keep the full strict treatment, so templates/*.md validate their actual payload and the documented build check exits 0.

Added

• jira-communication: the pre-post markup lint (lib/markup.py, used by jira-comment.py add/edit) flags flag-like tokens (--strict) outside code blocks (#189) — Jira parses -text- as strikethrough, even inside {{...}} monospace, so a pair of CLI flags strikes through everything between them. Escaped dashes (\-) pass; em/en-dash typography and single-dash options stay out of scope. Same rule as the jira-syntax shell validator; --force semantics unchanged.

• jira-syntax: validate-jira-syntax.sh warns on flag-like tokens (--strict) outside {code}/{noformat} blocks. Jira parses -text- as strikethrough, the opening dash needs only whitespace (or a {{ monospace opener) before it, and text effects apply inside {{...}} monospace, so a pair of CLI flags in prose strikes through everything between them. Backslash-escaped dashes (\-) pass.

Documentation

• jira-syntax: references/jira-syntax-quick-reference.md documents the dash-strikethrough trap for CLI flags and the escape — {{\-\-strict}} renders as literal --strict, each \- reaching the rendered HTML as a - entity (verified against the Jira Server 9.12 wiki renderer).
• jira-communication: references/troubleshooting.md corrects the task-checkbox claim — inline {task} checkboxes ARE toggleable via the API; the old claim had probed the wrong endpoint (#187).
• jira-communication: references/troubleshooting.md drops its internal-skill pointer (public repo), inlines the curl gotchas, and makes the 204 wording precise.

3.25.1 - 2026-08-12

Fixed

• List jira-create.py in the detected-issue reminder (hook)

3.25.0 - 2026-08-08

Added

• Add delete subcommand; report assignee and empty link sets in qa-gather (worklog)
• Add Agent Plugins 1.0.0 portable manifest (manifest)

Fixed

• Pass limit= to user_find_by_user_string (jira-user)
• Declare the split license in both manifests (license)

3.23.1 - 2026-07-30

Fixed

• jira-communication: jira-create.py project --bootstrap-issues printed its ✓ Created KEY-1: Projektmanagement line to stdout even under --json / --quiet, so the JSON payload failed to parse (json.loads → "Extra data") and --quiet emitted two lines instead of the project key. _create_bootstrap_issues accepted the context dict but never consulted it; it now suppresses the line in both modes. Covered by two regression tests.

Documentation

• jira-communication: references/troubleshooting.md documents both --json | jq failure modes. jq: parse error: Invalid numeric literal at line 1, column 10 is uv run's cold-cache Installed N packages notice reaching jq — uv writes it to stderr, so only a merged pipe (2>&1, a wrapper, or a harness capturing combined output) breaks, with grep -v '^Installed' as the fallback. Cannot index array with string is the payload shape: list-style subcommands emit a bare array, so the path is .[], never .issues[]. Includes a per-subcommand array-vs-object table (watchers list is the one list subcommand that wraps its result).
• jira-communication: references/watchers.md shipped a broken bulk-watch pipeline (jq -r '.issues[].key'), which exits 5 against a bare array. Corrected to .[].key.
• jira-communication: the --resolution rule is no longer unconditional. Workflows whose terminal transition screens omit the field reject --resolution outright, and a follow-up --fields-json update fails on the edit screen for the same reason. Documented handling: prefer another terminal transition whose screen carries the field, otherwise transition without --resolution and verify with resolution is EMPTY rather than assuming the workflow post-function fired. Covered in SKILL.md and references/intent-verbs.md, cross-linked from the generic "Field 'xyz' cannot be set" section in references/troubleshooting.md.
• jira-communication: references/versions.md records that renaming a version propagates to every issue carrying it — issues hold a reference by numeric ID — so the rolling-placeholder release pattern needs no per-issue fixVersions pass. Verified against a sandbox project: the issue's fixVersions name changed with the version untouched by any issue edit. Also documents the sharp edge that the old name does not merely stop matching in JQL, it becomes invalid (The value '<old>' does not exist for the field 'fixVersion', non-zero exit), so saved filters keyed on the old name break loudly rather than returning nothing.
• jira-communication: references/versions.md also warns that version create / update require project-admin rights, while assigning an existing version to an issue is an ordinary issue edit. A plain project member can do the latter and not the former, and the failure surfaces mid-procedure.
• jira-communication: references/issue-editing.md's labels section generalised to all array-valued fields. jira-issue.py update has no append path (Jira's update verb with add/remove is not exposed), so fixVersions, versions and components are replaced wholesale by --fields-json; only labels has incremental --add-label / --remove-label.
• jira-communication: references/links.md dropped its "Real-world reference" section, which pointed at the internal-only netresearch-jira skill (via a dead GitHub URL). A public, general-purpose skill should not send readers to a reference they cannot reach; the direction semantics it corroborated are already documented in full here. Same policy applied to the two other pointers at the internal-only skill: the routing aside in references/intent-verbs.md is now phrased generically, and the _create_bootstrap_issues docstring in jira-create.py keeps the convention's name without the unreachable file path.

3.23.0 - 2026-07-27

Changed

• jira-communication: jira-create.py project --bootstrap-issues now creates only the XXX-1 config-hub issue, using this Jira instance's dedicated "Issue Number One" issue type (summary "Projektmanagement") instead of a plain Task — falls back to Task if a --from-project template's issue type scheme doesn't include it. No longer auto-creates a PM Epic or Deployment Epic (dropped as unnecessary bootstrap overhead — create them by hand if a project actually needs them).

3.22.1 - 2026-07-26

Fixed

• jira-communication: jira-create.py project --bootstrap-issues failed to create both Epic-type issues ("Epic Name is required") — this Jira instance requires the Epic Name custom field, which wasn't being set. Now populated automatically from the issue summary.
• jira-communication: jira-create.py project now checks whether KEY-1 already resolves to an issue before creating — reusing an old, renamed-away project key silently skips Jira's issue numbering (the old key's redirect is permanent), so the new project's first bootstrap issue would silently NOT be KEY-1. Aborts with a clear error unless --force is passed. Discovered during a real project creation where the key had been used by a project since renamed to a different key back in 2012.

3.22.0 - 2026-07-25

Added

• jira-communication: jira-create.py project creates a new Jira project by copying the permission/notification/workflow schemes from an existing project, with an optional --bootstrap-issues flag for the XXX-1/2/3 (config hub, PM epic, deployment epic) convention (#165).
• jira-communication: new tempo-account.py script (customer create, account create, account link) wrapping Tempo Accounts management (#165).

Documentation

• jira-syntax: documented that validation gates the post — run it as its own step, never chained with the posting command (#164).
• jira-communication: documented clearing a field via --fields-json with an explicit null (typed flags like --assignee "" are a no-op) (#164).

3.21.1 - 2026-07-18

Documentation

• jira-communication: issue-editing.md's reference-index entry now points to --fields-json for custom-field updates, so it is found before guessing a non-existent --field flag (#158).

3.21.0 - 2026-07-16

Added

• jira-communication: wiki-markup lint flags inline emphasis (*bold*, _italic_) glued mid-word, where Jira does not render it (#160).

Documentation

• jira-communication: documented that jira-search.py query-subcommand options (-f, -n, --order-by) must come after query, not before it (#161).

3.20.0 - 2026-07-13

Added

• jira-communication: wiki-markup lint flags || (header separators) inside table data rows, with escaped-pipe handling (#153).

Changed

• jira-syntax: trimmed generic content from the quick-reference; fixed TOC links and the inline-code placeholder (#156).

Documentation

• jira-communication: skill triggers on keyless Jira intent ("create/find a ticket", "pick a project"); clarified MCP-connector access (#154).
• jira-syntax: noted PowerShell has no code-block lexer; added validator hint (#155).

3.19.0 - 2026-07-06

Added

• jira-communication: jira-worklog-query.py gains --tempo-account to query a customer/Tempo account's worked time (#149).

3.18.3 - 2026-07-01

Documentation

• All skills: added a "no editorializing" rule for written output — commit messages, PR/MR descriptions, review comments, tickets, and chat state what changed, not how good it is (#150).
• AGENTS.md: documented the atlassian-python-api >=3.41,<4 pin rationale (no Jira Cloud test tenant) (#148).

3.18.2 - 2026-06-27

Fixed

• hooks: the Jira-key guard no longer flags CWE/CVE/encoding IDs or PROJ-123-style placeholders as real keys, and blocks the PROJ/EXAMPLE/AES/TLS prefixes (#146).

Documentation

• jira-communication: check jira-attachment download exit status instead of file size, and document its auth requirement (#145); document unassigning an issue (#144).
• jira-syntax: document the (/) and (x) status emoticons and checklist semantics (#141).

3.18.1 - 2026-06-24

Documentation

• jira-communication: note the Jira Cloud [~accountId] mention form, transition-by-status-name, and [~mention] username gotchas (#140).
• jira-editing: epic-link is edit-screen-only; subtask↔standard conversion is via the UI "Convert to Issue" (#142).

3.18.0 - 2026-06-18

Added

• jira-attachment download-all: bulk-download every attachment on an issue in one call, with per-file progress and resilient error handling (#134).
• jira-issue transition: tolerant, Unicode-safe transition-name matching — transitions resolve case- and whitespace-insensitively (and across Unicode normalisation forms) instead of requiring an exact label match (#136).

Fixed

• jira-communication: surface the comment count and never render requested fields silently — when a field is requested but absent it is reported rather than dropped without notice (#127, #130).

Documentation

• jira-syntax: clarified wiki-markup escaping rules and fixed table pipe (|) escaping in the reference (#133).
• jira-syntax: warn that a bare GitLab !N reference renders as image markup in Jira wiki syntax (#138).

3.17.0 - 2026-06-11

Added

• jira-comment add / edit: comments are now linted for wiki-markup problems before posting. The new lib/markup.py lint_wiki_markup() helper catches the most damaging authoring mistakes: block-markup tags ({code}, {noformat}, {quote}, {panel}) used inline — these are block-level macros, so an unescaped tag with other text on the same line opens a real block mid-prose and swallows the rest of the line — plus unbalanced (odd-count) block tags and unclosed blocks. Escaped tags (\{code\}), inline-monospace lookalikes ({{code}}) and other tags inside an open block are ignored, matching the Jira Server 9.12 renderer. Findings abort the post with an explanatory error; --force posts anyway and downgrades findings to warnings. (#131)
• validate-jira-syntax.sh: new error for block tags used inline (same rule as the comment lint; escaped \{code\} literals and {{code}} monospace lookalikes are stripped per line before testing), and a new warning for unescaped * inside {{...}} monospace blocks, which turns bold mid-token (e.g. {{jira-*backup-*}} renders "backup-" bold). Escape as \*.

Changed

• validate-jira-syntax.sh: the unescaped-brace-inside-{{...}} check now skips backslash-escaped braces (\{ \}), which render literally and are fine; the {code} language extraction and the tag-balance counts for {code}/{panel}/{noformat}/{quote}/{anchor} now ignore escaped literals (\{code\}) and inline-monospace lookalikes ({{code}}) — both are prose, not block markup.
• references/cross-project-refs.md and the quick reference now document escaping (\{ \} \*) as the primary fix for literal braces and * inside {{...}} monospace, verified against the Jira Server 9.12 wiki renderer; splitting into separate {{...}} references remains a fallback when escaping hurts readability.

3.16.0 - 2026-06-09

Added

• jira-transition path KEY TARGET_STATUS: walk a multi-stage workflow to a target status in one call, instead of repeating list + do per stage. Runs the list → pick → do loop internally. Because the Jira API only exposes transitions from the issue's current status, the walk is greedy rather than a full graph search: at each step it takes the target if directly reachable, else the single non-backward transition (names matching reopen/cancel/reject/decline/abort/back, or targets already visited, count as backward); an ambiguous step stops and lists the options for an explicit do. --resolution/--comment apply to the final transition only, --max-steps (default 10) caps the walk, and --dry-run previews the first step. Motivated by closing a ticket sitting deep in a QA → UAT → Ready for deployment → Resolved → Closed workflow, which previously cost 8 round-trips. Documented in references/intent-verbs.md.

3.15.0 - 2026-05-28

Fixed

• jira-search query, jira-qa-gather, jira-worklog-query: JQL search now works on Atlassian Cloud. Atlassian's CHANGE-2046 removed /rest/api/2/search and /rest/api/3/search from Cloud; atlassian-python-api hardcodes api_version=2 so its jql() method failed with "The requested API has been removed" on every *.atlassian.net instance. LazyJiraClient.jql() now overrides the library and calls the new cursor-paginated /rest/api/3/search/jql endpoint directly on Cloud while Server/DC still goes through the library unchanged. The override translates cursor pagination (nextPageToken/isLast) back to the startAt/total shape the callers expect, so paginating loops keep terminating correctly on Cloud — no caller changes needed. Cloud detection uses is_cloud_url(client.url) (strict .atlassian.net match) rather than the library's cloud flag for cross-version robustness. Surgical override rather than bumping atlassian-python-api to 4.x — the 4.x line still has open Cloud-pathway bugs and the project cannot verify against a Cloud tenant. Inefficiency caveat: each call drains pages from index 0 up to start + limit because the new endpoint is cursor-based and we cannot resume from an offset, so deep pagination is O(N²) until upstream Cloud-aware jql() lands. Original fix by @rschmied in #107; pagination + Cloud-detection hardening in #112.

Changed

• validate-jira-syntax.sh: the "Unsupported {code:<lang>} language" error now suggests the closest-fit valid language for common stumbles instead of always falling back to the full valid-languages list. Identifiers are matched case-insensitively (Dockerfile, Makefile, HCL, TypeScript etc. all resolve). Recognised hints: hcl/tf/terraform/tofu → {code:none}, dockerfile/containerfile → {code:bash} or {code:none}, rust/rs → {code:none}, kotlin/kt → {code:java} or {code:none}, typescript/ts/tsx → {code:javascript} or {code:none}, shell/zsh/fish/console → {code:bash} or {code:none}, make/makefile → {code:none}, ini/toml/conf/properties → {code:none}, diff/patch → {code:none}, go-template/gotmpl/jinja/jinja2 → {code:none}. Unknown languages still get the full valid-languages list.

Added

• jira-issue update --description / -d: typed flag for plain description edits — previously required --fields-json '{"description": "..."}' with its JSON-escaping fragility. --description - reads the body from stdin so multi-line wiki markup can be piped in without shell-escape gymnastics. references/issue-editing.md updated; the long-tail --fields-json route remains for custom-field payloads.
• jira-issue work / qa / qa-fail / act: four single-call intent verbs that compose existing API endpoints (issue + comments + changelog + remote_links + transitions) into the right bundle for one specific intent — replacing the common jira-issue get + jira-comment list 2-call (or worse, with shell-side filtering, 5–6-call) pattern.
  • work KEY — description + all comments + attachments + links (use when starting work on a ticket)
  • qa KEY — description + handover bundle (comments around the most recent INTO_QA transition, before-or-after agnostic — empirically 80% of handover comments precede the transition click)
  • qa-fail KEY — description + reviewer rejection comment + implementer scope/clarification context from the same QA window
  • act KEY — meta + available transitions (one call before transitioning, replaces meta-fetch + transition-list)
  • All verbs support --json, --quiet and the standard global flags; work, qa, qa-fail also support --truncate N (act has no body to truncate)
  • Status-set classification configurable per profile via qa_status_names / working_status_names / resolved_status_names (or env vars). Defaults cover common single-stage and multi-stage QA workflows. Multi-stage progressions (QA→QA2, Review→UAT, QA→Acceptance) are correctly classified as forward, not as fail.
  • SKILL.md ## Auto-Trigger rewritten as an intent-routing table; references/intent-verbs.md documents the heuristics, status sets, and configuration.
• lib/changelog.py: extract_status_transitions_with_authors(), classify_transition(), find_transition_window() helpers used by the intent verbs.
• lib/config.py: load_status_sets(profile=...) resolves the three status sets from profile fields, env vars, or built-in defaults.
• jira-link create: --source / --target named aliases for FROM_KEY / TO_KEY. --source S --target T --type X is equivalent to create T S --type X. Mixing positional with named forms is rejected. The named form is recommended when the direction matters (it always does) so the call-site reads as English instead of relying on positional convention.
• jira-link bulk-create: read a CSV (--from-csv PATH, or - for stdin) with header from,to,type and create one link per row, mirroring the same direction convention as create ("TO does X to FROM"). --dry-run previews each resolved sentence without POSTing. --skip-existing checks the FROM ticket's issuelinks and skips rows where a link of the same type already connects FROM and TO (either direction) — useful because Jira Server is not idempotent on link creation. --abort-on-error (default) halts on the first failed row; --continue-on-error logs and keeps going. Per-row output uses [N/M] indices, ends with a created: K, skipped: S, failed: F summary, and the --json mode emits one JSON object per line plus a final summary: true object (JSONL). Link types are resolved once via a single get_issue_link_types() call regardless of how many rows reference them.
• jira-link bulk-delete: delete many issue links by ID, either from a comma-separated --ids list or a file (--ids-file PATH, - for stdin). Each ID is fetched first so per-row output shows the affected issues ([101] TEST-2 ↔ TEST-1 (Blocks)). Same --dry-run, --abort-on-error / --continue-on-error, and JSONL summary semantics as bulk-create.
• jira-link invert: one-shot fix for a backwards link. Given --id N, fetches the link, deletes it, and re-creates it with FROM/TO swapped. --dry-run shows Would invert: <current sentence> → <new sentence>. If the inverted POST fails, the script attempts to re-create the original; if that rollback also fails, it exits non-zero with an INCONSISTENT STATE error referencing both directions and the original link ID so the human can fix it in the Jira UI.
• jira-search query --order-by "FIELD [ASC|DESC]": append an ORDER BY clause to the JQL without editing the query string. Repeatable for multi-key sorts (--order-by "priority DESC" --order-by "created ASC" produces one comma-separated ORDER BY). Errors with exit 2 if the JQL already contains ORDER BY and points at the embedded form as the natural alternative.
• references/jql-quick-reference.md: new top-level "Sorting (ORDER BY)" section near the top showing both equivalent forms (embedded vs. flag).

3.13.1 - 2026-04-30

Added

• jira-syntax: validator now flags {code:LANG} whose LANG is not in the Jira Server source-code formatter set, mirroring the server-side error and pointing at {code:none}. Quick reference replaces the vague "many more — check Jira documentation" line with the authoritative formatter list grouped by category, calls out the literal c#/c++ form, and lists common identifiers that look valid but are not (typescript, rust, shell, yml, typoscript). (#94)

Fixed

• jira-worklog list: extract plain text from Cloud ADF ({type, content}) comment payloads instead of rendering the raw dict's repr(); --truncate no longer raises TypeError when slicing such a comment. Adds a shared comment_to_text() helper in lib/output.py (also used by jira-worklog-query.py) that normalizes None / Server-string / Cloud ADF dict comment shapes to text. (#92)
• jira-syntax validator: switch ERRORS/WARNINGS counters to pre-increment so (( )) returns the new (non-zero) value — the post-increment form returned 0 on first call and tripped set -e, aborting the script before the summary printed and making warning-only runs exit with code 1.
• jira-syntax validator: treat {code:language} as a placeholder warning rather than a hard error so the bundled templates (which intentionally ship the literal word "language" as a fill-in) still run cleanly.
• jira-syntax validator: use Bash built-in [[ ]] pattern matching for the {code:LANG} membership test — avoids spawning printf+grep per unique language and keeps shell-significant identifiers (c#, c++) literal.
• jira-syntax quick reference: backtick the <name> token in the reference blockquote so Markdown renderers don't strip it as an HTML tag.

Changed

• CI/release: grant the reusable release workflow id-token: write and attestations: write (required by actions/attest-build-provenance for SLSA build-provenance attestations on release archives); drop unused pull-requests: write. Drop the deprecated with: { bump, attest } inputs and the workflow_dispatch trigger from .github/workflows/release.yml — both inputs are ignored upstream and the manual trigger did nothing useful since releases ship via signed tag-push only. (#91, #93)

3.13.0 - 2026-04-27

Added

• jira-qa-gather.py: Single-call discovery utility for QA reviewers. Returns issue + description + comments + worklog + structured issue links + web/remote links + URLs extracted from prose (MR/PR/pipeline/commit/tag/release/issue) + sibling tickets in one shot. Supports --json, --quiet, --no-siblings, --sibling-window, --max-siblings. Designed for the peer-qa-review skill but useful for any review workflow. Reuses comment data from the initial issue fetch (no second API call); sibling search uses updated >= -Nd so open tickets are included; project/issue keys quoted in JQL; exception messages sanitized via _sanitize_error. CLI smoke tests added in tests/test_cli_smoke.py. Companion reference references/qa-gather.md. (#80)
• jira-search.py --start-at: server-side pagination flag for large result sets.

Fixed

• jira-syntax: correct closing-tag detection for {code} and {panel} macros; tighter regex; here-string + occurrence-count rewrite; restore executable bit on validate-jira-syntax.sh; remove false-positive suppression from inline-code warning.
• jira-search: harden pagination output and validation.
• jira-validate: use LazyJiraClient in check_connectivity; always show the "ignored --profile" warning when applicable.
• jira-transition: fix hardcoded comment truncation.
• SKILL.md compatibility line: drop curl from the dependency list (no longer required).

3.12.0 - 2026-04-19

Added

• jira-watchers.py: List, add, and remove watchers on issues with --dry-run previews and idempotent self-watch defaults. Surfaces isWatching state in the list header, distinguishes 403 vs 404 error shapes, and pins DC vs Cloud watcher-delete parameter mapping.
• jira-version.py: Full version CRUD — list (paginated, --query, --order-by, client-side status filter), get (by ID or name with --project, optional --counts), create (dates, flags, --dry-run, 409 duplicate-name surfacing), update via safe-merge helper (GET + merge + PUT), release/unrelease, archive/unarchive, move (--after / --position), merge (--dry-run counts preview), delete (with reassign flags, orphan warning, dry-run reference counts).
• evals/run-evals.sh — headless runner for the comprehensive eval suite using claude --print --output-format stream-json --plugin-dir. Emits per-eval pass/fail and tool-call counts, plus an optional consolidated --results-json. Documented in root AGENTS.md.
• 5 new eval cases (IDs 14–18) probing reference-load behavior for the refactored skill.
• Reference docs watchers.md and versions.md with "When to load" headers.

Changed

• Progressive-disclosure refactor of jira-communication/SKILL.md: extract advanced examples into 8 new feature-class references (issue-editing, creation, comments, worklog, attachments, links, agile, fields-and-users). SKILL.md drops from 491 to 392 words. All 12 references carry standardized "When to load" headers so Claude loads the right one on demand. A 3× baseline + 3× post-refactor eval comparison shows zero pass→fail regressions, and tool-call delta ≤ +1 per eval versus the stricter max_baseline vs min_post rubric (worst case: eval 11 gains one Read call to load references/creation.md).
• Scrub Netresearch-specific identifiers (doreen.wienhold, doreen) from eval prompts; create-issue-with-reporter uses paul.siedler as the reporter and the former user-search eval is reframed as user-me to exercise jira-user.py me.

3.11.0 - 2026-04-17

Added

• jira-link.py list: List all issue links on an issue with IDs, link type, direction, and related issue key/summary/status. Supports --json and --quiet output modes.
• jira-link.py delete: Remove an issue link by --id or by the combination of --to/--type. Detects ambiguous matches and requires --id to disambiguate. Supports --dry-run preview.
• jira-issue.py time-in-status PROJ-123 [--status X]: report cumulative time an issue has spent in each status (or in a single status when --status is given). Re-entered statuses are summed. --status accepts a fuzzy term — "review" resolves to "In Review" on most instances; ambiguous matches list candidates. (#72)
• jira-board.py list --name PATTERN: server-side partial match on board name, so the Jira API does the filtering. Eliminates pulling thousands of boards to grep client-side on large instances. (#72)
• references/jql-cookbook.md: translation guide for turning natural-language queries like "open bugs stale for 2 weeks" into safe JQL. Covers statusCategory vs. status, "blocked" disambiguation, resolver pointers, and worked examples. Complements the existing jql-quick-reference.md. (#72)

Changed

• SKILL.md: add examples for the new jira-link list/delete subcommands and the previously-undocumented jira-weblink delete. Full CRUD for both scripts is still discoverable via --help; SKILL.md shows the operations most relevant to the new delete workflow within the 500-word cap.
• jira-issue.py --json get now returns compact JSON by default — null and empty-list fields are stripped, trimming the typical issue payload from ~50 KB (dominated by null customfield_* entries) to a few KB. Pass --raw to restore the full Jira response. (#72)
• SKILL.md: add examples for jira-issue get --expand changelog,transitions, compact-vs---raw JSON, time-in-status, and jira-board list --name. Reference the new jql-cookbook.md.

3.10.1 - 2026-04-16

Fixed

• Windows: ensure UTF-8 stdout/stderr to prevent charmap codec errors that caused duplicate Jira operations (issues, comments, transitions) when Unicode status symbols failed to print after successful API calls (#61)
• DRY up Windows UTF-8 stream configuration — config.py now reuses output._ensure_utf8_streams() instead of duplicating the logic
• Fix ruff F541 lint error (f-string without placeholders) in jira-user.py

3.10.0 - 2026-04-16

Added

• jira-attachment.py add: Upload files as Jira issue attachments with --dry-run preview. Supports --json, --quiet, and default output modes. (#64)
• jira-create.py --reporter: Set issue reporter at creation time via --reporter / -r flag, reusing resolve_assignee() for user resolution. (#62)
• jira-user.py search: Search users by partial name, username, or email with --limit option. Server/DC and Cloud API fallback. (#62)
• Evals 11-13 with baseline/iteration proofs for reporter, user search, and attachment upload

Fixed

• CI: renamed lint.yml to validate.yml per skill-repo convention (#63)

3.9.0 - 2026-04-09

Added

• jira-weblink.py: Full CRUD for Jira web links (remote links) — add, list, update, delete subcommands for managing external URLs on issues. Supports identification by link ID or URL with proper conflict detection. (#60)
• jira-issue.py get: Now displays issue links (with directional arrows →/←) and web links ([id] title — url) in both text and JSON output. Web links available as webLinks key in JSON. (#60)
• --fields weblinks pseudo-field to explicitly request web link fetching when filtering fields

Fixed

• --fields parsing now filters empty tokens and preserves field order
• Removed duplicate LICENSE file (split licensing already covered by LICENSE-MIT and LICENSE-CC-BY-SA-4.0)
• Corrected composer.json license field to (MIT AND CC-BY-SA-4.0)
• Added CLAUDE.md symlinks in skill directories for agent discovery
• CI: use reusable harness-verify workflow from skill-repo-skill

3.8.0 - 2026-04-02

Added

• jira-worklog-query.py: Cross-cutting worklog query tool with date range, user, project, issue, epic, and sprint filters. Supports summary, detail, JSON, and quiet output modes. Auto-detects Tempo Timesheets plugin for faster server-side filtering with fallback to Jira REST API. (#59)

Fixed

• Use ${CLAUDE_SKILL_DIR} for script paths in SKILL.md for portability (#58)

3.7.0 - 2026-04-02

Added

• jira-issue.py delete: Delete issues with --dry-run preview and --delete-subtasks support. Uses library's native delete_issue() method. Closes #54. (#56)
• jira-move.py type change: Support changing issue type within the same project via --issue-type flag (e.g., jira-move issue PROJ-123 PROJ --issue-type Task). Matches Jira's own "Move" semantics. Closes #55. (#57)

Fixed

• Hook output shows absolute uv run commands instead of bare script names
• Pre-existing ruff lint error in test file (extraneous f-string prefix)

3.6.1 - 2026-03-26

Fixed

• Resolve all open issues: multi-profile auto-resolution, error sanitization, validate script improvements (#47, #48)
• Pin reusable workflow reference to commit SHA (#49)
• Use branch ref for org-internal reusable workflows (#52)

Changed

• Update astral-sh/setup-uv action to v8 (#53)

3.6.0 - 2026-03-22

Added

• --assignee me support: Shared resolve_assignee() in lib/client.py resolves "me" via client.myself() on Cloud and Server/DC. Works on any script with --assignee. (#38)
• Subtask type auto-detection: resolve_subtask_type() queries Jira API subtask boolean — no naming convention assumptions. jira-create.py auto-resolves when --parent given. (#39)
• jira-fields.py types [PROJECT]: List available issue types with subtask flag
• jira-comment.py delete: Delete comments. Closes #33. (#40)
• Skill evals: 14 eval scenarios testing all common Jira operations

Changed

• SKILL.md rewritten for direct execution: Copy-paste recipes for all operations. Agents go from 3-9 tool calls to 1 per task (-52% average)
• Assignee resolution deduplicated: Shared resolve_assignee() replaces duplicated blocks in jira-create.py and jira-issue.py

3.5.0 - 2026-03-21

Added

• jira-move.py: Move issues between projects (#37)

3.4.0 - 2026-03-17

Added

• Agent Skills spec frontmatter and improved descriptions

3.3.5 - 2026-02-27

Fixed

• jira-issue.py: Guard assignee lookup against non-list API response on Server/DC
• jira-create.py: Same assignee lookup fix applied to issue creation
• plugin.json: Align plugin name with SKILL.md
• composer.json: Rename package to match repository name

Documentation

• SKILL.md: Add working directory note clarifying script path context

3.3.4 - 2026-02-25

Added

• Multi-profile support: Work with multiple Jira instances via ~/.jira/profiles.json (#15)
  • New config format ~/.jira/profiles.json with named profiles and project mappings
  • Automatic profile resolution: URL host matching, project key mapping, directory context
  • --profile/-P flag added to all 14 CLI scripts
  • jira-setup.py --profile NAME: Create/update named profiles interactively
  • jira-setup.py --migrate: Convert existing ~/.env.jira to profiles.json
  • jira-validate.py --profile NAME: Validate specific profile
  • jira-validate.py --all-profiles: Validate all profiles with status table
  • .jira-profile file support for per-directory profile selection
  • Hook script detects and suggests profiles from issue keys and URLs
  • Full backwards compatibility: ~/.env.jira continues to work as fallback
• New library functions in scripts/lib/config.py:
  • load_profiles(): Load and validate profiles.json
  • resolve_profile(): Priority-based profile resolution algorithm
  • profile_to_config(): Convert profile to env-style config dict
  • load_config(): Unified loader combining profiles and legacy env files
• Comprehensive test suite: 187 tests covering CLI smoke tests, config, client, and security (#15)

Fixed

• SKILL.md: Clean frontmatter and align description with quality standards

3.3.3 - 2026-02-20

Internal maintenance release (CI improvements).

3.3.2 - 2026-02-15

Fixed

• SKILL.md: Align description with writing-skills quality standard

3.3.1 - 2026-02-07

Internal maintenance release (CI improvements).

3.3.0 - 2026-01-30

Added

• allowed-tools field (experimental): Pre-approved tool permissions per Agent Skills spec
  • jira-communication: Bash(uv run scripts/*:*) Read
  • jira-syntax: Bash(scripts/validate-jira-syntax.sh:*) Read
  • See: https://agentskills.io/specification#allowed-tools-field
• GitHub Actions release workflow: Automated package building on tag push (#11)
  • jira-integration-plugin-*.zip - Full plugin for multi-skill platforms
  • jira-communication-skill-*.zip - Standalone skill for Claude Desktop
  • jira-syntax-skill-*.zip - Standalone skill for Claude Desktop

Changed

• README.md: Clarify this is a plugin containing skills, not a standalone skill
• README.md: Add installation options for plugin vs individual skill packages
• README.md: Reference Agent Skills specification for cross-platform compatibility
• Remove root-level SKILL.md (redundant for plugin architecture)

3.2.1 - 2026-01-22

Fixed

• hooks.json: Remove duplicate hooks declaration (#12)

3.2.0 - 2026-01-22

Added

• UserPromptSubmit hook: Auto-detect Jira issue keys in user prompts (#10)
• AGENTS.md: Document release workflow

3.1.6 - 2026-01-14

Fixed

• jira-issue.py: Use accountId for assignee updates on Jira Cloud (#9)
• jira-link.py: Use correct API format for create_issue_link
• Documentation: Add working directory note and fix script tables (#8)

3.1.5 - 2026-01-07

Changed

• SKILL.md: Reduce size for context efficiency

3.1.4 - 2026-01-07

Changed

• jira-communication SKILL.md: Reduce size for context efficiency

3.1.3 - 2026-01-06

Added

• Agent Skills branding: Cross-platform compatibility improvements (#6)

Fixed

• plugin.json: Update skills schema to path strings format (breaking schema change)

Changed

• Author metadata: Remove email from author nodes, add URL to plugin.json
• Documentation: Add source repository footer for contributions

3.1.2 - 2025-12-19

Added

• Auto-trigger: Automatic activation on Jira URLs and interactive auth setup
• CAPTCHA detection: Challenge detection for Jira Server/DC authentication

Fixed

• Security: Address security issues identified by CodeQL scan
• skill-creator: Apply skill-creator best practices to SKILL.md files

3.1.1 - 2025-12-15

Fixed

• composer.json: Add Netresearch to description, update email

3.1.0 - 2025-12-12

Added

• Attachment support: Download and list issue attachments via jira-issue.py
• Output improvements: Enhanced table formatting and field display (#4)

Fixed

• jira-transition.py: Use set_issue_status for Jira Server/DC compatibility
• jira-comment.py: Restore comment support via update parameter
• Consistency improvements: Standardized output formatting across scripts

Documentation

• AGENTS.md: Adopt agents.md convention for AI agent instructions
  • Root AGENTS.md with global rules and SKILL.md conventions
  • Scoped AGENTS.md files for jira-communication and jira-syntax skills
  • CLAUDE.md now symlinks to AGENTS.md for backward compatibility
• Branding: Added Netresearch attribution to README.md and SKILL.md

3.0.2 - 2025-11-26

Added

• composer.json: Composer-based skill package distribution via netresearch/agent-jira-skill
• references/jql-quick-reference.md: Validated JQL syntax reference (validated against official docs)
• references/troubleshooting.md: Setup and error guidance for common issues
• Environment variable fallback: ~/.env.jira is now optional when JIRA_URL and auth env vars are directly set (file takes priority if present)

Fixed

• jira-worklog.py: Auto-normalize --started timestamp format (handles ISO8601 without timezone)
• jira-worklog.py: Use correct atlassian-python-api method for adding worklogs
• jira-user.py: Resolve user lookup on Jira Server/DC with multi-fallback approach (direct username, REST API search, Cloud-compatible fallback)
• jira-issue.py: Add missing --json, --quiet, --full flags to get subcommand
• jira-issue.py: Fix --fields parameter to pass string instead of list to Jira API
• jira-issue.py: Add truncation notice with --full option for complete content retrieval

Improved

• SKILL.md: Enhanced description with explicit 11-point capability list
• Cross-references: Added references to jira-syntax skill for content formatting
• Workflow examples: Added common workflow patterns with prominent flag ordering warning

Documentation

• CLI flag ordering requirement documented in SKILL.md
• Cleaned up outdated documentation files

3.0.1 - 2025-11-25

BREAKING CHANGES

• jira-search.py: Replaced --output choice option with standard --json and --quiet flags
  • --output table → default (no flags)
  • --output json → --json
  • --output keys → --quiet

Added

• jira-validate.py: Added --json and --quiet options for consistent CLI interface
• jira-fields.py: Added --quiet option (outputs field IDs only)
• jira-link.py: Added --quiet option (outputs link type names only)

Fixed

• All 12 scripts now consistently support --help, --json, and --quiet as documented in SKILL.md

3.0.0 - 2025-11-25

BREAKING CHANGES

• Removed MCP server dependency: The mcp-atlassian Docker-based MCP server is no longer used
• New invocation pattern: All operations now use uv run scripts/... instead of MCP tool calls
• Skill renamed: jira-mcp → jira-communication

Added

• Script-based architecture: Lightweight Python scripts with PEP 723 inline dependencies
• Shared library (lib/): Common utilities for client initialization, config, and output formatting
• Core scripts (scripts/core/):
  • jira-validate.py - Environment validation with actionable error messages
  • jira-worklog.py - Time tracking (add, list)
  • jira-issue.py - Issue operations (get, update)
  • jira-search.py - JQL search queries
• Workflow scripts (scripts/workflow/):
  • jira-create.py - Issue creation with all common fields
  • jira-transition.py - Status transitions with comments
  • jira-comment.py - Comment operations
  • jira-sprint.py - Sprint operations (list, issues, current)
  • jira-board.py - Board operations (list, issues)
• Utility scripts (scripts/utility/):
  • jira-fields.py - Field search and listing
  • jira-user.py - User information
  • jira-link.py - Issue linking
• New features:
  • --dry-run flag for all write operations
  • --json, --quiet output format options
  • Actionable error messages with suggestions
  • Auto-detection of Jira Cloud vs Server/DC

Changed

• Dependencies: Now uses uv/uvx instead of Docker
• Context usage: Reduced from ~8,000-12,000 tokens to ~500 tokens
• Startup time: Reduced from 3-5s (Docker) to <1s

Removed

• mcp-atlassian MCP server configuration
• Docker dependency
• Confluence operations (separate skill if needed)
• Old jira-mcp skill (use git history for reference)

Migration

See skills/jira-communication/references/migration-guide.md for detailed migration instructions from v2.x.

2.0.1 - 2025-11-25

Fixed

• SKILL.md Frontmatter: Removed invalid fields (version, mcp_servers) that are not recognized by Claude Code skill loading
• Skill Triggering: Moved "when to use" information from SKILL.md body to description field for proper skill activation
• plugin.json Structure: Added missing skills array declaration with proper paths to both skills

Improved

• Token Efficiency: Reduced jira-mcp/SKILL.md from ~415 to ~129 lines (69% reduction)
• Token Efficiency: Reduced jira-syntax/SKILL.md from ~243 to ~83 lines (66% reduction)
• Progressive Disclosure: SKILL.md files now serve as lean entry points, directing to comprehensive reference files
• Navigation: Added Table of Contents to jql-reference.md and jira-syntax-quick-reference.md for easier navigation

Changed

• Description Field: Now includes comprehensive trigger patterns (10 triggers for jira-mcp, 8 for jira-syntax)
• SKILL.md Structure: Follows skill-creator best practices with concise body pointing to references
• Reference Files: Long reference files (>100 lines) now have TOCs for better discoverability

Documentation

• Updated CLAUDE.md to reflect leaner skill architecture
• Skills validated against skill-creator framework best practices

2.0.0 - 2024-11-07

⚠️ BREAKING CHANGES

Major architectural redesign: The unified jira skill has been split into two specialized skills within a single plugin:

• jira-mcp: MCP server communication and Jira API operations
• jira-syntax: Jira wiki markup syntax validation and templates

Migration Required: See MIGRATION.md for upgrade instructions.

Changed

• Plugin name: jira → jira-integration
• Skill structure: Single unified skill → Two specialized skills
• File organization: Templates, references, and scripts reorganized by skill
• Activation patterns: Skills now activate independently based on context

Added

• jira-mcp skill: Dedicated MCP communication and API operations
  • references/jql-reference.md: Comprehensive JQL syntax guide with examples
  • references/mcp-tools-guide.md: Complete MCP tool documentation
  • references/workflow-patterns.md: Common multi-step operation sequences
• jira-syntax skill: Dedicated syntax validation and templates
  • Same templates moved from unified skill
  • Same syntax reference and validation scripts
• MIGRATION.md: Complete migration guide from v1.x to v2.0.0
• Plugin-level configuration: Both skills declared in single plugin.json

Improved

• Separation of concerns: API operations vs syntax enforcement
• Offline capability: jira-syntax works without MCP server for validation
• Clearer activation: Skills activate based on specific context
• Better documentation: Dedicated references for each domain
• Easier maintenance: Update skills independently

Removed

• Old unified skills/jira/ directory (archived in archive/jira-unified/)

1.0.3 - 2024-11-07

Fixed

• Added Docker as explicit prerequisite in README.md to prevent installation errors
• Removed references to non-existent templates (Task Template, Comment Templates) from documentation
• Updated template section to accurately reflect available resources

Added

• CHANGELOG.md following Keep a Changelog format for better version tracking

1.0.2 - 2024-11-07

Fixed

• Moved MCP server configuration inline to avoid collisions when working on this project
• Fixed environment file path for Docker-based MCP server execution
• Corrected JIRA_ENV_FILE reference to use ${HOME}/.env.jira instead of relative path

Changed

• Updated plugin metadata for better marketplace integration
• Cleaned up CLAUDE.md documentation for clearer skill guidance

1.0.1 - 2024-11-06

Changed

• Updated plugin metadata and documentation
• Improved CLAUDE.md with clearer project architecture guidance

1.0.0 - 2024-11-06

Added

• Initial release of Jira Integration Skill
• Automatic MCP server configuration via bundled .mcp.json
• Docker-based mcp-atlassian server integration
• Comprehensive Jira wiki markup syntax enforcement
• Bug report template with proper Jira formatting
• Feature request template with acceptance criteria structure
• Complete Jira syntax quick reference documentation
• Syntax validation script for Jira wiki markup
• Support for all mcp-atlassian MCP tools:
  • Issue CRUD operations (create, read, update, search)
  • JQL query support for advanced searching
  • Project and sprint management
  • Worklog tracking and time logging
  • Comment management with proper formatting
  • Issue linking (blocks, relates to, duplicates, epic)
  • Attachment upload and download
  • Issue transitions and workflow management
  • Batch operations for bulk updates
• Comprehensive README with installation and usage examples
• Integration with Netresearch Claude Code Marketplace
• MIT License

Documentation

• Complete README.md with installation, usage, and troubleshooting
• SKILL.md activation patterns and workflow guidance
• CLAUDE.md project architecture and development guidelines
• Jira syntax quick reference with examples
• Template documentation for bug reports and feature requests

Release Notes

Version 1.0.2

This release focuses on improving the reliability of MCP server configuration by moving it inline with the skill. This prevents configuration conflicts and ensures the correct environment file path is used for Docker-based execution.

Version 1.0.0

First stable release providing comprehensive Jira integration through Claude Code. The skill enforces proper Jira wiki markup syntax across all operations, includes ready-to-use templates, and provides seamless Docker-based MCP server integration with zero manual configuration required.

Links

• Repository
• mcp-atlassian
• Claude Code Marketplace
• Jira Wiki Markup Reference