commit bc6aaa6d91fba3fdad7d5f17f8dbc3752eed627b Author: Zhongwei Li Date: Sun Nov 30 09:07:01 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..2f88efa --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "jira-cli", + "description": "Command-line Jira management skill using jira-cli with efficient querying and issue workflows", + "version": "0.1.2", + "author": { + "name": "David Golden", + "email": "xdg@xdg.me" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..62944d2 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# jira-cli + +Command-line Jira management skill using jira-cli with efficient querying and issue workflows diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..500904f --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:xdg/xdg-claude:jira-cli", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "d78c99f7dc8fe11190719ce277689da7100b43fd", + "treeHash": "a8ada08add8a8d1f730cedd6c9c2164c69154846be44f9bb75a4813ddd829caa", + "generatedAt": "2025-11-28T10:29:06.406258Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "jira-cli", + "description": "Command-line Jira management skill using jira-cli with efficient querying and issue workflows", + "version": "0.1.2" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "1cf547b61a216bed086a040da1911b7b69370183983d1ba74e471cf84ba6bd65" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "5f3409cf0f998f9cd4e61b06aa05004b17f7194a1f73ad0876d4fe423c33f41a" + }, + { + "path": "skills/jira-cli/SKILL.md", + "sha256": "a3c88dfc3ce3669e49d7f2f15f1f910b664f42f5b5e1fd395940627252b40d61" + }, + { + "path": "skills/jira-cli/reference/jira-cli-reference.md", + "sha256": "755d7fc8fcf50a9fa0068ece7f71dfe248286966e15133162e87bf22f778e012" + } + ], + "dirSha256": "a8ada08add8a8d1f730cedd6c9c2164c69154846be44f9bb75a4813ddd829caa" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/jira-cli/SKILL.md b/skills/jira-cli/SKILL.md new file mode 100644 index 0000000..58a4dd3 --- /dev/null +++ b/skills/jira-cli/SKILL.md @@ -0,0 +1,47 @@ +--- +name: jira-cli +description: Manage Jira issues via command line - read issues, query by filters, create/update issues, add comments, and close issues after work completion. +--- + +# jira-cli: Command-Line Jira Management + +Use jira-cli when interacting with Jira. Assume jira-cli already installed/configured. + +**Project flag:** Always use `-p PROJ` to specify project explicitly (don't rely on defaults) + +## When to Use + +**Use for:** Reading issues, querying (status/priority/assignee filters), creating/updating issues, adding comments, closing after work complete + +**Ask user for web UI:** Attachments/images, visual board operations (can't do from CLI) + +## Core Pattern: Work on Issue + +```bash +jira issue view -p PROJ PROJ-123 # Read requirements +jira issue assign PROJ-123 $(jira me) # Assign to user +# ... implement ... +jira issue comment add PROJ-123 "Fixed in $(git rev-parse --short HEAD)" +jira issue move PROJ-123 "Done" # Close when complete +``` + +## Efficient Extraction + +Extract only needed fields to minimize context usage: + +```bash +# Get specific fields only +jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.status.name' + +# List keys for iteration +jira issue list -p PROJ --plain --no-headers --columns KEY +``` + +## When to Load Detailed Guide + +Load [jira-cli reference guide](./reference/jira-cli-reference.md) for: +- Command syntax and flags +- Query patterns and JQL filtering +- Output format options +- User intent → command mapping +- Git integration patterns diff --git a/skills/jira-cli/reference/jira-cli-reference.md b/skills/jira-cli/reference/jira-cli-reference.md new file mode 100644 index 0000000..bb91cd9 --- /dev/null +++ b/skills/jira-cli/reference/jira-cli-reference.md @@ -0,0 +1,185 @@ +# jira-cli Detailed Reference + +**Assumptions:** Already installed/configured, `JIRA_API_TOKEN` set, `jira init` complete + +**Project flag:** Always use `-p PROJ` to specify project explicitly (don't rely on defaults) + +--- + +# Core Workflow: Working on Issue + +```bash +# User: "Work on PROJ-123" +jira issue view -p PROJ PROJ-123 # Read requirements +jira issue assign PROJ-123 $(jira me) # Assign to user +jira issue move PROJ-123 "In Progress" # Update status +# ... implement code ... +jira issue comment add PROJ-123 "Fixed in $(git rev-parse --short HEAD)" +jira issue move PROJ-123 "Done" # Close +``` + +--- + +# Command Syntax by Intent + +## Query Issues + +**By filters:** +```bash +jira issue list -p PROJ -tBug -aCurrentUser -s"To Do" # Type, assignee, status +jira issue list -p PROJ -yHigh -lbackend --created week # Priority, label, date +``` + +**By JQL (complex queries):** +```bash +jira issue list -p PROJ --jql 'assignee=currentUser() AND status!="Done"' +jira issue list -p PROJ --jql 'priority IN (High,Critical) AND created >= -7d' +``` + +**Common patterns:** +- My bugs: `jira issue list -p PROJ -tBug -aCurrentUser` +- High priority work: `jira issue list -p PROJ -yHigh -s"To Do"` +- Recent activity: `jira issue list -p PROJ -aCurrentUser --updated -1d` + +## View Issue + +```bash +jira issue view -p PROJ PROJ-123 # Basic view +jira issue view -p PROJ PROJ-123 --comments 50 # With comments +jira issue view -p PROJ PROJ-123 --raw # JSON output +jira open PROJ-123 # Open in browser +``` + +## Create Issue + +```bash +jira issue create -p PROJ -tBug -s"Summary" -yHigh -lbackend +jira issue create -p PROJ -tStory -s"Feature name" +``` + +## Update Issue + +```bash +jira issue assign PROJ-123 $(jira me) # Assign to self +jira issue assign PROJ-123 "user@example.com" # Assign to user +jira issue move PROJ-123 "In Progress" # Change status +jira issue comment add PROJ-123 "Comment text" # Add comment +jira issue edit -p PROJ PROJ-123 -yHigh -lurgent # Edit priority/labels +``` + +--- + +# Efficient Data Extraction + +**Principle:** Extract only needed fields to minimize context. + +```bash +# Get single field via jq +jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.status.name' +jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.assignee.displayName' + +# Get specific columns only +jira issue list -p PROJ --plain --no-headers --columns KEY +jira issue list -p PROJ --plain --columns KEY,STATUS,ASSIGNEE + +# Check existence +jira issue view -p PROJ PROJ-123 --plain > /dev/null 2>&1 && echo "exists" +``` + +--- + +# JQL Reference + +**Structure:** `jira issue list -p PROJ --jql 'FIELD OPERATOR VALUE'` + +**Operators:** `=`, `!=`, `IN`, `>`, `<`, `>=`, `<=` + +**Functions:** +- `currentUser()` - Current logged-in user +- `openSprints()` - Active sprints +- `startOfWeek()`, `startOfDay()` - Date functions + +**Date formats:** +- Relative: `-7d`, `-2w`, `-1m` +- Absolute: `"2023-12-01"` + +**Examples:** +```bash +# Multiple conditions +jira issue list -p PROJ --jql 'project=PROJ AND assignee=currentUser() AND status!="Done"' + +# Date ranges +jira issue list -p PROJ --jql 'created >= -7d AND updated >= startOfWeek()' + +# IN operator +jira issue list -p PROJ --jql 'status IN ("To Do","In Progress")' +``` + +--- + +# Output Formats + +**For display:** Default table format +**For parsing:** `--plain --no-headers --columns KEY` +**For extraction:** `--raw` with `jq` + +```bash +# Table (default) +jira issue list -p PROJ + +# Plain text for parsing +jira issue list -p PROJ --plain --no-headers --columns KEY + +# JSON for field extraction +jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.summary' +``` + +--- + +# Filter Flags Reference + +| Flag | Purpose | Example | +|------|---------|---------| +| `-t` | Type | `-tBug`, `-tStory`, `-tTask` | +| `-s` | Status | `-s"To Do"`, `-s"In Progress"` | +| `-y` | Priority | `-yHigh`, `-yMedium`, `-yLow` | +| `-a` | Assignee | `-aCurrentUser`, `-a"user@example.com"` | +| `-l` | Label | `-lbackend`, `-lurgent,critical` | +| `--created` | Created date | `--created today`, `--created week`, `--created 2023-12-01` | +| `--updated` | Updated date | `--updated -7d` | +| `--jql` | Raw JQL query | `--jql 'custom query'` | + +--- + +# User Intent → Command Mapping + +| User Says | Command | +|-----------|---------| +| "Work on PROJ-123" | `jira issue view -p PROJ PROJ-123` | +| "What bugs do I have?" | `jira issue list -p PROJ -tBug -aCurrentUser` | +| "What should I work on?" | `jira issue list -p PROJ -yHigh -s"To Do"` | +| "Create bug for X" | `jira issue create -p PROJ -tBug -s"X"` | +| "Close PROJ-123" | `jira issue move PROJ-123 "Done"` | +| "Add comment to PROJ-123" | `jira issue comment add PROJ-123 "text"` | +| "What did I work on yesterday?" | `jira issue list -p PROJ -aCurrentUser --updated -1d` | + +--- + +# Best Practices + +1. **Always specify project:** Use `-p PROJ` flag explicitly +2. **Extract minimal data:** Use `--raw | jq` for specific fields instead of reading full issue +3. **Filter before reading:** Narrow with queries, then read details +4. **Use plain output for scripts:** `--plain --no-headers --columns KEY` +5. **Proactive updates:** After code changes, offer to add commits/close issues +6. **Rate limits:** Add `sleep 0.5` between bulk operations + +--- + +# Troubleshooting + +**Auth errors:** Check `echo $JIRA_API_TOKEN` and `cat ~/.config/.jira/.config.yml` + +**Issue not found:** Verify project key correct: `jira issue view -p PROJ PROJ-123 --plain` + +**Rate limits:** Add delays between bulk operations, use more specific queries