feat: add project-hygiene plugin

Post-task cleanup hook that runs after Claude completes work:
- Deletes temp files (*.tmp, *.bak, __pycache__, etc.)
- Warns about unexpected files in project root
- Identifies orphaned files (test_*, debug_*, *_backup.*)
- Logs actions to .dev/logs/
- Supports project-local config via .hygiene.json

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

project-hygiene/README.md

@@ -0,0 +1,135 @@
+# project-hygiene
+
+Post-task cleanup hook plugin for Claude Code. Automatically cleans up temporary files, warns about unexpected files in the project root, and manages orphaned supporting files after task completion.
+
+## Features
+
+- **Delete temp files**: Removes `*.tmp`, `*.bak`, `__pycache__`, `.pytest_cache`, and other common temporary patterns
+- **Root file warnings**: Alerts when unexpected files appear in project root
+- **Orphan detection**: Identifies `test_*`, `debug_*`, `*_backup.*` and similar files that may have been left behind
+- **Cleanup logging**: Records all actions to `.dev/logs/`
+- **Configurable**: Project-local `.hygiene.json` for custom rules
+
+## Installation
+
+Add to your Claude Code configuration or install from the marketplace:
+
+```bash
+claude plugin install project-hygiene
+```
+
+## How It Works
+
+The plugin registers a `task-completed` hook that runs after Claude completes any task. It:
+
+1. Scans for and deletes known temporary file patterns
+2. Removes temporary directories (`__pycache__`, `.pytest_cache`, etc.)
+3. Checks for unexpected files in project root and warns
+4. Identifies orphaned supporting files (test files, debug scripts, backups)
+5. Optionally moves orphans to `.dev/scratch/` for review
+6. Logs all actions to `.dev/logs/hygiene-TIMESTAMP.log`
+
+## Configuration
+
+Create `.hygiene.json` in your project root to customize behavior:
+
+```json
+{
+  "move_orphans": true,
+  "allowed_root_files": [
+    "custom-config.yaml",
+    "my-script.sh"
+  ],
+  "temp_patterns": [
+    "*.cache",
+    "*.pid"
+  ],
+  "ignore_patterns": [
+    "important_test_*.py",
+    "keep_this_backup.*"
+  ]
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `move_orphans` | boolean | `false` | Move orphaned files to `.dev/scratch/` instead of just warning |
+| `allowed_root_files` | array | (see below) | Additional files allowed in project root |
+| `temp_patterns` | array | `[]` | Additional temp file patterns to delete |
+| `ignore_patterns` | array | `[]` | Files to never touch during cleanup |
+
+### Default Allowed Root Files
+
+The plugin recognizes common project files in root:
+- Git files: `.git`, `.gitignore`, `.gitattributes`
+- Config: `.editorconfig`, `.env*`, `.nvmrc`, etc.
+- Documentation: `README.md`, `LICENSE`, `CHANGELOG.md`, `CLAUDE.md`
+- Package managers: `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, etc.
+- Build configs: `Makefile`, `Dockerfile`, `docker-compose.yml`, `tsconfig.json`, etc.
+
+### Default Temp Patterns
+
+Automatically cleaned:
+- `*.tmp`, `*.bak`, `*.swp`, `*.swo`, `*~`
+- `.DS_Store`, `Thumbs.db`
+- `*.log`, `*.orig`, `*.pyc`, `*.pyo`
+
+### Default Temp Directories
+
+Automatically removed:
+- `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`
+- `node_modules/.cache`, `.next/cache`, `.nuxt/.cache`, `.turbo`
+- `*.egg-info`, `.eggs`
+
+### Orphan Patterns
+
+Files flagged as orphans:
+- `test_*.py` (standalone test files)
+- `debug_*` (debug scripts)
+- `*_backup.*`, `*_old.*`, `*_bak.*`, `*.backup`
+- `temp_*`, `tmp_*`
+
+## Output
+
+After each task, you'll see output like:
+
+```
+[14:32:15] Starting project hygiene cleanup...
+
+[14:32:15] Cleaning temp files...
+[14:32:15]   DELETED: ./src/__pycache__/utils.cpython-311.pyc
+[14:32:15]   DELETED: ./temp.bak
+
+[14:32:15] Cleaning temp directories...
+[14:32:15]   DELETED DIR: ./src/__pycache__
+
+[14:32:15] Checking root files...
+[14:32:15]   WARNING: Unexpected root file: random_notes.txt
+
+[14:32:15] Checking for orphaned files...
+[14:32:15]   ORPHAN: ./test_scratch.py
+[14:32:15]   ORPHAN: ./debug_api.py
+
+=== Cleanup Summary ===
+  Deleted: 3 items
+  Warnings: 1 unexpected root files
+  Orphans: 2 files
+  Log file: .dev/logs/hygiene-20250110-143215.log
+```
+
+## Directory Structure
+
+```
+.dev/
+├── logs/
+│   └── hygiene-YYYYMMDD-HHMMSS.log
+└── scratch/        # (if move_orphans enabled)
+    └── debug_api.py
+```
+
+## Requirements
+
+- Bash 4.0+
+- Optional: `jq` for JSON config parsing (falls back to defaults if not installed)