Safe Project Organizer

Overview

This comprehensive skill combines three cleanup capabilities into one unified tool:

1. Safe Project Organization - Analyze and reorganize project structure with multi-stage validation
2. Root Directory Cleanup - Remove temporary files, build artifacts, and development clutter from the project root
3. Legacy Tech Removal - Audit and remove abandoned libraries, deprecated code, and dead directories

All operations prioritize 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:

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:

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:

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:

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:

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 mode
• Dry run completed successfully
• No critical files are being moved
• Build/test processes still work
• Team members notified if shared project

Error Handling and Troubleshooting

Common Issues

Permission Denied:

• Ensure you have write permissions
• Check file ownership
• May need appropriate privileges

Path Protected:

• Review protected patterns
• Confirm the path should be modified
• Adjust patterns if needed

Changes Not Appearing:

• Verify you used --execute-real (not just --execute)
• Check the operation log
• Confirm "yes" was entered at confirmation prompt

Recovery Options

Git Recovery:

git status                    # See what changed
git checkout -- .            # Restore all changes
git reset --hard HEAD        # Full reset to last commit

Operation Log Review:

cat .project_organizer.log    # Review detailed operation log

Customization

Adding Custom Protected Patterns

Edit the PROTECTED_PATTERNS list in the script:

PROTECTED_PATTERNS = [
    # Existing patterns...
    'my_important_dir/**',    # Custom protection
    '*.critical',             # Protect critical files
]

Custom Organization Rules

Edit MOVABLE_ROOT_FILES dictionary:

MOVABLE_ROOT_FILES = {
    'assets': ['*.png', '*.jpg', '*.svg'],  # Move images to assets/
    'data': ['*.csv', '*.json', '*.xml'],   # Move data files
}

Custom Safety Validators

Extend the SafeProjectOrganizer class:

def _custom_safety_check(self, path: Path) -> bool:
    """Your custom safety logic"""
    # Return True if safe, False if should be protected
    return True

Integration with Claude Code

As a Skill Tool

This skill integrates naturally with Claude Code's workflow:

1. User Request: "Organize my project structure"
2. Skill Activation: Safe Project Organizer loads
3. Sequential Execution: Follows the 5-step workflow automatically
4. User Confirmation: Confirms each step before proceeding
5. Safety Validation: All operations include safety checks

Example User Interactions

Simple Cleanup:

User: "My project root is messy, can you help organize it?"
Claude: [Uses skill to scan and suggest safe improvements]

Targeted Organization:

User: "I have too many documentation files scattered around"
Claude: [Uses skill to identify and suggest grouping docs/ folder]

Pre-Migration Cleanup:

User: "I need to clean up before handing this project to another team"
Claude: [Uses skill for comprehensive safe reorganization]

Root Directory Cleanup (Merged from root-project-cleaner)

A specialized capability for safely removing temporary files, build artifacts, and unwanted clutter FROM THE PROJECT ROOT DIRECTORY.

Scope

• Cleans: node_modules/.cache, dist, .vite, *.tmp, *.log in root
• Does NOT: Refactor code, organize source files, clean src/ directory

Root Cleanup Categories

1. Build Artifacts

• dist/, build/, .vite/
• Compiled assets and bundles

2. Development Caches

• node_modules/.cache/
• .cache/, tmp/, temp/

3. Temporary Files

• *.tmp, *.temp, *.swp, *.swo
• Editor backup files

4. System Files

• .DS_Store, Thumbs.db
• OS-specific metadata

5. Logs and Debug

• *.log, logs/, debug/

Root Cleanup Configuration

const config = {
  rules: {
    maxAge: 30,           // days
    maxSize: '100MB',
    patterns: {
      include: [
        '*.tmp', '*.temp', '*.swp', '*.swo',
        '*.log', 'logs/', '.cache/',
        'dist/', 'build/', '.vite/',
        'node_modules/.cache/', '.DS_Store',
        'Thumbs.db', '*.bak', '*.backup'
      ],
      exclude: [
        '*.config.*', '*.env.*', '.gitignore',
        'package.json', 'package-lock.json',
        '*.md', 'README.*', '.gitkeep'
      ]
    }
  },
  safety: {
    gitAware: true,
    createBackup: true,
    interactiveMode: true
  }
};

Legacy Tech Removal (Merged from legacy-tech-remover)

Automated audit and cleanup for abandoned/dead libraries, legacy tech stacks, and deprecated development directions.

4-Phase Legacy Removal Process

Phase 1: Legacy Detection & Inventory

