@mohammadhprp/system-prompt 0.12.1 → 0.12.2

package/framework/skills/jira-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: jira-cli
+description: Expert guidance for using the Jira CLI (jira) to manage Jira issues, sprints, epics, comments, transitions, and worklogs from the command line. Use this skill when the user needs to interact with Jira resources or perform Jira workflows — listing, creating, editing, or transitioning issues, running JQL queries, or scripting against Jira data — even if they don't explicitly mention the jira CLI.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Jira CLI (jira) Skill
+
+Provides guidance for using `jira`, the feature-rich interactive Jira command line, to perform Jira operations from the terminal.
+
+## When to Use This Skill
+
+Invoke when the user needs to:
+- Search, list, or view Jira issues
+- Create, edit, assign, clone, or transition issues
+- Add comments, links, or worklogs to issues
+- Work with epics, sprints, releases, or project boards
+- Run JQL queries or script against Jira data
+
+## Prerequisites
+
+Verify jira installation before executing commands:
+```bash
+jira --version
+```
+
+If not installed, inform the user and provide platform-specific installation guidance.
+
+## Setup Quick Start
+
+`jira` requires one-time initialization before first use:
+
+```bash
+# Interactive setup wizard: installation type (Cloud/Local), auth type, project, board
+jira init
+```
+
+Authentication via environment variables:
+
+```bash
+# Jira Cloud: API token from https://id.atlassian.com/manage-profile/security/api-tokens
+export JIRA_API_TOKEN=your-token
+
+# On-premises with a Personal Access Token
+export JIRA_API_TOKEN=your-token
+export JIRA_AUTH_TYPE=bearer
+```
+
+- Use `jira issue list -c /path/to/config.yaml` or `export JIRA_CONFIG_FILE=/path/to/config.yaml` to work with multiple projects or instances
+- Check authentication and current user: `jira me`
+
+## Core Workflows
+
+### Searching and Viewing Issues
+
+```bash
+# 1. List issues assigned to you (sorted by created, descending)
+jira issue list -a$(jira me) --plain
+
+# 2. Combine filters: high priority, open, created this month, label backend
+jira issue list -yHigh -s"To Do" --created month -lbackend -a$(jira me) --plain
+
+# 3. View issue details with recent comments
+jira issue view ISSUE-1 --comments 5
+```
+
+Filter flags: `-a` assignee, `-r` reporter, `-s` status (prefix `~` for "not"), `-y` priority, `-l` label (repeatable), `-t` type, `-w` watching, `-R` resolution, `--created`/`--updated` with values like `-7d`, `week`, `month`.
+
+> **IMPORTANT:** list commands open an interactive TUI by default. Always pass `--plain` (or `--table`, `--raw`, `--csv`) when running non-interactively, or the command will hang waiting for keyboard input.
+
+### Creating an Issue
+
+```bash
+# 1. Non-interactive creation with all required fields
+jira issue create -tBug -s"New Bug" -yHigh -lbug -b"Bug description" --no-input
+
+# 2. Attach to an epic on creation
+jira issue create -tStory -s"Summary" -PEPIC-42 --no-input
+
+# 3. Body from stdin or template
+echo "Description from stdin" | jira issue create -s"Summary" -tTask --no-input
+jira issue create --template /path/to/template.tmpl -s"Summary" -tTask --no-input
+```
+
+Supports GitHub-flavored and Jira-flavored Markdown in descriptions and comments. Use `--custom "key=value"` for custom fields.
+
+### Editing and Assigning
+
+```bash
+# Edit summary, priority, labels
+jira issue edit ISSUE-1 -s"Updated summary" -yHigh -lbug --no-input
+
+# Prefix minus (-) removes labels, components, or fix versions
+jira issue edit ISSUE-1 --label -p2 --label p1 --fix-version -v1.0 --fix-version v2.0 --no-input
+
+# Assign to a user, to self, to default, or unassign
+jira issue assign ISSUE-1 "Jon Doe"
+jira issue assign ISSUE-1 $(jira me)
+jira issue assign ISSUE-1 default
+jira issue assign ISSUE-1 x
+```
+
+### Transitioning Issues
+
+```bash
+# Move an issue to a new status (name must match the workflow exactly)
+jira issue move ISSUE-1 "In Progress"
+
+# Move with comment, resolution, and assignee
+jira issue move ISSUE-1 Done -RFixed -a$(jira me) --comment "Completed"
+```
+
+### Comments, Links, and Worklogs
+
+```bash
+# Add a comment (positional body, template, or stdin)
+jira issue comment add ISSUE-1 "My comment body"
+
+# Internal (restricted) comment
+jira issue comment add ISSUE-1 "Internal note" --internal
+
+# Link two issues with a link type such as Blocks, Relates, Duplicates
+jira issue link ISSUE-1 ISSUE-2 Blocks
+
+# Add a remote web link
+jira issue link remote ISSUE-1 https://example.com "Example text"
+
+# Log work: time is positional, e.g. "2d 3h 30m"
+jira issue worklog add ISSUE-1 "2d 3h 30m" --comment "Implementation" --no-input
+```
+
+### Sprints and Epics
+
+```bash
+# List issues in the current active sprint
+jira sprint list --current -a$(jira me) --table --plain
+
+# List issues in a specific sprint (get the ID from `jira sprint list`)
+jira sprint list SPRINT_ID -yHigh --table --plain
+
+# Add up to 50 issues to a sprint
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2
+
+# List issues in an epic
+jira epic list EPIC-1 --table --plain
+
+# Create an epic (epic name via -n is required)
+jira epic create -n"Epic epic" -s"Everything" -b"Epic description" --no-input
+
+# Add or remove issues in an epic (up to 50 at once)
+jira epic add EPIC-1 ISSUE-1 ISSUE-2
+jira epic remove ISSUE-1 ISSUE-2
+```
+
+## Common Patterns
+
+### Scripting and Automation
+
+The default view is an interactive UI. For shell pipelines, use machine-friendly output:
+
+```bash
+# Tab-separated plain output with selected columns, no headers
+jira issue list -a$(jira me) --plain --columns key,summary,status --no-headers
+
+# Raw JSON or CSV for parsing
+jira issue list --raw
+jira issue list --csv
+```
+
+### JQL Queries
+
+Execute raw JQL within the configured project context using `-q/--jql`:
+
+```bash
+jira issue list -q "summary ~ cli AND status != Done"
+```
+
+### Working With a Different Project
+
+Use `-p KEY` to target a project other than the one in the config:
+
+```bash
+jira issue list -pXYZ -a$(jira me) --plain
+```
+
+### Navigation Shortcuts (Interactive Mode Only)
+
+In the default TUI: `v` view issue, `m` transition, `ENTER` open in browser, `c` copy URL, `q` quit. Not usable in scripts — use `--plain` instead.
+
+## Best Practices
+
+1. **Verify setup first**: `jira me` confirms auth and config are working
+2. **Always pass `--no-input` with explicit flags** in scripts; interactive prompts will hang
+3. **Use `$(jira me)`** for self-assignment and self-filtering
+4. **Use `--plain --columns ... --no-headers`** for any output you intend to parse
+5. **Match transition names exactly** to the Jira workflow; list interactively first if unsure
+
+## Common Commands Quick Reference
+
+**Issues:**
+- `jira issue list -a$(jira me) --plain` - Your assigned issues
+- `jira issue list -w` - Issues you are watching
+- `jira issue list --history` - Issues you recently interacted with
+- `jira issue create -tBug -s"Summary" -b"Body" --no-input` - Create issue
+- `jira issue view ISSUE-1 --comments 5` - View details
+- `jira issue move ISSUE-1 "In Progress"` - Transition issue
+- `jira issue clone ISSUE-1 -s"New summary"` - Clone with modifications
+- `jira issue delete ISSUE-1 --cascade` - Delete with subtasks
+
+**Epics:**
+- `jira epic list` - List epics
+- `jira epic list EPIC-1` - List issues in an epic
+- `jira epic create -n"Name" -s"Summary" --no-input` - Create epic
+
+**Sprints:**
+- `jira sprint list --current --table --plain` - Current sprint issues
+- `jira sprint list --prev --table --plain` - Previous sprint issues
+- `jira sprint add SPRINT_ID ISSUE-1 ISSUE-2` - Add issues to sprint
+
+**Projects and Boards:**
+- `jira project list` - List accessible projects
+- `jira board list` - List boards in the configured project
+- `jira open ISSUE-1` - Open issue in browser
+- `jira me` - Show current user
+
+## Progressive Disclosure
+
+For detailed command documentation, refer to:
+- **references/commands-detailed.md** - Comprehensive command reference with all flags and options
+- **references/quick-reference.md** - Condensed command cheat sheet
+- **references/troubleshooting.md** - Detailed error scenarios and solutions
+
+Load these references when:
+- User needs specific flag or option details
+- Troubleshooting authentication, config, or permission issues
+- Working with advanced features (JQL, custom fields, multiple configs)
+
+## Common Issues Quick Fixes
+
+**"command not found: jira"** - Install jira-cli or verify PATH
+
+**Auth errors (401/403)** - Check `JIRA_API_TOKEN` is exported; for on-premises PAT auth set `JIRA_AUTH_TYPE=bearer`
+
+**"Please select installation type" / config missing** - Run `jira init` to generate the config
+
+**List command hangs in a script** - The default output is an interactive TUI; add `--plain`
+
+**"Transition not found" or move fails** - Status name must match the workflow exactly; run `jira issue move` without arguments to see valid transitions
+
+**Empty issue lists** - Verify the project/board chosen during `jira init`; try `-p PROJECT_KEY`
+
+For detailed troubleshooting, load **references/troubleshooting.md**.
+
+## Notes
+
+- Works with both Jira Cloud and on-premises (Server/Data Center) installations
+- Supports `basic`, `bearer` (PAT), and `mtls` (client certificates) auth types
+- Sprint lists show only the 25 most recent sprints
+- Descriptions and comments accept GitHub-flavored and Jira-flavored Markdown
+- Shell completion is available via `jira completion --help`

