github

name

github

description

Use the gh CLI for GitHub work across the software development lifecycle: planning (issues, milestones, labels), development (branches, draft PRs), review (PR review, checks, comments), release (tags, releases, changelogs), and maintenance (triage, backlog hygiene, project health). Use whenever the user asks to create or triage issues, label or route issues, review or shepherd a PR, inspect checks, manage a backlog, prepare release notes, evaluate a repo's health, or otherwise operate on a GitHub repository.

GitHub (across the SDLC)

Use GitHub's gh CLI as the primary interface for repository work. The user's gh is already authenticated. Prefer gh over raw API guessing; use gh api only when gh issue/gh pr/gh repo don't expose the data you need.

There is no custom wrapper tool — call gh directly via bash. Safety for destructive/outbound gh actions (pr merge, release/repo/issue delete, pr review submit, mutating gh api) is enforced deterministically by the permission-gate extension, which will prompt before they run. Your job is to use gh well and exercise judgment; the gate is the backstop.

The Lifecycle Map

Route the user's request to the right phase. Each phase has a workflow below.

Phase	Typical asks	Jump to
Plan	create issues, milestones, set up labels	Plan
Develop	branches, draft PRs, link issues	Develop
Review	review a PR, inspect checks, is it ready	Review
Release	release notes, tags, changelogs	Release
Maintain	triage, labels, backlog, project health	Maintain

Operating Principles

• Read before writing. Inspect the issue, PR, labels, checks, and repo conventions before recommending or applying changes.
• Prefer repo conventions over generic taxonomy. Inspect labels, milestones, templates, and recent similar issues/PRs before proposing changes.
• Mutations require explicit user intent. Do not comment, label, assign, close, reopen, edit, approve, request changes, merge, create/delete labels, or do bulk operations unless the user clearly asked. (The permission-gate will also prompt on the destructive ones — but ask anyway for the merely-outbound.)
• Show a preview for bulk changes unless told to apply without confirmation.
• AI-authored triage comments/issue bodies must start with > *This was generated by AI during triage.*.
• Lead with the decision, then the evidence.

Inspecting State (read-only, use freely)

gh repo view --json nameWithOwner,description,defaultBranchRef,repositoryTopics
gh label list --limit 200
gh issue list --state open --limit 100 --json number,title,labels,assignees,milestone,updatedAt,createdAt,url
gh pr list   --state open --limit 100 --json number,title,author,labels,reviewDecision,mergeStateStatus,updatedAt,url
gh issue view N --comments --json number,title,body,author,labels,assignees,milestone,state,comments,url
gh pr view N --comments --json number,title,body,author,baseRefName,headRefName,commits,files,labels,reviews,reviewDecision,mergeStateStatus,statusCheckRollup,comments,url
gh pr diff N
gh pr checks N

For GitHub-hosted open-source projects, mcp_deepwiki_ask_question gives a fast structured read of a repo's architecture and docs to complement gh.

---

Plan

Issues, milestones, and label scaffolding — the start of the lifecycle.

• Create an issue: draft a clear title + body, set a category label, show the draft, confirm, then gh issue create. Triage-authored bodies include the AI disclaimer line.
• Milestones / projects: gh issue list --milestone "...", gh api for project boards when needed.
• Label scaffolding: see Label Management under Maintain.

When creating issues during triage, start at needs-triage unless told otherwise (see the triage label model under Maintain).

---

Develop

• Inspect branch/PR state with the read-only commands above.
• Draft PRs: gh pr create --draft after confirming title/body/base.
• Link issues: reference Closes #N in the PR body so the issue auto-closes on merge.
• Use local repo tools (read, grep, find) for code context; use gh only for GitHub-side state.

---

Review & PR Shepherding

Default to a code-review mindset. Findings are the primary output. Do not approve, request changes, comment, or merge unless explicitly asked (the gate will prompt on review-submit and merge regardless).

Reviewing a PR

1. Inspect metadata, body, changed files, commits, reviews, checks, linked issues.
2. Read the diff (gh pr diff N); inspect local files for context.
3. Check behavior regressions, missing tests, security, API/compat, migrations, performance, error handling, maintainability.
4. Separate blocking findings from non-blocking suggestions.

Report:

**Findings**
- {severity}: {issue with file/line reference and why it matters}

**Open Questions**
- {question or assumption, if any}

**Testing Gaps**
- {missing or unverified coverage, if any}

**Summary**
{brief readiness assessment}

If there are no findings, say so and note residual risks/testing gaps.

Is this PR ready? (shepherding)

Check: failing/pending checks, merge conflicts/blocked state, unresolved review threads, missing reviewers/approvals, missing linked issue/changelog/tests, staleness vs base. Report:

**Readiness:** {ready | blocked | needs review | needs author update}
**Blockers:** {short list or "none found"}
**Recommended next step:** {one concrete action}

---

Release

Use when asked for release notes, tags, or changelogs.

1. Determine scope: milestone, tag range, merged-PR range, date range, or PR list.
2. Fetch merged PRs and linked issues.
3. Group by user-facing change: Added, Changed, Fixed, Deprecated, Removed, Security, Docs, Internal.
4. Avoid internal implementation detail unless user-relevant; include contributors if asked.
5. gh release create / gh release edit only after confirmation (the gate prompts on these).

---

Maintain

Issue Triage

Stricter workflow when routing issues to agents/humans or rejecting requests.

