| name | cleanup-workspace |
| description | Park a finished worktree — commit real work, delete temporary/generated leftovers, then switch to the throwaway branch named after the workspace directory and reset it to origin/master. Use when the user says "clean up this workspace", "park this worktree", "reset back to master", or is done with a feature branch and wants the directory ready for the next task. |
| allowed-tools | Bash, Read, Glob, Grep |
Clean Up / Park a Workspace
This repository is used through several sibling git worktrees
(/home/haui/devel/phoneblock, pb-1, pb-2, pb-3, pb-fix-sip, …). Each
pb-N worktree has a same-named throwaway branch (pb-1, pb-2, …) that tracks
origin/master and holds no work of its own. Between tasks a worktree is parked:
its feature branch is left behind (never deleted — the work lives on in origin
and in the branch ref), and the directory returns to its throwaway branch at the
current origin/master.
origin is haumacher/phoneblock. Always name origin explicitly.
Step 1 — Survey the workspace
git status
git stash list
git worktree list
Then, for the currently checked-out branch, find work that exists only locally:
git log --oneline @{upstream}..HEAD
Report what you found before changing anything.
Step 2 — Classify every uncommitted file
Split the dirty/untracked entries into two piles. Read or diff each file you
are unsure about — never classify by filename alone.
Commit — anything that is source, config, docs, tests, or release notes; in
short, work a reviewer would want. Group related files into commits with proper
messages, following the repository's commit style (git log for reference) and
ending each message with the Co-Authored-By: Claude trailer required by the
environment.
Delete — build output and tool leftovers that were never meant to be
tracked, e.g.:
phoneblock-dongle/firmware/sdkconfig.stale-* — ESP-IDF's backup of a
regenerated sdkconfig (sdkconfig itself is git-ignored, the .stale-*
copy is not, so it surfaces as untracked). Confirm it is just a generated
snapshot (diff it against sdkconfig) and remove it.build/, target/, scratch scripts, log files, *.orig/*.rej merge
debris, editor backups.
Two rules:
- If a file's pile is genuinely unclear, ask. Do not guess between
committing and deleting.
- Never delete something merely because it is untracked and inconvenient.
Untracked source is the most common form of unsaved work.
If a file should be ignored permanently rather than deleted every time,
propose the .gitignore addition — that change is itself a commit.
Stashes: leave them alone and tell the user they exist. Do not drop or pop a
stash without being asked.
Step 3 — Verify clean
git status --porcelain
Do not continue while output remains.
Step 4 — Determine the throwaway branch
It is the basename of the worktree directory — basename "$(git rev-parse --show-toplevel)"
(for /home/haui/devel/pb-1 that is pb-1). Do not invent a name and do not
reuse another worktree's.
Two checks before switching:
git worktree list — if that branch is checked out in a different
worktree, the checkout will fail. Stop and ask the user which branch to park
on.git log --oneline origin/master..<branch> — if the throwaway branch has
commits of its own, git reset --hard would discard them. Stop, show them,
and ask. (Normally this is empty; that's what makes the branch throwaway.)
The main worktree (/home/haui/devel/phoneblock) parks on master itself, not
on a pb-N branch.
Step 5 — Switch, fetch, reset
git checkout <branch>
git fetch origin --prune --tags
git reset --hard origin/master
--hard is intended here: the point is to discard local divergence of the
throwaway branch. It is safe only because steps 3 and 4 proved there is
nothing to lose.
Step 6 — Report
Confirm the final state (git status, git log --oneline -3) and tell the user:
- which commits were created (if any) and whether they still need pushing,
- which files were deleted,
- the branch left behind and that its work is preserved there,
- the commit the workspace now sits at.
If commits were created on the feature branch and are not yet pushed, say so
explicitly — the branch ref keeps them locally, but they exist nowhere else.
Ask whether to push; do not push on your own initiative.
