klaussy-restack.Rebase a stack of dependent branches so each one sits on top of its parent again, then push the stack. klaussy restack does the git mechanics: it maps the chain from ancestry and reflogs, rebases bottom-up with --onto, verifies, and pushes with a lease. Your job is the two decisions it can't make: confirming the chain, and resolving conflicts.
If the klaussy command isn't found, run it as python3 -m klaussy <command> (python -m klaussy on Windows, where python3 is usually absent) before falling back any further — the package is often installed with only its script directory off PATH. Use the fallback named for that step when that fails too, and say which one you used: a fallback answers a narrower question than the command it stands in for.
If klaussy isn't on PATH (the command isn't found), follow .agents/skills/fastapi-restack/manual.md instead; it's the same procedure by hand.
First, check for a stack tool. If the repo uses Graphite, git-town, spr or ghstack, or the host carries a native stack (see the forge commands below), use that tool's own restack command so its metadata stays consistent, and say which you found.
\nRun klaussy restack plan, which resolves the base itself (pass --base to override). It fetches, then prints the chain bottom-up, which branches already landed in the base, who authored the commits, and any line that needs you:
Show the user the chain and confirm it before anything is rewritten; a wrong parent drops or duplicates commits. If the stack holds commits by someone else, get explicit confirmation before force-pushing over their work. Optionally cross-check the chain against the forge's request bases; if they disagree, surface it rather than picking one.
\nRun klaussy restack run --chain <confirmed chain> with the chain exactly as confirmed. It records every branch's tip first, so klaussy restack undo puts everything back until you push.
Exit code 2 means a conflict. For each file it names:
\n--ours / --theirs to make it go away.git add the file, then git rebase --continue, then klaussy restack run --continue.If a conflict is genuinely ambiguous, run klaussy restack undo and hand it back with the specifics. A half-rebased stack is worse than stopping.
Run klaussy restack verify. Every branch should keep its own commit count. Lines marked ! are commits whose content changed in the move, which is expected where you resolved a conflict and a red flag anywhere else. Read those before pushing.
If a request's parent changed or landed, retarget its base with the forge commands below, before the push where the forge allows, so it never briefly shows its parent's commits as its own.
\norigin points at GitHub, so the gh CLI is the adapter. Confirm a flag with gh <command> --help before running one you haven't used in this repo; CLI interfaces drift between versions.
| Need | \nCommand | \n
|---|---|
| Read a ticket | \ngh issue view <n> --comments | \n
| Open a request | \ngh pr create --base <branch> --title <title> --body-file <file> | \n
| Request status | \ngh pr view <n> --json state,mergeable,reviewDecision,baseRefName | \n
| CI status | \ngh pr checks <n>, then gh run view <run-id> --log-failed on a failure | \n
| Retarget a request | \ngh pr edit <n> --base <branch> | \n
{owner}/{repo} are placeholders gh fills from the current repo, leave them literal.
GitHub has native stacks, driven by the gh-stack extension. gh extension list says whether it's installed. If it isn't, offer to install it — gh extension install github/gh-stack, one command, no repo changes — and say what it buys before asking: a stack map and layer navigation on every request page, plus cascading rebase when the base moves. Ask rather than installing unprompted, since it touches the user's gh setup and not this repo, but do ask; silently settling for bare chained bases hands back a worse result than the one command would have. Declining is a fine answer and the fallback below still works.
The extension is in public preview, so check gh stack <command> --help before relying on a flag.
| Need | \nCommand | \n
|---|---|
| Link requests that already exist into a stack | \ngh stack link --base <branch> <branch-or-pr> <branch-or-pr> ... | \n
| Track a carved chain locally | \ngh stack init --base <branch> <branch> ... | \n
| Push the tracked chain and open or update its requests | \ngh stack submit | \n
| See the stack | \ngh stack view | \n
| Cascading rebase after the base moved | \ngh stack rebase | \n
| Fetch, rebase, push, and sync in one pass | \ngh stack sync | \n
Arguments run bottom-up, nearest the base first. Two constraints decide whether a stack is available at all: every branch must live in this repo (cross-fork stacks aren't supported), and the extension has to be installed.
\nlink and init are two different entry points and the difference shows up later. link stacks requests that already exist and leaves nothing behind locally, so a later gh stack rebase needs gh stack checkout <stack-number> first to pick the stack back up. init registers the branches locally up front and submit then opens the requests itself, which means the bodies are its own — write them with gh pr edit <n> --body-file afterwards if they have to say something specific.
Without it, chained --base targets still give reviewers a per-layer diff, and GitHub often offers to convert an eligible chain into a stack — a banner on the request, or \"Add to stack\" behind the stack icon. Say which route you took.
A missing, unauthenticated or nonexistent CLI is not a failure here. Print what's left instead: each branch, its new parent, and the one field to change. Never ask the user to install a hosting CLI to finish a rebase.
\nThen run klaussy restack push. It force-pushes bottom-up with --force-with-lease --force-if-includes, never pushes master, and stops at the first refusal. A refused lease means someone else pushed: fetch and look. Never fall back to a bare --force.
Report the stack's new shape, the pre-restack tips from the plan output (the recovery path now that the push is done), and anything left to retarget by hand. Say plainly that only what CI re-runs is verified; a clean rebase is not a passing test.
\nmaster is behind — that's a plain git rebase origin/master, no stack machinery needed.