name: cleanup
description: >
Assess the project to reorganize or deprecate unused/outdated files.
Cleans the git workspace and commits changes.
allowed-tools: Bash, Read, Grep, Glob
triggers:
- cleanup this project
- reorganize the codebase
- remove outdated files
- deprecate unused code
- git cleanup
metadata:
short-description: Deep codebase assessment and technical debt cleanup

Cleanup Skill

This skill performs a deep assessment of the codebase to identify technical debt, unused files, and outdated documentation, then performs cleanup operations with confirmation.

Workflow

1. Assessment (--dry-run): Scan the codebase for:
2. Untracked "junk" files (logs, temp images, build artifacts).
3. Tracked files that are no longer referenced in the codebase.
4. Outdated documentation files.
5. Project structure inconsistencies.
6. Planning (--plan): Generate a Cleanup Plan markdown file for review.
7. Execution (--execute): Perform cleanup operations with user confirmation:
8. Remove junk files (with optional --force to skip prompts)
9. Remove dead tracked files (always requires confirmation, never auto-deleted)
10. Log all actions to local/CLEANUP_LOG.md

How to Use

1. Trigger with "cleanup this project" or "reorganize codebase".
2. Run bash .pi/skills/cleanup/run.sh --dry-run to see JSON findings.
3. Run bash .pi/skills/cleanup/run.sh --plan to generate a readable cleanup plan.
4. Review the plan and run bash .pi/skills/cleanup/run.sh --execute to perform cleanup.
5. Use --force to skip confirmation for junk files only (dead files still require confirmation).

Safety Features

• Dead files always require confirmation: The skill will never auto-delete tracked files that appear unreferenced. You must explicitly confirm each deletion.
• Uncommitted changes warning: The skill warns and asks for confirmation if you have uncommitted changes.
• Detailed logging: All actions are recorded in local/CLEANUP_LOG.md.
• Junk file detection: Uses patterns to identify common junk files (logs, temp files, build artifacts).

Command Options