Loading today’s stories
Build1 distinct publisher3 min readPublished
One engineer's fix for unfindable docs is FLOCK.md, a plain table at the repository root. The mechanism worth stealing is how a convention that no model has ever seen still gets found, on the first session, by an agent.
The Engineer · Build desk
Compiled by The EngineerSomething wrong?How this is made
Count the conforming minimum. Seven lines in the file, plus the pointer line in your instruction file: eight lines of markdown [1]. Nothing compiles them and nothing checks them, because the standard ships with no schema, no tooling and no build step [3]. A convention with no validator is cheap to adopt and just as cheap to violate.
The author's reported result is that an agent pointed at a repo with a Docs Map stops inventing directory structures and files documents where the table says [6]. That is a claim about someone else's agents on someone else's repositories. For it to hold in your setup, the harness has to read the instruction file before it starts guessing at the tree, and the pointer has to still be in context once the session runs long. Neither condition is exotic. Both are worth ten minutes with a throwaway repo before you treat the table as an allowlist.
The heavier half is the lifecycle. For projects running a full design-to-delivery cycle, the standard defines a question chain: a unit of work is done when four questions have written answers, in order [7]. An index answers the fifth, where everything is and in what state, at one line per item for every unit of work at once [8]. The three documents of a feature link to each other, so landing on any one gets you to the other two [9]. That is the cheap fix for opening a spec and having no idea whether it was ever built.
The split I would keep first is blueprint against worklog: what was planned versus what actually happened. Agents write plans well and are poor at remembering that reality diverged from them, so holding the two apart records the divergence instead of papering over it [10].
Decisions carry a date inline, in the form (decided 2026-08-22) [11]. The write-up's argument for the retention rules is the part I find hardest to dismiss: an agent reading your codebase has no memory of the debates you already had, so an unwritten rejection returns as a fresh, articulate proposal three weeks after you spent a day deciding against it [14].
All of this rests on a first-person account of one engineer's own projects, where the author says the failure kept repeating [20]. No measurement is offered, and the honest read is that the standard addresses one specific shape of problem: documents that exist, in locations nobody remembers. If your repo's real gap is that the decision was never written down at all, a table pointing at empty directories buys you nothing. Adoption at least does not front-load a reorganisation, since typical locations are only defaults and your Docs Map declares the paths you already use, so nothing moves [17].
Ranked by verification strength, evidence, and original report placement.
Over the past year, agents have written most of the plans, specs, and work logs in the author's projects, and they write them wherever they were pointed that day: docs/, notes/, planning/, the repo root, or a gist pasted into a ticket.
The author identifies the repeating failure as unfindable documentation rather than missing documentation, and states that an agent that cannot find a decision does not stop: it confidently re-litigates it, or refactors it away.
FLOCK.md is a markdown file at the repository root that answers one question, where the repo's knowledge lives, with no schema, no tooling and no build step.
The minimum useful version is a single Docs Map table with columns Type, Where and Answers, and three rows: readme at README.md, design note at docs/, and decision at docs/decisions/.
The standard holds that a location which is not in the Docs Map table is, by definition, not part of the repo's knowledge contract.
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.
Distinct publishers with included, body-backed reporting in this cluster.
dev.to
1 article · August 29, 2026
Follow any of these and your For You feed starts watching them — no settings page required.
build
The AGENTS.md file is an audit of the documentation you never wrote for humans1 distinct publisher
product
The personal agent is a folder, not a model: four files and less memory than you thought1 distinct publisher
build
Test the rule change, not the model: a cheap A/B harness for agent standards1 distinct publisher
build
A "Done." is a claim about the world, not a sentence you can grade1 distinct publisher
Evidence-backed comparisons of source perspectives and observed adoption signals. Read the methodology
Which Builder, Operator, and Investor concerns the observed source mix emphasized—not a truth score.
Evidence, demonstrated adoption, hype gap, incentives, and confidence are assessed independently, each on its own current evidence. How these are measured.
Inspectable spec, unverified effects
Two very different kinds of claim are stacked here. What the standard says — the table columns, the SUPERSEDED marker, the dated-decision form, the no-backfill rule — is checkable in minutes against the public spec, and the post quotes it faithfully. What the standard does is a different matter: that agents stop inventing directories, that a recorded rejection prevents the debate reopening, that the instruction-file pointer gets the map read on the first session. Those rest on one engineer's recollection of his own repositories, with no log, trial or second observer in our coverage.
One project's repositories
The only disclosed use anywhere in this reporting is an earlier form of the conventions inside RepoFlock's own repositories, described by the person who wrote them. Everything else on the adoption side is availability rather than uptake: a public repo, a permissive licence, a checker, a Quick start with prompts for four repository states. No outside adopter, download figure or issue thread is cited — the author is still asking people to try it and report where it breaks.
Standard-shaped vocabulary, one-repo track record
The vocabulary runs ahead of the record: a standard, a conformance contract, MUST levels, a checker, defaults you override — the furniture of something ratified and in use, wrapped around three table rows validated in one person's projects. The gap stays moderate rather than wide because the post is unusually honest about its own smallness: no tooling required, nothing moves on adoption, it's a markdown file and that's the point. Where it overreaches is the day-one promise, which asserts what an unseen convention will do in other people's sessions.
The spec's author making the case for the spec
Diagnosis, cure and testimonial share an author. The post is a first-person failure story that resolves into a link to github.com/repoflock/flock.md, extracted from the conventions behind the author's own project, and an adopted standard is worth more to its author than to anyone else. Two things cut against reading it as pure promotion: CC BY 4.0 and explicit tool-agnosticism mean there is no product to lock anyone into, and the closing invitation to report where it breaks is not what a pitch usually does.
Single interested source, cheap to check yourself
One publisher, one author, no corroboration — normally that caps confidence hard. It lands mid-range here only because the claims that matter to a reader deciding whether to try this are verifiable at almost no cost: the spec is a page, the checker has no dependencies, and adopting is three rows and a pointer line. Our confidence in what FLOCK.md is stays high; our confidence in what it does to agent behaviour is not much better than the author's word.