Your AI agent rebuilds context from scratch every session. One file gives it the map.

AI agents changed who writes the documents in my repositories. They didn't change who has to find them later.

Over the past year, agents have written most of the plans, specs, and work logs in my projects. They write them fast, they write them well enough — and they write them wherever they were pointed at that day. docs/

, notes/

, planning/

, the repo root, a gist someone pasted into a ticket. Every file made sense the day it was created.

Then you come back six weeks later and try to answer a simple question: why did we decide this? The decision exists. It's written down somewhere. Neither you nor the agent that wrote it can find it — and an agent that can't find a decision doesn't stop. It confidently re-litigates it, or refactors it away.

That was the failure that kept repeating for me. Not missing documentation — unfindable documentation, written faster than anyone could organize it.

FLOCK.md

is a markdown file at the repository root that answers one question:

where does this repo's knowledge live? No schema, no tooling, no build step.

The minimum useful version is a single table:

## Docs Map

| Type | Where | Answers |
|---|---|---|
| readme | README.md | What is this project and how do I run it? |
| design note | docs/ | Why is a piece of the system built the way it is? |
| decision | docs/decisions/ | What did we decide, when, and what was rejected? |

That's a conforming adoption. A location that isn't in the table is, by

definition, not part of the repo's knowledge contract — which sounds bureaucratic until you watch an agent actually respect it.

Point an agent at a repo with a Docs Map and it stops inventing directory structures. It reads the table and puts the document where the table says.

For projects that run a full design-to-delivery cycle, the standard defines a lifecycle called the question chain. A unit of work is done when four questions have written answers, in order:

An index answers the fifth question — where is everything, in what state? — in one line per item, for every unit of work at once.

The three documents of a feature link to each other, so landing on any one of them gets you to the other two. If you've ever opened a spec and wondered whether it was ever built — or opened code and wondered whether it ever had a spec — that's the failure three-way linking exists to close.

The split that matters most in practice is blueprint

vs worklog

: what we planned versus what actually happened. Agents are exceptionally good at writing plans and exceptionally bad at remembering that reality diverged from them. Keeping the two as separate documents means the divergence is recorded instead of papered over.

The standard's history rules are the piece I'd defend hardest, because they exist for a failure mode that barely existed before agents:

(decided 2026-08-22)

, inline, next to the decision.SUPERSEDED

with a date, with the new decision next to it.Here's why that third rule earns its keep: an agent reading your codebase has no memory of the debates you already had. If the rejected option isn't written down, the agent will propose it again — articulately, plausibly, and with total confidence — three weeks after you spent a day deciding against it. The recorded rejection is what stops the same debate from being reopened by something that argues for a living.

No — they're complementary, and the boundary is clean:

If you have an AGENTS.md

— or CLAUDE.md

, or whatever instruction file your tool reads — one line connects them:

Docs and project conventions: see FLOCK.md.

That line matters more than it looks, for a reason specific to this year: no model has a standard this new in its training data. An agent has never heard of FLOCK.md — but it already reads your instruction file at the start of every session, so it finds the map through a file it already trusts, from day one.

Adoption is a declaration, not a migration. The spec's typical locations are defaults; your Docs Map declares your real paths — so nothing moves. In a fresh repo, copy the minimal template as shipped and its defaults are the adoption.

In a repo that already has documentation, write Docs Map rows pointing at where the documents already live, and don't backfill: the history conventions apply from adoption day forward. Either way, the standard is explicit that adopting must not move, rename, or rewrite an existing file.

If you'd rather hand the adoption itself to an agent, the repo's Quick start routes by repository state — fresh, existing docs, migrating an established docs system, upgrading an old adoption — and carries a guardrailed prompt for each path that needs one. And when you want to verify the result, the spec repo ships its own conformance checker — node tools/check.mjs <repo>

, zero dependencies — which fails only on MUST violations: everything not marked MUST is guidance, and the checker holds itself to the same line the spec draws.

The full spec fits on one page: github.com/repoflock/flock.md.

It's CC BY 4.0 and deliberately tool-agnostic — it works with zero tooling, in any editor, with any agent. It was extracted from the working conventions behind RepoFlock, where an earlier form of it has been used in production across the project's own repositories, but nothing about it requires any particular tool. It's a markdown file. That's the point.

I'd genuinely like to hear where it breaks. If your repo has a docs layout that doesn't fit the Docs Map shape, or your agent workflow has a failure mode the history rules don't cover — the issues are open.