Jira

Project root contains:

• ~/.claude/.env - API credentials (JIRA_API_TOKEN, EMAIL)
• output/ - Generated reports directory

Quick Start

Using JiraHelper (Recommended)

import sys
sys.path.insert(0, '.claude/skills/jira/scripts')

from jira_helper import JiraHelper

helper = JiraHelper()
helper.connect()

# Search for tickets
tickets = helper.search_tickets(project="MYPROJECT", status="Open")

# Get ticket details
ticket = helper.get_ticket("PROJ-123")

# Create a new ticket
ticket = helper.create_ticket(
    project="MYPROJECT",
    summary="Implement new feature",
    description="Detailed description of the feature...",
    issue_type="Story",
    priority="High",
    components=["Backend"],
    labels=["feature", "q1"]
)

# Update ticket status
helper.transition_ticket(ticket_key="PROJ-123", status="In Progress")

# Add a comment
helper.add_comment(ticket_key="PROJ-123", comment="Started working on this")

# Link tickets
helper.link_tickets("PROJ-123", "PROJ-456", link_type="relates to")

# Get ticket metrics
metrics = helper.get_metrics(project="MYPROJECT")

Using JiraClient Directly

import sys
sys.path.insert(0, '.claude/skills/jira/scripts')

from jira_client import JiraClient

client = JiraClient()
client.authenticate()

# Search with JQL
issues = client.search_issues('project = MYPROJECT AND status = Open')

# Get single issue
issue = client.get_issue("PROJ-123")

# Create issue
new_issue = client.create_issue({
    "project": {"key": "MYPROJECT"},
    "summary": "New feature request",
    "issuetype": {"name": "Story"},
    "priority": {"name": "High"},
    "description": "Full description here..."
})

# Update issue
client.update_issue("PROJ-123", {"description": "Updated description"})

# Add comment
client.add_comment("PROJ-123", "Investigation complete")

# Transition issue
client.transition_issue("PROJ-123", "In Progress")

# Get transitions
transitions = client.get_transitions("PROJ-123")

Available Operations

JiraHelper Methods

JiraClient Methods

JQL Query Examples

# All tickets in a project
'project = MYPROJECT'

# Open tickets
'project = MYPROJECT AND status in (Open, "In Progress", "To Do")'

# High priority tickets
'project = MYPROJECT AND priority in (High, Critical)'

# Tickets created in last 30 days
'project = MYPROJECT AND created >= -30d'

# Tickets assigned to current user
'project = MYPROJECT AND assignee = currentUser()'

# Tickets with specific label
'project = MYPROJECT AND labels = backend'

# Recently updated tickets
'project = MYPROJECT AND updated >= -7d ORDER BY updated DESC'

# Unassigned tickets
'project = MYPROJECT AND assignee is EMPTY'

# Tickets by issue type
'project = MYPROJECT AND issuetype = Bug'

# Tickets in specific sprint
'project = MYPROJECT AND sprint = "Sprint 5"'

# Overdue tickets
'project = MYPROJECT AND duedate < now() AND status != Done'

Common Tasks

1. Find All Open Tickets

open_tickets = helper.get_open_tickets(project="MYPROJECT")
for ticket in open_tickets:
    print(f"{ticket['key']}: {ticket['summary']} - {ticket['status']}")

2. Create a Bug Ticket

ticket = helper.create_ticket(
    project="MYPROJECT",
    summary="Login button not working on mobile",
    description="""
    ## Steps to Reproduce
    1. Open app on mobile device
    2. Navigate to login page
    3. Tap login button

    ## Expected Behavior
    User should be logged in

    ## Actual Behavior
    Nothing happens when tapping the button
    """,
    issue_type="Bug",
    priority="High",
    components=["Mobile", "Authentication"],
    labels=["bug", "mobile", "urgent"]
)
print(f"Created: {ticket['key']}")

3. Track Progress

# Get ticket
ticket = helper.get_ticket("PROJ-123")
print(f"Status: {ticket['status']}")
print(f"Assignee: {ticket['assignee']}")

# Update with fix version
helper.update_ticket("PROJ-123", {
    "fixVersions": [{"name": "2.0.1"}]
})

# Transition to done
helper.transition_ticket("PROJ-123", "Done")
helper.add_comment("PROJ-123", "Fixed in release 2.0.1")

4. Generate Metrics Report

metrics = helper.get_metrics(project="MYPROJECT")
print(f"Total Tickets: {metrics['total']}")
print(f"Open: {metrics['by_status'].get('Open', 0)}")
print(f"High Priority: {metrics['by_priority'].get('High', 0)}")
print(f"Average Age: {metrics['avg_age_days']:.1f} days")

5. Link Related Tickets

# Link duplicate tickets
helper.link_tickets("PROJ-123", "PROJ-456", link_type="duplicates")

# Link related issues
helper.link_tickets("PROJ-123", "PROJ-789", link_type="relates to")

# Link blocker
helper.link_tickets("PROJ-123", "PROJ-100", link_type="blocks")

Error Handling

Common errors and solutions:

Running Scripts

# Run the helper example
python .claude/skills/jira/scripts/jira_helper.py

# Run client directly
python .claude/skills/jira/scripts/jira_client.py --search "feature"

Configuration

The client reads settings from environment:

• JIRA_API_TOKEN - API token (required)
• EMAIL - User email for Basic auth (required for Atlassian Cloud)
• JIRA_BASE_URL - Jira instance URL (default: https://hpe.atlassian.net)

API Limits

• Maximum 100 results per search (paginate for more)
• Rate limits apply per Jira instance configuration
• Bulk operations should be batched