• Dependency Analysis: Scan package managers for unused/abandoned libraries
• Directory Analysis: Identify orphaned source trees and dead folders
• Pattern Detection: Find deprecated architectural patterns
• Git History: Analyze last touched dates

Output Files:

• legacy-inventory.csv: Complete inventory with risk scores
• legacy-directories.tree: Hierarchical view of removal candidates
• legacy-dependencies.json: Dependency graph analysis

Phase 2: Impact Assessment & Risk Analysis

Risk Categories:

• SAFE: Zero usage, safe for immediate removal
• CAUTION: Low/uncertain usage, manual review recommended
• RISKY: Possible indirect use, migration required

Phase 3: Execution Automation

Execution Modes:

• DRY RUN: Preview mode with detailed reports, no changes
• BATCH EXECUTION: Automated removal of safe items
• MANUAL REVIEW: Interactive review of risky items
• VALIDATION: Post-execution verification

Phase 4: Documentation & Communication

• Migration Log: Complete record of all changes
• Architecture Updates: Update system documentation
• Team Notifications: Automated announcements

Legacy Tech Patterns Detected

• Deprecated Libraries: Libraries unmaintained >18 months
• Dead Frameworks: AngularJS, jQuery, Grunt, Gulp, TravisCI
• Abandoned Patterns: Legacy MVC, Flux, old build systems
• Orphaned Directories: old/, legacy/, v1/, bak/

Legacy Removal Usage

# Full legacy audit and removal plan
python3 scripts/run_legacy_removal.py --full-audit

# Only phase 1: Detection and inventory
python3 scripts/phase1_detection.py --output-dir ./reports

# Dry run of removal plan
python3 scripts/phase3_execution.py --dry-run --plan ./reports/removal_plan.json

# Execute safe removals only
python3 scripts/phase3_execution.py --safe-only --auto-commit

Configuration File: .claude/legacy-remover-config.yml

min_years_untouched: 2
safe_folder_patterns:
  - "^src/legacy/"
  - "^old/"
  - "^bak/"
  - "^deprecated/"

protected_packages:
  - "core-js"
  - "typescript"
  - "react"
  - "vue"

risk_thresholds:
  safe_removal: 0.2
  caution_zone: 0.6
  risky_removal: 0.8

git:
  auto_commit: true
  commit_prefix: "[legacy-removal]"
  create_backup_branch: true

Resources

scripts/

• project_organizer.py - The main safe project organizer script with comprehensive safety features
• run_legacy_removal.py - Full legacy audit orchestrator
• phase1_detection.py - Legacy detection and inventory
• phase2_assessment.py - Impact assessment and risk analysis
• phase3_execution.py - Execution automation
• phase4_documentation.py - Documentation generation

references/

• deprecated-patterns.md - Known deprecated technology patterns
• migration-strategies.md - Modern replacement recommendations

assets/

• config_schemas/legacy-remover-config-schema.json - Configuration validation schema

The script includes:

• Multi-phase analysis and execution
• Protected pattern detection
• Risk level classification
• Comprehensive safety checks
• Audit trail generation
• Rollback information preservation

This script can be executed independently of Claude Code for manual project organization tasks.

Safety Guarantee: This skill never modifies files without explicit confirmation, always previews changes, and includes comprehensive safety checks to protect important project data.

MANDATORY USER VERIFICATION REQUIREMENT

Policy: No Fix Claims Without User Confirmation

CRITICAL: Before claiming ANY issue, bug, or problem is "fixed", "resolved", "working", or "complete", the following verification protocol is MANDATORY:

Step 1: Technical Verification

• Run all relevant tests (build, type-check, unit tests)
• Verify no console errors
• Take screenshots/evidence of the fix

Step 2: User Verification Request

REQUIRED: Use the AskUserQuestion tool to explicitly ask the user to verify the fix:

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

Step 3: Wait for User Confirmation

• DO NOT proceed with claims of success until user responds
• DO NOT mark tasks as "completed" without user confirmation
• DO NOT use phrases like "fixed", "resolved", "working" without user verification

Step 4: Handle User Feedback

• If user confirms: Document the fix and mark as complete
• If user reports issues: Continue debugging, repeat verification cycle

Prohibited Actions (Without User Verification)

• Claiming a bug is "fixed"
• Stating functionality is "working"
• Marking issues as "resolved"
• Declaring features as "complete"
• Any success claims about fixes

Required Evidence Before User Verification Request

1. Technical tests passing
2. Visual confirmation via Playwright/screenshots
3. Specific test scenarios executed
4. Clear description of what was changed

Remember: The user is the final authority on whether something is fixed. No exceptions.