transition-jira-issue

Invocation: User-invoked only (model invocation disabled)
Argument hint: ISSUE-KEY (STATE-NAME | --transition-id ID) [--resolution NAME] [--comment TEXT | --comment-file PATH] [--no-notify] [--quiet]
Allowed tools: Bash, Read, Write
Source: skills/integrations/jira/transition-jira-issue/SKILL.md

Transition Jira Issue

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-context.sh !${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-context.sh transition-jira-issue

Transition a Jira issue through its workflow by state name. Work through the steps below in order. This skill never auto-invokes — it only runs when the user explicitly types /transition-jira-issue.

Step 1: Parse flags

Required positional: KEY (issue key, e.g. ENG-42).

State target — exactly one required, mutually exclusive:

• STATE_NAME (second positional) — target workflow state name (case-insensitive match against available transitions)
• --transition-id ID — numeric transition ID; bypasses the state name lookup GET entirely

Optional flags:

• --resolution NAME — set resolution field during transition
• --comment TEXT — inline comment body (Markdown → ADF)
• --comment-file PATH — comment body from file (Markdown → ADF)
• --no-notify — suppress watcher notifications (?notifyUsers=false)
• --quiet — suppress INFO stderr lines

Step 2: Trust-boundary enforcement (only when --comment or --comment-file is present)

If the user supplied --comment or --comment-file, verify that the body content comes ONLY from text the user typed in this turn or a file path the user explicitly named in this turn.

Do NOT use:

• A previously-fetched issue description or comment
• A web fetch result
• A prior assistant message quoting external sources

If the user’s phrasing implies “copy from above” or “use that text”, ask them to paste or confirm the literal text before continuing.

(Skip this step entirely if neither --comment nor --comment-file is present.)

Step 3: Generate the describe preview

Invoke the flow script with --describe:

${CLAUDE_PLUGIN_ROOT}/skills/integrations/jira/scripts/jira-transition-flow.sh \
  --describe <KEY> [STATE_NAME] [--transition-id ID] \
  [--resolution NAME] [--comment TEXT | --comment-file PATH] [--no-notify]

Important: when STATE_NAME is given (without --transition-id), --describe makes a read-only GET to Jira to resolve the transition eagerly — auth errors (exit 11/22) or network errors (exit 21) can surface here, not only during the POST. When --transition-id is given, --describe exits immediately without any network call.

Step 4: Handle the describe result

• Exit 0: proceed to Step 5.

• Exit 122 (E_TRANSITION_NOT_FOUND): tell the user:

  No transition to '<STATE_NAME>' is available from the current state. Check the issue’s workflow in Jira.

  Stop — do not proceed to confirm.

• Exit 123 (E_TRANSITION_AMBIGUOUS): parse the JSON array from stdout (list of {id, name, to.name} objects). If stdout is not parseable as a JSON array, surface it verbatim and ask the user to re-invoke with --transition-id directly. Otherwise, present a table:

  ID	Transition name	Target state
  …	…	…

  Ask: “Multiple transitions lead to '<STATE_NAME>'. Which would you like to use? Reply with the transition ID (e.g. 41) to proceed, or cancel to abort.”

  • Validate the reply as digits only (^[0-9]+$). Non-numeric replies count as a failed attempt.
  • After 3 failed disambiguation attempts, abort: “Aborted — could not resolve transition unambiguously. No Jira write was made.”
  • On a valid numeric ID: re-invoke --describe with --transition-id \<chosen_id> (omit STATE_NAME — passing both triggers exit 124). Loop back to Step 3.

• Other non-zero: tell the user “Preview failed — no API call was made.” Stop.

Step 5: Render the preview

Show under this heading:

Proposed Jira write — review before sending

Content:

• Endpoint: POST /rest/api/3/issue/<KEY>/transitions
• Transition: moving <KEY> → "<STATE_NAME>" via transition <ID>.
  • If state in the describe output is null (only --transition-id was supplied with no STATE_NAME): render as “via transition <ID>” without mentioning a target state name.
• Resolution: <NAME> (only if --resolution was given)
• Comment preview (truncate at 500 chars, append [… truncated]) if --comment/--comment-file given
• ⚠️ “Notifications suppressed” if --no-notify

Step 6: Confirm

Ask the user (exact canonical phrase):

Send this to Jira? Reply y to confirm, n to revise, anything else to abort.

Interpret the reply:

• Clear yes (y / yes): proceed to Step 7.
• Clear no (n / no or an explicit revision request): ask “What would you like to change?” Re-apply the Step 2 trust-boundary check if --comment content is revised. Rebuild the preview from Step 3 with the updated parameters. Allow up to 3 revision cycles; after the third rejection abort with “Aborted — no Jira write was made.”
• Ambiguous or off-topic: abort immediately with “Aborted — no Jira write was made.”

Step 7: Send

Invoke without --describe:

${CLAUDE_PLUGIN_ROOT}/skills/integrations/jira/scripts/jira-transition-flow.sh \
  <KEY> [STATE_NAME] [--transition-id ID] \
  [--resolution NAME] [--comment TEXT | --comment-file PATH] \
  [--no-notify] [--quiet]

Step 8: Render the response

• 204 with state name known (state in describe output is not null): ✓ **<KEY>** transitioned to "<STATE_NAME>".
• 204 with only --transition-id (state was null): ✓ **<KEY>** transition ID <ID> applied.
• After a disambiguation flow: the original STATE_NAME from the user’s invocation is available in the skill’s context even though the re-invoke used --transition-id (which returns state: null). Prefer: ✓ **<KEY>** transitioned to "<ORIGINAL_STATE_NAME>" (via transition ID <ID>).

Step 9: Exit-code handling

Code	Name	User-facing message
120	E_TRANSITION_NO_KEY	No issue key supplied. Pass the key as the first positional argument.
121	E_TRANSITION_NO_STATE	No target state name or --transition-id supplied. One is required.
122	E_TRANSITION_NOT_FOUND	No transition leads to that state from the current state. Check the issue’s workflow in Jira.
123	E_TRANSITION_AMBIGUOUS	Multiple transitions share that state name. Use the disambiguation table to pick a transition ID.
124	E_TRANSITION_BAD_FLAG	Unrecognised flag or conflicting arguments. See the usage banner.
125	E_TRANSITION_NO_BODY	--comment-file path is invalid, missing, or not readable.
126	E_TRANSITION_BAD_RESOLUTION	--resolution value is empty or whitespace-only.
11, 12, 22	auth errors	Check credentials with /init-jira. Note: exit 12 (HTTP 403) specifically means you do not have the TRANSITION_ISSUES permission on this project — check your Jira role with your project admin.
13	not found	Issue not found or you do not have permission to see it.
19	rate-limited	Wait briefly and retry.
20	server error	Jira returned a server error; check the Jira status page.
21	connection	Connection failed; check network and Jira site config.
34	E_REQ_BAD_REQUEST	HTTP 400 — Jira rejected the transition request. See the error body above.

Examples

Example 1 — simple state transition User: /transition-jira-issue ENG-42 "In Progress" Skill resolves transition via GET (--describe), shows preview (POST /rest/api/3/issue/ENG-42/transitions, moving to “In Progress” via transition 21), waits for y, posts transition, confirms ✓ **ENG-42** transitioned to "In Progress".

Example 2 — transition with resolution User: /transition-jira-issue ENG-42 "Done" --resolution "Fixed" Skill resolves transition via GET, shows preview including resolution “Fixed”, waits for y, posts, confirms ✓ **ENG-42** transitioned to "Done".

Example 3 — disambiguation flow User: /transition-jira-issue ENG-42 "In Review" Skill gets ambiguous result (two transitions both lead to “In Review”), shows table with IDs 41 and 42, asks user to pick. User replies 41. Skill re-invokes --describe --transition-id 41, shows preview, waits for y, posts, confirms ✓ **ENG-42** transitioned to "In Review" (via transition ID 41).

!${CLAUDE_PLUGIN_ROOT}/scripts/config-read-skill-instructions.sh transition-jira-issue