gh-stack

# GitHub Stack Use `gh stack` for branch topology and synchronization. Use the repository's `gh-create-pr` skill for Cherry-specific PR bodies, Spec approval, AC coverage, verification, and Agent Note lifecycle. ## Availability and prerequisites This public skill is tracked in `.agents/skills/` and discovered from the repository. Developers do not install a separate agent skill. `pnpm skills:sync` maintains the `.claude/skills/` compatibility symlink. Run this preflight before the first `gh stack` command in a task: ```bash command -v gh >/dev/null 2>&1 || { echo "GitHub CLI is required: https://cli.github.com/" >&2 exit 1 } gh auth status if ! gh stack --help >/dev/null 2>&1; then gh extension install github/gh-stack fi gh stack --help >/dev/null ``` If GitHub CLI authentication, extension installation, or the final verification fails, stop and report the failing command. Do not guess stack topology with ad hoc branch comparisons. Before initializing a stack, avoid extension prompts: ```bash git config rerere.enabled true ``` When multiple remotes exist, resolve the intended remote and pass `--remote <name>` to commands that accept it. Do not silently change `remote.pushDefault` for the developer. ## Stack model A stack is a linear dependency chain. The bottom branch is closest to the trunk; each higher branch contains only work that depends on the layer below it. ```text main -> spec -> implementation-core -> implementation-ui ``` Plan the complete dependency order before creating branches. Put a newly discovered lower-layer change on its owning branch, then rebase the upstack branches; do not hide it in the current layer. ## Agent-safe commands All commands must be non-interactive: - Always run `gh stack view --json`; plain `view` opens a TUI. - Always supply branch names to `init`, `add`, and `checkout`. - Always use `--auto` with `submit` if that command is explicitly allowed. - Pass `--remote <name>` to `push`, `submit`, `sync`, or `link` when more than one remote exists. - Use ordinary `git add` and `git commit -S --signoff` so each layer is staged deliberately. Common operations: ```bash gh stack init --base main <bottom-branch> [<higher-branch>...] gh stack add <new-top-branch> gh stack view --json gh stack push --remote <remote> gh stack rebase --upstack --remote <remote> gh stack sync --remote <remote> gh stack checkout <branch-or-pr> gh stack link --remote <remote> <bottom-pr> <higher-pr> [...] ``` Exit code `2` from `gh stack view --json` means only that the current checkout has no matching local stack metadata. It does not prove that an existing PR is standalone on GitHub. In a clean disposable worktree, run `gh stack checkout <pr-number-or-url>` to discover and hydrate remote topology, then rerun `gh stack view --json`. Classify an existing PR as standalone only after remote discovery confirms that it is not attached to a GitHub stack. Exit code `3` means a conflict, but recovery depends on the command. `gh stack rebase` leaves active recovery state, so resolve the conflict and run `gh stack rebase --continue`, or `gh stack rebase --abort`. `gh stack sync` rolls the attempted rebase back before returning; start a new `gh stack rebase` to resolve that conflict, and do not use `--continue` or `--abort` unless a rebase is active. Exit code `9` means GitHub stacked PRs are unavailable for the repository; stop instead of silently publishing a different PR shape. ## Cherry PR creation Do not use `gh stack submit --auto` to create human-authored Cherry PRs. It creates PRs before the required body preview and auto-generates bodies that do not satisfy the repository template. Create a compliant stack bottom-up: 1. Push the branches with `gh stack push --remote <remote>`. 2. Invoke `gh-create-pr` for each layer, using the parent branch as that layer's base. 3. After every PR has its approved title and body, link the existing PRs with `gh stack link --remote <remote> <bottom-pr> <higher-pr> [...]`. 4. Verify the resulting topology with `gh stack view --json`. `gh stack submit --auto` is allowed only for an explicitly authorized automation workflow that is exempt from the human PR template. It is not a shortcut around Cherry's preview requirement. ## Changes to an existing stack When changing a lower layer: 1. Check out that branch explicitly. 2. Make and verify the focused change there. 3. Run `gh stack rebase --upstack --remote <remote>`. 4. Push or sync the stack. 5. For every rewritten live PR, rerun `pnpm change:scope --base <verified-parent-ref>` and only the checks invalidated by that rewritten scope. After `gh stack sync`, inspect its output and run `gh stack view --json`; a successful command alone is not proof that each PR still has the intended base, scope, or verification. ## Lifecycle boundary Follow `.agents/skills/agent-notes/SKILL.md` for Spec approval and lifecycle transitions. Intermediate implementation layers keep the note proposed. Only the final layer whose cumulative, actually-run evidence covers every approved AC may move the bilingual note triplet to `implemented/`.