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

AI agents significantly changed the way documents are created in the repositories, but they have not addressed the issue of document discoverability. Over the past year, agents have been responsible for writing most of the plans, specifications, and work logs in various projects. These files were located in different directories such as docs/, notes/, planning/, and even in the repository root or shared gists.

Each file made sense at the time of creation, but six weeks later, it becomes challenging to locate a specific decision within the repository. If an agent cannot find the relevant information, it will continue to re-examine the decision or even discard it entirely. The issue lies in the unfindable documentation, which is written faster than anyone can organize it.

The solution to this problem is a single file called FLOCK.md, located at the repository root. FLOCK.md serves as a map that answers the question: where does the repository's knowledge live? It is a markdown file with a simple table defining the different types of documents and their locations. By providing this map, agents no longer need to search for documents scattered across various directories.

The minimum useful version of FLOCK.md consists of a table with three columns: Type, Where, and Answers. By adopting this file, agents will stop inventing directory structures and place documents where they are supposed to be. The adoption process for FLOCK.md is simple and does not require moving, renaming, or rewriting existing files.

It is explicit that the adoption must not alter any existing files. The spec also recommends writing a quick start guide that provides instructions based on the repository's current state, whether it is fresh or already has existing documentation. This standard is available online and is freely licensed under CC BY 4.0, making it accessible to any agent or human user.