# Safe Project Organizer

> Comprehensive project cleanup and organization skill combining safe reorganization, root directory cleanup, and legacy tech removal. Features multi-stage validation, dry-run previews, and explicit user confirmation.

- Skill: `majiayu000/safe-project-organizer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/safe-project-organizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/safe-project-organizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/safe-project-organizer

---


# 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:

```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 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:**
```bash
git status                    # See what changed
git checkout -- .            # Restore all changes
git reset --hard HEAD        # Full reset to last commit
```

**Operation Log Review:**
```bash
cat .project_organizer.log    # Review detailed operation log
```

## Customization

### Adding Custom Protected Patterns
Edit the `PROTECTED_PATTERNS` list in the script:
```python
PROTECTED_PATTERNS = [
    # Existing patterns...
    'my_important_dir/**',    # Custom protection
    '*.critical',             # Protect critical files
]
```

### Custom Organization Rules
Edit `MOVABLE_ROOT_FILES` dictionary:
```python
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:
```python
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
```javascript
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
```bash
# 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`
```yaml
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.**