/cleanup-project

name: cleanup-project
description: "Prepare a git repo before new work: review uncommitted changes, fix .gitignore, delete merged branches, end on clean main, or inspect one branch before deciding. Don't use for dead code, commit-and-push, releases, LICENSE files, or git how-tos."
license: MIT
effort: high
metadata:
  version: 1.0.2
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Cleanup Project

Get a repository to a clean foundation before new work: every uncommitted change decided, ignore files updated, merged branches deleted locally and on `origin`, and an up-to-date, clean `main`.

When to use

• "Clean up this repo before I start the next feature."
• "Delete the branches that are already merged, local and remote."
• "My working tree is a mess. Help me decide what to keep and get back to main."
• "Tidy the .gitignore and get rid of stale branches."
• "Is `spike/llm-cache` worth keeping?" This goes straight to the single-branch drill-down (Step 6).

Don't use it to remove dead code or unused imports (`code-review` mode:cleanup), commit and push everything (`auto-push`), cut a release or tag (`ship`), or add LICENSE, CONTRIBUTING and other OSS files (`oss-ready`). For a git how-to question ("`branch -d` vs `-D`?"), answer it directly and run no workflow.

Inputs

• **Base branch.** `main` by default. If the repo has no `main`, ask once which branch is the base

(`master`, `develop`, `trunk`) and use that answer everywhere this skill says `main`.

• **Remote.** `origin` by default. If `git remote` lists no `origin`, ask once: use another remote

(by name), or run local-only. Use that answer everywhere this skill says `origin`. Local-only means no fetch, no pull, no push, and no remote delete; the report says `local-only`.

• **Scope.** Infer it from the request, then confirm it once in one line

(`Scope: sweep (Steps 1, 3, 5, 6, 7). OK?`).

| Scope | Example request | Steps | |---|---|---| | full (default) | "clean up this repo before the next feature" | 1–7 | | review | "help me decide what to keep in my working tree" | 1, 2, 3, 7 | | ignore | "fix the .gitignore" | 1, 3, 4, 7 | | sweep | "delete the merged branches" | 1, 3, 5, 6, 7 | | report-only | "which branches are merged? don't touch anything" | 1, Step 5 up to the table, Step 6 list | | drill-down | "is `spike/x` worth keeping?" | 1, then Step 6 drill-down for that branch |

Step 1 always runs. Steps 3 and 7 run in every scope except report-only and drill-down. Report-only never switches, pulls, discards, or deletes. Residue left by a phase outside the scope is reported `— skipped by user` and does not make the run PARTIAL. Per-scope details: `references/scopes-and-results.md`.

Prerequisites

Check these before Step 1. If one fails, stop and print the report as `BLOCKED — <failed check>`.

• `git rev-parse --git-dir` succeeds (inside a git repository).
• The base branch resolves: `git rev-parse --verify main` or `origin/main`, or a confirmed base.
• No operation is in progress: `git rev-parse -q --verify` fails for `MERGE_HEAD`, `REBASE_HEAD`,

`CHERRY_PICK_HEAD` and `REVERT_HEAD`, and `test -d "$(git rev-parse --git-path rebase-merge)"` fails, as does the same for `rebase-apply` (never test a literal `.git/...` path: in a linked worktree `.git` is a file). Never "clean" through a conflict.

Repo Sync Before Edits (mandatory)

This skill syncs first, but not with the usual stash → pull → pop:

git fetch origin --prune        # refresh refs; the working tree is untouched

Do **not** stash or pull before Step 2: a stash hides the state the user must review, and a pull into a dirty tree can conflict before anything is decided. The pull happens in Step 3. If the fetch fails, show the error and ask once: continue local-only, or stop (`BLOCKED — fetch failed`). With no `origin`, the Inputs answer applies instead.

Rules for every destructive step

1. **List → explicit confirm → execute.** Show the exact commands with real names. A "no", or silence, means nothing runs. 2. If the user confirms only part of a list ("yes except `feat/x`"), re-show the edited list and take a fresh yes. 3. If a command fails, stop that plan and report the error. Never retry with force or a stronger flag (`-D` for `-d`, `--force`, `--ignore-other-worktrees`). 4. **Protected branches** are never deleted, renamed, or force-pushed: `main`, `master`, `develop`, `trunk`, `release/*`, the current branch, and any branch in a `branch refs/heads/<b>` line of `git worktree list --porcelain`. If the user asks to delete one, refuse and name the rule. For a worktree branch, tell them to run `git worktree remove <path>` first.

Workflow

1. Fetch and snapshot

1. Run the sync above. 2. Record the current branch (or detached HEAD), base, `git status --porcelain=v1 -z`, and `git worktree list --porcelain`. If `main` is checked out in another worktree and Step 3 is in scope, warn now that the run will stop BLOCKED at Step 3, before any Step 2 plan is confirmed. 3. Run `gh auth status`. It decides whether the merged-PR signal is available (not a stop condition). 4. If HEAD is detached, run `git log HEAD --not --branches --remotes --oneline`. If it prints commits, report them and offer `git switch -c <name>` to keep them (in report-only and drill-down, report them only).

2. Review each uncommitted change

1. Parse `git status --porcelain=v1 -z` (NUL-separated, so paths with spaces and both paths of a rename survive). 2. If there are more than 20 entries, show a grouped summary (by directory and status) and offer one decision per group. Show full diffs on request. You may propose groups; never infer a decision from them. 3. Show each entry with its status code and diff. If the path is secret-like (`.env*`, `*.pem`, `*.key`, `*.p12`, `id_rsa*`, `credentials*`), show only its name and size, never its content or diff, and print `⚠ secret-like: <path>`. 4. Ask: `keep (comm