safe-project-organizer

What this skill does

# Safe Project Organizer

## Overview

This skill enables Claude Code to analyze project structure and suggest safe organizational improvements like moving files, removing unused directories, and restructuring folders. It prioritizes safety through multi-stage validation, dry-run previews, and explicit user confirmation.

## Core Safety Principles

### 1. Read-Only Analysis Phase
- All analysis operations are read-only
- No modifications occur during scanning
- Complete project snapshot before any changes

### 2. Dry-Run Validation
- All operations preview changes before execution
- Show exact file paths being affected
- Calculate impact metrics (files moved, deleted, created)

### 3. Explicit User Confirmation
- Require confirmation for each operation category
- Display detailed change summary
- Allow selective approval of suggestions

### 4. Atomic Operations with Rollback
- Each operation is reversible
- Create backup references before modifications
- Maintain operation log for audit trail

### 5. Protected File Patterns
Never modify files matching these patterns:
- `.git/`, `.svn/`, `.hg/` (version control)
- `node_modules/`, `vendor/`, `venv/`, `.venv/` (dependencies)
- `.env*`, `secrets.*`, `credentials.*` (sensitive data)
- `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` (lock files)
- `dist/`, `build/`, `.next/`, `.nuxt/` (build artifacts)

## When to Use This Skill

Use this skill when you encounter any of these scenarios:

**Project Cleanup:**
- "My project root is messy with too many files"
- "I have empty directories that should be cleaned up"
- "Documentation files are scattered everywhere"

**Standardization:**
- "This project doesn't follow standard directory structure"
- "Source files are mixed with config files in root"
- "I need to organize files by type for better maintainability"

**Migration Preparation:**
- "I'm about to hand off this project and need to clean it up"
- "This codebase needs better organization before adding new features"
- "I want to standardize the project structure"

**Safety Concerns:**
- "I'm nervous about accidentally breaking something"
- "I need to see exactly what will change before making changes"
- "I want a safe way to reorganize without losing data"

## Safe Usage Workflow

### Step 1: Initial Scan (Read-Only)
Execute the project organizer script with `--scan` flag:

```bash
python3 scripts/project_organizer.py /path/to/project --scan
```

**What it does:**
- Scans entire project structure
- Identifies file types, counts, sizes
- Detects empty directories
- Lists protected files
- **No modifications made**

**Example Output:**
```
🔍 Scanning project: /path/to/project
📋 This is a READ-ONLY scan. No changes will be made.

✅ Scan complete!
   📁 Directories: 24
   📄 Files: 156
   🔒 Protected items: 42
   📂 Empty directories: 3
```

### Step 2: Generate Suggestions (Still Read-Only)
Use `--analyze` flag to generate organizational suggestions:

```bash
python3 scripts/project_organizer.py /path/to/project --analyze
```

**What it does:**
- Performs full analysis
- Generates organizational suggestions
- Displays suggestion count
- **Still no modifications**

### Step 3: Preview Changes (Detailed Review)
Use `--preview` flag to see exactly what will change:

```bash
python3 scripts/project_organizer.py /path/to/project --preview
```

**What it does:**
- Shows detailed preview of ALL suggestions
- Groups by action type (move, delete, create)
- Displays risk levels (🟢 low, 🟡 medium, 🔴 high)
- Shows safety checks for each operation
- Lists exact file paths affected
- **Zero modifications**

**Example Preview Output:**
```
📋 PREVIEW MODE - No changes will be made
============================================================

📊 Total Suggestions: 8

🎯 By Action:
   MOVE: 5
   DELETE: 2
   CREATE_DIR: 1

⚠️  By Risk Level:
   🟢 LOW: 6
   🟡 MEDIUM: 2

📝 Detailed Suggestions:

MOVE Operations (5):
1. 🟢 Documentation/config files organized in docs/ directory
   FROM: CONTRIBUTING.md
   TO:   docs/CONTRIBUTING.md
   Safety Checks:
      ✓ File is not a primary config
      ✓ No imports reference this file path
      ✓ Not in protected patterns

DELETE Operations (2):
1. 🟢 Empty directory with no files or subdirectories
   PATH: old_backup/temp
   Safety Checks:
      ✓ Directory is empty
      ✓ Not a protected path
      ✓ No version control markers
```

