CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

worktree-cleanup

Prune merged feature worktrees, fast-forward the root checkout's base branch, run the project's post-sync command, and refresh the "Active worktrees" row in docs/diary.md. Invoke as `/worktree-cleanup` (or `/worktree-cleanup --dry-run` to preview). Conservative — never removes dirty or unmerged worktrees.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is worktree-cleanup in agranado2k/google-books-clojure

SKILL.md
Quality
Evals
Security

/worktree-cleanup — prune merged worktrees + sync the root checkout

What this does

Closes the lifecycle the root AGENTS.md's first hard rule opens. Agents create worktree/<slug> per feature, but after the pull request merges the worktree, its local branch, and the diary's "Active worktrees" row are all left behind — and the root checkout's base branch goes stale, so the next worktree branches from an old base and pays a merge-reconciliation tax later.

The git mechanics live in scripts/worktree-cleanup.sh; this skill runs it and then does the one thing a script should not do on a human's behalf — edit the project's own memory.

Hard rules

  1. Never force-remove. The script already skips dirty or unmerged worktrees; do not override it by removing a worktree or deleting a kept branch by hand.
  2. Never touch uncommitted work in the root checkout. If the script reports the root as dirty, surface that to the operator; don't stash or commit on their behalf.
  3. Diary edits follow the diary's own update protocol (it is stated in docs/diary.md's header): refresh the "Active worktrees" row in the Current state block, which is edited in place; never rewrite or delete the dated entries below it.

Procedure

  1. Dry-run first and show the operator what would happen:

    sh scripts/worktree-cleanup.sh --dry-run
  2. Run for real (skip step 1's pause if the operator invoked the skill with a clear "clean up" intent — the script is conservative by design):

    sh scripts/worktree-cleanup.sh
  3. Update docs/diary.md: set the "Active worktrees" row in the Current state table to the worktrees that remain (or "None." if empty). If the row was already stale before this run, say so in the next dated entry rather than silently fixing history.

  4. Report the script's summary block plus the diary edit: base branch before → after, worktrees removed, worktrees kept and why.

What "merged" means here

A branch is pruned when it is an ancestor of the base ref (the normal case for merge commits and rebases) or its pull request is recorded as merged by the forge CLI. The second test exists because squash merges rewrite the commits, so ancestry can never succeed for them. Anything that satisfies neither test is kept.

Configuration

Both are environment variables read by the script, both optional:

  • WORKTREE_CLEANUP_BASE — the merge target. Defaults to origin's HEAD branch.
  • WORKTREE_CLEANUP_POST_SYNC — a command to run when the base branch moved, typically a dependency install. Empty by default: the kit does not know your toolchain, so it prints a reminder instead of guessing. Set it in constitution/local-workflow.md's "Before you push" section once you know what it should be, so the next person does not have to rediscover it.

Cross-references

  • The root AGENTS.md, hard rule 1 — why the worktrees exist at all.
  • /merge-train — runs this skill as its final step, once a batch has landed.
  • docs/diary.md — the update protocol step 3 obeys.
Repository

agranado2k/tic-tac-toe-with-agentic-sdlc

Path

.claude/skills/worktree-cleanup/SKILL.md

Last updated
First committed

Canonical home

agranado2k/google-books-clojure
In sync

since Nov 19, 2026

Also appears in

agranado2k/tic-tac-toe-haskell
In sync

since Nov 19, 2026

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.