project-fold

Automatic project file organization

skill name:project-fold Version:v0.2.0-candidate Chinese name: Automatic project file organization Positioning: A skill for Vibe Builder that places project files and judges upgrades

First principles:Upgrade。

Use the smallest usable structure by default; only upgrade the directory form when the existing structure cannot contain the real complexity. Directories serve getting things done, not neatness for its own sake.

Directory language and Chinese-English mapping

Before starting the scan, first determine whether this project root uses zh or en：

When used as a mishu sub-skill, first resolve the store root according to MISHU_HOME(if set) or ~/.mishu , then read SELF.md 's folder_language。
When used independently and the language is unknown, first ask the user whether to use Chinese directories or English directories; Chinese directories and bilingual mapping usually consume a bit more tokens.
The same Projects root uses only one set of actual directory names; Chinese and English must not be mixed. The English directory names in the body are stable schema IDs; during actual execution, map them according to the selected language.
In Chinese mode or during language migration, before performing any creation, renaming, or moving, you must read and follow references/folder-names.md: first write the complete mapping file, then write this round's mapping snapshot into the move log.
Machine contract file NOW.md、HANDOFF.md、SKILL.md is not translated, to avoid cross-Agent discovery failure.

Root directory rules

When project-fold is called by mishu,default_projects_root is only the default landing point for new projects and unassigned materials. Even if existing projects are located elsewhere, first inventory them in place read-only; do not relocate them just because a default root directory is set. Only after the user confirms centralized organization and has seen the move plan should reversible moves be executed.

The first level of Projects allows only three categories:

Projects/
  <Project>/
  _Project-Inbox/
  _Archive/

<Project> is a development goal that can be continuously advanced, reviewed, and archived. Do not let scattered files, download names, temporary demos, single build packages, process documents, or old repository copies occupy the first level.

Archival semantics have only two levels, with non-repeating names: the Projects root's _Archive/ only receivesentire retired project containers; old versions, old demos, and historical copies inside a project only go into 90_History/。

Non-development goals should not remain at the first level of Projects. Assets, reference images, fonts, screenshots, etc. go to global Assets or the project's 30_Assets/ / 70_References/; if uncertain, go to _Project-Inbox/。

Upgrade ladder

L0 Inbox

AI-generated files or user manually imported files whose ownership has not been determined first enter:

_Project-Inbox/

Do not make the user think about classification first. The Agent performs secondary classification later.

Inbox boundaries:

_Project-Inbox/      = 不知道属于哪个项目
<Project>/_Inbox/    = 知道属于这个项目，但不知道放哪个意图目录
<ProjectFamily>/_Inbox/ = 知道属于这个项目族，但不知道属于共享级还是子项目级

L1 ordinary project

Default form. One goal, one main development object.

Minimal structure:

<Project>/
  00_Context/
  10_Source/
  20_Docs/
  90_History/

Grow on demand (do not pre-build the full set, grow the directories actually needed according to the "file intent judgment table"):

30_Assets/
40_Builds/
50_Data/
60_Run-Release/
70_References/

Only add for cleanup tasks:

99_Delete-Review/

When multiple sources, multiple types of assets, build artifacts, data, and run/release processes appear within the same project,do not create a new project or upgrade the level; just add the corresponding directories. This is still L1, it has just gotten fatter.

L2 Project Family

Only when 2 or more output forms that will evolve independentlyappear under one goal does it get upgraded to a project family.

A project family has two more core decision points than an ordinary project:

<ProjectFamily>/
  00_Context/
  10_Shared/
  20_Subprojects/
  _Inbox/
  90_History/

Note that the numbering semantics have changed: a project family uses 10_Shared/20_Subprojects instead of L1's 10_Source/20_Docs, and the same level does not coexist. Only inside subprojects does it return to L1's 10_Source/20_Docs logic.

Add ordinary project directories as needed, such as 30_Assets/、40_Builds/、50_Data/、60_Run-Release/。

Iron rule:

shared things go in 10_Shared/
independently evolving things go in 20_Subprojects/
uncertain things go in _Inbox/
Inside subprojects, continue organizing according to ordinary project logic

Example: Only when a vibe builder user has a Web App, Browser Extension, Landing Site, and Skill Pack under the same goal at the same time does it get upgraded to a project family. When there is only one Web demo, it remains an ordinary project.

File Intent Decision Table

First choose the correct schema by level:L1 Ordinary Projectuses 10_Source/20_Docs；L2 Project Family Rootuses 10_Shared/20_Subprojects. The two sets do not coexist. The "Level" column in the table below indicates which level each directory applies to.