Label model: every triaged issue carries exactly one category label and one state label.

• Category: bug (broken) · enhancement (new/improvement).
• State: needs-triage · needs-info · ready-for-agent · ready-for-human · wontfix.

Transitions: unlabeled → needs-triage → (needs-info | ready-for-agent | ready-for-human | wontfix). needs-info → needs-triage once the reporter replies. Flag unusual transitions before applying.

Bootstrap labels (only when the user asks to set up the workflow; idempotent):

gh label list --limit 100
gh label create bug             --color d73a4a --description "Something is broken" || true
gh label create enhancement     --color a2eeef --description "New feature or improvement" || true
gh label create needs-triage    --color fbca04 --description "Maintainer needs to evaluate" || true
gh label create needs-info      --color d4c5f9 --description "Waiting on reporter for more info" || true
gh label create ready-for-agent --color 0e8a16 --description "Ready for an autonomous agent" || true
gh label create ready-for-human --color 1d76db --description "Needs human implementation" || true
gh label create wontfix         --color ffffff --description "Will not be actioned" || true

What needs attention: present three buckets, oldest first — unlabeled (gh issue list --search "no:label" --state open), needs-triage, and needs-info issues with new reporter replies. Counts + one-line summaries.

Triage a specific issue:

1. gh issue view N --comments — full context.
2. Inspect repo labels, templates, CONTRIBUTING/scope docs, similar issues.
3. For bugs, attempt reproduction before asking questions; report repro success/ fail/blocked.
4. Recommend category + state with evidence; wait for direction before applying.
5. If underspecified → draft answerable questions, recommend needs-info.
6. If ready → write a durable agent brief before ready-for-agent / ready-for-human (see below).

Report triage as:

**Category:** {bug | enhancement | unclear}
**Recommended state:** {needs-triage | needs-info | ready-for-agent | ready-for-human | wontfix}
**Recommended labels:** `{category}`, `{state}`, `{repo-native}`
**Priority:** {P0 | P1 | P2 | P3 | unclear}
**Next action:** {what should happen next}
**Reasoning:** {short evidence-based explanation}

Apply transitions with gh issue edit N --add-label LABEL --remove-label OLD.

Agent Briefs (the contract for ready-for-agent / ready-for-human)

When an issue moves to ready-for-agent/ready-for-human, post a brief that is the authoritative spec. Principles:

• Durable over precise — describe interfaces, types, behavioral contracts. Do NOT reference file paths or line numbers (they go stale).
• Behavioral, not procedural — say what the system should do, not how to implement it. The agent explores fresh.
• Complete, testable acceptance criteria — the agent must know when it's done.
• Explicit scope boundaries — state what's out of scope.

> *This was generated by AI during triage.*

## Agent Brief

**Category:** bug / enhancement
**Summary:** one-line description of what needs to happen

**Current behavior:**
{what happens now}

**Desired behavior:**
{what should happen after the work is complete, incl. edge/error cases}

**Key interfaces:**
- `TypeName` / `functionName()` / config shape — what should change and why

**Acceptance criteria:**
- [ ] Specific, testable criterion

**Out of scope:**
- Adjacent thing that should NOT be changed

For ready-for-human, add Why not delegated: (judgment call, external access, design decision, manual testing).

Needs-Info Template

> *This was generated by AI during triage.*

## Triage Notes

**What we've established so far:**
- point

**What we still need from you (@reporter):**
- specific, answerable question

Label Management

When asked to clean up / standardize / audit labels:

1. List labels with descriptions and colors.
2. Identify the taxonomy (type/area/priority/status/size/etc.).
3. Find duplicates, ambiguous, unused, undescribed, inconsistent labels.
4. Recommend minimal changes that reduce confusion without breaking workflows.
5. Produce a before/after table; confirm before applying. Avoid label sprawl — prefer a small orthogonal taxonomy.

Backlog Hygiene

For stale items, duplicates, summaries, maintainer sweeps:

1. Query a bounded set (respect user scope).
2. Group by status/area/priority/age/assignee/milestone/likely-action.
3. Recommend: keep, needs-info, label, assign, close-stale, close-duplicate, convert-to-discussion, promote-to-roadmap.
4. Draft comments for stale/needs-info items when useful.
5. Never close or bulk-comment without explicit confirmation.

Project Health (evaluating a repo)

Inspect: recent releases & changelog quality; open-issue volume/age/maintainer responsiveness/recurring themes; PR activity, review latency, merge pattern; security policy, license, governance, bus-factor; docs & migration guides; breaking-change/deprecation discipline. Use gh + mcp_deepwiki_ask_question. Do not treat star count as a primary health metric.

---

Mutation Safety (require explicit intent)

Posting comments; adding/removing/creating/deleting labels; editing titles/ bodies; assign/unassign; open/close/reopen/lock/transfer/convert issues; approve/request-changes/dismiss/submit reviews; merge/close/reopen/ready/ rebase PRs; create milestones/releases/projects/discussions; repo settings.

If wording is ambiguous, draft the proposed mutation and ask before applying. The permission-gate will additionally prompt on the destructive/outbound ones.

Reporting Style

• File/line references for PR findings; issue/PR numbers + URLs for summaries.
• Concise but evidence-backed. Lead with the decision/recommendation.
• Don't fabricate; don't bury the answer under raw notes — synthesize.