Your agent setup lives in your repo

Every vendor has an answer for teaching an agent about your project: a rules directory here, a plugin marketplace there. Each one belongs to one tool, loads on that tool's terms, and stays behind when the project moves. crystl's answer is older and plainer: put it in files, in the repo.

A project set up this way carries its own instructions. CLAUDE.md and AGENTS.md say how to build and what the conventions are. NORTH-STAR.md says what the project is for and what has already been turned down. WORKBENCH.md holds the task list you and your agents share. All of it is markdown at conventional paths. Every agent reads it on the same terms: Claude Code, Codex, Antigravity CLI, and whatever ships next.

Because they are ordinary files, they do what files do. They diff, so you can review a change to your agent's instructions the way you review a change to code. They ride along on branches and clones, so a teammate who pulls the repo gets the whole setup without installing anything. And they are readable without crystl open: close the app, or stop using it entirely, and nothing about your project breaks. The drawer, the editor, and the score are surfaces on top of your files, not a database that holds them hostage.

There is a cost difference too. A plugin is standing overhead: it loads into context on every turn, in every project, whether or not today's work needs it. A repo file loads when an agent starts in that project and carries only that project's context. Skills prove the point rather than break it. SKILL.md began as a Claude format and is now an open standard that dozens of agents read, and a skill is itself plain files in the repo, with only its one-line description loading eagerly. crystl's token tracking shows you what your skills and plugins cost per turn, so the heavy ones are a decision rather than a surprise.

The hard part was never writing one file. It is keeping fifteen repos from drifting into fifteen different states of neglect. That is the project optimizer's job. Open a project and it scores the setup, names each gap by severity, and fixes what it can in one click. A missing file comes from a starter kit. A thin section gets a scoped prompt handed to the agent already in that gem, and the file editor opens anything that needs a human sentence. It works in the other direction too: a file that turned out well can be saved into your library as a starter, then deposited into whichever projects you choose. Agents can run the same check themselves with crystl optimize from any shard.

One honest caveat: files in the repo are a convention, not magic. An agent only follows instructions that are actually good, and no scanner can write your build command or your project's purpose for you. The optimizer is explicit about this split: structure it can fix, substance only you can.