name: ai-cleanup description: Use after merging a PR, at session start, or to tidy up branches. Trigger for 'tidy up', 'clean up branches', 'sync to main', 'get back to main', 'delete old branches', 'what branches do I have', 'start fresh'. Also automatically invoked by /ai-pr after merge. Safely switches to default branch, prunes merged and squash-merged branches, produces per-branch status report. effort: medium argument-hint: "--branches|--sync|--all" tags: [git, branch, cleanup, hygiene, status, delivery] requires: bins:
- git
Repository Cleanup
Full repository hygiene: safely migrate to the default branch, delete merged and squash-merged branches, and produce a per-branch status report. No destructive operations without confirmation.
When to Use
- Session start, after merging PRs, between tasks, before
/ai-brainstorm. - NOT for committing -- use
/ai-commit.
Process
Default (no flags) is equivalent to --all: runs sync, branch cleanup, and report.
Phase 0: Safe Migration (--sync or --all)
- Detect default branch --
git symbolic-ref refs/remotes/origin/HEAD(main or master). - Record current branch for the report.
- Auto-stash if dirty --
git stash push -m "cleanup-auto-stash-$(date +%s)". - Switch to default --
git checkout <default>. - Pull latest --
git pull --ff-only origin <default>. If ff-only fails: WARN and STOP. - Restore stash --
git stash pop. If conflict: WARN, leave stash, continue cleanup.
Phase 1: Branch Analysis (--branches or --all)
- Fetch and prune --
git fetch --prune origin. - Enumerate all local branches (excluding
main,master). - Classify each branch:
| Category | Criteria | Action |
|---|---|---|
| Merged | In git branch --merged <default> | Delete (git branch -d) |
| Squash-merged | Not in --merged but git diff <default>..<branch> is empty | Delete (git branch -D) |
| Gone (safe) | Tracking ref [gone] AND no content diff | Delete (git branch -D) |
| Gone (has dev) | Tracking ref [gone] BUT has content diff | KEEP |
| Active | Has remote tracking, not merged | KEEP |
| Local only | No remote, has commits ahead | KEEP |
- Delete eligible -- merged with
-d, squash-merged and gone-safe with-D.
Phase 2: Status Report
- Build per-branch table:
## Repository Cleanup Report
**Default branch**: `main` (up to date)
**Previous branch**: `feat/old-feature`
**Working tree**: clean | stash restored | stash pending
| Branch | Action | Reason | Remote | Ahead/Behind |
|--------|--------|--------|--------|--------------|
| `feat/done` | DELETED | Merged | -- | -- |
| `feat/squashed` | DELETED | Squash-merged | -- | -- |
| `feat/active` | KEPT | Unmerged (5 commits) | origin/feat/active | +5/-2 |
Quick Reference
/ai-cleanup # full: sync + branch cleanup + report
/ai-cleanup --sync # sync to default branch only
/ai-cleanup --branches # branch cleanup only (no migration)
/ai-cleanup --all # explicit full cleanup
Common Mistakes
- Force-pulling when ff-only fails -- STOP and resolve manually.
Integration
Run before /ai-brainstorm to start clean. Composes with session start protocol.
References
.ai-engineering/manifest.yml-- protected branch rules..codex/skills/ai-brainstorm/SKILL.md-- spec creation composes cleanup. $ARGUMENTS