Project Folder Organizer

Turn a chaotic pile of project or engagement files into a clean, predictable structure: eight standardized subfolders plus a consistent, date-first filename convention, with a generated index that doubles as an audit trail. Same structure for every engagement type — client project, vendor evaluation, deal, grant, matter, hire — so the layout is learnable once and reused forever.

Non-destructive by design: originals are never moved or deleted. Files are copied into a new sibling folder. If the user explicitly asks to move/replace in place, confirm that intention before doing anything irreversible.

Workflow

1. Locate and scope the folder

Confirm the source folder path. If the user hasn't given one, ask once. Then inventory everything, including nested subfolders — these get flattened into the new structure. List files with their type and size:

find "<source_folder>" -type f -not -name '.*' -printf '%P\t%s bytes\n' | sort

Note the likely engagement context (client project / vendor selection / deal / grant / legal matter / hiring search) from the filenames and the user's framing — it informs DocType choices but not the folder structure, which is always the same eight folders.

2. Read enough of each file to classify it

Classify on content first, filename second — working files are notoriously mislabeled (Project Atlas v3 FINAL.pdf could be anything). You usually do not need the whole file; the first page / first slide / first sheet plus the filename is typically decisive. Read more only when torn.

• PDFs: read the first page or two (text extraction, or rasterize if scanned).
• Office files (.docx/.pptx/.xlsx): use the available document-reading tools or extract text; the title slide, document heading, or first sheet usually suffices.
• Other types (images, emails, archives): read the filename, metadata, and any embedded text; classify by whatever is decisive.
• Sample large files — don't burn context reading a 300-page data dump end to end.

Use the taxonomy, tie-breakers, and DocType vocabulary below for placement. Consult them whenever a placement is non-obvious.

3. Build the plan

For every file, decide three things: which of the eight folders, the new filename, and a confidence level. Assemble them into a plan JSON (schema below). Set confidence to medium/low and add a one-line note for anything you're unsure about; route genuinely unclassifiable files to 99_Unsorted. These get surfaced in the index for the user to review, which is far better than a confident misfile.

The eight folders:

Tie-breakers (content-based):

• Proposal vs. Research: produced by the counterparty to sell or present itself → 01; produced by us or a third party to evaluate it → 05.
• Financials vs. Legal: a document whose substance is numbers (budget, model, invoice) → 02, even if it is an exhibit to a contract; the contract itself → 04.
• Assessment vs. Communications: a structured questionnaire, audit, or checklist → 03; the email thread discussing it → 06.
• Research vs. Reference: analysis with a conclusion or recommendation → 05; background facts with no argument (bios, org charts, specs) → 07.
• Versions: keep every version; suffix the descriptor (-v2, -Final, -Signed) rather than dropping any.

DocType vocabulary (PascalCase, extend as needed): Proposal, PitchDeck, RFPResponse, OnePager, BusinessPlan, Budget, Quote, Invoice, Model, Forecast, Statement, PricingSheet, Questionnaire, SecurityAssessment, AuditReport, ReferenceCheck, SiteReport, MSA, SOW, NDA, TermSheet, Lease, License, Amendment, Filing, Memo, DecisionMemo, Analysis, Valuation, MarketResearch, InterviewNotes, Scorecard, StatusUpdate, Letter, Transcript, MeetingNotes, Minutes, EmailThread, Bio, OrgChart, Press, Spec, Manual.

Naming: YYYY-MM-DD_DocType_Descriptor.ext — date first (use the content date, fall back to file mtime), PascalCase DocType, short hyphenated descriptor, no client/project name (the parent folder carries it). Examples: 2025-03-14_SOW_Phase-2-Implementation.pdf, 2024-11-30_StatusUpdate_November.docx, 2025-01-08_SecurityAssessment_Vendor-Response.xlsx.

4. Preview, then execute

Show the user a compact summary of the plan before copying — counts per folder and, critically, any files headed to 99_Unsorted or flagged low-confidence. Invite a quick correction. For a small set you can list every rename; for a large set, show the per-folder counts plus the flagged items and a handful of representative renames.

Write the plan to a JSON file, then execute it with a short script (write it to the working directory or scratch space). By default the output folder is a sibling named <SourceName> (Organized). Support a --dry-run mode that prints every planned copy without writing. The executor must handle the deterministic, error-prone parts:

• canonicalize folder names (accept aliases like Financials, 02, legal; route unknown values to 99_Unsorted and flag them)
• sanitize filenames (strip characters unsafe for the filesystem, collapse whitespace)
• preserve original extensions
• resolve name collisions (-2, -3, …) rather than overwrite
• copy with metadata preserved (shutil.copy2), never move
• write 00_INDEX.md at the output root: a per-folder listing of new name ← original path, plus a Needs review section listing every unsorted, low-, and medium-confidence item with its note

5. Present the result

Point the user to the new folder and 00_INDEX.md. Explicitly call out the Needs review section — the unsorted and low-confidence files — and offer to re-file any of them based on the user's steer. If they correct a placement, edit the plan and re-run (re-running into a fresh output folder is cheap and clean).

Plan JSON shape

{
  "source_root": "/abs/path/to/messy/folder",
  "output_root": "/abs/path/to/Target (Organized)",
  "subject": "Acme Corp — Website Redesign Engagement",
  "engagement_context": "agency client project",
  "items": [
    {
      "source": "subdir/Nov update FINAL.pdf",
      "folder": "06_Communications",
      "new_name": "2024-11-30_StatusUpdate_November.pdf",
      "confidence": "high",
      "note": ""
    }
  ]
}

• source is relative to source_root (absolute paths also accepted).
• folder accepts the canonical name or a short alias (Financials, 02, legal…); unknown values are routed to 99_Unsorted and flagged.
• confidence is high | medium | low (default high).
• note is optional but always shown in the index for unsorted/low/medium items.

Principles

• Never destructive. Copy. Leave the original folder untouched unless the user explicitly and knowingly asks otherwise.
• Content over filenames. The whole point is to fix bad names, so don't trust them.
• Flag, don't guess. A file in 99_Unsorted with a note beats a confident misfile.
• One structure, every engagement type. Don't fork the taxonomy per context; adapt only the DocType words.
• Confidential material stays put. Files are copied within the user's own filesystem; nothing is uploaded, summarized externally, or shared.