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:

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>/.