Building a coding-agent entry point for 128 repositories

At a consumer-app company we built the same "entry point" — the documents a coding agent reads first — into 128 repositories. Four required files, a fail-closed checker, and no changes to default branches. The 37 active repositories passed the first specification with zero problems. Whether agents actually perform better is not measured yet.

The problem: agents start lost every time

Repositories at older companies run on memory. Which folders matter, which service calls which, how deploys work — that lives in people’s heads more than in documents. A person can ask the desk next to them; a coding agent starts every session empty-handed and spends its first turns opening files at random.

The goal was to cut those first turns: put an entry point with the same shape in every repository, telling the agent what to read first.

What we built

• Scope: 128 repositories, split into three tiers by activity (37, 38 and 53).
• Four required artifacts: README.md, AGENTS.md, structure/INDEX.md, structure/manifest.json.
• Method: default branches were never touched; everything went to a separate branch. Checks were fail-closed — if we could not confirm the file exists on the remote, it did not count as done.

What we checked

Checking that the rules held mattered more than writing the documents. A dedicated checker ran over the 37 active repositories and reported zero problems against the first specification, with local and remote branches in sync.

Right after that we tightened the specification: the “get started” section moved up to second, the files to read first were capped at three, and design decisions at seven. In hindsight, the first spec produced documents that were easy for a reviewer to check; the second produces documents that are cheap for an agent to read on its first turn.

What is still unproven

To be plain about it:

• The whole set has not been re-checked against the tightened second specification.
• The current state of the less active repositories was outside this check.
• The most important question — does the agent open the right file on its first turn because of the entry point? — has not been measured.

The next step is to run the same 5–10 tasks on branches with and without the entry point and compare files opened on the first turn, success rate, number of revisions and wrongly touched files. When there are results, they will be added here.

What we learned

AX is less about installing a tool and more about shaping the terrain an agent works on. And whether that terrain is really in place should be proven by a checker, not by the documents themselves. The planning and verification for this work ran on codexclaw’s plan, audit and check loop.