Skip to content
Skills Library
Programming · Automation

sc-gh-stack

/sc-gh-stack

Run stacked PRs with the gh stack extension the way that lands (append-only frozen layers on a named trunk, one stack writer, QA/CI on the top, one atomic merge). Use for any stack, stacked/dependent PRs, gh stack link/unstack/merge, landing, a red layer, or /sc-gh-stack. Supersedes /gh-stack.

Licence
MIT
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
15
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Run stacked PRs with the gh stack extension the way that lands (append-only frozen layers on a named trunk, one stack writer, QA/CI on the top, one atomic merge). Use for any stack, stacked/dependent PRs, gh stack link/unstack/merge, landing, a red layer, or /sc-gh-stack. Supersedes /gh-stack.

Original author description

Run stacked PRs with the gh stack extension the way that lands (append-only frozen layers on a named trunk, one stack writer, QA/CI on the top, one atomic merge). Use for any stack, stacked/dependent PRs, gh stack link/unstack/merge, landing, a red layer, or /sc-gh-stack. Supersedes /gh-stack.

How it works

  1. Step 1 — Verify gh, the gh-stack extension, git, python3
  2. Step 2 — Obtain the evidence the operation needs
  3. The model (read references/model.md once)
  4. What to do (pick the row, open the reference)
  5. Hard preconditions (details and incidents in references/preconditions.md)
  6. Deterministic helpers
  7. Storage
  8. Related
Original SKILL.md headings · 156 lines, 1,338 words
SKILL.md preview
---
name: sc-gh-stack
version: 0.2.0
description: Run stacked PRs with the gh stack extension the way that lands (append-only frozen layers on a named trunk, one stack writer, QA/CI on the top, one atomic merge). Use for any stack, stacked/dependent PRs, gh stack link/unstack/merge, landing, a red layer, or /sc-gh-stack. Supersedes /gh-stack.
entry_point: /sc-gh-stack
---

# sc-gh-stack

Supersedes the generic `/gh-stack` skill; its command guide lives in
`references/commands.md`. A stack exists so CI completes once, on the landing head, and the merge
happens once. Every rule here was paid for in production: the "why" lines
cite the incident. This file is the table of contents; read the reference a
step points to before acting, and nothing else.

## Step 1 — Verify gh, the gh-stack extension, git, python3

Check once at setup or after an executable/version change or failure. Local
reporting needs git and Python; check gh/auth only when acquisition needs it,
and the extension for actual extension operations.

```bash
which gh && gh --version
gh extension list | grep -i stack && gh stack --version
which git && git --version
which python3 && python3 --version
```

If any is missing, probe the usual off-PATH locations (Claude Code's bash may
not share PATH with the interactive shell):

```bash
for cli in gh git python3; do
  command -v "$cli" >/dev/null && continue
  for d in /opt/homebrew/bin /usr/local/bin "$HOME/.local/bin" "$HOME/.pyenv/shims"; do
    [ -x "$d/$cli" ] && echo "$cli found at: $d/$cli" && break
  done
done
```

Found off-PATH: `export PATH="<dir>:$PATH"` for this session. Still missing,
below the floors (git < 2.38, gh < 2.0, python3 < 3.9, no gh-stack
extension for an extension operation), or required authentication fails: read
`references/installation-and-troubleshooting.md`. Stop dependent writes;
local reports may retain useful evidence with explicit unknowns.

## Step 2 — Obtain the evidence the operation needs

`/sc-gh-stack-view` (skill `sc-gh-stack-view`, script
`.claude/scripts/gh_stack_view.py`) is the status call. Reuse sufficient
observations and mutation responses; obtain only missing or changed facts
needed for the next write or dispatch. Scope with `--stack <number-or-branch>`
or `--trunk`; `--compact-json` bounds routine agent output without changing
acquisition, while `--json` includes every layer. Compact output is not complete
composition evidence and never selects the top or a merge range. Use `--refresh-git` for current
remote refs, `--refresh-status` for hosted facts, or `--refresh` for both.
Do not duplicate the hosted executor's preflight with precautionary scans.
Paste requested status output verbatim. Never fan out `gh pr view` per branch,
text-parse `gh pr checks`, or use bare `gh stack view` (it opens a TUI).

## The model (read `references/model.md` once)

