Append to an existing stack by stack number with link

[skarim]

Builds on the stack-number work: gh stack link previously required you to list every PR in a stack each time you touched it. Adding one PR to the top meant re-typing the whole chain, and leaving one out failed with this would remove #… from the stack. This PR lets you pass a stack number as the first argument and append only the new PRs to the top of that stack, so growing a stack no longer means restating it. The create-from-scratch and additive-update forms are unchanged.

What's new

• gh stack link <stack-number> <pr-or-branch>… — when the first argument is a stack number (the identifier shown in the GitHub stack UI), the remaining PRs/branches are appended to the top of that stack, e.g. gh stack link 7 48 ui-polish. You no longer restate the PRs already in it.
• Implicit, and safe by construction. A numeric first argument is treated as a stack only when it matches an existing stack; otherwise it's a PR or branch as before. Stack, PR, and issue numbers share one repo-scoped numberspace, so a given number is only ever one kind of object — there's nothing to disambiguate.
• Idempotent. PRs already in the target stack are skipped with a note; if nothing new remains, the command reports the stack is already up to date.
• One stack only. A PR that belongs to a different stack is rejected (unstack it first) — you can grow a stack, but not merge two together.
• Correct base chaining. New branches get PRs created, and existing PRs get their base corrected, so the appended chain sits on top of the stack's current top branch. --base has no effect in this mode and says so.

The original forms — gh stack link a b c to create, and gh stack link 41 42 new-branch to additively update — behave exactly as before.

Changes

Append to a stack by number

• cmd/link.go — runLink now lists stacks up front, and detectAddMode splits a leading stack number from the PRs to append. A new runLinkAdd path partitions the arguments into already-present (skipped) and new, enforces the single-stack constraint, validates eligibility of the new PRs, chains them onto the stack's current top branch, and appends the delta through the AddToStack endpoint (reusing the update path's 404/422 handling). The existing create/update logic moves into runLinkCreateOrUpdate, and createMissingPRs / fixBaseBranches gain a bottomBase argument so both paths share the base-chaining. A best-effort GetStack fallback covers the case where the stack list omits per-PR head refs.

Docs

• docs/src/content/docs/reference/cli.md, faq.md, and skills/gh-stack/SKILL.md — document the stack-number-first form and replace the old "run link again with the full list of PRs" guidance.

Testing

• New cmd/link_test.go cases: add-mode append by number, branch creation chained on top of a stack, idempotent skip (all-present and mixed), cross-stack rejection, eligibility with the existing-member exemption, a numeric first argument that is a PR (not a stack) falling through to create/update, the --base warning, multi-PR base chaining, 404/422 handling, and the list-lacks-head-refs fallback.
• Live-validated against a real repo: created a stack, appended to it by number (both a new branch and an existing PR), and confirmed idempotent skips, cross-stack rejection, and correct base chaining end to end.
• go test -race -count=1 ./... and go vet ./... are clean, and the changed files pass gofmt.

---

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

[Copilot]

Pull request overview

Adds stack-number-based append support to gh stack link.

Changes:

• Detects a leading stack number and appends only new PRs.
• Preserves base chaining, eligibility checks, and idempotency.
• Updates tests and documentation.

Show a summary per file

File	Description
cmd/link.go	Implements stack-number append mode.
cmd/link_test.go	Adds append-mode coverage.
docs/src/content/docs/reference/cli.md	Documents CLI usage.
docs/src/content/docs/faq.md	Updates stack-growth guidance.
skills/gh-stack/SKILL.md	Updates agent instructions.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Medium

[talum]

🚀