folder.md

The boring default folder contract for AI agent workspaces.

View Template GitHub

The Problem

Agents know who they are (SOUL.md) and how to work (AGENTS.md).
But nothing tells them where to put things.

Duplicates. /my-app, /MyApp, /my_app — three copies.
Root pollution. Files scattered with no structure.
Name drift. project-v2, project-final, project-FINAL.
Lost context. Agent forgets where it put things.

Core Rules

Read FOLDER.md first. Before creating, moving, or writing any file.
Write to defined directories only. Never scatter files in the root.
Check before you create. Exact match, fuzzy match (kebab/snake/camel), semantic match.
Naming: lowercase-kebab-case. No underscores, spaces, or version suffixes.
Respect write boundaries. drafts/ is free, final/ is locked, prompt/ is read-only.
Create missing directories. If FOLDER.md describes it, make it before writing.

The Template

Multi-agent, multi-domain workspace

# FOLDER.md

> The folder contract for this workspace. Agents: read this before any file operation.

## Layout

./
├── FOLDER.md              # You are here
├── PROJECT.md             # Workspace purpose & current focus
├── tasks.md               # Global task inbox & views
├── tasks.jsonl            # Structured task log for agents
│
├── /prompt/               # System-level agent config
│   ├── SOUL.md            # Agent personality & behavior
│   ├── IDENTITY.md        # Workspace role (Founder OS, Dev, etc.)
│   ├── USER.md            # Stable facts about the user
│   ├── RULES.md           # Hard constraints & guardrails
│   ├── MEMORY.md          # Curated long-term knowledge
│   ├── ROUTING.md         # Agent delegation rules
│   ├── TOOL-POLICY.md     # Execution preferences (API vs browser)
│   └── VIEWS.md           # View overlays (Founder, Dev, Creator...)
│
├── /notes/                # Evolving knowledge
│   ├── daily/             # Daily logs: YYYY-MM-DD.md
│   ├── topics/            # Topic-specific (vercel.md, ai-agents.md)
│   └── people/            # Contact notes (houston-golden.md)
│
├── /areas/                # Long-term responsibilities
│   ├── business/
│   ├── health/
│   ├── family/
│   └── finance/
│
├── /projects/             # All active work
│   └── {project-name}/
│       ├── project.md     # Goal, status, milestones
│       ├── tasks.md       # Project-specific tasks
│       ├── notes/
│       ├── drafts/
│       ├── final/
│       └── assets/
│
├── /clients/              # Agency mode (optional)
│   └── {client-name}/
│       ├── relationship.md
│       └── projects/
│
├── /content/              # Creator workflows
│   ├── drafts/
│   ├── published/
│   └── assets/
│
├── /agents/               # Multi-agent support
│   └── {agent-name}/
│       ├── agent.md       # Agent purpose & capabilities
│       ├── soul.md        # Agent-specific personality
│       ├── tasks.md       # Agent's task queue
│       ├── prompt/        # Agent-specific prompts
│       └── skills/        # Agent-specific tools
│
├── /drafts/               # Global scratch space
├── /final/                # Approved outputs (locked)
├── /assets/               # Binary files (images, docs)
│   └── inbox/             # Unsorted uploads
└── /skills/               # Installed capability packs

## Rules

- Write only to directories listed above. No new root folders without asking.
- Use lowercase-kebab-case for all files and directories.
- Check before creating. Look for exact, fuzzy, and semantic matches.
- No version suffixes. No -v2, -final, -new, -copy. One name per thing.
- drafts/ is scratch space. Overwrite freely.
- final/ is locked. Only write when user says "finalize" or "ship it."
- prompt/ is read-only unless explicitly asked to update.
- notes/ is append-only. Add new notes, don't overwrite.
- tasks.jsonl is append-only. Each line is a task event.
- Each project gets its own tasks.md. Don't mix project tasks.
- Agents work in their own /agents/{name}/ directory.
- Route work to the right agent per ROUTING.md.

## Task Format (tasks.jsonl)

{"id":"t001","status":"todo","title":"...","project":"claws-so","agent":"developer"}
{"id":"t001","status":"in-progress","agent":"developer","ts":"2026-03-04T10:00:00Z"}
{"id":"t001","status":"done","ts":"2026-03-04T12:30:00Z"}

## Views

Switch context with VIEWS.md overlays:
- Founder — strategy, fundraising, decisions
- Developer — code, architecture, debugging  
- Creator — content, publishing, audience
- Agency — clients, deliverables, billing
- Personal — health, habits, life admin

Templates

Extend FOLDER.md for your workflow.

Install

OpenClawclawhub install houstongolden/folder-md

Skills CLInpx skills add houstongolden/folder-md

Or copy FOLDER.md into your workspace root. That's it.

Folder Cleanup

Already have a messy workspace? Run cleanup to analyze and reorganize your existing folders.

npx folder-md cleanup

Scan

Analyzes your root directory and all subdirectories

Plan

Generates a reorganization plan based on folder.md rules

Review

Shows you exactly what will move, rename, or merge

Apply

Executes the plan after your approval

Example cleanup plan

folder-md cleanup plan:

DUPLICATES FOUND:
  /my-app, /MyApp, /my_app → merge into /projects/my-app/

SCATTERED FILES:
  /random-notes.md → /notes/topics/random-notes.md
  /todo.txt → /tasks/backlog.md
  ~/Desktop/startup-idea.md → /projects/startup-idea/PROJECT.md

ROOT POLLUTION:
  /test-project/ → /projects/test-project/
  /client-acme/ → /clients/acme/

MISSING STRUCTURE:
  + /prompt/ (create with SOUL.md, RULES.md)
  + /drafts/ (scratch space)
  + /final/ (approved outputs)

Apply this plan? [y/N]

Nothing happens without your approval. Review the plan before applying.