- **Trunk** is the branch the stack lands on: `develop`, an integration branch
  such as `integrate/phase-N`, or whatever the user names. Never assume the
  repository default branch.
- **Append-only and linear.** Every unit of work is a new worktree cut from the
  current pushed top. A layer is **frozen** the moment its task closes; nothing
  below the top is edited again. Findings on layer K are fixed on a new layer
  above the top, never on K.
- **One writer per branch, one stack writer.** Only the stack writer (the lead
  or orchestrator) runs `link`, `unstack`, `sync`, `rebase`, `merge`. Everyone
  else pushes commits to their own layer only.
- **QA and CI gate the top only.** Red on a lower layer is informational unless
  that layer is to be merged alone.
- **Small fixes do not get a stack.** One owner, well under a few hundred
  lines, fix and tests together: one PR off trunk, no stack.

## What to do (pick the row, open the reference)

| Situation | Reference |
|-----------|-----------|
| Starting a new sprint, fix round, docs or evidence layer | `references/recipe-cut-layer.md` |
| First push of a layer landed; it needs a PR and a stack link | `references/recipe-link.md` |
| Several open PRs on one trunk depend on each other | `references/recipe-link.md` (full ordered link) |
| Fixing a finding on a frozen layer, or on any layer that has children | `references/recipe-cut-layer.md` (new layer on top; never edit below the top) |
| Starting a task on the live top layer (no children, not frozen) | `references/workflow.md` step 4 (rebase at task start) |
| Insert a layer mid-stack, remove a red layer whose fix is above, collapse a passing bottom | `references/recipe-restack.md` |
| Everything frozen, top green and QA PASS: land it | `references/recipe-land.md` |
| `gh stack merge` refused, `gh pr merge` refused, non-linear stack | `references/recipe-land.md` (fallbacks A and B) |
| View shows 🔄, or NOT COHERENT with `-` rows after an unstack | `references/recipe-stale-tracking.md` |
| Deciding layer boundaries, naming, what belongs where | `references/stack-design.md` |
| Any `gh stack` command, flag, exit code, `--json` schema | `references/commands.md` |
| An error message you do not recognise | `references/troubleshooting.md` |
| How a whole phase runs on one stack (worked example) | `references/phase-model-example.md` |
| Why status-call substitutions preserve recipe outcomes | `references/recipe-evidence.md` |

Record the current stack number when a link changes it. Reconcile changed
heads, bases and lifecycle before dependent work; a sufficient mutation
response or existing observation does not need a repeated full report.

## Hard preconditions (details and incidents in `references/preconditions.md`)

1. Creating or re-creating a stack is ONE `gh stack link --base <trunk>
   <bottom-pr#> ... <top-pr#>`: the full ordered list, from a worktree on a
   stack branch. Without `--base` the bottom PR is retargeted to the default
   branch and locked there. Appending one PR to an existing stack may use
   `gh stack link <stack#> <pr#>`, which appends on top only and cannot
   insert. Either way, verify every affected base from sufficient mutation
   responses or existing observations; request a scoped view only for missing facts.
2. Cut a new layer only from a **pushed** head that contains every lower
   layer's head (`git merge-base --is-ancestor`). Two layers cut from the same
   head must declare at cut time which one merges the other forward.
3. Never rewrite a layer that has children. Never rebase a frozen layer to
   "catch up" with trunk. Never force-push under a live agent.
4. Freeze the trunk from the final sync until the landing is confirmed:
   explicit FREEZE to every trunk writer, acked. One stray push restarts every
   layer's CI.
5. Never merge a red layer, and never merge a red bottom layer alone when its
   fix lives above (that puts the red on the trunk). Remove the red layer from
   the stack so the fixing layer above carries its commits
   (`recipe-restack.md`, section 2).
6. Before any scoped `gh stack merge <pr>`, inspect sufficient verified remote
   composition, or acquire it with scoped `--refresh` (not `--refresh-status`);
   use the compact projection in `references/recipe-evidence.md`. Local catalog membership
   alone is not complete; an unseen upper empty draft can be swept in and deleted.
7. Land with `gh stack merge <stack#> --yes --merge` (merge commits only, by
   stack number so stale local tracking cannot pick the wrong stack). Never
   `--squash`.
