Help us improve
Share bugs, ideas, or general feedback.
From rhdh
Manages RHDH Jira projects via Atlassian CLI: create, assign, refine, plan sprints, and track releases. Triggered by Jira keys, issue creation requests, or sprint ceremony commands.
npx claudepluginhub redhat-developer/rhdh-skill --plugin rhdhHow this skill is triggered — by the user, by Claude, or both
Slash command
/rhdh:rhdh-jiraThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<essential_principles>
assets/examples/bug-example.txtassets/examples/epic-example.txtassets/examples/feature-example.txtassets/examples/story-example.txtassets/examples/task-example.txtassets/templates/bug.txtassets/templates/epic.txtassets/templates/feature.txtassets/templates/story.txtassets/templates/task.txtreferences/acli-commands.mdreferences/assign.mdreferences/auth.mdreferences/duplicates.mdreferences/feature-exploration.mdreferences/fields.mdreferences/graphql-queries.mdreferences/grill.mdreferences/jql-patterns.mdreferences/plan.mdReferences Atlassian CLI (acli) commands for Jira: authenticate, create/view/edit issues, JQL searches, bulk operations, project/board/sprint management.
JIRA automation hub routing to 13 specialized skills for any JIRA task: issues, workflows, agile, search, time tracking, service management, and more.
Automates Jira tasks via Rube MCP (Composio): search issues with JQL, create/edit issues, manage projects/sprints/boards/comments/users. Requires Rube MCP and Jira OAuth setup.
Share bugs, ideas, or general feedback.
<essential_principles>
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.
</essential_principles>
| Command | Description | Reference |
|---|---|---|
assign [issue key(s) or JQL] | Recommend and assign team members using expertise, capacity, and context proximity analysis | references/assign.md |
refine [issue key(s), JQL, or 'sprint'] | Check issues against exit criteria, identify duplicates, missing fields, unaddressed comments, and readiness | references/refine.md |
plan [team] | Sprint planning prep: carryover, velocity, capacity, ready queue, sprint fill suggestions | references/plan.md |
sprint-report [team] | Sprint review summary: committed vs completed, per-member breakdown, demo checklist | references/sprint-report.md |
release [version] | Release readiness: feature matrix, PI funnel, dependency map, blocker bugs, risk assessment | references/release.md |
to-feature [description] | Create a RHDHPLAN Feature with grill, duplicate check, and optional Epic decomposition | references/to-feature.md |
to-epic [description] | Create an RHIDP Epic with grill, duplicate check, and optional Story/Task decomposition | references/to-epic.md |
to-issue [description] | Create a Story, Task, Bug, or Spike with automatic type inference and grill | references/to-issue.md |
update-jira-status [key] | Update issue with session progress, status comment, transition, and upward cascade | references/update-jira-status.md |
Single source of truth for command descriptions: scripts/command-metadata.json
Wait for response before proceeding.
Run scripts/setup.py to verify everything is configured:
python scripts/setup.py
The script checks:
acli binary on PATH~/.config/acli/jira_config.yaml).jira-token file next to acli executable (for REST API fallback)redhat.atlassian.netIf acli is not installed, download from Atlassian CLI and follow the Getting Started guide for installation and authentication setup. Use API token authentication, not OAuth — OAuth sessions expire and acli auth status gives false negatives with token auth (see Gotchas).
All operations follow this priority: acli → GraphQL → REST API.
Sub-commands (assign, refine) document which API they use. When a sub-command's workflow already has AUTH set from GraphQL reads, prefer REST for writes.
Before attempting any REST API or GraphQL call:
python scripts/setup.py --json and check token_file_found.jira-token not configured. Run setup.py for instructions." Continue with acli-only workflow.references/auth.md for setup instructions| Script | Purpose |
|---|---|
scripts/setup.py | Verify acli install + auth. Run with --json for structured output. |
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. |
scripts/command-metadata.json | Single source of truth for sub-command descriptions and argument hints. |
scripts/validate_components.py | Validate references/fields.md component catalog against live Jira projects (RHIDP + RHDHPLAN). Reports drift in both directions. Run with --json for structured output. |
| Key | Purpose | Issue Types |
|---|---|---|
| RHIDP | Engineering work | Epic, Story, Task, Sub-task, Vulnerability |
| RHDHPLAN | Program planning | Feature, Outcome, Feature Request, Sub-task |
| RHDHBUGS | Product defects | Bug, Sub-task |
| RHDHSUPP | Support-engineering interactions | Bug |
RHDHPAI (Plugins and AI) is archived — JQL queries against it will fail.
<reference_index>
Load only what the current task requires.
| File | Load when... |
|---|---|
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. |
references/fields.md | Need to know a field name, custom field ID, accepted values, or label conventions. Custom fields, labels, link types, components, priorities. |
references/workflows.md | Transitioning issues, checking exit criteria, or verifying readiness for the next status. |
references/templates.md | Creating new issues. Also load references/workflows.md for required fields at entry status. |
references/support.md | Handling support cases, filing bugs from customer cases, or creating feature requests from support. Full RHDHSUPP workflow, SLA, and anti-patterns. |
references/feature-exploration.md | Feature Exploration Process checklist: component validation, labels (demo, rhdh-testday), Doc Epic automation, cross-team dependencies, rescoping. Load when creating Features, refining Features, or checking Feature readiness. |
references/jql-patterns.md | Building a JQL query, finding a board ID, or looking up sprint information. JQL cookbook with 23+ tested queries. |
references/auth.md | Setting up authentication for REST API or GraphQL calls. Token file format, path discovery, security, instance config, common auth errors. |
references/rest-api-fallback.md | acli failed to update a custom field (Team, Size, Story Points, Release Note Type). Curl examples, response handling, OpenAPI spec discovery. |
references/graphql-queries.md | Complex read queries needing multiple fields, relationships, or custom field data in one call. Schema introspection, JQL search via GraphQL, field type fragments. Also for bulk operations where acli would be too slow. |
references/assign.md | Recommending assignees for unassigned issues. Team roster lookup, expertise profiling, sprint capacity analysis, context proximity scoring. Also for applying assignments after user confirmation. |
references/refine.md | Checking issues against exit criteria per status, identifying duplicates, missing fields, unaddressed comments, and readiness for the next workflow status. |
references/plan.md | Sprint planning prep: carryover report, velocity trend, per-member capacity, ready-for-planning queue, sprint fill suggestions. |
references/sprint-report.md | Sprint review summary: committed vs completed, per-member breakdown, epic progress, demo checklist with naming conventions, velocity trend. |
references/release.md | Release readiness report: feature matrix, PI funnel states, epic roll-up, cross-team dependency map, blocker bugs, RN readiness, risk assessment. |
references/to-feature.md | Create a RHDHPLAN Feature from conversation context with grill and optional Epic decomposition. |
references/to-epic.md | Create an RHIDP Epic from conversation context with grill and optional Story/Task decomposition. |
references/to-issue.md | Create a Story, Task, Bug, or Spike with automatic type inference and grill. |
references/update-jira-status.md | Update a Jira issue with session progress, status comment, transitions, and upward cascade to parent Epic/Feature. |
references/duplicates.md | Duplicate detection for pre-creation checks and refinement audits. Shared across creation commands and refine. |
references/grill.md | Shared challenging behavior for issue creation grills: sizing, completeness, scope, risks, cross-referencing. |
references/sizing.md | T-shirt sizing guide for Features/Epics and Fibonacci story points for Stories/Tasks. Used during grills and refinement. |
</reference_index>
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.view uses positional arg, everything else uses --key. acli jira workitem view RHIDP-123 but acli jira workitem edit --key RHIDP-123 ....--yes is mandatory for mutations. All edit, transition, assign, and link create commands prompt interactively without it. Always pass --yes.--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.customfield_10001 cannot be used in JQL WHERE clauses. However, "Team[Team]" = {teamId} (using the team UUID, not display name) works. Use the UUID syntax for JQL filtering; use customfield_10001.name in post-processing only when you need the display name from JSON output.--json returns Atlassian Document Format (nested JSON). Creating/editing with --description accepts plain text. Don't try to round-trip ADF through --description.customfield_10718.--enrich is MANDATORY for custom fields AND labels. Both acli search --json and acli view KEY --json (without --fields "*all") return only basic fields (assignee, issuetype, priority, status, summary). Labels, story points, team, sprint, size, and components will all appear as empty/null — looking like the data isn't set when it actually is. Always use scripts/parse_issues.py --enrich to get custom field data. Skipping --enrich is the #1 cause of false "missing data" reports.acli cannot set arbitrary custom fields. acli jira workitem edit does not have a --custom flag. Fields like Team, Size, Story Points, and Release Note Type can only be updated via the Jira REST API. Use PUT /rest/api/3/issue/{key} with the field payload (see references/rest-api-fallback.md for curl examples and payload formats). Find the token file at .jira-token next to the acli executable (discover the path with readlink -f "$(which acli)" or where acli). Never read the token file into context.acli sprint list-workitems --json wraps results in {"issues": [...]}. The output is NOT a flat array — it's an object with an issues key. Extract the array before piping to parse_issues.py. See references/acli-commands.md for the workaround command.issueSearchStable requires X-ExperimentalApi: JiraIssueSearch header. Load references/graphql-queries.md before attempting GraphQL queries..jira-token format is email:token, not bare token. A file containing only the API token without the email prefix will cause 401 errors on REST/GraphQL calls. The setup.py script validates the format.acli search silently truncates results. The default page size is 30. If your JQL matches more than 30 issues, you get the first 30 with no warning. Always pass --limit 200 for bulk queries, or use --count first to check the total, then --paginate to fetch all pages. This is the #2 cause of incorrect reports after skipping --enrich.rhdh-X.Y-candidate labels. Candidate labels track release targeting. Removing them without PM approval can silently drop a feature from release tracking.Parent Link field (customfield_10018), not issuelinks. To find child Epics of a Feature, use JQL: project = RHIDP AND type = Epic AND "Parent Link" = RHDHPLAN-XXX. Checking issuelinks will show zero results and produce false "no child Epics" reports./rest/api/3/search returns 410 Gone. This endpoint has been removed. Use POST to /rest/api/3/search/jql with body {"jql": "...", "fields": [...], "maxResults": N} instead. This only affects direct REST calls — acli search still works.| Error | Action |
|---|---|
acli not on PATH | Run scripts/setup.py. Install from Atlassian if missing. See Getting Started. |
"unauthorized" from auth status | Ignore. Check jira_config.yaml exists. Run smoke test. |
| "required flag(s) not set" | Command syntax wrong. Run acli jira <subcommand> --help. |
| "field X is not allowed" | Use --json instead of --fields for that field. |
| "the value X does not exist for the field 'project'" | Project key is wrong or project is archived (e.g., RHDHPAI). |
| Rate limiting (429) | Wait 5 seconds, retry once. |
| Interactive prompt hangs | Missing --yes flag on a mutating command. |
Custom field update fails via acli | Fall back to Jira REST API using .jira-token file. See Gotcha #9. |
issueSearchStable returns errors | Fall back to acli search (not REST — /rest/api/3/search returns 410 Gone on this instance). Warn that the beta API failed. |
These apply across all sub-commands:
"Apply changes? [y/N/edit]" — y applies all, N cancels, edit steps through each change individually.Won't Do, Duplicate, Done). Preserves the decision trail.Sub-commands share data.
planreuses roster/capacity/expertise fromassign.sprint-reportuses the same velocity query pattern asplan.releasereferences exit criteria fromworkflows.mdand can invokeassignfor unassigned Features.
references/templates.md for the body templatereferences/workflows.md for required fields at New statusacli jira workitem create (see references/acli-commands.md if unsure of syntax)references/jql-patterns.mdscripts/parse_issues.py --enrich for full field data-f team="X" to filter by team (not possible in JQL)references/workflows.md for exit criteria at the target statusacli jira workitem transition --key KEY --status "X" --yesreferences/graphql-queries.mdissueByKey for single issues or issueSearchStable (beta) for JQL searchacli + parse_issues.py --enrich if GraphQL returns errorsreferences/assign.mdreferences/refine.mdsprint, or backlog)references/plan.mdreferences/sprint-report.mdreferences/release.mdto-feature.md, to-epic.md, or to-issue.md)references/grill.md for challenging behaviorassets/templates/ and assets/examples/references/sizing.md)references/duplicates.mdreferences/update-jira-status.mdreferences/rest-api-fallback.md — use the OpenAPI spec or /rest/api/3/field endpointreferences/graphql-queries.md — use __type introspection queriesacli first, then GraphQL for bulk reads. REST API is the last resort for writes when acli fails and for schema discovery via OpenAPI spec (see Gotcha #9)acli for single-issue views and simple searches. GraphQL is for bulk operations, complex queries needing relationships or many custom fields in one call, team roster lookups, and schema introspection