Skip to content

Commit 851a0c4

Browse files
schultzp2020schultzp2020
authored
Merge pull request #13 from schultzp2020/feat/rhdh-jira-skill
feat: add rhdh-jira skill for Jira interaction via acli
2 parents 5457f0e + c790955 commit 851a0c4

9 files changed

Lines changed: 1658 additions & 0 deletions

File tree

‎skills/rhdh-jira/SKILL.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
name: rhdh-jira
3+
description: |
4+
Interact with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using the Atlassian CLI (acli). Use when the user needs to search, create, view, edit, transition, comment on, or link Jira issues for Red Hat Developer Hub. Also use when the user asks about Jira workflows, exit criteria, issue templates, custom fields, boards, sprints, or JQL queries in the RHDH context. Trigger when the user mentions Jira issue keys like RHIDP-1234, RHDHPLAN-567, RHDHBUGS-890, or any RHDH project key. Also trigger for support case bug filing, feature request creation, or release planning in Jira. Covers acli setup, authentication, and troubleshooting.
5+
compatibility: "acli (Atlassian CLI) on PATH. Python 3 for scripts. Windows, macOS, Linux."
6+
---
7+
8+
# RHDH Jira
9+
10+
Foundational skill for interacting with RHDH's Jira instance via the Atlassian CLI (`acli`). Covers all four active projects, issue types, workflows, custom fields, and JQL patterns.
11+
12+
## Prerequisites
13+
14+
Run `scripts/setup.py` to verify everything is configured:
15+
16+
```bash
17+
python scripts/setup.py
18+
```
19+
20+
The script checks:
21+
1. `acli` binary on PATH
22+
2. Jira API token auth configured (`~/.config/acli/jira_config.yaml`)
23+
3. Smoke test against `redhat.atlassian.net`
24+
25+
If `acli` is not installed, download from [Atlassian CLI](https://developer.atlassian.com/cloud/acli/). Authenticate with `acli auth login` or configure an API token.
26+
27+
## Scripts
28+
29+
| Script | Purpose |
30+
|--------|---------|
31+
| `scripts/setup.py` | Verify acli install + auth. Run with `--json` for structured output. |
32+
| `scripts/parse_issues.py` | Flatten, enrich, and filter acli JSON output. Solves the core problem: `acli search --json` can't return custom fields (team, story points, sprint). Pipe search results in, get clean data out. Use `--enrich` to fetch full fields, `-f team="X"` to filter by team. |
33+
34+
## Projects
35+
36+
| Key | Purpose | Issue Types |
37+
|-----|---------|-------------|
38+
| RHIDP | Engineering work | Epic, Story, Task, Sub-task, Vulnerability |
39+
| RHDHPLAN | Program planning | Feature, Outcome, Feature Request, Sub-task |
40+
| RHDHBUGS | Product defects | Bug, Sub-task |
41+
| RHDHSUPP | Support-engineering interactions | Bug |
42+
43+
RHDHPAI (Plugins and AI) is **archived** — JQL queries against it will fail.
44+
45+
### Issue type selection
46+
47+
- **Story** — end-user facing work (API, UI changes)
48+
- **Task** — not end-user facing (tests, CI/CD, refactoring, code organization)
49+
- **Epic** — collection of Stories/Tasks toward a deliverable
50+
- **Feature** — program-level planning item in RHDHPLAN
51+
- **Bug** — product defect (RHDHBUGS) or support case tracking (RHDHSUPP)
52+
- **Sub-task** — child of any issue type above
53+
- **Vulnerability** — CVE tracking in RHIDP (Product Security)
54+
55+
## Reference Files
56+
57+
Load only what the current task requires.
58+
59+
| File | Load when... |
60+
|------|-------------|
61+
| `references/acli-commands.md` | Running an acli command you haven't used before, or hitting unexpected flag behavior. Quick reference for syntax, flag differences, and output formats. |
62+
| `references/fields.md` | Need to know a field name, custom field ID, accepted values, or label conventions. Custom fields, labels, link types, components, priorities. |
63+
| `references/workflows.md` | Transitioning issues, checking exit criteria, or verifying readiness for the next status. |
64+
| `references/templates.md` | Creating new issues. Also load `references/workflows.md` for required fields at entry status. |
65+
| `references/support.md` | Handling support cases, filing bugs from customer cases, or creating feature requests from support. |
66+
| `references/jql-patterns.md` | Building a JQL query, finding a board ID, or looking up sprint information. JQL cookbook with 23+ tested queries. |
67+
68+
## Common Gotchas
69+
70+
1. **`acli auth status` lies.** It checks OAuth, not API token auth. Always returns "unauthorized" with token auth even when Jira works fine. Use `acli jira project list --recent 1` as a smoke test instead.
71+
2. **`view` uses positional arg, everything else uses `--key`.** `acli jira workitem view RHIDP-123` but `acli jira workitem edit --key RHIDP-123 ...`.
72+
3. **`--yes` is mandatory for mutations.** All `edit`, `transition`, `assign`, and `link create` commands prompt interactively without it. Always pass `--yes`.
73+
4. **`--fields` is restrictive on search.** Only accepts `key`, `summary`, `status`, `assignee`, `issuetype`, `priority`, `description`, `labels`. For components, sprint, fixVersions, and all custom fields — use `--json` or `scripts/parse_issues.py --enrich`.
74+
5. **Team field is NOT JQL-filterable.** `customfield_10001` cannot be used in JQL WHERE clauses. Fetch all issues, filter by `customfield_10001.name` in post-processing.
75+
6. **ADF vs plain text.** Reading descriptions via `--json` returns Atlassian Document Format (nested JSON). Creating/editing with `--description` accepts plain text. Don't try to round-trip ADF through `--description`.
76+
7. **Acceptance Criteria field is almost always null.** Scan the description for "Requirements", "Acceptance Criteria", or bullet-style criteria instead of checking `customfield_10718`.
77+
78+
## Error Handling
79+
80+
| Error | Action |
81+
|-------|--------|
82+
| `acli` not on PATH | Run `scripts/setup.py`. Install from Atlassian if missing. |
83+
| "unauthorized" from `auth status` | Ignore. Check `jira_config.yaml` exists. Run smoke test. |
84+
| "required flag(s) not set" | Command syntax wrong. Run `acli jira <subcommand> --help`. |
85+
| "field X is not allowed" | Use `--json` instead of `--fields` for that field. |
86+
| "the value X does not exist for the field 'project'" | Project key is wrong or project is archived (e.g., RHDHPAI). |
87+
| Rate limiting (429) | Wait 5 seconds, retry once. |
88+
| Interactive prompt hangs | Missing `--yes` flag on a mutating command. |
89+
90+
## Common Workflows
91+
92+
### Creating an issue
93+
1. Load `references/templates.md` for the body template
94+
2. Load `references/workflows.md` for required fields at New status
95+
3. Run `acli jira workitem create` (see `references/acli-commands.md` if unsure of syntax)
96+
97+
### Searching with custom fields (team, story points, sprint)
98+
1. Build JQL using patterns from `references/jql-patterns.md`
99+
2. Pipe results through `scripts/parse_issues.py --enrich` for full field data
100+
3. Use `-f team="X"` to filter by team (not possible in JQL)
101+
102+
### Transitioning an issue
103+
1. Load `references/workflows.md` for exit criteria at the target status
104+
2. Verify required fields are set before transitioning
105+
3. Run `acli jira workitem transition --key KEY --status "X" --yes`
106+
107+
## When NOT to Use
108+
109+
- **Non-RHDH Jira projects** — this skill's field mappings, workflows, and JQL patterns are specific to RHIDP/RHDHPLAN/RHDHBUGS/RHDHSUPP
110+
- **Jira REST API directly** — this skill covers `acli` CLI only

‎skills/rhdh-jira/references/acli-commands.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# acli Jira Command Reference
2+
3+
Cheat sheet for `acli jira` commands. For full flag details, run `acli jira <subcommand> --help`.
4+
5+
## Key Syntax Rules
6+
7+
1. **`view` takes a positional arg.** Everything else uses `--key`.
8+
2. **Always pass `--yes`** on mutating commands (`edit`, `transition`, `assign`, `link create`) to skip interactive prompts.
9+
3. **Use `--json`** when you need fields beyond `key`, `summary`, `status`, `assignee`, `issuetype`, `priority`, `description`. The `--fields` flag rejects `components`, `sprint`, `labels`, `fixVersions`.
10+
4. **Use `--csv`** for search results you want to pipe or parse.
11+
5. **Use `--paginate`** to fetch all results beyond the default page size.
12+
13+
## Work Items
14+
15+
### Search
16+
17+
```bash
18+
# JQL search with field selection
19+
acli jira workitem search --jql "project = RHIDP AND status = 'In Progress'" --fields "key,summary,status,assignee" --limit 50
20+
21+
# JSON output for full field data
22+
acli jira workitem search --jql "project = RHIDP" --limit 20 --json
23+
24+
# Count only
25+
acli jira workitem search --jql "project = RHDHBUGS AND status not in (Closed)" --count
26+
27+
# CSV export
28+
acli jira workitem search --jql "project = RHIDP" --fields "key,summary,status" --csv
29+
30+
# Fetch all results (paginated)
31+
acli jira workitem search --jql "project = RHIDP AND sprint in openSprints()" --paginate
32+
```
33+
34+
### View
35+
36+
```bash
37+
# View issue (positional arg — NOT --key)
38+
acli jira workitem view RHIDP-123
39+
40+
# Specific fields
41+
acli jira workitem view RHIDP-123 --fields "summary,description,status"
42+
43+
# All fields
44+
acli jira workitem view RHIDP-123 --fields "*all"
45+
46+
# JSON for full data (components, sprint, custom fields)
47+
acli jira workitem view RHIDP-123 --json
48+
49+
# Open in browser
50+
acli jira workitem view RHIDP-123 --web
51+
```
52+
53+
### Create
54+
55+
```bash
56+
# Basic creation
57+
acli jira workitem create --project RHIDP --type Story --summary "Implement auth plugin" --description "As a user..." --assignee "@me"
58+
59+
# With labels
60+
acli jira workitem create --project RHDHBUGS --type Bug --summary "Login fails" --label "rhdh-customer,ci-fail"
61+
62+
# With parent (sub-task or child of epic)
63+
acli jira workitem create --project RHIDP --type Task --summary "Write tests" --parent RHIDP-12968
64+
65+
# From JSON file (complex issues)
66+
acli jira workitem create --from-json workitem.json --project RHIDP --type Epic
67+
68+
# Generate JSON template
69+
acli jira workitem create --generate-json
70+
71+
# From description file
72+
acli jira workitem create --project RHIDP --type Story --summary "New feature" --description-file story.txt
73+
```
74+
75+
### Edit
76+
77+
```bash
78+
# Edit summary (--key flag, NOT positional)
79+
acli jira workitem edit --key RHIDP-123 --summary "Updated summary" --yes
80+
81+
# Edit multiple issues
82+
acli jira workitem edit --key "RHIDP-123,RHIDP-124" --assignee "jdoe@example.com" --yes
83+
84+
# Edit by JQL (batch)
85+
acli jira workitem edit --jql "project = RHIDP AND labels = 'needs-info'" --labels "needs-pm" --yes
86+
87+
# Add/remove labels
88+
acli jira workitem edit --key RHIDP-123 --labels "demo,test-day" --yes
89+
acli jira workitem edit --key RHIDP-123 --remove-labels "needs-info" --yes
90+
91+
# Edit description from file
92+
acli jira workitem edit --key RHIDP-123 --description-file updated.txt --yes
93+
94+
# Edit issue type
95+
acli jira workitem edit --key RHIDP-123 --type Task --yes
96+
```
97+
98+
### Transition
99+
100+
```bash
101+
# Move to status (--key flag)
102+
acli jira workitem transition --key RHIDP-123 --status "In Progress" --yes
103+
104+
# Batch transition by JQL
105+
acli jira workitem transition --jql "project = RHIDP AND status = 'Review'" --status "Closed" --yes
106+
107+
# Ignore errors on batch (some may not have valid transition)
108+
acli jira workitem transition --jql "..." --status "To Do" --yes --ignore-errors
109+
```
110+
111+
### Assign
112+
113+
```bash
114+
# Assign to self
115+
acli jira workitem assign --key RHIDP-123 --assignee "@me" --yes
116+
117+
# Assign to user
118+
acli jira workitem assign --key RHIDP-123 --assignee "jdoe@example.com" --yes
119+
120+
# Assign to project default
121+
acli jira workitem assign --key RHIDP-123 --assignee "default" --yes
122+
```
123+
124+
### Comment
125+
126+
```bash
127+
# Add comment
128+
acli jira workitem comment create --key RHIDP-123 --body "Investigation complete. Root cause: ..."
129+
130+
# List comments
131+
acli jira workitem comment list --key RHIDP-123
132+
133+
# Update comment
134+
acli jira workitem comment update --key RHIDP-123 --id 12345 --body "Updated findings"
135+
136+
# Delete comment
137+
acli jira workitem comment delete --key RHIDP-123 --id 12345
138+
```
139+
140+
### Links
141+
142+
```bash
143+
# List available link types
144+
acli jira workitem link type
145+
146+
# Create link (--out = source, --in = target)
147+
acli jira workitem link create --out RHIDP-123 --in RHIDP-456 --type "Blocks" --yes
148+
149+
# List links on an issue
150+
acli jira workitem link list --key RHIDP-123
151+
152+
# Delete link (by link ID only, no --key needed)
153+
acli jira workitem link delete --id 12345 --yes
154+
```
155+
156+
### Attachments
157+
158+
```bash
159+
# List attachments (note: attachment upload is not available via acli)
160+
acli jira workitem attachment list --key RHIDP-123
161+
162+
# Delete attachment
163+
acli jira workitem attachment delete --key RHIDP-123 --id 12345
164+
```
165+
166+
## Boards
167+
168+
```bash
169+
# Search boards by project
170+
acli jira board search --project RHIDP
171+
172+
# Search by name
173+
acli jira board search --name "RHDH Cope"
174+
175+
# Get board details
176+
acli jira board get --id 11374
177+
178+
# List sprints for a board (--id, NOT --board-id)
179+
acli jira board list-sprints --id 11374
180+
181+
# Active sprints only
182+
acli jira board list-sprints --id 11374 --state active
183+
```
184+
185+
## Sprints
186+
187+
```bash
188+
# View sprint details
189+
acli jira sprint view --id 65456
190+
191+
# List work items in a sprint
192+
acli jira sprint list-workitems --sprint 65456 --board 11374
193+
194+
# Create sprint
195+
acli jira sprint create --name "RHDH COPE 3292" --board 11374
196+
```
197+
198+
## Projects
199+
200+
```bash
201+
# List recent projects
202+
acli jira project list --recent 10
203+
204+
# View project details
205+
acli jira project view --key RHIDP
206+
```
207+
208+
## Filters
209+
210+
```bash
211+
# Search for saved filters
212+
acli jira filter search --name "RHDH"
213+
214+
# List my/favourite filters
215+
acli jira filter list --my
216+
acli jira filter list --favourite
217+
218+
# Get filter details (includes JQL)
219+
acli jira filter get --id 10001
220+
```
221+
222+
## Output Format Differences
223+
224+
| Behavior | Table (default) | `--json` |
225+
|----------|----------------|----------|
226+
| Description | Plain text | ADF (Atlassian Document Format) |
227+
| Team field | String name | Complex object `{id, name, avatarUrl, ...}` |
228+
| Sprint field | Not shown | Array of sprint objects |
229+
| Components | Not available via `--fields` | Full objects |
230+
| Labels | Not available via `--fields` | Array of strings |
231+
| Fix versions | Not available via `--fields` | Array of version objects |
232+
233+
When writing descriptions, use `--description "plain text"`. When reading, be aware `--json` returns ADF — don't try to round-trip it.

0 commit comments

Comments
 (0)