A generic utilities plugin serving as a catch-all for various helper commands

version
0.0.13
GitHub stars
123

Install

/plugin install utils@ai-helpers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.

Contents

Discovered from source

Commands 6

Name

utils:auto-approve-konflux-prs

Synopsis

/utils:auto-approve-konflux-prs

Description

The command automates the approval of open PRs created by the red-hat-konflux[bot] for the given repository.

It filters all open PRs from the given repository, checks whether the PR already has /lgtm and /approve comments, verifies that all required checks (CI jobs or other mandatory checks) have passed, and if any labels/comments are missing and all checks succeed, posts /lgtm and /approve comments to trigger approval.

This ensures that PRs are only auto-approved if all required checks succeed and the author is red-hat-konflux[bot], reducing the risk of approving failing or unauthorized changes.

Arguments

  • $1 – target-repositories (required): GitHub repository in OWNER/REPO format.
    • Example: openshift/multiarch-tuning-operator.

Implementation

The command executes the following workflow:

1. Restrict Author

The command only processes PRs authored by red-hat-konflux[bot]. If a PR from any other author is encountered, it reports an error such as below:

⚠️ Only PRs from red-hat-konflux[bot] can be automatically processed

and exits.

2. Get Open PRs

Fetch all open PRs authored by red-hat-konflux[bot] for the specified repository:

gh pr list --repo <target-repository> --author app/red-hat-konflux --state open --json number,title,baseRefName,labels
  • Extract: number,title,baseRefName,labels

3. Check CI Status and Labels

For Each PR::
  1. Fetch detailed PR information:
gh pr view <PR_NUMBER> --repo <target-repository> --json statusCheckRollup,labels
  • Extract: statusCheckRollup,labels
  • Handle errors: If PR is inaccessible, log warning and skip
  1. Verify all required checks:
  • Verify all required checks have "conclusion": "SUCCESS"
  • If any check has failed or is pending(except one pending tide job), skip adding /lgtm or /approve and log:
⚠️ Skipping PR #<PR_NUMBER>: CI checks not all passed
  1. Inspect labels:

    • Check for lgtm label
    • Check for approved label
  2. Add missing labels via comments:

    • If /lgtm is missing, post a comment /lgtm
    • If /approve is missing, post a comment /approve
    • If both are missing, post a single comment containing both commands.
  3. Log each action:

✅ Added /lgtm and/or /approve to PR #<PR_NUMBER>: <PR_TITLE> (merge into <MERGE_BRANCH>)

Return Value

  • Claude agent text: Summary of processed PRs and actions taken.
  • Side effects:
    • Comments posted to PRs to trigger /lgtm and /approve.
    • Progress updates for multiple PRs.

Examples

  1. Process all open PRs from red-hat-konflux[bot] in a repository:
/utils:auto-approve-konflux-prs openshift/multiarch-tuning-operator

Output:

Processing 3 open Konflux PRs...  
[1/3] PR #84 - chore(deps): update konflux references (merge into main)
✅ Added /lgtm and /approve (all CI passed)

[2/3] PR #83 - chore(deps): update konflux references (merge into v1.x)
⚠️ Skipping: CI checks not all passed

[3/3] PR #82 - chore(deps): update konflux references (merge into fbc)
✅ Added /lgtm (already had /approve, all CI passed)

Summary:
✅ Processed 2 PRs successfully, 1 skipped due to CI failures

Prerequisites

Required Tools

  1. GitHub CLI (gh): Must be installed and authenticated

    • Install: brew install gh (macOS) or see GitHub CLI docs
    • Authenticate: gh auth login
    • Verify: gh auth status
  2. Access to GitHub Repositories: Must have read access to repos where PRs are located

    • PRs in private repos require appropriate GitHub permissions
    • Public repos should work without additional configuration

Required Permissions

  1. GitHub Permissions:
    • Read access to pull requests
    • Write access to create comments on pull requests

Error Handling

  • Repository inaccessible: Reports error and exits.
  • PRs authored by someone other than red-hat-konflux[bot]: Reports error and exits.
  • No open PRs from Konflux bot: Logs "No PRs to process".
  • GitHub authentication failure: Suggests re-login with gh auth login.
  • Comment posting failure: Logs PR number and error for manual review.

Notes

  • The command only processes open PRs authored by app/red-hat-konflux.
  • Compatible with repositories in which the user has write permission to post PR comments.
  • Designed to minimize manual PR review effort and maintain consistent approvals.

Name

utils:find-konflux-images

Synopsis

/utils:find-konflux-images

Description

Given a PR in any Konflux-enabled repository, find all Konflux/Tekton pipeline-built container images, check their availability on quay.io, and report the results. Works with any repository that has .tekton/ pipeline configurations.

Usage Example

/utils:find-konflux-images https://github.com/org/repo/pull/123

