chore(CMP-62): add gh-stack workflow skill

.agents/skills/gh-stack/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: gh-stack
+description: >
+  Manages stacked PRs and splits multi-part work into reviewable branches with gh-stack.
+  Use for stack creation, viewing, edits, push, submit, sync, rebase, merge, or checkout;
+  when asked to split or isolate work for review; whenever a user mentions a stack,
+  branch layers, dependent PRs, or gh stack; or when a stack is checked out.
+metadata:
+  author: github
+  version: "0.1.0"
+---
+
+# gh-stack
+
+`gh stack` is a [GitHub CLI](https://cli.github.com/) extension for stacked branches and pull
+requests. A stack is an ordered chain of branches rooted on a trunk, where each branch has one PR
+based on the branch below it, so a reviewer sees only that layer's diff.
+
+`gh stack` prints a stack trunk-first, left to right:
+
+```
+(main) <- auth <- api <- frontend
+```
+
+Left is the **bottom**, right is the **top**. `auth` is based on `main` and merges first;
+`frontend` merges last. `up` moves toward the top, away from trunk; `down` moves toward it.
+Foundational work belongs at the bottom, code that depends on it above. For how to choose the
+layers, read `references/stack-design.md`.
+
+## Setup
+
+```bash
+gh extension install github/gh-stack
+git config rerere.enabled true         # remember conflict resolutions
+git config remote.pushDefault origin   # required if the repo has more than one remote
+```
+
+## Non-interactive use
+
+`gh stack` branches on whether **stdout is a TTY**. Piped, most commands error cleanly or print
+static text; under a PTY the same commands open a prompt or a full-screen TUI and block forever.
+Agent harnesses differ, so always pass the flags below instead of relying on that detection.
+
+**Multiple remotes:** never run `push`, `submit`, `sync`, `rebase`, or `link` without
+`--remote <name>` unless `remote.pushDefault` is configured. `checkout` and `trunk` have no
+`--remote` flag and require the config.
+
+| Always run | Never run bare | Why |
+|---|---|---|
+| `gh stack view --json` | `gh stack view` | opens a TUI under a PTY |
+| `gh stack submit --auto` | `gh stack submit` | prompts for a title per new PR |
+| `gh stack merge <target> --yes` | `gh pr merge` | `gh pr merge` cannot merge a stack |
+| `gh stack init <branch>...` | `gh stack init` | prompts for branch names |
+| `gh stack add <branch>` | `gh stack add` | prompts for a name, and fails even when piped |
+| `gh stack checkout <target>` | `gh stack checkout` | opens a selection menu |
+| `gh stack up` / `down` / `top` / `bottom` | `gh stack switch` | `switch` is menu-only |
+| — | `gh stack modify` | TUI-only, no non-interactive path |
+
+- `view --short` is safe in both modes, but it is formatted for humans. Use `--json` to parse.
+- **`checkout <pr>` when a different local stack already covers those branches** cannot be forced.
+  Run `gh stack unstack --local` first (this keeps the stack on GitHub), then retry.
+
+## Branch placement
+
+- **Starting multi-part work:** create the stack before writing files. Do not implement every
+  concern on trunk and split it later. Put one dependent concern in each layer, bottom to top.
+- **Editing an existing stack:** check out the layer that owns the change before editing. Never
+  commit a lower layer's concern on the current top branch. Run `gh stack view --json`; if
+  ownership is unclear, inspect `git log --all -- <path>`. Then check out the owner, edit, commit,
+  rebase upstack, and return to top.
+
+```bash
+gh stack down                   # or: gh stack checkout api
+git add ... && git commit -m "Add get-user endpoint"
+gh stack rebase --upstack       # replay every branch above onto the change
+gh stack top                    # return to where you were
+gh stack push
+```
+
+## Core loop
+
+```bash
+gh stack init auth              # create the stack and check out its branch
+git add ... && git commit -m "Add auth middleware"
+gh stack add api                # next layer, branched from the current one
+git add ... && git commit -m "Add API routes"
+gh stack submit --auto          # push every branch and open draft PRs
+gh stack view --json            # confirm
+```
+
+Add `--open` to `submit` to create PRs ready for review instead of drafts. Branch names are
+verbatim — `gh stack add refactor/foo` creates `refactor/foo`.
+
+## Staying in sync
+
+```bash
+gh stack sync                   # fetch, reconcile with GitHub, rebase, push, refresh PR state
+gh stack sync --prune           # also delete local branches for merged PRs
+```
+
+Pruning never happens without `--prune` when non-interactive. If the local and remote stacks have
+diverged, `sync` prints both chains, makes no changes, and exits 0 with `Sync aborted` — see
+`references/troubleshooting.md`.
+
+## Merging
+
+Scope the merge with an argument:
+
+```bash
+gh stack merge 42 --yes          # PR #42 plus every unmerged PR below it
+gh stack merge 7 --yes           # every unmerged PR in stack #7
+gh stack merge 42 --yes --squash # or --merge, --rebase, --merge-method <method>
+```
+
+Pass a PR number to merge that PR and every unmerged PR below it, or a stack number to merge every
+unmerged PR in that stack. The operation is all-or-nothing: if any PR in that set cannot merge,
+none do.
+
+Without a method flag the last-used method is reused. If the base branch uses a merge queue, the
+stack is queued instead and the queue picks the method, ignoring any flag you passed with a
+warning; queued PRs may land in separate groups.
+
+## Reading state
+
+`gh stack view --json` writes JSON to **stdout**. Status messages go to **stderr** — do not parse
+them, branch on exit codes instead.
+
+```
+trunk           string
+currentBranch   string
+branches[]      name, head, base, isCurrent, isMerged, isQueued, needsRebase
+branches[].pr   number, url, state ("OPEN" | "MERGED" | "QUEUED"); absent when no PR exists
+```
+
+`base` is the saved SHA of the parent branch that this branch was last known to contain. It may be
+older than the parent's current tip. `needsRebase` is true when the current parent tip is no longer
+an ancestor of the branch.
+
+## Exit codes
+
+| Code | Meaning | Recovery |
+|---|---|---|
+| 0 | Success | — |
+| 1 | Generic error | Read stderr |
+| 2 | Not in a stack | `gh stack init`, or `gh stack checkout <target>` |
+| 3 | Rebase conflict | Follow the Exit 3 recovery below |
+| 4 | GitHub API failure | Check `gh auth status`, retry |
+| 5 | Invalid arguments | Fix the invocation; see `<command> --help` |
+| 6 | Disambiguation required | Branch is in several stacks; check out a non-shared branch |
+| 7 | Rebase already in progress | `gh stack rebase --continue` or `--abort` |
+| 8 | Stack file locked | Another `gh stack` process is writing; retry after ~5s |
+| 9 | Stacked PRs unavailable | Not enabled on the repository; tell the user |
+| 10 | Modify recovery required | `gh stack modify --abort` |
+
+**Exit 3 recovery:**
+
+- After `gh stack rebase`: resolve the files, run `git add`, then
+  `gh stack rebase --continue`; use `gh stack rebase --abort` to restore the stack.
+- After `gh stack sync`: the stack has already been restored. Run `gh stack rebase` to recreate the
+  conflict, then resolve and continue as above.
+
+## Constraints
+
+- Stacks are strictly linear: one parent, at most one child. Use separate stacks for parallel work.
+- There is no non-interactive reorder or removal. Errors may suggest `gh stack modify`, but it is
+  TUI-only — restructure with `unstack` then `init` instead.
+- PR titles and bodies are auto-generated. Use `gh pr edit` afterwards to change them.
+- `checkout <branch-name>` resolves against local stacks only. Use a stack or PR number to pull a
+  stack down from GitHub.
+
+## More detail
+
+`gh stack <command> --help` is authoritative for flags and arguments. Note that
+`gh stack help <command>` does **not** work — it prints the top-level help.
+
+Open the reference whose trigger matches the task; no need to preload all three.
+
+- `references/stack-design.md` — read before creating a stack, when deciding how many layers to
+  use, what belongs in each one, or whether work belongs in a new stack.
+- `references/commands.md` — read when a command fails unexpectedly or you need its preconditions,
+  side effects, atomicity, or ordering guarantees.
+- `references/troubleshooting.md` — read on a rebase conflict, after a squash-merge, on local and
+  remote divergence, when restructuring a stack, or when driving stacks from another tool.

.agents/skills/gh-stack/references/commands.md

@@ -0,0 +1,179 @@
+# Command behavior
+
+`gh stack <command> --help` is authoritative for flags and arguments. (`gh stack help <command>` only prints the top-level help.) This file only covers behavior `--help` does not
+explain: preconditions, side effects, atomicity, and failure modes.
+
+## Contents
+
+- [init](#init)
+- [add](#add)
+- [push](#push)
+- [submit](#submit)
+- [link](#link)
+- [sync](#sync)
+- [rebase](#rebase)
+- [view](#view)
+- [checkout](#checkout)
+- [unstack](#unstack)
+- [merge](#merge)
+- [Navigation](#navigation)
+
+## init
+
+Creates the stack and checks out the **last** branch in the list, so a single `init` can lay down
+the whole chain: `gh stack init auth api frontend`.
+
+`init` processes branch arguments from bottom to top. Existing branches are adopted. If the first
+branch does not exist, it is created from the trunk; each later new branch is created from the
+branch immediately before it. There is no separate adopt mode — existence decides. `--base`
+selects a non-default trunk.
+
+`init` also enables `git rerere`. Under a TTY the first run in a repo asks for confirmation; set
+`git config rerere.enabled true` beforehand to skip it.
+
+## add
+
+- **Must run from the top branch** of the stack (or the trunk when the stack is still empty).
+  Anywhere else it exits **5** with `can only add branches on top of the stack`. Run `gh stack top`
+  first.
+- **Uncommitted changes carry over.** Without `-Am`, `add` does not touch the working tree, so
+  staged and unstaged changes follow you onto the new branch. Commit or stash first for a clean start.
+- **`add -Am` commits in place when the current branch has no commits yet** — for example
+  immediately after `init` — instead of creating a branch. This is deliberate: the first layer
+  usually needs its content before a second layer exists.
+- `-A` and `-u` are mutually exclusive, and both require `-m`.
+
+## push
+
+Pushes every active (non-merged, non-queued) branch in one multi-ref push with per-branch
+`--force-with-lease`.
+
+**Not atomic.** Some branches may update while another is rejected. A rejection means that branch
+moved on the remote; fix that branch and rerun — rerunning is safe and skips what already landed.
+
+`push` never creates or updates pull requests. Use `submit` for that.
+
+## submit
+
+Pushes each active branch, then creates a PR for every branch that lacks one, basing it on the
+first non-merged ancestor, then links them into a Stack on GitHub.
+
+- **Not atomic.** Branches are pushed sequentially with per-branch `--force-with-lease`. If a later
+  push is rejected, earlier pushes and PR updates stand. Fix the rejection and rerun the same command.
+- **A fully merged stack cannot be extended.** When every PR in the current stack is already merged,
+  `submit` forks the remaining unmerged branches into a **new** stack rooted at the trunk and creates
+  it on GitHub, leaving the merged stack untouched.
+- **Title generation with `--auto`:** a branch with a single commit uses that commit's subject as
+  the title and its body as the PR body. A branch with multiple commits humanizes the branch name
+  (hyphens and underscores become spaces). There is no flag for a custom title or body; use
+  `gh pr edit` afterwards.
+- `--open` marks new *and existing* PRs ready for review; without it new PRs are drafts.
+- Requires stacked PRs to be enabled on the repository. If not, `submit` exits **9** when
+  non-interactive (under a TTY it offers to create ordinary unstacked PRs instead).
+
+## link
+
+Creates or updates a stack on GitHub **without any local tracking state**. This is the path for
+branches managed by another tool or living in another worktree — see `troubleshooting.md`.
+
+- Arguments are given bottom to top. Each is a branch name or a PR number; a numeric argument is
+  tried as a PR number first and falls back to a branch name.
+- **A numeric first argument is treated as a stack number only when a stack with that number
+  exists.** In that case the remaining arguments are appended to the top of that stack and you do
+  not re-list its current PRs: `gh stack link 7 feature-c`. Arguments already in the stack are
+  skipped; arguments belonging to a different stack are rejected.
+- Branch arguments are pushed automatically (non-force, atomic). Missing PRs are created with
+  auto-generated titles and correctly chained bases; existing PRs with a wrong base are corrected.
+- Stack membership is **additive only** — `link` never removes a PR from a stack.
+
+## sync
+
+The routine command. Steps, in order:
+
+1. **Fetch** from the remote.
+2. **Reconcile with the GitHub stack.** PRs added to the stack on github.com are pulled down and
+   appended locally. On divergence, aborts when non-interactive (see `troubleshooting.md`).
+3. **Fast-forward the trunk.** Skipped when already current; warns when diverged.
+4. **Cascade rebase when needed.** This runs if the trunk moved, a stack branch was fast-forwarded
+   from its remote, or a branch no longer contains its expected parent. Merged PRs are handled
+   automatically. On conflict, **all branches are restored** to their pre-rebase state and the
+   command exits **3**.
+5. **Push** all active branches, atomically.
+6. **Refresh PR state** from GitHub.
+7. **Sync the stack object** — link open PRs into a stack, additively. Only when two or more PRs
+   exist. `sync` never opens PRs; that is `submit`.
+8. **Prune** local branches for merged PRs, only when `--prune` is passed in a non-interactive
+   environment.
+
+## rebase
+
+Pulls from the remote and cascade-rebases. Use it when `sync` reported a conflict or when you need
+to rebase only part of the stack.
+
+- `--upstack` rebases from the current branch to the top. This is what you run after editing a
+  lower layer.
+- `--downstack` rebases from the trunk to the current branch.
+- `--no-trunk` skips fetching and the trunk rebase entirely, aligning stack branches with each
+  other only.
+- `--continue` after staging resolutions; `--abort` restores every branch.
+- A merged PR is detected automatically and replayed with `--onto` against the correct target, so a
+  squash-merged parent does not produce spurious conflicts.
+- Starting a rebase while one is in progress exits **7**.
+
+## view
+
+- `--json` writes the machine-readable payload to stdout. Its schema is in `SKILL.md`.
+- Bare `view` opens a full-screen TUI when stdout is a TTY, and prints static text when piped.
+- `--short` prints a compact one-line-per-branch summary and never opens the TUI, but it is
+  formatted for humans; parse `--json` instead.
+- `view` refreshes PR state from GitHub as a side effect, best-effort — it does not fail when the
+  API is unreachable.
+
+## checkout
+
+Accepts a stack number, PR number, PR URL, or branch name.
+
+- A bare number resolves as a **stack number first**, then a PR number, then a branch name.
+- Stack numbers, PR numbers, and PR URLs fetch from GitHub, pull the branches down, and set the
+  stack up locally.
+- A **branch name resolves against locally tracked stacks only** and never contacts GitHub. Use a
+  stack or PR number to pull a stack that is not tracked locally.
+- If a local stack already exists over those branches with a different composition, `checkout`
+  cannot be forced past it. Run `gh stack unstack --local` first, then retry.
+- `checkout` has no flags. It relies on `remote.pushDefault` when several remotes exist.
+
+## unstack
+
+Removes the stack **grouping** only. It never deletes pull requests or branches.
+
+- With no argument it targets the active stack — the one containing the current branch — removing
+  it on GitHub and locally.
+- With a stack number it works from anywhere in the repository, tracked locally or not, via the API.
+  Local tracking is also removed when present.
+- `--local` removes local tracking only and never contacts GitHub. Combining `--local` with a stack
+  number that is not tracked locally is an error.
+- An unknown stack number exits **2**.
+
+## merge
+
+- Scope with an argument: pass a PR number to merge that PR and every unmerged PR below it in the
+  stack, or pass a stack number to merge every unmerged PR in that stack.
+- **All-or-nothing.** If any PR in that exact merge set cannot be merged, none are, and the reason
+  is reported.
+- The method comes from `--squash`, `--rebase`, `--merge`, or `--merge-method <method>`. Without
+  one, the last-used method is reused.
+- Only basic PR state is checked before merging: open and not a draft. Bypassing merge requirements
+  is not supported for stacks.
+- **A merge queue on the base branch overrides everything.** The stack is added to the queue rather
+  than merged; the queue chooses the method and any method flag you passed is ignored with a
+  warning. Queued PRs are submitted together but land as the queue processes them, so they may merge
+  in separate groups rather than all at once.
+- `gh pr merge` cannot merge a stack. Always use `gh stack merge`.
+
+## Navigation
+
+`up`, `down`, `top`, `bottom`, and `trunk` are always non-interactive. `up` and `down` accept a
+count (`gh stack up 3`). Movement clamps at the stack bounds, and merged branches are skipped when
+navigating from an active branch, so `bottom` lands on the lowest *unmerged* branch.
+
+`gh stack switch` is a selection menu with no non-interactive path. Use the commands above instead.