From AGENTS.md to PLANS.md: Codifying How Humans and AI Work Together

The first time I tried to “work with AI” on a real codebase, I treated it like a smart autocomplete.

It was impressive for about fifteen minutes.

Then it did what a capable, confident assistant does when it doesn’t know the real rules of the room: it guessed.

I remember sitting there late at night with a half-drunk mug of tea, watching it confidently refactor a section I hadn’t asked it to touch. It wasn’t even bad refactoring. It was clean. It was readable. It was also the wrong kind of clean—like a stranger reorganizing your kitchen because they have opinions about where the forks should live.

The changes were technically defensible and practically wrong:

• it rewrote things I didn’t want rewritten
• it reached for dependencies I wouldn’t choose
• it “improved” style where stability mattered more than elegance

Not malicious. Not dumb.

Just unaligned.

That was the moment I stopped thinking of AI as a tool and started thinking of it as a collaborator that needs a contract.

Not a legal contract. A working contract: the smallest set of shared assumptions that prevents drift.

That need is what pulled me into the early AGENTS.md effort. And it’s also what eventually pushed me beyond a simple todo.txt toward something more like an editorial operating system: PLANS.md.

This post is a field report from that arc—how small documentation conventions turned out to be the most practical interface between human intention and machine execution.

The real problem wasn’t capability. It was continuity.

In a one-off chat, you can correct the model live:

• “Don’t touch that file.”
• “Use TypeScript, not JavaScript.”
• “Keep the tone concise.”
• “Don’t add new libraries.”

In ongoing work, those corrections evaporate.

What you need is not more intelligence. You need persistence:

• persistent constraints (what not to do)
• persistent style (how we do things here)
• persistent goals (what we’re trying to achieve)
• persistent sequence (what comes next)

Without persistence, every session becomes a renegotiation. And renegotiation becomes fatigue.

Fatigue is where sloppy approvals and bad merges are born.

AGENTS.md: a handshake between a repo and an agent

AGENTS.md is a simple idea with big consequences:

Put the working rules inside the project so the agent can read them every time, the same way a new teammate reads a contributing guide.

The genius is not the file format. It’s the stance:

Make collaboration legible.

When AGENTS.md is good, it does three things:

1. Draws boundaries (what is in scope, what is not).
2. Defines taste (naming, structure, tone, “don’t be clever here”).
3. Establishes workflow (tests, validation, commit expectations, review norms).

The first versions I wrote were blunt because I was reacting to pain:

• “Don’t rename files.”
• “Don’t ‘improve’ things outside the task.”
• “Don’t add a new toolchain because it’s neat.”

Over time they became calmer and more precise. Not because the agent got worse, but because I got better at describing what I actually valued.

That’s a subtle benefit of codifying work: it forces you to make your taste explicit.

todo.txt: the first attempt at an operating artifact

After AGENTS.md, my next problem was not how the agent worked, but what it should do next.

So I started keeping a simple todo.txt.

It worked, in the way paper checklists work:

• it reduced forgetting
• it gave me a next action when I was tired
• it made work visible

But it also had a failure mode that only shows up once you’re serious:

A todo list is a queue, not a compass.

When you have more than a few parallel efforts, a todo list becomes a junk drawer:

• urgent and important get mixed
• narrative arcs dissolve
• “what matters” gets replaced by “what’s next”

If you’ve ever finished a week of tasks and felt strangely empty, you’ve felt the problem.

PLANS.md: when sequence and story started to matter

PLANS.md emerged from a different need: not task completion, but direction.

I wanted a place to hold:

• the shape of the work (what this project is becoming)
• the publishing arc (what ideas should land first)
• the reasons (why these posts, why this order)
• the constraints (tone, stakes, boundaries)

In other words: a document that can survive mood, context-switching, and time.

If AGENTS.md is a repo’s handshake, PLANS.md is its spine.

And it turned out to be the missing interface for collaborating with AI across days:

• the agent stops inventing “reasonable next steps”
• the agent can see the narrative you’re building
• the agent can make choices that match intention, not just local optimization

A tiny pattern that keeps paying off

The pattern I use now is embarrassingly simple:

• AGENTS.md holds rules and standards.
• PLANS.md holds direction and sequence.
• todo.txt holds execution-level checkboxes (optional, lightweight).

Each document has a different job.

Trying to make one file do all three jobs is how you end up with either bureaucracy or chaos.

What this means for “AI as a collaborator”

When people talk about AI helping with life and work, they often picture a magical mind.

My experience has been the opposite: the future is small artifacts and clear flows.

Collaboration becomes reliable when:

• assumptions are written down once
• the next step is visible
• the agent can’t accidentally “help” by rewriting your intent

This is also why I keep returning to the idea of a personal life OS (like OXYMUS): not as a single assistant, but as a system of durable interfaces between intention and action.

The deeper claim here is cultural, not technical:

The people who benefit most from AI won’t be the ones with the best prompts. They’ll be the ones with the best operating artifacts.

AGENTS.md was the first artifact that made the collaboration feel real.

PLANS.md is what made it sustainable.