link command for api-only operations

[skarim]

gh stack link — stacks API-wrapper for external tool users

Users who manage branches with external tools (jj, Sapling, ghstack, git-town) currently need to run init --adopt + submit to create GitHub stacks — but that creates local tracking state they don't want. This adds a lightweight gh stack link command that works entirely via the GitHub API without creating/modifying any local state.

Usage:

gh stack link [--base main] [--draft] [--remote origin] <branch-or-pr> [...]

Arguments can be branch names, PR numbers, or a mix. Branches are pushed automatically, PRs are created for branches that don't have them, and the PRs are linked as a stack on GitHub.

How it works:

1. Push — pushes branch args to the remote (skipped for PR-number-only invocations)
2. Find existing PRs — resolves each arg to a PR without creating anything yet. Numeric args try FindPRByNumber first; if not found, fall through to branch lookup via FindPRForBranch
3. Pre-validate — calls ListStacks and checks that the operation won't remove existing PRs from a stack (additive-only safety). Fails early before creating any new PRs
4. Create missing PRs — creates PRs for branches that don't have one, with correct base chaining (first branch uses --base, subsequent branches chain off the previous)
5. Fix base branches — corrects BaseRefName on existing PRs whose base doesn't match the expected chain (skips newly created PRs)
6. Upsert stack — creates a new stack or updates an existing one

Safety features:

• Additive-only updates — if the input would remove PRs from an existing stack, the command errors with a clear message showing the current stack composition
• Pre-validation before PR creation — stack conflicts are caught before creating new PRs, preventing orphaned PRs
• Fatal PR lookup errors — FindPRByNumber API errors are treated as fatal (not silently falling through to branch-name lookup)
• Single ListStacks call — pre-validation and upsert share the same API response

Flags:

Flag	Description
--base <branch>	Base branch for the bottom of the stack (default: main)
--draft	Create new PRs as drafts
--remote <name>	Remote to push to (defaults to auto-detected remote)

[Copilot]

Pull request overview

Adds a new gh stack link command intended for “API-first” stacked PR operations—linking existing PRs and/or branches into a GitHub stack without creating gh-stack local tracking state—along with full documentation and test coverage.

Changes:

• Introduces gh stack link CLI command and wires it into the root command.
• Implements link flow: push branch args, resolve/create PRs, fix base-branch chaining, then create/update the remote stack (additive-only).
• Adds extensive unit tests plus updates README, CLI reference docs, FAQ, and the gh-stack skill guide.

Show a summary per file

File	Description
skills/gh-stack/SKILL.md	Updates agent rules and adds a new section documenting gh stack link.
docs/src/content/docs/reference/cli.md	Adds CLI reference documentation for gh stack link.
docs/src/content/docs/faq.md	Updates FAQ to recommend gh stack link for external stacking tools.
cmd/root.go	Registers LinkCmd in the CLI.
cmd/link.go	Implements the link command (push/resolve/create/fix-base/upsert-stack).
cmd/link_test.go	Adds comprehensive tests for PR-number, branch-name, and mixed workflows.
README.md	Documents gh stack link usage and flags.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 7/7 changed files
• Comments generated: 5