Stack number as primary identifier

[skarim]

Builds on the Stacks REST API migration and newly available stack number. Now that the API exposes each stack's number (the repo-scoped identifier shown in the GitHub stack UI) this makes it the primary way to reference a stack in the CLI and surfaces it throughout the output and TUIs.

What's new

• gh stack checkout <stack-number>. A bare number is now interpreted first as a stack number, falling back — in order — to a locally tracked PR number, a PR number whose stack is discovered from GitHub, and finally a branch name. Existing PR-number, PR-URL, and branch-name usage is unchanged.
• gh stack unstack [<stack-number>]. An optional positional argument targets a specific locally tracked stack instead of the current one.
• The stack number is shown wherever it's known:
  • appended to submit / link / checkout / unstack success messages, e.g. Created stack with 3 PRs (stack #42),
  • as a Stack #N line in gh stack view and the stack-view TUI header,
  • in the submit TUI — a Stack #N • repo header line and a STACK #N label on the left-panel timeline.

The number is persisted in the tracking file (.git/gh-stack) and backfilled from the API for stacks created before it was tracked.

Changes

Support addressing a stack by its stack number

• cmd/checkout.go — interpret a bare numeric argument as a stack number first (resolved via GetStack), then fall back in order to a locally tracked PR number, a PR number discovered from GitHub, and a branch name; check out the stack's top-most unmerged branch.
• cmd/unstack.go, cmd/utils.go — add the optional <stack-number> argument and a helper that loads a locally tracked stack by its number.

Surface the stack number in output and TUIs

• cmd/{submit,link,checkout,unstack,view}.go, cmd/utils.go — append a (stack #N) label to the success messages and add a Stack #N line to gh stack view.
• internal/tui/stackview/model.go, internal/tui/submitview/{model,render,screen}.go — show the number in the stack-view and submit TUI headers, plus a STACK #N label on the submit timeline's left panel.

Update docs and agent instructions for the new API

• docs/ CLI reference and quick-start, AGENTS.md, .github/copilot-instructions.md, and skills/gh-stack/SKILL.md — document checkout/unstack by stack number and drop the now-removed PAT note.

Testing

• New tests for checkout-by-stack-number, unstack-by-stack-number, and the stack-number TUI headers.
• go test -race ./..., go vet ./..., and gofmt are clean, and each of the three commits builds and passes tests independently.

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Makes repository-scoped stack numbers the CLI’s primary stack identifier and surfaces them across commands and TUIs.

Changes:

• Adds checkout and unstack targeting by stack number.
• Persists and displays stack numbers in command output and TUIs.
• Updates tests, documentation, and agent guidance.

Show a summary per file

File	Description
cmd/checkout.go	Resolves numeric targets as stack numbers first.
cmd/checkout_test.go	Tests checkout by stack number.
cmd/link.go	Adds stack numbers to success output.
cmd/submit.go	Passes and prints stack numbers.
cmd/unstack.go	Adds optional stack-number targeting.
cmd/unstack_test.go	Tests targeted unstack behavior.
cmd/utils.go	Adds stack-label and number lookup helpers.
cmd/view.go	Displays stack numbers in views.
internal/tui/stackview/model.go	Adds stack numbers to the header.
internal/tui/stackview/model_test.go	Tests stack-view headers.
internal/tui/submitview/model.go	Stores the stack number in TUI state.
internal/tui/submitview/render.go	Renders numbered submit headers.
internal/tui/submitview/screen.go	Adds the number to the timeline label.
internal/tui/submitview/model_test.go	Tests numbered submit UI elements.
docs/src/content/docs/reference/cli.md	Documents stack-number commands and output.
docs/src/content/docs/getting-started/quick-start.md	Removes obsolete authentication guidance.
skills/gh-stack/SKILL.md	Documents stack-number workflows for agents.
AGENTS.md	Updates API and stack identity guidance.
.github/copilot-instructions.md	Updates GitHub client interface guidance.

Review details

• Files reviewed: 19/19 changed files
• Comments generated: 6
• Review effort level: Medium