Restack

Restack

ARGUMENTS: $ARGUMENTS

Propagate the current branch's changes into the branches stacked on top of it. Each stacked branch was created off — and targets — its parent (that's what /sculptor-experimental:stack sets up), so "propagating" means merging each parent's updated tip into its child, in order from base to tip.

This is a merge-based restack: it brings the parent's new commits into each child with a merge commit. It does not rewrite history, so no force-push is needed and open MRs/PRs keep their commits and review threads. The merge also keeps each child's scoped diff correct — after merging parent P into child C, the diff of C against P is exactly C's own changes.

This skill uses the sculpt CLI and operates directly on the shared on-disk git repo. The agent shell already has SCULPT_WORKSPACE_ID (current workspace) and SCULPT_PROJECT_ID set.

$ARGUMENTS is optional. It may name a different root branch to propagate from; if empty, propagate from the current branch.

Step 0 — Refuse if not in a worktree workspace

Restacking only works in worktree workspaces. Every branch in the stack lives in its own git worktree sharing one on-disk .git, which is what lets this skill resolve and merge them locally. From a clone or in-place workspace the stacked branches aren't locally resolvable.

sculpt workspace show "$SCULPT_WORKSPACE_ID" --json | jq -r .strategy

If the result is not WORKTREE, stop and tell the user (using their strategy name):

Restacking isn't supported from a <strategy> workspace — the stacked branches aren't locally resolvable. Restack from a worktree workspace instead.

Only proceed if the strategy is WORKTREE.

Step 1 — Discover the stack

1. Resolve the root branch — the branch whose changes you're propagating down. Use $ARGUMENTS if it names a branch; otherwise the current branch:

   git rev-parse --abbrev-ref HEAD

2. List the project's workspaces (stdout is clean JSON; the human-readable preamble goes to stderr):

   sculpt workspace list --json

   Each item has id, strategy, source_branch, target_branch, requested_branch_name, and is_deleted.

3. Build the stack graph. A workspace C is a stacked child of branch P when all of:

   • C.is_deleted is false and C.strategy == "WORKTREE",
   • C.requested_branch_name is set (this is C's own branch), and
   • C.target_branch, with any leading remote prefix stripped, equals P.

   The target may be stored either bare (my-branch) or remote-qualified (origin/my-branch) — strip a leading origin/ (or other remote) before comparing. Starting from the root branch, collect its children, then their children, and so on, recording edges (parent_branch, child_branch) in base→tip order (parents before children). Guard against cycles and against a branch listing itself as its own parent.

4. Map each branch in the stack to its on-disk worktree path:

   git worktree list --porcelain

   Match on branch name (strip the refs/heads/ prefix). Skip — with a warning — any stacked branch that has no live worktree (e.g. its workspace was deleted); also skip its descendants, since their parent can't be resolved.

5. If the root has no stacked children, report that nothing is stacked on it and stop.

Show the user the discovered stack as a tree (root at the bottom of the stack, descendants above) before changing anything.