A File-Based Workspace for AI

Problem

Working with an AI assistant usually means opening a chat window and starting over. Context that took ten minutes to establish yesterday has to be re-established today. You paste the same documents repeatedly. Eventually the conversation gets long enough that the model loses the thread, and you start a new one — back to zero.

The industry’s answer is to reach for machinery: an agent framework, a vector database, embeddings, a retrieval pipeline. That is a lot of infrastructure to maintain, and it solves the problem by making the model search for context rather than by giving it the right context in the first place.

Approach

The opposite bet: the folder is the app, and plain markdown is the whole system. An agent drops into a folder, reads that folder’s instructions, does its work, and exits — never loading more than the task in front of it requires.

The core of it is a discipline about what the model sees, when — context routed across three layers rather than assembled into one enormous prompt:

Layer	Loaded	Role
CLAUDE.md	Always	The map — folder structure, conventions, task-to-location routing. Stays short because it is always resident.
CONTEXT.md	Per folder	The room — stages, naming, per-request instructions. Can be detailed, because it costs nothing on unrelated work.
Content files	On demand	The work itself.

The insight is not a bigger context window — it is routing. Give the model exactly the right thing every time. The same assistant becomes a technical co-builder in one folder, a planning partner in another, and a reflective listener in a third, with no prompt-juggling and no per-session re-explanation.

Frontmatter does the second half of the work. A YAML block turns every plain-text file into a structured record the model reads and writes directly — flipping status: open to status: done is a file edit, not a database migration. The filesystem is the database, which means the whole system is greppable, diffable, versionable in git, and readable without any of the software that produced it.

Outcome

A working template rather than a proposal. It ships with a fully worked software-engineering pipeline — brief → spec → architecture → build → release, with staged folders and matching workflows — plus roughly thirty packaged skills spanning software, knowledge capture, and career work, and a tutorial explaining the reasoning rather than just the mechanics.

It is public on GitHub, structured so another developer can clone it and have an AI assistant walk them through customizing it to their own life and work.

Two things make it more than a filing convention. It is the substrate the AI Assistant operates on — the bot and the workspace are one system, not two projects. And it is the environment this entire site was designed and built inside, including the specs behind it. The method is not theoretical; it is what produced the work you are reading.