Files Move. Platforms Don't.

A few weeks ago I wrote that your files are dead. I meant files as passive storage — the documents you organize, forget, and never act on. I stand by that.

Here's the twist I didn't see coming: files as an interface are the most alive thing in my entire stack.

This week I finished a product design engagement the way I now finish everything: as a folder of files. A working prototype in one HTML file. A UX vision written in markdown. A schema document. A demo script. Zipped, it's a few hundred kilobytes. Any AI coding tool — Claude Code, Codex, Cursor, whatever ships next quarter — can open that folder in any repo and build the product. The receiving system doesn't matter. That's not a happy accident. It's the design constraint everything else follows from.

The test that proves it

My personal AI operating system is a vault of markdown files. For a while, it quietly assumed one provider: the instructions lived in a file named for one company's tool, the automation scripts named that company's models directly.

So I spent a day removing every assumption:

• The canonical instructions moved to AGENTS.md — an emerging convention any agent runtime can find. CLAUDE.md still exists, but it's a symlink. One source of truth, thin pointers everywhere else.
• Scripts stopped asking for models by name. They ask a registry for a tier — economy, standard, reasoning — and the registry decides what that means this month. When a better model ships, I edit one JSON file and every agent in the system upgrades.
• An llms.txt at the root tells any newly-arrived system what this place is and where to start reading.

Then the real test: I pointed a completely different company's CLI at the vault, cold. No setup, no explanation. It found the instructions, understood the structure, and did useful work inside the same rules my usual tools follow.

That's the bar. If your system only works with one provider's agent, you don't have a system. You have a dependency with good vibes.

Why this matters more every month

Model leadership changes hands constantly now. The best reasoning model, the best cheap model, and the best coding agent have each changed multiple times in the last year, and the gaps between leaders keep shrinking while the switching costs — if you built provider-neutral — keep falling.

Every platform integration you build has a half-life measured in quarters. Every markdown file you write has a half-life measured in decades. Plain text from the 1970s still opens today; it will open in 2050. No API contract, no SDK version, no vendor's roadmap decides whether your own operating manual keeps working.

There's a personal version of this and a professional version. The personal version: my system holds years of context — goals, projects, decision history. I will not gamble that archive on any single company still existing, still being good, or still being affordable in five years. The professional version is sharper: when you hand work to another team, another tool, another contractor's AI, the handoff is the product. If it only opens correctly in your environment, you didn't hand anything off.

What a portable handoff actually contains

The engagement I just finished taught me what has to be inside the files for the handoff to survive contact with a foreign system:

A working prototype, not a description of one. Prose drifts. Running code doesn't. The handoff states it plainly: when the documents and the prototype disagree, the prototype wins. That single rule ends most ambiguity before it starts.

Behavior separated from appearance. The vision file is deliberately style-free — it defines what the product does, beat by beat, and instructs the receiving system to keep whatever visual language the target codebase already has. Behavior travels; pixels don't have to. This is what makes the same file work in an empty repo and a mature one.

Instructions written to the receiver, not about the work. The file opens with a standing order for whatever AI reads it: audit the existing code first, produce a gap map, propose a plan, wait for approval, then converge one behavior at a time. It ends with acceptance criteria the receiver must walk and report honestly. A handoff that doesn't tell the next system how to proceed is just documentation.

A vocabulary. Every concept named once, in a table. Two systems that share nouns can collaborate; two systems that each invented their own names can't even disagree productively.

A never-do list. What the receiving system must not build turns out to be the highest-value section. Constraints compress better than instructions.

The rules I now build by

Distilled, the whole approach is six rules:

1. Content lives in markdown, never in code. Scripts render; files decide.
2. One canonical file per concern; everything else is a symlink or a pointer.
3. Abstract at the model seam — ask for a capability tier, never a product name.
4. Prefer single-file artifacts. A thing that is one file can go anywhere one file can go, which is everywhere.
5. The unit of handoff is a folder you could email. If it needs your environment to make sense, it isn't done.
6. Test portability the honest way: hand it to a system that has never seen it, and watch.

None of this is anti-provider. I use these companies' tools all day, happily, and the frontier models are genuinely miraculous. But the miracle is the engine, not the road. Engines get replaced. The road — the files, the structure, the accumulated context — is the part I own, and it's the part that compounds.

Your files are dead as storage. Long live files as the interface.