Clearpath

ClearPath File System v3.0

One convention. Point it at a folder, approve the tree, done. The goal is a unified system of organization that is very easy to understand and that lets you find anything fast.

Apply ClearPath to every file and folder created, renamed, or organized. When invoked via /clearpath or when asked to create, rename, organize, or audit files and folders, follow this system exactly.

Bundled resources

Read these from this skill's directory as needed:

The 5 rules

Rule 1: Lowercase + hyphens

Names use lowercase letters, words joined by hyphens. No spaces, no camelCase. The one exception: UPPERCASE format/platform prefix codes (below).

BAD:  Q1 Sales Report.xlsx
GOOD: q1-sales-report_021526.xlsx

Rule 2: Underscore is a segment separator

The underscore separates segments of meaning. Hyphens join words within one segment.

• Co-equal topics: use _ instead of -and- → advertising_marketing
• The date is always its own trailing segment → ..._MMDDYY
• The trailing 6-digit segment is always the date. Everything before it is topic/role segments.

advertising_marketing_021526.md      ← topic "advertising" + topic "marketing" + date
most-ai-content-is-lying-script_021526.md   ← one topic (hyphens) + role + date

Rule 3: Dates are MMDDYY, month-first

_MMDDYY. Six digits, no separators. 021526 = February 15, 2026. Never YYMMDD. Never ISO YYYYMMDD. This file system is read month-first; that preference is canonical.

• Date these: documents, reports, scripts, deliverables, exports, snapshots, meeting notes — anything that gets a newer version later.
• Do NOT date: config files (package.json, .env), framework files (README.md, SKILL.md, CLAUDE.md), build files (Dockerfile), permanent assets (logo-primary.png), source code in git repos, and a skill's own bundled references.

Rule 4: Organize by topic, never by file type

A topic folder holds everything about that topic. Never split a topic across pdfs/, scripts/, images/.

BAD (by type):        GOOD (by topic):
  pdfs/                 marketing/
  spreadsheets/           brand-guidelines_011026.pdf
  images/                 content-calendar_020126.xlsx

Rule 5: Depth target is 4, soft

Aim for 4 levels. Go to 5 or 6 only when it genuinely makes sense (deep client/project hierarchies). If you are creating empty intermediate folders just to categorize, flatten.

Two rules that protect findability

Never create an empty folder

Structure follows content. Create a subfolder only when something goes in it. A missing folder is a useful signal that the piece still needs producing. An empty folder is noise.

Reorganize within a topic's home — never into a global master folder

ClearPath reorganizes files within the topic folder they already belong to, into that topic's canonical shape. It never lifts files out into a global type-based collection. Moving every project's chat-recap and project-handoff docs into one shared chat-recap_project-handoff/ master folder is BANNED — it destroys findability, because you remember the file by its project, not its type. Project-local docs stay project-local.

Format & platform prefix codes (UPPERCASE)

Prefixes ride on subfolders and files, not the topic folder. The topic folder is the plain, human-readable name (e.g. the video title).

A content topic uses a topic folder containing prefixed subfolders, each created only when its content exists:

most-ai-content-is-lying/                    ← topic folder, no prefix, no date
  LF-most-ai-content-is-lying/
    LF-most-ai-content-is-lying-script_021526.md
    slides/
      LF-most-ai-content-is-lying-slides.html
  LIC-most-ai-content-is-lying/
    LIC-most-ai-content-is-lying-carousel_021526.pdf
    LIC-most-ai-content-is-lying-post_021526.md
    slides/
      slide-01.png            ← build artifacts: no prefix, no date
  _archive/
    tree-before_021526.md
    tree-after_021526.md

(No SF- folder above = the short-form has not been produced yet. That absence is the to-do signal.) Files repeat the topic so they stay self-identifying when detached. The role (-script, -tp, -carousel, -post) attaches by hyphen before the date.

Folder naming

• Standard: topic-name/ — lowercase, hyphens, no date
• Ordered: 01-topic-name/ when sequence matters
• Special: _archive/ (superseded work + tree snapshots), _inbox/ (quick capture, empty often), references/, assets/, scripts/

The _archive/ and _inbox/ underscore prefix is the one exception to "underscore separates segments."

Words to remove from filenames

FINAL, USE-THIS, CURRENT, LATEST, v1/v2/v3, copy, Copy, (1), (2), new, old, updated, revised. The date is the version. Keep draft only if the file is a draft. Keep a version number only when it identifies a distinct product (safe-v2), not a revision.

The workflow: scan → tree → approve → execute → archive

This is the operating loop. Never skip the approval gate.

/clearpath [path] — audit

1. Run scripts/clearpath-validate.sh [path].
2. Display violations.
3. If violations exist, produce the BEFORE/AFTER tree (apply proposed renames in memory only — touch nothing) and present both for the user to compare.

/clearpath apply [path] — restructure

MANDATORY: read references/safety-protocol.md first.

1. Pre-flight — filesystem type, cloud-sync detection, backup/git check, scope count, JSON staging manifest (/tmp/clearpath-stage-*.json).
2. Scan & preview — show the BEFORE tree and the proposed AFTER tree. WAIT FOR EXPLICIT APPROVAL.
3. Execute — copy-first-delete-later, max 20 ops per batch, two-step renames on case-insensitive filesystems. Reorganize within the topic's home only. Create no empty folders.
4. Archive the trees — write tree-before_MMDDYY.md and tree-after_MMDDYY.md into the target's _archive/. These are the human-readable map (where everything was, where it went). They are NOT the safety mechanism — the JSON staging manifest + copy-first-delete-later is the actual rollback. Keep both.
5. Validate — file counts match before/after, zero violations remain.

/clearpath help

Display references/quick-reference.md.

Quick decision guide

ClearPath v3.0 — month-first dates, segment underscores, topic homes, approved trees.