jira-integration

# Jira Integration Skill

Comprehensive Jira integration through lightweight Python CLI scripts.

## Auto-Trigger Patterns

**AUTOMATICALLY ACTIVATE** when user mentions:
- **Jira URLs**: `https://jira.*/browse/*`, `https://*.atlassian.net/browse/*`, `https://*/jira/browse/*`
- **Issue keys**: Pattern like `PROJ-123`, `NRS-4167`, `ABC-1` (uppercase letters + hyphen + numbers)
- **Keywords**: "Jira issue", "Jira ticket", "search Jira", "open this ticket"

**Example triggers:**
- "I want to work on https://jira.netresearch.de/browse/NRS-4167" → Extract NRS-4167, fetch issue
- "What's the status of PROJ-123?" → Fetch issue PROJ-123
- "Search Jira for my open issues" → Run JQL search

## Authentication Failure Handling

**CRITICAL**: When authentication fails, DO NOT just display the error. Instead:

1. **Detect failure** - Look for "Missing required variable", "Configuration errors", or 401/403 responses
2. **Offer help** - Ask: "Jira credentials aren't configured. Would you like me to help set them up?"
3. **Run interactive setup** - Execute: `uv run skills/jira-communication/scripts/core/jira-setup.py`
4. **The script will**:
   - Prompt for Jira URL
   - Auto-detect Cloud vs Server/DC
   - Ask for credentials (API token or Personal Access Token)
   - Validate credentials before saving
   - Create `~/.env.jira` with secure permissions (600)

## Sub-Skills

This plugin contains two specialized skills:

| Skill | Purpose |
|-------|---------|
| `jira-communication` | API operations via Python CLI scripts |
| `jira-syntax` | Wiki markup syntax, templates, validation |

## Quick Start

```bash
# Install uv (Python package runner)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Configure credentials in ~/.env.jira
JIRA_URL=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-api-token

# Validate setup
uv run scripts/core/jira-validate.py --verbose
```

## Common Operations

```bash
# Search issues
uv run scripts/core/jira-search.py query "project = PROJ AND status = 'In Progress'"

# Get issue details
uv run scripts/core/jira-issue.py get PROJ-123

# Add worklog
uv run scripts/core/jira-worklog.py add PROJ-123 "2h 30m" -c "Code review"

# Create issue
uv run scripts/workflow/jira-create.py issue PROJ "Fix bug" --type Bug --priority High

# Transition issue
uv run scripts/workflow/jira-transition.py PROJ-123 "In Progress"
```

## Features

- **Zero MCP overhead** - Scripts invoked via Bash, no tool descriptions loaded
- **Fast execution** - No Docker container spin-up
- **Full API coverage** - All common Jira operations supported
- **Jira Server/DC + Cloud** - Works with both deployment types
- **Automatic auth detection** - API token, PAT, or basic auth

## Sub-Skill Documentation

- **skills/jira-communication/SKILL.md** - API operations (scripts, JQL, worklogs)
- **skills/jira-syntax/SKILL.md** - Wiki markup syntax, templates, validation

## Scripts Reference

### Core Operations
| Script | Purpose |
|--------|---------|
| `jira-setup.py` | **Interactive credential setup** (run when auth fails) |
| `jira-validate.py` | Verify connection and credentials |
| `jira-issue.py` | Get or update issue details |
| `jira-search.py` | Search with JQL queries |
| `jira-worklog.py` | Time tracking entries |
| `jira-comment.py` | Add/list comments |

### Workflow Operations
| Script | Purpose |
|--------|---------|
| `jira-create.py` | Create new issues |
| `jira-transition.py` | Change issue status |
| `jira-link.py` | Create/list issue links |
| `jira-sprint.py` | Sprint management |
| `jira-board.py` | Board operations |

## Jira Syntax Quick Reference

**Important**: Jira uses wiki markup, NOT Markdown.

| Jira Syntax | Purpose |
|-------------|---------|
| `h2. Title` | Heading (NOT `## Title`) |
| `*bold*` | Bold (NOT `**bold**`) |
| `{code:java}...{code}` | Code block (NOT triple backticks) |
| `[text\|url]` | Link |
| `[PROJ-123]` | Issue link |

See `skills/jira-syntax/SKILL.md` for complete syntax guide.

---

> **Contributing:** Improvements to this skill should be submitted to the source repository:
> https://github.com/netresearch/jira-skill