Claude Skill

stacked-prs

Work with GitHub stacked pull requests (gh stack) in the team's repos. Put a branch on the right stack, commit, push and open its PR with the "Stacked on" banner, fix a merge conflict on the one branch that has it, and walk a stack bottom to top. Use whenever the user says "on th

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download beakpoint-insights-roost-skills_stacked-prs-6697acd.zip · 4 KB

Install

skills CLI npx skills add https://github.com/Beakpoint-Insights/roost/tree/main/skills/stacked-prs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install beakpoint-insights-roost@llmmart
Git git clone https://github.com/Beakpoint-Insights/roost.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole beakpoint-insights/roost collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Stacked PRs

This team ships most work as a stack of pull requests managed with gh stack (vcs.stacking: gh-stack in the roost config). Each PR is based on the branch below it, so a mistake in one place shows up in every PR above it. Getting this right quickly matters more than explaining it.

First, load the team config with roost-config. This skill uses vcs, repos and deploy.

With vcs.stacking: none, there are no stacks: every branch starts from main and is its own PR against main ("Without stacking" in roost-config). Skip every gh stack step and "One deploy per stack", and publish a change this way instead, with the rules below, the commit and PR title rules, and the Release order comment as usual:

git switch -c <branch> origin/main        # or from the branch it needs, if it needs one
# commit (signed, if required)
git push -u origin <branch>
gh pr create --base main --title "…" --body "…"   # add "Waits for #<PR>." when it started from another branch

When the branch it started from merges, rebase it onto main (git rebase --onto origin/main <that branch> <branch>), force-push with lease, and drop the "Waits for" line.