Directory	Level	What goes in	What does not go in / Conflict judgment
`00_Context/`	L1 / L2 common	The minimum truth that must be read when starting work: project definition, current status, next steps, key decisions	Long historical documents do not go here; if they must be read every time work starts, distill them into Context and keep the original in Docs
`10_Source/`	L1 only (or inside subprojects)	Sources that change the product itself: code repositories, worktrees, App/Web/CLI engineering, skill source directories	Multiple Git repositories are not merged; first use `local-worktree/`、`public-repo/` and the like to mark identities
`10_Shared/`	L2 root only	Sources, protocols, templates, code, and editable specifications reused across subprojects in a project family	Media assets go to Assets; external references go to References; decision boundaries go to Context
`20_Subprojects/`	L2 root only	Subprojects within a project family that will be independently developed, released, and evolved	Sharing only resources does not count as a subproject
`20_Docs/`	L1 only (or inside subprojects)	Process materials: PRDs, discussion records, retrospectives, proposals, explanations, analysis conclusions	Current required reading goes to Context; machine data goes to Data
`30_Assets/`	L1 / L2 common	Assets the project will directly use: logos, screenshots, videos, design drafts, release media	External materials used only for reference go to References
`40_Builds/`	L1 / L2 common	Finished products that can be regenerated or delivered externally: apps, dmg, zip, exported HTML, release	Source code does not go here
`50_Data/`	L1 / L2 common	CSV/JSON/test data/user records/cleaning intermediate results/analysis inputs and outputs	Analysis conclusion documents go to Docs
`60_Run-Release/`	L1 / L2 common	How to run and release: deployment, signing, notarization, server, environment instructions	tokens, certificates, private keys,`.env` go to the sensitive review area
`70_References/`	Common to L1 / L2	External references: competitors, templates, third-party examples, design references	Materials that will go into deliverables go to Assets
`90_History/`	Common to L1 / L2	Old versions, old demos, historical copies, pre-merge backups within the project	The current entry point does not start here; only an entirely retired project goes into the Projects root's `_Archive/`
`99_Delete-Review/`	Common to L1 / L2	Only place candidates that are ready to be deleted but need review during cleanup tasks	Ordinary organizing does not proactively create

Handling backup and version proliferation

A pile of files from the same source (version numbers, dates, "backup/backup/copy/copy/_bak/_old", "backup before xxx") is the most space-consuming and least deletable stuff in organizing. Rule:Identify a family → keep the latest → collect the old ones into the pending-deletion area → never auto-delete → user review。

Identify the "same-source family": same base name, differing only by version or note suffix. Example:

CAM需求清单_v2.7.xlsx
CAM需求清单_v2.7_修改前备份.xlsx
CAM需求清单_v2.7_版本号统一前备份.xlsx
CAM需求清单_v2.8.xlsx
CAM需求清单_v2.9.xlsx      <- 最新，留在正常目录

Handling:

