jira-pm

Required:

• JIRA_URL – Base URL of your Jira instance (e.g., https://yourcompany.atlassian.net)
• JIRA_API_TOKEN – API token for authentication (generate at Jira Account Settings → Security → API Tokens)
• JIRA_USER_EMAIL – Email address associated with the API token

Optional:

• JIRA_DEFAULT_PROJECT – Default project key for operations (e.g., PROJ)
• JIRA_API_VERSION – API version (default: 3)

<tool_categories>

Issues

Projects

Sprints

Comments

</tool_categories>

<usage_patterns>

Common Workflows

Issue Creation:

1. List projects to find correct project key
2. Get project info to understand issue types
3. Create issue with appropriate fields
4. Add comment if needed

Sprint Management:

1. Get active sprint for board
2. List sprint issues
3. Update issue status using transitions
4. Add comments for status updates

Issue Search:

1. Use JQL for targeted searches (e.g., project = PROJ AND status = "In Progress")
2. Retrieve issue details for specific issues
3. Update issues based on search results </usage_patterns>

<jql_examples>

JQL Query Examples

Common Queries:

# Issues assigned to current user
assignee = currentUser()

# Open issues in specific project
project = PROJ AND status != Done

# Issues created this week
created >= startOfWeek()

# High priority bugs
type = Bug AND priority = High

# Issues in current sprint
sprint in openSprints()

# Recently updated issues
updated >= -7d

# Overdue issues
duedate < now() AND status != Done

</jql_examples>

<agent_integration>

Primary Agent: pm (Product Manager)

• Use Case: Project backlog management, sprint planning, requirement tracking
• Common Operations: Create issues, update priorities, manage sprints

Secondary Agent: developer

• Use Case: Issue tracking during development, status updates
• Common Operations: Search assigned issues, transition issues, add comments

Supporting Agent: qa

• Use Case: Bug tracking, test case management
• Common Operations: Create bug reports, update test results, search defects </agent_integration>

<error_handling>

Common Error Scenarios

Authentication Errors:

• Missing or invalid API token
• Expired credentials
• Insufficient permissions

Rate Limiting:

• Too many API requests in short period
• Implement exponential backoff

Invalid Inputs:

• Non-existent project keys
• Invalid issue types
• Invalid transition IDs

Network Errors:

• Connection timeouts
• Unreachable Jira instance </error_handling>

<best_practices>

1. Use JQL Efficiently: Craft precise JQL queries to reduce result sets and API calls
2. Cache Metadata: Store project keys, issue types, and transitions locally
3. Verify Before Create: Always verify project and issue type before creating issues
4. Use Transitions: Respect workflow states when changing issue status
5. Batch Operations: Group related API calls when possible
6. Handle Errors Gracefully: Provide clear error messages and recovery suggestions
7. Respect Rate Limits: Implement backoff strategies for high-volume operations </best_practices>

Create Issue:

# Create a new story
create-issue --project PROJ --type Story --summary "Implement user authentication" --description "Add OAuth2 authentication flow"

Update Issue:

# Update issue priority
update-issue --key PROJ-123 --priority High

Transition Issue:

# Move issue to "In Progress"
transition --key PROJ-123 --status "In Progress"

Get Sprint Issues:

# List issues in active sprint
active-sprint --board-id 42
sprint-issues --sprint-id 123

Add Comment:

# Add progress update
add-comment --key PROJ-123 --comment "Completed authentication implementation, ready for review"

</code_example>

<progressive_disclosure>

Context Optimization

This skill uses progressive disclosure to minimize context usage:

1. Lazy Loading: Only load issue details when explicitly requested
2. Field Selection: Request only necessary fields from Jira API
3. Caching: Store frequently accessed metadata (projects, issue types)
4. Streaming: Not supported – all responses are complete payloads
5. Pagination: Automatically handle large result sets

Context Savings: 90%+ compared to loading full Jira MCP server </progressive_disclosure>

<api_reference>

Jira REST API Endpoints Used

• /rest/api/3/search – JQL search
• /rest/api/3/issue/{issueKey} – Get/update issue
• /rest/api/3/issue – Create issue
• /rest/api/3/issue/{issueKey}/transitions – Transition issue
• /rest/api/3/project – List projects
• /rest/api/3/project/{projectKey} – Get project details
• /rest/agile/1.0/board/{boardId}/sprint – Get sprints
• /rest/agile/1.0/sprint/{sprintId}/issue – Get sprint issues
• /rest/api/3/issue/{issueKey}/comment – Get/add comments

See Jira REST API Documentation for full reference. </api_reference>

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it’s not in memory, it didn’t happen.