/gh-issues

name: gh-issues
description: "Process GitHub issues as an automation queue: /gh-issues lists and filters issues, confirms selected issue numbers, deduplicates fix/issue-* work, delegates one focused PR per issue, and can monitor issue-fix PR review feedback. Use this instead of general PR workflow tools only when the entry point is a GitHub issue list or issue-fix queue."
user-invocable: true
disable-model-invocation: false
requires:
  bins:
    - git
metadata:
  hybridclaw:
    category: development
    short_description: "GitHub issue queue automation."
    tags:
      - engineering
      - github
      - issues
      - pull-requests
      - delegation
    related_skills:
      - github-pr-workflow
      - code-review
    install:
      - id: gh
        kind: brew
        formula: gh
        bins: ["gh"]
        label: "Install GitHub CLI (brew)"

GitHub Issues

You are an issue queue orchestrator. Follow the phases in order. Do not run processing preflight before the user has selected issues.

Live data invariant: every issue-list or "no issues matched" response must be based on a successful GitHub data tool call made in the current turn. Never reuse issue tables, issue numbers, labels, or "no matches" results from memory, conversation history, session search, cached summaries, or previous turns. If no current-turn GitHub data call succeeds, report the fetch failure instead of answering from stale context.

Use this skill for `/gh-issues` requests that start from a GitHub issue list, batch issue filters, `fix/issue-*` branch automation, issue-fix PR review monitoring, or scheduled issue queue follow-up.

Do not use this skill for ordinary branch, commit, push, PR, CI, or review work that starts from the current branch or a known PR. Use a GitHub PR workflow or code-review skill for those.

Phase 1 - Parse Arguments

Parse the arguments after `/gh-issues`.

Positional:

• `owner/repo`: source repository. If omitted, infer it from

`git remote get-url origin`; if that is unavailable, ask for `owner/repo`. If `owner/repo` is provided explicitly, do not run any local git discovery during parsing or issue listing. Local checkout checks belong only to Phase 4 after issue selection.

Flags:

| Flag | Default | Description | | --- | --- | --- | | `--label <label>` | none | Filter by label. | | `--limit <n>` | `10` | Max issues to fetch per poll. | | `--milestone <milestone>` | none | Filter by milestone title. | | `--assignee <assignee>` | none | Filter by assignee; resolve `@me` with `gh api user --jq .login`. | | `--state <open\|closed\|all>` | `open` | Issue state. | | `--fork <owner/repo>` | none | Push branches to a fork while PRs target the source repo. | | `--watch` | false | Fetch the issue list normally, then schedule recurring issue and review follow-up after the first confirmed run. | | `--interval <minutes>` | `5` | Watch interval; only valid with `--watch`. | | `--cron` | false | Recurring-run mode: process at most one eligible item and exit. | | `--dry-run` | false | Fetch and display issues only. | | `--yes` | false | Process listed issues without another confirmation. | | `--reviews-only` | false | Skip issue fetching and process issue-fix PR review feedback. | | `--model <model>` | none | Optional model override for delegated tasks. | | `--notify-channel <target>` | none | Optional HybridClaw message target for final summaries only. |

Derived values:

• `SOURCE_REPO`: issue and PR target repository.
• `PUSH_REPO`: `--fork` value, otherwise `SOURCE_REPO`.
• `PUSH_OWNER`: owner portion of `PUSH_REPO`.
• `PUSH_REMOTE`: `fork` when `--fork` is used, otherwise `origin`.
• `FORK_MODE`: true when `--fork` is used.
• `SOURCE_REPO_SLUG`: `SOURCE_REPO` with `/` replaced by `-`.

Mode routing:

• If `--reviews-only` is set, run authentication, then jump to Phase 6.
• If `--cron` is set, force `--yes`.
• If `--watch` is set, use `--interval`, defaulting to 5 minutes. Do not skip

issue fetching or confirmation. The first watch turn follows Phases 2 and 3 like a normal run.

Phase 2 - Authenticate And Fetch Issues

GitHub CLI is preferred but optional. First check whether it exists:

command -v gh

If `gh` exists, prefer GitHub CLI authentication:

gh auth status

If `gh` is unavailable or authentication fails, use the GitHub REST API through the `http_request` tool with `bearerSecretName: "GH_TOKEN"`. The gateway resolves `GH_TOKEN` from the encrypted secret store; do not ask the shell for `GH_TOKEN`, do not echo tokens, and do not use `curl` for authenticated GitHub API calls. If neither `gh` auth nor stored secret `GH_TOKEN` works, ask the user to run `gh auth login` or store a GitHub token in this order: browser admin at `/admin/secrets`, `/secret set GH_TOKEN <token>` in browser `/chat` or TUI, then local console fallback `hybridclaw secret set GH_TOKEN <token>`.

When not in `--reviews-only`, fetch issues with a current-turn GitHub data call. Primary `gh` path:

gh issue list --repo "$SOURCE_REPO" --state "$STATE" --limit "$LIMIT" \
  --json number,title,labels,assignees,url,body

Add optional filters only when present:

• `--label "$LABEL"`
• `--milestone "$MILESTONE"`
• `--assignee "$ASSIGNEE"` after resolving `@me`

API fallback path with `gh` still available:

gh api "repos/$SOURCE_REPO/issues" \
  -f state="$STATE" -f per_page="$LIMIT"

API fallback path without `gh`: call `http_request` with `bearerSecretName: "GH_TOKEN"` and the GitHub URL. Example request shape:

{
  "method": "GET",
  "url": "https://api.github.com/repos/{SOURCE_REPO}/issues?state={STATE}&per_page={LIMIT}",
  "bearerSecretName": "GH_TOKEN",
  "headers": {
    "Accept": "application/vnd.github+json"
  }
}

Add API query parameters only when present:

• `labels=$LABEL`
• `assignee=$ASSIGNEE` after resolving `@me` through `GET /user`
• `milestone=$MILESTONE_NUMBER`; if the user supplied a title, first list

milestones and ma