jira-claude-toolkit

Turn a Jira issue into a Spec-Kit technical specification, from inside Claude Code or from a plain shell.

Install it once, use it in every repository. The toolkit discovers each repository's own Spec-Kit conventions instead of imposing its own.

Jira  →  Jira Client  →  Normalized Issue Context  →  Claude Code
      →  Grill / Clarification  →  Decision  →  Spec-Kit  →  Technical Specification
                                      │
                    ┌─────────────────┼──────────────┬──────────────────┐
                    ▼                 ▼              ▼                  ▼
              CREATE_SPEC       UPDATE_SPEC       NO_OP        NEEDS_CLARIFICATION
                    └─────────────────┘                              / BLOCKED
                        └──► spec.md                                 (no spec)

Quick start

pipx install jira-claude-toolkit          # or: pip install jira-claude-toolkit

cd ~/code/your-project
jira-claude install --config-files        # writes skills + starter config
$EDITOR .jira-claude.yaml                 # base_url, project_key
cp .env.example .env && $EDITOR .env      # JIRA_EMAIL, JIRA_API_TOKEN
jira-claude doctor                        # verify everything

Then in Claude Code — find something to work on:

/jira-ticket --mine --status "In Progress"

and turn one of them into a specification:

/jira-speckit PROJ-25

That second command fetches the ticket, investigates your codebase, grills the requirements, decides whether a specification is actually needed, and — if it is — drives your repository's own Spec-Kit specify command. It produces a specification and nothing else; it never implements the feature.

The two are deliberately separate. Finding a ticket is not consent to specify it, so /jira-ticket ends at a key and never runs /jira-speckit for you.

Commands

jira-claude doctor            # every check: config, Jira, Spec-Kit, skills, secrets
jira-claude validate-env      # configuration only, no network
jira-claude connect           # authenticate and confirm project access
jira-claude ticket            # list issues in the configured project (bounded)
jira-claude ticket PROJ-25    # normalized issue context (Markdown or --json)
jira-claude grill PROJ-25     # clarification questions derived from the ticket
jira-claude decide PROJ-25    # CREATE_SPEC / UPDATE_SPEC / NO_OP / NEEDS_CLARIFICATION / BLOCKED
jira-claude smoke-test PROJ-25  # read-only checks against a REAL Jira site
jira-claude install           # write the Claude Code skills into a repository
jira-claude scan-secrets      # fail if a credential reached a committable file

stdout is data, stderr is diagnostics, exit codes are stable:

jira-claude ticket PROJ-25 --json | jq '.acceptance_criteria'

Claude Code commands

Status: 1.1.0. Verified against a mock Jira (892 tests), a CI matrix spanning Python 3.9–3.13 on Ubuntu and Windows, and a live Atlassian site over REST v2. See docs/testing.md and CHANGELOG.md for what live data did and did not exercise — including the checks a three-issue project could not.

Finding a ticket

/jira-ticket                              # bounded list, most recently updated first
/jira-ticket PROJ-25                      # one issue in detail
/jira-ticket --status "In Progress"
/jira-ticket --mine
/jira-ticket --priority High
/jira-ticket --type Bug
/jira-ticket --search "payment"
/jira-ticket --limit 25
/jira-ticket --jql 'status = "In Progress"'
/jira-ticket --mine --json                # machine-readable

Filters combine, so --mine --status "In Progress" --priority High narrows on all three.

Results are bounded, and the toolkit never invents a total. Jira's search endpoint returns issues, not a count of everything that matched — so the output distinguishes the two cases it can actually tell apart:

Total: 3 issues              # paging finished; this is every match

Showing: 25 issues           # the limit was reached first
Result set: bounded by --limit 25
More issues may exist.

Obtaining a true project-wide total would cost a second request nobody asked for, so Total: appears only when paging exhausted the result set. The status counts below the table describe the returned issues for the same reason, and say so.

Listing is cheap by design: one request per page, never one per issue, and it never asks Jira for descriptions or comments — so a 50-issue list does not drag 50 descriptions into the conversation.

