Every repository a run lands in should have a README, even a quick fix #140

Closed
opened 2026-10-03 17:25:11 -04:00 by cmoriarty · 1 comment
Owner

The hello world baseline (run 42, see #139) merged to main with no README. The only run instructions were in the PR summary ("run npm run dev") and the committed AGENTS.md, and an operator who opened index.html directly got a CORS error.

Nothing in the pipeline writes a README: the prompts tell agents to read one (prompts.py:1477, :2161, :2375, :2486), and the docs pipeline treats README as a docs file, but no step creates one. forgejo.py:849 also deliberately creates repos with no auto_init, so a new repo has none.

Proposal: a run that lands code in a repository with no README adds a short one: what the project is (from the brief), how to run it, how to run its tests. A scripted check (paths-exist:README* after the last agent step, or a docs-style check) holds the pipeline to it. A repo that already has a README keeps it, with the run's instructions updated only where the run changed them. The run instructions in the README are what the independent judge proposed in #139 would follow.

The hello world baseline (run 42, see #139) merged to `main` with no README. The only run instructions were in the PR summary ("run `npm run dev`") and the committed `AGENTS.md`, and an operator who opened `index.html` directly got a CORS error. Nothing in the pipeline writes a README: the prompts tell agents to read one (`prompts.py:1477`, `:2161`, `:2375`, `:2486`), and the docs pipeline treats `README` as a docs file, but no step creates one. `forgejo.py:849` also deliberately creates repos with no `auto_init`, so a new repo has none. Proposal: a run that lands code in a repository with no README adds a short one: what the project is (from the brief), how to run it, how to run its tests. A scripted check (`paths-exist:README*` after the last agent step, or a `docs`-style check) holds the pipeline to it. A repo that already has a README keeps it, with the run's instructions updated only where the run changed them. The run instructions in the README are what the independent judge proposed in #139 would follow.
Author
Owner

Shipped as runs-leave-a-readme.

  • Who writes it. The step that implements the code writes a short README when the repository has none: what the project is (from the brief), how to run it, and how to run its tests. That step is agent.implement in the quick fixes, the first apply group in an OpenSpec run, or the apply step in solo. An existing README is kept, and only its run and test instructions are updated where the work changed them.
  • The check. Every round of the fix loop looks for a README at the repository root: any case, not blank, docs/ doesn't count. A round without one fails as a red lane does. That round is not judged, and the fix round writes the README. So nothing is merged without one.
  • The judge. It reads the README first, and opens the app the way the README says. An instruction that does not work as written fails the round, quoting the instruction.

Verified. The fast and full lanes passed on the integrated batch (3,388 backend tests, 681 vitest, 249 browser specs with the slow and live ones, 29 of 29 simulated runs), and it is live on production as 57971c2 (deploy run 138, self-check braid-selfcheck: ok). Archived in a6ae0dc. The new simulated run readme-from-the-fix-round starts from a repository with no README.

Not covered: the docs, plan and release pipelines, which land no code. Whether a real model writes a sensible README needs a real-model run on a repository with none, as in run 42.

Shipped as `runs-leave-a-readme`. - **Who writes it.** The step that implements the code writes a short README when the repository has none: what the project is (from the brief), how to run it, and how to run its tests. That step is `agent.implement` in the quick fixes, the first apply group in an OpenSpec run, or the apply step in `solo`. An existing README is kept, and only its run and test instructions are updated where the work changed them. - **The check.** Every round of the fix loop looks for a README at the repository root: any case, not blank, `docs/` doesn't count. A round without one fails as a red lane does. That round is not judged, and the fix round writes the README. So nothing is merged without one. - **The judge.** It reads the README first, and opens the app the way the README says. An instruction that does not work as written fails the round, quoting the instruction. **Verified.** The fast and full lanes passed on the integrated batch (3,388 backend tests, 681 vitest, 249 browser specs with the slow and live ones, 29 of 29 simulated runs), and it is live on production as 57971c2 (deploy run 138, self-check `braid-selfcheck: ok`). Archived in a6ae0dc. The new simulated run `readme-from-the-fix-round` starts from a repository with no README. Not covered: the docs, plan and release pipelines, which land no code. Whether a real model writes a sensible README needs a real-model run on a repository with none, as in run 42.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#140
No description provided.