branch-cleanup

name	branch-cleanup
description	Clean up merged and stale branches from local and remote repositories. Use when branch list is cluttered or after merging PRs.
argument-hint	[project-name] [--execute] [--include-remote]
user-invocable	true
disable-model-invocation	true
context	fork
allowed-tools	Bash(git *)
loop_safe	false
iso_class	none

Branch Cleanup Command

Clean up merged and stale branches from local and remote repositories.

Usage

/branch-cleanup [<project-name>] [options]
/branch-cleanup [--execute] [--include-remote] [--stale-days <days>]

Example:

/branch-cleanup                                    # Dry-run preview (default), local only
/branch-cleanup --execute                          # Actually delete the previewed branches
/branch-cleanup hospital_erp_system                # Preview specific project
/branch-cleanup --execute --include-remote --stale-days 30  # Delete, include remote, 30-day threshold

Arguments

• <project-name>: Optional project directory name (defaults to current directory)

Options

Option	Values	Default	Description
--execute	flag	false	Actually delete branches. Without it, the command is a read-only dry-run preview.
--include-remote	flag	false	Also clean remote tracking branches
--stale-days	number	90	Days since last commit to consider stale

By default (no --execute) the command performs a read-only dry-run preview and deletes nothing. Confirmation happens at invocation time by adding --execute — there is no interactive mid-run prompt, so the command is scriptable.

Protected Branches

The following branches are never deleted, regardless of their merge status:

Branch Pattern	Rationale
main	Primary production branch
master	Legacy primary branch
develop	Development integration branch
release/*	Release preparation branches
hotfix/*	Emergency fix branches

Instructions

Execute the following workflow:

1. Navigate to Project

# If project name provided
cd <project-name> 2>/dev/null || { echo "Error: Project directory not found"; exit 1; }

# Fetch latest remote state
git fetch --prune origin

2. Identify Merged Branches

# Get current branch
CURRENT_BRANCH=$(git branch --show-current)

# List branches merged into develop, main, or master
MERGED_BRANCHES=$(
  { git branch --merged develop 2>/dev/null; \
    git branch --merged main 2>/dev/null; \
    git branch --merged master 2>/dev/null; } | sort -u
)

# Filter out protected branches and current branch
echo "$MERGED_BRANCHES" | grep -v -E "^\*|main|master|develop|release/|hotfix/"

3. Identify Stale Branches

# Find branches with no commits in the last N days
STALE_THRESHOLD=$(date -d "$STALE_DAYS days ago" +%s 2>/dev/null || date -v-${STALE_DAYS}d +%s)

for branch in $(git branch --format='%(refname:short)'); do
    LAST_COMMIT=$(git log -1 --format='%ct' "$branch" 2>/dev/null)
    if [[ -n "$LAST_COMMIT" && "$LAST_COMMIT" -lt "$STALE_THRESHOLD" ]]; then
        echo "$branch (stale: no commits in $STALE_DAYS days)"
    fi
done

4. Display Branches for Cleanup

Present categorized results:

## Branches Identified for Cleanup

### Merged Branches (safe to delete)
- feat/issue-123-add-login
- fix/issue-456-null-check

### Stale Branches (no commits in 90+ days)
- feat/old-experiment (last commit: 2024-06-15)
- fix/abandoned-fix (last commit: 2024-05-20)

### Protected Branches (will NOT be deleted)
- main
- develop
- release/v2.0

5. Gate Deletion on --execute

The default run is a read-only dry-run preview. Stop here unless --execute was passed — the user confirms by re-invoking with the flag, so there is no interactive prompt.

# Without --execute, this is a preview only: report and exit without deleting.
if [[ "$EXECUTE" != "true" ]]; then
    echo "Dry-run preview only. Re-run with --execute to delete the above branches."
    exit 0
fi

6. Delete Local Branches

for branch in $BRANCHES_TO_DELETE; do
    # Skip protected branches
    if [[ "$branch" =~ ^(main|master|develop|release/|hotfix/) ]]; then
        echo "Skipping protected branch: $branch"
        continue
    fi

    # Delete local branch
    git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
    echo "Deleted local branch: $branch"
done

7. Delete Remote Branches (if --include-remote)

if [[ "$INCLUDE_REMOTE" == "true" ]]; then
    for branch in $REMOTE_BRANCHES_TO_DELETE; do
        # Skip protected branches
        if [[ "$branch" =~ ^(main|master|develop|release/|hotfix/) ]]; then
            echo "Skipping protected remote branch: $branch"
            continue
        fi

        git push origin --delete "$branch"
        echo "Deleted remote branch: $branch"
    done
fi

8. Report Results

Provide summary of actions taken.

Policies

See _policy.md for common rules.

Command-Specific Rules

Item	Rule
Protected branches	Never delete main, master, develop, release/, hotfix/
Current branch	Never delete the currently checked-out branch
Confirmation	Default run is a read-only dry-run preview; deletion requires the explicit --execute flag
Remote deletion	Only with explicit --include-remote flag

Output

After completion, provide summary:

## Branch Cleanup Summary

| Item | Value |
|------|-------|
| Project | <project-name> |
| Mode | Dry-run / Executed |
| Stale threshold | 90 days |

### Deleted Branches
| Branch | Type | Last Commit |
|--------|------|-------------|
| feat/issue-123 | merged | 2024-12-01 |
| fix/old-bug | stale | 2024-06-15 |

### Skipped Branches
| Branch | Reason |
|--------|--------|
| main | Protected |
| develop | Protected |
| feat/current-work | Current branch |

### Statistics
- Local branches deleted: N
- Remote branches deleted: N
- Total branches cleaned: N

Error Handling

Prerequisites Check

Requirement	Error Message	Resolution
git installed	"Git is not installed"	Install git from https://git-scm.com
inside git repo	"Not a git repository"	Navigate to a git repository
Project directory exists	"Project directory not found: [path]"	Verify project path

Runtime Errors

Error Condition	Behavior	User Action
No branches to clean	Report "No merged or stale branches found"	No action needed
Branch deletion failed	Report specific branch and error, continue with others	Check if branch has unmerged changes
Remote deletion failed	Report "Cannot delete remote branch: [name]"	Verify remote permissions
Protected branch in list	Skip automatically with warning	No action needed
Current branch selected	Skip automatically	Checkout different branch first
Network error (remote)	Report "Cannot reach remote - check connection"	Verify internet connection

Side Effects and Loop-Safety

This skill is loop_safe: false. It deletes merged and stale local/remote branches. Repeated invocation is a destructive cascade with nothing left to do after the first pass, and could race against concurrent branch creation. Run it once per cleanup; do not wrap it in /loop.