jira-config

name	jira-config
description	Read and validate the jira block in .claude/project.json for jira-pack: required keys, defaults, working-repo resolution. NOT for talking to Jira itself (that's jira-tasks / the Atlassian MCP tools) and NOT for Confluence.
version	0.1.0
owner	swarmery-core
docs	{"status":"reviewed","source_sha":"0b1d68abed0c","updated":"2026-08-06T00:00:00.000Z"}

Purpose

jira-pack runs with autonomy: auto — nobody is watching to answer a clarifying question. Anything the ticket text doesn't spell out has to come from .claude/project.json, and if it's missing the run must fail loudly with a fix-it message, never guess. This skill is that gate: it reads the jira block, validates it, resolves defaults, and resolves which repo the run operates against — before any other jira-pack skill or agent touches a ticket.

Source of truth

Read ${CLAUDE_PROJECT_DIR}/.claude/project.json, key jira, straight from the file. Never infer these values from a ticket, a prompt, or a prior run — the schema at overlays/_schema/project.schema.json (jira property) is the contract; this skill enforces it at runtime.

Validation

Required: jira.baseUrl, jira.projectKey, jira.qaStatus, jira.repro.test.

If any of these is missing (key absent, empty string, or repro present without test): stop immediately. Do not call Jira, do not fall back to a guess, do not proceed with a partial config. Report exactly which keys are missing and hand back a ready-to-paste JSON fragment for the consumer to drop into .claude/project.json, e.g.:

jira-config: missing required keys — jira.projectKey, jira.qaStatus

Paste this into .claude/project.json (fill in the placeholders):

  "jira": {
    "baseUrl": "<jira-base-url>",
    "projectKey": "<PROJECT-KEY>",
    "qaStatus": "QA",
    "repro": { "setup": "npm ci", "test": "npm test" },
    "budget": { "maxFiles": 5, "maxAttempts": 3 }
  }

Only list the keys that are actually missing — don't reprint the whole fragment as if nothing were configured when the config is partially there.

Working-repo resolution

Default: ${CLAUDE_PROJECT_DIR}. If the caller passes --repo <path>, use that path instead, provided it exists and is a git repository (git -C <path> rev-parse --is-inside-work-tree or equivalent) — otherwise stop and report the bad path, don't silently fall back to the default. The resolved root is printed in the skill's own report and is what gets threaded into the board card's prompt field downstream, so the executor agent operates against the same repo this skill validated.

Documented limitation, not a missed case: there is no "Jira component → repository" mapping in this iteration. One jira block resolves to exactly one working repo (default-or---repo); multi-repo routing by ticket component is out of scope until a later phase adds it.

Defaults

• budget.maxFiles = 5, budget.maxAttempts = 3 when budget (or either field) is absent — chosen to match plugins/core/agents/debugger.md's own stop conditions (~5 files, 3 failed attempts), so the orchestrator's budget never conflicts with the executor's internal limits.
• repro.setup is optional. Absent means the setup step is skipped — that is expected behavior, not a validation failure. repro.test has no default; its absence is a hard stop (see Validation above).

Placeholders / neutrality

Any example this skill prints uses only <jira-base-url> and <PROJECT-KEY> as placeholders. Never print a real site host, project key, or team name — plugins/** must stay at zero hits under scripts/scan-flavor.sh (docs/NEUTRALITY.md).

Related

• overlays/_schema/project.schema.json — the jira block's JSON Schema (source of the required-keys list above).
• overlays/example/project.json — a fully-populated neutral example of the block.
• plugins/core/skills/jira-tasks/SKILL.md — read-only Jira queries once a run is underway; this skill only resolves and validates config, it never calls the Atlassian MCP tools itself.
• plugins/core/agents/debugger.md — source of the budget defaults above.

How to use

What it does

This skill reads the jira block from your project's .claude/project.json, checks that everything a run needs is actually there, and works out which repository the run will operate against. Because jira-pack runs unattended, nothing can be guessed at runtime — so this gate either hands back a validated config or stops the run with a message telling you exactly which keys to add.

When to use it

• Before any other jira-pack skill or agent touches a ticket, so a run never starts on a half-configured project.
• When a ticket run failed with a config complaint and you want the precise list of missing keys plus a paste-ready fix.
• When you are setting up jira-pack in a new project and want to confirm the jira block is complete.
• When you need to know which repository a run will work in, including a --repo <path> override.

When not to use it

• To read or search tickets — use the jira-tasks skill, which handles read-only tracker queries.
• To verify that tracker access and credentials actually work — that is the jira-access-preflight skill.
• To classify a ticket as a defect or a change — that is the jira-triage skill.
• For Confluence pages of any kind; this skill only touches the local config file.

How to invoke

Skill(skill: "jira-pack:jira-config")

Call it first in a jira-pack run. It reads the config file itself, so you do not pass the values in.

Inputs

• --repo <path> — an alternative working repository root — optional; must exist and be a git repository, otherwise the run stops.
• .claude/project.json — the config file it reads, with a jira block holding baseUrl, projectKey, qaStatus, and repro.test as required keys — required.

What you get back

A short report naming the resolved working-repo root and the effective settings, including defaults it filled in (budget.maxFiles = 5, budget.maxAttempts = 3 when absent; a missing repro.setup simply skips the setup step). If a required key is missing, you instead get a hard stop listing only the keys that are actually absent, plus a JSON fragment with neutral placeholders to paste into your config. The resolved repo root is what downstream jira-pack steps operate against.

Worked example

Skill(skill: "jira-pack:jira-config")

→ jira-config: missing required keys — jira.projectKey, jira.qaStatus

  Paste this into .claude/project.json (fill in the placeholders):

    "jira": {
      "projectKey": "<PROJECT-KEY>",
      "qaStatus": "QA"
    }

You add the two keys, run it again, and it reports a valid config with the working repo resolved to your project root.

Related

• jira-access-preflight — run it right after this one to confirm the tracker itself is reachable.
• jira-triage — prefer it once config is valid and you need the ticket classified.
• jira-tasks — prefer it for read-only ticket queries during a run.