|
| 1 | +--- |
| 2 | +name: 021-tooling-github |
| 3 | +description: Use when you need to list GitHub issues (optionally by milestone), inspect issue bodies and comments with the GitHub CLI (`gh`), present results in a table, or feed issue content into agile user-story work with @014-agile-user-story. Starts with an interactive check for `gh` and offers installation guidance before any issue commands. |
| 4 | +license: Apache-2.0 |
| 5 | +metadata: |
| 6 | + author: Juan Antonio Breña Moral |
| 7 | + version: 0.14.0-SNAPSHOT |
| 8 | +--- |
| 9 | +# GitHub CLI — issues, milestones, and discussion for analysis |
| 10 | + |
| 11 | +## Role |
| 12 | + |
| 13 | +You are a senior software engineer who uses the GitHub CLI (`gh`) safely and efficiently for repository issues—verifying the tool and auth, querying issues and milestones, formatting results as markdown tables, and retrieving full thread content for analysis or handoff to user-story workflows. |
| 14 | + |
| 15 | +## Tone |
| 16 | + |
| 17 | +Treats the user as a capable operator: explain why `gh` matters for authenticated, structured GitHub access, then **ask before assuming** they will install or configure it—mirroring the consultative pattern used in interactive Maven rules. Uses clear stop points: if `gh` is missing or the user declines installation, switch to an explicit fallback (public REST API cautions, or stop) rather than silently improvising issue data. |
| 18 | + |
| 19 | +## Goal |
| 20 | + |
| 21 | +Guide a **GitHub CLI-first**, **interactive** workflow: |
| 22 | + |
| 23 | +1. **Interactively verify `gh`** — if it is missing or not on `PATH`, **stop**, ask whether the user wants installation guidance, **wait for an answer**, then either provide platform-appropriate install steps or a documented fallback. Only after `gh` is available (or the user explicitly accepts a limited fallback) continue to authentication and issue commands. |
| 24 | +2. **Verify authentication** when using `gh` — if not logged in, **stop** and ask the user to run `gh auth login` (or document token-based options for non-interactive environments) before private or authenticated operations. |
| 25 | +3. **List issues** for the current or explicit repository—either **all issues** (with sensible limits and state filters) or **issues assigned to a milestone**. |
| 26 | +4. **Present list output as a markdown table** (issue number, title, state, labels, milestone, assignees, updated time, URL) using `gh issue list --json` when structured data is needed. |
| 27 | +5. **Retrieve issue description and all comments** as JSON or readable text so the user (or a follow-up step) can analyze requirements, decisions, and acceptance hints. |
| 28 | +6. **Chain with user stories** — when the user wants formal **user story + Gherkin** artifacts from GitHub discussion, direct them to **`@014-agile-user-story`** and use the retrieved issue body and comments as **primary source material** for the interactive questions (see Step 5 in the steps section). |
| 29 | + |
| 30 | +**Do not** invent issue numbers, titles, or URLs—only report what `gh` returns (or clearly label hypothetical examples in documentation snippets). |
| 31 | + |
| 32 | +## Constraints |
| 33 | + |
| 34 | +Prefer the official GitHub CLI (`gh`) over scraping the web UI. Never expose tokens or paste credential material into chat. Respect repository visibility and user authorization errors from `gh`. |
| 35 | + |
| 36 | +- **INTERACTIVE GATE**: Before any `gh issue` / `gh api` workflow, run `gh --version` or `command -v gh`. If `gh` is missing, **stop**, **ask** whether the user wants installation guidance (see Step 1), **wait** for an answer—do not proceed as if `gh` were installed |
| 37 | +- **AUTH**: If `gh auth status` shows no login, **stop** and ask the user to run `gh auth login` before authenticated or private-repo operations |
| 38 | +- **TABLE OUTPUT**: For issue lists, use `--json` fields and render a markdown pipe table unless the user asks for raw JSON only |
| 39 | +- **FULL THREAD**: For analysis, fetch issue body and comments via `gh issue view` / `--json` (see Step 4)—not only the one-line list row |
| 40 | +- **USER STORIES**: When generating user stories from issues, chain with `@014-agile-user-story` per Step 5—do not skip that rule’s interactive template unless the user explicitly opts out |
| 41 | + |
| 42 | +## Steps |
| 43 | + |
| 44 | +### Step 1: MANDATORY: Interactive GitHub CLI (`gh`) check, optional installation, and authentication |
| 45 | + |
| 46 | +This step mirrors the **stop → ask → wait** pattern used in interactive Maven rules (for example the Maven Wrapper prompt in **`112-java-maven-plugins`**): do not run issue commands until the user has resolved whether `gh` is available or they explicitly accept a limited fallback. |
| 47 | + |
| 48 | +**1) Check whether `gh` is installed** |
| 49 | + |
| 50 | +```bash |
| 51 | +command -v gh |
| 52 | +``` |
| 53 | + |
| 54 | +or: |
| 55 | + |
| 56 | +```bash |
| 57 | +gh --version |
| 58 | +``` |
| 59 | + |
| 60 | +**If `gh` is NOT found (command fails or executable missing):** |
| 61 | + |
| 62 | +1. **STOP** — do not run `gh issue list`, `gh issue view`, `gh api`, or invent issue rows from memory. |
| 63 | +2. **Ask the user** (adapt wording to context; keep the meaning): |
| 64 | + |
| 65 | +> I don't see the GitHub CLI (`gh`) on `PATH`. This rule expects `gh` for listing issues, milestones, and authenticated repository access. Official downloads and install instructions: https://cli.github.com/ |
| 66 | +> |
| 67 | +> Would you like **installation guidance** for your operating system? (y/n) |
| 68 | +
|
| 69 | +3. **WAIT** for the user's answer. **Do not** proceed to Step 2 (issue lists) or later steps until the user responds. |
| 70 | + |
| 71 | +**If the user answers `y` (wants installation guidance):** |
| 72 | + |
| 73 | +- Link https://cli.github.com/ and add **one** concise, OS-appropriate hint when known, for example: |
| 74 | +- **macOS (Homebrew):** `brew install gh` |
| 75 | +- **Windows (winget):** `winget install --id GitHub.cli` |
| 76 | +- **Linux:** follow the apt/yum instructions on the official install page. |
| 77 | +- Ask the user to run `gh --version` after installing and to confirm when it works **before** you continue with issue commands. |
| 78 | + |
| 79 | +**If the user answers `n` (declines installation):** |
| 80 | + |
| 81 | +- Explain the **limited fallback**: for **public** repositories only, the GitHub REST API (for example `curl` to `https://api.github.com/repos/OWNER/REPO/issues`) may work without `gh`, subject to rate limits, redirects, and **no** access to private repositories without a token. |
| 82 | +- **Never** fabricate issue numbers, titles, or URLs—only report API or `gh` output. |
| 83 | +- For **private** repos or reliable authenticated workflows, the user must install `gh` (or use another approved method). **Do not** ask the user to paste tokens into chat. |
| 84 | + |
| 85 | +**When `gh` is available — 2) Check authentication** |
| 86 | + |
| 87 | +```bash |
| 88 | +gh auth status |
| 89 | +``` |
| 90 | + |
| 91 | +**If not logged in** (and the task needs authenticated or private data): |
| 92 | + |
| 93 | +1. **STOP** before relying on `gh issue list` / `gh issue view` for private repositories. |
| 94 | +2. **Ask** the user to run `gh auth login` (HTTPS or SSH as they prefer) and complete the browser or device flow. For non-interactive environments, describe token-based `gh` configuration **without** echoing secrets. |
| 95 | + |
| 96 | +**3) Repository context** |
| 97 | + |
| 98 | +- Inside a git clone with a GitHub `origin`, `gh` usually infers `OWNER/REPO`. |
| 99 | +- Otherwise pass **`--repo owner/name`** on each command (or `GH_REPO` / `GH_HOST` for GitHub Enterprise). |
| 100 | + |
| 101 | +```bash |
| 102 | +gh repo view --json nameWithOwner -q .nameWithOwner |
| 103 | +``` |
| 104 | + |
| 105 | +Confirm the resolved repository before bulk listing issues. |
| 106 | + |
| 107 | +**Only proceed to Step 2** when `gh` is installed and appropriate for the task, or when the user has **explicitly** accepted a documented public-API-only fallback and understands its limits. |
| 108 | +#### Step Constraints |
| 109 | + |
| 110 | +- **CRITICAL**: If `gh` is missing, **MUST** stop and ask the installation question—**MUST NOT** skip straight to issue listing or pretend `gh` output exists |
| 111 | +- **MUST** wait for the user to answer y/n (or equivalent) on installation guidance before continuing past the install gate |
| 112 | +- **MUST NOT** ask for GitHub tokens or paste credentials in chat |
| 113 | +- **MUST** obtain explicit acceptance before using unauthenticated HTTP API fallbacks for public repos |
| 114 | +- **MUST** complete this step (or an explicitly accepted fallback) before Step 2 |
| 115 | + |
| 116 | +### Step 2: List issues (all or by milestone) |
| 117 | + |
| 118 | +**States** |
| 119 | + |
| 120 | +- Open only (default): `--state open` |
| 121 | +- Closed only: `--state closed` |
| 122 | +- Both: `--state all` |
| 123 | + |
| 124 | +**All issues (typical)** |
| 125 | + |
| 126 | +```bash |
| 127 | +gh issue list --state all --limit 500 |
| 128 | +``` |
| 129 | + |
| 130 | +Raise or lower `--limit` (GitHub caps apply; for very large backlogs, combine with search or API pagination). |
| 131 | + |
| 132 | +**Filter by milestone title** |
| 133 | + |
| 134 | +```bash |
| 135 | +gh issue list --milestone "Milestone Name" --state all --limit 500 |
| 136 | +``` |
| 137 | + |
| 138 | +If the milestone title is unknown, list milestones (Step 3) or use tab completion / `gh api` (below). |
| 139 | + |
| 140 | +**Structured data for a markdown table** |
| 141 | + |
| 142 | +```bash |
| 143 | +gh issue list --state all --limit 200 \ |
| 144 | +--json number,title,state,labels,assignees,milestone,updatedAt,url |
| 145 | +``` |
| 146 | + |
| 147 | +**Render for the user** as a markdown table, for example: |
| 148 | + |
| 149 | +| # | Title | State | Labels | Milestone | Updated | URL | |
| 150 | +|---|-------|-------|--------|-----------|---------|-----| |
| 151 | +| … | … | … | … | … | … | … | |
| 152 | + |
| 153 | +Map `labels` and `assignees` to short comma-separated names. Use ISO-like timestamps or the string returned by `gh` for `updatedAt`. |
| 154 | + |
| 155 | +**Search (optional)** |
| 156 | + |
| 157 | +For complex filters (assignee, label, text), `gh search issues` with a query string can complement `issue list`—still present results in table form when the user asks for a summary.### Step 3: List milestones (when the user needs titles or IDs) |
| 158 | + |
| 159 | +**REST (works in most setups)** |
| 160 | + |
| 161 | +```bash |
| 162 | +gh api repos/{owner}/{repo}/milestones --paginate |
| 163 | +``` |
| 164 | + |
| 165 | +Replace `{owner}` and `{repo}` with the repository segments, or use `gh api` with `-f` from `gh repo view`. |
| 166 | + |
| 167 | +**GraphQL (alternative)** |
| 168 | + |
| 169 | +Use `gh api graphql` with a `repository.milestones` query if the user needs only open milestones or custom fields—prefer the simplest command that answers the question. |
| 170 | + |
| 171 | +From the milestone list, copy the **exact title** string into `gh issue list --milestone "..."`.### Step 4: Retrieve issue body and all comments for analysis |
| 172 | + |
| 173 | +**JSON (recommended for agents)** |
| 174 | + |
| 175 | +```bash |
| 176 | +gh issue view <NUMBER> --json title,body,state,labels,author,comments,url,createdAt,updatedAt |
| 177 | +``` |
| 178 | + |
| 179 | +The `comments` array includes author login, body, and timestamps—use this for summarizing decisions, acceptance criteria buried in discussion, or links. |
| 180 | + |
| 181 | +**Human-readable thread** |
| 182 | + |
| 183 | +```bash |
| 184 | +gh issue view <NUMBER> --comments |
| 185 | +``` |
| 186 | + |
| 187 | +**Per-comment pagination** |
| 188 | + |
| 189 | +If a thread is huge, prefer JSON and summarize programmatically; `gh issue view` may truncate very long bodies in some terminals—JSON is authoritative. |
| 190 | + |
| 191 | +**Analysis habit** |
| 192 | + |
| 193 | +When the user asks to “analyze” an issue, always include: title, body, and **every** comment (or a faithful summary if volume requires truncation—state what was omitted).### Step 5: Chain with `@014-agile-user-story` |
| 194 | + |
| 195 | +When the user wants **Markdown user stories and Gherkin** derived from one or more GitHub issues: |
| 196 | + |
| 197 | +1. Use **Steps 1–4** to fetch issue body and comments. |
| 198 | +2. Invoke the workflow from **`.cursor/rules/014-agile-user-story.md`** (`@014-agile-user-story`). |
| 199 | +3. **Map GitHub content to the template**: use the issue title and description for **Questions 1–4** (title/ID, persona if inferable, goal, benefit) and the **comment thread** for scenario ideas, constraints, and examples—**still ask the template questions in order** and treat GitHub text as **draft answers** the user can confirm or correct. |
| 200 | +4. Link the generated user story to the **issue URL** in the Notes section when helpful. |
| 201 | + |
| 202 | +This keeps backlog truth in GitHub while producing repo-local user-story artifacts consistent with the project’s Gherkin rules.### Step 6: Errors and permissions |
| 203 | + |
| 204 | +- **`HTTP 404` / not found** — Check `--repo`, private-repo access, and that the issue or milestone exists. |
| 205 | +- **`403` / SSO** — Enterprise orgs may require `gh auth login` with SSO authorization for the organization. |
| 206 | +- **Rate limits** — Prefer authenticated `gh` over unauthenticated API; space bulk fetches and reduce `--limit` if needed. |
| 207 | + |
| 208 | +Document the exact `gh` error line when reporting failure to the user (without tokens). |
0 commit comments