### Step 4: Dry Run (Simulation Only)
Use `--execute` flag for dry-run simulation:

```bash
python3 scripts/project_organizer.py /path/to/project --execute
```

**What it does:**
- Simulates ALL operations
- Shows what WOULD happen
- Validates all safety checks
- Reports success/failure/skipped
- **No actual changes made**

### Step 5: Real Execution (Requires Confirmation)
Use `--execute-real` flag only after thorough review:

```bash
python3 scripts/project_organizer.py /path/to/project --execute-real
```

**What it does:**
- Prompts for explicit confirmation
- Executes approved changes
- Creates audit log (`.project_organizer.log`)
- Shows real-time progress
- **Actually modifies project**

**Confirmation Prompt:**
```
⚠️  WARNING: This will make REAL changes. Type 'yes' to confirm: yes
```

## Operation Types and Safety

### Move Operations
**Low Risk (🟢):**
- Moving documentation files to `docs/`
- Moving config files to `config/`
- Moving scripts to `scripts/`

**Medium Risk (🟡):**
- Grouping source files by type
- Creating organizational directories

**Safety Checks Performed:**
- Source file exists and is accessible
- Source is not in protected patterns
- Destination doesn't already exist
- Parent directories can be created safely

### Delete Operations
**Low Risk (🟢):**
- Removing truly empty directories
- Deleting temporary files

**Safety Checks Performed:**
- Target exists
- Directory is completely empty
- Not a protected path
- No version control markers

### Create Directory Operations
**Low Risk (🟢):**
- Creating standard directories (`src/`, `docs/`, `tests/`)
- Creating organizational structure

**Safety Checks Performed:**
- Target doesn't already exist
- No naming conflicts
- Standard directory pattern
- Parent directories can be created

## Protected File Patterns

The skill automatically protects these paths from modification:

### Version Control
- `.git/`, `.git/**`
- `.svn/`, `.svn/**`
- `.hg/`, `.hg/**`

### Dependencies
- `node_modules/`, `node_modules/**`
- `vendor/`, `vendor/**`
- `venv/`, `venv/**`
- `.venv/`, `.venv/**`

### Build Artifacts
- `dist/`, `dist/**`
- `build/`, `build/**`
- `.next/`, `.next/**`
- `.nuxt/`, `.nuxt/**`
- `out/`, `out/**`

### Sensitive Data
- `.env*`
- `secrets.*`
- `credentials.*`

### Lock Files
- `package-lock.json`
- `yarn.lock`
- `pnpm-lock.yaml`
- `Gemfile.lock`
- `Pipfile.lock`
- `poetry.lock`

### Cache Files
- `__pycache__/`, `__pycache__/**`

## Best Practices

### Before Running the Skill
1. **Commit Changes**: Ensure all current work is committed to version control
2. **Backup Important Files**: Have a recent backup or git stash available
3. **Review Project**: Understand what files and directories are important
4. **Test Access**: Verify you have necessary permissions

### During Execution
1. **Always Start with Scan**: Begin with `--scan` to understand the project
2. **Review Suggestions Carefully**: Look through all generated suggestions
3. **Use Preview Mode**: Always use `--preview` before any execution
4. **Test with Dry Run**: Use `--execute` to simulate changes safely

### After Execution
1. **Verify Project Works**: Test that your project still builds/runs correctly
2. **Review Operation Log**: Check `.project_organizer.log` for what was changed
3. **Commit Separately**: Commit organizational changes separately from functional changes
4. **Update Documentation**: Update any documentation that references old file paths

### Safety Checklist
Before using `--execute-real`, verify:
- [ ] Project is committed to version control
- [ ] All suggestions reviewed in preview m