From cc6be606c506e05744b61c471f95dbbe281603dc Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:46:33 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 +++ README.md | 3 + plugin.lock.json | 53 ++++++++++++ skills/jira/SKILL.md | 103 +++++++++++++++++++++++ skills/jira/references/mcp-parity.md | 81 ++++++++++++++++++ skills/jira/scripts/check-environment.sh | 24 ++++++ 6 files changed, 275 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/jira/SKILL.md create mode 100644 skills/jira/references/mcp-parity.md create mode 100755 skills/jira/scripts/check-environment.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..fc6bd8c --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "jira", + "description": "Manage Jira projects, issues, boards, and sprints via the jira CLI", + "version": "0.1.0", + "author": { + "name": "Otahontas" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1238646 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# jira + +Manage Jira projects, issues, boards, and sprints via the jira CLI diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..73dbdad --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:otahontas/jira-cli-skill:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "856d9f5617ff81f8c35667b6f84fa708aafabf91", + "treeHash": "174cb94babb5239cd20d0afcc18aa2d48e3885b4e8d52715e6fa2cb0c6ee0827", + "generatedAt": "2025-11-28T10:27:32.392063Z", + "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", + "description": "Manage Jira projects, issues, boards, and sprints via the jira CLI", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "1b2bdf46da491b256fd90fa4b6dd8715bef254115972f216ae3c44318a4b3efe" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "e29155e38f69bca8a918d5fecef49d9ea21e17a509d445274ea2f69b6a30bca1" + }, + { + "path": "skills/jira/SKILL.md", + "sha256": "2df7c973545157e97c0c36e8d1a570205b926d52cdca239b04ca9c49aba1cea4" + }, + { + "path": "skills/jira/references/mcp-parity.md", + "sha256": "98809966db7ed0e13d9f546aad10fa11dbfc96e3e886769573ddacda27771a05" + }, + { + "path": "skills/jira/scripts/check-environment.sh", + "sha256": "273b7b3d2f26f893b45845dbac2d814896cc2c6161f848b144dc3cc6c3c99fd1" + } + ], + "dirSha256": "174cb94babb5239cd20d0afcc18aa2d48e3885b4e8d52715e6fa2cb0c6ee0827" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/jira/SKILL.md b/skills/jira/SKILL.md new file mode 100644 index 0000000..24a56f6 --- /dev/null +++ b/skills/jira/SKILL.md @@ -0,0 +1,103 @@ +--- +name: jira +description: Operate Atlassian Jira through the official jira CLI; trigger this skill to list, inspect, create, update, triage, or report on Jira work using deterministic shell commands aligned with Jira MCP workflows. +version: 0.1.0 +--- + +# Jira Issue Management + +**Use this skill whenever Jira work is requested.** + +## Setup + +- Run `./scripts/check-environment.sh`. The skill halts with explicit instructions when `jira` is missing or not authenticated (`jira init` required once). +- Ensure the `jira` CLI remains in PATH after the check. +- Use upstream flags like `--project`, `--board`, etc., for context as needed; no extra configuration lives in the skill. + +## Command Pattern + +```bash +jira [arguments] [flags] +``` + +Primary commands: `issue`, `project`, `board`, `sprint`, `epic`, `release`, `open`, `me`, `serverinfo`. + +Keep outputs deterministic: + +- Run `./scripts/check-environment.sh` at the start of every session; abort work if it reports an error. +- Add `--plain` plus `--columns ...` for TSV tables that stream cleanly. +- Use `--raw` (alias for JSON) when structured data is required. +- Provide explicit ranges via `--paginate start:limit` to cap interactive views. + +## Core Workflows + +- **Projects** – enumerate available projects + ```bash + jira project list --plain --columns key,name,type + ``` + +- **Issues** + - Search / filter: + ```bash + jira issue list --status Done --assignee "$(jira me)" --plain --columns key,summary,status,assignee + jira issue search 'project = PROJ AND status = "In Progress"' --plain --columns key,summary,status + jira issue list --raw --jql 'label = backend' --paginate 0:50 + ``` + - View details: `jira issue view PROJ-123 --plain --comments 5` + - Create: + ```bash + jira issue create \ + --type Bug \ + --summary "API returns 500" \ + --description-file docs/bug.md \ + --priority High \ + --assignee "$(jira me)" \ + --label backend --label urgent + ``` + - Update: + ```bash + jira issue edit PROJ-123 --summary "Refine API contract" --priority Medium + jira issue move PROJ-123 "In Review" --comment "Ready for QA" + jira issue assign PROJ-123 user@example.com + ``` + - Comment / worklog: + ```bash + jira issue comment add PROJ-123 "Investigating..." --no-input + jira issue worklog add PROJ-123 "1h 30m" --comment "Debugging" + ``` + - Linking: `jira issue link PROJ-1 PROJ-2 "Blocks"` (remove with `jira issue unlink ...`). + +- **Epics** + - Create: `jira epic create --name "Platform Stability" --summary "Q3 initiative"` + - List: `jira epic list --plain --columns key,summary,status` + - Attach issues: `jira epic add EPIC-1 PROJ-123 PROJ-456` + +- **Boards & Sprints** + - Boards: `jira board list --plain --columns id,name,type` + - Sprint overview: `jira sprint list --plain --columns id,name,state,start,end` + - Sprint issues: `jira sprint list --plain --columns key,summary,status,assignee` + - Move issues: `jira sprint add PROJ-123 PROJ-456` + - Close sprint: `jira sprint close ` + +- **Releases (Versions)** – `jira release list --plain --columns name,start,end,state` + +- **Open in browser** – `jira open PROJ-123 --no-browser` (omit flag to launch UI). + +- **User / Instance context** – `jira me`, `jira serverinfo`, `jira version`. + +## Output Strategies + +- Issues default to `key,summary,status,assignee`; sprints to `id,name,state,start,end`. Override with `--columns`. +- `--raw` returns JSON for downstream processing (`jq`, scripting). +- Combine commands with standard Unix tooling: + ```bash + jira issue list --plain --columns key,status,assignee | rg "In Progress" + jira issue view PROJ-123 --plain --comments 10 | tee PROJ-123.txt + ``` + +## Reference Material + +- `references/mcp-parity.md` contains a Jira MCP → CLI mapping, including attachments, watchers, and worklogs. +- For authentication or environment issues + - re-run `jira init` and review `~/.config/.jira/.config.yml`. + - check that JIRA_API_TOKEN is set or `~/.netrc` contains proper jira setup diff --git a/skills/jira/references/mcp-parity.md b/skills/jira/references/mcp-parity.md new file mode 100644 index 0000000..f401f0e --- /dev/null +++ b/skills/jira/references/mcp-parity.md @@ -0,0 +1,81 @@ +# Jira MCP Parity Mapping + +High-level equivalence table between Jira MCP API operations and the `jira` CLI commands exposed through `jira-cli-skill`. Load this reference when planning workflows that depend on specific MCP actions. + +## Projects + +| MCP capability | CLI command | Notes | +|------------------------------|------------------------------------------------------------------|-------| +| List projects | `jira project list --plain --columns key,name,type` | `--plain` recommended for deterministic TSV output. | +| Get project details | `jira project view ` | Use `--raw` for JSON payload. | + +## Issues + +| MCP capability | CLI command | Notes | +|------------------------------------|-----------------------------------------------------------------------------------------------------|-------| +| Search issues (JQL) | `jira issue search '' --plain --columns key,summary,status` | Add `--raw` for JSON. | +| List issues by status/assignee | `jira issue list --status "In Progress" --assignee "$(jira me)" --plain --columns key,summary,status,assignee` | Default columns recommended for parsing. | +| Get issue details | `jira issue view PROJ-123 --plain --comments 5` | Increase comments via `--comments N`. | +| Create issue | `jira issue create --type Task --summary "Title" --description-file path.md --priority High` | Use `--assignee`, `--label`, `--component`, `--custom key=value`. | +| Update fields | `jira issue edit PROJ-123 --summary "New" --priority Low --custom story-points=5` | Combine with `issue move` for status transitions. | +| Transition workflow | `jira issue move PROJ-123 "In Review" --comment "Ready"` | Accepts `--resolution`, `--assignee`. | +| Assign issue | `jira issue assign PROJ-123 user@example.com` | Accepts email, display name, or `default`. | +| Comment | `jira issue comment add PROJ-123 "Body" --no-input` | `--template -` reads stdin. | +| Delete issue | `jira issue delete PROJ-123 --cascade` | Warn: irreversible unless Jira config allows recovery. | +| Clone issue | `jira issue clone PROJ-123 --summary "Copy"` | Supports overrides for fields. | +| Link issues | `jira issue link PROJ-1 PROJ-2 "Blocks"` | Remove via `jira issue unlink PROJ-1 PROJ-2`. | +| Manage attachments | `jira issue attach add PROJ-123 ./file.txt --name "spec.txt"` | Remove via `attach remove`. | +| Watchers | `jira issue watch PROJ-123 user@example.com` | Omit user to watch/unwatch self. | +| Worklogs | `jira issue worklog add PROJ-123 "2h" --started "2024-06-01 09:00" --timezone "America/New_York"` | `worklog edit` and `worklog delete` mirror MCP updates. | + +## Epics + +| MCP capability | CLI command | Notes | +|--------------------------|------------------------------------------------------------------------------|-------| +| Create epic | `jira epic create --name "Epic" --summary "Goal" --label initiative` | Provide `--type` if org uses custom epic issue types. | +| List epics | `jira epic list --plain --columns key,summary,status` | Use filters: `--status`, `--priority`, `--label`. | +| Attach issues to epic | `jira epic add EPIC-1 PROJ-1 PROJ-2` | Up to 50 issues per call. | +| Remove issues from epic | `jira epic remove PROJ-1 PROJ-2` | Equivalent to MCP unlink. | + +## Boards & Sprints + +| MCP capability | CLI command | Notes | +|----------------------------------|----------------------------------------------------------------------------------------------|-------| +| List boards | `jira board list --plain --columns id,name,type` | Requires project context. | +| List sprints on board | `jira sprint list --plain --columns id,name,state,start,end` | `--paginate` limits results. | +| View issues in sprint | `jira sprint list --plain --columns key,summary,status,assignee` | Add `--state active` etc. | +| Add issues to sprint | `jira sprint add PROJ-123 PROJ-456` | Mirrors MCP batch add. | +| Remove issues from sprint | `jira sprint remove PROJ-123` | Use when unassigning sprints. | +| Close sprint | `jira sprint close ` | Equivalent to MCP close. | + +## Releases / Versions + +| MCP capability | CLI command | Notes | +|------------------------|--------------------------------------------------------------------------------|-------| +| List releases | `jira release list --plain --columns name,start,end,state` | CLI uses "release" for Jira versions. | +| Create release | `jira release create --name "v1.5.0" --release-date 2024-08-01` | Additional flags: `--description`, `--project`. | +| Update release | `jira release edit --name "v1.5.1"` | Equivalent to MCP update. | +| Archive/delete release | `jira release archive ` / `jira release delete ` | Deletes require confirmation; use `--confirm`. | + +## User & Instance + +| MCP capability | CLI command | Notes | +|-----------------------|--------------------------------------|-------| +| Current user | `jira me` | Returns display name and account ID. | +| Instance metadata | `jira serverinfo` | Mirrors MCP server info. | +| CLI version | `jira version` | Helpful for troubleshooting. | + +## Attachments & Assets + +- Upload file: `jira issue attach add PROJ-123 ./design.pdf` +- Download attachment: `jira issue attach get PROJ-123 --output ./design.pdf` +- List attachments: `jira issue attach list PROJ-123 --plain --columns id,filename,author` + +## Tips + +- Combine CLI options to keep parity with MCP filters (`--status`, `--priority`, `--label`, `--assignee`, `--jql`). +- Use `--raw` when Claude must parse JSON; otherwise rely on the TSV defaults to minimise tokens. +- Env overrides: + - `JIRA_PROJECT` auto-applies `--project` when omitted. + - `JIRA_CLI_PATH` points the wrapper to a custom binary location. +- When the CLI reports "interactive view", re-run with `--plain` or `--raw` to keep outputs deterministic. diff --git a/skills/jira/scripts/check-environment.sh b/skills/jira/scripts/check-environment.sh new file mode 100755 index 0000000..8b6c7d9 --- /dev/null +++ b/skills/jira/scripts/check-environment.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +set -euo pipefail + +echo "[jira-cli-skill] Verifying Jira CLI environment..." + +if ! command -v jira >/dev/null 2>&1; then + echo "ERROR: jira CLI not found in PATH." + echo "Install it via 'brew install jira-cli' or follow https://github.com/ankitpokhrel/jira-cli#installation" + exit 1 +fi + +if ! jira version >/dev/null 2>&1; then + echo "ERROR: jira CLI is installed but failed to report its version." + echo "Run 'jira init' to configure credentials, then retry." + exit 1 +fi + +if ! jira me >/dev/null 2>&1; then + echo "ERROR: jira CLI is not authenticated." + echo "Run 'jira init' and ensure credentials are valid." + exit 1 +fi + +echo "[jira-cli-skill] Environment check passed."