Jira

Natural language interaction with Jira. Supports multiple backends.

Backend Detection

Run this check first to determine which backend to use:

1. Check if jira CLI is available: → Run: which jira → If found: USE CLI BACKEND

2. If no CLI, check for Atlassian MCP: → Look for mcp__atlassian__* tools → If available: USE MCP BACKEND

3. If neither available: → GUIDE USER TO SETUP

Backend When to Use Reference

CLI jira command available references/commands.md

MCP Atlassian MCP tools available references/mcp.md

None Neither available Guide to install CLI

Quick Reference (CLI)

Skip this section if using MCP backend.

Intent Command

View issue jira issue view ISSUE-KEY

List my issues jira issue list -a$(jira me)

My in-progress jira issue list -a$(jira me) -s"In Progress"

Create issue jira issue create -tType -s"Summary" -b"Description"

Move/transition jira issue move ISSUE-KEY "State"

Assign to me jira issue assign ISSUE-KEY $(jira me)

Unassign jira issue assign ISSUE-KEY x

Add comment jira issue comment add ISSUE-KEY -b"Comment text"

Open in browser jira open ISSUE-KEY

Current sprint jira sprint list --state active

Who am I jira me

Quick Reference (MCP)

Skip this section if using CLI backend.

Intent MCP Tool

Search issues mcp__atlassian__searchJiraIssuesUsingJql

View issue mcp__atlassian__getJiraIssue

Create issue mcp__atlassian__createJiraIssue

Update issue mcp__atlassian__editJiraIssue

Get transitions mcp__atlassian__getTransitionsForJiraIssue

Transition mcp__atlassian__transitionJiraIssue

Add comment mcp__atlassian__addCommentToJiraIssue

User lookup mcp__atlassian__lookupJiraAccountId

List projects mcp__atlassian__getVisibleJiraProjects

See references/mcp.md for full MCP patterns.

Triggers

• "create a jira ticket"

• "show me PROJ-123"

• "list my tickets"

• "move ticket to done"

• "what's in the current sprint"

Issue Key Detection

Issue keys follow the pattern: [A-Z]+-[0-9]+ (e.g., PROJ-123, ABC-1).

When a user mentions an issue key in conversation:

• CLI: jira issue view KEY or jira open KEY

• MCP: mcp__atlassian__jira_get_issue with the key

Workflow

Creating tickets:

• Research context if user references code/tickets/PRs

• Draft ticket content

• Review with user

• Create using appropriate backend

Updating tickets:

• Fetch issue details first

• Check status (careful with in-progress tickets)

• Show current vs proposed changes

• Get approval before updating

• Add comment explaining changes

Before Any Operation

Ask yourself:

What's the current state? — Always fetch the issue first. Don't assume status, assignee, or fields are what user thinks they are.

Who else is affected? — Check watchers, linked issues, parent epics. A "simple edit" might notify 10 people.

Is this reversible? — Transitions may have one-way gates. Some workflows require intermediate states. Description edits have no undo.

Do I have the right identifiers? — Issue keys, transition IDs, account IDs. Display names don't work for assignment (MCP).

NEVER

NEVER transition without fetching current status — Workflows may require intermediate states. "To Do" → "Done" might fail silently if "In Progress" is required first.

NEVER assign using display name (MCP) — Only account IDs work. Always call lookupJiraAccountId first, or assignment silently fails.

NEVER edit description without showing original — Jira has no undo. User must see what they're replacing.

NEVER use --no-input without all required fields (CLI) — Fails silently with cryptic errors. Check project's required fields first.

NEVER assume transition names are universal — "Done", "Closed", "Complete" vary by project. Always get available transitions first.

NEVER bulk-modify without explicit approval — Each ticket change notifies watchers. 10 edits = 10 notification storms.

Safety

• Always show the command/tool call before running it

• Always get approval before modifying tickets

• Preserve original information when editing

• Verify updates after applying

• Always surface authentication issues clearly so the user can resolve them

No Backend Available

If neither CLI nor MCP is available, guide the user:

To use Jira, you need one of:

1. jira CLI (recommended): https://github.com/ankitpokhrel/jira-cli

   Install: brew install ankitpokhrel/jira-cli/jira-cli Setup: jira init

2. Atlassian MCP: Configure in your MCP settings with Atlassian credentials.

Deep Dive

LOAD reference when:

• Creating issues with complex fields or multi-line content

• Building JQL queries beyond simple filters

• Troubleshooting errors or authentication issues

• Working with transitions, linking, or sprints

Do NOT load reference for:

• Simple view/list operations (Quick Reference above is sufficient)

• Basic status checks (jira issue view KEY )

• Opening issues in browser

Task Load Reference?

View single issue No

List my tickets No

Create with description Yes — CLI needs /tmp pattern

Transition issue Yes — need transition ID workflow

JQL search Yes — for complex queries

Link issues Yes — MCP limitation, need script

References:

• CLI patterns: references/commands.md

• MCP patterns: references/mcp.md