| name | jira |
| description | Use when the user mentions Jira issues (e.g., "PROJ-123"), asks about tickets, wants to create/view/update issues, check sprint status, or manage their Jira workflow. Triggers on keywords like "jira", "issue", "ticket", "sprint", "backlog", or issue key patterns. |
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
