github

# GitHub

## Overview

Prefer `gh` for all GitHub operations. The default goal is to complete the full GitHub flow with the least possible user effort: detect existing authentication first, reuse it if available, and only ask the user for the smallest missing step.

Never ask the user to manually perform a long GitHub setup if the agent can check, reuse, or finish it directly.

## Core Rules

- Prefer `gh` over raw GitHub API calls.
- Prefer existing authenticated state over asking for new credentials.
- Prefer non-interactive checks before prompting the user.
- Prefer the smallest unblock request:
  - paste a one-time code
  - confirm browser login
  - provide a PAT
  - confirm repository visibility
- Do not ask the user to manually create the repository if `gh` can do it.
- Do not ask the user to manually add remotes, initialize Git, or push if the agent can do it.
- Never print, echo, log, summarize, or restate secrets.
- Never store secrets in files, commits, repo config, docs, examples, or chat summaries.
- Never switch credential strategy unless the current one actually fails.

### Interactive login driving rules

When using `gh auth login` through a shell session, do not assume the browser login step has started after the first prompt or after sending one key.

You must continue driving the interactive flow until there is explicit evidence of one of these states:

1. GitHub CLI has clearly started browser/device authentication
2. GitHub CLI is explicitly waiting for the user to complete external authentication
3. GitHub CLI reports that authentication succeeded
4. GitHub CLI reports a real error and cannot continue

While driving the login flow:

- keep polling the session after each input
- handle intermediate prompts such as protocol selection, SSH/HTTPS choice, credential helper confirmation, browser/device flow confirmation, or similar setup questions
- use minimal inputs such as `enter`, arrow keys, `y`, `n`, or short submitted text as needed
- do not stop after only one successful prompt response
- do not tell the user that the browser has opened unless the command output explicitly indicates that a browser login or web flow has started
- do not tell the user that login is complete unless the command output explicitly indicates success

Acceptable evidence that browser or external auth has actually started includes output such as:

- a message that a browser is being opened
- a URL to visit
- a device code to enter
- explicit wording that GitHub authentication is waiting for completion

If the shell session remains running but only shows that an earlier prompt was answered, continue polling instead of summarizing the state prematurely.

Only ask the user to act when the output clearly shows an external action is now required.

When the user says they completed browser or device authorization, do not start a new `gh auth login` flow immediately.

Instead:

1. continue polling the existing shell session if it is still running
2. wait for explicit success or failure from that same session
3. only if that session has exited or is unrecoverable, then check `gh auth status`
4. only start a brand-new login flow if the previous login session has clearly failed or been closed

If the shell output contains prompts like:

- "Press Enter to open ..."
- "Press Enter to continue"
- similar one-step local confirmation prompts

then send `enter` automatically and continue polling the same session.

Do not stop at that prompt.
Do not ask the user to confirm completion yet.
Do not start a new login flow while this session is still running.

## Credential Handling Priority

### 1. Reuse `gh` authentication first

Check whether `gh` exists and is already authenticated.

Use this path when possible:

- `gh auth status`
- if authenticated, continue directly with:
  - repo detection
  - `gh repo create`
  - remote setup
  - push

If `gh` is authenticated, do not ask the user for tokens, passwords, SSH keys, or browser login.

### 2. If `gh` exists but is not authenticated, log in with `gh` directly

If `gh` is installed but not authenticated, use `gh auth login` directly and continue the GitHub flow after login succeeds.

Preferred order:

1. browser/web login via `gh auth login -h github.com -w`
2. standard interactive `gh auth login -h github.com`
3. PAT-based login only if the normal `gh` login path is unavailable or fails

Rules:

- do not switch away from `gh` login unless it actually fails
- do not ask the user to manually create repositories or configure git
- do not ask the user to perform a long GitHub setup outside the login itself
- continue automatically as soon as login succeeds

When login requires user interaction:

- ask for only the smallest possible action
- examples:
  - “Please complete the GitHub browser login that just opened.”
  - “Please finish the GitHub CLI login prompts.”
  - “Please paste a GitHub PAT with repo access.”

After login succeeds, continue directly with:

- repo detection
- `gh repo create`
- remote setup
- push

### 3. If `gh` is unavailable, try to install it first

If `gh` is missing:

- first try to install `gh` automatically using the platform's normal package manager or a reasonable official installation path
- prefer non-interactive installation methods when available
- after installation, re-check whether `gh` exists and continue with the normal `gh`-first flow
- only fall back away from `gh` if installation actually fails, is blocked by the environment, or would require disproportionate user effort

Acceptable install attempts include examples like:

- Homebrew on macOS
- `apt`, `dnf`, or similar package managers on Linux
- `winget` or other normal package-manager paths on Windows

Rules:

- do not ask the user to install `gh` manually before you have tried a reasonable automatic install path
- do not switch to a different credential strategy just because `gh` is missing initially
- if installation fails, summarize the blocker briefly and then cont