Cleanup 2

---
name: cleanup
description: "Clean up completed work: inspect branches, update main, remove merged branches (local and optionally remote), reconcile beads, and produce a concise report. Trigger on queries like: 'clean up', 'tidy up', 'prune branches', 'housekeeping'."
---

# Cleanup Skill

Triggers
- "clean up"
- "tidy up"
- "cleanup"
- "housekeeping"

## Purpose
- Inspect repository branches and beads, identify merged or stale work, remove safely deletable branches, propose bead closures, and produce a concise report of actions and next steps.

## Required tools
- `git` (required)
- `bd` (beads CLI) — optional but recommended for bead metadata
- `gh` (GitHub CLI) — optional for PR summaries

## Runtime flags (recommended)
- `dry-run` (default): list actions without performing deletes or closes
- `confirm_all`: allow single confirmation to apply a group of safe actions
- `delete-remote` (opt-in): permit remote branch deletion when explicitly confirmed

## Preconditions & safety
- Never delete a remote branch or close a bead without explicit confirmation.
- Never rewrite history or force-push without explicit permission.
- Default protected branches: `main`, `master`, `develop` (do not delete or target for deletion).
- Detect default branch dynamically when possible (check `git remote show origin` or fallback to `main`).
- Use conservative merge checks (`git merge-base --is-ancestor`) to determine whether a branch's HEAD is contained in the default branch.

## High-level Steps

1) Inspect current branch
- Show current branch: `git rev-parse --abbrev-ref HEAD`.
- Detect default branch (recommended): `git remote show origin` and parse "HEAD branch". Fallback to `main`.
- If current branch is not the default branch:
  - Fetch remote: `git fetch origin --prune`.
  - Check whether current branch is merged into `origin/<default>`:
    - `git merge-base --is-ancestor HEAD origin/<default>` (exit code 0 => merged)
  - If not merged: present summary (branch name, last commit, unpushed commits, associated bead) and ask user: keep working / open PR / merge / skip deletion.
  - If merged and user permits (or in `confirm_all`), allow continuing to default branch.

2) Switch to default branch and update
- `git fetch origin --prune`.
- `git checkout <default>`.
- `git pull --ff-only origin <default>` (if fast-forward fails, report and ask).

3) Summarize open PRs targeting default
- If `gh` available: `gh pr list --state open --base <default> --json number,title,headRefName,url,author`.
- Present any open PRs and their head branches; skip deleting branches that have open PRs unless user explicitly authorizes.

4) Identify merged local branches
- List local branches merged into `origin/<default>` using conservative check per branch:
  - For each branch `b` (excluding protected names and current):
    - `git merge-base --is-ancestor b origin/<default>` (exit code 0 => merged)
- Present candidate list with metadata: last commit date, upstream (if any), bead id (if parseable), and open PR presence.
- Ask user to confirm deletion. If confirmed and not `dry-run`: `git branch -d <branch>` (safe delete). If `-d` fails, report and offer `-D` only with explicit permission.

5) Offer remote deletion (opt-in)
- For each deleted or candidate local branch with a remote `origin/<branch>`:
  - Verify no open PR references it and that it is merged (use `git merge-base --is-ancestor origin/<branch> origin/<default>`).
  - Present remote deletion candidates; ask per-branch or grouped confirmation based on `confirm_all`.
  - If confirmed and not `dry-run` and `delete-remote` enabled: `git push origin --delete <branch>`.

6) Summarize remaining branches
- Produce a table of remaining local and remote branches with: name, upstream, last commit, merged? (yes/no), bead id (if any), and open PR links (if available).
- For each remaining branch, offer actions: keep / delete / create PR / assign bead / rebase / merge.

7) Beads (bd) review
- Run `bd sync` to ensure bead data is current.
- If `bd` available: `bd list --status in_progress --json`.
- Cross-reference beads with branches found in the repo. For each in-progress bead, show last updated, linked branches, and recommend close if: bead's branch is merged and PRs/commits indicate completion or inactivity (configurable age threshold).
- For each bead use the status skill to evaluate their suitability for closure.
- Present candidate bead closures and ask for confirmation. If confirmed and not `dry-run`: `bd close <id> --reason "Completed" --json` then `bd sync`.
  - If there are no candidates, report none found.

8) Final report
- Produce concise report including:
  - Branches deleted (local + remote)
  - Branches kept and reasons
  - Beads closed
  - Any operations skipped or requiring manual intervention
- Offer to save report: `history/cleanup-report-<timestamp>.md` (write only with confirmation).

Branch ↔ Bead mapping
- Parse branch names for bead tokens using the project's convention: `<prefix>-<id>/...` (example: `bd-123/feature`).
- If found: `bd show <id> --json` to include title, status, priority, and comments.
- If not found: flag branch for manual review and present guidance for associating to a bead.

Commands (examples)
- Detect default: `git remote show origin` or `git symbolic-ref refs/remotes/origin/HEAD`.
- Conservative merge check: `git merge-base --is-ancestor <branch> origin/<default>`.
- List branches for manual checking: `git for-each-ref --format='%(refname:short) %(committerdate:iso8601)' refs/heads/`.
- PR summary: `gh pr list --state open --base <default> --json number,title,headRefName,url,author`.
- Beads: `bd list --status in_progress --json`, `bd show <id> --json`, `bd close <id> --reason "Completed" --json`, `bd sync`.

Safety prompts (always asked)
- Confirm local branch deletions with full list and dry-run preview.
- Confirm remote deletions per-branch or as a single group (if `confirm_all`).
- Confirm bead closures and show bead details (description, last comments, linked branches).
- If default branch cannot be fast-forwarded, ask how to proceed (pause or abort).

Suggested bundled resources (optional)
- `scripts/list-merged-branches.sh` — helper to produce a conservative list of merged branches using `git merge-base` (recommended to include in the skill if operations will be repeated).
- `references/branch-naming.md` — guide describing repo-specific branch naming and bead conventions.

Outputs
- Human-readable summary printed to terminal.
- Optional `history/cleanup-report-<timestamp>.md` written on confirmation.

Example short dialogue
- Agent: "I can inspect merged branches and propose deletions in dry-run mode. Shall I proceed? (yes/no)"
- User: "Yes — run dry-run and show candidates, do not delete remotes."
- Agent: "Dry-run complete. Candidate local deletions: A, B. Remote candidates: C. Would you like to delete local A, B? (yes/no)"

Notes for operators
- Skill assumes `bd` and `gh` may be available; proceed gracefully if not.
- Follow AGENTS.md bead/branch naming conventions. If conventions differ, flag branches for manual mapping.
- Do not create or modify commits, force-push, or change remote configuration without explicit permission.

End.