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.
- Author
- randlee ↗
- Repository
- synaptic-canvas ↗
- Licence
- MIT
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
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
- Step 1 — Verify gh, the gh-stack extension, git, python3
- Step 2 — Obtain the evidence the operation needs
- The model (read references/model.md once)
- What to do (pick the row, open the reference)
- Hard preconditions (details and incidents in references/preconditions.md)
- Deterministic helpers
- Storage
- Related
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…