Project Cleanup

---
name: cleanup
version: 1.0.0
description: "Audit and clean up any project workspace — temp files, security issues, dead code, unused deps, git hygiene, build caches, and code quality. This skill should be used when the user wants to clean up, tidy, audit, or organize the project. Also use when the user mentions 'cleanup,' 'clean up,' 'tidy up,' 'housekeeping,' 'remove temp files,' 'dead code,' 'unused deps,' 'unused dependencies,' 'git hygiene,' 'project audit,' 'repo cleanup,' 'clear cache,' or 'stale branches.'"
---

# Project Cleanup

Audit and clean the project workspace across 7 categories. Every action follows the same safety protocol: scan first, preview changes, confirm with user, then execute.

## Before Starting

Read these files for context:
- `CLAUDE.md` — Project structure, tech stack, protected patterns
- `.gitignore` — Existing ignore rules
- `references/protected-paths.md` — Common paths that must never be modified or deleted

If the project has a local `.claude/skills/cleanup/references/known-temp-patterns.md`, read that too for project-specific temp file patterns.

---

## Safety Protocol

These rules are non-negotiable and override any user request:

| Rule | Detail |
|------|--------|
| **Dry-run first** | Every category starts with a read-only scan. Show results before any action. |
| **User confirms** | Present a numbered list of proposed actions. Execute ONLY items the user approves. |
| **Protected paths** | NEVER touch files in `references/protected-paths.md`. Tag with `[PROTECTED]` if they appear in scan results. |
| **Baseline before destructive ops** | Before deleting untracked files or removing dead code, offer to create a stash or branch so changes are recoverable. |
| **No silent deletions** | Every file removal must appear in the preview table with its size and reason. |
| **Git safety** | Never force-push. Never delete the current branch. Never delete `main` or `master`. |

---

## Invocation

`/cleanup [category]` or `/cleanup all`

If no category specified, present this menu using AskUserQuestion (multiSelect: true):

| # | Category | What It Does |
|---|----------|-------------|
| 1 | `security` | Find exposed secrets, missing gitignore rules |
| 2 | `temp` | Remove temp files, screenshots, extraction artifacts |
| 3 | `git` | Untracked files, stale branches, uncommitted work |
| 4 | `deps` | Unused or outdated dependencies |
| 5 | `dead-code` | Unused files, exports, types |
| 6 | `build` | Clear build caches |
| 7 | `quality` | Lint issues, TODOs, console.logs |

Run categories in this order (rationale in parentheses):
1. security (highest priority)
2. temp (quick wins, free space)
3. git (committing untracked files affects what appears unused)
4. deps (after git, so committed files are visible)
5. dead-code (after deps, for accurate analysis)
6. build (clear stale caches)
7. quality (last — lint against clean state)

---

## Category: security

Find exposed secrets, credential files outside protected directories, and missing gitignore rules.

### Scan

```bash
# Check common auth/secret directories are gitignored
for dir in .auth .secrets .credentials; do
  [ -d "$dir" ] && git check-ignore -v "$dir" 2>&1
done

# Find credential-like files in project (max depth 3)
find . -maxdepth 3 \( -name "client_secret*" -o -name "credentials.json" -o -name "token.json" -o -name "*.pem" -o -name "*.key" -o -name "service-account*.json" -o -name ".env" \) -not -path "./node_modules/*" 2>/dev/null

# For each found file, check if gitignored
# git check-ignore -v <file>

# Scan for hardcoded secrets in source code (adapt paths to project)
grep -rn "sk-[a-zA-Z0-9]\{20,\}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" --include="*.py" . 2>/dev/null | grep -v node_modules
grep -rn "Bearer [a-zA-Z0-9]\{20,\}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" . 2>/dev/null | grep -v node_modules
```

### Preview Format

```
## Security Audit

| # | Issue | File | Severity | Action |
|---|-------|------|----------|--------|
| 1 | .auth/ not in .gitignore | .gitignore | HIGH | Append to .gitignore |
| 2 | Credential file in root | client_secret_*.json | MEDIUM | Move to secure dir |
```

