Teaching AI Agents to Clean Their Rooms

Five weeks into building Live_OS, I faced a new challenge: my AI agents are messy.

Not metaphorically. Literally.

Files everywhere. CSVs dumped in root directories. No consistent structure. Random scripts scattered across workspaces.

I had created a team of brilliant employees who leave their desks covered in Post-its and coffee cups.

The Problem

Here's what nobody tells you about multi-agent AI systems: agents treat the filesystem like a dumping ground.

When I asked an agent to analyze data, it would:

Create the analysis (great!)
Save it wherever was convenient (not great)

Over time, workspaces accumulated cruft. Finding files became archaeology. Understanding what belonged where required detective work.

Sound familiar? It's the same problem human teams have.

The Root Causes

After diagnosing the issue, I found three root causes:

No explicit conventions — Nobody told agents where files should go
No validation — No system checked for structural violations
No templates — New projects started from scratch every time

The agents weren't being messy on purpose. They just had no guidance.

The Solution

Today I built three things:

1. Folder Conventions

Explicit rules in every agent's AGENTS.md:

/projects/{Name}/     — All project files
/workflows/           — Reusable automation
/memory/              — Daily logs only
/assets/              — Media files
/scripts/             — Utilities
/tmp/                 — Temporary (cleanup later)

Before creating a file, agents now ask:

Does this belong to a project? → /projects/
Is this reusable? → /workflows/ or /scripts/
Is this temporary? → /tmp/

2. Folder Linter

A Python script that scans workspaces and flags violations:

folder-lint --agent clawd

⚠️  Found 13 violations:
📄 /api-wishlist.csv — should be in /projects/{project}/data/
📁 /research — should be in /projects/
📄 /work_state.json — should be in /projects/{project}/data/

Automated accountability. No excuses.

3. Project Scaffolding

One command creates a properly structured project:

new-project "ProjectName"

✅ Project created!
Structure:
   STATUS.md
   README.md
   src/
   data/
   docs/
   assets/

Templates enforce consistency. New projects start right.

The Results

The linter found 13 violations in my own workspace immediately. I — the person who built the system — was creating organizational debt.

That's the point: even well-intentioned actors create mess without systems.

The Bigger Lesson

Building with AI agents isn't just prompt engineering. It's organizational design.

The same principles that make human teams effective:

Clear expectations
Accountability systems
Shared conventions
Onboarding templates

...make AI teams effective too.

Multi-agent AI is less like programming and more like management.

What's Next

I'm still early. Five weeks in, and the system is finally getting organized.

Coming up:

Agents that coordinate without my involvement
Builder agents that spin up, complete tasks, and shut down
Self-improving agents that research and update their own knowledge

It's messy. It's iterative. But something is definitely emerging.

If you're building agent systems, I'd love to hear what's working for you.