gh

name

gh

description

The gh-CLI playbook for a fray-ui worker signed into GitHub (invoke as fray:gh). Load this whenever your effort touches GitHub — reading or triaging an issue or PR, reviewing a diff, checking CI/release status, or searching issues/PRs — to use `gh` eagerly and correctly: the read-vs-write boundary (never comment/label/close/merge unless the human asks), optional toon use for large JSON, concrete read recipes, and active Monitor/background-Bash CI/PR watches. Only meaningful when you are signed in (`gh auth status --active` exit 0); the session-seed hook injects a pointer here when you are.

fray:gh — the gh-CLI playbook

You are a fray-ui worker and you are signed into the gh CLI in a GitHub repo (the session-seed hook confirmed gh auth status --active before pointing you here). gh is the fastest path to issue / PR / CI / release context — reach for it before guessing, and prefer it over scraping the web UI or reasoning from memory.

This skill is the full playbook the injected ⟦gh available⟧ block summarizes: the read-vs-write boundary, optional toon use for large JSON, concrete read recipes, and how to keep a CI/PR watch active until the next actionable event.

The one hard rule — READ freely, WRITE only when asked

gh can mutate the repo, and your token has the scopes to do it. Do not. Unless the human explicitly asks in this session, you are strictly read-only:

• NEVER comment, review, approve, request-changes, label, assign, milestone, edit, close, reopen, merge, or push — no state change of any kind on GitHub.
• Your deliverable is your final message (a findings write-up, a review, a recommendation) — NOT a GitHub post. Producing the review in-session is the job; posting it is a separate action the human authorizes.
• If posting would genuinely help, don't just do it — ask with a two-option ```question block ("A. Post this review to the PR / B. Keep it in-session only", Recommendation), then rest. When the destructive edge is real (a force-merge, a close), that's a ```question danger gate.
• When the human HAS asked you to write, do exactly the scoped thing and report the resulting URL — nothing extra.

There is no server-side enforcement of this; the boundary is yours to hold.

toon — pipe LARGE, FLAT gh JSON through the shim

toon (Token-Oriented Object Notation) losslessly re-encodes JSON ~30–40% smaller for LLM context. Use it only when a gh … --json result you're reading into YOUR context is large and flat (a list page: gh issue list, gh pr list, gh search, gh api list endpoints) and command -v toon succeeds. It is optional: do not install it or assume a home-directory-specific location.

if command -v toon >/dev/null 2>&1; then
  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50 | toon
else
  gh issue list -R OWNER/REPO --json number,title,url,updatedAt --limit 50
fi

Skip toon for tiny payloads (a handful of fields, one item) and for deeply-nested JSON (reactionGroups, review threads, nested files) — nesting defeats tabularization, so the savings collapse to noise and you add a parse tax for yourself. A single gh pr view N --json … is small — read it raw.

Read recipes

Always scope with -R OWNER/REPO so a command is dir-independent, and prefer --json <fields> (+ -q <jq>) so you pull exactly what you need.

Issues

gh issue view N -R OWNER/REPO --comments                          # full thread, human-readable
gh issue view N -R OWNER/REPO --json title,body,labels,state,url  # structured
gh issue list -R OWNER/REPO --search "sort:updated-desc" --json number,title,url,updatedAt --limit 30
gh issue list -R OWNER/REPO --search "sort:reactions-desc is:open" --json number,title,url --limit 30

PRs + diffs

gh pr view N -R OWNER/REPO --json title,body,state,labels,files,additions,deletions,url
gh pr diff N -R OWNER/REPO                # the unified diff — pipe through toon only if HUGE and you just need shape
gh pr checks N -R OWNER/REPO              # CI check rollup for the PR
gh pr view N -R OWNER/REPO --comments     # review threads + conversation

Read the changed files in context, not just the hunks — gh pr diff shows what changed, but correctness lives in the surrounding code.

Reading ONE review (what a pr-watch wake hands you)

A wake permalink ending #pullrequestreview-<id> is a review, and a review's body is routinely empty — review apps (pullfrog, coderabbit) and humans doing an inline pass put every word in the review's inline comments. Reading the body and concluding the review is empty is the wrong turn here. One endpoint answers it in one call:

gh api --paginate repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID/comments \
  --jq '.[] | "\(.path):\(.line // .original_line // "file")\n\(.body)\n"'

Do not sweep …/pulls/N/comments and filter by pull_request_review_id — it pulls the whole PR's history to find a handful of lines. Add the review's own body only if you need it (gh api repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID --jq .body). A #issuecomment-<id> permalink is the other shape and does carry its substance in its body: gh api repos/OWNER/REPO/issues/comments/ID --jq .body.

--paginate is the default for any list endpoint. gh api returns 30 items per page and caps per_page at 100, silently — a truncated page reads exactly like "that's all there is," so a missing --paginate becomes a wrong answer rather than an error.

CI / runs / releases

gh run list -R OWNER/REPO --branch BRANCH --limit 10
gh run view RUN_ID -R OWNER/REPO --log-failed        # just the failing step logs
gh release view -R OWNER/REPO                         # latest release

Search (across issues/PRs)

gh search issues -R OWNER/REPO "crash on startup" --state open --json number,title,url --limit 30
gh search prs --repo OWNER/REPO "author:@me" --json number,title,url --limit 30

Use search to find duplicates, related work, and prior art before you conclude something is novel.

Raw API for anything the porcelain doesn't cover:

gh api repos/OWNER/REPO/commits/SHA/check-runs --jq '.check_runs[] | {name, conclusion}'
gh api "repos/OWNER/REPO/issues?state=open&labels=bug&per_page=50" | { command -v toon >/dev/null 2>&1 && toon || cat; }

Keep GitHub automation active

CI, automated review, releases, merge queues, and already-authorized merge progression are work you can observe with gh; they do not earn an awaiting fence. Keep a live operation attached to the thread and continue when it reports.

Select monitor tooling explicitly

Before launching any CI/review monitor, inspect project-local AGENTS.md, active skills, repository docs, package.json scripts, and declared monitor tooling. Prefer an explicit project-local monitor only if it documents terminal semantics for this gate. Validate its absolute command and terminal event/exit contract before launch. If declared tooling is missing, invalid, or has no terminal semantics, stop and report that configuration error; never silently shadow it with a Fray script, and never execute a monitor merely because its filename looks plausible.

When no project monitor is declared, the bundled fallback scripts are <this-skill-dir>/scripts/ci-watch.mjs and review-watch.mjs. They are generated byte-for-byte from Fray's canonical monitors/ source and require only Node plus logged-in gh. Their stdout is fray.github-monitor/v1 NDJSON: status means keep waiting; terminal is a verdict. They join exact-head workflow runs with PR checks, keeping ACTION_REQUIRED pending, and baseline every review and comment so any new one wakes — bot or human, with no actor filter. A GitHub/auth error is terminal exit 3; SIGINT/SIGTERM produces terminal cancelled and exit 130. A --once pending/baseline snapshot is deliberately non-terminal exit 0. For CI, retries are collapsed only within the same workflow name and event; distinct exact-head events such as push and pull_request both contribute to the aggregate verdict.

• One-shot completion: launch Bash with run_in_background: true, for example gh run watch RUN_ID -R OWNER/REPO --exit-status or a repo watcher that exits when all PR checks settle. The completion task-notification re-invokes you. Diagnose/fix on red; continue the authorized release/merge path on green.
• State transitions: use native Monitor with a quiet loop that prints only changes or the terminal event. It is the Claude adapter for the selected script; do not make a sub-agent the monitor abstraction. Finite monitors run up to one hour; persistent: true runs until TaskStop or the Claude session ends. Stop a watch once its gate is obsolete.
• A background Bash launch exposes an output-file path. Use Read on that path only for diagnostics; TaskOutput is deprecated. Do not fake waiting with echo waiting or sleep-only Bash calls.

Both mechanisms are session-bound. If the next check deliberately belongs at a named wall-clock instant, park with a durable timer: fence. If a specific external human reviewer/approver is the only remaining gate, park with human: <actor + exact action>. For a GitHub PR, pair it with pr-watch: OWNER/REPO#NUMBER: fray-ui baselines current reviews/comments and wakes on ANY new activity after the fence — bot or human — durably across restarts. Otherwise optionally pair a timer for a scheduled recheck. The dashboard operator's own go/no-go remains a ```question block. pr: / ci: / session: awaiting hints are legacy compatibility only — do not emit them for new automated waits.

Fitting gh work into your thread type

• Investigating an issue (a research thread): reproduce → trace to file:line (cite every load-bearing claim) → recommend the smallest correct fix; read the full thread and linked issues/PRs with gh for context. Don't implement — stop at the recommendation. Handback = findings in your final message.
• Reviewing a PR (an audit thread): read the diff AND the files in context, verify correctness/edges/tests, check CI (gh pr checks), then produce a review (blocking issues vs nits, each citing file:line) as your final message. Approve/merge only if explicitly asked.

In both cases: read-only on GitHub unless told otherwise, and the review/findings live in your session, not in a GitHub post.