Keep the live one: the copy with the highest version number / most recent time stays in the normal directory; when it is impossible to tell which is the latest, keep the whole family in Inbox and explain.
Old versions go to the pending-deletion area: the rest go into 99_Delete-Review/<族名>/(or the backup directory the user's project already has, such as 09_备份/——Follow the user's existing conventions, do not invent new ones）。
Only place, do not delete: the pending-deletion area is "candidates"; whether to delete is decided by the user after review; the skill itself never deletes.
Runtime junkListed separately:*.sqlite-wal/-shm、__pycache__/、*-recovery-backups/、Thumbs.db、.DS_Store etc. are tool runtime residue, not materials; put them into 99_Delete-Review/_runtime/ or list them as pending-deletion review candidates; do not archive them as project files, and the Skill itself does not delete them.
Every placement into the pending-deletion area is still written to the move log, so it can be restored.

Secondary classification of AI-generated and manually imported items

Do not classify only by file extension. First determine the ownership level, then determine the file's intent.

Order:

First strip out backup/version families (see "Handling backup and version proliferation"): keep the latest, put the old ones into the pending-deletion area, then determine ownership for the rest.
Which project or project family does it belong to?
Is it project-level, shared-level, or subproject-level?
Is it Context, Source, Docs, Assets, Builds, Data, Run-Release, References, History, or Delete-Review?
Is the confidence level sufficient?
If not, leave it in Inbox; do not force a move.

Confidence:

High   -> 可建议直接移动
Medium -> 列入 move plan，等用户确认
Low    -> 留在 Inbox，并说明缺什么信息

Example:

index.html

It might be 10_Source/、40_Builds/、90_History/ or _Project-Inbox/; decide by looking at adjacent files, reference relationships, file names, and user intent.

logo.png

It might be project 30_Assets/, project family 30_Assets/, subproject 30_Assets/ or 70_References/; do not move it just because the extension is png.

Mini case：

导入文件：
  landing.html
  app-demo.mp4
  logo.png
  prompt.md
  old-v1.zip

判断：
  landing.html -> 10_Source 或 40_Builds，看是否还会继续编辑
  app-demo.mp4 -> 30_Assets
  logo.png     -> 30_Assets
  prompt.md    -> 00_Context 或 20_Docs，看是否定义项目行为
  old-v1.zip   -> 90_History

Two modes

At the start, first determine which mode to use; do not default to silently organizing.

Plan mode (default): for the first organizing session, or when the user first encounters this framework.Understand the current state before writing the plan—only after a read-only scan is complete and the ownership relationships between files are understood, then start writing. The plan must beminimal: List only the files that actually need to be moved (which one → where, confidence, and a one-sentence reason). Don't pile up or explain the obvious items, so the user can confirm at a glance after a few seconds. Execute only after confirmation. Better to ask one extra question than to move things without authorization.
Direct mode: enabled only whenanyof the following conditions is met, skipping the plan and executing directly—
- The user explicitly says "organize it right now / just do it / no need to show me a plan";
- The target directory is already this structure (directory names may be the Chinese or English from the mapping table; the first level contains only project containers, Inbox, and Archive), indicating the user is using this framework and is just doing routine filing.
- Even in direct mode, only High confidence items are actually moved; Medium/Low still stay in Inbox and are explained in the log.

If you can't tell which mode to use, default to plan mode.

Workflow

Determine the mode (see "Two Modes"): if unsure or it's the first time → plan mode.
First confirm the Projects root path with the user, record it as $PROJECTS_ROOT; don't assume, don't guess.
Read-only scan of the first level of $PROJECTS_ROOT and Inbox.
Have the user confirm the project name; don't hard-infer the project name from the repository name.
Before moving a Git repository, first run git status --short; if there is uncommitted content, only wrap it by identity—don't merge, don't delete.
By default, create a normal project (L1) container.
Only upgrade to a project family (L2) when multiple independently evolving outputs appear.
Generate a move plan for loose files based on "ownership level + file intent + confidence".
Execute the moves: in plan mode you must first show the user the plan and move only after confirmation; in direct mode you skip confirmation, but only move High confidence items, and Medium/Low always stay in Inbox.
Historical copies inside a project go into the 90_History / 90_历史corresponding to the chosen language; only when the entire project is retired does the project container go into the _Archive / _归档at the Projects root. Don't delete.
Write all moves to a move log (as a restoration fallback): each record includes 原路径 -> 新路径, time, and confidence, ensuring each can be reversed one by one. When the user hasn't specified an output directory, in English mode put it in $PROJECTS_ROOT/_Project-Inbox/cleanup-log.md, and in Chinese mode put it in $PROJECTS_ROOT/_项目收件箱/搬运日志.md. Format example:

## 2026-07-07 14:30 整理
- ./landing.html -> ./Tuck/10_Source/landing.html  [High]
- ./old-v1.zip   -> ./Tuck/90_History/old-v1.zip    [High]
- ./mystery.dat  留 _Project-Inbox（Low：无法判断归属）

Verify after completion:

find "$PROJECTS_ROOT" -maxdepth 1 -type f -not -name '.DS_Store' -not -name '.localized' -print
find "$PROJECTS_ROOT" -maxdepth 1 -mindepth 1 -not -name '.DS_Store' -not -name '.localized' -print

The first line should be empty; the second line should show only project containers and the Inbox and Archive corresponding to the chosen language.

Real filesystem pitfalls

macOS is case-insensitive by default:tuck and Tuck are treated as the same path. When encountering a case-only change or wrapping with a container of the same name, you must use a temporary name as an intermediate:tuck -> __tmp_tuck_source -> Tuck/10_Source/local-workspace。
.DS_Store and .localized are system noise; ignore them during verification, and only prompt the user that they can be cleaned up or listed for deletion review—the Skill itself does not delete them.
An ordinary directory must not remain at the first level of Projects just because its name looks like a number; it must be a development target confirmed by the user, otherwise it goes into _Archive/、_Project-Inbox/ or the project's 70_References/。
When moving a project container with the same name, first wrap the old content into 90_History/<old-name>/, then create the new structure.

Safety boundaries

Every organization must write a move log (原路径 -> 新路径); this is the restoration fallback; a move without a log is equivalent to irreversible and is not allowed.
During Chinese mode or language migration, move only after both the mapping file and the mapping snapshot in the log are written; if the mapping is incomplete, stop.
Do not delete.
Do not automatically clear node_modules、.next、.build, models, venv.
Do not move system directories, hidden configuration directories,bin。
Do not merge Git repositories; for multiple repositories, first use local-worktree/、github-repo/、public-repo/ to mark identity.
Do not put certificates, tokens,.env, or private keys into the project repository; put them in the sensitive review area.
Do not stuff the application itself into /Applications, unless it is an explicit .app installation package and the user requests it.