### Execute

For gitignore additions — append to `.gitignore` (never replace).
For file relocations — `mv` to a gitignored directory.
NEVER delete credential files — only relocate or gitignore them.

---

## Category: temp

Detect and remove temporary files that accumulated from one-off tasks.

### Scan

Adapt scans to the project. Common patterns:

```bash
# Screenshot artifacts in project root
ls -la *.png *.jpg *.jpeg *.gif 2>/dev/null

# Debug/extraction JSON files in root (exclude config files)
ls -la *.json 2>/dev/null | grep -v -E 'package|tsconfig|eslintrc|\.mcp|composer'

# Temp directories
du -sh .auth/*/ tmp/ temp/ .tmp/ 2>/dev/null

# Log files
ls -la *.log 2>/dev/null

# Core dumps, heap snapshots
ls -la core.* *.heapsnapshot 2>/dev/null
```

Also check for project-specific patterns:
- Build tool temp dirs (`.turbo/`, `.parcel-cache/`, `.vite/`)
- Browser automation caches (`.auth/*/`, `playwright-data/`)
- One-off script outputs in root

### Preview Format

```
## Temp Files Audit

| # | File/Dir | Size | Origin | Action |
|---|----------|------|--------|--------|
| 1 | screenshot.png | 136K | Debug output | Delete |
| 2 | .auth/browser-cache/ | 81M | Playwright cache | Delete |

**Total reclaimable: ~XX MB**
```

### Execute

Only delete user-approved items via `rm -f` (files) or `rm -rf` (directories).

---

## Category: git

Review untracked files, stale branches, and uncommitted work.

### Scan

```bash
# Untracked files
git status --short | grep "^??"

# Modified but unstaged
git status --short | grep "^ M\|^M "

# All branches (local + remote)
git branch -a

# Large untracked items
git status --short | grep "^??" | awk '{print $2}' | xargs -I{} du -sh {} 2>/dev/null

# Check for merge conflict markers
grep -rn "<<<<<<< " --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules
```

### Preview Format

Split untracked files into two groups:

```
## Git Hygiene Audit

### Untracked — Likely to Commit
| # | Path | Type | Size | Suggestion |
|---|------|------|------|------------|
| 1 | src/new-feature/ | Feature | 8K | Commit |

### Untracked — Likely Temp/Artifacts
| # | Path | Type | Size | Suggestion |
|---|------|------|------|------------|
| 1 | debug-*.png | Screenshot | 900K | Delete (or run `temp` category) |

### Modified but Unstaged
| # | File | Status |
|---|------|--------|
| 1 | README.md | Modified |

### Branches
| # | Branch | Suggestion |
|---|--------|------------|
| 1 | remotes/origin/old-feature | Check if merged → delete |
```

### Execute

For committing — `git add <paths>` then `git commit -m "chore: ..."`.
For branch cleanup — `git branch -d <branch>` (safe delete, only if merged), `git remote prune origin`.

---

## Category: deps

Find unused, outdated, or duplicate dependencies.

### Scan

Detect package manager and run appropriate tool:

```bash
# Preferred: knip (comprehensive — works with npm, yarn, pnpm)
npx knip --dependencies 2>/dev/null

# Fallback: depcheck (npm/yarn projects)
npx depcheck 2>/dev/null

# Outdated packages
npm outdated 2>/dev/null || yarn outdated 2>/dev/null || pnpm outdated 2>/dev/null
```

### Preview Format

```
## Dependency Audit

### Unused Dependencies
| # | Package | Type | Confidence | Action |
|---|---------|------|------------|--------|
| 1 | some-package | production | High | Uninstall |

### Outdated (major versions behind)
| # | Package | Current | Latest | Breaking? |
|---|---------|---------|--------|-----------|
| 1 | some-lib | 2.0.0 | 4.0.0 | Yes — review changelog |
```

### Execute

Uninstall unused packages with the project's package manager.
For outdated — only suggest, do not auto-update without explicit per-package approval.

