| name | file-organization |
| description | Use when helping organize files, clean up directories, or establish file naming and structure conventions — covers 18 manifest types, intelligent file categorization, naming conventions, and organizational patterns with audit trails |
| allowed-tools | Read Glob Bash(ls *) Bash(find *) Bash(mv *) Bash(mkdir *) |
File Organization
When to Use
When organizing files into a coherent structure, cleaning up messy directories, establishing naming conventions, setting up project folder hierarchies, categorizing files by type or purpose, identifying duplicate or orphaned files, or helping someone establish a sustainable file organization system. Useful at project start (establish structure), mid-project (when things get messy), and project end (archive and clean up).
18 Project Manifest Types
These manifest files identify a project's root directory and its technology stack. Use them to auto-discover projects within a directory tree.
| Manifest File | Project Type | Ecosystem |
|---|
package.json | node | JavaScript / TypeScript / Node.js |
pyproject.toml | python | Modern Python (Poetry, Hatch, PDM) |
setup.py | python | Legacy Python (setuptools) |
Cargo.toml | rust | Rust (Cargo) |
go.mod | go | Go modules |
pom.xml | java-maven | Java (Maven) |
build.gradle | java-gradle | Java / Android (Gradle) |
build.gradle.kts | kotlin-gradle | Kotlin (Gradle KTS) |
Gemfile | ruby | Ruby (Bundler) |
composer.json | php | PHP (Composer) |
pubspec.yaml | dart-flutter | Dart / Flutter |
platformio.ini | embedded-pio | Embedded / ESP32 / Arduino |
CMakeLists.txt | cpp-cmake | C++ (CMake) |
Makefile | make | Make-based builds |
mix.exs | elixir | Elixir (Mix) |
shard.yml | crystal | Crystal |
deno.json | deno | Deno |
bun.lockb | bun | Bun runtime |
Usage: Scan a directory tree looking for these files. When found, the parent directory is a project root. Stop descending into that project's subdirectories to avoid false matches in nested dependencies.
Skip directories during scanning: node_modules, __pycache__, target, build, dist, .git, venv, .venv, env, .tox (these are build artifacts or dependency caches, never project roots).
Canonical Client Folder Structure
For client/project-based work, use this four-folder structure per client:
clients/
{client-name}/
projects/ # Source code, build files, project assets
contracts/ # Legal documents, SOWs, NDAs, agreements
deliverables/ # Final outputs, reports, presentations, exports
communications/ # Emails, meeting notes, chat logs, correspondence
This structure cleanly separates concerns and makes files findable by purpose rather than just date or type.
Intelligent File Categorization
Heuristic Classification Rules
When determining where a file belongs, apply these rules in order (first match wins):
Contracts (high confidence: 0.7)
Keywords in filename: contract, agreement, nda, sow, terms, legal, msa
File types: .docx, .doc (when combined with contract keywords)
Communications (high confidence: 0.7)
Keywords in filename: email, meeting, notes, chat, message, correspondence, minutes
Deliverables (medium confidence: 0.6)
Keywords in filename: report, presentation, deliverable, final, export, invoice
File types: .pdf, .pptx, .ppt, .xlsx, .xls, .csv
Projects (default, low confidence: 0.4)
Everything else — source code, config files, assets, documentation
This is the fallback when no other pattern matches
LLM-Assisted Categorization
When heuristic rules produce low confidence (below 0.5) or the file is ambiguous, use Claude to analyze the file's name, extension, path context, and (if small enough) content to suggest placement.
Prompt pattern for ambiguous files:
For each file below, suggest which canonical folder it belongs in.
The folders are:
- projects/ (source code, build files, project assets)
- contracts/ (legal documents, SOWs, NDAs, agreements)
- deliverables/ (final outputs, reports, presentations, exports)
- communications/ (emails, meeting notes, chat logs, correspondence)
Files:
- path/to/ambiguous-file.ext
- path/to/another-file.ext
For each file provide: suggested_folder, reason, confidence (0.0-1.0)
Naming Conventions
File Naming Rules
General principles:
- Lowercase with hyphens:
project-proposal.md not Project Proposal.md
- No spaces in filenames (use hyphens or underscores)
- Be descriptive:
2024-q2-revenue-report.pdf not report-final-v3.pdf
- Include version only if multiple versions coexist; prefer a single source of truth
Date-prefixed files (use for time-series content):
YYYY-MM-DD-description.ext
2024-06-01-client-meeting-notes.md
2024-05-weekly-status-report.pdf
When to date-prefix:
- Communication logs and meeting notes
- Reports and deliverables with temporal relevance
- Invoices and financial documents
- Anything where chronological sorting matters
When NOT to date-prefix:
- Source code files
- Configuration files
- Templates and reusable documents
- READMEs and documentation
Directory Naming
- Lowercase with hyphens:
meeting-notes/ not Meeting Notes/
- Singular nouns for categories:
contract/ or contracts/ (pick one convention and stick with it)
- No abbreviations unless universally understood:
docs/ is fine, comms/ should be communications/
Directory Structure Patterns
Pattern 1: By Project (Best for client work)
workspace/
client-alpha/
projects/
contracts/
deliverables/
communications/
client-beta/
projects/
contracts/
deliverables/
communications/
Pattern 2: By Type (Best for personal files)
documents/
contracts/
invoices/
reports/
notes/
code/
project-one/
project-two/
media/
images/
videos/
audio/
Pattern 3: By Date (Best for archives, logs)
archive/
2024/
q1/
q2/
q3/
q4/
2023/
...
Pattern 4: Hybrid (Recommended for most workflows)
workspace/
active/ # Current projects (by client or project)
client-alpha/
personal-site/
archive/ # Completed work (by year)
2024/
2023/
templates/ # Reusable templates
reference/ # Reference material, docs, guides
Audit Trail
Every file move or organization action should be logged. This creates an undo-able history and helps track what changed.
Audit Entry Format
id: mv_a1b2c3d4e5f6
action: move
src: /old/path/to/file.pdf
dst: /new/path/to/file.pdf
client_id: acme-corp
timestamp: 2024-06-01T14:30:00Z
metadata:
size_bytes: 245760
reason: "Matched contract keywords, moved to contracts/"
Audit Actions
| Action | Description |
|---|
move | File relocated from src to dst |
create_structure | Directory structure created (e.g., client folders) |
discover | Project auto-discovery scan completed |
suggest | LLM or heuristic classification generated |
Audit Log Storage
Store as an append-only file (JSONL format, one JSON object per line):
audit-log.jsonl
Each line is a self-contained JSON record. Easy to grep, parse, and review. Never edit existing entries -- only append new ones.
Safe File Moves
When moving files:
- Verify source exists and is a file (not a directory)
- Resolve to absolute paths (avoid relative path confusion)
- Check destination does not already exist (refuse to overwrite)
- Create parent directories as needed
- Perform the move
- Log the audit entry with source, destination, and timestamp
- Verify the destination file exists after the move
Cleanup Patterns
Identifying Duplicates
By filename: Find files with identical names in different locations
Look for: same filename + same size = likely duplicate
Verify with: content hash (SHA-256) for certainty
By content hash: Compute hash of file contents, group by hash
Same hash = identical content regardless of filename
Action: Keep the copy in the canonical location, remove others (or move to a duplicates/ staging directory for review).
Identifying Orphaned Files
Orphaned files are those that:
- Live outside any project or client directory
- Have no clear categorization
- Were created as temporary files and never cleaned up
- Are old versions superseded by newer files
Common orphan patterns:
*.tmp, *.bak, *.old, *.swp # Temporary/backup files
*-copy.*, *-Copy.*, * (1).* # Accidental duplicates
~$* # Office temp files
.DS_Store, Thumbs.db, desktop.ini # OS metadata
Identifying Outdated Versions
Look for patterns like:
report-v1.pdf
report-v2.pdf
report-v3.pdf # Only this one matters
report-final.pdf # Or this one
report-final-final.pdf # The naming tells you there's a problem
Fix: Keep only the latest version in the working directory. Move older versions to archive/ with date prefix.
Organization Workflows
Project Start: Establish Structure
1. Decide on structure pattern (by-project, by-type, hybrid)
2. Create top-level directories
3. For client work: create per-client folder structure
4. Create README.md documenting the conventions
5. Set up audit log file
6. Move any existing loose files into the structure
7. Log all moves in the audit trail
Mid-Project: Clean Up the Mess
1. Scan for project roots using the 18 manifest types
2. Identify files outside any project directory (orphans)
3. Run heuristic classification on orphaned files
4. For low-confidence files, use LLM-assisted categorization
5. Review suggested moves before executing
6. Execute moves with audit trail
7. Scan for duplicates and remove/archive
8. Remove OS metadata files (.DS_Store, Thumbs.db)
9. Update README if conventions changed
Project End: Archive
1. Verify all deliverables are in deliverables/
2. Verify all contracts are in contracts/
3. Move project directory to archive/{year}/
4. Create a project summary file (what was done, key dates, outcome)
5. Remove build artifacts and temporary files:
- node_modules/, __pycache__/, target/, build/, dist/
- .env files (never archive secrets)
- IDE-specific files (.idea/, .vscode/ settings)
6. Compress the archive directory if space is a concern
7. Log the archive action in the audit trail
Project Discovery
Auto-Discovering Projects in a Directory
Scan a directory tree (up to 5 levels deep by default) looking for the 18 manifest files. For each found:
Collected information:
path: /Users/me/code/my-app
name: my-app
project_type: node
manifest_file: package.json
size_bytes: 15728640
file_count: 342
Why this matters: Before organizing, you must know what projects exist and where they live. Discovery prevents accidentally breaking a project by moving its files.
Common Pitfalls
Organizing Without a Plan
- Symptom: Moving files around randomly, no consistent structure
- Impact: Files become harder to find, not easier
- Fix: Choose a structure pattern first, document it in a README, then organize
No Audit Trail
- Symptom: "Where did that file go?" / "I moved it somewhere..."
- Impact: Lost files, no ability to undo, others can't find things
- Fix: Log every move. An append-only JSONL file takes seconds to write
Overorganizing
- Symptom: 10 levels of nested directories with 1 file each
- Impact: More time navigating than working, path names become unwieldy
- Fix: Max 3-4 levels deep. If a directory has fewer than 3 files, it probably doesn't need to exist
Ignoring Build Artifacts
- Symptom:
node_modules/ and __pycache__/ mixed in with project files
- Impact: Bloated directories, slow searches, confusing file counts
- Fix: Never organize into build artifact directories. Exclude them from scans
Not Archiving Completed Work
- Symptom: Active workspace has 50+ directories, most for completed projects
- Impact: Hard to find current work, overwhelming directory listings
- Fix: Move completed projects to
archive/{year}/ within 2 weeks of completion
Spaces and Special Characters in Filenames
- Symptom:
My Final Report (v3) - Copy.pdf
- Impact: Shell commands break, scripts fail, URLs get mangled
- Fix: Lowercase, hyphens, no spaces:
2024-06-final-report.pdf
Checklists
Initial Organization Setup
Weekly Maintenance
Monthly Cleanup
Project Archival
Emergency "Desk is on Fire" Triage
