• worktree — "spin up a worktree for this branch", "make me a worktree for #42", "where is the worktree for

  issue-42-…

  ", "tear down this worktree", "list my worktrees", "clean up the ones that are merged".
• base ref — "what's the base branch here", "diff me against the base".
• sync — "should I rebase or merge here", "this branch is behind — bring it up to date".
• called by another skill — any skill that needs a worktree, a base ref, a branch name, or a sync decision delegates here and uses what comes back.

$ git worktree add ../wt-b feature-x
fatal: 'feature-x' is already used by worktree at '.../wt-a'

review-…

qa-…

• Lookup is by branch, always — through git, never by reading or guessing at a directory path. This is what makes the flattening above free, and what lets a worktree sitting in some older root keep working untouched.
• The "kind" of a worktree rides along for free, because the branch name already carries it.

  issue-42-auth-capability-module

  is named that because the branch was named that when the work started.

• issue-<n>-<slug>

  — work that starts from a tracker issue. Slug from the issue title: if it follows a conventional

  type(scope): summary

  form, strip the prefix; kebab-case the rest, cap at roughly 50 characters on a word boundary, drop a trailing hyphen. An empty slug degrades to a bare

  issue-<n>

  . The number guarantees uniqueness, so no tie-break is ever needed.

• pr-<n>-<slug>

  — only for a fork pull request, where no local branch exists yet and one must be invented to hold the fetched head. Slug from the head branch name, kebab-cased, capped at roughly 40 characters.
• Anything else — a branch name the human or the repo's convention supplies. gitkit does not rename it.

pr-*

git -C "$REPO" fetch origin --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE_ROOT/$(basename "$REPO")/$BRANCH" "$BASE"

• Fetch first, always. Branching off a stale base is silent and only surfaces as conflicts later.

• $BASE

  comes from The base ref — never a hard-coded

  origin/main

  , and never a sibling feature branch.
• Drop

  -b

  when the branch already exists locally (a same-repo PR you have fetched, a branch you made earlier);

  git worktree add <path> <branch>

  checks it out.
• For a fork pull request, fetch the head into a local branch first —

  git fetch origin "pull/<n>/head:pr-<n>-<slug>"

  — then add the worktree on that branch, no

  -b

  .

git -C "$REPO" worktree remove "$WT"
git -C "$REPO" branch -d "$BRANCH"     # only a branch you created, and only if merged

• A dirty worktree stops teardown. Show exactly what would be lost — uncommitted changes, untracked files, unpushed commits — and let the human decide. Never reach for

  --force

  on their behalf.
• Never remove a worktree you adopted rather than created. If it was already there when you arrived, it is someone else's context; you have no idea what is open in it.
• Never delete a branch you did not create.

  -d

  (not

  -D

  ) so git itself refuses an unmerged branch.

main

develop

trunk

master

1. gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

   — authoritative when the GitHub CLI is available and authenticated.

2. git symbolic-ref --short refs/remotes/origin/HEAD

   — the local record, if it has been set.

3. git remote set-head origin --auto

   to repair an unset

   origin/HEAD

   , then retry the previous step. This is the step most implementations skip, and it is the one that turns a failure into an answer.
4. Whichever of

   origin/main

   /

   origin/master

   actually exists.
5. Ask the human. Do not guess past this point.

git diff <base>...HEAD

Rebase onto the base to sync a feature branch — published or not. Merging the base in is an exception that needs a stated reason and the user's consent.

git fetch origin
git rev-list --left-right --count "origin/$BASE"...HEAD   # "<behind>\t<ahead>"; left > 0 means behind
git rebase "origin/$BASE"

• Rebase is the answer unless someone has said otherwise for this branch. No pull request, an open one, a shared branch — the recommendation is the same.
• A branch with no remote counterpart rebases straight through. Nothing points at those SHAs, so nothing can break; this is the cheap-and-reversible class, and it needs no confirmation.
• A published branch previews once and waits. One confirmation covers the rebase and the

  --force-with-lease

  push that follows — they are a single decision, and asking twice asks the same question twice. Name what it costs: the base being synced, the commits being rewritten, and the number of unresolved review threads that will go outdated.
• Count the threads before you ask. On a branch with an open PR, query the GraphQL

  reviewThreads

  connection for unresolved threads and put the number in the preview. "3 review threads will be marked outdated" is a fact the user can decide on; "this may outdate review comments" is not.
• Unresolved threads are the reason to offer the merge exception — not to take it. Still recommend the rebase; name merge as the available alternative alongside the count. A preference that folds in the case that argues against it was never a preference.

• --force-with-lease

  , never bare

  --force

  — the lease is what stops you overwriting a commit someone else pushed while you were rebasing.
• On conflict, stop and surface it (

  git diff --name-only --diff-filter=U

  ). Propose a resolution per file and confirm before writing. A conflict resolution is a code change: run the repo's test gate afterward.

git merge "origin/$BASE" -m "chore(repo): sync with origin $BASE"

• Never git's default subject.

  Merge branch 'main' into issue-42-tailwind-4-foundation

  is what git writes when nobody chose a message, and it reads that way forever in

  git log

  . The fixed subject is the message.
• Interpolate the base, don't hardcode

  main

  . The base ref ladder exists because

  develop

  and

  trunk

  repos are real; a subject that says

  main

  in one of them is simply false.
• No

  --no-ff

  . If the sync can fast-forward, the branch had nothing of its own to preserve and git writes no commit at all — there is no subject to fix, and forcing one manufactures an empty merge commit.
• State the reason in the same breath as the ask. "Merging instead of rebasing because this PR has 3 unresolved review threads" is a reason. "Merging to be safe" is not; if you cannot name what rebasing would break, rebase.

• Mount both

  $WORKTREE_ROOT

  and the main checkout. A worktree's real git directory lives under the main repo's

  .git/worktrees/

  ; mounting only the worktree yields a broken checkout.
• Mount both at the same absolute path inside and outside the container. This is the robust answer.
• Second belt, on git 2.48+:

  git config worktree.useRelativePaths true

  and

  git worktree repair --relative-paths

  . Relative pointers survive remapping as long as the repo and the worktree root keep their relative positions — which argues for siding them, e.g.

  ~/code/<repo>

  and

  ~/worktrees/<repo>

  .

git worktree list

• gitkit is the single source of truth for what it owns. A calling skill may hold policy about when to ask — that a PR is worth pulling down, that a branch is ready to publish — but never about how the git operation is done. If you find a worktree path, base-ref ladder, or rebase rule restated inside another skill, that is the bug.
• gitkit never implements, commits, or opens anything. It prepares the ground and tears it down. Writing code in the worktree, committing, and publishing belong to other skills.
• Destructive steps preview and confirm. Removing a worktree, deleting a branch, and rebasing a published branch each show what is about to happen and wait for an OK. Creating, adopting, and rebasing an unpushed branch are cheap and reversible — those run straight through. The line is whether anything outside this machine points at what you are about to rewrite, not which command you typed.
• No shell available (e.g. a browser-based agent)? Then you cannot run git. Reason from what the user provides and print the exact commands as a codeblock for them to run — never report a worktree created or removed that you could not perform.