Workspace Files Organization#

Organize new work so that project-specific files stay together, reusable utilities stay separate, and outputs live with the work that produced them.

Mandatory Trigger#

Before creating any durable workspace file or folder, stop and classify it:

• If it belongs to a specific topic, goal, monitor, cron job, report, investigation, or automation, create/use projects/<name>/ first.
• If it is project state, cache, output, downloaded data, generated content, or monitor state, put it under projects/<name>/data/.
• Only skip this skill for trivial temporary shell output that is not written to disk, or for clearly workspace-wide files such as MEMORY.md, AGENTS.md, USER.md, SOUL.md, or TOOLS.md.

A monitor with persistent state is a project. A cron-backed workflow with files is a project. A one-off investigation that creates reusable notes or outputs is usually a project.

Core Rules#

• Put all files that belong to a specific project under projects/<name>/ when that work has its own topic, goal, or context.
• Treat code, notes, configs, prompts, supporting assets, and outputs for that project as project-local unless there is a strong reason not to.
• Put project outputs under projects/<name>/data/.
• Do not create or use a global data/ directory.
• Use scripts/ only for genuinely generic, reusable utilities that are not tied to one project.
• Do not put project-specific scripts in scripts/.
• Treat every body of work that requires created files as a project from the start.
• Create or choose projects/<name>/ before generating project-specific files.
• Do not create project files in ad hoc locations with the intention of organizing them later.

New Project Folder Standard#

When creating a new project folder, create:

• projects/<name>/README.md

Add a short README immediately. Include:

• what the project is about
• when the project was started
• a brief note about the current purpose or scope

Keep the README short unless the user asks for more detail.

Recommended Layout#

Use this layout by default for project-specific work:

text

projects/
  <name>/
    README.md
    data/
    ...project files...

Possible project files include:

• scripts and code
• notebooks
• prompts
• configuration files
• scraped or downloaded inputs
• generated outputs
• summaries or notes

Only add extra subfolders when they improve clarity.

Placement Heuristics#

Choose locations in this order:

1. When work requires creating durable files, start by creating or choosing projects/<name>/.
2. If the file belongs to that project, place it in projects/<name>/.
3. If it is state, cache, or output generated by that project, place it in projects/<name>/data/.
4. If it is a reusable utility that clearly works across unrelated projects, place it in scripts/.
5. If there is ambiguity, prefer creating a new project folder over placing files at the workspace root, a custom top-level folder, or scripts/.

Root Directory Discipline#

Avoid placing new project files directly in the workspace root.

Allow root placement only for files that are truly workspace-wide, such as:

• top-level workspace documentation
• shared agent notes
• global configuration expected at the root

Naming Guidance#

• Use short, descriptive project names.
• Prefer lowercase names.
• Use hyphens or underscores consistently within the workspace.
• Name projects by domain or outcome, for example dges-crawl, invoice-reconciliation, or travel-planning.

Migration Guidance#

When you find project-specific files scattered in the root or mixed into scripts/:

• group them under a new or existing projects/<name>/
• move outputs into projects/<name>/data/
• leave only truly generic utilities in scripts/
• update references or commands if paths changed
• treat the scattered state as something to fix, not as an acceptable starting pattern

Decision Standard#

Prefer a structure that makes it obvious where a future reader should look first.

When in doubt, create a project folder first and keep everything for that body of work under projects/<name>/.