Initial commit

skills/jira-cli/references/commands.md

@@ -0,0 +1,464 @@
+# Jira CLI - Comprehensive Command Reference
+
+This file contains detailed command syntax, options, and examples for all jira-cli operations.
+
+## Issue Management
+
+### Listing Issues
+
+Use powerful filters to find exactly what you need:
+
+```bash
+# Basic listing
+jira issue list                          # Recent issues
+jira issue list "Feature Request"        # Search by specific text
+jira issue list --created -7d            # Last 7 days
+jira issue list -s"To Do"                # Specific status
+jira issue list -yHigh                   # High priority
+
+# Personal queries
+jira issue list -a$(jira me)             # Assigned to me
+jira issue list -r$(jira me)             # Reported by me
+jira issue list -w                       # Issues I'm watching
+
+# Filtering by fields
+jira issue list -lbackend                # With label
+jira issue list -CBackend                # With component
+jira issue list -tBug                    # Bug type
+jira issue list -R"Won't do"             # With resolution
+
+# Combined filters (high priority, In Progress, created this month, with labels)
+jira issue list -yHigh -s"In Progress" --created month -lbackend -l"high-prio"
+
+# Time-based queries
+jira issue list --created -1h            # Created in last hour
+jira issue list --updated -30m           # Updated in last 30 minutes
+jira issue list --created week           # Created this week
+jira issue list --created month          # Created this month
+jira issue list --created-before -24w    # Created before 24 weeks ago
+
+# Advanced queries
+jira issue list -a"User A" -r"User B"    # Assigned to A, reported by B
+jira issue list -ax                      # Unassigned issues
+jira issue list -a~x                     # Assigned to anyone
+jira issue list -s~Done                  # Status NOT done (~ is NOT)
+jira issue list -s~Done --created-before -24w -a~x  # Complex NOT query
+
+# Special queries
+jira issue list --history                # Recently viewed by you
+jira issue list -r$(jira me) --reverse  # First issue you ever reported
+jira issue list -a$(jira me) -tBug -sDone -rFixed --reverse  # First bug you fixed
+
+# Project-specific
+jira issue list -pXYZ                    # In project XYZ
+jira issue list -w -pXYZ                 # Watching in project XYZ
+
+# Sorting and ordering
+jira issue list --order-by rank --reverse     # By rank (same as UI)
+jira issue list --order-by created           # By creation date
+jira issue list --order-by updated           # By update date
+
+# Output formats
+jira issue list --plain                  # Plain text
+jira issue list --csv                    # CSV format
+jira issue list --raw                    # Raw JSON
+jira issue list --columns key,summary,status,assignee  # Custom columns
+jira issue list --plain --no-headers     # No headers (for parsing)
+
+# Raw JQL
+jira issue list -q "summary ~ cli"       # Execute JQL in project context
+```
+
+### Creating Issues
+
+```bash
+# Interactive mode
+jira issue create
+
+# Non-interactive with all parameters
+jira issue create -tBug -s"Bug title" -yHigh -lbug -lurgent -b"Description" --no-input
+
+# Create with specific fields
+jira issue create -tStory -s"Story title" -yMedium -lfeature
+jira issue create -tTask -s"Task" -a"John Doe"  -CBackend
+jira issue create -tBug -s"Critical bug" -yHighest --fix-version v2.0
+
+# Attach to epic during creation
+jira issue create -tStory -s"Story title" -PEPIC-42
+
+# Using templates for description
+jira issue create --template /path/to/template.md
+jira issue create --template -                    # From stdin
+
+# Pipe description from stdin
+echo "Description from pipeline" | jira issue create -s"Summary" -tTask
+
+# With custom fields
+jira issue create --custom field1=value1 --custom field2=value2
+```
+
+### Editing Issues
+
+```bash
+# Interactive edit
+jira issue edit ISSUE-1
+
+# Update specific fields
+jira issue edit ISSUE-1 -s"New summary"
+jira issue edit ISSUE-1 -yHigh
+jira issue edit ISSUE-1 -b"New description"
+
+# Update multiple fields at once
+jira issue edit ISSUE-1 -s"New summary" -yHigh -lurgent --no-input
+
+# Add and remove labels/components
+jira issue edit ISSUE-1 --label new-label
+jira issue edit ISSUE-1 --label -old-label --label new-label
+jira issue edit ISSUE-1 --component -FE --component BE
+
+# Update fix version
+jira issue edit ISSUE-1 --fix-version v2.0
+jira issue edit ISSUE-1 --fix-version -v1.0 --fix-version v2.0
+```
+
+### Assigning Issues
+
+```bash
+# Interactive assign
+jira issue assign
+
+# Assign to specific user
+jira issue assign ISSUE-1 "Jon Doe"
+
+# Assign to self
+jira issue assign ISSUE-1 $(jira me)
+
+# Assign based on keyword (prompts if multiple matches)
+jira issue assign ISSUE-1 john
+
+# Assign to default assignee
+jira issue assign ISSUE-1 default
+
+# Unassign
+jira issue assign ISSUE-1 x
+```
+
+### Moving/Transitioning Issues
+
+```bash
+# Interactive transition
+jira issue move
+
+# Move to specific status
+jira issue move ISSUE-1 "In Progress"
+jira issue move ISSUE-1 Done
+
+# Move with comment
+jira issue move ISSUE-1 "In Progress" --comment "Started working on it"
+
+# Set resolution and assignee while moving
+jira issue move ISSUE-1 Done -RFixed
+jira issue move ISSUE-1 Done -RFixed -a$(jira me)
+```
+
+### Viewing Issues
+
+```bash
+# View issue in terminal
+jira issue view ISSUE-1
+
+# View with recent comments
+jira issue view ISSUE-1 --comments 5
+jira issue view ISSUE-1 --comments 10
+```
+
+### Linking Issues
+
+```bash
+# Interactive linking
+jira issue link
+
+# Link with relationship type
+jira issue link ISSUE-1 ISSUE-2 Blocks
+jira issue link ISSUE-1 ISSUE-2 "is blocked by"
+jira issue link ISSUE-1 ISSUE-2 Duplicates
+jira issue link ISSUE-1 ISSUE-2 Relates
+
+# Add remote web link
+jira issue link remote ISSUE-1 https://example.com "Example text"
+jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
+
+# Unlink issues
+jira issue unlink ISSUE-1 ISSUE-2
+```
+
+### Cloning Issues
+
+```bash
+# Clone an issue
+jira issue clone ISSUE-1
+
+# Clone with modifications
+jira issue clone ISSUE-1 -s"Modified summary"
+jira issue clone ISSUE-1 -s"New title" -yHigh -a$(jira me)
+
+# Clone and replace text in summary/description
+jira issue clone ISSUE-1 -H"old text:new text"
+jira issue clone ISSUE-1 -H"2024:2025"
+```
+
+### Deleting Issues
+
+```bash
+# Interactive delete
+jira issue delete
+
+# Delete specific issue
+jira issue delete ISSUE-1
+
+# Delete with all subtasks
+jira issue delete ISSUE-1 --cascade
+```
+
+### Comments
+
+```bash
+# Add comment interactively
+jira issue comment add
+
+# Add comment with text
+jira issue comment add ISSUE-1 "My comment text"
+
+# Add internal comment (visible only to team)
+jira issue comment add ISSUE-1 "Internal note" --internal
+
+# Add comment from template
+jira issue comment add ISSUE-1 --template /path/to/comment.md
+jira issue comment add ISSUE-1 --template -
+
+# Pipe comment from stdin
+echo "Comment from pipeline" | jira issue comment add ISSUE-1
+```
+
+### Worklog (Time Tracking)
+
+```bash
+# Add worklog interactively
+jira issue worklog add
+
+# Add worklog with time
+jira issue worklog add ISSUE-1 "2h 30m" --no-input
+jira issue worklog add ISSUE-1 "1d" --no-input
+jira issue worklog add ISSUE-1 "30m" --no-input
+
+# Add worklog with comment
+jira issue worklog add ISSUE-1 "2h" --comment "Implementation work" --no-input
+jira issue worklog add ISSUE-1 "1h 15m" --comment "Code review" --no-input
+```
+
+## Epic Management
+
+### Listing Epics
+
+```bash
+# List all epics (explorer view)
+jira epic list
+
+# List epics (table view)
+jira epic list --table
+
+# List epics with filters (same filters as issue list)
+jira epic list -r$(jira me)              # Reported by me
+jira epic list -sOpen                     # Open epics
+jira epic list -yHigh                     # High priority
+jira epic list -r$(jira me) -sOpen -yHigh  # Combined filters
+
+# List issues in an epic
+jira epic list EPIC-1
+
+# List epic issues with filters
+jira epic list EPIC-1 -ax                # Unassigned issues in epic
+jira epic list EPIC-1 -yHigh             # High priority issues in epic
+jira epic list EPIC-1 -a$(jira me)      # My issues in epic
+
+# Order epic issues by rank
+jira epic list EPIC-1 --order-by rank --reverse
+```
+
+### Creating Epics
+
+```bash
+# Interactive
+jira epic create
+
+# With parameters
+jira epic create -n"Epic name" -s"Epic summary"
+jira epic create -n"Q1 Features" -s"Q1 Feature Development" -yHigh -lfeature -b"Epic description"
+```
+
+### Managing Epic Issues
+
+```bash
+# Add issues to epic (interactive)
+jira epic add
+
+# Add issues to epic (up to 50 at once)
+jira epic add EPIC-1 ISSUE-1 ISSUE-2 ISSUE-3
+
+# Remove issues from epic (interactive)
+jira epic remove
+
+# Remove issues from epic (up to 50 at once)
+jira epic remove ISSUE-1 ISSUE-2 ISSUE-3
+```
+
+## Sprint Management
+
+### Listing Sprints
+
+```bash
+# List all sprints (explorer view)
+jira sprint list
+
+# List sprints (table view)
+jira sprint list --table
+
+# Current active sprint
+jira sprint list --current
+
+# Current sprint with filters
+jira sprint list --current -a$(jira me)
+jira sprint list --current -yHigh
+jira sprint list --current -a$(jira me) -yHigh -s"In Progress"
+
+# Previous sprint
+jira sprint list --prev
+
+# Next planned sprint
+jira sprint list --next
+
+# Filter by sprint state
+jira sprint list --state active
+jira sprint list --state future
+jira sprint list --state future,active
+jira sprint list --state closed
+
+# Specific sprint (use ID from sprint list)
+jira sprint list SPRINT_ID
+jira sprint list SPRINT_ID -yHigh
+jira sprint list SPRINT_ID -a$(jira me)
+jira sprint list SPRINT_ID -yHigh -a$(jira me) -s"In Progress"
+
+# Order sprint issues by rank
+jira sprint list SPRINT_ID --order-by rank --reverse
+```
+
+### Adding Issues to Sprint
+
+```bash
+# Add issues interactively
+jira sprint add
+
+# Add multiple issues (up to 50 at once)
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2 ISSUE-3
+```
+
+## Release Management
+
+Interact with releases (project versions). Ensure the [feature is enabled](https://support.atlassian.com/jira-software-cloud/docs/enable-releases-and-versions/) on your instance.
+
+```bash
+# List releases for default project
+jira release list
+
+# List releases for specific project by ID
+jira release list --project 1000
+
+# List releases for specific project by key
+jira release list --project MYPROJ
+```
+
+## Other Commands
+
+### Project and Board Navigation
+
+```bash
+# Open project in browser
+jira open
+
+# Open specific issue in browser
+jira open ISSUE-1
+
+# List all projects you have access to
+jira project list
+
+# List all boards in a project
+jira board list
+```
+
+### User Information
+
+```bash
+# Get your own username (useful in scripts)
+jira me
+```
+
+## Navigation and Interaction
+
+When in interactive UI:
+
+**Movement:**
+- **Arrow keys** or **j,k,h,l** - Navigate through list
+- **g** - Jump to top
+- **G** - Jump to bottom
+- **CTRL+f** - Scroll page down
+- **CTRL+b** - Scroll page up
+
+**Actions:**
+- **v** - View selected issue details
+- **m** - Transition the selected issue
+- **CTRL+r** or **F5** - Refresh the list
+- **ENTER** - Open selected issue in browser
+- **c** - Copy issue URL to clipboard (requires xclip/xsel on Linux)
+- **CTRL+k** - Copy issue key to clipboard
+- **w** or **TAB** - Toggle focus between sidebar and content
+- **q** / **ESC** / **CTRL+c** - Quit
+- **?** - Show help window
+
+## Output Formats and Options
+
+### Format Options
+
+```bash
+# Interactive table (default)
+jira issue list
+
+# Plain text output (for scripts)
+jira issue list --plain
+
+# CSV format (for spreadsheets)
+jira issue list --csv
+
+# Raw JSON (for programmatic parsing)
+jira issue list --raw
+```
+
+### Column Selection
+
+```bash
+# Default columns
+jira issue list
+
+# Custom columns
+jira issue list --columns key,summary,status
+jira issue list --columns key,summary,status,assignee,priority
+jira issue list --columns created,updated,reporter
+
+# Without headers (for parsing)
+jira issue list --plain --no-headers
+jira issue list --csv --no-headers
+```
+
+### Pagination
+
+jira-cli handles pagination automatically. For very large result sets, the tool will fetch additional pages as needed.

skills/jira-cli/references/scripting.md

@@ -0,0 +1,457 @@
+# Jira CLI - Scripting and Automation
+
+This file contains examples for automating Jira operations with scripts and integrating with CI/CD pipelines.
+
+## Bash Scripting Examples
+
+### Tickets Created Per Day This Month
+
+```bash
+#!/usr/bin/env bash
+# Generate report of tickets created per day in current month
+
+tickets=$(jira issue list --created month --plain --columns created --no-headers | \
+  awk '{print $2}' | awk -F'-' '{print $3}' | sort -n | uniq -c)
+
+echo "${tickets}" | while IFS=$'\t' read -r line; do
+  day=$(echo "${line}" | awk '{print $2}')
+  count=$(echo "${line}" | awk '{print $1}')
+  printf "Day #%s: %s tickets\n" "${day}" "${count}"
+done
+```
+
+### Number of Tickets Per Sprint
+
+```bash
+#!/usr/bin/env bash
+# Count tickets in each sprint
+
+sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
+
+echo "${sprints}" | while IFS=$'\t' read -r id name; do
+  count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l)
+  printf "%10s: %3d tickets\n" "${name}" $((count))
+done
+```
+
+### Number of Unique Assignees Per Sprint
+
+```bash
+#!/usr/bin/env bash
+# Count unique assignees in each sprint
+
+sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
+
+echo "${sprints}" | while IFS=$'\t' read -r id name; do
+  count=$(jira sprint list "${id}" --plain --columns assignee --no-headers 2>/dev/null | \
+    awk '{print $2}' | awk NF | sort -n | uniq | wc -l)
+  printf "%10s: %3d people\n" "${name}" $((count))
+done
+```
+
+### Daily Standup Report
+
+```bash
+#!/usr/bin/env bash
+# Generate daily standup report
+
+echo "=== Daily Standup Report ==="
+echo ""
+
+echo "Yesterday's work (updated in last 24h):"
+jira issue list -a$(jira me) --updated -1d --plain --columns key,summary
+
+echo ""
+echo "Currently working on:"
+jira issue list -a$(jira me) -s"In Progress" --plain --columns key,summary
+
+echo ""
+echo "Closed this week:"
+jira issue list -a$(jira me) -sDone --updated week --plain --columns key,summary
+```
+
+### Sprint Report Generator
+
+```bash
+#!/usr/bin/env bash
+# Generate sprint summary report
+
+SPRINT_ID=$1
+
+if [ -z "$SPRINT_ID" ]; then
+  echo "Usage: $0 <sprint-id>"
+  exit 1
+fi
+
+echo "=== Sprint Report for Sprint $SPRINT_ID ==="
+echo ""
+
+total=$(jira sprint list "$SPRINT_ID" --plain --no-headers | wc -l)
+done_count=$(jira sprint list "$SPRINT_ID" -sDone --plain --no-headers | wc -l)
+in_progress=$(jira sprint list "$SPRINT_ID" -s"In Progress" --plain --no-headers | wc -l)
+todo=$(jira sprint list "$SPRINT_ID" -s"To Do" --plain --no-headers | wc -l)
+
+echo "Total tickets: $total"
+echo "Done: $done_count"
+echo "In Progress: $in_progress"
+echo "To Do: $todo"
+echo ""
+
+completion_rate=$(echo "scale=2; ($done_count / $total) * 100" | bc)
+echo "Completion rate: ${completion_rate}%"
+```
+
+### Bulk Issue Assignment
+
+```bash
+#!/usr/bin/env bash
+# Assign unassigned high priority tickets to team members
+
+# Get list of unassigned high priority tickets
+issues=$(jira issue list -ax -yHigh -s"To Do" --plain --columns key --no-headers)
+
+# Team members
+team=("Alice" "Bob" "Charlie")
+team_size=${#team[@]}
+index=0
+
+# Assign in round-robin fashion
+for issue in $issues; do
+  assignee="${team[$index]}"
+  echo "Assigning $issue to $assignee"
+  jira issue assign "$issue" "$assignee"
+  index=$(( (index + 1) % team_size ))
+done
+```
+
+### Auto-Label Based on Summary
+
+```bash
+#!/usr/bin/env bash
+# Auto-label issues based on keywords in summary
+
+# Get issues without labels
+issues=$(jira issue list --plain --columns key,summary --no-headers)
+
+echo "$issues" | while IFS=$'\t' read -r key summary; do
+  # Check for keywords and add labels
+  if echo "$summary" | grep -qi "bug\|error\|crash"; then
+    echo "Adding 'bug' label to $key"
+    jira issue edit "$key" --label bug
+  fi
+
+  if echo "$summary" | grep -qi "feature\|enhancement"; then
+    echo "Adding 'enhancement' label to $key"
+    jira issue edit "$key" --label enhancement
+  fi
+
+  if echo "$summary" | grep -qi "urgent\|critical\|blocker"; then
+    echo "Adding 'urgent' label to $key"
+    jira issue edit "$key" --label urgent
+  fi
+done
+```
+
+### Export Issues to CSV
+
+```bash
+#!/usr/bin/env bash
+# Export filtered issues to CSV file
+
+OUTPUT_FILE="issues_$(date +%Y%m%d).csv"
+
+# Export with custom columns
+jira issue list \
+  --created month \
+  --csv \
+  --columns key,type,status,priority,assignee,summary,created \
+  > "$OUTPUT_FILE"
+
+echo "Exported to $OUTPUT_FILE"
+```
+
+### Monitor High Priority Issues
+
+```bash
+#!/usr/bin/env bash
+# Monitor and alert on high priority unassigned issues
+
+THRESHOLD=5
+
+count=$(jira issue list -ax -yHigh -s~Done --plain --no-headers | wc -l)
+
+if [ "$count" -gt "$THRESHOLD" ]; then
+  echo "⚠️  Alert: $count high priority unassigned issues (threshold: $THRESHOLD)"
+  jira issue list -ax -yHigh -s~Done --plain --columns key,summary
+
+  # Could send to Slack, email, etc.
+  # slack-cli send "#team-alerts" "High priority issues need attention: $count tickets"
+else
+  echo "✅ OK: $count high priority unassigned issues"
+fi
+```
+
+## CI/CD Integration
+
+### GitHub Actions - Create Jira Issue on PR
+
+```yaml
+name: Create Jira Issue
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  create-jira:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install jira-cli
+        run: |
+          wget https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_amd64.tar.gz
+          tar -xf jira_linux_amd64.tar.gz
+          sudo mv jira /usr/local/bin/
+
+      - name: Create Jira Issue
+        env:
+          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+          JIRA_SERVER: ${{ secrets.JIRA_SERVER }}
+          JIRA_PROJECT: ${{ secrets.JIRA_PROJECT }}
+        run: |
+          jira issue create \
+            -tTask \
+            -s"Review PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }}" \
+            -b"${{ github.event.pull_request.html_url }}" \
+            --no-input
+```
+
+### GitLab CI - Update Jira on Deploy
+
+```yaml
+update_jira:
+  stage: deploy
+  script:
+    - |
+      # Extract Jira keys from commit messages
+      JIRA_KEYS=$(git log --format=%B -n 10 | grep -oE '[A-Z]+-[0-9]+' | sort -u)
+
+      for KEY in $JIRA_KEYS; do
+        echo "Updating $KEY to Done"
+        jira issue move "$KEY" Done -RDeployed --comment "Deployed to production"
+      done
+  only:
+    - main
+```
+
+### Jenkins Pipeline - Sprint Metrics
+
+```groovy
+pipeline {
+    agent any
+    triggers {
+        cron('0 9 * * 1')  // Every Monday at 9 AM
+    }
+    stages {
+        stage('Generate Sprint Report') {
+            steps {
+                script {
+                    sh '''
+                        # Get current sprint
+                        SPRINT_ID=$(jira sprint list --current --table --plain --columns id --no-headers)
+
+                        # Generate metrics
+                        echo "Sprint Metrics Report" > sprint_report.txt
+                        echo "===================" >> sprint_report.txt
+
+                        total=$(jira sprint list $SPRINT_ID --plain --no-headers | wc -l)
+                        done=$(jira sprint list $SPRINT_ID -sDone --plain --no-headers | wc -l)
+
+                        echo "Total: $total" >> sprint_report.txt
+                        echo "Done: $done" >> sprint_report.txt
+
+                        # Send to team
+                        cat sprint_report.txt
+                    '''
+                }
+            }
+        }
+    }
+}
+```
+
+## Data Analysis
+
+### Export Data for Analysis
+
+```bash
+#!/usr/bin/env bash
+# Export comprehensive data for analysis
+
+# Create timestamped directory
+DIR="jira_export_$(date +%Y%m%d_%H%M%S)"
+mkdir -p "$DIR"
+
+# Export different views
+echo "Exporting all open issues..."
+jira issue list -s~Done --csv > "$DIR/open_issues.csv"
+
+echo "Exporting completed this month..."
+jira issue list -sDone --updated month --csv > "$DIR/completed_month.csv"
+
+echo "Exporting by assignee..."
+for user in $(jira issue list --plain --columns assignee --no-headers | sort -u); do
+  jira issue list -a"$user" --csv > "$DIR/assignee_${user// /_}.csv"
+done
+
+echo "Export complete in $DIR/"
+```
+
+### Calculate Team Velocity
+
+```bash
+#!/usr/bin/env bash
+# Calculate team velocity over last N sprints
+
+SPRINT_COUNT=5
+
+echo "=== Team Velocity (last $SPRINT_COUNT sprints) ==="
+echo ""
+
+sprints=$(jira sprint list --state closed --table --plain --columns id,name --no-headers | head -$SPRINT_COUNT)
+
+total_points=0
+sprint_count=0
+
+echo "$sprints" | while IFS=$'\t' read -r id name; do
+  # Assuming story points in summary or custom field
+  completed=$(jira sprint list "$id" -sDone --plain --no-headers | wc -l)
+  echo "$name: $completed stories"
+
+  total_points=$((total_points + completed))
+  sprint_count=$((sprint_count + 1))
+done
+
+# Calculate average
+if [ $sprint_count -gt 0 ]; then
+  avg=$(echo "scale=2; $total_points / $sprint_count" | bc)
+  echo ""
+  echo "Average velocity: $avg stories per sprint"
+fi
+```
+
+## Automation Helpers
+
+### Auto-Transition Based on PR Status
+
+```bash
+#!/usr/bin/env bash
+# Auto-transition Jira issues based on PR status
+
+# Get list of open PRs from GitHub
+# (requires gh CLI)
+prs=$(gh pr list --json number,title --jq '.[] | "\(.number)|\(.title)"')
+
+echo "$prs" | while IFS='|' read -r number title; do
+  # Extract Jira key from PR title
+  jira_key=$(echo "$title" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+
+  if [ -n "$jira_key" ]; then
+    # Check current status
+    status=$(jira issue view "$jira_key" --plain | grep "Status:" | awk '{print $2}')
+
+    # Move to In Review if not already
+    if [ "$status" != "Review" ]; then
+      echo "Moving $jira_key to In Review (PR #$number)"
+      jira issue move "$jira_key" "In Review"
+      jira issue link remote "$jira_key" "https://github.com/org/repo/pull/$number" "PR #$number"
+    fi
+  fi
+done
+```
+
+### Stale Issue Cleanup
+
+```bash
+#!/usr/bin/env bash
+# Find and handle stale issues
+
+# Find issues not updated in 3 months
+stale=$(jira issue list --updated-before -12w -s"To Do" --plain --columns key,summary --no-headers)
+
+echo "$stale" | while IFS=$'\t' read -r key summary; do
+  echo "Stale issue found: $key - $summary"
+
+  # Add comment asking for update
+  jira issue comment add "$key" "This issue hasn't been updated in 3 months. Is it still relevant?"
+
+  # Add stale label
+  jira issue edit "$key" --label stale
+
+  # Optionally: move to backlog or close
+  # jira issue move "$key" "Backlog"
+done
+```
+
+## Best Practices for Scripts
+
+### Error Handling
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail  # Exit on error, undefined vars, pipe failures
+
+# Check if jira-cli is available
+if ! command -v jira &> /dev/null; then
+  echo "Error: jira-cli not found. Please install it first."
+  exit 1
+fi
+
+# Check for required environment variables
+if [ -z "${JIRA_API_TOKEN:-}" ]; then
+  echo "Error: JIRA_API_TOKEN not set"
+  exit 1
+fi
+
+# Wrap jira commands with error handling
+if ! jira issue list -a$(jira me) 2>&1; then
+  echo "Error: Failed to fetch issues"
+  exit 1
+fi
+```
+
+### Logging and Debugging
+
+```bash
+#!/usr/bin/env bash
+
+# Enable debug mode
+DEBUG=${DEBUG:-false}
+
+debug() {
+  if [ "$DEBUG" = "true" ]; then
+    echo "[DEBUG] $*" >&2
+  fi
+}
+
+debug "Starting script..."
+debug "Fetching issues for user: $(jira me)"
+
+issues=$(jira issue list -a$(jira me) --plain --columns key --no-headers)
+debug "Found $(echo "$issues" | wc -l) issues"
+```
+
+### Rate Limiting
+
+```bash
+#!/usr/bin/env bash
+
+# Process issues with rate limiting
+issues=$(jira issue list --plain --columns key --no-headers)
+
+for issue in $issues; do
+  echo "Processing $issue"
+  jira issue view "$issue" > /dev/null
+
+  # Rate limit: 1 request per second
+  sleep 1
+done
+```

skills/jira-cli/references/workflows.md

@@ -0,0 +1,290 @@
+# Jira CLI - Common Workflows
+
+This file contains practical workflow examples for common Jira use cases and team collaboration scenarios.
+
+## Daily Standup Preparation
+
+Get quick answers for your daily standup:
+
+```bash
+# What did I work on yesterday?
+jira issue list -a$(jira me) --updated -1d
+
+# What am I working on today?
+jira issue list -a$(jira me) -s"In Progress"
+
+# What tickets did I close this week?
+jira issue list -a$(jira me) -sDone --updated week
+
+# Any blockers? (high priority issues assigned to me)
+jira issue list -a$(jira me) -yHigh -s~Done
+```
+
+## Sprint Planning
+
+Prepare for and manage sprint planning:
+
+```bash
+# High priority unassigned tickets (need assignment)
+jira issue list -ax -yHigh
+
+# Backlog items ready for sprint (ordered by rank like UI)
+jira issue list -s"Ready for Dev" --order-by rank --reverse
+
+# Current sprint progress
+jira sprint list --current
+
+# Current sprint with my tasks only
+jira sprint list --current -a$(jira me)
+
+# See what's planned for next sprint
+jira sprint list --next
+
+# Check sprint capacity (how many issues)
+jira sprint list SPRINT_ID --plain --no-headers | wc -l
+```
+
+## Code Review Workflow
+
+Integrate Jira with your code review process:
+
+```bash
+# 1. Create ticket for review
+jira issue create -tTask -s"Code review: Feature X"
+
+# 2. Link to related PR
+jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
+
+# 3. Move to review status
+jira issue move ISSUE-1 "In Review"
+
+# 4. Add review comments
+jira issue comment add ISSUE-1 "LGTM! Approved changes."
+
+# 5. Close the ticket
+jira issue move ISSUE-1 Done -RFixed
+```
+
+## Bug Triage
+
+Efficient bug triage workflow:
+
+```bash
+# List new bugs from last week
+jira issue list -tBug -sOpen --created -7d
+
+# List critical/high priority bugs
+jira issue list -tBug -yHighest,High -s~Done
+
+# Assign high priority bug to team lead
+jira issue assign BUG-123 "Team Lead"
+
+# Add triage notes
+jira issue comment add BUG-123 "Investigating root cause. Checking logs."
+
+# Update priority and labels
+jira issue edit BUG-123 -yHigh -lproduction -lurgent
+
+# Link to related issues
+jira issue link BUG-123 BUG-100 "is caused by"
+```
+
+## Epic Management Workflow
+
+Working with epics effectively:
+
+```bash
+# Create a new epic for quarterly goals
+jira epic create -n"Q1 2025 Goals" -s"Q1 Goals" -yHigh
+
+# List open epics to see what's in progress
+jira epic list -sOpen
+
+# View all tasks in a specific epic
+jira epic list EPIC-42
+
+# Add new stories to the epic
+jira issue create -tStory -s"User authentication" -PEPIC-42
+jira epic add EPIC-42 STORY-100 STORY-101
+
+# Check epic progress (how many done vs total)
+jira epic list EPIC-42 -sDone --plain --no-headers | wc -l
+jira epic list EPIC-42 --plain --no-headers | wc -l
+
+# Remove completed stories from epic
+jira epic remove STORY-98 STORY-99
+```
+
+## Release Management
+
+Managing releases and versions:
+
+```bash
+# List all releases
+jira release list
+
+# List releases for specific project
+jira release list --project MYPROJECT
+
+# Create issues for a release
+jira issue create -tBug -s"Release blocker" --fix-version v2.0
+
+# Find all issues in a release
+jira issue list --fix-version v2.0
+
+# Find unresolved issues blocking release
+jira issue list --fix-version v2.0 -s~Done
+```
+
+## Team Collaboration
+
+Collaborate effectively with your team:
+
+```bash
+# See what your teammate is working on
+jira issue list -a"John Doe" -s"In Progress"
+
+# Find issues reported by PM for review
+jira issue list -r"Jane PM" -s"To Do" --order-by priority
+
+# Check team's completed work this week
+jira issue list -a~x --updated week -sDone
+
+# Find unassigned high priority work
+jira issue list -ax -yHigh -s"To Do"
+
+# Check who's working on what in current sprint
+jira sprint list --current --plain --columns assignee,key,summary
+```
+
+## Incident Response
+
+Handle production incidents:
+
+```bash
+# Create critical incident ticket
+jira issue create -tBug -s"Production outage: API down" -yHighest -lincident -lproduction --no-input
+
+# Link related issues
+jira issue link INC-1 BUG-789 "is caused by"
+
+# Add status updates
+jira issue comment add INC-1 "Root cause identified. Rolling back deployment."
+
+# Track time spent
+jira issue worklog add INC-1 "2h" --comment "Incident response" --no-input
+
+# Close incident
+jira issue move INC-1 Done -RFixed --comment "Service restored. Post-mortem scheduled."
+```
+
+## Backlog Grooming
+
+Keep your backlog organized:
+
+```bash
+# Find old unassigned tickets (potential cleanup candidates)
+jira issue list -ax --created-before -12w -s"To Do"
+
+# Find tickets with no recent activity
+jira issue list --updated-before -8w -s~Done
+
+# Find tickets missing labels or components
+jira issue list -l~x -C~x
+
+# Update stale tickets in bulk (interactive or scripted)
+for issue in $(jira issue list -ax --created-before -12w --plain --columns key --no-headers); do
+  jira issue edit $issue -s"To Do" --label stale
+done
+```
+
+## Cross-Team Coordination
+
+Working across teams:
+
+```bash
+# Find issues blocked by other teams
+jira issue list -a$(jira me) -lblocked --plain --columns key,summary,status
+
+# Check dependencies in a project
+jira issue list -pOTHERPROJ -a"Dependency Owner"
+
+# See what other teams need from you
+jira issue list -r~$(jira me) -a$(jira me) --plain --columns key,reporter,summary
+
+# Create handoff ticket
+jira issue create -tTask -s"Handoff: Database migration" -CInfra -a"Infrastructure Lead"
+```
+
+## Personal Productivity
+
+Personal task management:
+
+```bash
+# My daily dashboard
+alias jira-today='jira issue list -a$(jira me) -s"In Progress"'
+
+# What I should focus on
+alias jira-priorities='jira issue list -a$(jira me) -yHigh -s~Done --order-by priority'
+
+# What I reported that needs attention
+alias jira-reported='jira issue list -r$(jira me) -s"To Do"'
+
+# Quick add task
+alias jira-task='jira issue create -tTask -a$(jira me)'
+
+# My work this week
+alias jira-week='jira issue list -a$(jira me) --updated week'
+```
+
+## Best Practices
+
+### Efficient Filtering
+
+```bash
+# Combine multiple filters for precision
+jira issue list -a$(jira me) -yHigh -s"In Progress" --created week -lurgent
+
+# Use NOT operator (~) to exclude
+jira issue list -s~Done -s~"In Progress"  # Not done and not in progress
+
+# Time-based queries for recent activity
+jira issue list --updated -2h  # Last 2 hours
+jira issue list --created today  # Created today
+```
+
+### Bulk Operations
+
+```bash
+# Add multiple issues to sprint
+jira sprint add SPRINT_ID $(jira issue list -s"Ready" --plain --columns key --no-headers | head -10 | tr '\n' ' ')
+
+# Batch assign to team members
+for issue in ISSUE-1 ISSUE-2 ISSUE-3; do
+  jira issue assign $issue "Team Member"
+done
+```
+
+### Keyboard Shortcuts in Interactive Mode
+
+Master the interactive UI for speed:
+- Use **j/k** instead of arrows for Vim-like navigation
+- Press **v** to quickly view details without leaving the list
+- Press **m** to transition without navigating to browser
+- Use **c** and **CTRL+k** to quickly copy links/keys for sharing
+
+### Output Formatting for Different Needs
+
+```bash
+# For spreadsheets
+jira issue list --csv > issues.csv
+
+# For scripts
+jira issue list --plain --no-headers --columns key
+
+# For reports
+jira issue list --plain --columns key,status,assignee,summary
+
+# For JSON processing
+jira issue list --raw | jq '.issues[] | {key, summary}'
+```