Jira Builders

Jira Ticket Management

Use jira-tool CLI for all Jira operations.

Core Commands

# Get ticket
jira-tool get WPCW-370

# Search
jira-tool search 'project=WPCW AND status="To Do"'

# List epics
jira-tool epics --project WPCW

# Create epic
jira-tool create --project WPCW --type Epic --summary "Title"

# Create story under epic
jira-tool create --project WPCW --type Story --summary "Title" --parent WPCW-370

# Create subtask
jira-tool create --project WPCW --type Sub-task --summary "Title" --parent WPCW-371

# Export for analysis
jira-tool export --project WPCW --all --format jsonl -o data.jsonl

Rich Descriptions

Use heredoc for multi-line descriptions:

jira-tool create --project WPCW --type Epic \
  --summary "User Authentication" \
  --description "$(cat <<'EOF'
Implement OAuth2 authentication with session management.

**Problem Statement:**
Users cannot securely log in.

**Acceptance Criteria:**
- User can log in with email/password
- Session persists across refresh
- Logout invalidates sessions
EOF
)"

Batch Operations

Shell scripts with jira-tool:

#!/bin/bash
EPIC=$(jira-tool create --project WPCW --type Epic \
  --summary "Parent Epic" --format json | jq -r '.key')

for task in "Task 1" "Task 2" "Task 3"; do
  jira-tool create --project WPCW --type Story \
    --summary "$task" --parent "$EPIC"
done

Data Processing

Export and process with shell tools:

# Export tickets
jira-tool export --project WPCW --all --format jsonl -o tickets.jsonl

# Process with jq
jq -r 'select(.fields.status.name == "To Do") | .key' tickets.jsonl

When to Use What

• Single operation: jira-tool directly
• Batch operations: Shell scripts with jira-tool in loops
• Complex workflows: Invoke jira-ticket-manager agent
• Data analysis: Export + process with jq/awk

Requirements

• jira-tool CLI installed (check with jira-tool --version)
• Environment: JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN

Critical Anti-Patterns to Avoid

DO NOT:

1. Import jira_tool Python module - it's internal/private

   # WRONG - This will fail
   from jira_tool import JiraClient
   

2. Use curl for Jira API unless jira-tool doesn't support the operation

   # WRONG - Fragile, error-prone
   curl -u "$JIRA_USERNAME:$JIRA_API_TOKEN" "$JIRA_BASE_URL/rest/api/3/search"
   

3. Create multiple scripts for same purpose (violates DRY principle)

   # WRONG - Multiple scripts for slight variations
   pull_tickets_basic.py, pull_tickets_filtered.py, pull_tickets_csv.py
   

DO:

1. Use jira-tool CLI for all operations

   # RIGHT - Use the CLI
   jira-tool search 'project=WPCW'
   

2. Use subprocess if you need programmatic access

   # RIGHT - Call CLI from Python
   import subprocess
   result = subprocess.run(['jira-tool', 'get', 'PROJ-123'],
                          capture_output=True, text=True)
   

3. Use command-line flags for variations

   # RIGHT - One script with options
   jira-tool export --format csv --filter status=Open -o file.csv
   

Supporting References

• Quick Reference: ~/.claude/skills/jira-builders/references/QUICK_REFERENCE.md - Common CLI patterns and examples
• Tool Selection: ~/.claude/skills/jira-builders/references/TOOL_SELECTION.md - When to use CLI vs agent vs curl