package/framework/skills/jira-cli/references/commands-detailed.md

@@ -0,0 +1,268 @@
+# Jira CLI Detailed Command Reference
+
+Complete flag and option reference for the `jira` CLI. All list flags are POSIX-compliant and combine freely.
+
+## Table of Contents
+
+- [Global Options](#global-options)
+- [Issue List](#issue-list)
+- [Issue Create](#issue-create)
+- [Issue Edit](#issue-edit)
+- [Issue Assign](#issue-assign)
+- [Issue Move (Transition)](#issue-move-transition)
+- [Issue View](#issue-view)
+- [Issue Link / Unlink](#issue-link--unlink)
+- [Issue Clone](#issue-clone)
+- [Issue Delete](#issue-delete)
+- [Issue Comment](#issue-comment)
+- [Issue Worklog](#issue-worklog)
+- [Epic](#epic)
+- [Sprint](#sprint)
+- [Releases, Projects, Boards, Other](#releases-projects-boards-other)
+
+## Global Options
+
+```bash
+jira --version              # Print version
+jira init                   # Interactive config wizard (run once)
+jira me                     # Print the current logged-in user
+jira open [KEY-1]           # Open project or issue in browser
+jira completion --help      # Shell completion setup (Bash/Zsh)
+```
+
+- `-c, --config <file>` — use an alternative config file (or `JIRA_CONFIG_FILE` env var)
+- `-p, --project <KEY>` — override the configured project on list/create commands
+
+## Issue List
+
+```bash
+jira issue list [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `-a, --assignee <user>` | Filter by assignee; `x` = unassigned; use `$(jira me)` for yourself |
+| `-r, --reporter <user>` | Filter by reporter |
+| `-s, --status <status>` | Filter by status; prefix with `~` for "not" (e.g. `-s~Done`) |
+| `-y, --priority <priority>` | Filter by priority (e.g. `High`) |
+| `-t, --type <type>` | Filter by issue type (e.g. `Bug`) |
+| `-l, --label <label>` | Filter by label; repeatable |
+| `-w, --watching` | Issues you are watching |
+| `-R, --resolution <value>` | Filter by resolution (e.g. `"Won't do"`, `Fixed`) |
+| `--history` | Issues you recently interacted with |
+| `--created <value>` | Relative window: `-7d`, `-1h`, `week`, `month` |
+| `--updated <value>` | Same value format as `--created` |
+| `--created-before <value>` | e.g. `-24w` |
+| `--updated-before <value>` | Same format |
+| `-q, --jql <query>` | Raw JQL within the project context |
+| `--order-by <field>` | Order by field (e.g. `rank`, `created`) |
+| `--reverse` | Reverse sort order |
+| `--plain` | Non-interactive table output (use in scripts) |
+| `--table` | Table view for explorer commands (epic/sprint) |
+| `--raw` | Raw JSON output |
+| `--csv` | CSV output |
+| `--columns <list>` | Comma-separated columns to display |
+| `--no-headers` | Omit the header row (for `awk`/parsing) |
+
+Examples:
+
+```bash
+# Assigned to me, high priority, open, created this month
+jira issue list -a$(jira me) -yHigh -sopen --created month
+
+# Unassigned issues created this week
+jira issue list -ax --created week
+
+# Not Done, created before 24 weeks ago, assigned to someone
+jira issue list -s~Done --created-before -24w -a~x
+
+# Issues I reported this week, oldest first
+jira issue list -r$(jira me) --created week --reverse
+```
+
+## Issue Create
+
+```bash
+jira issue create [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `-t, --type <type>` | Issue type (required) |
+| `-s, --summary <text>` | Summary/title (required) |
+| `-b, --body <text>` | Description; supports GitHub- and Jira-flavored Markdown |
+| `-y, --priority <value>` | Priority |
+| `-l, --label <label>` | Label; repeatable |
+| `-P, --parent <KEY>` | Attach to an epic (or parent in next-gen projects) |
+| `--fix-version <value>` | Fix version |
+| `--custom "key=value"` | Set custom fields; repeatable |
+| `--template <file\|->` | Load description from file or stdin |
+| `--no-input` | Skip all interactive prompts |
+
+```bash
+# Minimal non-interactive creation
+jira issue create -tTask -s"Summary" -b"Description" --no-input
+
+# Description piped from stdin
+echo "Description" | jira issue create -s"Summary" -tTask --no-input
+
+# Story attached to EPIC-42 with labels and fix version
+jira issue create -tStory -s"Summary" -PEPIC-42 -lbackend --fix-version v2.0 --no-input
+```
+
+## Issue Edit
+
+```bash
+jira issue edit ISSUE-1 [flags]
+```
+
+Accepts the same field flags as create (`-s`, `-b`, `-y`, `-l`, `-C` component, `--fix-version`). Prefix a value with `-` to remove it:
+
+```bash
+# Remove label p2, add p1; swap fix version v1.0 for v2.0
+jira issue edit ISSUE-1 --label -p2 --label p1 --fix-version -v1.0 --fix-version v2.0 --no-input
+```
+
+## Issue Assign
+
+```bash
+jira issue assign ISSUE-1 <user>
+jira issue assign ISSUE-1 $(jira me)   # assign to self
+jira issue assign ISSUE-1 default      # default assignee
+jira issue assign ISSUE-1 x            # unassign
+```
+
+A partial name ("suffix") may prompt for selection if it matches multiple users.
+
+## Issue Move (Transition)
+
+```bash
+jira issue move ISSUE-1 <status> [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--comment <text>` | Comment added during the transition (workflow must allow it) |
+| `-R, --resolution <value>` | Set resolution while moving (e.g. `Fixed`) |
+| `-a, --assignee <user>` | Reassign while moving |
+
+```bash
+jira issue move ISSUE-1 "In Progress"
+jira issue move ISSUE-1 Done -RFixed -a$(jira me) --comment "Completed"
+```
+
+The status name must match the workflow exactly (case-sensitive). Run `jira issue move` with no arguments to pick from valid transitions interactively.
+
+## Issue View
+
+```bash
+jira issue view ISSUE-1 [--comments <n>]
+```
+
+Renders the description as Markdown in the terminal (pager: `less` by default). `--comments 5` shows the 5 most recent comments.
+
+## Issue Link / Unlink
+
+```bash
+jira issue link ISSUE-1 ISSUE-2 <link-type>   # e.g. Blocks, Relates, Duplicates
+jira issue unlink ISSUE-1 ISSUE-2
+jira issue link remote ISSUE-1 <url> "<text>" # add a remote web link
+```
+
+## Issue Clone
+
+```bash
+jira issue clone ISSUE-1 [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `-s, -y, -a, -l, -C` | Override summary, priority, assignee, labels, components on the clone |
+| `-H, --replace "find:replace"` | Case-sensitive text replacement in summary and description |
+
+```bash
+jira issue clone ISSUE-1 -s"Modified summary" -yHigh -a$(jira me)
+jira issue clone ISSUE-1 -H"find me:replace with me"
+```
+
+## Issue Delete
+
+```bash
+jira issue delete ISSUE-1 [--cascade]
+```
+
+`--cascade` also deletes all subtasks.
+
+## Issue Comment
+
+```bash
+jira issue comment add ISSUE-1 "Comment body" [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--internal` | Mark as an internal (restricted) comment |
+| `--template <file\|->` | Load comment from file or stdin |
+
+```bash
+echo "Comment from stdin" | jira issue comment add ISSUE-1
+```
+
+The positional body takes precedence over `--template` when both are given.
+
+## Issue Worklog
+
+```bash
+jira issue worklog add ISSUE-1 "<time>" [flags]
+```
+
+Time is positional and accepts values like `"10m"`, `"2h"`, `"2d 3h 30m"`.
+
+```bash
+jira issue worklog add ISSUE-1 "2d 3h 30m" --comment "Implementation" --no-input
+```
+
+## Epic
+
+```bash
+jira epic list [EPIC-KEY] [issue-list-flags]   # list epics, or issues in an epic
+jira epic list EPIC-1 -ax -yHigh --table --plain
+jira epic create -n"Epic name" -s"Summary" -yHigh -lbug -b"Description" --no-input
+jira epic add EPIC-1 ISSUE-1 ISSUE-2           # up to 50 issues at once
+jira epic remove ISSUE-1 ISSUE-2               # up to 50 issues at once
+```
+
+`epic list` supports all `issue list` filter flags except issue type. `epic create` requires `-n/--name`.
+
+## Sprint
+
+```bash
+jira sprint list [SPRINT_ID] [flags]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--current` | Issues in the current active sprint |
+| `--prev` | Issues in the previous sprint |
+| `--next` | Issues in the next planned sprint |
+| `--state <list>` | e.g. `future,active` |
+| `--table` | Table view (default is explorer) |
+
+```bash
+jira sprint list --current -a$(jira me) --table --plain
+jira sprint list --state future,active --table --plain
+jira sprint list SPRINT_ID -yHigh --table --plain   # all issue filters supported
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2           # up to 50 issues at once
+```
+
+Only the 25 most recent sprints are shown. Get sprint IDs from `jira sprint list`.
+
+## Releases, Projects, Boards, Other
+
+```bash
+jira release list [--project KEY]   # project versions; feature must be enabled on the instance
+jira project list                   # all accessible projects
+jira board list                     # boards in the configured project
+jira open                           # open project in browser
+jira open ISSUE-1                   # open issue in browser
+```

package/framework/skills/jira-cli/references/quick-reference.md

@@ -0,0 +1,111 @@
+# Jira CLI Quick Reference
+
+Condensed cheat sheet. Use `--plain` (or `--table`, `--raw`, `--csv`) and `--no-input` when running non-interactively.
+
+## Setup
+
+```bash
+jira init                  # one-time config wizard (Cloud/Local, auth, project, board)
+export JIRA_API_TOKEN=...  # Jira Cloud API token
+export JIRA_AUTH_TYPE=bearer  # only for on-premises PAT auth
+jira me                    # verify auth and current user
+```
+
+## List Issues
+
+```bash
+jira issue list --plain
+jira issue list -a$(jira me) --plain                          # assigned to me
+jira issue list -r$(jira me) --created week --plain           # reported by me this week
+jira issue list -w --plain                                    # watching
+jira issue list --history                                     # recently interacted
+jira issue list -yHigh -s"To Do" --created month -lbackend --plain
+jira issue list -ax --created week --plain                    # unassigned
+jira issue list -s~Done --plain                               # status is not Done
+jira issue list -q "summary ~ cli" --plain                    # raw JQL
+```
+
+Filter flags: `-a` assignee (`x` = unassigned), `-r` reporter, `-s` status (`~` = not), `-y` priority, `-l` label (repeatable), `-t` type, `-w` watching, `-R` resolution, `--created`/`--updated` (`-7d`, `-1h`, `week`, `month`), `--created-before`/`--updated-before`, `--order-by <field> --reverse`.
+
+## Output Modes
+
+```bash
+jira issue list --plain --columns key,summary,status --no-headers   # TSV, no header
+jira issue list --raw        # JSON
+jira issue list --csv        # CSV
+```
+
+## Create / Edit / Assign
+
+```bash
+jira issue create -tBug -s"Summary" -b"Body" -yHigh -lbug --no-input
+jira issue create -tStory -s"Summary" -PEPIC-42 --no-input              # attach to epic
+echo "Body" | jira issue create -s"Summary" -tTask --no-input           # body via stdin
+jira issue edit ISSUE-1 -s"New summary" --no-input
+jira issue edit ISSUE-1 --label -p2 --label p1 --no-input               # "-" removes
+jira issue assign ISSUE-1 "Jon Doe"
+jira issue assign ISSUE-1 $(jira me)                                    # self
+jira issue assign ISSUE-1 default                                       # default assignee
+jira issue assign ISSUE-1 x                                             # unassign
+```
+
+## Transition
+
+```bash
+jira issue move ISSUE-1 "In Progress"
+jira issue move ISSUE-1 Done -RFixed -a$(jira me) --comment "Done"
+```
+
+Status name must match the workflow exactly.
+
+## Comments / Links / Worklog
+
+```bash
+jira issue comment add ISSUE-1 "Comment body"
+jira issue comment add ISSUE-1 "Internal note" --internal
+jira issue link ISSUE-1 ISSUE-2 Blocks
+jira issue unlink ISSUE-1 ISSUE-2
+jira issue link remote ISSUE-1 https://example.com "Example text"
+jira issue worklog add ISSUE-1 "2d 3h 30m" --comment "Note" --no-input
+```
+
+## Clone / Delete
+
+```bash
+jira issue clone ISSUE-1 -s"New summary" -a$(jira me)
+jira issue clone ISSUE-1 -H"find:replace"          # replace text in summary/description
+jira issue delete ISSUE-1 --cascade                # also deletes subtasks
+```
+
+## Epics
+
+```bash
+jira epic list --table --plain
+jira epic list EPIC-1 --table --plain              # issues in an epic
+jira epic create -n"Name" -s"Summary" -b"Body" --no-input
+jira epic add EPIC-1 ISSUE-1 ISSUE-2               # up to 50
+jira epic remove ISSUE-1 ISSUE-2                   # up to 50
+```
+
+## Sprints
+
+```bash
+jira sprint list --current --table --plain
+jira sprint list --prev --table --plain
+jira sprint list --next --table --plain
+jira sprint list --state future,active --table --plain
+jira sprint list SPRINT_ID -yHigh --table --plain  # issue filters work here too
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2          # up to 50
+```
+
+## Projects, Boards, Misc
+
+```bash
+jira project list
+jira board list
+jira release list --project KEY
+jira open ISSUE-1          # open in browser
+jira me                    # current user
+jira issue list -pXYZ ...  # override configured project
+jira issue list -c ./config.yaml ...   # alternative config file
+```