---
name: project-tidy
description: Audit and tidy a creative project folder before handoff or archive. Reports duplicate files (by hash), zero-byte files, orphaned/unreferenced assets, weird filenames (spaces, emoji, mixed case), empty folders, and oversized files. Outputs a markdown report. With --apply, moves cruft to a `_attic/` folder (never deletes). TRIGGER when the user wants to clean up a project directory, prepare a folder for zipping, hand off work to a collaborator, archive an old session, or asks "what's in this folder I don't need". Designed to run BEFORE generative skills like clip-stitch, sample-pack, or mood-board so they get a clean input.
---


# project-tidy

Walk a creative project folder and surface everything that's cruft, duplicated, oddly named, or oversized. Report-only by default; with `--apply` it relocates the cruft to a `_attic/` folder inside the project (never deletes — destructive operations are out of scope).

## When to use

- Before zipping a project to send to a collaborator
- Before archiving a finished session
- After a long messy work day, before pushing to git or backup
- Before running generative skills that walk the same folder (so they don't pick up junk)

## What it checks

| Check | What it flags |
| --- | --- |
| **Duplicates** | Files with identical SHA-256, kept by mtime (oldest survives) |
| **Zero-byte files** | Empty files left behind by failed exports |
| **Oversized files** | Files larger than `--max-size` (default 500MB) — likely raw renders worth archiving |
| **Weird names** | Spaces, emoji, leading dots, mixed case in same dir, double extensions |
| **Empty folders** | Directories containing no files (recursively) |
| **Orphans** | Files not referenced by any project file (`.fcpxml`, `.aep`, `.als`, `.logic`, `.prproj`, `.json`, `.md`) |

## Usage

```bash
# Report only (safe — read-only)
python tidy.py /path/to/project

# Report + write markdown to a file
python tidy.py /path/to/project --report tidy-report.md

# Actually move flagged cruft to _attic/ (still reversible — nothing deleted)
python tidy.py /path/to/project --apply

# Tune what counts as oversized
python tidy.py /path/to/project --max-size 1G
```

## Safety

- `--apply` only **moves** files into `<project>/_attic/<timestamp>/` preserving relative paths. You can restore everything by moving them back.
- The skill never deletes anything, ever.
- Hidden files and `.git/` are skipped by default.
- You can dry-run with `--apply --dry-run` to preview what would move.

## Output

Markdown report with sections per check, file paths relative to the project root, and a one-line summary at the top:

```
project-tidy report — /Users/me/projects/song-2026-04
  47 duplicates (310MB recoverable) · 3 zero-byte · 12 weird names · 2 empty dirs · 8 orphans
```

## Pairs well with

- `clip-stitch`, `sample-pack`, `mood-board` — run `project-tidy` first so they don't ingest junk
- `vid-rip` output folders — usually full of partial downloads worth attic-ing