branch-cleanup

name	branch-cleanup
description	Post-merge lifecycle cleanup. Investigates the full state first, presents one decision summary, then executes after user approval. Commits leftover artifacts, deletes the session plan file, archives the worktree's isolated .planning, and delegates worktree removal to the worktree-manager agent. Pairs with branch-finisher as the closing bookend of a feature branch.

Branch Cleanup

Overview

The post-merge companion to branch-finisher. Where branch-finisher ships a branch (commit -> push -> PR), branch-cleanup closes the loop after the PR merges: commit leftovers, discard the session plan, and tear down the worktree cleanly.

Invoke with /branch-cleanup when a PR has been merged and the worktree is no longer needed.

When to Use

• The PR for this branch has been merged to main
• Untracked artifacts exist that need committing or discarding
• A session plan file exists in .claude/plans/ and the work is fully shipped
• User says "clean up", "we're done", "remove this worktree", "tear down this branch"

---

Procedure

Phase 1 - Investigate everything first (no actions yet)

Run all of these in parallel before asking the user anything:

1a. PR status

gh pr list --head <current-branch> --state all

Note: merged PR numbers, titles, and merge dates.

1b. Untracked files

git status

For each untracked item, classify it:

Item	Classification
.planning/	Real isolated dir - archive before removal. Each worktree now owns a real, isolated .planning (phases + STATE.md private to this branch). Before tearing the worktree down, archive it to the shared archive so the phase history survives (Phase 3e). It is gitignored, so never commit it to the feature branch and never git clean it.
local-scripts/	Scratch scripts - likely discard
Any other untracked path	Unknown - needs user decision

1c. Modified tracked files Check git diff and git diff --staged for any uncommitted changes to tracked files.

1d. Plan files

Get-ChildItem $env:USERPROFILE\.claude\plans\ -Name

Identify which plan files belong to this branch's work (by name or content). A plan is safe to delete if its PR is merged and no "Remaining work" section has open items.

---

Phase 2 - Present one decision summary

After gathering all of the above, show the user a single block:

Branch: <branch-name>
PRs merged: #<n> — <title>, #<n> — <title>

Untracked artifacts:
  .planning/     → real isolated dir; archive to shared archive before removal
  <other-path>   → [commit as docs: / discard]  ← your choice

Modified tracked files:
  <file>         → [commit / discard]  ← your choice
  (none)

Plan files to delete:
  <plan-file>.md → [delete / keep]  ← your choice

After your approval:
  1. Commit / discard artifacts as decided above
  2. Delete selected plan files
  3. Archive .planning, then remove worktree via worktree-manager (destroys Docker volume, irreversible)

Proceed?

Wait for the user's typed response before doing anything.

---

Phase 3 - Execute after approval

Execute the approved actions in order:

3a. Handle modified tracked files first (if any) Use the /commit skill — dirty working tree must be clean before worktree removal.

3b. Commit approved artifacts Use the /commit skill with type docs: (patch bump). Stage only the specific approved paths — never git add . or git add -A.

3c. Discard rejected artifacts

git clean -fd <specific-path>

Never run git clean -fd without a specific path.

3d. Delete approved plan files

Remove-Item "$env:USERPROFILE\.claude\plans\<plan-file>.md"

3e. Archive this worktree's .planning

The worktree's .planning is a real, isolated directory. Preserve its phase history before removal:

$src = "C:\dev\wwv\worldwideview.<branch>\.planning"
$dst = "C:\dev\wwv\.planning\archive\<branch>"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Copy-Item "$src\*" $dst -Recurse -Force

Skip if .planning has no phases worth keeping (fresh milestone: none state). The shared archive lives at C:\dev\wwv\.planning\archive\.

3f. Remove the worktree Delegate to the worktree-manager agent:

"Remove the worktree for branch <branch-name>."

The agent runs git-wt remove --force --yes <branch> from the main repo, tears down Docker volumes, and verifies cleanup. (The worktree's real .planning is removed along with the worktree directory, which is why Phase 3e archives it first.)

Do not run git-wt remove directly - use the agent so verification and troubleshooting are handled correctly.

---

Phase 4 - Summary

Report:

• PRs merged: #<n> — <title> (list)
• Artifacts: committed / discarded (list)
• Plan files: deleted / kept
• Worktree: removed from C:\dev\wwv\worldwideview.<branch>\
• Next step:

  cd C:\dev\wwv\worldwideview && git pull
  

---

Quick reference

Phase	Action	Rule
Investigate	PR status, git status, plan files	Parallel - no actions yet
Decide	One summary block	Wait for user approval
Execute	Commit, delete plans, remove worktree	In order, after approval
.planning/	Archive then remove	Real isolated dir; preserve phase history first