/jira-speckit does not require /jira-connect to have been run. It validates the connection itself and points at /jira-connect only if something breaks. There is no connection-state file: every Jira call authenticates, so a cached "connected" flag could only ever produce a misleading error message.

A Jira ticket does not imply a specification

The workflow ends in an explicit, reportable decision — not in a document by default:

$ jira-claude decide PROJ-25
Jira Issue: PROJ-25
Repository Investigation: COMPLETE
Existing Specification: FOUND
Grill: RESOLVED

Decision: NO_OP

Reason:
Existing specification completely covers this Jira request.

jira-claude decide computes a mechanical proposal from files on disk and ticket fields — it searches the specs directory for a specification citing this Jira key. /jira-speckit then confirms or overrides it after reading the codebase, which is the one part of the pipeline that needs judgement.

Concluding NO_OP is a success. A pipeline that always emits a document emits duplicates.

Exit code 0 means a decision was computed, not that the answer was "yes". Branch on the outcome, never on the exit status:

outcome=$(jira-claude decide PROJ-25 --json | jq -r .outcome)
case "$outcome" in
  CREATE_SPEC|UPDATE_SPEC) run-spec-kit ;;
  NO_OP)                   echo "already specified — nothing to do" ;;
  NEEDS_CLARIFICATION)     echo "needs answers first" ;;
  BLOCKED)                 exit 1 ;;
esac

Failures that prevent a decision — invalid key (2), config (4), auth (6), not found (7), wrong project (8) — still use their own exit codes.

Configuration: two files, one rule each

.env                  credentials ONLY — JIRA_EMAIL, JIRA_API_TOKEN. Git-ignored.
.jira-claude.yaml     everything else — base URL, project key, limits. Committed.

Putting a credential in the YAML file is a hard error, not a warning: that file is meant to be committed, so accepting a token there would create the exact leak the split exists to prevent.

Precedence: process environment → .env → .jira-claude.yaml → defaults. The environment wins so CI needs no files on disk.

See docs/configuration.md.

How it stays repo-agnostic

The skills contain no Jira logic, no credentials, and no paths. Before doing anything, /jira-speckit runs:

jira-claude doctor --json --offline

and reads this repository's actual conventions out of the result — the specs directory, feature numbering (003-name vs 20260319-143022-name), and the real specify command (/speckit-specify or /speckit.specify). Nothing is assumed, so the same two files work in Engineering OS, Product Intelligence, TokenHelm and repositories that do not exist yet.

Override discovery per project in .jira-claude.yaml when a repository does something unusual.

Architecture

Layering is enforced by import direction, not convention:

So the Jira client is usable on its own:

from jira_claude.client import JiraClient
from jira_claude.issue import normalize
from jira_claude.secrets import Secret

client = JiraClient("https://acme.atlassian.net", "dev@acme.io", Secret(token))
issue = normalize(client.issue("PROJ-25"))
print(issue.acceptance_criteria)

…and the Claude Code integration is usable against any repository.

See docs/architecture.md.

Requirements

Python 3.9+. One runtime dependency: PyYAML. HTTP is stdlib urllib.

Tests

pip install -e ".[dev]"
pytest                       # 389 tests — mock only, no credentials, no network
pytest -m "not integration"  # unit tests only
pytest --cov=jira_claude     # coverage

Real-Jira tests are a separate layer and are deselected by default. They need JIRA_REAL_TEST=1 plus real credentials plus -m realjira; any gate closed means skipped, never failed. They are read-only.

jira-claude smoke-test PROJ-25   # the same checks, without pytest

See docs/testing.md.

Security

The API token is wrapped in a Secret that cannot be printed by accident — str(), repr(), f-strings and format() all yield ***, and pickling raises. It travels in an HTTP header, never in a URL, a process argument, or a file. Redirects are refused so it is never forwarded to another host.

jira-claude scan-secrets     # pre-commit hook material

See docs/security.md.

Documentation

• Installation — pip, pipx, local, skill install
• Configuration — project config and secrets
• Architecture — the seven components and the layering
• Testing — mock testing vs real-Jira smoke testing
• Security — credential containment
• End-to-end example — a real run, verbatim
• Changelog — release history and the path to 1.0.0

Licence

MIT.