8. Mergeability is `git merge-tree --write-tree A B` (exit code) or a real
   `git merge --no-commit` in a scratch worktree. Never the legacy 3-arg
   `merge-tree`; it prints diff3 hunks on clean merges.
9. Every push to a PR head restarts its CI. No cosmetic or metadata pushes to
   a green or running head; batch follow-ups into one validated push.
10. Landing, closing PRs and unstacking are outward-facing. Confirm with the
    user before `gh stack merge`, `gh pr close` or `gh stack unstack` unless the
    user already directed that exact action.

## Deterministic helpers

| Script (installed under `.claude/scripts/`) | Purpose | Mutates |
|---|---|---|
| `gh_stack_view.py` | Coherence, mergeability, CI and LANDING table for every open stack | no |
| `gh_stack_chain_check.py --trunk <trunk> <bottom> ... <top>` | Pre-link check: every head pushed, linear ancestry, PR bases as expected, top merges clean into trunk | no |

If `CLAUDE_PLUGIN_ROOT` is set (plugin install), the scripts are at
`$CLAUDE_PLUGIN_ROOT/scripts/`. Otherwise, if a script is not at
`.claude/scripts/`, locate it with `find .claude ~/.claude -name 'gh_stack_*.py'`
and use the newest match. Never reproduce the checks by hand.

## Storage

Shared observations live in the common repository's `.sc/sc-gh-stack/output/`;
nonsecret cooldown coordination lives in `~/.sc/sc-gh-stack/`. No tokens are
stored. Common and legacy per-worktree gh-stack catalogs are read locally;
conflicting tracking requires `recipe-stale-tracking.md` recovery.

## Related

- `../sc-gh-stack-view/SKILL.md` — the status tool this skill depends on.
- `sc-git-worktree` (if installed) creates the layer worktrees; the recipes
  show the plain `git worktree add` equivalent.
Files in this package (15)
  • SKILL.md 9 KB
  • references/commands.md 14 KB
  • references/installation-and-troubleshooting.md 4 KB
  • references/model.md 7 KB
  • references/phase-model-example.md 6 KB
  • references/preconditions.md 7 KB
  • references/recipe-cut-layer.md 3 KB
  • references/recipe-evidence.md 4 KB
  • references/recipe-land.md 6 KB
  • references/recipe-link.md 4 KB
  • references/recipe-restack.md 5 KB
  • references/recipe-stale-tracking.md 2 KB
  • references/stack-design.md 5 KB
  • references/troubleshooting.md 8 KB
  • references/workflow.md 6 KB

Versions

The database has no other skills named sc-gh-stack.

Database snapshot: 13.11.2026 · package version fac3a7667ab1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100stacked-prs
    GitHub's native stacked pull requests and the `gh stack` CLI. Covers creating a stack, editing a layer, restacking after a merge, and merging part or all of a stack. Use whenever the user mentions stacked PRs, a PR stack, GitHub stacks, dependent PRs, or `gh stack`, when…
  • 100pg-merging-stacked-prs
    Use when landing a stack of dependent GitHub PRs (A ← B ← C, where each bases on the one below) onto the trunk, merging a PR whose base is another open PR's branch, or whenever a request mentions "stacked PRs", "PR stack", "dependent PRs", or merging several related PRs in…
  • 100merging-pr-stack
    Use when merging a stack of stacked PRs with jj. Triggered by phrases like "merge the PR stack", "merge the stacked PRs", "land these PRs", or "merge the stack into main".
  • 90stacked-prs
    Design and operate GitHub stacked pull requests with the official github/gh-stack CLI. Use when deciding whether dependent work should be a stack, splitting work into valid layers, or creating, reviewing, updating, handing off, merging, cleaning up, or recovering a stack. Do not…
  • 100dsh-merging-stacked-prs
    Use when landing a stack of dependent GitHub PRs (A ← B ← C, where each bases on the one below) onto master, merging a PR whose base is another open PR's branch, or whenever a request mentions "stacked PRs", "PR stack", "dependent PRs", or merging several related PRs in…
  • 100dsh-merging-stacked-prs
    Use when landing a stack of dependent GitHub PRs (A ← B ← C, where each bases on the one below) onto master, merging a PR whose base is another open PR's branch, or whenever a request mentions "stacked PRs", "PR stack", "dependent PRs", or merging several related PRs in…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.