Rules that always apply

  • Pasted steps are the request. If the user pastes instructions (for example GitHub's "Use the gh stack CLI to resolve conflicts" steps), do exactly those steps. Don't investigate first, ask for a go-ahead, or widen the scope.
  • Only touch the branch you were asked about. Fixing one PR's conflict doesn't mean rebasing or force-pushing the whole stack.
  • Signed commits, when vcs.signed_commits is true. Never pass --no-gpg-sign. If signing fails because it's blocked on the user (vcs.signing_blocker; errors like vcs.signing_errors), stop, say so in one line, and wait. Don't retry in a loop.
  • No worktrees and no side branches. Work in the checkout that's already there. Stage your own files by path, never git add -A, because another session may be editing the same repo.
  • Report in one line when it went as asked. For example "Pushed PROJ-2759 and opened #183 on the stack." Detail only when something didn't go as asked.

Find where you are

Run these before creating a branch, opening a PR, or saying what's deployed:

git status --short
git log --oneline origin/main..HEAD | head -20   # commits not on main yet
gh stack view --short                            # this stack's branches and PRs, bottom to top

Code that isn't on main isn't running in staging or production. Don't reason about an environment from a branch.

Add a branch on top of a stack

gh stack checkout <PR number or branch in the stack>
gh stack top                      # go to the top branch
gh stack add PROJ-1234-short-description

Branch names follow vcs.branch_name, starting with the ticket key. Each fix gets its own branch unless the user says otherwise.

One deploy per stack

A stack holds the PRs of one deploy only. Merging a stack merges every PR linked into it, so a branch meant for a later deploy must never be linked into an earlier deploy's stack.

  • Before gh stack link, read the branch's deploy in the epic's Release order comment (its Deploy column). Link it only into the stack whose PRs share that deploy.
  • The first branch of a new deploy starts a new stack. Create it on the earlier deploy's top branch if it needs that code, but don't link it into that stack, and give its PR the banner > Ships in Deploy <N>. Waits for Deploy <N-1> (#<PRs>) to merge. Later branches of the same deploy stack on it as usual.
  • When the earlier deploy has merged, rebase the whole new stack onto main, bottom to top: gh stack rebase, or from the top branch git rebase --update-refs --onto origin/main <old base> <top branch>, which moves every branch in it. Push every rewritten branch (force-with-lease), and retarget the bottom PR to main.
  • Before anyone merges a stack, list exactly which PRs the merge takes (gh stack view --short) and check every one is in this deploy. If one isn't, unlink it first.

Commit, push and open the PR on the stack

  1. Commit (signed, if required), with a message that names the ticket. When vcs.pr_title is conventional, use a Conventional Commit, for example fix(PROJ-1234): …. The PR title follows vcs.pr_title too, for example feat(PROJ-1234): API keys page on the managed-list pattern. The repos' title checks fail on anything else ("PROJ-1234 backend (1/2): …" fails). With vcs.merge_method: squash, the title becomes the commit message.
  2. Push: gh stack push.
  3. Open the PR against the branch directly below it, never against main:
    gh pr create --base <parent branch> --title "…" --body "$(cat <<'EOF'
    > [!NOTE]
    > Stacked on #<parent PR number>.
    
    ## Summary
    …
    EOF
    )"
    
  4. Link it into the stack on GitHub: gh stack link <stack number> <new branch>. Get the stack number from gh stack view. If link asks for the full list, give every PR in the stack, bottom to top.
  5. Check it landed: gh stack view --short shows the new branch on top, and the PR's base is the parent branch.

If the user says "we're already on a PR", don't open another one: push and update the existing PR's title and description instead (gh pr edit).

Cross-repo dependencies

Don't write dependency prose into PR descriptions ("the frontend still waits for this branch, because …"). Every PR in a stack ends up with one, and readers miss them. Instead:

  • The epic has one Release order comment in the tracker that lists every branch and PR in deploy order, across every repo, with a Deploy column (which deploy ships it) and what each waits for. Whoever opens a PR adds it there (run-slice and the tech lead keep it current).
  • A PR in a repo with depends_on that can't ship until a PR in the repo it depends on is deployed gets one banner line under the "Stacked on" note, linking that comment: > [!IMPORTANT] > Ships after <that repo's name> #577 and #578 are deployed. Release order: <link to the epic's comment>.
  • PRs in repos that don't depend on another repo (no depends_on) carry no dependency note.

Migrations need a deploy note

When deploy.migrations_run_on_deploy is false, staging and production don't run migrations on deploy (deploy.migrations_note), so a migration that only reached the local database is easy to forget. Whenever a branch adds a migration, make sure a deploy note covers it, and add one only if it's missing:

  • Where: the epic's deploy ticket (its "Deploy …" Task, for example PROJ-2795). For a standalone bug, the bug's own ticket.
  • The note: one Migrations to apply comment, listing every migration on the stack in order, with its context or module and the story or bug that added it. Update that comment when a migration is added; don't start a second list.
  • The steps: a pre-deploy sub-task each for staging and production ("Before deploying: apply the database migrations"). Each has the back-up step and, for each context, deploy.migration_apply, where $CONN is read from that environment's deployed secret when the step runs (deploy.secret_read, as write-runbook does). Never paste a connection string or password into the tracker, in the sub-task or a comment. The step is done when deploy.migration_verify, with the same context and $CONN, shows them applied, so it checks the environment that was migrated. Create the sub-tasks once; later migrations go into the existing ones.
  • A migration that only changes the model snapshot (no DDL) still goes on the list, marked "snapshot only", so the history matches.

Evidence an agent can't attach

gh can't attach images to a PR. Put screenshots on the story's ticket (see "Attach a file" in the tracker adapter) and add a PR comment that lists them and links the story. Never pass this to the user.

Fix a merge conflict

GitHub's own steps, which the user expects followed exactly:

gh stack checkout <PR number>
gh stack rebase
# fix the conflicts, then commit (signed, if required)
gh stack push
  • Fix the conflict on the branch that introduced it. Fixing it on a branch higher up leaves the lower PR still conflicted.
  • Then check that GitHub shows that PR as mergeable: gh pr view <number> --json mergeable,mergeStateStatus.
  • If the PRs above it now conflict, and the user asked you to keep going, work up the stack one PR at a time, the same way. Otherwise report which PR conflicts next and stop.
  • Stash and restore uncommitted work around a rebase without asking.

Refresh local tracking

When the user asks to "refresh the local gh stack tracking", run gh stack checkout <a PR in the stack>. It pulls the stack's branches and tracking from GitHub. Don't use gh stack sync unless asked: it also rebases and force-pushes every branch.

After pushing

  • If CI runs on the PR, say so and give the PR link. Don't wait silently.
  • If the user asked for an updated PR description, rewrite it as one coherent description of the branch, not a changelog of edits.
Files (roost)
  • SKILL.md 9.4 KB
    ---
    name: stacked-prs
    description: Work with GitHub stacked pull requests (gh stack) in the team's repos. Put a branch on the right stack, commit, push and open its PR with the "Stacked on" banner, fix a merge conflict on the one branch that has it, and walk a stack bottom to top. Use whenever the user says "on the stack", "add it to the stack", "open a PR on the stack", "fix the conflict", or pastes GitHub's stacked-PR conflict steps.
    ---
    
    # Stacked PRs
    
    This team ships most work as a stack of pull requests managed with `gh stack` (`vcs.stacking: gh-stack` in the roost config). Each PR is based on the branch below it, so a mistake in one place shows up in every PR above it. Getting this right quickly matters more than explaining it.
    
    **First, load the team config with `roost-config`.** This skill uses `vcs`, `repos` and `deploy`.
    
    **With `vcs.stacking: none`,** there are no stacks: every branch starts from `main` and is its own PR against `main` ("Without stacking" in `roost-config`). Skip every `gh stack` step and "One deploy per stack", and publish a change this way instead, with the rules below, the commit and PR title rules, and the Release order comment as usual:
    
    ```bash
    git switch -c <branch> origin/main        # or from the branch it needs, if it needs one
    # commit (signed, if required)
    git push -u origin <branch>
    gh pr create --base main --title "…" --body "…"   # add "Waits for #<PR>." when it started from another branch
    ```
    
    When the branch it started from merges, rebase it onto `main` (`git rebase --onto origin/main <that branch> <branch>`), force-push with lease, and drop the "Waits for" line.
    
    ## Rules that always apply
    
    - **Pasted steps are the request.** If the user pastes instructions (for example GitHub's "Use the gh stack CLI to resolve conflicts" steps), do exactly those steps. Don't investigate first, ask for a go-ahead, or widen the scope.
    - **Only touch the branch you were asked about.** Fixing one PR's conflict doesn't mean rebasing or force-pushing the whole stack.
    - **Signed commits,** when `vcs.signed_commits` is true. Never pass `--no-gpg-sign`. If signing fails because it's blocked on the user (`vcs.signing_blocker`; errors like `vcs.signing_errors`), stop, say so in one line, and wait. Don't retry in a loop.
    - **No worktrees and no side branches.** Work in the checkout that's already there. Stage your own files by path, never `git add -A`, because another session may be editing the same repo.
    - **Report in one line when it went as asked.** For example "Pushed PROJ-2759 and opened #183 on the stack." Detail only when something didn't go as asked.
    
    ## Find where you are
    
    Run these before creating a branch, opening a PR, or saying what's deployed:
    
    ```bash
    git status --short
    git log --oneline origin/main..HEAD | head -20   # commits not on main yet
    gh stack view --short                            # this stack's branches and PRs, bottom to top
    ```
    
    Code that isn't on `main` isn't running in staging or production. Don't reason about an environment from a branch.
    
    ## Add a branch on top of a stack
    
    ```bash
    gh stack checkout <PR number or branch in the stack>
    gh stack top                      # go to the top branch
    gh stack add PROJ-1234-short-description
    ```
    
    Branch names follow `vcs.branch_name`, starting with the ticket key. Each fix gets its own branch unless the user says otherwise.
    
    ## One deploy per stack
    
    A stack holds the PRs of **one deploy** only. Merging a stack merges every PR linked into it, so a branch meant for a later deploy must never be linked into an earlier deploy's stack.
    
    - **Before `gh stack link`,** read the branch's deploy in the epic's **Release order** comment (its **Deploy** column). Link it only into the stack whose PRs share that deploy.
    - **The first branch of a new deploy starts a new stack.** Create it on the earlier deploy's top branch if it needs that code, but don't link it into that stack, and give its PR the banner `> Ships in Deploy <N>. Waits for Deploy <N-1> (#<PRs>) to merge.` Later branches of the same deploy stack on it as usual.
    - **When the earlier deploy has merged,** rebase the whole new stack onto `main`, bottom to top: `gh stack rebase`, or from the top branch `git rebase --update-refs --onto origin/main <old base> <top branch>`, which moves every branch in it. Push every rewritten branch (force-with-lease), and retarget the bottom PR to `main`.
    - **Before anyone merges a stack,** list exactly which PRs the merge takes (`gh stack view --short`) and check every one is in this deploy. If one isn't, unlink it first.
    
    ## Commit, push and open the PR on the stack
    
    1. Commit (signed, if required), with a message that names the ticket. When `vcs.pr_title` is `conventional`, use a Conventional Commit, for example `fix(PROJ-1234): …`.
       The **PR title** follows `vcs.pr_title` too, for example `feat(PROJ-1234): API keys page on the managed-list pattern`. The repos' title checks fail on anything else ("PROJ-1234 backend (1/2): …" fails). With `vcs.merge_method: squash`, the title becomes the commit message.
    2. Push: `gh stack push`.
    3. Open the PR against the branch directly below it, never against `main`:
       ```bash
       gh pr create --base <parent branch> --title "…" --body "$(cat <<'EOF'
       > [!NOTE]
       > Stacked on #<parent PR number>.
    
       ## Summary
       …
       EOF
       )"
       ```
    4. Link it into the stack on GitHub: `gh stack link <stack number> <new branch>`. Get the stack number from `gh stack view`. If `link` asks for the full list, give every PR in the stack, bottom to top.
    5. Check it landed: `gh stack view --short` shows the new branch on top, and the PR's base is the parent branch.
    
    If the user says "we're already on a PR", don't open another one: push and update the existing PR's title and description instead (`gh pr edit`).
    
    ### Cross-repo dependencies
    
    Don't write dependency prose into PR descriptions ("the frontend still waits for this branch, because …"). Every PR in a stack ends up with one, and readers miss them. Instead:
    - The epic has one **Release order** comment in the tracker that lists every branch and PR in deploy order, across every repo, with a **Deploy** column (which deploy ships it) and what each waits for. Whoever opens a PR adds it there (`run-slice` and the tech lead keep it current).
    - **A PR in a repo with `depends_on` that can't ship until a PR in the repo it depends on is deployed** gets one banner line under the "Stacked on" note, linking that comment:
      `> [!IMPORTANT]`
      `> Ships after <that repo's name> #577 and #578 are deployed. Release order: <link to the epic's comment>.`
    - PRs in repos that don't depend on another repo (no `depends_on`) carry no dependency note.
    
    ### Migrations need a deploy note
    
    When `deploy.migrations_run_on_deploy` is false, staging and production don't run migrations on deploy (`deploy.migrations_note`), so a migration that only reached the local database is easy to forget. Whenever a branch adds a migration, make sure a deploy note covers it, and add one only if it's missing:
    
    - **Where:** the epic's deploy ticket (its "Deploy …" Task, for example PROJ-2795). For a standalone bug, the bug's own ticket.
    - **The note:** one **Migrations to apply** comment, listing every migration on the stack in order, with its context or module and the story or bug that added it. Update that comment when a migration is added; don't start a second list.
    - **The steps:** a pre-deploy sub-task each for staging and production ("Before deploying: apply the database migrations"). Each has the back-up step and, for each context, `deploy.migration_apply`, where `$CONN` is read from that environment's deployed secret when the step runs (`deploy.secret_read`, as `write-runbook` does). **Never paste a connection string or password into the tracker**, in the sub-task or a comment. The step is done when `deploy.migration_verify`, with the same context and `$CONN`, shows them applied, so it checks the environment that was migrated. Create the sub-tasks once; later migrations go into the existing ones.
    - A migration that only changes the model snapshot (no DDL) still goes on the list, marked "snapshot only", so the history matches.
    
    ### Evidence an agent can't attach
    
    `gh` can't attach images to a PR. Put screenshots on the story's ticket (see "Attach a file" in the tracker adapter) and add a PR comment that lists them and links the story. Never pass this to the user.
    
    ## Fix a merge conflict
    
    GitHub's own steps, which the user expects followed exactly:
    
    ```bash
    gh stack checkout <PR number>
    gh stack rebase
    # fix the conflicts, then commit (signed, if required)
    gh stack push
    ```
    
    - Fix the conflict on the branch that **introduced** it. Fixing it on a branch higher up leaves the lower PR still conflicted.
    - Then check that GitHub shows that PR as mergeable: `gh pr view <number> --json mergeable,mergeStateStatus`.
    - If the PRs above it now conflict, and the user asked you to keep going, work up the stack one PR at a time, the same way. Otherwise report which PR conflicts next and stop.
    - Stash and restore uncommitted work around a rebase without asking.
    
    ## Refresh local tracking
    
    When the user asks to "refresh the local gh stack tracking", run `gh stack checkout <a PR in the stack>`. It pulls the stack's branches and tracking from GitHub. Don't use `gh stack sync` unless asked: it also rebases and force-pushes every branch.
    
    ## After pushing
    
    - If CI runs on the PR, say so and give the PR link. Don't wait silently.
    - If the user asked for an updated PR description, rewrite it as one coherent description of the branch, not a changelog of edits.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.