---

## Category: dead-code

Find unused files, exports, types, and components.

### Scan

```bash
# Preferred: knip (comprehensive — unused files, exports, types)
npx knip 2>/dev/null

# Fallback: manual checks for TypeScript projects
# Unused exports
grep -rn "export type\|export interface\|export function\|export const" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules

# Orphaned components (imported in 0-1 files) — adapt glob to project
# for f in components/**/*.tsx; do ...
```

### Preview Format

```
## Dead Code Audit

### Unused Exports
| # | Export | File | Confidence |
|---|--------|------|------------|
| 1 | SomeType | types/index.ts | High |

### Unused Files
| # | File | Last Modified | Confidence |
|---|------|---------------|------------|
| 1 | src/old-util.ts | 30 days ago | Medium |
```

### Execute

Before removing dead code, ALWAYS offer:
```
Create safety stash before removing dead code? (recommended) [y/n]
```

If yes: `git stash push -m "cleanup: pre-dead-code-removal backup"`

Then remove approved items only.

---

## Category: build

Clear build caches and generated output directories.

### Scan

Detect framework and check common cache locations:

```bash
# Common build caches
du -sh .next/ dist/ build/ output/ .turbo/ .parcel-cache/ .vite/ node_modules/.cache/ __pycache__/ .pytest_cache/ target/ 2>/dev/null
```

### Preview Format

```
## Build Cache Audit

| # | Directory | Size | Gitignored | Action |
|---|-----------|------|------------|--------|
| 1 | .next/ | 331M | Yes | Delete (rebuilds on dev) |
| 2 | node_modules/.cache/ | 50M | Yes | Delete (rebuilt automatically) |

**Total reclaimable: ~XXX MB**
```

### Execute

Delete approved directories. After clearing, remind user how to rebuild (e.g., `npm run dev`, `npm run build`).

---

## Category: quality

Lint issues, TODO/FIXME comments, console.log statements, and type errors.

### Scan

Detect available linting tools and run:

```bash
# Lint (detect tool)
npm run lint 2>&1 || npx eslint . 2>&1 || echo "No linter configured"

# TODO/FIXME comments in source (exclude node_modules, .git, build dirs)
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | grep -v node_modules | grep -v ".next/"

# console.log in production code
grep -rn "console\.\(log\|debug\|warn\)" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . 2>/dev/null | grep -v node_modules | grep -v ".next/"

# TypeScript errors (if tsconfig exists)
[ -f tsconfig.json ] && npx tsc --noEmit 2>&1 | head -50
```

### Preview Format

```
## Code Quality Audit

### ESLint Issues
| # | File | Line | Rule | Message |
|---|------|------|------|---------|
| 1 | src/app.tsx | 12 | no-unused-vars | 'x' defined but never used |

### TODO/FIXME Comments
| # | File | Line | Comment |
|---|------|------|---------|
| 1 | src/api/route.ts | 45 | TODO: refactor |

### Console Statements
| # | File | Line | Statement |
|---|------|------|-----------|
| 1 | src/api/route.ts | 23 | console.log(...) |

### TypeScript Errors
[from tsc --noEmit output]
```

### Execute

For ESLint auto-fixable: `npx eslint --fix <file>`.
For console.log removal and TODO resolution — handle manually per item after user approval.

---

## Final Summary

After all selected categories complete, present:

```
## Cleanup Summary

| Category | Found | Fixed | Skipped | Space Freed |
|----------|-------|-------|---------|-------------|
| security | 2 | 2 | 0 | — |
| temp | 5 | 4 | 1 | 84 MB |
| git | 10 | 8 | 2 | — |
| deps | 1 | 1 | 0 | — |
| dead-code | 0 | 0 | 0 | — |
| build | 2 | 2 | 0 | 400 MB |
| quality | 4 | 3 | 1 | — |

**Total space freed: XXX MB**
**Security issues resolved: X**

### Remaining Items (manual follow-up)
1. [ ] Item requiring manual attention
2. [ ] ...
```