Arguments

  • $ARGUMENTS (required): A full GitHub PR URL (e.g., https://github.com/owner/repo/pull/123). Extract org, repo, and PR number from the URL.

Implementation

The command executes the following workflow:

1. Resolve the PR

Use gh pr view <PR> --json headRefOid,baseRefName,state to get:

  • The commit SHA (headRefOid)
  • The base branch (baseRefName) — shown in the output for context
  • The PR state (state) — used to determine if retrigger is possible

2. Find the pull-request pipeline templates

Look in the .tekton/ directory at the PR's head commit for *-pull-request.yaml files. Read each one and extract the output-image value, which contains the image URL pattern with {{revision}} placeholder.

Use the GitHub API to fetch from the PR's commit SHA directly (not the base branch), so results are accurate even if the PR modifies .tekton/ files:

PR_FILES=$(gh api "repos/${REPO}/contents/.tekton?ref=${COMMIT_SHA}" \
  --jq '.[] | select(.type=="file" and (.name | endswith("-pull-request.yaml"))) | .name')

for file in $PR_FILES; do
  CONTENT=$(gh api "repos/${REPO}/contents/.tekton/${file}?ref=${COMMIT_SHA}" --jq '.content' | base64 -d)
  IMAGE_PATTERN=$(echo "$CONTENT" | grep -A1 'name: output-image' | grep 'value:' | head -1 | sed 's/.*value: *//')
  COMPONENT=$(echo "$file" | sed 's/-pull-request\.yaml$//')
done

3. Check which Konflux builds were triggered

gh pr checks ${PR_NUMBER} --repo ${REPO} --json name,state \
  --jq '.[] | select(.name | test("-on-pull-request$")) | .name'

Use structured output to identify image-build checks consistently. The enterprise-contract checks are verification-only.

4. Verify image availability and get expiration date from quay.io

Only check images for triggered pipelines. Skip quay.io lookup for untriggered components — report them directly as NOT TRIGGERED.

For each triggered component, replace {{revision}} in the IMAGE_PATTERN extracted from step 2 with the commit SHA to get the full image URL. Then parse the repo path and tag from it to query the quay.io tag API:

# Derive the full image URL from IMAGE_PATTERN
FULL_IMAGE=$(echo "$IMAGE_PATTERN" | sed "s/{{revision}}/${COMMIT_SHA}/g")
# Parse: quay.io/<REPO_PATH>:<TAG>
REPO_PATH=$(echo "$FULL_IMAGE" | sed 's|quay.io/||' | sed 's|:.*||')
TAG=$(echo "$FULL_IMAGE" | sed 's|.*:||')

# Query the quay.io tag API — returns availability, creation time, and expiration date
TAG_INFO=$(curl --fail --silent --show-error --max-time 15 \
  "https://quay.io/api/v1/repository/${REPO_PATH}/tag/?specificTag=${TAG}") \
  || { echo "ERROR: Unable to reach quay.io registry API."; exit 1; }
# Parse the response:
#   - tags[0].expiration: exact expiration date (e.g., "Sun, 22 Mar 2026 21:22:50 -0000")
#   - tags[0].start_ts: creation timestamp
#   - empty tags array means image not found (never built or already expired/garbage-collected)

Use tags array length to determine availability (non-empty = found). Extract the expiration field for the exact expiry date. Format it as a short date (e.g., 2026-03-22).

Important: Compare the expiration timestamp against the current time (UTC). The quay.io tag API may still return tags after they have expired (before garbage collection). If the expiration date is in the past, mark the image as EXPIRED — it is no longer pullable even though the API still returns it.

5. Present results

Present results as a Markdown table:

ComponentStatusExpirationImage URL
my-componentAVAILABLE2026-04-05quay.io/redhat-user-workloads/...
my-other-componentEXPIRED2026-03-20--
optional-componentNOT TRIGGERED----
  • AVAILABLE: Tag found in quay.io and expiration date is in the future — image is pullable
  • EXPIRED: Tag found in quay.io but expiration date is in the past — image is no longer pullable
  • NOT FOUND: Tag not found in quay.io (build failed or image already garbage-collected)
  • NOT TRIGGERED: Pipeline was not triggered for this PR (file changes didn't match the CEL filter)
  • Only show the full image URL when the status is AVAILABLE
  • Show -- in the Image URL and Expiration columns when the image is not available
  • Show the base branch name (e.g., main, release-4.21)

6. Offer to retrigger expired images

If any triggered images are EXPIRED or NOT FOUND, and the PR is still open, offer to retrigger by commenting /retest on the PR:

gh pr comment ${PR_NUMBER} --repo ${REPO} --body "/retest"

Key facts about /retest:

  • Prow treats /retest as "rerun only failed jobs" — if all Prow jobs pass, Prow does nothing
  • Konflux (Pipelines as Code) treats /retest as "rerun all pipeline runs" — it rebuilds all images
  • This means /retest is safe to use for rebuilding expired Konflux images without re-running passing Prow jobs
  • Builds typically take 10-20 minutes; re-run this command to check availability afterward

Error Handling

ScenarioAction
PR not foundShow error with PR number
No .tekton/ directoryERROR: No .tekton/ directory found. This repo may not use Konflux.
No pull-request configs foundERROR: No pull-request Tekton pipeline configs found in .tekton/.
quay.io API unreachableERROR: Unable to reach quay.io registry API.
Image expired (tag exists but past expiration)Report as EXPIRED with the expiration date, show -- in Image URL column, offer to retrigger via /retest if PR is still open
Image gone (tag not found)Report as NOT FOUND, show -- in both Expiration and Image URL columns, offer to retrigger via /retest if PR is still open
PR is closed/mergedDo not offer retrigger; images can only be rebuilt on open PRs

Important Notes

  • PR images have an expiration date set by quay.io. Query the tag API to get the exact expiry date per image.
  • For EXPIRED images (tag exists but expiration is in the past), show the expiration date but -- in the Image URL column.
  • For NOT FOUND images (not triggered or already garbage-collected), show -- in both Expiration and Image URL columns.
  • Expired images can be rebuilt by commenting /retest on the PR (only works if PR is still open)
  • Image URL patterns vary between components — always read from the Tekton config
  • Not all pipelines trigger on every PR — each has a CEL expression filtering on changed file paths

Requirements

  • gh CLI authenticated with access to the target repository
  • curl available

Name

utils:gh-attention

Synopsis

/utils:gh-attention [--repo <org/repo>]

Description

The utils:gh-attention command identifies pull requests and issues that are waiting for your action. It scans PRs you've authored, PRs where you're requested as a reviewer, and PRs where you've participated in discussions. For each, it detects specific states where you are the blocker: unresolved review comments, unanswered PR conversation comments, change requests you haven't addressed, merge conflicts, and unanswered questions on assigned issues.

This command helps cut through notification noise by focusing only on actionable items where others are waiting for your input.

Implementation

Step 0: Prerequisites and Setup

  1. Check gh CLI installation and authentication:

    gh version || echo "gh CLI not installed. Install from https://cli.github.com/"
    gh auth status || gh auth login
    
  2. Parse arguments:

    • Check for --repo <org/repo> flag
    • Extract repository if provided
  3. Get current username:

    CURRENT_USER=$(gh api user -q .login)
    

Step 1: Repository Discovery

If --repo is provided:

  • Use the specified repository
  • Skip discovery phase

If no --repo argument:

  1. Find all open PRs where you're involved:

    a. PRs authored by you:

    gh search prs --author=@me --state=open --json number,repository,title,url,isDraft --limit 100
    

    b. PRs where you're requested as reviewer:

    gh search prs --review-requested=@me --state=open --json number,repository,title,url,isDraft --limit 100
    

    c. PRs where you've commented/reviewed:

    gh search prs --commenter=@me --state=open --json number,repository,title,url,isDraft --limit 100
    
  2. Find all open issues assigned to current user:

    gh search issues --assignee=@me --state=open --json number,repository,title,url --limit 100
    
  3. Combine and deduplicate PRs from steps 1a, 1b, and 1c

  4. Filter out draft PRs immediately to reduce API calls

  5. Extract unique repositories from the results

Step 2: Data Collection

Use GraphQL for efficient data fetching: GraphQL allows us to fetch all needed data in a single query and provides direct access to the isResolved field on review threads.

For each PR (non-draft only):

  1. Fetch all PR data using GraphQL:

    Split the repository owner and name from <REPO> (format: owner/name).

    gh api graphql -f query='
    query($owner: String!, $name: String!, $number: Int!) {
      repository(owner: $owner, name: $name) {
        pullRequest(number: $number) {
          number
          title
          url
          createdAt
          author { login }
          mergeable
          reviewThreads(first: 100) {
            nodes {
              isResolved
              isOutdated
              comments(first: 20) {
                nodes {
                  author { login }
                  body
                  createdAt
                  path
                  line
                }
              }
            }
          }
          reviews(first: 50) {
            nodes {
              author { login }
              state
              submittedAt
              body
            }
          }
          comments(first: 100) {
            nodes {
              author { login }
              body
              createdAt
            }
          }
          commits(last: 50) {
            nodes {
              commit {
                committedDate
              }
            }
          }
        }
      }
    }' -f owner='<OWNER>' -f name='<NAME>' -F number=<PR_NUMBER>
    
  2. Parse the GraphQL response to extract:

    • PR metadata (number, title, url, mergeable, author)
    • Review threads with resolution status
    • Reviews with state and timestamp
    • PR comments (general conversation comments)
    • Commit timestamps
  3. Determine your role in the PR:

    • If author.login == CURRENT_USER: You are the PR author
    • Otherwise: You are a reviewer/commenter

For each issue:

  1. Fetch issue data using GraphQL:

    gh api graphql -f query='
    query($owner: String!, $name: String!, $number: Int!) {
      repository(owner: $owner, name: $name) {
        issue(number: $number) {
          number
          title
          url
          body
          comments(first: 100) {
            nodes {
              author { login }
              body
              createdAt
            }
          }
        }
      }
    }' -f owner='<OWNER>' -f name='<NAME>' -F number=<ISSUE_NUMBER>
    
  2. Parse the GraphQL response to extract issue details and comments

Step 3: Analysis and Detection

Detection logic differs based on your role (determined in Step 2.3):

A. Detect Merge Conflicts (CRITICAL Priority) - Only for PRs you authored

For each PR where author.login == CURRENT_USER:

  • Check mergeable field from Step 2
  • If mergeable == "CONFLICTING", flag as CRITICAL
  • Record: Merge conflict needs resolution
B. Detect Review Feedback (HIGH Priority)

For each PR (from GraphQL data), check for any pending review feedback:

  1. Check for unresolved review threads:

    • Filter review threads where:
      • isResolved == false (direct from GraphQL)
      • isOutdated == false (ignore outdated code comments)
      • First comment author is not a bot (dependabot, renovate, openshift-ci-robot, openshift-ci)
    • For each unresolved thread:
      • Get the last comment in the thread
      • If last_comment.author.login == CURRENT_USER, skip (you already responded)
      • Otherwise, record: path:line - @author commented (X days ago) with snippet (first 80 chars)
  2. Check for unaddressed change request reviews - Only for PRs you authored:

    • If author.login == CURRENT_USER:
      • Filter reviews where state == "CHANGES_REQUESTED"
      • For each change request:
        • Compare review submittedAt with commit dates (commits.nodes[].commit.committedDate)
        • If NO commits after the review, record: @reviewer requested changes (X days ago)
        • If multiple from same reviewer, use most recent
  3. Check for unanswered PR comments (general conversation comments):

    • Get PR comments from GraphQL response
    • Find your last comment timestamp in the PR conversation
    • For comments after your last comment where:
      • author.login != CURRENT_USER
      • Author is not a bot (exclude dependabot, renovate, openshift-ci-robot, openshift-ci)
      • body contains @{CURRENT_USER} OR body contains ?
    • Record: @author commented in PR conversation (X days ago) with snippet (first 80 chars)
  4. Combine and flag as HIGH priority if any of: unresolved threads, unaddressed change requests (if you're the author), or unanswered PR comments exist

C. Detect Unanswered Issue Questions (LOW Priority)

For each assigned issue (from GraphQL data):

  1. Find your last comment timestamp:

    • Scan comments from GraphQL response
    • Find most recent comment where author.login == CURRENT_USER
  2. Check for questions after your last comment:

    • Look for comments where:
      • createdAt > your_last_comment_timestamp
      • body contains @{CURRENT_USER} OR body contains ?
      • author.login != CURRENT_USER
      • Author is not a bot (exclude dependabot, renovate, openshift-ci-robot, openshift-ci)
  3. Also check the issue body for unanswered questions if you haven't commented yet

  4. For each unanswered question:

    • Flag as LOW priority
    • Record: @author asked a question (X days ago)
    • Use comment's createdAt to calculate waiting time

Step 4: Calculate Waiting Time

For each detected item:

  • Calculate days/hours since the triggering event (review submitted, comment posted, conflict detected)
  • Format as human-readable: 3 days ago, 5 hours ago, just now

Step 5: Sort and Prioritize

  1. Primary sort: By priority level

    • CRITICAL (merge conflicts)
    • HIGH (review feedback - change requests, unresolved threads, and unanswered PR comments)
    • LOW (issue questions)
  2. Secondary sort: By waiting time (oldest first within each priority)

Step 6: Generate Output

Header:

Found X items requiring attention across Y repositories

For each item, display:

[PRIORITY_LEVEL] Repository: org/repo
  PR #123: Title of the pull request
  URL: https://github.com/org/repo/pull/123
  Reason: [specific reason - e.g., "2 unresolved comment threads"]
  Waiting: X days since last comment

  Details:
  • path/to/file.go:45 - @reviewer asked about error handling (2 days ago)
    "Should we add retry logic here?"
  • path/to/other.go:120 - @reviewer requested refactoring (3 days ago)
    "Consider extracting this into a helper function"

Footer summary:

Summary:
  1 PR with merge conflicts
  3 PRs with review feedback
  1 issue with unanswered questions

If no items found:

✓ No items requiring attention! All caught up.

Step 7: Error Handling

No repositories found:

No open PRs or assigned issues found.

API rate limit hit:

⚠️  GitHub API rate limit reached after checking X items.
Try using --repo <org/repo> to narrow the scope.
Rate limit resets at: [timestamp from gh api rate_limit]

Authentication failure:

❌ GitHub CLI not authenticated.
Run: gh auth login

Repository access denied:

⚠️  Unable to access repository <org/repo> (private or insufficient permissions)
Skipping...

Return Value

The command outputs a prioritized list of actionable items with:

  • Priority level: CRITICAL, HIGH, or LOW
  • Repository and PR/issue number: For navigation
  • URL: Direct link to the item
  • Reason: Why it requires attention
  • Waiting time: How long since the triggering event
  • Details: Specific comments, reviewers, or questions with context
  • Summary: Count of items by category

Exit codes:

  • 0: Success (items found or no items found)
  • 1: Error (authentication failure, gh CLI not found)

Examples

Example 1: Check all repositories

/utils:gh-attention

Output:

Found 3 items requiring attention across 2 repositories

[HIGH] Repository: openshift/console
  PR #5678: Add dark mode toggle
  URL: https://github.com/openshift/console/pull/5678
  Reason: 2 unresolved review threads
  Waiting: 3 days since last comment

  Details:
  • src/components/Header.tsx:120 - @designer commented (3 days ago)
    "Can we use the theme constant instead of hardcoding?"
  • src/styles/theme.css:15 - @reviewer commented (2 days ago)
    "Should this support high contrast mode?"

[HIGH] Repository: openshift/origin
  PR #1234: Fix authentication timeout bug
  URL: https://github.com/openshift/origin/pull/1234
  Reason: 1 change request, 1 unresolved thread
  Waiting: 2 days since review

  Details:
  • @reviewer-name requested changes (2 days ago)
    "Please add unit tests for the timeout logic"
  • pkg/auth/handler.go:45 - @reviewer commented (1 day ago)
    "Should we log this error before returning?"

[LOW] Repository: openshift/enhancements
  Issue #234: Enhancement proposal for new API
  URL: https://github.com/openshift/enhancements/issues/234
  Reason: Unanswered question
  Waiting: 4 days since question

  Details:
  • @team-member asked a question (4 days ago)
    "@you What's the timeline for implementing this?"

Summary:
  2 PRs with review feedback
  1 issue with unanswered questions

Example 2: Check specific repository

/utils:gh-attention --repo openshift/origin

Output:

Found 1 item requiring attention in openshift/origin

[HIGH] Repository: openshift/origin
  PR #1234: Fix authentication timeout bug
  URL: https://github.com/openshift/origin/pull/1234
  Reason: Change request not addressed
  Waiting: 2 days since review

  Details:
  • @reviewer-name requested changes (2 days ago)
    "Please add unit tests for the timeout logic"

Summary:
  1 PR with unaddressed change requests

Example 3: No items requiring attention

/utils:gh-attention

Output:

✓ No items requiring attention! All caught up.

Arguments:

  • --repo <org/repo>: (Optional) Limit check to a specific repository. If omitted, checks all repositories with your open PRs or assigned issues.

Name

utils:process-renovate-pr

Synopsis

/utils:process-renovate-pr <PR_NUMBER|open> [JIRA_PROJECT] [COMPONENT]

Description

The utils:process-renovate-pr command automates the processing of Renovate/Konflux dependency update pull requests to meet repository contribution standards. It analyzes dependencies, creates comprehensive Jira tickets, and updates PR titles with proper references.

This command significantly reduces manual PR processing time from approximately 15 minutes to 2 minutes by automating:

  • Dependency analysis (direct vs indirect)
  • OpenShift version detection from release branches
  • Jira ticket creation with comprehensive details
  • PR title updates with Jira references
  • Testing strategy identification

The command can process either a single PR by number or all open dependency PRs from the Konflux bot.

Implementation

The command executes the following workflow:

1. Validation

  • Verifies the PR is from red-hat-konflux[bot]
  • Checks PR title matches pattern: chore(deps): update * digest to * (main)
  • Filters out "Pipelines as Code configuration" PRs
  • If argument is "open", fetches all open dependency PRs

2. Target Version Determination

  • Fetches latest state: git fetch origin
  • Gets commit hash for origin/main
  • Finds all release branches matching main's commit: origin/release-*
  • Selects the lowest version number (e.g., if both 4.21 and 4.22 match, uses 4.21)

3. Dependency Analysis

From the PR diff (go.mod changes):

Type Classification:

  • Checks for // indirect comment in go.mod
  • For indirect: uses go mod why <package> to identify parent dependency

Usage Analysis:

  • Direct dependencies: Searches codebase for import statements
    • Identifies importing files
    • Determines purpose (e.g., "OpenStack image management", "AWS integration")
    • Distinguishes runtime code vs tooling (check hack/tools/)
  • Indirect dependencies: Documents parent dependency usage

Version Changes:

  • Extracts old and new pseudo-versions from go.mod
  • Fetches upstream commit messages via GitHub API
  • Categorizes as patch/minor/major or digest update

Testing Strategy:

  • hack/tools dependencies: Identifies Makefile targets
  • Runtime dependencies: Suggests component testing

4. Jira Ticket Management

  • Checks existing PR comments for Jira references
  • Creates new ticket if none exists with:
    • Summary: {Package name} ({Brief purpose})
    • Type: Task
    • Components: From $3 or default "HyperShift"
    • Labels: ["dependencies", "renovate", "ai-generated"] plus context labels
    • Description: Comprehensive details including:
      • Dependency information (type, versions, location)
      • Usage in repository
      • Changes in update
      • Step-by-step testing instructions
    • Target Version: Sets customfield_10855 to openshift-X.Y

5. PR Title Update

Posts comment with /retitle command and processing summary:

/retitle [PROJECT-XXXX](https://redhat.atlassian.net/browse/PROJECT-XXXX): {Package name} ({Brief description})

Includes checklist of completed actions and link to Jira ticket.

Return Value

  • Claude agent text: Processing status and summary
  • Side effects:
    • Jira ticket created or referenced
    • PR comment posted with /retitle command
    • Progress updates for multiple PRs

Examples

  1. Process a single PR:

    /utils:process-renovate-pr 7051
    

    Output:

    ✅ Processed PR #7051
    - Dependency: github.com/go-logr/logr
    - Type: Direct
    - Jira: CNTRLPLANE-1234
    - Target Version: openshift-4.21
    - PR title updated with Jira reference
    
  2. Process with custom Jira project:

    /utils:process-renovate-pr 7051 OCPBUGS
    

    Creates ticket in OCPBUGS project instead of default CNTRLPLANE.

  3. Process with custom component:

    /utils:process-renovate-pr 7051 CNTRLPLANE "Control Plane Operator"
    

    Creates ticket with specified component name.

  4. Process all open dependency PRs:

    /utils:process-renovate-pr open
    

    Output:

    Processing 3 dependency PRs...
    
    [1/3] Processing PR #7051...
    ✅ Completed PR #7051
    - Dependency: github.com/go-logr/logr
    - Jira: CNTRLPLANE-1234
    
    [2/3] Processing PR #7049...
    ✅ Completed PR #7049
    - Dependency: golang.org/x/net
    - Jira: CNTRLPLANE-1235
    
    [3/3] Processing PR #7048...
    ✅ Completed PR #7048
    - Dependency: k8s.io/api
    - Jira: CNTRLPLANE-1236
    
    Summary:
    ✅ Processed 3 PRs successfully
    - Jira project: CNTRLPLANE
    - Component: HyperShift
    - Target Version: openshift-4.21
    
  5. Process all open PRs with custom settings:

    /utils:process-renovate-pr open OCPBUGS Infrastructure
    

Arguments

  • $1 (required): PR number (e.g., 7051) or open to process all open dependency PRs from Konflux bot

    • When open: Automatically fetches and filters dependency PRs, excluding "Pipelines as Code configuration" PRs
  • $2 (optional): Jira project key (default: CNTRLPLANE)

    • Examples: CNTRLPLANE, OCPBUGS, HOSTEDCP
  • $3 (optional): Jira component name (default: HyperShift)

    • Use quotes for multi-word components: "Control Plane Operator"

Error Handling

The command handles common error cases:

  • PR not from Konflux bot: Explains requirement and exits
  • Pipeline configuration PR: Explains this command only handles dependency updates
  • Jira creation failure: Provides ticket content for manual creation
  • Version field update failure: Notes it may need manual setting
  • Invalid PR number: Validates PR exists before processing

Notes

  • Repository name is automatically detected from git remote -v (non-fork remote)
  • Direct dependencies include file-level usage analysis
  • Indirect dependencies focus on dependency chain documentation
  • Testing instructions are tailored to dependency type (tooling vs runtime)
  • All Jira tickets are labeled with "ai-generated" for tracking

Name

utils:review-ai-helpers-overlap

Synopsis

/utils:review-ai-helpers-overlap [--idea "description"] [--pr NUMBER] [--verbose]

Description

Review potential overlaps between your planned or implemented work and existing Claude Code Plugins, Commands, Skills, Sub-agents, or Hooks in the openshift-eng/ai-helpers repository to avoid duplicating effort and find collaboration opportunity.

This command is specifically designed for contributors and reviewers to the openshift-eng/ai-helpers repository. It checks for overlaps in:

  • Plugin commands (plugins/*/commands/*.md)
  • Skills (plugins/*/skills/*/SKILL.md and helper scripts)
  • Sub-agents (agents/*.md)
  • Hooks (.claude/hooks/*.sh and .claude/hooks/*.py)

Modes:

  • Idea check (--idea "TEXT"): Check if your idea already exists before writing code
  • Local check (default): Compare your local changes against main branch and open PRs
  • PR review mode (--pr NUMBER): Check if a specific PR overlaps with others

This command helps contributors avoid duplicate work and helps reviewers identify related PRs that should be consolidated.

Implementation

Phased duplicate detection with token-efficient early returns:

  • Checks local git changes, open PRs, and main branch commands
  • Uses semantic matching ("analyze" ≈ "inspect") via Claude's LLM
  • Progressive disclosure: summary → findings → verbose details

Step 0: Determine Mode

Parse $ARGUMENTS:

  1. Idea Mode: If --idea "TEXT" provided - extract idea description
  2. PR Review Mode: If --pr <NUMBER> provided - extract PR number
  3. Contributor Mode (default): Check local git diff

Store flags: verbose

Step 1: Set Repository Context

This command only works with the openshift-eng/ai-helpers repository.

Validate repository:

# Check if we're in the ai-helpers repository
REPO_URL=$(git remote get-url upstream 2>/dev/null || git remote get-url origin)
if ! echo "$REPO_URL" | grep -q "openshift-eng/ai-helpers"; then
  echo "Error: This command only works in the openshift-eng/ai-helpers repository"
  exit 1
fi

# Hardcode repository for all gh commands
REPO="openshift-eng/ai-helpers"

Step 2: Gather Context

Idea Mode: Extract keywords from idea description using Claude's semantic understanding

Contributor Mode:

  • Get changed files from ai-helpers structure:
    # Get all ai-helpers changes in one pass (commands, skills, agents, hooks)
    CHANGED_FILES=$(git diff --name-only main...HEAD | grep -E '(^plugins/.*/commands/.*\.md$|^plugins/.*/skills/.*/SKILL\.md$|^plugins/.*/skills/.*\.py$|^agents/.*\.md$|^\.claude/hooks/.*\.(sh|py)$)')
    
  • If no ai-helpers-specific files changed: Show message "No ai-helpers changes detected (commands, skills, agents, or hooks). This tool is designed for ai-helpers repository contributions." and exit
  • For each file, use Read to extract: plugin name, command/skill/agent name, description (first 500 chars)

PR Review Mode:

  • Get PR files: gh pr view <NUMBER> --repo "$REPO" --json files --jq '.files[].path'
  • Get content: gh pr diff <NUMBER> --repo "$REPO" -- <file_path>
  • Parse diff for added lines and extract metadata

Step 3: Check PR Titles (Lightweight)

Fetch open PRs (metadata only): gh pr list --repo "$REPO" --state open --json number,title,body,author,createdAt --limit 100

Match keywords semantically:

  • Idea Mode: Check PR titles/bodies for idea keywords
  • Contributor/PR Review Mode: Check for plugin name, command name, similar keywords

If potential overlap found, prompt user: "Continue with deep comparison? (y/n)"

  • If "no": Exit with recommendation to review the PR
  • If "yes" or no overlap: Continue to Step 4

Step 4: Deep Semantic Comparison

Run if Step 3 flagged overlaps (user confirmed) OR --verbose flag OR no obvious overlaps in Step 3.

For flagged PRs:

  1. Fetch content based on file type:
    • Commands: gh pr diff <PR_NUMBER> --repo "$REPO" -- plugins/<plugin>/commands/<command>.md
    • Skills: gh pr diff <PR_NUMBER> --repo "$REPO" -- plugins/<plugin>/skills/<skill>/SKILL.md
    • Agents: gh pr diff <PR_NUMBER> --repo "$REPO" -- agents/<agent>.md
    • Hooks: gh pr diff <PR_NUMBER> --repo "$REPO" -- .claude/hooks/<hook>.(sh|py)
  2. Parse diff to extract Description and Implementation sections
  3. Claude compares purposes, workflows, functionality and assesses overlap:
    • HIGH (85-100%): Near-identical → Strong warning to collaborate
    • MODERATE (60-85%): Similar goal, different approach → Soft warning to differentiate
    • LOW (<60%): Different purposes → OK to proceed

Step 5: Check Main Branch

Idea Mode: Scan all ai-helpers files:

  • Commands: find plugins/*/commands/*.md
  • Skills: find plugins/*/skills/*/SKILL.md
  • Agents: find agents/*.md
  • Hooks: find .claude/hooks/*.{sh,py}

Use Read for frontmatter descriptions, flag if 3+ keyword overlap or semantic similarity

Contributor/PR Review Mode: List existing files in changed areas:

  • Commands: ls plugins/<plugin>/commands/*.md
  • Skills: ls plugins/<plugin>/skills/*/SKILL.md
  • Agents: ls agents/*.md
  • Hooks: ls .claude/hooks/*.{sh,py}

Check for duplicate names and description similarity

Step 6: Present Findings

Use progressive disclosure (3 layers):

  • Layer 1 (always): Summary of checks performed and files analyzed
  • Layer 2 (if overlaps): Detailed findings with severity ([HIGH/MODERATE/LOW OVERLAP]), PR links, and recommendations for joint effort
  • Layer 3 (--verbose): Side-by-side comparison with differentiation suggestions

Step 7: Save Report (Optional)

If overlaps found, save detailed report to .work/review-ai-helpers-overlap/report-{timestamp}.md with summary, PRs compared, findings, and recommendations. Display file path to user.

Examples

  1. Idea validation (before coding):

    /utils:review-ai-helpers-overlap --idea "command to analyze Jira issues and create PRs"
    
    /utils:review-ai-helpers-overlap --idea "command to analyze test coverage"
    

    Checks if a similar command already exists in ai-helpers plugins or there are opened PR(s) for similar purpose

  2. Check local changes before raising a PR (ai-helpers contributor workflow):

    /utils:review-ai-helpers-overlap
    

    Checks your local command/skill/agent/hook changes against main branch and open PRs.

  3. PR review (check if PR overlaps with others):

    /utils:review-ai-helpers-overlap --pr 123
    

    Check if PR #123 overlaps with other open PRs

Return Value

Structured overlap analysis with progressive disclosure:

  • Summary: Checks performed and files analyzed
  • Findings (if overlaps): Severity ratings (HIGH/MODERATE/LOW), PR links, recommendations
  • Verbose details (--verbose): Side-by-side comparisons with differentiation suggestions

Optionally saves report to .work/review-ai-helpers-overlap/report-{timestamp}.md when overlaps found.

Notes

  • Repository Scope: This command only works in the openshift-eng/ai-helpers repository
  • Requirements: GitHub CLI (gh) and git
  • Best Practice: Contributors run /utils:review-ai-helpers-overlap --idea during planning, run /utils:review-ai-helpers-overlap during developing; reviewers use --pr <NUMBER> during reviewing
  • Uses semantic matching ("analyze" ≈ "inspect") and phased checks (PR titles → full diffs) for token efficiency

Arguments

  • --idea "TEXT": Check if your idea exists before coding (activates idea validation mode)
  • --pr <NUMBER>: Check if specific PR overlaps with others (reviewer mode)
  • --verbose: Show detailed side-by-side comparisons (Layer 3 output)

Name

utils:review-security

Synopsis

/utils:review-security [file-paths-or-patterns]

Description

The utils:review-security command is a security analysis orchestrator that combines deterministic scanning tools with AI-powered contextual reasoning. Unlike traditional security scanners that produce noisy, context-free alerts, this command:

Orchestrates proven tools (when available):

  • gitleaks or trufflehog - Secret detection with maintained pattern databases
  • gosec - Go AST-aware security analysis
  • bandit - Python-specific security scanner
  • semgrep - Cross-language semantic analysis

Adds intelligence layer:

  • Triages tool findings to reduce false positives
  • Explains exploitability in plain language for non-security developers
  • Traces data flow to assess reachability from user input
  • Identifies if findings are in test/dead code
  • Suggests concrete fixes with code examples

Analyzes what tools miss:

  • Business logic flaws spanning multiple files
  • Authentication/authorization design issues
  • Context-dependent vulnerabilities
  • Security controls removed in diffs

Scope: Without arguments, analyzes git diff changes (ideal for PR reviews). With file paths/patterns, analyzes specified files.

Important: This is NOT a replacement for CI/CD security gates. Deterministic tools should still run in your pipeline. This command helps developers understand and act on findings during development.

Implementation

1. Determine Analysis Scope

Diff mode (default - no arguments):

  • Run git diff --name-only to identify changed files
  • Run git diff to capture what actually changed (for context analysis)
  • If no diff exists, fall back to git status --porcelain for unstaged changes
  • Extract change intent: refactor vs new feature vs bugfix (from commit messages/branch name, or the added inline comments or even the changed code, if necessary)

File mode (arguments provided):

  • Use Glob tool to expand patterns: /utils:review-security "pkg/**/*.go"
  • Validate files exist and are readable
  • Note: In file mode, analyze entire file content (no diff context)

Filter scope:

  • Exclude: vendored code (vendor/, node_modules/, etc.), generated code (protobuf, etc.)
  • Analyze all other files in scope

2. Run Security Scanning Tools

CRITICAL: Only scan files in scope to avoid performance issues:

  • In diff mode: scan only changed files (from git diff --name-only)
  • In file mode: scan only specified files (from arguments)

Create .work/security-review/ directory. Collect the list of files to scan and detect languages:

# FILES already determined in step 1
# Detect languages from file extensions
GO_FILES=$(echo "$FILES" | grep '\.go$' || true)
PY_FILES=$(echo "$FILES" | grep '\.py$' || true)

Tool availability checking and installation:

Before running scans, check which tools are needed based on detected languages:

  • Language-specific: gosec (for Go; only check if Go files are in scope), bandit (for Python; only check if Python files are in scope)
  • Language-agnostic: gitleaks or trufflehog
  • Multi-language: semgrep

Detect OS. For each missing tool:

  1. Provide platform-aware installation commands (dnf/apt/brew/go install/pip install)
  2. Let user choose if to install it - WAIT for response before proceeding Do not use AskUserQuestion tool. Just ask for one tool, let user type yes/no, then ask for another tool for user to type yes/no, et al.

After asking all missing tools and collecting user's choices, install selected tools via Bash, then inform user which tools will run (e.g., "Running: gosec ✓, gitleaks ✓, semgrep ✗")

Execute all available tools (all language-specific, language-agnostic and multi-language)

Go analysis (only if .go files in scope):

# IMPORTANT: Do NOT use ./... which scans entire codebase
# Get unique directories containing changed .go files
GO_DIRS=$(echo "$GO_FILES" | xargs -n1 dirname 2>/dev/null | sort -u || true)

# Run gosec only on directories with changed files
if [ -n "$GO_DIRS" ]; then
  gosec -fmt json -out .work/security-review/gosec.json $GO_DIRS 2>/dev/null
fi

Python analysis (only if .py files in scope):

# IMPORTANT: Do NOT use -r . which scans entire directory tree
# Run bandit only on specific Python files
if [ -n "$PY_FILES" ]; then
  bandit -f json -o .work/security-review/bandit.json $PY_FILES 2>/dev/null
fi

Secret detection (try both, use whichever is available):

# Option 1: gitleaks (scan specific files only, not entire repo)
echo "$FILES" | tr '\n' '\0' | xargs -0 gitleaks detect --no-git --report-format json --report-path .work/security-review/gitleaks.json 2>/dev/null

# Option 2: trufflehog (scan specific files only)
echo "$FILES" | tr '\n' '\0' | xargs -0 trufflehog filesystem --json 2>/dev/null > .work/security-review/trufflehog.json

General SAST (if semgrep available):

# Run semgrep only on files in scope
if command -v semgrep >/dev/null 2>&1; then
  semgrep --config auto --json --output .work/security-review/semgrep.json $FILES 2>/dev/null
fi

Track execution:

  • Log which tools executed successfully vs which were unavailable
  • Note which findings come from which tool
  • Continue with gap analysis even if no tools available

3. Contextual Triage of Tool Findings

Important: Language-specific tools (e.g. gosec, bandit), language-agnostic tools (e.g. gitleaks) and multi-language tools (e.g. semgrep) may report overlapping findings. This is normal and indicates higher confidence in the issue.

For each finding from the tools, perform AI-powered analysis:

Deduplication:

  • Group findings by file + line number + issue type
  • If multiple tools report the same issue (e.g., gosec + semgrep both find SQL injection at line 45):
    • Treat as high confidence finding
    • Note all tools that detected it in the report
    • Only analyze it once (don't duplicate the triage work)
  • Example: "SQL injection in handlers/user.go:145 (detected by: gosec, semgrep)"

A. Read Sufficient Context

  • Read the complete function containing the finding
  • If file < 500 lines: read entire file
  • If file ≥ 500 lines: read ±50 lines or to function boundaries (whichever is larger)
  • If still unclear about data flow, trace back through function callers and imports until you can determine if user input reaches the vulnerability

B. False Positive Detection

  • Assess: Is this a true positive or false positive?
  • Examples of false positives to catch (including but not limited to):
    • Secrets in test fixtures or example configurations
    • SQL concatenation in logging/debugging code (not executed)
    • Hardcoded keys that are actually public API identifiers
    • Weak crypto used for non-security purposes (checksums)
  • Provide reasoning for classification

C. Exploitability Analysis For confirmed issues, answer:

  • Reachability: Is this code path reachable from user input? Trace data flow
  • Impact: What's the actual blast radius if exploited?
  • Likelihood: Is exploitation trivial or requires complex conditions?
  • Context: Is this in production code, test code, or dead code?

Reclassify severity based on context, including but not limited to below examples:

  • Tool says CRITICAL → Actually in unreachable test helper → Downgrade to INFO
  • Tool says MEDIUM → User input flows directly with no validation → Upgrade to HIGH

D. Exploitability Narratives Write 2-3 sentence attack scenario for each confirmed HIGH/CRITICAL:

Example:

"An attacker could submit a malicious user_id parameter containing '; DROP TABLE users;--. Because this value is concatenated directly into the SQL query at line 45 without parameterization, the database would execute the injected command, potentially deleting all user records."

This helps non-security developers understand the real-world impact.

E. Concrete Fix Suggestions For each finding, provide:

  • Explanation of WHY it's vulnerable
  • Code example showing the fix
  • Link to relevant documentation (OWASP, language security guides)

4. Gap Analysis (AI's Unique Value)

Review code for issues deterministic tools cannot detect:

Business Logic Flaws:

  • Authorization checks in wrong order
  • Race conditions in security-critical sections
  • Time-of-check-time-of-use (TOCTOU) vulnerabilities
  • Insufficient validation of complex business rules

Design Issues:

  • Authentication missing before sensitive operations
  • Privilege escalation via parameter manipulation
  • Session fixation vulnerabilities
  • Insecure state management across requests

Multi-File Context:

  • Data flow vulnerabilities spanning multiple files
  • Inconsistent security controls across similar endpoints
  • Global state manipulation affecting security

Diff-Specific Analysis (when in diff mode):

  • Flag if a security control was REMOVED (e.g., auth check deleted)
  • Identify new attack surface introduced by changes
  • Detect if refactoring inadvertently bypassed validation
  • Note: Tools scan whole files; understanding "this line moved vs new" requires reasoning

5. Generate Actionable Report

Create a report at .work/security-review/report-{timestamp}.md with:

Executive Summary:

  • Tools executed (which ran successfully, which were unavailable)
  • Total findings: {count by severity}
  • Scope analyzed (diff vs full files)

Tool Findings (Triaged): For each finding from gitleaks, trufflehog, gosec, bandit, semgrep:

### [HIGH] SQL Injection in handlers/user.go:145
**Source**: gosec (G201)
**AI Assessment**: TRUE POSITIVE - High severity confirmed

**Exploitability**:
An attacker could submit a malicious `user_id` parameter containing `'; DROP TABLE users;--`.
Because this value is concatenated directly into the SQL query without parameterization, the
database would execute the injected command, potentially deleting all user records.

**Reachability**: User input flows directly from HTTP handler → database query with no validation

**Fix**:
\```go
// Before (vulnerable)
query := "SELECT * FROM users WHERE id = " + userInput

// After (secure)
query := "SELECT * FROM users WHERE id = ?"
rows, err := db.Query(query, userInput)
\```

**Reference**: https://owasp.org/www-community/attacks/SQL_Injection

Clearly mark which findings are:

  • Tool Found + AI Confirmed: High confidence issues
  • Tool Found + AI Downgraded: False positives with reasoning
  • AI Identified (Gap Analysis): Issues tools missed

Gap Analysis Section: List issues found via manual review that tools cannot detect (business logic, design flaws, diff-specific concerns)

Summary Statistics:

  • X tool findings triaged (Y confirmed, Z false positives)
  • N gap analysis issues identified
  • Top 3 most critical issues to address first

Return Value

Console Output:

  • Summary of tools executed (available vs missing)
  • Count of findings by severity (after AI triage)
  • Top 3 critical issues with file:line references
  • Path to detailed report

Report File: .work/security-review/report-{timestamp}.md

  • Tool findings with AI triage and exploitability analysis
  • Gap analysis for issues tools missed
  • Concrete fix suggestions with code examples

Format: Markdown optimized for reading and sharing with team

Examples

Example 1: Review changes in current PR/branch (default)

/utils:review-security

Output:

Security Review - Diff Mode
Tools: gitleaks ✓ | gosec ✓ | bandit ✗ (not installed) | semgrep ✗

Analyzed: 3 changed files (24 lines modified)
Findings: 1 CRITICAL, 2 HIGH, 1 FALSE POSITIVE

Top Issues:
1. [CRITICAL] Hardcoded AWS key in config/aws.go:23 (gitleaks)
2. [HIGH] SQL injection in handlers/user.go:145 (gosec - confirmed)
3. [HIGH] Removed auth check in api/delete.go:67 (AI - gap analysis)

Report: .work/security-review/report-20241216-143022.md

Example 2: Review specific files

/utils:review-security pkg/handlers/*.go config.yaml

Example 3: Review all Python files

/utils:review-security "**/*.py"

Arguments

$@ (optional): File paths or glob patterns

  • No arguments: Analyzes git diff (changed files only) - ideal for PR reviews
  • With arguments: Analyzes specified files/patterns
    • Single file: config.go
    • Multiple files: main.go config.go utils.go
    • Glob pattern: "pkg/**/*.go" "**/*.py"

What This Command Does NOT Do

  • Replace CI/CD security gates: Deterministic tools (gosec, snyk, etc.) should still run in pipelines
  • Provide deterministic results: AI analysis is contextual and may vary
  • Scan dependencies: Use npm audit, snyk, trivy, or safety for dependency vulnerabilities
  • Guarantee complete coverage: This is a development aid, not a compliance certification tool

Notes

Tool Installation: The command provides platform-aware installation suggestions when tools are missing. Common installation methods:

Best Practices:

  • Run this command before creating PRs to catch issues early
  • Review AI triage reasoning - it may miss edge cases
  • Use in combination with peer code review, not as replacement
  • For compliance/audit needs, rely on deterministic tool output in CI/CD

Sponsors

Details

Marketplace
openshift-eng/ai-helpers
Source
plugins/utils
Category
Tooling
Keywords
utilities, helpers, misc

More from openshift-eng/ai-helpers

All 56