updated link docs

Author: skarim

docs/src/content/docs/faq.md

@@ -255,7 +255,14 @@ This doesn't create any local tracking and only hits the APIs to create Stacked
 
 If the provided branches already have open PRs, `link` will use them. If not, it creates draft PRs by default with the correct base branch chaining.
 
-To add more to the stack, run `link` again, but be sure to include the full list of PRs/branches in the stack:
+To add more to the stack, pass the stack number (shown in the GitHub stack UI) as the first argument, followed by just the new PRs or branches — you no longer need to re-list the PRs already in the stack:
+
+```bash
+# 42 is the stack number; change4 and change5 are appended to its top
+gh stack link 42 change4 change5
+```
+
+You can also pass the full list of PRs/branches (without a leading stack number) to create a stack or additively update an existing one:
 
 ```bash
 gh stack link 123 124 125 change4 change5

docs/src/content/docs/reference/cli.md

@@ -430,7 +430,7 @@ gh stack push --remote upstream
 Link PRs into a stack on GitHub without local tracking.
 
 ```sh
-gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
+gh stack link [flags] <stack-number | branch-or-pr> <branch-or-pr> [...]
 ```
 
 Creates or updates a stack on GitHub from branch names or PR numbers/URLs. This command does not create or modify any `gh-stack` local tracking state. It is designed for users who manage branches with other tools locally (e.g., jj, Sapling, git-town) and want to simply open a stack of PRs.
@@ -439,9 +439,11 @@ Arguments are provided in stack order (bottom to top). Branch arguments are auto
 
 If the PRs are not yet in a stack, a new stack is created. If some of the PRs are already in a stack, the existing stack is updated to include the new PRs. Existing PRs are never removed from a stack — the update is additive only.
 
+To grow an existing stack without re-listing its PRs, pass a stack number (the number shown in the GitHub stack UI) as the first argument. The remaining arguments are appended to the top of that stack. Arguments already in the stack are skipped, and arguments that belong to a different stack are rejected. Because stack and PR numbers never overlap, a numeric first argument is treated as a stack only when it matches an existing stack — otherwise it is treated as a PR or branch.
+
 | Flag | Description |
 |------|-------------|
-| `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |
+| `--base <branch>` | Base branch for the bottom of the stack (default: `main`); ignored when adding to an existing stack |
 | `--open` | Mark new and existing PRs as ready for review |
 | `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
 
@@ -460,6 +462,10 @@ gh stack link https://github.com/owner/repo/pull/10 https://github.com/owner/rep
 # Add branches to an existing stack of PRs
 gh stack link 42 43 feature-auth feature-ui
 
+# Append to the top of an existing stack by its stack number (no need to
+# re-list the PRs already in stack 7)
+gh stack link 7 48 feature-ui
+
 # Use a different base branch and mark PRs as ready for review
 gh stack link --base develop --open feat-a feat-b feat-c
 ```

skills/gh-stack/SKILL.md

@@ -61,7 +61,7 @@ git config remote.pushDefault origin     # if multiple remotes exist (skips remo
 7. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
 8. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
 9. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
-10. **Use `gh stack link` for external tool workflows.** When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers.
+10. **Use `gh stack link` for external tool workflows.** When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Provide at least two branches/PRs to create or update a stack, or a stack number followed by the new branches/PRs to append them to the top of an existing stack (e.g. `gh stack link 7 branch-c`).
 
 **Never do any of the following — each triggers an interactive prompt or TUI that will hang:**
 - ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json`
@@ -573,7 +573,7 @@ gh stack submit --auto --open
 Link PRs into a stack on GitHub without creating any local tracking state. This is the recommended approach if you are managing stacked branches with other tools (jj, Sapling, git-town) and want to simply create GitHub Stacked PRs via an API.
 
 ```
-gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
+gh stack link [flags] <stack-number | branch-or-pr> <branch-or-pr> [...]
 ```
 
 ```bash
@@ -588,8 +588,14 @@ gh stack link 10 20 30
 
 # Add branches to an existing stack of PRs
 gh stack link 42 43 feature-auth feature-ui
+
+# Append to the top of an existing stack by its stack number
+# (7 is a stack number; only the new PRs/branches are listed)
+gh stack link 7 48 feature-auth
 ```
 
+When the first argument is a stack number, the remaining arguments are appended to the top of that stack, so you don't have to re-list its current PRs. Arguments already in the stack are skipped; arguments in a different stack are rejected. A numeric first argument is treated as a stack only when it matches an existing stack — otherwise it is a PR or branch.
+
 | Flag | Description |
 |------|---------|
 | `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |